@haposoft/cafekit 0.16.0-rc.1 → 0.16.0-rc.3

package/src/claude/skills/specs/rules/task-scoring-rubric.md

@@ -1,52 +1,51 @@
-# Task Scoring Rubric
+# Task Scoring Rubric (optional advisory)
 
-Use this rubric after applying the Phase Decision Matrix and before writing each task file. The score determines priority, split/merge, spike needs, dependency shape, and evidence depth.
+Load this rubric only when the persisted policy requires a task bundle and the
+decomposition has a real split/merge or dependency question. It is not a lane
+classifier, readiness gate, approval gate, or reason to create a task bundle.
 
-## Score Each Candidate Task
+## Candidate dimensions
 
-Score each dimension 0-3.
+Score each candidate from 0–3 only when the score will change a task decision:
 
 | Dimension | 0 | 1 | 2 | 3 |
 |---|---|---|---|---|
-| Dependency criticality | Standalone | Depends on one task | Blocks one feature slice | Blocks many tasks or core runtime |
-| Implementation risk | Routine | Known pattern, minor edge cases | Complex logic or integration | Unproven behavior, migration, security, provider/platform uncertainty |
-| Blast radius | Isolated file | Feature-local files | Shared component/API/config | Auth, data layer, routing, permissions, package export, or critical path |
-| User value | Internal cleanup | Enables later work | User-visible improvement | Core acceptance criterion or launch blocker |
-| Evidence confidence | Proven by code/tests/docs | Mostly proven | Partial evidence | Low/no evidence |
-| Testability burden | Simple unit/smoke | Component/integration | Multi-step workflow | E2E/security/performance/rollback proof required |
-| File conflict risk | No overlap | Minor shared utility | Shared module with consumers | Same files as another task or cross-agent conflict likely |
-| Scope creep risk | Fully in scope | Small interpretation | Adds adjacent behavior | Adds unapproved feature/contract |
-
-## Interpret Score
-
-| Total | Priority | Action |
-|---:|---|---|
-| 0-6 | P3 | Keep compact. Merge if no independent proof exists. |
-| 7-12 | P2 | Normal task. Include explicit dependencies and evidence. |
-| 13-18 | P1 | High attention. Consider split, stronger evidence, and validation note. |
-| 19+ | P1 critical | Split or add spike. Do not mark parallel unless file ownership is isolated. |
-
-## Mandatory Overrides
-
-- If Scope creep risk = 3, stop and use `AskUserQuestion` before generating the task.
-- If Evidence confidence = 3 and Implementation risk >= 2, create a spike task first.
-- If Blast radius = 3, include rollback/negative-path proof in `Evidence`.
-- If File conflict risk >= 2, remove `(P)` unless ownership is explicitly separated.
-- If User value = 3 and Dependency criticality >= 2, schedule early unless blocked by foundation work.
-
-## Task Metadata Decisions
-
-- `priority`: from total score plus overrides.
-- `dependencies`: list every required predecessor task file.
-- `(P)` marker: allowed only when dependency and file conflict scores are <= 1 and design boundaries do not overlap.
-- `Evidence`: choose proof type from `tasks-generation.md` Test Type Selection table; increase proof depth for high scores.
-- `Risk Assessment`: include all dimensions scored 2-3 as risks or constraints.
-
-## Compact Output
-
-Do not write the raw score table into every task file. Use the rubric to shape task content. Surface only decisions that affect implementation:
-
-- why task is P1/P2/P3
-- why it is split/merged
-- why it is or is not parallel
-- why a spike or extra proof is required
+| Dependency criticality | standalone | one predecessor | one slice blocked | core path blocked |
+| Implementation risk | routine | known pattern | complex integration | unproven/security |
+| Blast radius | isolated | feature-local | shared contract | critical boundary |
+| User value | internal | enables work | visible improvement | acceptance/launch |
+| Evidence confidence | proven | mostly proven | partial | low/no evidence |
+| Test burden | unit/smoke | component/integration | workflow | security/rollback |
+| File conflict | none | minor | shared module | overlapping ownership |
+| Scope creep | none | interpretation | adjacent behavior | unapproved contract |
+
+## Use of the result
+
+Use the result only to explain priority, split/merge, dependency order,
+parallel ownership, or proof depth. Prefer one task when one boundary and one
+proof path are enough. Split only for a real dependency, ownership boundary, or
+independent proof path.
+
+- Scope-creep score 3: stop and ask for scope approval.
+- Low evidence plus risk ≥2: consider a time-boxed spike, but do not create one
+  solely because a Cynefin label says `Complex`.
+- Blast radius 3: include rollback/negative-path proof.
+- File conflict ≥2: remove `(P)` unless ownership is isolated.
+- High value plus dependency ≥2: schedule early only after real prerequisites.
+
+Cynefin is advisory discovery language. It may suggest a spike or research
+question; it never changes Direct/Standard/Critical, adds registry/DAG
+ceremony, or decides readiness.
+
+## Compact task metadata
+
+Do not copy the raw table into task files. Record only decisions that affect
+execution:
+
+- why the task is split or merged;
+- why it is early or deferred;
+- why it is or is not parallel;
+- why a spike or deeper proof is useful;
+- exact dependencies and evidence.
+
+If no decision changes, omit scoring entirely and keep the task packet compact.

