coding-agent-harness 1.0.0

package/templates/ledger/Harness-Ledger.md

@@ -0,0 +1,39 @@
+# Harness Ledger
+
+## Purpose
+
+Track whether each meaningful task kept the harness contract intact: planning, scope control, SSoT updates, regression evidence, review, walkthrough, lessons, and reference routing.
+
+## Status Legend
+
+| Status | Meaning | Required Next Step |
+| --- | --- | --- |
+| proposed | Work is identified but not accepted into active execution. | Assign an owner or reject with a reason. |
+| planned | Scope, owner, and expected evidence are known. | Start execution or update schedule. |
+| active | Work is in progress. | Keep task plan and evidence current. |
+| review | Implementation is complete and waiting for review or verification. | Complete review and regression gates. |
+| blocked | Work cannot proceed without a decision or dependency. | Record blocker owner and unblock condition. |
+| closed | Work is complete and closeout evidence exists. | Archive only when no longer operationally useful. |
+| archived | Entry is historical and no longer part of active coordination. | Keep a pointer to the archive location. |
+
+## Active Ledger
+
+| ID | Task or Change | Owner | Status | Plan | Feature or Delivery SSoT | Regression Evidence | Review Evidence | Walkthrough | Lessons Check | Residual | Updated |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| HL-YYYY-MM-DD-001 | Short operational title | owner | planned | docs/09-PLANNING/TASKS/.../task_plan.md | F-000 or D-000 | RG-000 or n/a | review.md or n/a | pending | pending | none | YYYY-MM-DD |
+
+## Routing Rules
+
+1. Create or update one ledger row for every non-trivial feature, refactor, release, harness update, or multi-agent handoff.
+2. Link to durable files and commands. Do not rely on chat history as evidence.
+3. If a task changes product behavior, route it through Feature SSoT or Delivery SSoT.
+4. If a task changes regression expectations, route it through Regression SSoT and Cadence Ledger.
+5. If a task changes agent process, documentation standards, or repeatable checks, route it through Lessons SSoT.
+6. A row can move to `closed` only when the walkthrough, regression evidence, review disposition, and lessons check are recorded.
+
+## Archive Rules
+
+- Keep active, blocked, review, and recently closed rows in this file.
+- Move old closed rows to `docs/01-GOVERNANCE/archive/` or the project archive path when they no longer affect current coordination.
+- Preserve the ledger ID, final status, closeout link, and archive date in any archive entry.
+- Never delete a row to hide skipped verification, `accepted-risk`, or unresolved review feedback.

package/templates/lessons/lesson-arch-process-change.md

@@ -0,0 +1,47 @@
+# L-YYYY-MM-DD-001: Short Architecture or Process Lesson
+
+## Lesson Type
+
+arch-process-change
+
+## Source
+
+| Field | Value |
+| --- | --- |
+| Discovered in | walkthrough, review, incident, verifier, or release |
+| Source link | path or URL |
+| Related task | F-000, D-000, HL-000, or task plan path |
+| Owner | owner |
+| Status | candidate / accepted / applied / rejected / superseded |
+
+## Problem
+
+Describe the recurring architecture, ownership, phase-gate, or operating-process problem in one short paragraph.
+
+## Impact
+
+| Impact Area | Evidence | Severity |
+| --- | --- | --- |
+| delivery, quality, safety, review load, or agent repeatability | source evidence | low / medium / high |
+
+## Proposed Change
+
+| Area | Current Rule | Proposed Rule |
+| --- | --- | --- |
+| operating model, phase gate, ownership, or architecture boundary | current behavior | new behavior |
+
+## Adoption Plan
+
+| Step | Owner | Target File or Process | Due | Status |
+| --- | --- | --- | --- | --- |
+| Update standard, template, checker, or workflow | owner | path or process name | YYYY-MM-DD | planned |
+
+## Acceptance Criteria
+
+- The new rule has a durable home in a reference, template, checker, or project operating model.
+- The Lessons SSoT row links this detail doc and the applied change.
+- Existing active tasks know whether the new rule applies immediately or only to future work.
+
+## Disposition
+
+accepted / rejected / applied / superseded, with reason and evidence link.

package/templates/lessons/lesson-new-doc.md

