corp-v1-channel-kanban/references/kanban-bootstrap-and-validation.md

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.