coding-agent-harness 1.0.1 → 1.0.2

package/templates/AGENTS.md.template

@@ -1,6 +1,8 @@
 # [Project Name]
 
-This file is the operating contract for agents working in this repository. Keep it concise: it should route agents to the right source of truth, not replace the project documentation.
+This file is the operating entry point for agents working in this repository.
+Keep it as a charter and routing index. Detailed rules belong in
+`docs/11-REFERENCE/`, not in this file.
 
 ## Project Profile
 
@@ -8,59 +10,66 @@ This file is the operating contract for agents working in this repository. Keep
 - Stack: [language, framework, runtime]
 - Repository shape: [single repo / monorepo / multi-repo]
 - Primary modules: [module list]
-- Primary users or operators: [audience]
+- Default branch: [main / master / other]
 
 ## Non-Negotiable Rules
 
 1. Preserve architecture boundaries documented in `docs/11-REFERENCE/engineering-standard.md`.
-2. Do not hard-code secrets, credentials, production tokens, or private endpoints.
+2. Do not commit secrets, credentials, private endpoints, or user data.
 3. Start non-trivial work with a task directory under `docs/09-PLANNING/TASKS/`.
 4. Record evidence before claiming completion.
-5. Protect unrelated working-tree changes. Never revert files outside the assigned scope.
-6. Keep shared ledgers and SSoT files coordinator-owned unless a lock is explicitly assigned.
+5. Protect unrelated working-tree changes; never revert files outside the assigned scope.
+6. Commit verified, meaningful work slices unless the user explicitly says not to commit.
 
 ## Reading Matrix
 
+Read the smallest context that can answer the task.
+
 | Work Type | Read First |
 | --- | --- |
 | Architecture or core module change | `docs/11-REFERENCE/engineering-standard.md` |
-| Tests, smoke, or regression | `docs/11-REFERENCE/testing-standard.md` |
-| Execution, commit, or PR | `docs/11-REFERENCE/execution-workflow-standard.md` |
-| Team, multi-repo, or staged delivery | `docs/11-REFERENCE/delivery-operating-model-standard.md` and `docs/09-PLANNING/Delivery-SSoT.md` |
-| Repository, PR, branch, or CI work | `docs/11-REFERENCE/repo-governance-standard.md` and `docs/11-REFERENCE/ci-cd-standard.md` |
+| System map, service responsibility, or external system relationship | `docs/03-ARCHITECTURE/README.md`, `docs/03-ARCHITECTURE/service-catalog.md` |
+| Local development, mocks, stubs, or cross-repo debugging | `docs/04-DEVELOPMENT/README.md`, `docs/04-DEVELOPMENT/codebase-map.md` |
+| API, event, webhook, SDK, or third-party contract | `docs/06-INTEGRATIONS/README.md` and the related contract file |
+| Tests, smoke, or regression | `docs/11-REFERENCE/testing-standard.md`, `docs/05-TEST-QA/Regression-SSoT.md` |
+| Execution, commit, PR, or release work | `docs/11-REFERENCE/execution-workflow-standard.md`, `docs/11-REFERENCE/repo-governance-standard.md`, `docs/11-REFERENCE/ci-cd-standard.md` |
+| Creating or advancing a task | Current task directory under `docs/09-PLANNING/TASKS/`; use the Harness CLI if this project has it configured |
+| Brief, Execution Strategy, or Visual Map | Current task `brief.md`, `execution_strategy.md`, and `visual_map.md` |
 | Long-running task | `docs/11-REFERENCE/long-running-task-standard.md` |
-| Adversarial review | `docs/11-REFERENCE/adversarial-review-standard.md` |
-| Reviewer or subagent routing | `docs/11-REFERENCE/review-routing-standard.md` |
-| Documentation governance | `docs/11-REFERENCE/docs-library-standard.md` |
-| Harness Ledger update | `docs/11-REFERENCE/harness-ledger-standard.md` |
+| Reviewer, subagent, or adversarial review | `docs/11-REFERENCE/review-routing-standard.md`, `docs/11-REFERENCE/adversarial-review-standard.md` |
+| Team, multi-repo, or staged delivery | `docs/11-REFERENCE/delivery-operating-model-standard.md`, `docs/09-PLANNING/Delivery-SSoT.md` |
+| Module-parallel work | `docs/09-PLANNING/Module-Registry.md` and the related module plan |
+| Documentation governance or Harness update | `docs/11-REFERENCE/docs-library-standard.md`, `.harness-capabilities.json` |
+| External source material intake | `docs/11-REFERENCE/external-source-intake-standard.md` |
 | Regression SSoT maintenance | `docs/11-REFERENCE/regression-ssot-governance.md` |
