Skip to content

artifacts.md

Latest commit

 

History

History
62 lines (46 loc) · 4.82 KB

artifacts.md

File metadata and controls

62 lines (46 loc) · 4.82 KB
Raw

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

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-###-<slug>.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-###-<slug>.md — for example UC-001-create-task.md, so the name alone says what the file covers. The older plain UC-###.md form is still accepted; in both cases the UC-### prefix of 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-###(-<slug>).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

The index lands as README.md with its use-cases/... links rewritten to sibling links, and the feature report is not copied — it stays with the work item for audit. On this first copy the .works/ versions win unconditionally: whatever already sits at a canonical path, including a hand-edited requirement mirror, is overwritten.

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.

The overwrite behaviour flips on a re-archive: 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 — the bypass is recorded in .kfw.json.

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.