package/src/claude/skills/specs/rules/tasks-generation.md

@@ -2,16 +2,25 @@
 
 ## Core Principles
 
-### 0. Pre-Generation Decision Gates
+### 0. Conditional generation gates
+
+This file is loaded only after the persisted lane obligations say that a task
+bundle is needed. A bounded Standard scope may finish with its feature receipt
+and no `tasks/` or registry.
 
 Before writing any `tasks/task-R*.md` file:
 
-1. Load `phase-decision-matrix.md` and identify implementation slices/task clusters: R0 foundation, risk spikes, vertical slices, layer slices, cross-cutting slices, integration gates, verification gates, and release/packaging slices when in scope.
-2. Load `task-scoring-rubric.md` and score each candidate task. Use the result to choose priority, split/merge, spike needs, dependencies, parallel eligibility, and evidence depth.
-3. Load `../references/ask-user-question-gates.md` if scoring or slicing detects unapproved scope expansion, unresolved architecture tie, missing evidence, contract ambiguity, or final contradiction.
-4. Do not ask about facts that targeted scout, repo files, tests, or official/current docs can answer.
+1. Load `phase-decision-matrix.md` only if the task boundaries are unclear.
+2. Load `task-scoring-rubric.md` only if an actual split/merge, dependency, or
+   evidence-depth decision needs it. Scoring is optional and never selects a
+   lane or makes tasks mandatory.
+3. Load `../references/ask-user-question-gates.md` only for an unapproved scope
+   change, unresolved architecture choice, missing evidence, or contradiction.
+4. Use targeted scout, repository files, tests, and current primary docs for
+   facts before asking the user.
 
-The raw score table does not need to appear in each task file. The task file must reflect the decisions: why the task exists, what it depends on, why it is split/merged, whether it can be parallel, and what proof is required.
+The task file must explain only decisions that affect execution: scope,
+dependencies, ownership, proof, and any intentional split/merge.
 
 ### 1. Natural Language Descriptions
 Focus on capabilities and outcomes, not code structure.
@@ -32,7 +41,10 @@ Detail bullets must include:
    - API payloads, routes, and JSON contracts.
    - Edge cases, error handling, and exact validation thresholds (e.g., `Return 403 if invalid`).
 
-**Rationale**: Humans review tasks to verify business requirements are met; AI Coders (like implementer or ck) read tasks to write explicit code. If you only write business jargon, the AI hallucinates. If you only write code names, the human reviewer cannot verify the business value. You MUST provide both.
+**Rationale**: Humans review tasks to verify business requirements are met;
+coding agents read tasks to write explicit code. If you only write business
+jargon, the AI hallucinates. If you only write code names, the human reviewer
+cannot verify the business value. You MUST provide both.
 
 ### 2. Task Integration & Progression
 
@@ -48,8 +60,10 @@ Detail bullets must include:
 - Reuse canonical contracts from `design.md` verbatim; never invent alternate auth/provider/deletion policies in task prose
 - Use major task summaries sparingly—omit detail bullets if the work is fully captured by child tasks.
 
-**End with integration tasks** to wire everything together.
-- For UI/app/runtime workflows, the final integration task MUST name the real entrypoint (`App.tsx`, route, command, worker, extension manifest, API route, etc.) and verify every user-visible surface from the requirements is reachable from that entrypoint.
+**Add integration proof when the surface needs it**.
+- For UI/app/runtime workflows, the last task or a final integration section
+  names the real entrypoint (`App.tsx`, route, command, worker, extension
+  manifest, API route, etc.) and verifies every scoped surface is reachable.
 - Components, services, routes, commands, workers, providers, and data loaders created by earlier tasks MUST be consumed by a later integration task or explicitly marked as internal support in `design.md`; orphaned deliverables are invalid.
 - Prefer compact, implementation-ready task prose over large boilerplate. The golden shape is: `Context` -> `Steps` -> `Requirements` -> `Related Files` -> `Completion Criteria` -> `Evidence` -> `Risk Assessment`.
 - A compact task is valid when it names exact files/contracts, maps requirements, and gives executable evidence. Do not expand it into nested filler just to satisfy a template.