-| Walkthrough, closeout, or lessons | `docs/11-REFERENCE/walkthrough-standard.md` |
+| Walkthrough, closeout, or lessons | `docs/11-REFERENCE/walkthrough-standard.md`, `docs/10-WALKTHROUGH/Closeout-SSoT.md`, `docs/01-GOVERNANCE/Lessons-SSoT.md` |
 | Worktree operations | `docs/11-REFERENCE/worktree-standard.md` |
 
 ## Standard Execution Flow
 
 1. Confirm the request, scope, and affected files.
-2. Create or update the task plan.
-3. Choose the operating model and record it in `execution_strategy.md`.
-4. Create the required worktree or record why one is unnecessary.
-5. Implement only within the approved scope.
-6. Run the required checks and capture evidence.
-7. Complete review when required.
-8. Update Feature SSoT, Delivery SSoT, Regression SSoT, Closeout SSoT, Lessons SSoT, and Harness Ledger as applicable.
-9. Write the walkthrough, or record the allowed reason for skipping it.
-10. Clean up worktrees after integration.
-
-## Subagent Contract
+2. For non-trivial work, create or update the task plan before editing code.
+3. Load only the reference documents required by the Reading Matrix.
+4. Preserve existing project facts; merge new context instead of overwriting history.
+5. Use a worktree or branch when the task requires isolation or parallel work.
+6. Implement only within the approved scope.
+7. Run the relevant checks and capture evidence in the task records.
+8. Route required review and close blocking findings.
+9. Write or update the walkthrough and closeout records.
+10. Update SSoT / ledger files that the task actually touched.
+
+## Coordination Rules
 
 - Reviewers are read-only unless explicitly assigned a write scope.
-- Workers may edit only their assigned worktree, branch, and file scope.
-- Worker handoff must include worktree path, branch, commit SHA, checks, changed files, and residual risks.
-- The coordinator owns shared ledgers, final integration, and release claims unless delegated in writing.
+- Workers may edit only their assigned branch, worktree, and file scope.
+- Shared ledgers, registries, and SSoT files are coordinator-owned unless a lock is explicitly assigned.
+- Worker handoff must include branch or worktree, changed files, checks, evidence, and residual risks.
 
-## Single Sources of Truth
+## Single Sources Of Truth
 
 - Feature SSoT: `docs/09-PLANNING/Feature-SSoT.md`
 - 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`
@@ -79,4 +88,6 @@ This file is the operating contract for agents working in this repository. Keep
 
 ## Completion Standard
 
-A task is complete only when the requested change is implemented, evidence is recorded, required review findings are closed or explicitly accepted, and the relevant SSoT or ledger updates are complete.
+A task is complete only when the requested change is implemented, evidence is
+recorded, required reviews are resolved, and affected SSoT or ledger files are
+updated.

package/templates/architecture/Architecture-SSoT.md

@@ -0,0 +1,21 @@
+# Architecture SSoT
+
+Context Doc Type: architecture-ssot
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## System Summary
+
+[Describe the current repository and the larger system it participates in.]
+
+## Current Architecture Facts
+
+| ID | Fact | Source Evidence | Last Verified | Confidence | Read Before |
+| --- | --- | --- | --- | --- | --- |
+| ARCH-001 | [fact] | [code/doc/owner note/command] | unknown | low | [path] |
+
+## Promotion Log
+
+| Source Task | Promoted Fact | Destination | Decision | Date |
+| --- | --- | --- | --- | --- |

package/templates/architecture/README.md

@@ -0,0 +1,49 @@
+# Architecture
+
+Context Doc Type: architecture-index
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+This folder is the system-structure source of truth. It explains what the current repository is, what larger system it belongs to, and which services, flows, and decisions matter before an agent changes code.
+
+## Read Order
+
+1. `Architecture-SSoT.md`
+2. `local-repo-context.md`
+3. `system-map.md`
+4. `service-catalog.md`
+5. `critical-flows.md`
+6. `services/<service-key>.md`
+7. `decisions/ADR-*.md`
+
+## Boundary
+
+- Put system structure, service responsibility, ownership, and critical flows here.
+- Put payload bodies, endpoint parameters, event schemas, and SDK details in `docs/06-INTEGRATIONS/`.
+- Put local setup, mocks, stubs, and cross-repo debugging notes in `docs/04-DEVELOPMENT/`.
+
+## Structure Contract
+
+| File / Path | Facts to maintain | Write rule |
+| --- | --- | --- |
+| `Architecture-SSoT.md` | Current architecture state, key decisions, known risks | Only long-lived system facts |
+| `local-repo-context.md` | This repository's role and boundary in the wider system | Say what this repo owns and does not own |
+| `system-map.md` | Service/module topology, upstream/downstream relationships, deployment boundaries | Use diagrams or tables for global relationships; do not write payload details |
+| `service-catalog.md` | Service index; one row per service or microservice | Add a row first, then decide whether a profile file is needed |
+| `services/<service-key>.md` | One service's responsibility, data, interface summary, and read-before links | One service per file; do not mix multiple services |
+| `critical-flows.md` | Critical cross-service flows | Write business/system flow, not interface field details |
+
+## Microservice Rule
+
+For multi-service systems, `service-catalog.md` is the master index. Every known service should have at least one row. Create `services/<service-key>.md` for any service that affects development, debugging, integration, or task decisions in this repository.
+
+Each `services/<service-key>.md` answers only three questions:
+
+1. What does this service own, including data ownership.
+2. How does it relate to this repository.
+3. Which `04-DEVELOPMENT` and `06-INTEGRATIONS` docs must an agent read before changing this repository.
+
+Do not put interface fields, mock instructions, or temporary debugging notes in `03-ARCHITECTURE`. Those belong in `06-INTEGRATIONS` and `04-DEVELOPMENT`.

package/templates/architecture/critical-flows.md

@@ -0,0 +1,22 @@
+# Critical Flows
+
+Context Doc Type: critical-flows
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Flow Index
+
+| Flow ID | Name | Trigger | Services | Business Impact | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Flow Template
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant CurrentRepo
+  participant ExternalService
+  User->>CurrentRepo: request
+  CurrentRepo->>ExternalService: call
+```

