@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.
- package/bin/__tests__/codex-hooks.test.js +794 -21
- package/bin/__tests__/codex-native.test.js +228 -7
- package/bin/__tests__/develop-contract.test.js +1838 -112
- package/bin/__tests__/installer-safety.test.js +82 -29
- package/bin/__tests__/opencode-spec-gate.test.js +799 -0
- package/bin/__tests__/package-inventory.test.js +841 -10
- package/bin/__tests__/specs-v2-execution-closeout.test.js +421 -0
- package/bin/__tests__/specs-v2-policy-and-scaffold.test.js +601 -0
- package/bin/__tests__/specs-v2-validator-grounder-contract.test.js +952 -0
- package/bin/__tests__/test-runtime-dependency-closure.cjs +182 -0
- package/bin/__tests__/validator-grounding.test.js +2469 -71
- package/bin/lib/managed-writer.js +12 -3
- package/bin/phases/codex-runtime.js +17 -1
- package/package.json +1 -1
- package/src/claude/CLAUDE.md +6 -0
- package/src/claude/agents/code-auditor.md +20 -0
- package/src/claude/agents/spec-maker.md +153 -202
- package/src/claude/hooks/__tests__/completion-authority.test.js +953 -0
- package/src/claude/hooks/__tests__/privacy-block.test.js +172 -0
- package/src/claude/hooks/__tests__/semantic-review-authority.test.js +257 -0
- package/src/claude/hooks/__tests__/spec-gate.test.js +604 -56
- package/src/claude/hooks/completion-authority-check.cjs +56 -0
- package/src/claude/hooks/completion-authority-state.cjs +527 -0
- package/src/claude/hooks/completion-authority.cjs +154 -0
- package/src/claude/hooks/docs-sync.cjs +5 -2
- package/src/claude/hooks/lib/privacy-command-analysis.cjs +393 -0
- package/src/claude/hooks/lib/runtime-path-safety.cjs +119 -0
- package/src/claude/hooks/privacy-block.cjs +77 -30
- package/src/claude/hooks/semantic-review-authority.cjs +152 -0
- package/src/claude/hooks/session.cjs +33 -19
- package/src/claude/hooks/spec-gate.cjs +181 -139
- package/src/claude/hooks/spec-state.cjs +112 -47
- package/src/claude/migration-manifest.json +15 -2
- package/src/claude/rules/state-sync.md +52 -21
- package/src/claude/rules/workflow.md +17 -9
- package/src/claude/scripts/provenance.cjs +315 -0
- package/src/claude/scripts/spec-final-state.cjs +244 -0
- package/src/claude/scripts/spec-ground.cjs +535 -173
- package/src/claude/scripts/spec-readiness.cjs +118 -0
- package/src/claude/scripts/spec-receipt.cjs +162 -0
- package/src/claude/scripts/spec-resolver.cjs +501 -0
- package/src/claude/scripts/spec-scaffold.cjs +1945 -55
- package/src/claude/scripts/spec-semantic-model.cjs +396 -0
- package/src/claude/scripts/validate-spec-output.cjs +3204 -262
- package/src/claude/scripts/workflow-policy.cjs +1888 -203
- package/src/claude/settings/settings.json +12 -0
- package/src/claude/skills/code-review/SKILL.md +94 -66
- package/src/claude/skills/code-review/references/spec-compliance-review.md +10 -2
- package/src/claude/skills/code-review/references/verification-gate.md +13 -0
- package/src/claude/skills/develop/SKILL.md +138 -283
- package/src/claude/skills/develop/references/parallel-waves.md +9 -6
- package/src/claude/skills/develop/references/quality-gate.md +123 -148
- package/src/claude/skills/develop/references/subagent-patterns.md +42 -37
- package/src/claude/skills/specs/SKILL.md +192 -397
- package/src/claude/skills/specs/references/ask-user-question-gates.md +27 -18
- package/src/claude/skills/specs/references/cross-spec-dependency.md +8 -4
- package/src/claude/skills/specs/references/research-strategy.md +4 -1
- package/src/claude/skills/specs/references/review.md +200 -260
- package/src/claude/skills/specs/references/scope-inquiry.md +18 -5
- package/src/claude/skills/specs/rules/design-discovery-full.md +33 -81
- package/src/claude/skills/specs/rules/design-discovery-light.md +21 -42
- package/src/claude/skills/specs/rules/design-principles.md +136 -180
- package/src/claude/skills/specs/rules/design-review.md +42 -97
- package/src/claude/skills/specs/rules/ears-format.md +42 -50
- package/src/claude/skills/specs/rules/phase-decision-matrix.md +42 -41
- package/src/claude/skills/specs/rules/task-scoring-rubric.md +46 -46
- package/src/claude/skills/specs/rules/tasks-generation.md +189 -271
- package/src/claude/skills/specs/templates/design.md +49 -263
- package/src/claude/skills/specs/templates/requirements.md +26 -36
- package/src/claude/skills/specs/templates/research.md +9 -98
- package/src/claude/skills/specs/templates/spec-state.json +26 -67
- package/src/claude/skills/specs/templates/task.md +30 -82
- package/src/claude/skills/sync/SKILL.md +45 -15
- package/src/claude/skills/sync/references/sync-protocols.md +34 -16
- package/src/claude/skills/test/SKILL.md +151 -167
- package/src/codex/AGENTS.md +6 -0
- package/src/codex/hooks/completion-authority-check.cjs +63 -0
- package/src/codex/hooks/completion-authority-state.cjs +527 -0
- package/src/codex/hooks/completion-authority.cjs +106 -0
- package/src/codex/hooks/lib/hook-context.cjs +58 -4
- package/src/codex/hooks/lib/privacy-command-analysis.cjs +3 -0
- package/src/codex/hooks/lib/privacy-state.cjs +38 -16
- package/src/codex/hooks/lib/runtime-path-safety.cjs +3 -0
- package/src/codex/hooks/lib/spec-receipt.cjs +86 -115
- package/src/codex/hooks/lib/spec-utils.cjs +104 -27
- package/src/codex/hooks/privacy-approval.cjs +1 -1
- package/src/codex/hooks/privacy-block.cjs +67 -11
- package/src/codex/hooks/semantic-review-authority.cjs +130 -0
- package/src/codex/hooks/session.cjs +2 -0
- package/src/codex/hooks/spec-gate.cjs +151 -24
- package/src/codex/hooks/spec-state.cjs +65 -12
- package/src/codex/hooks/state.cjs +2 -0
- package/src/codex/hooks.json +16 -1
- package/src/codex/rules/state-sync.md +47 -27
- package/src/common/AGENTS.md +1 -1
- package/src/opencode/AGENTS.md +4 -2
- package/src/opencode/plugins/spec-gate.ts +296 -122
- 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
|
-
##
|
|
4
|
+
## Outcome
|
|
40
5
|
|
|
41
|
-
|
|
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
|
-
##
|
|
8
|
+
## Scope
|
|
45
9
|
|
|
46
|
-
|
|
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
|
-
##
|
|
13
|
+
## Anchors and Ownership
|
|
52
14
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
-
|
|
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
|
-
##
|
|
21
|
+
## Changes
|
|
59
22
|
|
|
60
|
-
|
|
61
|
-
|
|
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
|
-
|
|
27
|
+
## Acceptance
|
|
64
28
|
|
|
65
|
-
|
|
66
|
-
-
|
|
67
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
35
|
+
- {{DEPENDENCIES}}
|
|
88
36
|
|
|
89
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
17
|
+
## v2.1 authority-aware synchronization
|
|
18
18
|
|
|
19
|
-
Read
|
|
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
|
|
26
|
-
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
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:**
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
|
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`).
|
|
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
|
-
|
|
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"`
|
|
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
|
-
**
|
|
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.
|
|
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
|
|
19
|
-
* **Receipt Integrity Rule:** A valid
|
|
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`,
|
|
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.
|
|
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.
|
|
34
|
-
6.
|
|
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.
|
|
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
|
|
61
|
-
- Registry says `done` but markdown still pending → update markdown only if
|
|
62
|
-
- Either side says `done` but
|
|
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
|
|
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.
|