coding-agent-harness 1.0.2 → 1.0.5

package/templates/planning/lesson_candidates.md

@@ -1,6 +1,6 @@
 # {{TASK_TITLE}} - Lesson Candidates
 
-This file is the task-local lesson candidate queue. It is not the Lessons SSoT. Human review decides whether any candidate should move into governance promotion.
+This file is the task-local lesson candidate queue. Human review decides whether any candidate should stay task-local, be rejected, enter dry-run promotion, become a promoted lesson detail doc, or become a separate sedimentation task.
 
 ## Candidate Status
 
@@ -24,14 +24,14 @@ Allowed task-level status:
 - `pending-review`: candidate file exists, but human decision is not complete.
 - `no-candidate-accepted`: human accepted the agent's no-candidate reason.
 - `needs-promotion`: at least one candidate is queued for governance promotion.
-- `promoted`: all accepted candidates were promoted to Lessons SSoT.
+- `promoted`: all accepted candidates were promoted to the agreed governance target.
 - `rejected`: all candidates were rejected or archived with reasons.
 
 Allowed row status:
 
 - `ready-for-review`: agent believes this candidate may matter.
-- `needs-promotion`: human marked the candidate worth preserving.
-- `promoted`: maintenance CLI promoted the candidate to Lessons SSoT.
+- `needs-promotion`: human marked the candidate worth preserving through dry-run promotion or a follow-up sedimentation task.
+- `promoted`: maintenance CLI or an approved follow-up task promoted the candidate to the agreed governance target.
 - `rejected`: human rejected the candidate with a reason.
 
 Aggregation rule:
@@ -44,8 +44,8 @@ Aggregation rule:
 
 ## Candidates
 
-| ID | Row Status | Title | Why It Might Matter | Review Decision | Promotion Target |
-| --- | --- | --- | --- | --- | --- |
+| ID | Row Status | Title | Scope | Module Key | Detail Artifact | Boundary Reason | Why It Might Matter | Review Decision | Promotion Target | Conflict Check | Required Standard Update | Follow-up Task |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 
 ## No-Candidate Reason
 
@@ -54,5 +54,17 @@ Not decided yet. Fill this only when review accepts that the task produced no re
 ## Promotion Notes
 
 - If human review decides a candidate is worth preserving, mark the row `needs-promotion` and record the target governance location.
+- If a candidate is marked `needs-promotion`, write the full task-local detail artifact while the source task context is fresh, then link it in `Detail Artifact`.
+- Use `Scope` values `task`, `module`, or `global`; module-scoped candidates must fill `Module Key`.
 - If human review rejects a candidate, mark the row `rejected` and keep the reason in the review decision.
 - `needs-promotion` does not block task closeout, but it must remain visible in the maintenance queue and closeout record.
+- Default promotion behavior is dry-run or follow-up-task first. Do not write a shared Lessons table; accepted candidates become promoted lesson detail docs.
+- A sedimentation task must classify scope, check conflicts against existing lessons and standards, propose the target change, and report verification before applying.
+
+## Queue Routing
+
+| Queue | When this task enters it | Exit condition |
+| --- | --- | --- |
+| Lessons | Any candidate is `ready-for-review` or `needs-promotion`. | Human rejects it, keeps it task-local, creates a sedimentation task, or approves promotion. |
+| Missing Materials | The file is absent, has invalid status, or lacks a required no-candidate reason. | Agent repairs the candidate file. |
+| Confirmed / Finalized | Human review is confirmed but a candidate still has deferred governance work. | Follow-up task or dry-run decision is recorded. |

package/templates/planning/module_session_prompt.md

@@ -34,6 +34,7 @@ Do not edit shared SSoT files, coordinator-owned integration files, or unrelated
 
 - Keep `task.state`, `lifecycleState`, `reviewStatus`, and `closeoutStatus` separate when reporting progress.
 - `done` means the implementation step finished. It is not `closed` until closeout evidence is recorded.
+- Use the current task `visual_map.md` phase table as the lifecycle map. At the end of a slice, inspect the current gate phase and follow its `Exit Command` only when its `Actor` is `agent`.
 - If review is required, update `review.md`. Human review completion must be confirmed through the local dashboard workbench or by the coordinator with `harness review-confirm`; do not mark it complete while open P0/P1/P2 findings remain.
 
 ## Shared Sync Rule

package/templates/planning/optional/artifacts/INDEX.md

@@ -2,9 +2,9 @@
 
 Use this index for generated outputs that support the task but are not the source of truth.
 