package/templates/architecture/local-repo-context.md

@@ -0,0 +1,20 @@
+# Local Repo Context
+
+Context Doc Type: local-repo-context
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Responsibility
+
+[State what this repository owns.]
+
+## Main Components
+
+| Component | Path | Responsibility | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## External Dependencies
+
+| Dependency | Why It Matters | Architecture Link | Integration Link | Development Link |
+| --- | --- | --- | --- | --- |

package/templates/architecture/service-catalog.md

@@ -0,0 +1,17 @@
+# Service Catalog
+
+Context Doc Type: service-catalog
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Services
+
+| Service Key | Service / Component | Owner | Repo / Path | Responsibility | Interfaces | Data Owned | Dependencies | Service Profile | Development Context | Source Pack | Contract Index | Source Evidence | Last Verified | Stale After | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+## Boundary Rule
+
+This catalog gives interface summaries and links only. Put payload bodies, auth rules, error codes, and event schemas in `docs/06-INTEGRATIONS/`.
+
+Each service or microservice gets one row. If the service affects development or task decisions in this repository, add links to `services/<service-key>.md`, `docs/04-DEVELOPMENT/external-context/<service-key>.md`, and the relevant `docs/06-INTEGRATIONS/<contract>.md`.

package/templates/architecture/services/service-template.md

@@ -0,0 +1,31 @@
+# Service: <service-key>
+
+Context Doc Type: service-profile
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Index Links
+
+| Catalog Row | Development Context | Source Pack | Integration Contracts | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+| `docs/03-ARCHITECTURE/service-catalog.md` | `docs/04-DEVELOPMENT/external-context/<service-key>.md` | `docs/04-DEVELOPMENT/external-source-packs/<source-key>/README.md` or N/A | `docs/06-INTEGRATIONS/<contract>.md` | unknown | low |
+
+## Responsibility
+
+[What this service owns.]
+
+## Interfaces Summary
+
+| Interface | Direction | Contract Link | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- |
+
+## Agent Read Before
+
+- [architecture link]
+- [development context link]
+- [integration contract link]
+
+## Placement Rule
+
+This file describes one service only. Do not merge multiple services, payload details, mock instructions, or temporary debugging notes into this profile.

package/templates/architecture/system-map.md

@@ -0,0 +1,22 @@
+# System Map
+
+Context Doc Type: system-map
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Scope
+
+[Describe the larger system boundary this repository belongs to.]
+
+## Mermaid Map
+
+```mermaid
+flowchart LR
+  current["Current Repository"] --> external["External Service"]
+```
+
+## Map Evidence
+
+| Node | Meaning | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- |

package/templates/dashboard/assets/app-src/00-state.js

