@haposoft/cafekit 0.16.0-rc.2 → 0.16.0-rc.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/bin/__tests__/codex-hooks.test.js +794 -21
  2. package/bin/__tests__/codex-native.test.js +228 -7
  3. package/bin/__tests__/develop-contract.test.js +1838 -112
  4. package/bin/__tests__/installer-safety.test.js +82 -29
  5. package/bin/__tests__/opencode-spec-gate.test.js +799 -0
  6. package/bin/__tests__/package-inventory.test.js +841 -10
  7. package/bin/__tests__/specs-v2-execution-closeout.test.js +421 -0
  8. package/bin/__tests__/specs-v2-policy-and-scaffold.test.js +601 -0
  9. package/bin/__tests__/specs-v2-validator-grounder-contract.test.js +952 -0
  10. package/bin/__tests__/test-runtime-dependency-closure.cjs +182 -0
  11. package/bin/__tests__/validator-grounding.test.js +2469 -71
  12. package/bin/lib/managed-writer.js +12 -3
  13. package/bin/phases/codex-runtime.js +17 -1
  14. package/package.json +1 -1
  15. package/src/claude/CLAUDE.md +6 -0
  16. package/src/claude/agents/code-auditor.md +20 -0
  17. package/src/claude/agents/spec-maker.md +153 -202
  18. package/src/claude/hooks/__tests__/completion-authority.test.js +953 -0
  19. package/src/claude/hooks/__tests__/privacy-block.test.js +172 -0
  20. package/src/claude/hooks/__tests__/semantic-review-authority.test.js +257 -0
  21. package/src/claude/hooks/__tests__/spec-gate.test.js +604 -56
  22. package/src/claude/hooks/completion-authority-check.cjs +56 -0
  23. package/src/claude/hooks/completion-authority-state.cjs +527 -0
  24. package/src/claude/hooks/completion-authority.cjs +154 -0
  25. package/src/claude/hooks/docs-sync.cjs +5 -2
  26. package/src/claude/hooks/lib/privacy-command-analysis.cjs +393 -0
  27. package/src/claude/hooks/lib/runtime-path-safety.cjs +119 -0
  28. package/src/claude/hooks/privacy-block.cjs +77 -30
  29. package/src/claude/hooks/semantic-review-authority.cjs +152 -0
  30. package/src/claude/hooks/session.cjs +33 -19
  31. package/src/claude/hooks/spec-gate.cjs +181 -139
  32. package/src/claude/hooks/spec-state.cjs +112 -47
  33. package/src/claude/migration-manifest.json +15 -2
  34. package/src/claude/rules/state-sync.md +52 -21
  35. package/src/claude/rules/workflow.md +17 -9
  36. package/src/claude/scripts/provenance.cjs +315 -0
  37. package/src/claude/scripts/spec-final-state.cjs +244 -0
  38. package/src/claude/scripts/spec-ground.cjs +535 -173
  39. package/src/claude/scripts/spec-readiness.cjs +118 -0
  40. package/src/claude/scripts/spec-receipt.cjs +162 -0
  41. package/src/claude/scripts/spec-resolver.cjs +501 -0
  42. package/src/claude/scripts/spec-scaffold.cjs +1945 -55
  43. package/src/claude/scripts/spec-semantic-model.cjs +396 -0
  44. package/src/claude/scripts/validate-spec-output.cjs +3204 -262
  45. package/src/claude/scripts/workflow-policy.cjs +1888 -203
  46. package/src/claude/settings/settings.json +12 -0
  47. package/src/claude/skills/code-review/SKILL.md +94 -66
  48. package/src/claude/skills/code-review/references/spec-compliance-review.md +10 -2
  49. package/src/claude/skills/code-review/references/verification-gate.md +13 -0
  50. package/src/claude/skills/develop/SKILL.md +138 -283
  51. package/src/claude/skills/develop/references/parallel-waves.md +9 -6
  52. package/src/claude/skills/develop/references/quality-gate.md +123 -148
  53. package/src/claude/skills/develop/references/subagent-patterns.md +42 -37
  54. package/src/claude/skills/specs/SKILL.md +192 -397
  55. package/src/claude/skills/specs/references/ask-user-question-gates.md +27 -18
  56. package/src/claude/skills/specs/references/cross-spec-dependency.md +8 -4
  57. package/src/claude/skills/specs/references/research-strategy.md +4 -1
  58. package/src/claude/skills/specs/references/review.md +200 -260
  59. package/src/claude/skills/specs/references/scope-inquiry.md +18 -5
  60. package/src/claude/skills/specs/rules/design-discovery-full.md +33 -81
  61. package/src/claude/skills/specs/rules/design-discovery-light.md +21 -42
  62. package/src/claude/skills/specs/rules/design-principles.md +136 -180
  63. package/src/claude/skills/specs/rules/design-review.md +42 -97
  64. package/src/claude/skills/specs/rules/ears-format.md +42 -50
  65. package/src/claude/skills/specs/rules/phase-decision-matrix.md +42 -41
  66. package/src/claude/skills/specs/rules/task-scoring-rubric.md +46 -46
  67. package/src/claude/skills/specs/rules/tasks-generation.md +189 -271
  68. package/src/claude/skills/specs/templates/design.md +49 -263
  69. package/src/claude/skills/specs/templates/requirements.md +26 -36
  70. package/src/claude/skills/specs/templates/research.md +9 -98
  71. package/src/claude/skills/specs/templates/spec-state.json +26 -67
  72. package/src/claude/skills/specs/templates/task.md +30 -82
  73. package/src/claude/skills/sync/SKILL.md +45 -15
  74. package/src/claude/skills/sync/references/sync-protocols.md +34 -16
  75. package/src/claude/skills/test/SKILL.md +151 -167
  76. package/src/codex/AGENTS.md +6 -0
  77. package/src/codex/hooks/completion-authority-check.cjs +63 -0
  78. package/src/codex/hooks/completion-authority-state.cjs +527 -0
  79. package/src/codex/hooks/completion-authority.cjs +106 -0
  80. package/src/codex/hooks/lib/hook-context.cjs +58 -4
  81. package/src/codex/hooks/lib/privacy-command-analysis.cjs +3 -0
  82. package/src/codex/hooks/lib/privacy-state.cjs +38 -16
  83. package/src/codex/hooks/lib/runtime-path-safety.cjs +3 -0
  84. package/src/codex/hooks/lib/spec-receipt.cjs +86 -115
  85. package/src/codex/hooks/lib/spec-utils.cjs +104 -27
  86. package/src/codex/hooks/privacy-approval.cjs +1 -1
  87. package/src/codex/hooks/privacy-block.cjs +67 -11
  88. package/src/codex/hooks/semantic-review-authority.cjs +130 -0
  89. package/src/codex/hooks/session.cjs +2 -0
  90. package/src/codex/hooks/spec-gate.cjs +151 -24
  91. package/src/codex/hooks/spec-state.cjs +65 -12
  92. package/src/codex/hooks/state.cjs +2 -0
  93. package/src/codex/hooks.json +16 -1
  94. package/src/codex/rules/state-sync.md +47 -27
  95. package/src/common/AGENTS.md +1 -1
  96. package/src/opencode/AGENTS.md +4 -2
  97. package/src/opencode/plugins/spec-gate.ts +296 -122
  98. package/src/opencode/plugins/spec-state.ts +183 -116
