coding-agent-harness 1.0.1 → 1.0.4

package/templates/planning/execution_strategy.md

@@ -4,6 +4,37 @@
 
 [Describe the execution approach, including why this operating model fits the risk and scope.]
 
+## Subagent Authorization
+
+Read this section at the start of the task and report the current authorization state before delegating.
+This is an audit record, not an execution sandbox.
+
+| Role | Status | Permission | Authorized By | Authorized At | Scope | Worktree / Branch | Reuse |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| reviewer subagent | allowed by default | read-only | harness task policy | task creation | current task review | n/a | allowed within this task |
+| worker subagent | not authorized | write only after user approval | pending | pending | pending | pending | allowed only within approved task/scope |
+
+## Subagent Delegation Decision
+
+At task start, the coordinator must make this decision from the user's goal, even if the user never mentions subagents.
+Do not expect the user to know what a subagent or worker is. If delegation would help, explain the benefit in plain language and ask for permission once.
+It is fine to say "subagent" or "worker" to the user; the important rule is that the agent must not wait for the user to ask for them.
+If the task is clearly split into independent slices, decide `ask-user` before implementation. If exact file paths are still unknown, first identify the paths, then immediately ask for the independent execution helper authorization.
+
+| Question | Decision | Reason | Next Action |
+| --- | --- | --- | --- |
+| Should a reviewer subagent be used? | yes / no | [why reviewer review helps or is unnecessary] | If yes, call a read-only reviewer without asking for extra permission. |
+| Would a worker subagent materially help? | no / ask-user / already-authorized | [parallel slice, independent implementation, focused investigation, or not useful] | If ask-user, ask directly: "This task is suitable for a worker subagent. Do you authorize me to assign one worker subagent to modify only [scope] in [worktree/branch] while I coordinate and review the result?" |
+
+## User Authorization Decision
+
+If the worker decision above is `ask-user`, implementation is blocked until this table records the user's answer.
+Allowed resolved states are `authorized`, `denied`, or `not-needed`. Do not leave this as `pending` after choosing `ask-user`.
+
+| Gate | State | Decided By | Decided At | Scope | Worktree / Branch | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| worker subagent | pending | pending | pending | pending | pending | Fill only after directly asking the user. |
+
 ## Operating Model
 
 - Model: solo / team / split-repo / program / waterfall / kanban / module-parallel

package/templates/planning/lesson_candidates.md