-| Artifact | Purpose | Generated By | Keep? |
-| --- | --- | --- | --- |
-| [file] | [why it exists] | [command, tool, or agent] | yes / no |
+| ID | Type | Path | Summary | Produced By |
+| --- | --- | --- | --- | --- |
+| [artifact-id] | command / diff / fixture / screenshot / review / report | TARGET:path or URL:https://example.com | [why it exists] | coordinator |
 
 ## Retention Notes
 

package/templates/planning/optional/references/INDEX.md

@@ -2,9 +2,9 @@
 
 Use this index for sources the task depends on but does not own.
 
-| Reference | Type | Why It Matters | Source |
-| --- | --- | --- | --- |
-| [name] | doc / link / transcript / code | [why this source is relevant] | [path or URL] |
+| ID | Type | Path | Summary | Used By |
+| --- | --- | --- | --- | --- |
+| [reference-id] | doc / link / transcript / code | TARGET:path or URL:https://example.com | [why this source is relevant] | coordinator |
 
 ## Source Rules
 

package/templates/planning/review.md

@@ -13,6 +13,36 @@
 - Out of scope: [explicit exclusions]
 - Source materials: [task plan, diff, test output, runtime evidence]
 
+## Agent Review Submission
+
+This section is written by the agent or coordinator when the review packet is ready.
+It is not human approval.
+
+| Field | Value |
+| --- | --- |
+| Submission ID | [generated by task-review] |
+| Submitted At | [timestamp] |
+| Submitted By | [agent or coordinator identity] |
+| Task Key | {{TASK_ID}} |
+| Materials Checklist Hash | [generated by task-review; informational, not a manual gate] |
+| Evidence Summary | [tests, diff, runtime, and review packet evidence] |
+| Open Findings Count | [number] |
+| Scanner Version | [generated scanner version] |
+
+### Material Checklist
+
+| Material | Required? | Status | Evidence |
+| --- | --- | --- | --- |
+| Brief | yes / no | present / missing / incomplete | [path or reason] |
+| Task plan | yes / no | present / missing / incomplete | [path or reason] |
+| Progress and evidence | yes / no | present / missing / incomplete | [path or reason] |
+| Visual map | yes / no | present / missing / incomplete | [path or reason] |
+| Lesson candidate decision | yes / no | present / missing / incomplete | [path or reason] |
+| Walkthrough or closeout link | yes / no | present / missing / incomplete | [path or reason] |
+
+The scanner derives `materialsReady` from required files, sections, evidence, and this strict submission block. If materials are not ready, route the task to Missing Materials instead of Human Review Confirmation.
+If there are open P0/P1/P2 blocking findings, route the task to Blocked instead of Human Review Confirmation.
+
 ## Confidence Challenge
 
 Answer directly: do you have 100% confidence in the plan, implementation, and strategy?
@@ -43,6 +73,17 @@ Do not keep sample findings. If there are no material findings, leave only the h
 | --- | --- | --- | --- |
 | [risk] | [owner] | yes / no | [path or next action] |
 
+## Lifecycle Queue Routing
+
+| Queue | Applies? | Reason | Exit condition |
+| --- | --- | --- | --- |
+| Review | yes / no | Submitted review packet is ready for human confirmation. | Human confirms or returns it. |
+| Missing Materials | yes / no | Required file, section, evidence, or review submission is absent/incomplete. | Agent repairs materials and resubmits review. |
+| Blocked | yes / no | Open blocking finding, invalid state transition, failed audit, or human waiver needed. | Blocker is fixed, closed, or explicitly waived. |
+| Lessons | yes / no | Lesson candidate needs rejection, task-local retention, dry-run promotion, or a sedimentation task. | Human decides candidate routing; promotion remains a separate maintenance task unless explicitly approved. |
+| Confirmed / Finalized | yes / no | Human confirmation exists; closeout or governance work may still be pending. | Closeout, ledger, and lesson routing are complete. |
+| Soft-deleted / Superseded | yes / no | Task has tombstone, superseded-by, archive, duplicate, or abandoned status. | Reopen or keep as read-only audit history. |
+
 ## Final Confidence Basis
 
 [Explain the final confidence basis after fixes and verification. If confidence is limited, name the remaining limits and who owns them.]

package/templates/planning/task_plan.md

@@ -1,6 +1,7 @@
 # [Task Name]
 
 Task Contract: harness-task/v1
+Task Package Index: required
 
 ## Goal
 
@@ -11,34 +12,18 @@ Task Contract: harness-task/v1
 - In scope: [specific files, modules, behavior, or docs]
 - Out of scope: [explicit exclusions]
 