@@ -0,0 +1,41 @@
+const bundle = window.__HARNESS_DASHBOARD__ || {};
+const defaultLocale = window.__HARNESS_LOCALE__ || ((navigator.language || "").toLowerCase().startsWith("zh") ? "zh" : "en");
+let locale = localStorage.getItem("harness.locale") || defaultLocale;
+if (!window.HarnessI18n?.[locale]) locale = "en";
+let labels = window.HarnessI18n?.[locale] || {};
+
+const state = {
+  query: "",
+  taskState: "all",
+  taskGroupMode: "migration",
+  taskPageByGroup: {},
+  taskGroupPage: 1,
+  warningFilter: "all",
+  warningPage: 1,
+  renderMode: "rendered",
+  theme: localStorage.getItem("harness.theme") || "system",
+  taskLayout: localStorage.getItem("harness.taskLayout") || "list",
+  runtime: { mode: "static", csrfToken: "", writableActions: [] },
+  runtimeLoaded: false,
+  runtimePoller: null,
+};
+
+const taskPageSize = 25;
+const taskGroupsPerPage = 8;
+const warningPageSize = 18;
+
+const taskDocTabs = [
+  ["brief", "brief.md"],
+  ["taskPlan", "task_plan.md"],
+  ["strategy", "execution_strategy.md"],
+  ["visualMap", "visual_map.md"],
+  ["legacyRoadmap", "visual_roadmap.md"],
+  ["lessonCandidates", "lesson_candidates.md"],
+  ["longRunningContract", "long-running-task-contract.md"],
+  ["progress", "progress.md"],
+  ["review", "review.md"],
+  ["findings", "findings.md"],
+  ["walkthrough", "__walkthrough__"],
+  ["references", "references/INDEX.md"],
+  ["artifacts", "artifacts/INDEX.md"],
+];

package/templates/dashboard/assets/app-src/10-router.js

@@ -0,0 +1,76 @@
+function t(key) {
+  return labels[key] || key;
+}
+
+function setLocale(nextLocale) {
+  locale = window.HarnessI18n?.[nextLocale] ? nextLocale : "en";
+  labels = window.HarnessI18n?.[locale] || {};
+  localStorage.setItem("harness.locale", locale);
+}
+
+function app() {
+  const systemTheme = window.matchMedia?.("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  document.documentElement.dataset.theme = state.theme === "system" ? systemTheme : state.theme;
+  document.documentElement.lang = locale === "zh" ? "zh-CN" : "en";
+  const root = document.getElementById("app");
+  root.innerHTML = shell();
+  bind();
+}
+
+function shell() {
+  return `<div class="visibility-shell">
+    <header class="hero">
+      <div class="hero-copy">
+        <p class="eyebrow">${t("eyebrow")}</p>
+        <h1>${escapeHtml(projectName())} ${t("projectCockpit")}</h1>
+      </div>
+      <div class="hero-actions">
+        ${routeLink("#/", t("overview"), "overview")}
+        ${routeLink("#/tasks", t("taskIndex"), "tasks")}
+        ${routeLink("#/review", t("reviewQueue"), "review")}
+        ${routeLink("#/modules", t("moduleView"), "modules")}
+        <button data-language-toggle>${locale === "zh" ? "EN" : "中文"}</button>
+        <button data-theme-toggle>${themeLabel()}</button>
+      </div>
+    </header>
+    ${runtimeModeBanner()}
+    ${renderRoute()}
+    <div id="drawer-overlay" class="drawer-overlay"></div>
+    <div id="task-drawer" class="task-drawer"></div>
+  </div>`;
+}
+
+function runtimeModeBanner() {
+  if (window.__HARNESS_WORKBENCH__ === true) return "";
+  return `<section class="runtime-banner">
+    <strong>${t("staticReadOnly")}</strong>
+    <span>${t("staticReadOnlyDetail")}</span>
+    <code>harness dev</code>
+  </section>`;
+}
+
+function renderRoute() {
+  const route = currentRoute();
+  if (route.name === "task") return taskDetail(route);
+  if (route.name === "reviewTask") return reviewWorkspace(route);
+  if (route.name === "review") return reviewQueue();
+  if (route.name === "modules") return modulesView(route.id);
+  if (route.name === "tasks") return taskIndex();
+  return overview();
+}
+
+function currentRoute() {
+  const hash = window.location.hash || "#/";
+  const parts = hash.replace(/^#\/?/, "").split("/").filter(Boolean).map(decodeURIComponent);
+  if (parts[0] === "tasks" && parts[1]) return { name: "task", id: parts[1], doc: parts[2] === "docs" ? parts[3] || "" : "" };
+  if (parts[0] === "review" && parts[1]) return { name: "reviewTask", id: parts[1] };
+  if (parts[0] === "review") return { name: "review" };
+  if (parts[0] === "modules") return { name: "modules", id: parts[1] || "" };
+  if (parts[0] === "tasks") return { name: "tasks" };
+  return { name: "overview" };
+}
+
+function routeLink(hash, text, routeName) {
+  const active = currentRoute().name === routeName;
+  return `<a class="${active ? "active" : ""}" href="${hash}">${escapeHtml(text)}</a>`;
+}