@@ -1,99 +1,47 @@
1
1
  # Task R{{REQ_NUMBER}}-{{SEQ}}: {{TITLE}}
2
-
3
- **Requirement:** R{{REQ_NUMBER}} — {{REQUIREMENT_TITLE}}
4
2
  **Status:** pending
5
- **Priority:** {{PRIORITY}}
6
- **Estimated Effort:** {{EFFORT}}
7
- **Dependencies:** {{DEPENDENCIES}}
8
- **Spec:** specs/{{FEATURE_NAME}}/
9
-
10
- ## Context
11
-
12
- - **Why**: {{Business/user reason this task exists}}
13
- - **Current state**: {{Relevant existing files, route, model, API, screen, or "greenfield"}}
14
- - **Target outcome**: {{Observable behavior after this task is done}}
15
-
16
- ## Constraints
17
-
18
- - **MUST**: {{Non-negotiable requirement or technical constraint}}
19
- - **SHOULD**: {{Recommended approach or optimization}}
20
- - **MUST NOT**: {{Explicitly forbidden action or approach}}
21
- - **SCOPE**: Implement only the behavior mapped to R{{REQ_NUMBER}} and the approved `scope_lock`; do not add out-of-scope features or leave scoped acceptance criteria unwired.
22
-
23
- ## Steps
24
-
25
- - [ ] 1. {{Actionable step with exact file/path/contract}}
26
- - {{Business intent: what user/system behavior this enables}}
27
- - {{Code detail: schema/API/component/function/route and validation rules}}
28
- - _Requirements: {{REQ_NUMBER}}.{{X}}_
29
-
30
- - [ ] 2. {{Next actionable step}}
31
- - {{Business intent}}
32
- - {{Code detail, edge case, or integration contract}}
33
- - _Requirements: {{REQ_NUMBER}}.{{Y}}_
34
-
35
- - [ ] 3. Verification implementation
36
- - {{Unit/integration/e2e test or explicit manual verification hook}}
37
- - _Requirements: {{REQ_NUMBER}}_
38
3
 