@@ -94,15 +108,24 @@ Some requirements (e.g., "language handling", "error handling") naturally touch
 
 Grouping tasks vertically by requirement carries the risk of "siloed" or fragmented code (e.g., each requirement building its own isolated setup). To ensure the system remains cohesive:
 
-1. **Foundation First (The R0 Concept)**: Extract shared infrastructure, core database migrations, authentication wrappers, and base UI layouts into foundational tasks running before feature work. If these aren't explicitly in requirements, classify them as `task-R0-XX-foundation.md` or map them to the most logical architectural requirement. All parallel feature tasks MUST depend on these foundation tasks.
+1. **Foundation only when real**: Add a foundation task only for a shared
+   prerequisite that has its own ownership or proof boundary. Do not invent an
+   R0 task for a small bounded change.
 2. **Shared Interfaces (Horizontal Contracts)**: Sub-tasks that touch shared cross-requirement architecture (like registering a new page in a global `router.ts` or adding a column to a shared table) MUST explicitly reference the shared contract defined in `design.md`. 
 3. **Integration Enforcers**: If R1 and R2 interact (e.g., R2 UI displays data fetched by R1 backend), the later task MUST have a sub-task explicitly dedicated to "Wiring/Integrating with [Previous Feature] output".
-4. **Final Runtime Integration**: For any feature that has a user-facing screen, public route, CLI command, background worker, browser extension surface, or API flow, create a final integration task (or a final integration section in the last dependent task) that proves the whole scoped feature works from its runtime entrypoint. This task MUST fail if prior-task outputs exist but are not imported, mounted, registered, or invoked.
-5. **Scored Sequencing**: Use `task-scoring-rubric.md` to schedule high-value/high-dependency tasks early, but only after required foundation/spike work. High file-conflict or high blast-radius tasks must not be marked `(P)` without isolated ownership.
+4. **Final Runtime Integration**: For a feature with a user-facing or
+   runtime-facing surface, include a final integration task or section only if
+   the existing task evidence does not already prove the entrypoint. It MUST
+   fail when outputs are not imported, mounted, registered, or invoked.
+5. **Advisory sequencing**: If the optional rubric was used, apply its
+   dependency/ownership notes. Never use a score to add ceremony or override
+   the persisted lane.
 
-### 3d. Spike Tasks for Complex/Uncertain Areas (MANDATORY)
+### 3d. Spike tasks for unresolved uncertainty (ADVISORY)
 
-When the 5-Dimension Complexity Assessment (Step 3) flags a component or requirement as **Risk = Complex** (Cynefin), the task breakdown MUST include a dedicated **spike/prototype task** before the main implementation task for that area.
+When the assessment flags an unproven assumption, a time-boxed spike may be
+useful before implementation. A Cynefin `Complex` label alone does not mandate
+one, change the lane, or create a registry/DAG.
 
 **Purpose**: Validate assumptions and reduce uncertainty before committing to full implementation.
 
@@ -117,8 +140,9 @@ When the 5-Dimension Complexity Assessment (Step 3) flags a component or require
 5. **Dependencies**: The main implementation task for this area MUST depend on the spike task.
 
 **When NOT to create spike tasks:**
-- Risk = Clear or Complicated → skip spike, proceed directly.
-- The uncertain area is already covered by research.md with concrete evidence (real API tests, not just documentation links).
+- the assumption is already grounded by targeted evidence or required research;
+- the change is clear enough for a direct implementation/proof path;
+- the spike would add ceremony without reducing a concrete uncertainty.
 
 ### 6. Risk Assessment Table (MANDATORY)
 
@@ -190,7 +214,9 @@ Choose verification by task risk and touched surface. Do not force every task to
 | Bug fix/regression | Regression test reproducing the old failure, then passing |
 | Performance/security-sensitive requirement or touched surface | Performance/security check only when specified by requirements, design risk, or changed boundary |
 
-`hapo:specs` writes the expected proof into each task. `hapo:develop` executes the task-local proof before marking the task done. `hapo:test` runs the broader system pass after implementation or for a requested feature scope.
+`hapo:specs` writes the expected proof into each task. `hapo:test` is the sole
+execution-proof owner and emits the canonical receipt. `hapo:develop` consumes
+that proof at closeout; it does not create a second execution receipt.
 
 ### Frontend Fidelity Rule (when a visual reference is provided)
 
@@ -260,12 +286,15 @@ Reuse vs new component:
 
 ## Requirements Coverage
 
