coding-agent-harness 1.0.1 → 1.0.4

package/templates/dashboard/assets/mermaid-renderer.js

@@ -25,25 +25,35 @@ function parseFlowchart(code) {
     edges.push([from, to]);
   }
   if (nodes.size === 0) return null;
-  return { nodes: [...nodes.entries()], edges };
+  const direction = (lines[0].match(/^flowchart\s+(LR|TB|TD|RL|BT)/i)?.[1] || "LR").toUpperCase();
+  return { direction, nodes: [...nodes.entries()], edges };
 }
 
-function renderSvg({ nodes, edges }) {
-  const width = Math.max(360, nodes.length * 150);
-  const height = 150;
-  const positions = new Map(nodes.map(([id], index) => [id, { x: 70 + index * 140, y: 70 }]));
+function renderSvg({ direction, nodes, edges }) {
+  const layout = layoutNodes(nodes, direction);
+  const { positions, width, height } = layout;
   const nodeSvg = nodes.map(([id, label]) => {
     const pos = positions.get(id);
+    const displayLabel = truncateLabel(label);
     return `<g class="mermaid-node">
-      <rect x="${pos.x - 54}" y="${pos.y - 24}" width="108" height="48" rx="8"></rect>
-      <text x="${pos.x}" y="${pos.y + 4}" text-anchor="middle">${escapeMermaid(label).replaceAll("\\n", " ")}</text>
+      <title>${escapeMermaid(label).replaceAll("\\n", " ")}</title>
+      <rect x="${pos.x - pos.width / 2}" y="${pos.y - 24}" width="${pos.width}" height="48" rx="8"></rect>
+      <text x="${pos.x}" y="${pos.y + 4}" text-anchor="middle">${escapeMermaid(displayLabel)}</text>
     </g>`;
   }).join("");
   const edgeSvg = edges.map(([from, to]) => {
     const a = positions.get(from);
     const b = positions.get(to);
     if (!a || !b) return "";
-    return `<path class="mermaid-edge" d="M ${a.x + 54} ${a.y} L ${b.x - 62} ${b.y}"></path><path class="mermaid-arrow" d="M ${b.x - 62} ${b.y} l -7 -5 v 10 z"></path>`;
+    const horizontal = Math.abs(a.x - b.x) > Math.abs(a.y - b.y);
+    const startX = horizontal ? a.x + Math.sign(b.x - a.x) * (a.width / 2) : a.x;
+    const startY = horizontal ? a.y : a.y + Math.sign(b.y - a.y) * 24;
+    const endX = horizontal ? b.x - Math.sign(b.x - a.x) * (b.width / 2 + 8) : b.x;
+    const endY = horizontal ? b.y : b.y - Math.sign(b.y - a.y) * 32;
+    const arrow = horizontal
+      ? `M ${endX} ${endY} l ${b.x > a.x ? -7 : 7} -5 v 10 z`
+      : `M ${endX} ${endY} l -5 ${b.y > a.y ? -7 : 7} h 10 z`;
+    return `<path class="mermaid-edge" d="M ${startX} ${startY} L ${endX} ${endY}"></path><path class="mermaid-arrow" d="${arrow}"></path>`;
   }).join("");
   return `<figure class="mermaid-rendered">
     <figcaption>Mermaid</figcaption>
@@ -51,6 +61,46 @@ function renderSvg({ nodes, edges }) {
   </figure>`;
 }
 
+function layoutNodes(nodes, direction) {
+  const vertical = ["TD", "TB", "BT"].includes(direction);
+  const nodeSizes = nodes.map(([id, label]) => [id, nodeWidth(label)]);
+  const positions = new Map();
+  const margin = 48;
+  const rowGap = 104;
+  const colGap = 34;
+  if (vertical) {
+    const maxWidth = Math.max(220, ...nodeSizes.map(([, width]) => width));
+    nodeSizes.forEach(([id, width], index) => {
+      positions.set(id, { x: margin + maxWidth / 2, y: margin + 24 + index * rowGap, width });
+    });
+    return { positions, width: maxWidth + margin * 2, height: Math.max(150, margin * 2 + nodeSizes.length * rowGap) };
+  }
+
+  const maxPerRow = nodes.length > 5 ? Math.ceil(Math.sqrt(nodes.length * 1.4)) : nodes.length;
+  let y = margin + 24;
+  let width = 360;
+  for (let index = 0; index < nodeSizes.length; index += maxPerRow) {
+    const row = nodeSizes.slice(index, index + maxPerRow);
+    let x = margin;
+    for (const [id, nodeW] of row) {
+      positions.set(id, { x: x + nodeW / 2, y, width: nodeW });
+      x += nodeW + colGap;
+    }
+    width = Math.max(width, x + margin - colGap);
+    y += rowGap;
+  }
+  return { positions, width, height: Math.max(150, y + margin - rowGap) };
+}
+
+function nodeWidth(label) {
+  return Math.max(112, Math.min(240, String(label || "").replaceAll("\\n", " ").length * 7 + 34));
+}
+
+function truncateLabel(label) {
+  const text = String(label || "").replaceAll("\\n", " ");
+  return text.length > 28 ? `${text.slice(0, 25)}...` : text;
+}
+
 function escapeMermaid(value) {
   return String(value ?? "")
     .replaceAll("&", "&amp;")

package/templates/development/README.md

@@ -0,0 +1,52 @@
+# Development Context
+
+Context Doc Type: development-index
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+This folder is the development input pack. It tells agents how to work in this repository, how to face external services during development, and what not to assume when the external repositories are unavailable.
+
+## Boundary
+
+- Put local setup, codebase map, external service development summaries, mocks, stubs, and cross-repo debugging here.
+- Put long-lived system structure in `docs/03-ARCHITECTURE/`.
+- Put concrete API/event/webhook contracts in `docs/06-INTEGRATIONS/`.
+
+## Structure Contract
+
+| File / Path | Facts to maintain | Write rule |
+| --- | --- | --- |
+| `local-setup.md` | Local startup, dependencies, environment variables, common failures | Development startup facts only; not production architecture |
+| `codebase-map.md` | Local code entry points, directory responsibilities, read order | Agents read this before editing code |
+| `external-context/<service-key>.md` | External service impact on local development, mocks/stubs, debug entry points | One external service per file |
+| `external-source-packs/` | Large external source sets, indexes, digests, and projection status | Intake layer only; not the final fact layer |
+| `stubs-and-mocks.md` | Available mock/stub strategies in this repository | Include executable paths or commands |
+| `cross-repo-debugging.md` | Cross-repo debugging sequence and evidence | Debug workflow only; not a service responsibility overview |
+
+## External Service Rule
+
+If this repository depends on multiple microservices, do not write all external knowledge into one large document. For any external service that affects local development or testing, create:
+
+- `docs/03-ARCHITECTURE/services/<service-key>.md`: what the service is and what it owns.
+- `docs/04-DEVELOPMENT/external-context/<service-key>.md`: how this repository mocks, stubs, or debugs it.
+- `docs/06-INTEGRATIONS/<contract>.md`: concrete API/event/webhook contracts.
+
+`04-DEVELOPMENT` only answers how to work with the external service during development. Do not maintain full system topology here, and do not put payload schemas here.
+
+## External Source Pack Rule
+
+If an external team provides many documents, screenshots, exported packets, meeting notes, or links, do not place them directly into `03/04/06`. Read `docs/11-REFERENCE/external-source-intake-standard.md` first, then decide whether `external-source-packs/<source-key>/` is needed.
+
+`external-source-packs/` owns source indexes, digests, and projection status only. Stable conclusions must be written back to:
+
+- `docs/03-ARCHITECTURE/services/<service-key>.md`
+- `docs/04-DEVELOPMENT/external-context/<service-key>.md`
+- `docs/06-INTEGRATIONS/<contract>.md`
+
+## External Context Index
+
+| Service Key | Why It Matters To This Repo | Local Stub / Mock | Debug Entry | Architecture Link | Contract Link | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |

package/templates/development/codebase-map.md

@@ -0,0 +1,11 @@
+# Codebase Map
+
+Context Doc Type: codebase-map
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Entry Points
+
+| Area | Path | Responsibility | Read When | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |

package/templates/development/cross-repo-debugging.md

@@ -0,0 +1,18 @@
+# Cross-Repo Debugging
+
+Context Doc Type: cross-repo-debugging
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Debug Flow
+
+1. Identify the failing interface or flow.
+2. Read `docs/03-ARCHITECTURE/service-catalog.md` for ownership and upstream/downstream services.
+3. Read the matching `docs/06-INTEGRATIONS/` contract.
+4. Use the matching `docs/04-DEVELOPMENT/external-context/<service-key>.md` notes for mocks and local debugging.
+
+## Known Failure Modes
+
+| Symptom | Likely Service | First Check | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |

package/templates/development/external-context/service-template.md

@@ -0,0 +1,33 @@
+# External Development Context: <service-key>
+
+Context Doc Type: external-development-context
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Index Links
+
+| Service Profile | Source Pack | Integration Contracts | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-source-packs/<source-key>/README.md` or N/A | `docs/06-INTEGRATIONS/<contract>.md` | unknown | low |
+
+## Development Use
+
+[What an agent needs to know about this external service while changing this repository.]
+
+## Do Not Assume
+
+- [Assumption that is unsafe without checking the external repo or owner.]
+
+## Mocks / Stubs
+
+| Scenario | Stub / Mock | Command or Path | Source Evidence |
+| --- | --- | --- | --- |
+
+## Cross-Repo Debug Notes
+
+[How to debug when this service is involved.]
+
+## Placement Rule
+
+This file only covers local development, testing, and debugging context for this external service. Put service responsibility in `03-ARCHITECTURE`; put interface fields and schemas in `06-INTEGRATIONS`.

package/templates/development/external-source-packs/README.md

@@ -0,0 +1,24 @@
+# External Source Packs
+
+Context Doc Type: external-source-pack-registry
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+This directory is only for external source intake, indexing, and digests. Stable facts become Harness execution context only after they are projected into `03-ARCHITECTURE`, `04-DEVELOPMENT/external-context`, or `06-INTEGRATIONS`.
+
+Read `docs/11-REFERENCE/external-source-intake-standard.md` before adding a source pack.
+
+## Source Packs
+
+| Source Key | External Project / Service | Raw Storage Mode | Source Count | Digest Status | Projected To 03/04/06 | Owner | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Placement Rule
+
+- If there are fewer than 5 source documents, prefer linking them from `Source Evidence` in `03/04/06`; a source pack may be unnecessary.
+- If the material is large, multi-topic, or expected to grow, create `<source-key>/README.md` and `digests/`.
+- `raw/` may contain only commit-safe material with no secrets, personal data, or customer data.
+- Non-committable material should be represented by external path, owner, access condition, and digest only.

package/templates/development/external-source-packs/digest-template.md

@@ -0,0 +1,28 @@
+# External Source Digest: <source-id>
+
+Context Doc Type: external-source-digest
+Source Pack: <source-key>
+Original Location: <path-or-url-or-owner>
+Digest Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Source Summary
+
+[Summarize what this source is, what it covers, how trustworthy it is, and when it was last updated in 5-10 lines.]
+
+## Extracted Facts
+
+| Fact ID | Fact | Category | Project To | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| F-001 | [verifiable fact] | architecture / development / integration / security / operations / product / unknown | `docs/...` or hold | <source-id> | unknown | low |
+
+## Questions / Unsafe Assumptions
+
+| ID | Question Or Assumption | Why It Matters | Owner | Status |
+| --- | --- | --- | --- | --- |
+
+## Projection Status
+
+| Target Doc | Action | Status | Evidence |
+| --- | --- | --- | --- |

package/templates/development/local-setup.md

@@ -0,0 +1,16 @@
+# Local Setup
+
+Context Doc Type: local-setup
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Commands
+
+| Task | Command | Expected Result | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## Environment
+
+| Variable | Required | Purpose | Source Evidence |
+| --- | --- | --- | --- |

package/templates/development/stubs-and-mocks.md

@@ -0,0 +1,11 @@
+# Stubs and Mocks
+
+Context Doc Type: stubs-and-mocks
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Available Stubs
+
+| External Service | Scenario | Stub Path | How To Run | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |

package/templates/integrations/README.md

@@ -0,0 +1,40 @@
+# Integrations
+
+Context Doc Type: integration-index
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+This folder owns concrete interface contracts: APIs, events, webhooks, SDK usage, third-party integrations, auth, payloads, errors, and contract tests.
+
+## Boundary
+
+- Put service topology and ownership in `docs/03-ARCHITECTURE/`.
+- Put development mocks and debugging notes in `docs/04-DEVELOPMENT/`.
+- Put endpoint, payload, error, auth, event, webhook, and SDK contracts here.
+
+## Structure Contract
+
+| File / Path | Facts to maintain | Write rule |
+| --- | --- | --- |
+| `<service-key>-api.md` | API endpoints, auth, payloads, errors, contract tests | Create from `api-contract.md` |
+| `<event-name>-event.md` | Event producer/consumer, schema, delivery, retry | Create from `event-contract.md` |
+| `<webhook-name>-webhook.md` | Webhook source, target, signature, payload, retry | Create from `webhook-contract.md` |
+| `third-party/<vendor-key>.md` | Third-party platform, account/permission boundaries, SDK usage, limits | Create from `third-party/vendor-template.md` |
+
+## Contract Rule
+
+Every interface contract must be its own file and link back to the related service:
+
+- Service ownership and topology: `docs/03-ARCHITECTURE/service-catalog.md` or `services/<service-key>.md`
+- Local mocks, stubs, and debugging: `docs/04-DEVELOPMENT/external-context/<service-key>.md`
+- Concrete payloads, auth, errors, and contract tests: this folder
+
+Do not mix multiple services into one large "integration notes" document. Multi-service systems should have multiple contract files; the Contract Index below is the navigation layer for humans and agents.
+
+## Contract Index
+
+| Contract | Type | Producer | Consumer | Service Profile | Development Context | Contract Tests | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |

package/templates/integrations/api-contract.md

@@ -0,0 +1,42 @@
+# API Contract: <service-or-api>
+
+Context Doc Type: api-contract
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+API
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Auth
+
+[Authentication and authorization requirements.]
+
+## Endpoints
+
+| Method | Path | Purpose | Request Payload | Response Payload | Errors | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Payload
+
+[Schema or link to schema.]
+
+## Errors
+
+[Error codes, retry rules, and user-visible behavior.]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+This file describes one API contract only. Put service responsibility in `03-ARCHITECTURE`; put local mock/stub/debug details in `04-DEVELOPMENT`.

package/templates/integrations/event-contract.md

@@ -0,0 +1,46 @@
+# Event Contract: <event-name>
+
+Context Doc Type: event-contract
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+Event
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Topic / Channel
+
+[Queue, topic, stream, or bus.]
+
+## Auth
+
+[Producer/consumer permission, signature, or access control. Use N/A with evidence when no auth exists.]
+
+## Payload
+
+[Event schema or link.]
+
+## Producers and Consumers
+
+| Role | Service | Responsibility | Source Evidence |
+| --- | --- | --- | --- |
+
+## Errors
+
+[Dead-letter, retry, and compatibility behavior.]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+This file describes one event contract only. Put service responsibility in `03-ARCHITECTURE`; put local mock/stub/debug details in `04-DEVELOPMENT`.

package/templates/integrations/third-party/vendor-template.md

@@ -0,0 +1,42 @@
+# Third-Party Integration: <vendor>
+
+Context Doc Type: third-party-integration
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+Third-party service
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<vendor-key>.md` | `docs/04-DEVELOPMENT/external-context/<vendor-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Auth
+
+[Credential and permission model. Do not include secrets.]
+
+## API / SDK Surface
+
+| Surface | Purpose | Contract Link | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## Payload
+
+[Important request/response bodies or links.]
+
+## Errors
+
+[Vendor error, quota, retry, and fallback behavior.]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+This file describes one third-party integration only. Put account/permission/SDK/limit facts here; put business responsibility and system topology in `03-ARCHITECTURE`.

package/templates/integrations/webhook-contract.md

@@ -0,0 +1,41 @@
+# Webhook Contract: <webhook-name>
+
+Context Doc Type: webhook-contract
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Contract Type
+
+Webhook
+
+## Index Links
+
+| Service Profile | Development Context | Contract Index | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/services/<service-key>.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/06-INTEGRATIONS/README.md` | unknown | low |
+
+## Auth
+
+[Signature, token, or IP allowlist.]
+
+## Payload
+
+[Webhook body schema or link.]
+
+## Source Evidence
+
+[Code, vendor docs, owner note, or discovery command.]
+
+## Errors
+
+[Retry, timeout, and idempotency behavior.]
+
+## Contract Tests
+
+| Test | Command / Path | Expected Result |
+| --- | --- | --- |
+
+## Placement Rule
+
+This file describes one webhook contract only. Put service responsibility in `03-ARCHITECTURE`; put local mock/stub/debug details in `04-DEVELOPMENT`.

package/templates/ledger/Harness-Ledger.md

@@ -2,38 +2,26 @@
 
 ## Purpose
 
-Track whether each meaningful task kept the harness contract intact: planning, scope control, SSoT updates, regression evidence, review, walkthrough, lessons, and reference routing.
+Generated canonical task lifecycle index. Humans should use the Dashboard for current status; agents should use `task-list`, `task-index`, or this generated ledger for low-cost lookup.
 
-## Status Legend
+This file is not a hand-written work log. Do not edit lifecycle rows manually. Update task-local facts (`task_plan.md`, `progress.md`, `review.md`, `lesson_candidates.md`, closeout / walkthrough evidence), then run `harness governance rebuild --archive --apply`.
 
-| 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. |
+Repo Governance / CI-CD changes remain routed through their reference standards and task evidence. Regression gates, delivery sequencing, cadence rules, closeout contracts, and module ownership remain in their dedicated governance files until explicitly replaced by equivalent scanner-supported facts.
 
 ## Active Ledger
 
-| ID | Task or Change | Owner | Status | Plan | Feature or Delivery SSoT | Regression Evidence | Review Evidence | Walkthrough | Lessons Check | Residual | Updated |
+| ID | Scope | Module | Task | State | Queues | Plan | Review | Lessons Check | Closeout | 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 |
+| HL-YYYY-MM-DD-001 | task | none | Short operational title | planned | none | docs/09-PLANNING/TASKS/.../task_plan.md | pending | pending | pending | none | YYYY-MM-DD |
 
-## Routing Rules
+## Field 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.
+- `Scope`: `task` for root planning tasks, `module` for module-local tasks.
+- `Module`: module key, or `none`.
+- `Queues`: scanner-derived lifecycle queues; query with `harness task-list --queue`.
+- `Review`, `Lessons Check`, `Closeout`, and `Residual`: scanner-derived summaries and routes. Detailed evidence stays in task-local files.
+- `Updated`: generation date, not a manual edit timestamp.
 
-## Archive Rules
+## Legacy Tables
 
-- 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.
+`Feature-SSoT.md` and `Private-Feature-SSoT.md` are legacy task lifecycle projections. Current Harness versions archive them during `harness governance rebuild --archive --apply` and do not regenerate them.

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

@@ -39,7 +39,7 @@ Describe the recurring architecture, ownership, phase-gate, or operating-process
 ## 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.
+- This promoted lesson detail doc links the applied change and the closeout record.
 - Existing active tasks know whether the new rule applies immediately or only to future work.
 
 ## Disposition

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

@@ -43,7 +43,7 @@ Describe the missing reference document, template, checklist, or operating guide
 
 - 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.
+- This promoted lesson detail doc links the new document and the closeout record.
 
 ## Disposition
 

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

@@ -37,7 +37,7 @@ ref-change
 ## Acceptance Criteria
 
 - The target reference, template, or checker is updated.
-- The update is linked from Lessons SSoT.
+- The update is linked from this promoted lesson detail doc and the closeout record.
 - Any active task affected by the rule has a migration or no-impact note.
 
 ## Disposition

package/templates/planning/brief.md

@@ -0,0 +1,32 @@
+# {{TASK_TITLE}}
+
+## Brief
+
+## Task ID
+
+`{{TASK_ID}}`
+
+## Created
+
+{{DATE}}
+
+## Outcome
+
+State the user-visible or project-visible result this task must deliver.
+
+## Boundaries
+
+- In scope: files, behavior, documentation, or verification this task may change.
+- Out of scope: work that must not be folded into this task.
+- Stop conditions: uncertainty, risk, or missing access that requires coordinator or user review.
+
+## Execution Contract
+
+- Owner: coordinator
+- Lifecycle state: not_started
+- Required files: `task_plan.md`, `execution_strategy.md`, `visual_map.md`, `progress.md`, `findings.md`, `review.md`
+- Required closeout: verification evidence recorded in `progress.md`
+
+## First Next Step
+
+Replace this line with the first concrete action before implementation starts.