39
- ## Requirements
4
+ ## Outcome
40
5
 
41
- - {{REQ_NUMBER}}.{{X}} — {{Acceptance criterion or requirement covered}}
42
- - {{REQ_NUMBER}}.{{Y}} — {{Acceptance criterion or requirement covered}}
6
+ {{Concrete observable vertical outcome, named entrypoint, and resulting state delivered by this task.}}
43
7
 
44
- ## Related Files
8
+ ## Scope
45
9
 
46
- | Path | Action | Description |
47
- |---|---|---|
48
- | `{{FILE_PATH_1}}` | Create / Modify / Delete | {{DESCRIPTION_1}} |
49
- | `{{FILE_PATH_2}}` | Create / Modify / Delete | {{DESCRIPTION_2}} |
10
+ - **In scope:** {{Exact behavior owned by this task}}
11
+ - **Out of scope:** {{Explicit exclusions or delegated behavior}}
50
12
 
51
- ## Completion Criteria
13
+ ## Anchors and Ownership
52
14
 
53
- - [ ] {{Criteria 1 — observable output or artifact, maps to acceptance criteria R{{REQ_NUMBER}}}}
54
- - [ ] {{Criteria 2 — measurable behavior or negative-path outcome}}
55
- - [ ] {{Criteria 3 — maps directly to acceptance criteria from requirements.md and can be proven below}}
56
- - [ ] {{Criteria 4 — no orphaned component/service/route/command; created runtime-facing work is reachable from the declared entrypoint or explicitly deferred to a named integration task}}
15
+ <!-- Compact core: one owned anchor is enough; proof artifact/owner exists only for a typed proof boundary (see Verification Plan). -->
16
+ | ID | Type | Target | Role | Access | Action |
17
+ |---|---|---|---|---|---|
18
+ | A-R{{REQ_NUMBER}}-{{SEQ}}-01 | file | `{{exact/path/to/file}}` | owner | write | modify |
19
+ <!-- For a typed proof boundary, add: | A-R{{REQ_NUMBER}}-{{SEQ}}-02 | file | `{{exact/path/to/test-file}}` | proof | write | create | and set Task role accordingly; otherwise omit. Every executable task must own a concrete test file/artifact anchor or share proof via that typed boundary; bare command is not ownership. -->
57
20
 
58
- ## Evidence
21
+ ## Changes
59
22
 
60
- This section is both the task-level test plan and the proof checklist. Keep it short, exact, and executable.
61
- Select the proof by task risk; do not run every test type for every task.
23
+ <!-- Every checkbox maps exact RN.M IDs; the set must equal Acceptance below. -->
24
+ - [ ] {{Implement behavior at the exact owned boundary.}} _Requirements: {{REQ_NUMBER}}.{{X}}_
25
+ - [ ] {{Handle the concrete negative or recovery path.}} _Requirements: {{REQ_NUMBER}}.{{Y}}_
62
26
 
63
- Verification: PENDING
27
+ ## Acceptance
64
28
 
65
- - Logic/data/validator task: include unit tests.
66
- - Stateful UI/component task: include component or integration tests.
67
- - Cross-module/API/state flow task: include integration tests.
68
- - User-facing end-to-end workflow: include E2E/UI flow verification.
69
- - Layout/theme/responsive task: include visual/runtime viewport checks.
70
- - Interactive UI task: include accessibility checks when keyboard, focus, labels, or ARIA can regress.
71
- - Scaffold/release task: include smoke build/test/dev-server checks.
72
- - Performance/security checks are required only when the requirement, risk, or touched surface calls for them.
29
+ <!-- Declare each mapped RN.M once with a measurable output/state and negative behavior. -->
30
+ - **R{{REQ_NUMBER}}.{{X}}:** {{Measurable observable outcome}}
31
+ - **R{{REQ_NUMBER}}.{{Y}}:** {{Concrete negative or recovery outcome}}
73
32
 