-## Task Budget
-
-| Budget | Use When | Required Structure |
-| --- | --- | --- |
-| simple | One owner, no subagent, L0/L1 evidence, no formal review gate | `brief.md`, `task_plan.md`, `visual_map.md`, `progress.md` |
-| standard | Normal feature, fix, or documentation change | Plan, strategy, roadmap, progress, findings, and review as needed |
-| complex | Multi-hour work, L2/L3 evidence, subagent/reviewer, or optional artifact/reference indexes | Standard files plus optional structures as needed |
+## Selected Budget
 
 Selected budget: {{TASK_BUDGET}}
 
+Rationale: [why this budget fits this task]
+
 ## Context Packet
 
 | ID | Type | Path | Why It Matters | Used By |
 | --- | --- | --- | --- | --- |
 | C-001 | public-doc / private-plan / external / code | PUBLIC:path or PRIVATE:path or TARGET:path or URL:https://example.com | [why this source matters] | coordinator / reviewer / worker |
 
-## Required Files
-
-| Contract File | Required | Purpose |
-| --- | --- | --- |
-| `execution_strategy.md` | yes | Operating model, allocation, conflict control, and evidence strategy |
-| `visual_map.md` | yes | Diagram collection: phase map, optional architecture/sequence/data-flow/state diagrams, completion state, evidence state, and blocking risk |
-| `progress.md` | yes | Execution log, decisions, and handoff |
-| `findings.md` | yes | Findings, research notes, and unresolved risks |
-| `lesson_candidates.md` | yes for standard/complex | Task-local lesson candidate queue. Human review must accept no-candidate, reject candidates, or queue promotion before review confirmation |
-| `review.md` | if needed | Adversarial or specialist review report |
-| `long-running-task-contract.md` | if needed | Continuous execution permission, loop rules, and stop conditions |
-
 ## Steps
 
 1. [First concrete step]
@@ -75,10 +60,9 @@ Selected budget: {{TASK_BUDGET}}
 
 ## Links
 
-- Feature SSoT entry: [reference]
 - Related Regression Gate: [reference]
 - Review Report: [path / n/a]
-- Harness Ledger entry: [complete at closeout]
+- Generated Ledger: rebuilt by lifecycle CLI / `harness governance rebuild`
 - Prerequisite tasks: [reference or none]
 
 ## Coordinator Handoff

package/templates/planning/visual_map.md

@@ -15,22 +15,26 @@ Include only diagrams that materially help a human or agent understand the task.
 
 ```mermaid
 flowchart LR
-  PH01["PH-01 Plan"] --> PH02["PH-02 Implement"]
-  PH02 --> PH03["PH-03 Verify"]
-  PH03 --> PH04["PH-04 Review and Closeout"]
+  INIT01["INIT-01 Scope and Context\nkind=init"] --> EXEC01["EXEC-01 Implementation Slice\nkind=execution"]
+  EXEC01 --> GATE01["GATE-01 Agent Review Submission\nkind=gate"]
+  GATE01 --> GATE02["GATE-02 Human Review Confirmation\nkind=gate"]
 ```
 
 ## Phase Table
 
-| Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
-| --- | --- | --- | ---: | --- | --- | --- | --- | --- |
-| PH-01 | none | planned | 0 | Approved task plan and execution strategy | `task_plan.md`, `execution_strategy.md` | missing | none | coordinator |
-| PH-02 | PH-01 | planned | 0 | Scoped implementation or document update | diff, worker handoff, or artifact path | missing | [risk] | [owner] |
-| PH-03 | PH-02 | planned | 0 | Verification evidence | commands, logs, screenshots, or runtime proof | missing | [risk] | [owner] |
-| PH-04 | PH-03 | planned | 0 | Review disposition and closeout updates | `review.md`, progress update, ledger updates | missing | [risk] | coordinator |
+| Phase ID | Kind | Depends On | State | Completion | Output | Required Evidence | Exit Command | Actor | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| INIT-01 | init | none | planned | 0 | Approved task plan and execution strategy | `task_plan.md`, `execution_strategy.md` | `harness task-start {{TASK_ID}}` | agent | missing | none | coordinator |
+| EXEC-01 | execution | INIT-01 | planned | 0 | Scoped implementation, document update, and verification evidence | diff, commands, worker handoff, or artifact path | `harness task-phase {{TASK_ID}} EXEC-01 --state done --completion 100 --evidence present` | agent | missing | [risk] | [owner] |
+| GATE-01 | gate | EXEC-01 | planned | 0 | Agent Review Submission | `review.md`, progress update, lesson routing | `harness task-review {{TASK_ID}} --message "<summary>"` | agent | missing | [risk] | coordinator |
+| GATE-02 | gate | GATE-01 | planned | 0 | Human Review Confirmation | review packet and human confirmation | `harness review-confirm {{TASK_ID}} --confirm {{TASK_ID}}` | human | missing | agent must not perform human confirmation | human |
 
