@phuthuycoding/kanban-flow 0.3.0

package/dist/workflow/validate-traceability.js

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { ARTIFACTS, STAGE_INDEX } from "./schema.js";
+import { splitFrontmatter, isFilledFile } from "../shared/frontmatter.js";
+import { finding } from "./findings.js";
+/**
+ * Traceability for features from planning on: every use case has its own file
+ * matching the index, and every test case references FR/UC ids that exist.
+ */
+export function checkTraceability(feature) {
+    const issues = [];
+    if (STAGE_INDEX[feature.stage] < STAGE_INDEX.planning || feature.meta?.kind === "bug")
+        return issues;
+    const error = (file, code, message) => {
+        issues.push(finding(feature, "ERROR", file, code, message));
+    };
+    const tcFile = ARTIFACTS["test-cases"].file;
+    const ucIndexFile = ARTIFACTS["use-case-specification"].file;
+    const tcPath = join(feature.dir, tcFile);
+    const frPath = join(feature.dir, ARTIFACTS["spec-requirement"].file);
+    const ucPath = join(feature.dir, ucIndexFile);
+    const ucDir = join(feature.dir, "use-cases");
+    const ucFiles = existsSync(ucDir)
+        ? readdirSync(ucDir).filter((file) => /^UC-\d+\.md$/i.test(file))
+        : [];
+    if (ucFiles.length === 0) {
+        error("use-cases/", "use_cases_missing", "Each use case must be written in its own use-cases/UC-###.md file.");
+    }
+    const fileIds = new Set(ucFiles.map((file) => file.slice(0, -3).toUpperCase()));
+    if (existsSync(ucPath)) {
+        const index = readFileSync(ucPath, "utf8");
+        const indexedIds = new Set([...index.matchAll(/\bUC-\d+\b/gi)].map((match) => match[0].toUpperCase()));
+        for (const id of indexedIds) {
+            if (!fileIds.has(id))
+                error(`use-cases/${id}.md`, "use_case_file_missing", `${id} is listed in the index but has no individual file.`);
+        }
+        for (const id of fileIds) {
+            if (!indexedIds.has(id))
+                error(ucIndexFile, "use_case_not_indexed", `${id} must be listed in the use-case index.`);
+        }
+    }
+    for (const file of ucFiles) {
+        const content = readFileSync(join(ucDir, file), "utf8");
+        const id = file.slice(0, -3).toUpperCase();
+        if (!isFilledFile(content, splitFrontmatter(content).body)) {
+            error(`use-cases/${file}`, "use_case_unfilled", `${file} is empty or still contains template placeholders.`);
+        }
+        if (!new RegExp(`\\b${id}\\b`, "i").test(content)) {
+            error(`use-cases/${file}`, "use_case_id_missing", `${file} must declare its matching ${id} identifier.`);
+        }
+    }
+    if (!existsSync(tcPath))
+        return issues;
+    const tcs = readFileSync(tcPath, "utf8");
+    const cases = [...tcs.matchAll(/^##\s+(TC-\d+)\b[^\n]*(?:\n|$)([\s\S]*?)(?=^##\s+TC-\d+\b|(?![\s\S]))/gm)];
+    if (cases.length === 0) {
+        error(tcFile, "no_test_cases", "Test cases must be defined in separate ## TC-XXX sections.");
+    }
+    const caseIds = new Set();
+    for (const [, id, body] of cases) {
+        if (caseIds.has(id.toUpperCase()))
+            error(tcFile, "duplicate_tc", `Duplicate test case ${id}.`);
+        caseIds.add(id.toUpperCase());
+        if (!/\bFR-\d+\b/i.test(body) || !/\bUC-\d+\b/i.test(body)) {
+            error(tcFile, "tc_refs_missing", `${id} must reference both a requirement (FR-XXX) and a use case (UC-XXX).`);
+        }
+    }
+    if (!/FR-\d+/i.test(tcs)) {
+        error(tcFile, "no_fr_refs", "test-cases has no requirement references (FR-XXX); traceability chain broken");
+    }
+    if (!/UC-\d+/i.test(tcs)) {
+        error(tcFile, "no_uc_refs", "test-cases has no use case references (UC-XXX); traceability chain broken");
+    }
+    if (existsSync(frPath)) {
+        const frDoc = readFileSync(frPath, "utf8");
+        const refs = [...tcs.matchAll(/\b(FR-\d+)\b/gi)].map((m) => m[1].toUpperCase());
+        const declared = new Set([...frDoc.matchAll(/\bFR-\d+\b/gi)].map((m) => m[0].toUpperCase()));
+        const missing = [...new Set(refs)].filter((r) => !declared.has(r));
+        if (missing.length > 0) {
+            error(tcFile, "fr_ref_missing", `test-cases reference requirements not in spec-requirement: ${missing.join(", ")}`);
+        }
+    }
+    if (existsSync(ucPath) || ucFiles.length > 0) {
+        const refs = [...tcs.matchAll(/\b(UC-\d+)\b/gi)].map((m) => m[1].toUpperCase());
+        const missing = [...new Set(refs)].filter((r) => !fileIds.has(r));
+        if (missing.length > 0) {
+            error(tcFile, "uc_ref_missing", `test-cases reference use cases without individual files: ${missing.join(", ")}`);
+        }
+    }
+    return issues;
+}

package/dist/workflow/validate.js

@@ -0,0 +1,73 @@
+import { STAGES } from "./schema.js";
+import { finding } from "./findings.js";
+import { checkDueArtifacts, checkStageGate, checkSecrets } from "./validate-artifacts.js";
+import { checkApproval, checkBypasses } from "./validate-approval.js";
+import { checkTasks, checkTestingResult, checkReviewReport, checkDonesArtifacts } from "./validate-reports.js";
+import { checkTraceability } from "./validate-traceability.js";
+import { checkCancellation } from "./validate-cancel.js";
+export { findSecretLike } from "./secrets.js";
+export { checkDirectionGate } from "./direction.js";
+export { STAGES };
+/** Checks for the CURRENT stage. If the feature can leave the current stage, all its gate artifacts must exist & be filled. */
+export function validateFeature(feature, strict = false, requireApproval = true) {
+    const issues = [];
+    if (!feature.meta) {
+        issues.push(finding(feature, "ERROR", ".kfw.json", feature.metaError ? "metadata_invalid" : "metadata_missing", feature.metaError ?? "Feature metadata is required for approval and execution tracking."));
+    }
+    // A cancelled item is asked for no artifact, no approval and no report. `STAGE_INDEX = -1`
+    // already makes most of those checks inert, but one that compares no index is not covered by
+    // that trick, and it made an item cancelled out of brainstorm permanently invalid — including
+    // the reopen command `kf cancel` itself prints. Deciding it here rather than inside each check
+    // means a check added later cannot reintroduce the trap by forgetting a guard.
+    //
+    // The bypass trail is deliberately NOT skipped: a recorded --force is an audit record about
+    // what someone did, not a demand on the item, and three places promise it shows up on every
+    // validation. Everything else is, including the `no_tasks` warning.
+    //
+    // Secrets are the one thing every stage owes, cancelled included. checkSecrets therefore sits
+    // OUTSIDE the branch, so neither side can drop it: it used to live inside checkDueArtifacts,
+    // where `STAGE_INDEX = -1` skipped it along with everything else, and cancelling an item was
+    // the quietest way to take a committed token off the radar while leaving it in the repo.
+    issues.push(...checkSecrets(feature));
+    issues.push(...(feature.stage === "cancelled"
+        ? [...checkCancellation(feature), ...checkBypasses(feature)]
+        : [
+            ...checkDueArtifacts(feature),
+            ...checkStageGate(feature),
+            ...checkApproval(feature, requireApproval),
+            ...checkBypasses(feature),
+            ...checkTasks(feature),
+            ...checkTestingResult(feature),
+            ...checkReviewReport(feature),
+            ...checkTraceability(feature),
+            ...checkDonesArtifacts(feature),
+        ]));
+    const hasErrors = issues.some((i) => i.severity === "ERROR");
+    const hasWarnings = issues.some((i) => i.severity === "WARNING");
+    return {
+        feature: feature.name,
+        stage: feature.stage,
+        valid: !hasErrors && !(strict && hasWarnings),
+        issues,
+    };
+}
+export function renderValidateText(r) {
+    const lines = [];
+    if (r.issues.length === 0) {
+        lines.push(`✓ ${r.feature} (stage ${r.stage}) — valid`);
+        return lines.join("\n");
+    }
+    lines.push(`✗ ${r.feature} (stage ${r.stage}) — ${r.valid ? "warnings" : "invalid"}`);
+    for (const i of r.issues) {
+        lines.push(`  [${i.severity}] ${i.file}: ${i.message} (${i.code})`);
+    }
+    return lines.join("\n");
+}
+export function validateToJson(r) {
+    return {
+        feature: r.feature,
+        stage: r.stage,
+        valid: r.valid,
+        issues: r.issues,
+    };
+}

package/docs/workflow/README.md

@@ -0,0 +1,67 @@
+# Kanban Flow Workflow
+
+`kanban-flow` drives a feature's life cycle through the `kf` CLI and the phase skills:
+
+```text
+brainstorm → planning → implementation → testing → review → dones
+                 ↘ backlog ↗
+
+any stage ──kf cancel──→ cancelled ──back to the stage it stopped in──→ (resumes)
+```
+
+The pipeline exists to turn an idea into an approved execution contract, then execute it with traceability, and test and review the right version of it before archiving.
+
+Features and bugs share one state machine. Create a bug with `kf new <name> --type bug`; it goes through `kanban-bug` for triage and reproduction before it reaches planning.
+
+## Where to start
+
+1. [Lifecycle](lifecycle.md) — who does what, and in what order.
+2. [State machine](state-machine.md) — the states and the transitions each one allows.
+3. [Gates](gates.md) — artifacts, approval, execution ids and report status.
+4. [Artifact contract](artifacts.md) — file structure, traceability and the canonical output.
+5. [CLI reference](cli-reference.md) — the command syntax an agent uses to move state.
+6. [Skill routing](skills.md) — which skill loads in which state.
+7. [Dashboard](dashboard.md) — the KPIs, the charts, the filters and what each number means.
+8. [Agent harness](harness.md) — the stage → role → runner mapping behind `kf run`, `kf runs` and `kf harness`.
+9. [Source layout](source-layout.md) — the shape of `src/` and how to extend it.
+
+## The rules that never bend
+
+- Never move a folder by hand; use `kf stage`, `kf cancel` or `kf archive`.
+- `kf cancel` is the second way out. It needs `--reason`, moves the item to `.works/cancelled/`, and the only way back is the stage it stopped in.
+- The requirement or bug report must be `status: confirmed` before it leaves brainstorm.
+- Once planning is approved, the user chooses to start now or to send the item to `backlog`.
+- Planning needs human approval. A feature's fingerprint covers the requirement, the four planning artifacts and every UC file; a bug's fingerprint covers only the bug report.
+- Editing the execution contract after approval forces a return to planning and a fresh approval.
+- Every entry into testing mints a new execution id. The testing and review reports must reference that exact id.
+- A FAIL or a REJECT returns to implementation and must be tested again. BLOCKED stops the pipeline.
+- REQUIREMENT_BUG stops every ordinary transition so the user can decide.
+- The feature report must be written before archive; the CLI syncs the canonical docs when a feature is archived. A bug only updates the related docs when there is a docs impact.
+
+One rule in that list is not like the others: the pipeline granting itself no access to a database, a deployment, a publish or a message is a **policy carried in the skill prompts**, not a gate. Nothing in `src/` enforces it, and the runner presets start workers with edits auto-accepted. It bends exactly as far as the worker does.
+
+## Filesystem model
+
+```text
+project/
+├── .kf/
+│   ├── config.json
+│   ├── templates/
+│   ├── hooks/
+│   └── review/rules/
+├── .works/
+│   ├── brainstorm/
+│   ├── planning/
+│   ├── backlog/
+│   ├── implementation/
+│   ├── testing/
+│   ├── review/
+│   ├── cancelled/
+│   └── dones/
+└── docs/
+    ├── requirement/{context}/{feature}.md
+    ├── use-cases/{context}/{feature}/README.md + UC-###.md + diagram.md
+    └── testplan/{context}/{feature}{,-result}.md
+```
+
+Each work item folder is named `{feature}_{YYYYMMDD_HHmm}` and carries a `.kfw.json`. The standard artifacts all use the `phase-{number}-` prefix.

package/docs/workflow/artifacts.md

@@ -0,0 +1,60 @@
+# The artifact contract and how to read it
+
+Artifacts are written inside the work item folder under `.works/`. Each file answers a different question; never use one report in place of another phase's.
+
+## Reading order inside a work item
+
+```text
+phase-1-spec-requirement.md
+├── phase-2-implementation-plan.md       (feature only)
+├── phase-2-use-case-specification.md    (feature only: index + coverage)
+├── use-cases/UC-###.md                   (feature only: one file per UC)
+├── phase-2-use-case-diagram.md           (feature only)
+└── phase-2-test-case.md                  (feature only: the test contract)
+    └── phase-4-testing-result.md         (the outcome of one execution)
+        └── phase-5-review-report.md      (review of that same execution)
+            └── phase-6-feature-report.md (feature only: the handover)
+```
+
+A bug uses the `phase-1-bug-report.md` template but still stores its triage record at `phase-1-spec-requirement.md` so the CLI keeps working. Beyond that record a bug needs only the testing and review reports; the planning set and the feature report are not required. If behaviour appears beyond the scope of the defect fix, report the scope change and let the user decide whether a separate feature is warranted.
+
+`phase-2-use-case-specification.md` is only an index. A feature's narrative belongs in `use-cases/UC-###.md`, and the ID in the file name must match the ID declared inside it. Every test case must trace `FR-###` → `UC-###`.
+
+## Shared conventions
+
+| Convention | What it means |
+|---|---|
+| Frontmatter | Identifies the work item, its context, its status and the current execution |
+| Placeholder | Lives only in the template; every one must be replaced with real content before a gate |
+| ID | `FR-###`, `UC-###`, `TC-###`, used consistently across every artifact |
+| Report status | Testing: `PASS/FAIL/REJECT/BLOCKED`; review: `PASS/FAIL/REJECT/REQUIREMENT_BUG` |
+| Execution | Testing and review must carry the same `executionId` as the current run |
+| Summary tables | Totals must match the detail rows, not merely describe them |
+
+The CLI checks the files, the placeholders, secret-like content, ID references, the approval fingerprint and each report's execution and status. Table totals, measured coverage and the quality of the narrative are the agent's job during planning, testing and review; a passing validator proves none of them.
+
+## On archive into `dones`
+
+`kf archive` leaves the artifact set in `.works/dones/{feature}_{timestamp}/` for audit. For a feature, the CLI copies the documents people actually read into the canonical docs:
+
+| Canonical doc | Contents |
+|---|---|
+| `docs/requirement/{context}/{feature}.md` | The archived requirement |
+| `docs/use-cases/{context}/{feature}/README.md` | The UC index and coverage |
+| `docs/use-cases/{context}/{feature}/UC-###.md` | Each use case narrative |
+| `docs/use-cases/{context}/{feature}/diagram.md` | The actor and use case diagram |
+| `docs/testplan/{context}/{feature}.md` | The test plan and the coverage matrix |
+| `docs/testplan/{context}/{feature}-result.md` | The most recent execution result |
+
+For a bug, archive neither creates nor overwrites an existing feature's docs. The archive skill updates the related docs only when the bug report states a docs impact; when there is none, it says "No documentation update required" in the closure or review.
+
+Archiving a feature that is already in `dones` refuses to overwrite canonical docs that have changed since the snapshot, so updates from a bug or from extra documentation survive. Use `--skip-specs` to leave the docs alone; use `--force` only when restoring the old snapshot is what you actually want.
+
+## Checklist before closing
+
+- [ ] The requirement or bug report is `confirmed` and free of placeholders.
+- [ ] Feature: four planning artifacts, one file per UC, and a test matrix whose IDs line up.
+- [ ] Bug: a triage record carrying the reproduction, the severity and the regression strategy.
+- [ ] Testing and review both `PASS`, on the current execution.
+- [ ] The feature report records what changed, which tests ran, which docs moved and what limits remain. Not required for a bug.
+- [ ] Canonical docs synced where needed, and no database, deploy or publish action outside the approved scope.

package/docs/workflow/cli-reference.md

@@ -0,0 +1,78 @@
+# CLI reference
+
+The binary is `kf`. Every command *except* `kf init` looks for `.works/` from the current directory upwards to the project root, so you can run it from the root or from any subdirectory.
+
+`kf init` is the exception: it resolves its path argument against the current directory and does not search upwards. Running it inside a subdirectory of a project that is already initialised creates a second `.works/`, `.kf/` and skills set there rather than finding the existing one.
+
+## Setting up and creating work
+
+| Command | What it does |
+| --- | --- |
+| `kf init [path]` | Onboarding. On a TTY it asks for the context, the stack, the reviewer, the agents, the gitignore entry and whether to seed a demo feature; without a TTY it takes the defaults. Creates `.works/`, `docs/{requirement,use-cases,testplan}` and `.kf`, installs the project-scope skills, and seeds `AGENTS.md` when neither `AGENTS.md` nor `CLAUDE.md` exists. |
+| `kf init --defaults` | Non-interactive onboarding on default values, for agents and scripts. |
+| `kf init --minimal` | Skips the questions, not the scaffolding. Creates `.works/`, the docs roots, the skills, `.kf/config.json` with the schema and the runner presets, the empty `.kf/{templates,hooks,review/rules}` directories, and `AGENTS.md` when neither `AGENTS.md` nor `CLAUDE.md` exists. What it does *not* do is copy template, hook or review-rule files into those directories — the full path does that. With `--context` on a genuinely new project it declares that context, exactly as the full path does. |
+| `kf new <feature> [--context <ctx>] [--goal <text>] [--type feature\|bug]` | Creates a feature or bug in `brainstorm`; a bug routes through `kanban-bug`. Feature and context names must match `[a-z0-9][a-z0-9_-]*` **case-insensitively**, so `LoginFlow` is accepted. Context names are then compared case-insensitively against the declared list, which refuses `Auth` beside `auth`. When the project declares contexts, an undeclared one is refused with the nearest declared name. |
+| `kf list [--json]` | Lists every work item with its kind and state. |
+| `kf doctor [--json]` | Diagnoses the project rather than a work item: stage directories, a config that parses, work item metadata that can be read, skills still installed, and config fields that no longer mean what they say. Read-only, keeps going after the first problem, and exits 1 when anything is at ERROR. Work items that are not valid are counted but never change the verdict — that is the normal state of a pipeline in motion. |
+| `kf contexts [--json]` | Lists the declared contexts with a work-item count each, marks any context in use but not declared, and prints a survey brief when none are declared. Read-only. See [contexts](#contexts). |
+| `kf show <feature> [--json]` | Shows a work item's requirement or bug report. |
+| `kf view [--json]` | Workflow statistics in the terminal; the JSON carries metrics, charts and the per-stage detail. |
+| `kf dashboard [--port <1-65535>]` | KPI and chart dashboard with context and kind filters, on port `8787` by default. See [how each number is computed](dashboard.md). |
+
+## Driving the workflow
+
+| Command | What it does |
+| --- | --- |
+| `kf status --change <feature> [--json]` | One work item's state, including how many gate or hook bypasses have been recorded, and any blocking findings the validator raises. The artifact checklist only says which files exist and are filled; the blocking list is what `kf approve` or `kf stage` would refuse on, so the two cannot disagree. The human approval gate is reported by the `Approval:` field rather than counted as a blocker. |
+| `kf status --all [--json]` | Every work item, `backlog` and `dones` included. |
+| `kf instruct <artifact\|use-case> [--change <feature>] [--id UC-###] [--json]` | Renders an artifact template; `use-case` produces the instruction for exactly one `use-cases/UC-###.md`. |
+| `kf templates [--json]` | Lists the templates currently resolved and where each came from. |
+| `kf validate --change <feature> [--strict] [--json]` | Checks artifacts, placeholders, secret-like content, traceability and the gates. Exits `1` on failure. |
+| `kf validate --all [--strict] [--json]` | Validates every work item. |
+| `kf approve <feature> [--by <name>]` | The human gate on the execution contract in planning; records the approver, the moment and the contract hash. |
+| `kf stage <feature> <next-stage> [--force] [--skip-hooks]` | Performs a legal transition and runs the destination state's hook. Planning may go to `backlog` or to `implementation`; `dones` is reached through archive. |
+| `kf cancel <feature> --reason "<why>" [--by <name>] [--purge-docs] [--force] [--skip-hooks]` | Stops a work item for good and moves it to `.works/cancelled/`, recording `cancellation { at, by, reason, fromStage }`. Refuses while a run is live unless `--force`. An item in `dones` has its canonical docs listed, and only `--purge-docs` deletes them, asking first on a TTY; `--force` answers that question in advance, and without a TTY it is the only way through. Reopen with `kf stage <feature> <fromStage>`. |
+| `kf archive <feature> [--force] [--skip-specs] [--skip-hooks]` | Archives from review into dones and updates the metadata; a feature receives the canonical copies, a bug keeps its existing docs. |
+| `kf rules [--stack <id> ...] [--list] [--force]` | Copies the stack best-practice review rules into `.kf/review/rules/`. Detects the stacks automatically, installing several packs in a monorepo; `--list` shows the packs and `--force` overwrites files you have edited. |
+| `kf autoconfig` | Prints a briefing for an agent on stdout: the project context, a config checklist of what is done and what is missing with the command to fix it, the effective review rules and the workflow guide, so the agent can configure the project itself. |
+| `kf run <feature> [--stage <s>] [--role <r>] [--fresh] [--detach] [--timeout <minutes>] [--dry-run]` | Runs, in order, the role chain that `harness.stages` assigns to the current stage. Records a `runs[]` entry per role and resumes the session per work item and role. A role that does not finish `DONE` stops the chain. `--detach` returns immediately and leaves a supervisor to finish. Exits 1 when the chain does not complete. See [harness](harness.md). |
+| `kf runs [<feature>] [--json]` | Worker run history with role, runner, stage, mode, status and STATUS line, newest first. |
+| `kf harness [--json]` | The harness in effect: the main role, stage to role chain, role to runner with its brief and output, and which runner CLIs are on PATH. |
+
+`--force` deliberately skips a gate; when re-archiving a work item in `dones` it also allows the archive snapshot to overwrite canonical docs that were edited. `--skip-hooks` skips the destination phase's hook. `--skip-specs` touches no canonical doc during archive. Whenever `--force` or `--skip-hooks` actually skips something, the CLI writes a record into `.kfw.json` under `bypasses[]` and says so in its output. See [gates](gates.md#force-and-recovery).
+
+## Skill installation
+
+Skills always live at **project scope** (`{root}/.claude/skills`, `{root}/.agents/skills` and so on). The `kf` CLI is the only thing installed globally, through `npm link`. `kf init` installs the skills during setup; `kf install` and `kf uninstall` work on the project root resolved from the nearest `.works/` above the working directory. Neither writes anything into `~/`.
+
+| Command | What it does |
+| --- | --- |
+| `kf install [--agent <id> ...]` | Installs the 8 skills into each agent's own directory, defaulting to `claude`. Must run inside a kanban project, which means a `.works/` exists; run `kf init` first if it does not. The directory is `.claude/skills`, `.gemini/skills`, `.kiro/skills`, `.cursor/skills`, `.opencode/skills` — and `.agents/skills` for `codex`, which follows the open standard rather than its own name. An unknown agent also falls back to `.agents/skills`. |
+| `kf uninstall [--agent <id> ...] [--purge] [--force]` | Removes exactly the 8 skills that kanban-flow manages, leaving every other skill alone. `--purge` also deletes `.works/`, `.kf/` and `docs/{requirement,use-cases,testplan}/`, asking first on a TTY and requiring `--force` without one. |
+
+Uninstall only removes skills. To take the CLI off PATH: `npm rm -g @phuthuycoding/kanban-flow`.
+
+## Error conventions
+
+- Success exits `0`. Bad input, a failed gate, a failed hook, a missing work item or an exception exits `1`. The readable report goes to **stdout**; stderr carries only a short reason line. A CI step that keeps stderr and discards stdout captures the reason but none of the detail.
+- The CLI never runs a migration, updates a database, deploys or publishes on its own.
+- Hooks resolve in order: the project `.kf/hooks`, then the user's `~/.kf/hooks`, then the package hooks. The environment handed to a hook carries `KFW_FEATURE`, `KFW_CONTEXT`, `KFW_FROM_STAGE`, `KFW_TO_STAGE`, `KFW_FEATURE_DIR`, `KFW_WORK_ROOT` and `KFW_APPROVAL`.
+
+## Contexts
+
+A context groups work items and their canonical docs by business domain: `docs/requirement/{context}/`, and the same under `use-cases` and `testplan`.
+
+A project may declare which contexts exist, in `.kf/config.json`:
+
+```json
+"contexts": ["auth", "billing", "catalog"]
+```
+
+Two things follow from that list, and nothing follows without it:
+
+- **The first entry is the default context** for `kf new` without `--context`. There is no separate default field to keep in step with the list. `defaultContext` is still read for projects created before `contexts` existed, and is ignored once a list is declared.
+- **`kf new` refuses a context that is not on the list**, naming the nearest declared spelling. A name differing only in case is refused too, because accepting `Auth` beside `auth` is how a second docs tree appears on a case-sensitive filesystem.
+
+A project with no `contexts` key is unrestricted. Re-running `kf init` there does not add the key, and neither does a project that has work items but no config file yet: a project counts as existing if it has either. `kf init` writes the list only for a genuinely new project, or when you answer its question on a terminal. The one behaviour that did change for an unrestricted project: `kf new` now reads the config on every path, so a malformed config fails loudly instead of only when `--context` was omitted.
+
+`kf contexts` reports each in-use context with the spelling found on disk, not a lowercased one. Where an undeclared spelling differs from a declared one only by case, it says so instead of telling you to add it, because the config reader refuses that repeat: rename the work items, or change the declared entry. It never writes anything. When no list is declared it prints a brief for an agent to survey the repo and propose one, which a human then confirms and writes.

package/docs/workflow/dashboard.md

@@ -0,0 +1,35 @@
+# Dashboard metrics and charts
+
+Run `kf dashboard` and open `http://localhost:8787`. Change the port with `--port`. The dashboard refreshes every 5 seconds, has a manual refresh button and filters by context and by work item kind.
+
+## KPI
+
+| Metric | How it is computed |
+|---|---|
+| Work items | Every feature and bug matching the filter, `dones` included |
+| In execution | Items in `implementation`, `testing` or `review` |
+| Backlog | Items in `backlog` |
+| Completed | Items in `dones`; the rate is dones divided by total items **minus cancelled ones** |
+| Cancelled | Items in `cancelled`; shown so the gap in the completion rate's denominator is visible |
+| Gate bypasses | Items carrying a recorded `--force` or `--skip-hooks` |
+| Task progress | Completed checkboxes divided by all checkboxes across the items in execution |
+
+With no items or no tasks to divide by, the figure shows as `—`. An item in execution with no task checkboxes is counted separately and never defaults to done. Task progress is not a test pass rate and not code coverage.
+
+## Charts
+
+- Bars by stage: the total per state and the feature/bug split within it.
+- Feature and bug donut: the share of each work item kind under the current filter.
+- Bars by context: item volume across contexts, ordered by total, largest first.
+- Approval bars: pending, approved and changed. The filter excludes exactly two stages, `brainstorm` and `dones` — so besides planning through review and backlog, **cancelled items are counted too**, and a cancelled item that never reached approval lands in the pending column.
+- Task progress bar: tasks done, items that have tasks and items that do not, across the stages in execution.
+
+The charts show the filesystem as it is right now. The workflow keeps no history of stage transitions, so the dashboard infers no throughput, no lead time and no trend over time from these counts.
+
+## CLI and API
+
+`kf view` prints the same summary in the terminal. `kf view --json` and `/api/data` return `metrics`, `charts`, `availableContexts` and `stages`, so existing agents and tools can still read it.
+
+The API takes `?kind=feature|bug&context=<slug>`. Drop a parameter to see everything. `context=__none__` selects older items that carry no context. The context list behind the filter is always drawn from the whole project.
+
+When the API fails, the dashboard says so and keeps the previous snapshot with a warning that the numbers may be stale. It never turns an error into a zero.

package/docs/workflow/gates.md

@@ -0,0 +1,103 @@
+# Gates and the artifact contract
+
+A gate is checked on the way out of the current state. `kf validate` runs most of the same checks so you see the failures early; `kf stage` and `kf archive` refuse the transition when a gate does not hold.
+
+One group is not shared: the *direction* gate, which decides where a PASS or FAIL report may send an item. `validateFeature` does not call it, so `tasks_incomplete` and `testing_already_pass` never appear in `kf validate` and first surface when `kf stage` refuses the move. A clean `kf validate` is therefore not a promise that the next transition will be allowed.
+
+## Required artifacts
+
+| Phase | File | Minimum contents | Unlocks |
+| --- | --- | --- | --- |
+| 1 — Brainstorm / bug triage | `phase-1-spec-requirement.md`, a bug using the bug-report template | Feature: the requirement plus FR-XXX. Bug: reproduction, actual against expected, severity, regression strategy | Planning |
+| 2 — Planning (feature) | `phase-2-implementation-plan.md` | Scope, tasks, impact, definition of done, risks | The execution contract |
+| 2 — Planning (feature) | `phase-2-use-case-specification.md` plus `use-cases/UC-###.md` | Index and coverage in the phase file; each UC carries its own preconditions, flows and alternate or error flows | Design and testing |
+| 2 — Planning (feature) | `phase-2-use-case-diagram.md` | A valid actor and use case diagram | Traceability |
+| 2 — Planning (feature) | `phase-2-test-case.md` | TC-XXX entries linked to FR-XXX and UC-XXX | The testing contract |
+| 4 — Testing | `phase-4-testing-result.md` | The current execution id, a PASS/FAIL/REJECT/BLOCKED verdict, the evidence | Review, or the repair loop |
+| 5 — Review | `phase-5-review-report.md` | The current execution id, a PASS/FAIL/REJECT/REQUIREMENT_BUG verdict, the findings | Archive, or the repair loop |
+| 6 — Artifact (feature) | `phase-6-feature-report.md` | The summary, what changed, the tests, the docs, the known limits | A finished feature |
+
+Implementation has no required artifact of its own in the schema, but the implement skill must finish the tasks in the plan and leave the code in a state that can be tested.
+
+## Canonical output on entering `dones`
+
+`kf archive` copies from the work item folder to stable paths under the context. Only a feature gets its canonical docs copied automatically:
+
+| Source | Destination |
+| --- | --- |
+| `phase-1-spec-requirement.md` | `docs/requirement/{context}/{feature}.md` |
+| `phase-2-use-case-specification.md` | `docs/use-cases/{context}/{feature}/README.md`, the index |
+| `use-cases/UC-###.md` | `docs/use-cases/{context}/{feature}/UC-###.md`, one file per use case |
+| `phase-2-use-case-diagram.md` | `docs/use-cases/{context}/{feature}/diagram.md` |
+| `phase-2-test-case.md` | `docs/testplan/{context}/{feature}.md` |
+| `phase-4-testing-result.md` | `docs/testplan/{context}/{feature}-result.md` |
+
+The canonical requirement is marked `archived`; the other artifacts keep their frontmatter and evidence so they can be traced later. For a bug, archive only moves the work item into `dones`; the related feature's docs change only when the bug report states a docs impact. `--skip-specs` skips this whole table.
+
+## What each direction requires
+
+```mermaid
+flowchart LR
+    B[brainstorm] -->|requirement confirmed| P[planning]
+    P -->|feature: 4 artifacts + approval<br/>bug: bug report + approval| I[implementation]
+    I -->|implementation complete + tasks done| T[testing]
+    T -->|PASS + current execution| R[review]
+    T -->|FAIL/REJECT| I
+    R -->|PASS + current execution<br/>feature additionally requires feature report| D[dones]
+    R -->|FAIL/REJECT| I
+    T -->|scope change| P
+    R -->|scope change| P
+    P -->|hold: no gate| BL[backlog]
+    BL -->|start: same gate as planning| I
+    BL -->|scope change| P
+    I -->|scope change| P
+```
+
+`implementation → testing` is also blocked while `tasks.md` still holds an unfinished checkbox, which is the definition of done. `tasks.md` is not a required artifact: with no such file, this gate does not apply.
+
+## Contract and traceability
+
+Feature planning builds a chain you can follow:
+
+`FR-XXX` → `UC-XXX` → `TC-XXX` → implementation → testing evidence → review finding.
+
+IDs must match exactly; `FR-001` is never treated as `FR-0010`. A TC missing its FR or UC reference, a reference that does not exist, a duplicate TC id, an empty file or an unreplaced placeholder all fail validation. The agent still has to review the content of each section and the totals in each table.
+
+The validator also scans artifact content for real secrets, such as a Bearer token, an API key, a private key or a password written as `KEY=value`, and fails with `artifact_secret` when it finds one. An artifact must never carry a credential. Placeholder values like `{key}`, `<token>`, `changeme`, `redacted` or a run of four or more `x` are not flagged. The exemption applies to the **captured value**, not to the whole line: `TOKEN=ghp_… # example` is still flagged. High-confidence formats (`ghp_`/`github_pat_`, `sk-`, `AKIA`, `xox*-`, a PRIVATE KEY header, a three-segment JWT starting `eyJ`, and Slack or Discord webhook URLs) are exempt only when the value itself is masked with `xxxx` or `****`. Each of those begins with something no honest template would invent, so no wording on the line excuses them.
+
+A connection string carrying a password (`scheme://user:<password>@host`) is also flagged, with the password as the captured value — but it is **not** high-confidence, because it has no such marker: it is pure URL shape, which a template like `scheme://user:<password>@host` has too. It uses the ordinary placeholder exemption, so a real password is caught and an obvious placeholder is not. A URL with no password is never flagged; there is nothing to leak. The error message never echoes the secret.
+
+The secret scan is the one check that ignores the stage entirely. It runs on **every artifact that exists on disk**, whether or not the workflow has reached the phase that asks for that file, and including items in `cancelled` — which sit at `STAGE_INDEX = -1` and are exempt from every other artifact check. A credential is a credential regardless of where the item stands, and cancelling an item must not be a way to take a committed token off the radar.
+
+A testing report with `status: PASS` must also carry a table under the `## Commands and Evidence` heading with at least one command line and every Exit code cell equal to `0`; breaking that is `testing_exit_code`. The rule does not prove the tests ran. It only stops a PASS report that has no numeric evidence behind it. FAIL, REJECT and BLOCKED reports are not bound by it.
+
+The Phase 2 approval is a SHA-256 fingerprint of the requirement, the four planning artifacts and every `use-cases/UC-###.md` for a feature; a bug's fingerprint covers the bug report alone. Editing the contract after approval forces a return to planning, a rewrite and a fresh approval.
+
+## Cancelled
+
+`cancelled` is the one stage with **no artifact gate**. Its `STAGE_INDEX` is `-1`, so every "is this artifact due yet" and "are we past planning" comparison comes out false, and the validator skips artifacts, approval, traceability and report semantics entirely. In exchange it has exactly one requirement of its own: `cancellation.reason` must not be empty, and a missing one is `cancellation_missing`.
+
+`kf cancel` runs the `cancelled.sh` hook like any other transition, refuses while a worker run is live unless `--force`, and for an item in `dones` it **lists** the canonical docs rather than deleting them. Only `--purge-docs` deletes. On a TTY it asks first — unless `--force` is also given, which takes the confirmation as already granted; without a TTY, `--force` is the only way through. The deletion runs only **after** the work item has moved into `.works/cancelled/` successfully, so a failure during the move cannot lose documents. A cancelled item cannot be archived.
+
+On the numbers: cancelled items are taken out of the denominator of `completionRate`, so dropping something does not dent the rate, and `kf runs` leaves out the runs of a dropped item unless you name it directly with `kf runs <feature>`, exactly as it treats an item in `dones`.
+
+## Force and recovery
+
+`--force` is a deliberate escape hatch for skipping validation or a directional gate. It does not belong in the normal flow, and when it is used the reason must be written into the review or the feature report.
+
+Every time `--force` skips a gate that was actually failing, or `--skip-hooks` skips a hook that actually exists, `kf stage` and `kf archive` write a record into `.kfw.json`:
+
+```json
+"bypasses": [
+  { "at": "20260919_1230", "from": "brainstorm", "to": "planning", "flag": "force", "codes": ["requirement_unconfirmed"] },
+  { "at": "20260919_1231", "from": "planning", "to": "backlog", "flag": "skip-hooks", "codes": ["hook:/path/.kf/hooks/backlog.sh"] }
+]
+```
+
+A flag that skips nothing, because the gate passed or no hook exists, records nothing. `kf validate` raises the `gate_bypassed` warning, `kf status` prints `Bypasses: N`, and `kf view --json` and the dashboard count the work items carrying one. There is no command to erase a record. The limit is worth stating plainly: this is a trail for a human reviewer, not a guarantee, because an agent can still edit the JSON by hand.
+
+- A phase hook fails: the transition is refused. Fix the hook, or use `--skip-hooks` once you understand what that skips.
+- Testing or review comes back `FAIL` or `REJECT`: return to implementation, fix the code, then enter testing again for a new execution id.
+- `BLOCKED`: stop and report the blocker. Never fake a PASS.
+- `REQUIREMENT_BUG`: stop the feature and tell the user. Continue only on a clear decision from them about the scope or the requirement.
+- Archive fails midway: the CLI returns the feature to review and restores the metadata and specs where it can. When the rollback is incomplete, the error says so plainly so it can be sorted out by hand.