74
- - [ ] Automated verification (unit/component/integration/E2E as applicable)
75
- - Command(s): `{{TYPECHECK / TEST / BUILD COMMANDS OR N/A}}`
76
- - Expected proof: {{What output, exit code, or report proves success}}
77
- - [ ] Artifact / runtime verification
78
- - Inspect: `{{artifact path | route | UI state | DB object | manifest entry}}`
79
- - Expect: {{Observable result that proves the task is really wired}}
80
- - [ ] Runtime reachability verification
81
- - Entrypoint/caller: `{{App.tsx | route file | CLI command | worker registration | manifest | API consumer}}`
82
- - Expect: {{Created component/service/route/worker/loader is imported, mounted, registered, or invoked from the runtime path; if deferred, name the later integration task}}
83
- - [ ] Contract / negative-path verification
84
- - Check: {{Unauthorized path, validation error, permission omission, missing env behavior, deletion effect, etc.}}
85
- - Expect: {{Concrete failure mode or contract-preserving behavior}}
33
+ ## Dependencies
86
34
 
87
- ## Risk Assessment
35
+ - {{DEPENDENCIES}}
88
36
 
89
- | Risk | Severity | Mitigation |
90
- |---|---|---|
91
- | {{RISK_1}} | High/Medium/Low | {{MITIGATION_1}} |
92
- | {{RISK_2}} | High/Medium/Low | {{MITIGATION_2}} |
37
+ ## Verification Plan
93
38
 
94
- ---
39
+ <!-- Ownership invariant: a bare npm test command without a concrete file/artifact anchor is not ownership; shared proof must use a typed proof boundary. -->
40
+ - **Verification ref:** {{V reference whose structured subject/proof owner matches this task}}
41
+ - **Task role:** {{subject | verifier}}
42
+ - **Command:** `{{Exact project command}}`
43
+ - **Expected:** {{Exit, output, state, artifact, or UI result}}
44
+ - **Negative path:** {{Contract-preserving failure check}}
45
+ - **Reachability:** `{{Real entrypoint/caller or generated artifact}}`
95
46
 
96
- > **Parallel marker**: Append `(P)` to the title if this task can run concurrently with another (usually when serving different requirements).
97
- > **Test note**: If a test coverage sub-task can be deferred post-MVP, mark it with `- [ ]*`.
98
- > **Requirement mapping**: Every sub-task MUST end with `_Requirements: X.X_`. No mapping = invalid task file.
99
- > **Evidence rule**: No `## Evidence` section = invalid task file. Use `## Evidence` (legacy heading aliases still parse).
47
+ <!-- The table above is the only task anchor/ownership table. Access read requires Action read. Access write requires create, modify, or delete. Targets are exact; globs and parent-directory claims are invalid. A verifier must not repeat the subject's Acceptance criterion. Specs-only never creates or updates docs and never fabricates execution proof; record doc impact as a brief recommendation only. -->
@@ -14,19 +14,28 @@ metadata:
14
14
 
15
15
  This skill safely bridges the gap between active development state and physical documentation files (`spec.json` + `task_registry` + `tasks/task-R*.md`). Instead of relying on risky raw AI edits, this skill executes precise contextual replacements.
16
16
 
17
- ## Lane-aware synchronization
17
+ ## v2.1 authority-aware synchronization
18
18
 
19
- Read lane policy before mutating state:
19
+ Read canonical policy before mutating state. Lane is a derived view:
20
20
 
21
21
  ```bash
22
22
  node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON>' --json
23
23
  ```
24
24
 