@@ -0,0 +1,70 @@
+# {{TASK_TITLE}} - Lesson Candidates
+
+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
+
+| Field | Value |
+| --- | --- |
+| Schema version | lesson-candidate-v1 |
+| Task-level status | pending-review |
+| Review gate | candidate-file-present |
+| Review decision | pending-human-review |
+| Promotion state | not-promoted |
+| Closeout token | pending |
+| Source task | {{TASK_ID}} |
+| Owner | coordinator |
+| Last updated | {{DATE}} |
+
+## Schema
+
+Allowed task-level status:
+
+- `missing`: candidate file is absent.
+- `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 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 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:
+
+- Any `ready-for-review` row keeps task-level status `pending-review`.
+- Any `needs-promotion` row sets task-level status `needs-promotion` unless another row is still `ready-for-review`.
+- All rows `promoted` sets task-level status `promoted`.
+- All rows `rejected` sets task-level status `rejected`.
+- A no-candidate task must use task-level status `no-candidate-accepted` and fill `No-Candidate Reason`.
+
+## Candidates
+
+| 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
+
+Not decided yet. Fill this only when review accepts that the task produced no reusable lesson candidate.
+
+## 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/long-running-task-contract.md

@@ -18,6 +18,12 @@
 
 - [Shared files that may conflict with other work, or none]
 
+## Primary Caller / Entry
+
+- Primary caller: [CLI / local agent / UI / API / automation / integration / other]
+- Entries this task must support: [list]
+- Entries explicitly not required: [list]
+
 ## Permission Boundaries
 
 - Continuous execution allowed: yes / no
@@ -50,6 +56,7 @@
 - [ ] Runtime verification: [URL / command / log]
 - [ ] Review report: `review.md` / n/a
 - [ ] Residual risks recorded: yes / no
+- [ ] Lesson candidate review recorded: `lesson_candidates.md` uses `no-candidate-accepted`, `needs-promotion`, `promoted`, or `rejected`
 
 ## Stop Conditions
 

package/templates/planning/module_brief.md

@@ -0,0 +1,25 @@
+# {{TASK_TITLE}} Module
+
+## Brief
+
+## Module Key
+
+`{{TASK_ID}}`
+
+## Created
+
+{{DATE}}
+
+## Role
+
+State what this module owns and why it exists.
+
+## Boundaries
+
+- Owns: directories, services, or document areas under this module.
+- Shared surfaces: files that require coordinator sync.
+- Does not own: adjacent modules or global files outside the declared scope.
+
+## Current Work
+
+List the active module tasks or point to `module_plan.md`.

package/templates/planning/module_session_prompt.md

@@ -30,6 +30,12 @@ Do not edit shared SSoT files, coordinator-owned integration files, or unrelated
 - Residual risks
 - Coordinator updates needed
 
+## Review And State Rule
+
+- 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.
+- 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
 
 Do not update Module Registry, Harness Ledger, Closeout SSoT, Regression SSoT, or Cadence Ledger from a worker session unless the coordinator assigned the shared lock.

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?
@@ -31,6 +61,24 @@ Do not keep sample findings. If there are no material findings, leave only the h
 
 [If no material findings remain, state what evidence was checked and why no material finding remains.]
 
+## Human Review Confirmation
+
+This section must only be completed by a human reviewer or by a command/workbench action acting on explicit human confirmation. Agent review submission, self-review, and subagent review do not satisfy this gate.
+
+| Field | Value |
+| --- | --- |
+| Confirmation ID | [generated by review-confirm] |
+| Confirmed At | [timestamp] |
+| Reviewer | [human name] |
+| Reviewer Email | [email, if available] |
+| Task Key | {{TASK_ID}} |
+| Confirm Text | [must match the task id or confirmation phrase required by the command] |
+| Evidence Checked | [review packet / tests / diff summary] |
+| Commit SHA | [confirmation commit SHA generated by review-confirm] |
+| Audit Status | committed / blocked |
+
+Do not fill this section when the task still belongs in Missing Materials, Blocked, or Lessons routing. `review-confirm` and the Dashboard Workbench must reject dirty Git state, missing commit identity, hook failures, or writes outside the current task `review.md` / `progress.md` allowlist.
+
 ## Evidence Checked
 
 | Evidence ID | Type | Path | Summary |
@@ -43,6 +91,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,5 +1,7 @@
 # [Task Name]
 
+Task Contract: harness-task/v1
+
 ## Goal
 
 [State the outcome this task must deliver in one sentence.]
@@ -13,12 +15,11 @@
 
 | Budget | Use When | Required Structure |
 | --- | --- | --- |
-| simple | One owner, no subagent, L0/L1 evidence | Standard task files only |
-| standard | Normal feature, fix, or documentation change | Plan, strategy, roadmap, progress, findings, and review as needed |
-| long-running | Multi-hour autonomous loop | Add `long-running-task-contract.md` and a review loop |
-| module-parallel | Independent module slices | Add `module_plan.md`, module registry updates, and worker handoff |
+| 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 | `brief.md`, `task_plan.md`, `execution_strategy.md`, `visual_map.md`, `findings.md`, `lesson_candidates.md`, `progress.md`, `review.md` |
+| complex | Multi-hour work, L2/L3 evidence, subagent/reviewer, or optional artifact/reference indexes | Standard files plus `references/INDEX.md` and `artifacts/INDEX.md` |
 
-Selected budget: [simple / standard / long-running / module-parallel]
+Selected budget: {{TASK_BUDGET}}
 
 ## Context Packet
 
@@ -28,14 +29,39 @@ Selected budget: [simple / standard / long-running / module-parallel]
 
 ## Required Files
 
-| Contract File | Required | Purpose |
-| --- | --- | --- |
-| `execution_strategy.md` | yes | Operating model, allocation, conflict control, and evidence strategy |
-| `visual_roadmap.md` | yes | Phase graph, completion state, evidence state, and blocking risk |
-| `progress.md` | yes | Execution log, decisions, and handoff |
-| `findings.md` | yes | Findings, research notes, and unresolved risks |
-| `review.md` | if needed | Adversarial or specialist review report |
-| `long-running-task-contract.md` | if needed | Continuous execution permission, loop rules, and stop conditions |
+Do not hand-copy this template to create task directories. Use `harness new-task`
+so the selected budget creates the correct file set and `harness check` can
+enforce it.
+
+| Budget | Required Files |
+| --- | --- |
+| simple | `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 |
+
+Optional subdirectories are created only when triggered:
+
+- `lessons/LC-*.md`: task-local detail artifacts for lesson candidates marked `needs-promotion`.
+- `references/INDEX.md`: complex-task source package and reference index.
+- `artifacts/INDEX.md`: complex-task generated evidence and artifact index.
+
+File purposes:
+
+| Contract File | Purpose |
+| --- | --- |
+| `brief.md` | Human-readable task summary and current context packet |
+| `task_plan.md` | Goal, scope, budget, acceptance, and operating decisions |
+| `execution_strategy.md` | Operating model, allocation, conflict control, and evidence strategy |
+| `visual_map.md` | Diagram collection: phase map, optional architecture/sequence/data-flow/state diagrams, completion state, evidence state, and blocking risk |
+| `progress.md` | Execution log, decisions, and handoff |
+| `findings.md` | Findings, research notes, and unresolved risks |
+| `lesson_candidates.md` | Task-local lesson candidate queue. Human review must accept no-candidate, reject candidates, or queue promotion before review confirmation |
+| `lessons/LC-*.md` | Optional task-local lesson detail artifacts written while source context is fresh and linked from `Detail Artifact` |
+| `review.md` | Agent review submission, adversarial review, or specialist review report |
+| `references/INDEX.md` | Complex-task source package and reference index |
+| `artifacts/INDEX.md` | Complex-task generated evidence and artifact index |
+| `long-running-task-contract.md` | Continuous execution permission, loop rules, and stop conditions |
 
 ## Steps
 