+Allowed Kind: init, execution, gate.
+Allowed Actor: agent, human, coordinator.
 Allowed Evidence Status: missing, partial, present, waived.
 
+Dashboard implementation completion is computed from non-skipped `execution` phases only. `init` and `gate` phases route lifecycle readiness and next actions; they must not make implementation progress look incomplete.
+
 ## Supporting Maps
 
 Add optional diagrams only when useful:

package/templates/planning/visual_map.simple.md

@@ -0,0 +1,52 @@
+# [Task Name] - Visual Map
+
+Visual Map Contract: v1.0
+
+This file is the task's diagram collection. It is not only a phase roadmap.
+Include only diagrams that materially help a human or agent understand the task.
+
+## Map Index
+
+| ID | Type | Purpose | Required For Understanding | Source Evidence | Promotion Candidate |
+| --- | --- | --- | --- | --- | --- |
+| MAP-01 | phase | Show the execution phases and dependencies | yes | `task_plan.md` | no |
+
+## Phase Graph
+
+```mermaid
+flowchart LR
+  INIT01["INIT-01 Scope and Context\nkind=init"] --> EXEC01["EXEC-01 Implementation Slice\nkind=execution"]
+  EXEC01 --> GATE01["GATE-01 Direct Completion\nkind=gate"]
+```
+
+## Phase Table
+
+| Phase ID | Kind | Depends On | State | Completion | Output | Required Evidence | Exit Command | Actor | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| INIT-01 | init | none | planned | 0 | Task scope is clear enough to execute | `task_plan.md` | `harness task-start {{TASK_ID}}` | agent | missing | none | coordinator |
+| EXEC-01 | execution | INIT-01 | planned | 0 | Simple implementation or documentation change is complete | diff, command, or artifact path | `harness task-phase {{TASK_ID}} EXEC-01 --state done --completion 100 --evidence present` | agent | missing | [risk] | [owner] |
+| GATE-01 | gate | EXEC-01 | planned | 0 | Direct task completion | progress update and final evidence note | `harness task-complete {{TASK_ID}} --message "<summary>"` | agent | missing | [risk] | coordinator |
+
+Allowed Kind: init, execution, gate.
+Allowed Actor: agent, human, coordinator.
+Allowed Evidence Status: missing, partial, present, waived.
+
+Dashboard implementation completion is computed from non-skipped `execution` phases only. `init` and `gate` phases route lifecycle readiness and next actions; they must not make implementation progress look incomplete.
+
+## Supporting Maps
+
+Add optional diagrams only when useful:
+
+- architecture: module, component, or service structure.
+- sequence: frontend/backend/service/database/agent interaction.
+- data-flow: data movement and ownership.
+- state: state machine or lifecycle.
+- topology: repo, service, worker, or worktree layout.
+- decision: branch and tradeoff tree.
+
+## Map Notes
+
+- Use `missing` when no evidence has been checked.
+- Use `partial` when some evidence exists but required checks remain.
+- Use `present` when the phase has sufficient evidence for its current claim.
+- Use `waived` only when the reason and owner are recorded in `progress.md`.

package/templates/reference/execution-workflow-standard.md

@@ -12,16 +12,44 @@ Define the standard lifecycle for non-trivial work from intake through planning,
 4. Implement in small reviewable slices and keep the plan current when scope changes.
 5. Run checks that match the risk surface before claiming completion.
 6. Route material findings through review and do not bury unresolved issues in summaries.