25
- - Direct may have no spec/state/registry; sync only concrete targeted evidence and never invents approval state.
26
- - Standard stores one bounded spec and one canonical feature receipt; one combined `code-auditor` review gates feature closeout.
27
- - Critical requires strict durable evidence and `inspector → implementer → test-runner → code-auditor` delegation by default.
28
- - `generated`, `agent_validated`, and `user_approved` are independent. Missing `user_approved` stays false; sync never auto-approves user-owned state.
29
- - Explicit lane overrides must preserve automatic classification and warning in receipt/state output, especially Critical downgrades.
25
+ - Direct may have no spec/state/registry; sync only concrete targeted evidence
26
+ and never invents proof, readiness, approval, or audit state.
27
+ - Standard stores one bounded spec; final integration creates one canonical
28
+ feature receipt. A combined closeout review is required only when the
29
+ persisted policy says an independent audit is needed.
30
+ - Critical requires strict durable evidence and the persisted capability obligations; choose available actors or the main session according to required capability and independence, never a fixed actor sequence.
31
+ - Authoring states are only `draft`, `validated`, or `absent`. Legacy approval
32
+ fields are readable but inert.
33
+ - Preserve `classified_minimum`. Reclassification happens before persistence;
34
+ after persistence, the same-feature baseline is monotonic and no downgrade is
35
+ supported until a trusted issuer exists.
36
+ - `spec.json` is machine authority. Task status/checkboxes, dependencies, and
37
+ ownership Markdown are projections. Typed `coordination.boundaries` are the
38
+ only topology authority.
30
39
 
31
40
  ## Supported Commands
32
41
  ### 1. Task Synchronization
@@ -52,22 +61,43 @@ Scans the `spec.json` against all physical `task-R*.md` files to detect mismatch
52
61
 
53
62
  1. **Precision Edits:** Never overwrite the entire `spec.json` string blindly. Update only the required keys, while keeping JSON valid.
54
63
  2. **Machine + Human Sync:** Every task status update MUST modify both `spec.json.task_registry[...]` and the matching markdown task file header/status section.
55
- 3. **Markdown Integrity:** When marking a task `done`, only then turn `[ ]` into `[x]` inside `## Steps` / `## Implementation Steps` and relevant `Completion Criteria` / `Evidence` checkboxes that have actual proof. Use `## Evidence` (legacy heading aliases still parse).
56
- 4. **Verification Receipt Rule:** `done` is illegal without a human-readable verification receipt already present in `## Evidence` (legacy heading aliases still parse) (commands executed, artifact/runtime proof, or equivalent concrete evidence). If proof is missing, keep the task `in_progress` or `blocked`.
57
- 5. **Task Docs Hook:** Every time `hapo:sync` marks a task as `done`, it must flag that a task-level docs checkpoint is now due for that verified task.
58
- 6. **Phase Prompt Rule:** When `hapo:sync` marks the final pending task in the whole feature as `done`, it should automatically prompt the user if they'd like to advance the phase, but only after the docs checkpoint for that last completed task has been considered.
64
+ 3. **Markdown Integrity:** Task Markdown is a plan plus `**Status:**`. Update
65
+ Status and `Changes` checkboxes only when their implementation is real; never
66
+ insert Base/Head, verdicts, command outcomes, or receipt proof into the plan.
67
+ 4. **Verification Receipt Rule:** `done` is illegal without a valid canonical
68
+ `receipts/<task-basename>.md`, or a readable legacy `## Evidence` receipt.
69
+ Prefer the separate receipt; if both exist and proof identity conflicts,
70
+ refuse completion. If proof is missing, keep the task `in_progress` or
71
+ `blocked`.
72
+ 5. **Task Docs Hook:** When `hapo:sync` marks a task as `done`, assess actual documentation impact and report `Docs impact: major|minor|none`; do not create a docs update request when impact is `none`.
73
+ 6. **Topology Rule:** Never infer dependency or parallel state from `(P)`,
74
+ `task_triggers`, `Related Files`, or prose; project typed boundaries instead.
59
75
 
60
76
  ### 4. Explicit Flash Finalization
61
77
 
62
- **Usage:** `/hapo:sync <feature_name> <task_id|task-file> sync-finalize`
78
+ **Usage:** `/hapo:sync <feature_name> <task_id|task-file> sync-finalize` (the adapter must call `workflow-policy.cjs --sync-finalize --task-json <current-task> --verdict PASS --proof <canonical-receipt> --json`)
63
79
 