@@ -0,0 +1,50 @@
+# L-YYYY-MM-DD-001: Short New-Document Lesson
+
+## Lesson Type
+
+new-doc
+
+## Source
+
+| Field | Value |
+| --- | --- |
+| Discovered in | walkthrough, review, incident, verifier, or release |
+| Source link | path or URL |
+| Related task | F-000, D-000, HL-000, or task plan path |
+| Owner | owner |
+| Status | candidate / accepted / applied / rejected / superseded |
+
+## Gap
+
+Describe the missing reference document, template, checklist, or operating guide that caused ambiguity or repeat work.
+
+## Why Existing Docs Are Not Enough
+
+| Existing Doc | Gap |
+| --- | --- |
+| path or none | what it does not cover |
+
+## Proposed Document
+
+| Field | Value |
+| --- | --- |
+| Target path | docs/.../document-name.md |
+| Primary reader | agent, reviewer, maintainer, release owner, or operator |
+| Required sections | concise section list |
+| Related standards | paths or none |
+
+## Adoption Plan
+
+| Step | Owner | Due | Status |
+| --- | --- | --- | --- |
+| Draft, review, link, and add checker coverage if needed | owner | YYYY-MM-DD | planned |
+
+## Acceptance Criteria
+
+- The new document exists at the target path and is linked from the relevant index or entrypoint.
+- The document contains operational rules, not background essay content.
+- The Lessons SSoT row links this detail doc and the new document.
+
+## Disposition
+
+accepted / rejected / applied / superseded, with reason and evidence link.

package/templates/lessons/lesson-ref-change.md

@@ -0,0 +1,45 @@
+# L-YYYY-MM-DD-001: Short Reference-Change Lesson
+
+## Lesson Type
+
+ref-change
+
+## Source
+
+| Field | Value |
+| --- | --- |
+| Discovered in | walkthrough, review, incident, verifier, or release |
+| Source link | path or URL |
+| Related task | F-000, D-000, HL-000, or task plan path |
+| Owner | owner |
+| Status | candidate / accepted / applied / rejected / superseded |
+
+## Existing Rule
+
+| Reference | Current Text or Behavior | Problem |
+| --- | --- | --- |
+| path to standard, template, checker, or entrypoint | short summary | why future agents may fail |
+
+## Proposed Update
+
+| Target | Change Required | Reason |
+| --- | --- | --- |
+| path | add, revise, delete, or route rule | operational reason |
+
+## Validation
+
+| Check | Evidence |
+| --- | --- |
+| Updated reference or template reviewed | path or pending |
+| Checker update needed? | yes / no, reason |
+| Active tasks impacted? | yes / no, migration note |
+
+## Acceptance Criteria
+
+- The target reference, template, or checker is updated.
+- The update is linked from Lessons SSoT.
+- Any active task affected by the rule has a migration or no-impact note.
+
+## Disposition
+
+accepted / rejected / applied / superseded, with reason and evidence link.

package/templates/planning/execution_strategy.md

@@ -0,0 +1,40 @@
+# [Task Name] - Execution Strategy
+
+## Strategy Summary
+
+[Describe the execution approach, including why this operating model fits the risk and scope.]
+
+## Operating Model
+
+- Model: solo / team / split-repo / program / waterfall / kanban / module-parallel
+- Primary executor: coordinator / worker / human
+- Shared sync owner: coordinator
+- Worktree required: yes / no
+- Review required: yes / no
+
+## Work Allocation
+
+| Role | Input Package | Write Scope | Handoff Required | Owner |
+| --- | --- | --- | --- | --- |
+| coordinator | task plan, strategy, roadmap | shared ledgers and integration | yes | [owner] |
+| worker | assigned slice | assigned files only | yes | [owner] |
+
+## Coordination Rules
+
+1. Shared files are coordinator-owned unless a lock is explicitly assigned.
+2. Workers update only assigned files and route shared-table changes through handoff.
+3. Parallel work must use non-overlapping write scopes.
+4. Integration runs final checks after worker commits are merged or applied.
+
+## Verification Strategy
+
+| Check | Command or Evidence | Required | Owner |
+| --- | --- | --- | --- |
+| Static check | [command or path] | yes / no | [owner] |
+| Unit test | [command or path] | yes / no | [owner] |
+| Integration or smoke | [command, URL, or log] | yes / no | [owner] |
+| Review | `review.md` / verifier output / n/a | yes / no | [owner] |
+
+## Closeout Rule
+
+Do not mark the task complete until required evidence is present, material findings are closed or accepted, and shared updates are either completed or assigned to the coordinator.