@@ -73,10 +99,9 @@ Selected budget: [simple / standard / long-running / module-parallel]
 
 ## 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

@@ -0,0 +1,50 @@
+# [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
+  PH01["PH-01 Plan"] --> PH02["PH-02 Implement"]
+  PH02 --> PH03["PH-03 Verify"]
+  PH03 --> PH04["PH-04 Review and Closeout"]
+```
+
+## 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 |
+
+Allowed Evidence Status: missing, partial, present, waived.
+
+## 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/docs-library-standard.md

@@ -14,6 +14,35 @@ Define how the project documentation library is organized so agents can find cur
 6. Do not mix private runtime state, credentials, personal notes, or generated caches into the public docs library.
 7. Documentation updates that change process or behavior must be reflected in the relevant index or routing file.
 
+## Architecture / Development / Integration Routing
+
+Use these directories as a low-entropy context system:
+
+| Directory | Owns | Must Not Own | Required Schema Signals |
+| --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/` | system structure, service responsibility, ownership, service catalog, critical flows, ADRs | endpoint payloads, mock instructions, task logs | `Context Doc Type`, `Source Evidence`, `Last Verified`, `Confidence` |
+| `docs/04-DEVELOPMENT/` | local setup, codebase map, external development context, external source packs, mocks, stubs, cross-repo debugging | long-lived architecture facts, API payload contracts, undigested external document dumps | `Context Doc Type`, `Development Use`, `Do Not Assume`, `Mocks / Stubs`, `Source Evidence`, `Last Verified`, `Confidence` |
+| `docs/06-INTEGRATIONS/` | API/event/webhook/SDK/third-party contracts, auth, payloads, errors, contract tests | global topology, service ownership catalog, debugging notes | `Context Doc Type`, `Contract Type`, `Auth`, `Payload`, `Errors`, `Contract Tests`, `Source Evidence`, `Last Verified`, `Confidence` |
+
+Concrete split:
+
+- `03-ARCHITECTURE/service-catalog.md` gives only the service summary and links.
+- `06-INTEGRATIONS/<service>-api-contract.md` owns payload bodies, auth, errors, and contract tests.
+- `04-DEVELOPMENT/external-context/<service>.md` owns mocks, stubs, unsafe assumptions, and debug notes.
+- `04-DEVELOPMENT/external-source-packs/` owns external source indexes, digests, and projection status only; final facts must be written back to `03/04/06`.
+
+## External Source Intake
+
+If the target project is a microservice, multi-repo system, split frontend/backend repository, or depends on external team documents, the agent must ask the user for external source material during Diagnose / Decide. Small source sets can be linked from `Source Evidence`; large source sets must use `external-source-intake-standard.md` and a source pack.
+
+The fixed processing order is:
+
+```text
+Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
+```
+
+Raw external material that has not been digested and projected must not become execution fact.
+
 ## Required Checklist
 
 - Entry points identify current reference standards, planning templates, SSoT files, walkthroughs, and ledgers.