-**Mandatory Check**:
-- ALL requirements from requirements.md MUST be covered
+**Check when a task bundle exists**:
+- ALL requirements assigned to the task bundle MUST be covered
 - Cross-reference every requirement ID with task mappings
 - If gaps found: Return to requirements or design phase
 - No requirement should be left without corresponding tasks
 
-Use the requirement ID style already present in `requirements.md` (`R1`, `REQ-01`, or `N.M`). The task filename cluster (`task-R1-01-*`) does not have to mirror every requirement ID exactly, but every requirement MUST be listed in at least one task's `## Requirements` section.
+Use the requirement ID style already present in `requirements.md` (`R1`,
+`REQ-01`, or `N.M`). The task filename cluster (`task-R1-01-*`) does not have
+to mirror every requirement ID exactly, but every requirement represented by
+the bundle MUST be listed in at least one task's `## Requirements` section.
 
 Document any intentionally deferred requirements with rationale.

package/src/claude/skills/specs/templates/spec-state.json

@@ -64,7 +64,6 @@
   "design_context": {
     "discovery_mode": null,
     "discovery_reason": null,
-    "execution_tier": "standard",
     "validation_recommended": false
   },
   "validation": {
@@ -81,5 +80,27 @@
     "sync": "always",
     "last_synced_at": null
   },
-  "ready_for_implementation": false
+  "ready_for_implementation": false,
+  "workflow_policy": {
+    "version": "1",
+    "lane": "Standard",
+    "automatic_lane": "Standard",
+    "risks": [],
+    "artifact_profile": "bounded",
+    "proof_obligations": [
+      "needsInspection",
+      "needsExecutionProof"
+    ],
+    "actor_needs": [
+      {
+        "capability": "inspection",
+        "independence": "same-session"
+      },
+      {
+        "capability": "execution-proof",
+        "independence": "same-session"
+      }
+    ],
+    "override_receipt": null
+  }
 }

package/src/claude/skills/specs/templates/task.md

@@ -7,6 +7,13 @@
 **Dependencies:** {{DEPENDENCIES}}
 **Spec:** specs/{{FEATURE_NAME}}/
 
+The owning `spec.json.workflow_policy` snapshot is authoritative for this task.
+`needsInspection` and `needsExecutionProof` are separate capabilities; Standard
+requires both, while Direct requires execution proof. Do not encode an agent
+chain in this task. The canonical verdicts are `PASS`, `PASS_WITH_WARNINGS`,
+`FAIL`, and `BLOCKED`. Legacy diagnostic inputs `PARTIAL` and `NO_TESTS` are
+normalized to unfinished `BLOCKED`; they are not canonical verdicts.
+
 ## Context
 
 - **Why**: {{Business/user reason this task exists}}
@@ -48,12 +55,22 @@
 | `{{FILE_PATH_1}}` | Create / Modify / Delete | {{DESCRIPTION_1}} |
 | `{{FILE_PATH_2}}` | Create / Modify / Delete | {{DESCRIPTION_2}} |
 
+### Optional artifact declaration
+
+If this task produces a hashable compiled or generated output, the producer MUST add
+`task_registry[path].artifacts` as a non-empty JSON array of safe relative path
+strings. Omit the field when the task has no such artifact. A `Related Files`
+row (`Create`, `Modify`, `Delete`, or `Read`) is not an artifact declaration by
+itself. The receipt must declare each artifact path with its own `SHA-256:` value
+containing exactly 64 hexadecimal characters.
+
 ## Completion Criteria
 
 - [ ] {{Criteria 1 — observable output or artifact, maps to acceptance criteria R{{REQ_NUMBER}}}}
 - [ ] {{Criteria 2 — measurable behavior or negative-path outcome}}
 - [ ] {{Criteria 3 — maps directly to acceptance criteria from requirements.md and can be proven below}}
 - [ ] {{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}}
+- [ ] Completion decision is canonical: only literal `PASS` may complete after a canonical execution receipt bound to the runtime's expected Base/Head pair and every `workflow_policy.proof_obligations` proof; `PASS_WITH_WARNINGS` stays unfinished, `FAIL` needs fix-and-rerun, and `BLOCKED` plus legacy diagnostics record the blocker or missing proof.
 
 ## Evidence
 
@@ -61,6 +78,8 @@ This section is both the task-level test plan and the proof checklist. Keep it s
 Select the proof by task risk; do not run every test type for every task.
 
 Verification: PENDING
+Canonical verdict: PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED
+Legacy diagnostic input: PARTIAL | NO_TESTS -> unfinished BLOCKED
 
 - Logic/data/validator task: include unit tests.
 - Stateful UI/component task: include component or integration tests.