-7. Proactively commit each verified, meaningful slice. A completed slice should not remain only as unstaged or staged working-tree state unless the user explicitly asked to defer commits or a documented blocker prevents a clean commit.
-8. Close the loop by updating walkthrough, SSoT, regression, ledger, or docs artifacts when the work changes durable project knowledge. New non-simple tasks should keep `lesson_candidates.md` reviewable before human review confirmation.
+7. Proactively commit each verified, meaningful slice. A completed slice should not remain only as unstaged or staged working-tree state unless the user explicitly asked to defer commits, checks failed, dirty ownership is unclear, or a documented blocker prevents a clean commit. Deferred commits require a no-commit reason, owner, and next step.
+8. Use CLI lifecycle commands for mechanical Harness writes whenever available. CLI-owned writes use locked, allowlisted auto-commit. `new-task` may preserve unrelated dirty files while committing only its own write scope; overlapping dirty paths or unrelated staged files still block the command. Other lifecycle commands may still require a clean tree. Agent-owned manual edits still need an explicit task commit or deferred-commit rationale.
+9. Treat `visual_map.md` as the lifecycle phase map. `init` phases prepare work, `execution` phases define implementation completion, and `gate` phases define review, human confirmation, lesson routing, and closeout. Follow a phase `Exit Command` only when its `Actor` matches the current operator; agents must not perform `human` gates.
+10. New task directories must carry machine-readable Task Audit Metadata in `INDEX.md`. The normal path is `Created By: harness new-task`; manual creation is allowed only as `manual-exception` with a concrete reason, and historical migration must use `historical-backfill`.
+11. Close the loop by updating walkthrough, SSoT, regression, ledger, or docs artifacts when the work changes durable project knowledge. New non-simple tasks should keep `lesson_candidates.md` reviewable before human review confirmation.
+
+## Task Package Structure
+
+Use `harness new-task` instead of hand-copying task files. The CLI creates the selected budget file set and records task audit metadata in `INDEX.md` so `harness check` can validate it.
+
+| Budget | Required Files |
+| --- | --- |
+| simple | `INDEX.md`, `brief.md`, `task_plan.md`, `visual_map.md`, `progress.md` |
+| standard | simple files plus `execution_strategy.md`, `findings.md`, `lesson_candidates.md`, `review.md` |
+| complex | standard files plus `references/INDEX.md`, `artifacts/INDEX.md` |
+| long-running add-on | `long-running-task-contract.md` when `--long-running` is selected |
+
+`INDEX.md` is the task package navigation page and audit metadata SSoT. It points to contract files and optional indexes but does not replace them.
+
+Optional directories are created only when triggered:
+
+- `references/INDEX.md`: task-local sources, external links, reviewer input packages, and preset-provided required reads.
+- `artifacts/INDEX.md`: command output, screenshots, fixtures, generated reports, reviews, and other evidence.
+- `lessons/LC-*.md`: task-local lesson detail artifacts for candidates marked `needs-promotion`.
+- `slices/<slice-id>/`: multi-slice task material, when a task explicitly uses slice packets.
+
+Preset packages must not add or replace root-level base scaffold documents. Presets may append controlled sections to fixed base documents or add isolated resources under `references/**` and `artifacts/**`. Resource rows belong only in `references/INDEX.md` and `artifacts/INDEX.md`; the root `INDEX.md` may show only system-rendered preset summary fields.
 
 ## Required Checklist
 
 - Goal, scope, acceptance criteria, and constraints are written down.
+- Task Audit Metadata is present in `INDEX.md`, or the manual/historical exception reason is explicit.
+- The task package `INDEX.md` is present for new generated tasks.
 - Current repo state and ownership boundaries were checked.
 - Implementation notes identify changed surfaces.
 - Required checks and evidence are captured.
-- Verified slices have commit SHAs, or the reason for deferring commit is written down.
+- Verified slices have commit SHAs, or the no-commit reason, owner, and next step are written down.
+- The current lifecycle gate in `visual_map.md` has either been executed or has a recorded blocker.
 - Review status and material findings are recorded.
 - Residuals are explicit and assigned.
 - Closeout artifacts are updated when required.

package/templates/reference/pull-request-standard.md

@@ -0,0 +1,80 @@
+# Pull Request Standard
+
+## Purpose
+
+Every non-trivial PR must be reviewable without reading the full agent
+conversation. The PR body is a handoff packet for maintainers: what changed,
+why it changed, how it was verified, which version is affected, and what risks
+remain.
+
+## Required Shape
+
+The PR body must include:
+
+1. Summary
+2. What Changed
+3. Version Impact
+4. Verification
+5. Review Evidence
+6. Residual Risk
+7. References
+
+Use a bilingual PR body when the repository has Chinese and English users or
+the task discussion is Chinese. English comes first for public GitHub readers,
+then the localized section follows after the English section.
+
+## Content Rules
+
+- State the target version explicitly. If `package.json` changes from `1.0.3`
+  to `1.0.4`, say so in Version Impact.
+- List changed surfaces by user-visible area or module, not by dumping every
+  file path.
+- Verification must name the real commands, browser checks, CI runs, or
+  evidence artifacts. If a check was not run, say why.
+- Review Evidence must mention self-review, subagent review, human review, or
+  code-quality review status. Release-blocking findings must be closed or
+  routed before merge.
+- Residual Risk must distinguish accepted risk, deferred follow-up, and
+  unrelated local/private debt.
+- References must link relevant task docs, SSoT rows, review files, commits,
+  issues, or PRs.
+
+## Template
+
+```markdown
+## Summary
+
+[One or two sentences explaining the intent and outcome.]
+
+## What Changed
+
+- [User-facing or module-level change.]
+- [Governance, CLI, dashboard, docs, or template change.]
+
+## Version Impact
+
+- Package version: `[old]` -> `[new]`
+- Release notes: [CHANGELOG entry or reason no release note is needed]
+
+## Verification
+
+- `[command]`: pass
+- `[browser/runtime/CI evidence]`: pass
+- Not run: [reason]
+
+## Review Evidence
+
+- Self-review: [summary]
+- Additional review: [reviewer/subagent/human result]
+- Blocking findings: [none / closed / routed]
+
+## Residual Risk
+
+- [none / accepted / deferred / unrelated debt]
+
+## References
+
+- Task: [path or issue]
+- Review: [path or PR review]
+- Evidence: [path, commit, screenshot, workflow, or dashboard]
+```