@@ -22,6 +51,8 @@ Define how the project documentation library is organized so agents can find cur
 - Generated or private artifacts are excluded or explicitly separated.
 - Cross-links point to the source of truth for each subject.
 - New standards include closeout and evidence expectations.
+- `03/04/06` documents use the required schema signals and route misplaced content back to the correct directory.
+- External source packs, when present, have a registry, digests, projection targets, and residuals.
 
 ## Closeout Expectations
 

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

@@ -12,7 +12,9 @@ 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. Close the loop by updating walkthrough, SSoT, regression, ledger, or docs artifacts when the work changes durable project knowledge.
+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 and refuse dirty Git state; agent-owned manual edits still need an explicit task commit or deferred-commit rationale.
+9. 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.
 
 ## Required Checklist
 
@@ -20,10 +22,11 @@ Define the standard lifecycle for non-trivial work from intake through planning,
 - 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 no-commit reason, owner, and next step are written down.
 - Review status and material findings are recorded.
 - Residuals are explicit and assigned.
 - Closeout artifacts are updated when required.
 
 ## Closeout Expectations
 
-Closeout must provide a concise change summary, evidence checked, checks not run with reasons, review outcome, residual risk, and any durable docs or ledger updates made during the task.
+Closeout must provide a concise change summary, evidence checked, checks not run with reasons, review outcome, residual risk, relevant commit SHAs or deferred-commit rationale, and any durable docs or ledger updates made during the task.

package/templates/reference/external-source-intake-standard.md