@@ -74,6 +93,7 @@ Verification: PENDING
 - [ ] Automated verification (unit/component/integration/E2E as applicable)
   - Command(s): `{{TYPECHECK / TEST / BUILD COMMANDS OR N/A}}`
   - Expected proof: {{What output, exit code, or report proves success}}
+  - Runtime binding: `policy.createReceiptBinding({ base, head })` must be supplied to completion/flash adapters; a valid-length receipt pair without expected binding is not proof of identity.
 - [ ] Artifact / runtime verification
   - Inspect: `{{artifact path | route | UI state | DB object | manifest entry}}`
   - Expect: {{Observable result that proves the task is really wired}}

package/src/claude/skills/sync/SKILL.md

@@ -23,8 +23,8 @@ node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON
 ```
 
 - Direct may have no spec/state/registry; sync only concrete targeted evidence and never invents approval state.
-- Standard stores one bounded spec and one canonical feature receipt; one combined `code-auditor` review gates feature closeout.
-- Critical requires strict durable evidence and `inspector → implementer → test-runner → code-auditor` delegation by default.
+- Standard stores one bounded spec and one canonical feature receipt; a combined closeout review is required only when the persisted policy says an independent audit is needed.
+- 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.
 - `generated`, `agent_validated`, and `user_approved` are independent. Missing `user_approved` stays false; sync never auto-approves user-owned state.
 - Explicit lane overrides must preserve automatic classification and warning in receipt/state output, especially Critical downgrades.
 
@@ -54,20 +54,27 @@ Scans the `spec.json` against all physical `task-R*.md` files to detect mismatch
 2. **Machine + Human Sync:** Every task status update MUST modify both `spec.json.task_registry[...]` and the matching markdown task file header/status section.
 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).
 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`.
-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.
-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.
+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`.
+6. **Phase Prompt Rule:** When the final pending task becomes `done`, a phase-advance prompt may mention documentation only when the impact assessment found affected docs; otherwise continue without a docs ceremony.
 
 ### 4. Explicit Flash Finalization
 
-**Usage:** `/hapo:sync <feature_name> <task_id|task-file> sync-finalize`
+**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`)
 
-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.
+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.
+
+The current state must be the exact stored form: `status: "in_progress"`,
+`receipt: "FLASH_UNVERIFIED"`, `dependencyBlocked: true`, `unblocks: false`, a
+concrete blocker, and no caller promotion fields. The canonical proof must be
+bound by the runtime adapter with `policy.createReceiptBinding({ base, head })`
+and must match both receipt anchors; arbitrary valid-length Base/Head values do
+not authorize finalization.
 
 ### Flash implementation state
 
-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.
+Executable policy source: `.claude/scripts/workflow-policy.cjs` (source: `src/claude/scripts/workflow-policy.cjs`). Trusted sync-finalize invokes `promoteFlashTask` only after exact task Evidence 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.
 
-`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`.
+`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`.
 
 ## References
 Read `references/sync-protocols.md` for exact Search/Replace regex patterns and JSON schema expectations before acting on the files.

package/src/claude/skills/sync/references/sync-protocols.md

@@ -2,7 +2,7 @@
 
 The following guidelines dictate exactly how `hapo:sync` should interact with files to prevent data corruption.
 
-**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`.
+**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`.
 
 **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.
 
@@ -18,7 +18,7 @@ The following guidelines dictate exactly how `hapo:sync` should interact with fi
 *   **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.
 *   **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`.
 *   **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.
-*   **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.
+*   **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.
 
 ## 2. Updating `tasks/task-**.md`
 
@@ -33,7 +33,7 @@ When `/hapo:sync <feature> <task-id> done`:
 5. Locate block: `## Steps` or `## Implementation Steps`.
 6. Convert `- [ ]` into `- [x]` strictly within that section.
 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.
-8. Surface a note such as: `Docs checkpoint due: task Rn-mm just completed`.
+8. Surface `Docs impact: major|minor|none`; if impact is not `none`, name the affected docs and the follow-up checkpoint.
 
 ### B. Blocking a Task
 When `/hapo:sync <feature> <task-id> blocked "API error"`:
@@ -62,4 +62,4 @@ When `/hapo:sync audit <feature>` is activated:
    - 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
    - Either side says `done` but the receipt contains `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or explicit contract-substitution notes → downgrade to `in_progress` or flag conflict
 5. **Correction Alert:** Output a brief markdown alert detailing mismatches fixed and any unresolved conflicts requiring manual review.
-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.
+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.