62 lines
4.7 KiB
Markdown
62 lines
4.7 KiB
Markdown
# Kanban documentation bootstrap and validation
|
|
|
|
Use this when a project documentation site has authoritative Scope and Architecture records but no dedicated Kanban area yet.
|
|
|
|
## Bootstrap sequence
|
|
|
|
1. Start from a clean clone of the current documentation integration branch. Do not reuse a worktree with unrelated modifications.
|
|
2. Read current Scope records plus Architecture, Delivery, Releases, and enough Kanban-channel history to establish approval and execution evidence.
|
|
3. Add a dedicated Docusaurus docs plugin for `kanban/`, with its own `sidebarsKanban.ts`.
|
|
4. Place the top-level Kanban navigation item immediately after Architecture and add `/kanban` to documentation search indexing.
|
|
5. Add exactly two sidebar entries in this order: Board, Focus.
|
|
6. Populate Board from authoritative unfinished Epic and Feature records only. Map detailed lifecycle states deterministically to `InIdeation`, `InBacklog`, `InProgress`, or `ToBeReleased` without changing source state.
|
|
7. Populate Focus only from qualifying `InBacklog`, `InProgress`, or `ToBeReleased` evidence. An empty Focus is correct when no item qualifies; state the exact missing approval, dependency, task-definition, or execution evidence.
|
|
8. Never create placeholder tasks to make Focus appear populated. A task needs a stable Architecture-owned ID, parent hierarchy, Feature implementation approval, and explicit exact-task human Focus admission.
|
|
|
|
## Recommended structural validator
|
|
|
|
Add a repository validation script and include it in the main validation command. Check at least:
|
|
|
|
- Kanban plugin, search route, and top-level navigation order;
|
|
- dedicated sidebar containing Board then Focus;
|
|
- all four allowed Board columns;
|
|
- all known unfinished Epic/Feature IDs appear exactly as intended;
|
|
- no card has a terminal authoritative source status;
|
|
- Focus exposes only `InBacklog`, `InProgress`, and `ToBeReleased` sections;
|
|
- Focus preserves the exact-task human admission rule.
|
|
|
|
Avoid naïve substring checks when explanatory prose names excluded states. Validate headings or structured fields instead—for example, reject an `## InIdeation` Focus section rather than rejecting every occurrence of the word `InIdeation`.
|
|
|
|
## Verification and publication
|
|
|
|
1. Run existing Scope and Architecture validators, the Kanban validator, TypeScript checks, the strict-link Docusaurus production build, and `git diff --check`.
|
|
2. Push a review branch; do not merge autonomously.
|
|
3. Open or update the existing PR against the integration branch; do not create a duplicate PR for the same review branch.
|
|
4. Fetch the remote, verify the local and remote branch SHAs match, and confirm the worktree is clean.
|
|
5. Read Board, Focus, sidebar, and config back from the exact remote commit. A deterministic local/remote comparison is:
|
|
- `git show origin/<BRANCH>:kanban/board.md | sha256sum` versus `sha256sum kanban/board.md`;
|
|
- repeat for `kanban/focus.md` and any changed structural files.
|
|
6. Read the PR remotely and confirm `state`, `merged`, `mergeable`, `head.sha`, and `base.sha`. Private Gitea repositories may return `404` to unauthenticated API requests; use an already configured runtime credential in memory without printing, exporting, or placing it on the command line. Treat a credentialed read as verification, not permission to merge.
|
|
7. Wait for an Actions run whose `head_sha` exactly matches the PR head and require `status=completed` plus `conclusion=success`; do not transfer CI results from another SHA.
|
|
8. Report paths, PR, commit, exact-head run ID, source message IDs, admission decisions, and unresolved gates.
|
|
|
|
### Safe private-Gitea read pattern
|
|
|
|
For a private repository, resolve the active profile environment path, load only the configured Gitea token inside a short-lived process, and send it in an in-memory authorization header. Output only non-secret fields. Query:
|
|
|
|
- `/api/v1/repos/<OWNER>/<REPO>/pulls/<NUMBER>` for PR state and exact head/base SHAs;
|
|
- `/api/v1/repos/<OWNER>/<REPO>/actions/runs?limit=<N>` for recent run IDs, head SHAs, status, conclusion, and event.
|
|
|
|
Never print the token, headers, environment file contents, exception request objects, or response bodies that may echo credentials. An unauthenticated `404` followed by a successful credentialed read means the repository is private; it is not evidence that the endpoint is absent.
|
|
|
|
## Evidence pattern for an empty Focus
|
|
|
|
Record each ownership boundary explicitly:
|
|
|
|
- Scope: Epic/Feature state remains Proposed or otherwise outside active Focus.
|
|
- Architecture: no stable implementation task and/or no Approved-for-Implementation evidence.
|
|
- Kanban: no explicit human admission for an exact task.
|
|
- Delivery: no verified execution evidence.
|
|
- Releases: no verified release handoff.
|
|
|
|
This turns an empty Focus into a useful gate report rather than filler. |