64
- This is the only operation allowed to turn a flash-promoted task (`Verification: PASS`, `status: in_progress`, `readyForSync: true`) into `done` and unblock dependencies. A normal `done` request cannot bypass flash promotion or stale `FLASH_UNVERIFIED` state.
80
+ This is the only operation allowed to turn the current `FLASH_UNVERIFIED` task into `done` and unblock dependencies. The policy derives promotion from that current state and explicit proof; `readyForSync`, `flashTransition`, and `promotionReceipt` supplied by the caller are not proof. A normal `done` request cannot bypass flash promotion or stale `FLASH_UNVERIFIED` state.
81
+
82
+ The current state must be the exact stored form: `status: "in_progress"`,
83
+ `receipt: "FLASH_UNVERIFIED"`, `dependencyBlocked: true`, `unblocks: false`, a
84
+ concrete blocker, and no caller promotion fields. The canonical proof must be
85
+ bound by the runtime adapter with `policy.createReceiptBinding({ base, head })`
86
+ and must match both receipt anchors; arbitrary valid-length Base/Head values do
87
+ not authorize finalization.
65
88
 
66
89
  ### Flash implementation state
67
90
 
68
- Executable policy source: `.claude/scripts/workflow-policy.cjs` (source: `src/claude/scripts/workflow-policy.cjs`). Use `promoteFlashTask` only after exact task Evidence and reachability return PASS; FAIL, BLOCKED, and NO_TESTS remain blocked in progress.
91
+ Executable policy source: `.claude/scripts/workflow-policy.cjs` (source: `src/claude/scripts/workflow-policy.cjs`). Trusted sync-finalize invokes `promoteFlashTask` only after the exact task Verification Plan and reachability return PASS; test PASS itself only supplies canonical proof and leaves the persisted task blocked in progress. FAIL, BLOCKED, and NO_TESTS remain blocked in progress.
92
+
93
+ `FLASH_UNVERIFIED` is storage for implemented-but-unverified work, not a completion status. Store it as `status: "in_progress"` with `dependencyBlocked: true`, `unblocks: false`, a concrete blocker, and no promotion fields; do not unblock dependencies. `/hapo:test` may produce canonical proof, but the supported sync-finalize boundary must receive explicit `--verdict PASS` and `--proof`, require the runtime Base/Head binding, revalidate the receipt/artifact, derive the transition, and only then set `done`. FAIL, BLOCKED, NO_TESTS, marker-only proof, minimal state, and pre-promoted caller JSON remain `in_progress`.
69
94
 
70
- `FLASH_UNVERIFIED` is storage for implemented-but-unverified work, not a completion status. Store it as `status: "in_progress"` with blocker `awaiting /hapo:test <feature>`; do not unblock dependencies. `/hapo:test` may promote one task only after its exact Evidence and reachability PASS, replacing the receipt with proof, clearing blocker, and setting `readyForSync: true` while dependencies remain blocked. Only explicit `/hapo:sync ... sync-finalize` may set `done` and unblock. FAIL, BLOCKED, and NO_TESTS remain `in_progress`.
95
+ After the last task is done, sync does not synthesize proof. Test/Develop must
96
+ run final integration and create `feature-receipt.md` once. Task-bearing
97
+ completion requires all task receipts plus the feature receipt. Taskless
98
+ Compact/Full completion requires the feature receipt only; its absence before
99
+ final closeout is normal. No receipt grants or infers approval, readiness, or
100
+ audit status.
71
101
 
72
102
  ## References
73
103
  Read `references/sync-protocols.md` for exact Search/Replace regex patterns and JSON schema expectations before acting on the files.
@@ -2,23 +2,33 @@
2
2
 
3
3
  The following guidelines dictate exactly how `hapo:sync` should interact with files to prevent data corruption.
4
4
 
5
- **Flash implementation state:** `FLASH_UNVERIFIED` MUST remain `status: "in_progress"` with blocker `awaiting /hapo:test <feature>`. It never unblocks dependencies. A task-scoped `/hapo:test` PASS replaces receipt with real `Verification: PASS`, clears blocker, and sets `readyForSync: true` while dependency blocking remains. Only explicit `/hapo:sync ... sync-finalize` may set `done` and unblock; FAIL, BLOCKED, and NO_TESTS stay `in_progress`.
5
+ **Flash implementation state:** `FLASH_UNVERIFIED` MUST remain the exact stored form: `status: "in_progress"`, `dependencyBlocked: true`, `unblocks: false`, a concrete blocker, and no `readyForSync`, `flashTransition`, or `promotionReceipt` fields. It never unblocks dependencies. The supported sync-finalize adapter must pass the current task, `--verdict PASS`, and canonical `--proof` to `workflow-policy.cjs`; the policy derives promotion, requires a runtime `createReceiptBinding({ base, head })` match for both receipt anchors, revalidates receipt/artifact requirements, and rejects caller-supplied promotion fields before setting `done`. FAIL, BLOCKED, NO_TESTS, marker-only proof, minimal state, and pre-promoted caller JSON stay `in_progress`.
6
6
 