package/templates/reference/repo-governance-standard.md

@@ -10,10 +10,11 @@ Define repository-level rules for branches, commits, pull requests, ownership, g
 2. Use task-scoped branches and worktrees for non-trivial changes, especially when multiple workers are active.
 3. Keep commits focused on the requested scope and avoid mixing unrelated cleanup with feature work.
 4. Generated files, caches, build output, local runtime state, and secrets must be ignored or stored in the approved location.
-5. Commit verified, meaningful slices proactively. Deferred commits require an explicit reason and owner.
-6. Pull requests must describe intent, changed surfaces, checks run, checks not run, review status, and residual risk.
-7. Required checks and material review findings block merge unless an approved exception is recorded.
-8. Merge or release ownership must be explicit when several branches or workers contribute to the same outcome.
+5. Commit verified, meaningful slices proactively. Deferred commits require an explicit no-commit reason, owner, and next step.
+6. Do not mix unrelated dirty changes into a task commit. CLI-owned Harness writes should use the local Harness commands so their locked, allowlisted auto-commit can protect shared governance files.
+7. Pull requests must follow `docs/11-REFERENCE/pull-request-standard.md` and describe intent, changed surfaces, version impact, checks run, checks not run, review status, references, and residual risk.
+8. Required checks and material review findings block merge unless an approved exception is recorded.
+9. Merge or release ownership must be explicit when several branches or workers contribute to the same outcome.
 
 ## Required Checklist
 
@@ -21,8 +22,8 @@ Define repository-level rules for branches, commits, pull requests, ownership, g
 - Allowed and forbidden paths are respected.
 - Dirty worktree state was checked before edits.
 - Generated and private files are not accidentally staged.
-- Verified slices have commit SHAs, or deferred commit rationale is recorded.
-- PR summary includes evidence and residuals.
+- Verified slices have commit SHAs, or deferred commit rationale records the no-commit reason, owner, and next step.
+- PR summary follows `pull-request-standard.md` and includes evidence, version impact, references, and residuals.
 - Review findings are resolved or explicitly accepted.
 - Merge strategy and rollback or revert path are understood.
 

package/templates/reference/review-routing-standard.md

@@ -13,6 +13,12 @@ Define when work needs review, which reviewer identity is appropriate, and how r
 5. Reviewers must list `Evidence Checked`; unverified claims are questions, not conclusions.
 6. The implementation owner is responsible for reconciling conflicting reviewer feedback.
 7. Closeout must include the final review disposition and `Final Confidence Basis`.
+8. At task start, read the current task `execution_strategy.md` Subagent Authorization and Subagent Delegation Decision sections, then report the state and delegation choice; users do not need to know or ask for subagents.
+9. Reviewer subagents are allowed by default for read-only review within the current task.
+10. If a worker subagent would materially help and is not authorized, proactively ask the user once in plain language for task/scope/worktree authorization; it is fine to say "worker subagent", but do not wait for the user to know or suggest subagents.
+11. If independent slices are obvious but exact file paths are not, identify the file paths first and then immediately ask for independent-execution-helper authorization before implementation.
+12. Worker subagents require one user authorization recorded in `execution_strategy.md`; reuse is limited to the same task, scope, and worktree/branch.
+13. A `Would a worker subagent materially help?` decision of `ask-user` is a blocking gate until `User Authorization Decision` records `authorized`, `denied`, or `not-needed`.
 
 ## Required Checklist
 

package/templates/reference/walkthrough-standard.md

@@ -10,7 +10,7 @@ Define the closeout walkthrough that converts implementation work into durable p
 2. A walkthrough must explain what changed, why it changed, how it was verified, what review found, and what residual risk remains.
 3. Do not paste large raw logs. Link to evidence files, commands, PRs, screenshots, or CI runs.
 4. Material findings and their resolution must be visible.
-5. Lessons that change future behavior must first be routed through `lesson_candidates.md`; accepted candidates are then routed to the appropriate SSoT, reference standard, or Harness Ledger.
+5. Lessons that change future behavior must first be routed through `lesson_candidates.md`; candidates marked `needs-promotion` must link a task-local `lessons/LC-*.md` detail artifact before a follow-up task or promotion tries to preserve them.
 6. Walkthroughs must be written from the final integrated state, not from a single worker's partial view.
 7. If work is incomplete, the walkthrough must identify the next safe action and stop reason.
 