@@ -0,0 +1,82 @@
+# External Source Intake Standard
+
+## Purpose
+
+This standard defines how agents receive, filter, organize, and project large external documentation sets from other projects, microservice teams, or platform owners. The goal is executable context, not a document dump.
+
+## Core Model
+
+```text
+external source material -> source pack index -> digest -> 03/04/06 execution projection
+```
+
+`03-ARCHITECTURE`, `04-DEVELOPMENT`, and `06-INTEGRATIONS` only hold facts that have been distilled enough to guide work. Raw external files, long documents, screenshots, exported chats, diagrams, and historical packets first go through `docs/04-DEVELOPMENT/external-source-packs/`.
+
+## When To Ask The User
+
+During Diagnose / Decide, the agent must ask whether external source material exists when any of these signals appear:
+
+- The repository is part of a multi-repo, microservice, split frontend/backend, or platform system.
+- The code references external services, SDKs, API gateways, message queues, webhooks, contracts, schemas, or mocks.
+- The user mentions other repositories, upstream/downstream services, interface docs, business knowledge, or system-level design.
+- The agent cannot determine service responsibility, integration contracts, or local debugging behavior from the current repository alone.
+
+Recommended questions:
+
+1. Does this project depend on external services or other repositories?
+2. Do you have architecture docs, API docs, diagrams, meeting notes, source links, code paths, or exported packets from those teams?
+3. Can those materials be copied into this repository? If not, should the Harness store only local paths or URLs?
+4. Which sources are authoritative, and which are historical references only?
+
+## Storage Rules
+
+| Case | Storage |
+| --- | --- |
+| Only 1-4 stable external documents | No separate source pack is required; link them from `Source Evidence` in the relevant `03/04/06` docs |
+| More than 5 documents, multiple topics, or continuing growth | Create `docs/04-DEVELOPMENT/external-source-packs/<source-key>/` |
+| Material contains secrets, customer data, private links, or cannot be committed | Do not copy raw files; record external location, owner, access condition, and digest only |
+| Material is safe to commit | Raw files may go under `raw/`, but only digested facts may be projected into execution docs |
+
+Recommended structure:
+
+```text
+docs/04-DEVELOPMENT/external-source-packs/<source-key>/
+├── README.md              # source index and projection status
+├── digests/               # digest for each source or source group
+├── raw/                   # commit-safe raw material only
+└── raw-index.md           # path/URL/owner index when raw material cannot be committed
+```
+
+Do not replicate a full `03/04/06` tree for every microservice. The source pack is the intake layer. The stable execution entries remain:
+
+- `docs/03-ARCHITECTURE/service-catalog.md`
+- `docs/03-ARCHITECTURE/services/<service-key>.md`
+- `docs/04-DEVELOPMENT/external-context/<service-key>.md`
+- `docs/06-INTEGRATIONS/<contract>.md`
+
+## Intake Flow
+
+1. **Inventory**: list sources, owners, dates, trust level, and commit eligibility.
+2. **Classify**: tag each source as architecture, development, integration, security, operations, product, or unknown.
+3. **Sanitize**: check for secrets, tokens, customer data, personal information, internal accounts, and private links; keep non-committable material as references only.
+4. **Digest**: extract facts, questions, unsafe assumptions, and evidence with the digest template.
+5. **Project**: move stable facts into `03/04/06`, then mark the source as projected in the source pack README.
+6. **Verify**: use code evidence, contract tests, owner confirmation, or runtime checks where feasible; update `Last Verified` and `Confidence`.
+7. **Residual**: keep unverified or conflicting facts in the source pack or in `Do Not Assume`; do not treat them as execution facts.
+
+## Projection Rules
+
+| Source Content | Projection Target |
+| --- | --- |
+| Service responsibility, upstream/downstream relationship, owner, data ownership, topology | `03-ARCHITECTURE/service-catalog.md` or `services/<service-key>.md` |
+| Local mocks, stubs, startup, debugging, cross-repo development behavior | `04-DEVELOPMENT/external-context/<service-key>.md` |
+| Endpoint, payload, auth, error, event, webhook, SDK, contract test | `06-INTEGRATIONS/<contract>.md` |
+| Unconfirmed, conflicting, stale, or background-only material | Keep in source pack README / digest; do not project into execution docs |
+
+## Prohibited
+
+- Do not copy large external document sets directly into `03-ARCHITECTURE`, `04-DEVELOPMENT`, or `06-INTEGRATIONS`.
+- Do not treat an external-source digest as verified fact without `Source Evidence`, `Last Verified`, and `Confidence`.
+- Do not keep long raw excerpts, chat logs, or meeting transcripts inside execution docs.
+- Do not commit secrets, production tokens, customer data, personal information, or non-public raw material.
+- Do not create one full directory tree per microservice for completeness; create source packs only for large external source sets.

package/templates/reference/harness-ledger-standard.md

@@ -13,6 +13,7 @@ Define when and how the Harness Ledger records durable changes to the agent oper
 5. Do not store secrets, personal data, large logs, or raw generated output in the ledger.
 6. If a lesson changes a reference standard, record both the lesson and the reference update.
 7. If no ledger update is needed, closeout should say why.
+8. New task closeout should route lesson review through `lesson_candidates.md`; record `checked-candidate:<LC-ID>`, `queued-promotion:<LC-ID>`, or `checked-created:<L-ID>` as the final lesson outcome.
 
 ## Required Artifacts