7
- **Lane state rule:** classify Direct/Standard/Critical before sync. Direct may omit spec/state/registry for clear, reversible low-risk work; Standard uses one bounded spec and one feature receipt; Critical requires strict durable evidence. Explicit overrides must retain automatic lane, risk signals, and warning. `generated`, `agent_validated`, and `user_approved` are independent booleans; never infer or write `user_approved: true` from agent fields.
7
+ **Policy state rule:** read the v2.1 policy input before sync. Direct/Standard/
8
+ Critical are derived views. Preserve `classified_minimum`, risks, and explicit
9
+ override receipt. Authoring states are only `draft`, `validated`, or `absent`;
10
+ legacy approval fields are inert.
11
+
12
+ **Authority rule:** `spec.json` is machine authority. Markdown is a projection.
13
+ Typed `coordination.boundaries` own dependency, ownership, transition, proof,
14
+ and parallel semantics; never infer them from `(P)`, `task_triggers`, `Related
15
+ Files`, or prose.
8
16
 
9
17
  ## 1. Updating `spec.json`
10
18
 
11
- * **JSON Modification Rule:** Do not output whole files. Instead, load the JSON structure, apply the update to `status`, `current_phase`, `blocker` (if any), `task_files`, and the relevant `task_registry` entry, then overwrite the file cleanly.
19
+ * **JSON Modification Rule:** Do not output whole files. Load the JSON,
20
+ update only lifecycle fields and the relevant registry entry, then write
21
+ valid JSON without changing semantic topology.
12
22
  * **Task Registry Rule:** Resolve the incoming task reference to a single relative path in `task_registry`. Accept either:
13
23
  - compact task ID like `R0-02`
14
24
  - full filename like `task-R0-02-extension-shell.md`
15
25
  - full relative path like `tasks/task-R0-02-extension-shell.md`
16
26
  * **Status Update:** If a task changes to `blocked`, the matching `task_registry[path].status` must become `"blocked"`, `task_registry[path].blocker` must record the reason, and `spec.json.status` / `spec.json.blocker` must reflect the top-level block if work is globally blocked.
17
27
  * **Timestamp Rule:** Update `task_registry[path].started_at`, `completed_at`, and `last_updated_at` consistently with the new state. Also refresh `spec.json.updated_at`.