@@ -22,6 +22,7 @@ Define the closeout walkthrough that converts implementation work into durable p
 - Residual risk section.
 - Lesson or follow-up section.
 - Lesson candidate decision: `checked-candidate:<LC-ID>`, `queued-promotion:<LC-ID>`, `checked-created:<L-ID>`, or legacy `checked-none:<reason>`.
+- Source lesson detail link for any queued or promoted candidate.
 - Links to updated SSoT, Regression SSoT, or Harness Ledger entries when applicable.
 
 ## Closeout Expectations

package/templates/verifier/verifier-output.md

@@ -16,7 +16,7 @@
 | Tests and regression | yes / no | commands, CI runs, logs, screenshots |
 | SSoT and ledger updates | yes / no | Feature, Delivery, Regression, Closeout, or Harness Ledger links |
 | Review disposition | yes / no | review path, finding IDs, or no-finding statement |
-| Lessons and references | yes / no | Lessons SSoT, detail doc, or checked-none reason |
+| Lessons and references | yes / no | lesson_candidates.md, detail doc, or checked-none reason |
 
 ## Explicit Exclusions
 

package/templates-zh-CN/AGENTS.md.template

@@ -15,10 +15,11 @@
 
 1. 遵守 `docs/11-REFERENCE/engineering-standard.md` 中的架构边界。
 2. 不提交密钥、令牌、私有接口、用户隐私数据或生产凭据。
-3. 非平凡任务先在 `docs/09-PLANNING/TASKS/` 下建立任务目录。
+3. 非平凡任务先用 Harness CLI 在 `docs/09-PLANNING/TASKS/` 下建立任务目录。
 4. 声称完成前必须记录证据。
 5. 保护无关工作区改动，不回滚任务范围外文件。
-6. 已验证的、有意义的工作切片要主动提交，除非用户明确说不要提交。
+6. 已验证的、有意义的工作切片要主动提交。除非用户明确暂停提交、检查失败、dirty 归属不清，或安全边界导致无法形成干净提交，否则不要把已完成工作只留在未提交文件里；不能提交时，必须在 progress、handoff 或 closeout 中写明 no-commit reason、owner 和下一步。不要把无关 dirty 改动混入本任务提交。
+7. 最终回复前检查当前任务 `visual_map.md` 的 gate 阶段。如果当前 `Exit Command` 的 `Actor` 是 `agent`，就执行它或记录 blocker。不得执行 `review-confirm` 这类 `human` gate，除非用户已经明确完成或委托了人工确认。
 
 ## 任务阅读矩阵
 
@@ -31,8 +32,8 @@
 | 本地开发、mock、stub、跨仓调试 | `docs/04-DEVELOPMENT/README.md`、`docs/04-DEVELOPMENT/codebase-map.md` |
 | API、event、webhook、SDK、第三方契约 | `docs/06-INTEGRATIONS/README.md` 和相关契约文件 |
 | 测试、冒烟、回归 | `docs/11-REFERENCE/testing-standard.md`、`docs/05-TEST-QA/Regression-SSoT.md` |
-| 开发执行、提交、PR、发布 | `docs/11-REFERENCE/execution-workflow-standard.md`、`docs/11-REFERENCE/repo-governance-standard.md`、`docs/11-REFERENCE/ci-cd-standard.md` |
-| 创建或推进任务 | `docs/09-PLANNING/TASKS/` 下的当前任务目录；如果本项目已配置 Harness CLI，优先用 CLI |
+| 开发执行、提交、PR、发布 | `docs/11-REFERENCE/execution-workflow-standard.md`、`docs/11-REFERENCE/repo-governance-standard.md`、`docs/11-REFERENCE/pull-request-standard.md`、`docs/11-REFERENCE/ci-cd-standard.md` |
+| 创建或推进任务 | `docs/09-PLANNING/TASKS/` 下的当前任务目录；如果本项目已配置 Harness CLI，使用 `harness new-task` / lifecycle 命令 |
 | Brief、Execution Strategy、Visual Map | 当前任务的 `brief.md`、`execution_strategy.md`、`visual_map.md` |
 | 长程任务 | `docs/11-REFERENCE/long-running-task-standard.md` |
 | reviewer、subagent、对抗性审查 | `docs/11-REFERENCE/review-routing-standard.md`、`docs/11-REFERENCE/adversarial-review-standard.md` |
@@ -41,39 +42,44 @@
 | 文档治理或 Harness 更新 | `docs/11-REFERENCE/docs-library-standard.md`、`.harness-capabilities.json` |
 | 外部资料摄取 | `docs/11-REFERENCE/external-source-intake-standard.md` |
 | Regression SSoT 维护 | `docs/11-REFERENCE/regression-ssot-governance.md` |
