docs: establish ZitPlane notes project and user documentation governance
This commit is contained in:
1 parent
40af500750
commit
7ecf531697
22 files changed
+1507
No files matched your search
@@ -0,0 +1,13 @@
|
||||
# Development change log
|
||||
|
||||
This is the chronological **index**. Phase-specific scope/implementation evidence lives in the linked Markdown reports. Use absolute dates and Git SHA for each completed phase.
|
||||
|
||||
| Date | Phase | Recorded implementation | Commit / validation |
|
||||
| --- | --- | --- | --- |
|
||||
| 2026-11-22 | P01 | Monorepo foundation and initial guides | `8f54ccb`; committed |
|
||||
| 2026-11-22 | P02 | Pinned local-only ZITADEL/PostgreSQL/Traefik Compose; runtime still unverified | `433a0a3`, P02 source handoff `eadd0e5`; prior source tests 3/3 |
|
||||
| 2026-11-22 | P03 | Imported Login V2 v4.20.4 matching upstream source/workspace | `4404849`; source blob audit, CI deferred |
|
||||
| 2026-11-22 | P04 | Account Portal OIDC and protected frontend foundation | `40af500`; patch/scope audit, CI deferred |
|
||||
| 2026-11-22 | DOCS-01 | Knowledge folders, first-party file/function maps, exact source inventory, user guides and mandatory AGENTS documentation policy | Documentation implementation complete; focused manifest/link/scope audit PASS; Git SHA in DOCS-01 local commit, see [DOCS-01.md](DOCS-01.md) |
|
||||
|
||||
Rules: Append new phases or fixes; never silently rewrite a past result. Separate **implemented**, **verified**, **blocked**, and **proposed**. Never log a user secret or personal data.
|
||||
@@ -0,0 +1,44 @@
|
||||
# DOCS-01 — Repository knowledge-base and developer rules
|
||||
|
||||
**Date:** 2026-11-22
|
||||
**State:** COMPLETED — exact manifest/link/scope audit PASS; documentation committed locally, not pushed to Gitea.
|
||||
**Baseline:** `40af5007503501643d1e9ad2ab3939ba57dab5f9` (`main`)
|
||||
**User approval:** Create Git-tracked `notes/`, `project/` and `docs/` knowledge areas, add mandatory docs-first and documentation-sync rules to `AGENTS.md`, give each new knowledge-area directory a README and a **MINIFEST.md**.
|
||||
|
||||
## Scope lock — documentation only
|
||||
|
||||
**Allowed:** `notes/**`, `project/**`, `docs/**`, root `AGENTS.md`, `README.md` and `MINIFEST.md` for navigation and root-folder inventory. Source inventory can be *read* in `core/**`, `auth/**`, `users/**`, `deployment/**`, `tests/**`, `scripts/**`, `packages/**`.
|
||||
|
||||
**Out of scope:** All app/backend/auth logic, upstream ZITADEL snapshot, Compose, UI, package versions, secrets, `.env`, tests, CI, releases, deployment, remotes/production changes. Existing unrelated untracked `AI_INSTRUCTIONS.md` must not be modified/staged.
|
||||
|
||||
## Required deliverables
|
||||
|
||||
1. `notes/`: how-to, manifest, this pre-change plan and append-only change timeline.
|
||||
2. `project/`: developer-oriented map: real architecture, features/pages, function/logic ownership, module/technology rationale, setup references, phase change history, source file inventory.
|
||||
3. `docs/`: user-facing how-to for current features/pages/buttons, setup prerequisites, error/limitations; preserve earlier architecture/phase/evidence files.
|
||||
4. `AGENTS.md`: enforce **pre-change notes**, implementation logs, concurrent developer and end-user documentation updates, status/provenance rules, README/MINIFEST maintenance on new first-party folders.
|
||||
5. Explicitly distinguish existing implementation, not-yet-run tests, planned capabilities and unverified runtime behavior.
|
||||
|
||||
## Pre-change evidence
|
||||
|
||||
- `main` baseline matches Gitea `40af500...`.
|
||||
- `notes/`, `project/` previously absent; `docs/` already contains ARCHITECTURE, DEVELOPMENT, PHASES and P02/P03/P04 evidence.
|
||||
- P02 backend configuration, P03 imported upstream Login V2 v4.20.4, P04 custom Account Portal source exist; runtime/CI/deployment remain unverified.
|
||||
- `AI_INSTRUCTIONS.md` already exists as unrelated untracked file; preserve.
|
||||
- No change to other project sources approved.
|
||||
|
||||
## Final result / verification
|
||||
|
||||
- Added Git-tracked `notes/` (README, MINIFEST, DOCS-01 plan/results, chronological log) before creating other documentation content.
|
||||
- Added `project/`: README, MINIFEST, architecture, file map, function map, feature/page register, setup/dependency rationale, changelog, and exact 701-path Git tracked-source inventory.
|
||||
- Expanded existing `docs/`: README, MINIFEST, first-party page-by-page/visible button guide, operator/setup guide, feature status and troubleshooting. Preserved P02/P03/P04 existing evidence.
|
||||
- Root `AGENTS.md` now requires **notes before every change**, synchronized developer/user docs, historical logs, README and literal MINIFEST for each new first-party directory, accurate verification status, secret-safe Markdown and upstream-vendor exception.
|
||||
- Root `README.md` now navigates all three knowledge areas; root `MINIFEST.md` lists top-level tracked files/folders and phases.
|
||||
- Source-file changes outside documentation paths: **none**. ZITADEL, Login V2, Account Portal, Docker Compose and dependency manifests unchanged.
|
||||
- **Focused documentation-only audit (2026-11-22):** notes 4/4 manifest entries, project 9/9, docs 12/12; 28 Markdown files checked, **0 broken relative links**, Git tracked file inventory **701/701**, out-of-scope staged files **0**, staged application code files **0**, unrelated `AI_INSTRUCTIONS.md` untouched.
|
||||
- One generated source-inventory trailing blank line corrected; final `git diff --cached --check` **PASS**.
|
||||
- Local build, test, dev server, Docker, CI and deployment: **NOT RUN** (documentation-only phase).
|
||||
- Git checkpoint: record is in this phase's local Git commit; inspect `git log -1` for exact SHA. No remote push was requested in DOCS-01.
|
||||
- Preexisting limitations unchanged: P02 Docker acceptance, P03 Login build, P04 Account Portal OIDC/build and production deployment remain unverified.
|
||||
|
||||
**Maintenance rule:** Future approved changes must first update their own dated `notes/` phase record and then keep `project/`, `docs/` and `MINIFEST.md` synchronized with actual source and evidence.
|
||||
@@ -0,0 +1,10 @@
|
||||
# notes/ manifest
|
||||
|
||||
| File | Purpose | Phase / status |
|
||||
| --- | --- | --- |
|
||||
| [README.md](README.md) | Rules for developer planning, ongoing notes, verification evidence and phase history | DOCS-01 / active |
|
||||
| [MINIFEST.md](MINIFEST.md) | File list and ownership; **MINIFEST is the exact required filename** | DOCS-01 / active |
|
||||
| [DOCS-01.md](DOCS-01.md) | This documentation-governance change: baseline, scope, plan, implementation and closure | DOCS-01 / implementation complete |
|
||||
| [CHANGELOG.md](CHANGELOG.md) | Short append-only chronological phase log and links to detailed reports | DOCS-01 / active |
|
||||
|
||||
Update this manifest whenever any direct child file or directory changes. Use **actual source state**; a planned file must be labeled planned, not present.
|
||||
@@ -0,0 +1,16 @@
|
||||
# notes/ — Development working log
|
||||
|
||||
Purpose: **planning, scope locks, implementation steps, audit evidence, decisions, and chronological change/fix logs during development**.
|
||||
|
||||
## When and how to write
|
||||
|
||||
1. **Before** each change, create/update a dated phase note with baseline SHA, goal, allowed paths, exclusions, expected behavior, security risks, acceptance criteria and status **PLANNED**.
|
||||
2. During work, record decisions, files modified, blockers, exact source evidence and any approved scope change; do **not** claim a test passed unless it ran.
|
||||
3. After the change, record actual diff/commit references, tests or CI run URLs when available, known limitations, and final status.
|
||||
4. Update `project/` (developer truth) and `docs/` (user truth) in the same phase if behavior or usage changes.
|
||||
5. Keep notes concise, chronological and traceable to commits; supersede, do not erase, historic outcomes.
|
||||
|
||||
This folder is **Git-tracked Markdown**, not a runtime log store and **never** a location for secrets, credentials, user information, access tokens, live data or machine-specific confidential output.
|
||||
|
||||
## Files
|
||||
See [MINIFEST.md](MINIFEST.md) for the exact file register. Phase reports use names such as `P05-PLAN.md` and `P05-RESULT.md`. The current governance/setup change is recorded in `DOCS-01.md`.
|
||||
Reference in new issue
Block a user