package/templates/planning/findings.md

@@ -0,0 +1,24 @@
+# [Task Name] - Findings
+
+Use this file for defects, risks, unclear requirements, research notes, and review follow-up that may affect delivery.
+
+## Open Findings
+
+| ID | Severity | Finding | Evidence | Owner | Required Action | Status |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Do not keep sample findings. Add rows only for real findings discovered during the task.
+
+## Resolved Findings
+
+| ID | Resolution | Evidence | Date |
+| --- | --- | --- | --- |
+
+Add rows only after a real finding is resolved or accepted with owner-routed risk.
+
+## Severity Guide
+
+- P0: Blocks release or risks data loss, security exposure, or production outage.
+- P1: Blocks the task goal or a required workflow.
+- P2: Material quality, maintainability, or evidence gap.
+- P3: Follow-up improvement that does not block closeout.

package/templates/planning/long-running-task-contract.md

@@ -0,0 +1,69 @@
+# [Task Name] - Long-Running Task Contract
+
+## Goal
+
+[State the single main problem this loop must close.]
+
+## Scope
+
+### In Scope
+
+- [Allowed directories, modules, or capability surfaces]
+
+### Out of Scope
+
+- [Items explicitly excluded from this loop]
+
+### Shared Files and Conflict Risk
+
+- [Shared files that may conflict with other work, or none]
+
+## Permission Boundaries
+
+- Continuous execution allowed: yes / no
+- Automatic review/fix/test loop allowed: yes / no
+- Reviewer or subagent allowed: yes / no
+- Must pause before: [high-risk actions]
+
+## Required Loop
+
+1. Re-read the goal, scope, and current findings.
+2. Choose the smallest complete fix for the current finding or phase.
+3. Implement within the allowed write scope.
+4. Run required verification.
+5. Update `progress.md` and `findings.md`.
+6. Run review when required and update `review.md`.
+7. Continue, stop, or pause based on the stop and pause conditions below.
+
+## Reviewer / Subagent Contract
+
+- Reviewer scope: [files / modules / problem domain]
+- Reviewer output: `review.md`
+- Worker allowed to edit code: yes / no
+- If a worker may edit, handoff must include worktree path, branch, commit SHA, checks, files changed, and residual risks.
+
+## Evidence
+
+- [ ] Static checks: [command]
+- [ ] Unit tests: [command]
+- [ ] Integration or smoke tests: [command]
+- [ ] Runtime verification: [URL / command / log]
+- [ ] Review report: `review.md` / n/a
+- [ ] Residual risks recorded: yes / no
+
+## Stop Conditions
+
+- [ ] Goal is met.
+- [ ] Scope was not exceeded.
+- [ ] Required tests and regression gates pass or have documented waivers.
+- [ ] Runtime, console, and request errors are clear or classified as accepted-risk with owner rationale.
+- [ ] Review has no open P0/P1 material findings.
+- [ ] Residual risks are routed to an owner and do not block the goal.
+
+## Pause Conditions
+
+- [ ] Goal or scope becomes invalid.
+- [ ] High-risk product, architecture, security, or data decision is required.
+- [ ] Unknown uncommitted changes conflict with this work.
+- [ ] Environment, permission, quota, or external dependency blocks progress.
+- [ ] Reviewer finding changes task direction.

package/templates/planning/module_plan.md

@@ -0,0 +1,36 @@
+# [Module Name] - Module Plan
+
+## Module Identity
+
+- Module key: [key]
+- Owner: [agent / human]
+- Branch: [branch]
+- Write Scope: [directories or files]
+- Shared files: [files requiring coordinator lock, or none]
+
+## Boundaries
+
+- May edit: [paths]
+- Must not edit: [paths or shared surfaces]
+- External dependencies: [services, packages, teams, or none]
+
+## Steps
+
+| Step ID | Name | Status | Task Plan | Depends On |
+| --- | --- | --- | --- | --- |
+| MOD-01 | [step name] | planned | [path] | none |
+
+## Verification
+
+| Check | Command or Evidence | Required |
+| --- | --- | --- |
+| [check name] | [command or path] | yes / no |
+
+## Handoff
+
+- Branch: [branch]
+- Commit SHA: [sha]
+- Checks: [summary]
+- Files changed: [summary]
+- Residual risks: [none / list]
+- Coordinator updates needed: [none / list]