-| 收口、walkthrough、Lessons | `docs/11-REFERENCE/walkthrough-standard.md`、`docs/10-WALKTHROUGH/Closeout-SSoT.md`、`docs/01-GOVERNANCE/Lessons-SSoT.md` |
+| 收口、walkthrough、Lessons | `docs/11-REFERENCE/walkthrough-standard.md`、`docs/10-WALKTHROUGH/Closeout-SSoT.md`、当前任务 `lesson_candidates.md`、`docs/01-GOVERNANCE/lessons/` |
 | Worktree、并行开发隔离 | `docs/11-REFERENCE/worktree-standard.md` |
 
 ## 标准执行流程
 
 1. 先确认请求、范围和受影响文件。
-2. 非平凡任务先创建或更新任务计划，再改代码。
-3. 只读取任务阅读矩阵要求的 reference 文档。
-4. 保留已有项目事实；新增上下文使用 merge / append，不覆盖历史。
-5. 需要隔离或并行时，使用独立 worktree 或分支。
-6. 只在确认范围内实现。
-7. 运行相关检查，并把证据写入任务记录。
-8. 按需触发 review，关闭阻塞发现。
-9. 写入或更新 walkthrough 与 closeout 记录。
-10. 只更新本任务实际触达的 SSoT / ledger。
+2. 非平凡任务先创建或更新任务计划，再改代码。优先使用 `harness new-task`；CLI 不可用时必须在任务 `INDEX.md` 保留任务审计元数据，并把 `Created By` 设为 `manual-exception`，写清具体原因。
+3. 根据用户目标主动判断是否需要分工；用户不需要知道或主动要求 subagent。
+4. 只读取任务阅读矩阵要求的 reference 文档。
+5. 保留已有项目事实；新增上下文使用 merge / append，不覆盖历史。
+6. 需要隔离或并行时，使用独立 worktree 或分支。
+7. 只在确认范围内实现。
+8. 运行相关检查，并把证据写入任务记录。
+9. 按需触发 review，关闭阻塞发现。
+10. 按当前 `visual_map.md` lifecycle gate 的 `Exit Command` / `Actor` 收口。
+11. 写入或更新 walkthrough 与 closeout 记录。
+12. 只更新本任务实际触达的 SSoT / ledger；任务生命周期总账优先由 Harness CLI 生成，不手写任务行。
 
 ## 协作规则
 
-- reviewer 默认只读，除非明确分配写入范围。
-- worker 只能编辑分配给自己的分支、worktree 和文件范围。
+- 任务开始时，先读取当前任务 `execution_strategy.md` 的 Subagent Authorization 和 Subagent Delegation Decision，并说明是否应该使用 reviewer 或 worker subagent；即使用户只说目标，也要主动判断。
+- reviewer subagent 默认允许，只能做当前任务的只读审查。
+- 如果 worker subagent 对任务有明显帮助但尚未授权，用白话主动向用户申请一次 task/scope/worktree 授权；可以直接说 worker subagent，但不要等用户知道或主动提醒你用 subagent。
+- 如果独立切片已经明显但精确文件路径还不清楚，先确认文件路径，然后在 implementation 前立刻申请独立执行助手授权。
+- worker subagent 需要用户授权一次，并记录到 `execution_strategy.md`；之后只可在同一任务、同一范围、同一 worktree/branch 内复用。
 - 共享 ledger、registry 和 SSoT 默认由 coordinator 维护，除非明确登记锁。
 - worker 交接必须包含分支或 worktree、改动文件、检查、证据和残余风险。
 
 ## 单一事实源
 
-- Feature SSoT：`docs/09-PLANNING/Feature-SSoT.md`
+- Harness Ledger：`docs/Harness-Ledger.md`（任务生命周期总账，由 CLI 生成）
 - Delivery SSoT：`docs/09-PLANNING/Delivery-SSoT.md`
 - Module Registry：`docs/09-PLANNING/Module-Registry.md`
 - Regression SSoT：`docs/05-TEST-QA/Regression-SSoT.md`
 - Cadence Ledger：`docs/05-TEST-QA/Cadence-Ledger.md`
-- Lessons SSoT：`docs/01-GOVERNANCE/Lessons-SSoT.md`
+- Lesson Candidates：当前任务 `lesson_candidates.md`
+- Lesson Detail Docs：`docs/01-GOVERNANCE/lessons/`
 - Closeout SSoT：`docs/10-WALKTHROUGH/Closeout-SSoT.md`
-- Harness Ledger：`docs/Harness-Ledger.md`
 
 ## 本地命令