18
- * **Done-State Rule:** Never set `task_registry[path].status = "done"` unless the matching markdown task file already contains a verification receipt in `## Evidence` (legacy heading aliases still parse), or the caller explicitly provides proof that can be written there first.
19
- * **Receipt Integrity Rule:** A valid verification receipt must include the exact commands run, their outcomes, and artifact/runtime proof. Receipts containing `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit "placeholder / simplified for MVP / production later" contract deviations are not eligible for `done`.
28
+ * **Done-State Rule:** Never set `task_registry[path].status = "done"` unless `receipts/<task-basename>.md` is valid, or a legacy `## Evidence` receipt is valid. Write proof to the separate receipt first; never add execution evidence to a new-format task plan.
29
+ * **Receipt Integrity Rule:** A valid task receipt includes task identity/path, exact commands and outcomes, expected versus observed behavior, applicable negative/reachability/artifact proof, and Base/Head binding. If separate and legacy receipts both exist with conflicting proof identity, refuse `done`. `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, placeholders, and contract substitutions are not eligible.
20
30
  * **Contract Fidelity Rule:** If the task file notes or evidence show that a named framework/auth/runtime choice from the spec was silently replaced, sync MUST refuse `done` until the spec is amended or the implementation is corrected.
21
- * **Task Docs Rule:** After a task is moved to `done`, emit a short alert that a task-level docs checkpoint is due for this verified task.
31
+ * **Task Docs Rule:** After a task is moved to `done`, assess actual documentation impact and report `Docs impact: major|minor|none`. Only affected docs receive a follow-up checkpoint.
22
32
 
23
33
  ## 2. Updating `tasks/task-**.md`
24
34
 
@@ -27,19 +37,18 @@ The structure of `tasks/task.md` relies heavily on exact keyword markers. Follow
27
37
  ### A. Completing a Task
28
38
  When `/hapo:sync <feature> <task-id> done`:
29
39
  1. Find: `**Status:** pending` (or `in_progress` / `blocked`).
30
- 2. Inspect `## Evidence` (legacy heading aliases still parse) first. If it has no explicit proof lines (commands run, artifact proof, runtime proof, or blockers cleared), STOP and refuse to mark the task done.
40
+ 2. Resolve `receipts/<task-basename>.md` first, with legacy `## Evidence` as fallback. If neither has valid proof, STOP and refuse to mark the task done.
31
41
  3. Refuse completion if the receipt contains any non-passing marker such as `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or an explicit note that the implementation substituted a named contract with a placeholder/custom simplification.
32
42
  4. Replace with: `**Status:** done`.
33
- 5. Locate block: `## Steps` or `## Implementation Steps`.
34
- 6. Convert `- [ ]` into `- [x]` strictly within that section.
35
- 7. Update relevant checkboxes in `## Completion Criteria` and `## Evidence` (legacy heading aliases still parse) only when the caller provides or the file already contains real proof.
36
- 8. Surface a note such as: `Docs checkpoint due: task Rn-mm just completed`.
43
+ 5. Update only implemented checkboxes under `## Changes`; never append receipt fields to the task plan.
44
+ 6. Surface `Docs impact: major|minor|none`; if impact is not `none`, name the affected docs and the follow-up checkpoint.
37
45
 
38
46
  ### B. Blocking a Task
39
47
  When `/hapo:sync <feature> <task-id> blocked "API error"`:
40
48
  1. Find: `**Status:** <anything>`.
41
49
  2. Replace with: `**Status:** blocked`.
42
- 3. Ensure that an entry under `## Blocker Log` exists recording the explicit reason (e.g. `API error`) and timestamp.
50
+ 3. Record the reason and timestamp in `task_registry[path].blocker`; do not add
51
+ a non-canonical task section.
43
52
 
44
53
  ### C. Starting / Resuming a Task
45
54
  When `/hapo:sync <feature> <task-id> in_progress`:
@@ -57,9 +66,18 @@ When `/hapo:sync audit <feature>` is activated:
57
66
  4. **Reconciliation Rules:**
58
67
  - Missing registry entry → create it
59
68
  - Missing disk file referenced in registry → remove or flag it
60
- - Markdown says `done` but registry not done → registry wins only if evidence already exists; otherwise downgrade markdown or flag conflict
61
- - Registry says `done` but markdown still pending → update markdown only if evidence exists
62
- - Either side says `done` but `## Evidence` (legacy heading aliases still parse) has no concrete proof → downgrade to `in_progress` or flag conflict instead of preserving fake completion
69
+ - Markdown says `done` but registry not done → registry wins only if a canonical separate or legacy receipt exists; otherwise downgrade markdown or flag conflict
70
+ - Registry says `done` but markdown still pending → update markdown only if a canonical separate or legacy receipt exists
71
+ - Either side says `done` but neither receipt source has concrete proof → downgrade to `in_progress` or flag conflict instead of preserving fake completion
72
+ - Both receipt sources exist with conflicting proof identity → fail closed and require manual reconciliation
63
73
  - Either side says `done` but the receipt contains `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit contract-substitution notes → downgrade to `in_progress` or flag conflict
64
74
  5. **Correction Alert:** Output a brief markdown alert detailing mismatches fixed and any unresolved conflicts requiring manual review.
65
- 6. **Task Docs Alert:** If audit reveals tasks newly marked `done`, include whether task-level docs sync appears still due or already accounted for in the current run summary.
75
+ 6. **Task Docs Alert:** If audit reveals tasks newly marked `done`, include the actual docs impact; do not emit a generic docs-sync request when no docs are affected.
76
+
77
+ ## 4. Feature closeout
78
+
79
+ - Before all tasks are done, missing `feature-receipt.md` is normal.
80
+ - After all tasks are done, require final integration execution and one valid
81
+ `feature-receipt.md`; never derive it from task status alone.
82
+ - A taskless Compact/Full spec uses the same final feature receipt and does not
83
+ require a synthetic registry entry.