package/templates/planning/module_session_prompt.md

@@ -0,0 +1,39 @@
+# Module Worker Session Prompt
+
+## Context Package
+
+- Project: [project]
+- Module key: [module]
+- Task directory: [path]
+- Module plan: [path]
+- Assigned worktree: [path]
+- Assigned branch: [branch]
+
+## Goal
+
+[State one concrete module outcome.]
+
+## Write Scope
+
+You may edit only:
+
+- [path]
+
+Do not edit shared SSoT files, coordinator-owned integration files, or unrelated modules unless the coordinator explicitly assigns that scope.
+
+## Required Output
+
+- Branch name
+- Commit SHA
+- Files changed
+- Checks run and results
+- Residual risks
+- Coordinator updates needed
+
+## 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.
+
+## Stop Rule
+
+Pause and report if the requested change requires editing outside the assigned scope, resolving unrelated dirty files, making a product decision, or changing a shared contract.

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

@@ -0,0 +1,12 @@
+# Artifacts Index
+
+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 |
+
+## Retention Notes
+
+- Keep artifacts that are needed to reproduce evidence or review decisions.
+- Remove or ignore temporary artifacts once their result is captured in `progress.md`.

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

@@ -0,0 +1,13 @@
+# References Index
+
+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] |
+
+## Source Rules
+
+- Prefer canonical project files over summaries.
+- Record external links with enough context for a reviewer to re-check them.
+- Mark stale or uncertain references in `findings.md`.

package/templates/planning/optional/slices/_slice-template/brief.md

@@ -0,0 +1,27 @@
+# Slice Brief
+
+## Identity
+
+| Parent Phase ID | Depends On | State | Owner / Handoff |
+| --- | --- | --- | --- |
+| PH-01 | none | planned | [owner] |
+
+## Goal
+
+[State one concrete slice outcome.]
+
+## Scope
+
+- In scope: [items]
+- Out of scope: [items]
+- Write scope: [paths]
+
+## Required Evidence
+
+| Evidence | Command / Path | Required |
+| --- | --- | --- |
+| [check] | [command or path] | yes |
+
+## Handoff Requirement
+
+The slice owner must report files changed, checks run, residual risks, and any shared updates needed from the coordinator.

package/templates/planning/optional/slices/_slice-template/evidence.md

@@ -0,0 +1,9 @@
+# Slice Evidence
+
+| Evidence ID | Type | Path | Summary | Status |
+| --- | --- | --- | --- | --- |
+| SE-001 | command / file / runtime / review | [command or path] | [what this evidence shows] | missing |
+
+## Status Values
+
+Use `missing`, `partial`, `present`, or `waived`. If evidence is waived, record the reason and owner in the parent `progress.md`.

package/templates/planning/optional/slices/_slice-template/review.md

@@ -0,0 +1,31 @@
+# Slice Review
+
+## Reviewer Identity
+
+| Reviewer | Type | Scope |
+| --- | --- | --- |
+| [name] | self / subagent / external / human | [slice scope] |
+
+## Confidence Challenge
+
+Answer directly: do you have 100% confidence in this slice?
+
+- Verdict: yes / no
+- If no, list every plausible gap below and propose fixes.
+
+## Material Findings
+
+| ID | Severity | Finding | Evidence Checked | Required Action | Open | Disposition | Blocks Release | Follow-up |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+Do not keep sample findings. If there are no material findings, leave only the header and complete the Final Confidence Basis.
+
+## Evidence Checked
+
+| Evidence ID | Type | Path | Summary |
+| --- | --- | --- | --- |
+| SE-001 | command / file / runtime | [path or command] | [summary] |
+
+## Final Confidence Basis
+
+[Explain why this slice is ready to merge, or name the remaining limits.]

package/templates/planning/progress.md

@@ -0,0 +1,33 @@
+# [Task Name] - Progress
+
+## Current Status
+
+planned
+
+## Log
+
+| Time | Actor | Action | Evidence | Next |
+| --- | --- | --- | --- | --- |
+| YYYY-MM-DD HH:MM | coordinator | [action taken] | type:path:summary | [next step] |
+
+## Decisions
+
+| Date | Decision | Reason | Owner |
+| --- | --- | --- | --- |
+| YYYY-MM-DD | [decision] | [reason] | [owner] |
+
+## Evidence Ledger
+
+| Evidence ID | Type | Path or Command | Result | Used For |
+| --- | --- | --- | --- | --- |
+| E-001 | command / file / runtime / review | [path or command] | pass / fail / observed / waived | [claim supported] |
+
+## Residual
+
+none
+
+## Coordinator Handoff
+
+- Global sync status: pending-coordinator-pass / synced / n/a
+- Owner: coordinator / n/a
+- Required shared updates: [none]

package/templates/planning/review.md

@@ -0,0 +1,48 @@
+# [Task Name] - Review
+
+## Reviewer Identity
+
+| Reviewer | Type | Scope |
+| --- | --- | --- |
+| [name] | self / subagent / external / human | [files, modules, behavior, or release surface] |
+
+## Review Scope
+
+- Review type: adversarial / security / regression / architecture / release / other
+- In scope: [files, modules, behavior]
+- Out of scope: [explicit exclusions]
+- Source materials: [task plan, diff, test output, runtime evidence]
+
+## Confidence Challenge
+
+Answer directly: do you have 100% confidence in the plan, implementation, and strategy?
+
+- Verdict: yes / no
+- If no, list every plausible gap below and propose fixes.
+
+## Material Findings
+
+| ID | Severity | Finding | Evidence Checked | Required Action | Open | Disposition | Blocks Release | Follow-up |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+Do not keep sample findings. If there are no material findings, leave only the header and complete the No-Finding Statement.
+
+## No-Finding Statement
+
+[If no material findings remain, state what evidence was checked and why no material finding remains.]
+
+## Evidence Checked
+
+| Evidence ID | Type | Path | Summary |
+| --- | --- | --- | --- |
+| E-001 | command / file / runtime | [path or command] | [what was checked and what it showed] |
+
+## Residual Risk
+
+| Risk | Owner | Accepted? | Follow-up |
+| --- | --- | --- | --- |
+| [risk] | [owner] | yes / no | [path or next action] |
+
+## 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

@@ -0,0 +1,86 @@
+# [Task Name]
+
+## Goal
+
+[State the outcome this task must deliver in one sentence.]
+
+## Scope
+
+- 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 | 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 |
+
+Selected budget: [simple / standard / long-running / module-parallel]
+
+## 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_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 |
+
+## Steps
+
+1. [First concrete step]
+2. [Second concrete step]
+3. [Third concrete step]
+
+## Acceptance Criteria
+
+- [ ] [Observable criterion]
+- [ ] [Verification criterion]
+- [ ] [Documentation or handoff criterion]
+
+## Worktree
+
+- Path: [worktree path or n/a]
+- Branch: [branch or n/a]
+- Worker owner: coordinator / subagent id / n/a
+- Worker handoff commit required: yes / no / n/a
+- If no worktree, reason: [reason]
+
+## Long-Running Task Decision
+
+- Long-running task: yes / no
+- Contract file if yes: `long-running-task-contract.md`
+- Continuous execution permission: granted / not granted / n/a
+- Stop condition summary: [one sentence]
+
+## Review Decision
+
+- Adversarial review required: yes / no
+- Report file if yes: `review.md`
+- Reviewer: self / subagent / external / human / n/a
+- No-finding requirement: [requirement or n/a]
+
+## Links
+
+- Feature SSoT entry: [reference]
+- Related Regression Gate: [reference]
+- Review Report: [path / n/a]
+- Harness Ledger entry: [complete at closeout]
+- Prerequisite tasks: [reference or none]
+
+## Coordinator Handoff
+
+- Global sync owner: coordinator / n/a
+- Global sync status: pending-coordinator-pass / synced / n/a
+- Shared updates needed: [Module Registry / Harness Ledger / Closeout SSoT / Regression SSoT / none]