coding-agent-harness 1.0.2 → 1.0.5

package/presets/legacy-migration/preset.yaml

@@ -0,0 +1,134 @@
+id: legacy-migration
+version: 2
+compatibleBudgets: [complex]
+localeSupport: [en-US, zh-CN]
+purpose: migrate legacy Harness projects into v1 task readability and cutover gates
+task:
+  kind: project-migration
+  defaultTaskId: harness-v1-migration
+  defaultOutcome: Create a controlled Harness v1 migration task from the recorded migrate-run session without rewriting history automatically.
+  requiresFromSession: true
+  projectLevelOnly: true
+  migrationTargetLevel: migration-baseline
+inputs:
+  session:
+    type: json-file
+    flag: --from-session
+    required: true
+    validateOperation: migrate-run
+    rejectPlanOnly: true
+    requireTarget: true
+    targetFromSession: true
+templateValues:
+  preset:
+    value: legacy-migration
+  presetVersion:
+    value: 2
+  evidenceBundle:
+    from: computed.evidenceBundle
+  migrationTargetLevel:
+    from: computed.migrationTargetLevel
+  migrationAchievedLevel:
+    from: computed.migrationAchievedLevel
+  strictDeferred:
+    from: computed.strictDeferred
+  fullCutoverClaimAllowed:
+    from: computed.fullCutoverClaimAllowed
+  warnings:
+    from: computed.warnings
+  taskActions:
+    from: computed.taskActions
+  legacyResiduals:
+    from: computed.legacyResiduals
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [session.json]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+      executionStrategyAppend: templates/execution_strategy.append.md
+      visualMapAppend: templates/visual_map.append.md
+      findingsSeed: templates/findings.seed.md
+      reviewSeed: templates/review.seed.md
+  plan:
+    type: script
+    command: scripts/plan-work-queue.mjs
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [docs/**, .git/**]
+    audit: true
+  scaffold:
+    type: script
+    command: scripts/scaffold-task-contracts.mjs
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [docs/**]
+    audit: true
+  check:
+    type: check
+    command: checks/preset-check.mjs
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [docs/**]
+    audit: true
+workbench:
+  panels: workbench/dashboard-panels.yaml
+  migrationQueueSchema: workbench/migration-queue.schema.json
+evidence:
+  bundleDir: evidence
+  files:
+    session:
+      path: session.json
+      type: input-json
+      value: inputs.session
+    migratePlan:
+      path: migrate-plan.json
+      type: json
+      value: inputs.session.plan
+    normalCheck:
+      path: normal-check.json
+      type: json
+      value: inputs.session.checks.normal
+    strictCheck:
+      path: strict-check.json
+      type: json
+      value: inputs.session.checks.strict
+    migrateVerify:
+      path: migrate-verify.json
+      type: migration-verify
+    migrationLedger:
+      path: migration-ledger.json
+      type: migration-ledger
+    presetManifest:
+      path: preset-manifest.json
+      type: preset-manifest
+    presetAudit:
+      path: preset-audit.json
+      type: preset-audit
+    writeScope:
+      path: write-scope.json
+      type: write-scope
+    dashboardHash:
+      path: dashboard.hash.txt
+      type: dashboard-hash
+    targetGitStatus:
+      path: target-git-status.txt
+      type: target-git-status
+    targetCommit:
+      path: target-commit.txt
+      type: target-commit
+    harnessVersion:
+      path: harness-version.txt
+      type: harness-version
+    generatedAt:
+      path: generated-at.txt
+      type: generated-at
+review:
+  required: true
+  materialFindingPolicy: block-open-p0-p2
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-manifest.json, preset-audit.json, write-scope.json]
+writeScopes:
+  taskArtifacts:
+    path: docs/09-PLANNING/TASKS/**
+    access: write

package/presets/legacy-migration/scripts/plan-work-queue.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+console.error("legacy-migration plan entrypoint is declared for audit and will be implemented in the v2 package slice.");
+process.exit(2);

package/presets/legacy-migration/scripts/scaffold-task-contracts.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+console.error("legacy-migration scaffold entrypoint is declared for audit and will be implemented in the v2 package slice.");
+process.exit(2);

package/presets/legacy-migration/templates/execution_strategy.append.md

@@ -0,0 +1,18 @@
+## Legacy Migration Preset Strategy
+
+This preset keeps migration inside the Complex Task contract.
+
+| Area | Rule |
+| --- | --- |
+| Write boundary | Do not rewrite historical task bodies unless the user explicitly confirms that phase. |
+| Evidence source | Use `{{evidenceBundle}}/` as the handoff bundle. Absolute session paths are origin data only. |
+| Target level | `{{migrationTargetLevel}}` |
+| Achieved level | `{{migrationAchievedLevel}}` |
+
+## Subagent Lane Table
+
+Declare lanes before dispatching workers.
+
+| Lane ID | Allowed globs | Forbidden globs | Shared file owner | Worktree / branch | Handoff path | Merge order | Verification command |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| coordinator | docs/09-PLANNING/TASKS/** | AGENTS.md, CLAUDE.md, docs/Harness-Ledger.md until closeout | coordinator | current | progress.md | 1 | harness check --profile target-project . |

package/presets/legacy-migration/templates/findings.seed.md

@@ -0,0 +1,17 @@
+## Legacy Migration Action Buckets
+
+| Bucket | Count | Owner | Status | Next Action |
+| --- | ---: | --- | --- | --- |
+| warnings | {{warnings}} | coordinator | open | Triage before increasing target level |
+| taskActions | {{taskActions}} | coordinator | open | Upgrade only current/reopened/current-evidence tasks |
+| legacyResiduals | {{legacyResiduals}} | coordinator | open | Assign real owner before full cutover |
+
+## Residual Policy
+
+Residuals require reason, owner, trigger, next action, and reviewer. Placeholder owner `migration-owner` is not a real owner.
+
+## Status Conflict Table
+
+| Item | Competing Evidence | Chosen Classification | Confidence | Human Needed |
+| --- | --- | --- | --- | --- |
+| pending | session / SSoT / progress / git | pending | medium | yes |

package/presets/legacy-migration/templates/review.seed.md

@@ -0,0 +1,12 @@
+## Legacy Migration Preset Gate
+
+`migration-full-cutover` can only be claimed when the final session proves all gates:
+
+- final session result is `complete`
+- strict check passes
+- `migrate-verify --full-cutover` passes
+- warnings/actions/residuals/strictDeferred are zero
+- dashboard evidence is readable
+- review has no open P0/P1/P2 blocker
+
+Current achieved level: `{{migrationAchievedLevel}}`.

package/presets/legacy-migration/templates/task_plan.append.md

@@ -0,0 +1,9 @@
+## Legacy Migration Preset
+
+This Complex Task uses the `{{preset}}` preset package. The preset only scaffolds the migration task and records evidence at creation time. It does not run migration, rewrite historical task bodies, stage files, or commit changes.
+
+- Preset version: `{{presetVersion}}`
+- Baseline session: `{{evidenceBundle}}/session.json`
+- Migration plan: `{{evidenceBundle}}/migrate-plan.json`
+- Strict deferred: {{strictDeferred}}
+- Full-cutover claim allowed now: {{fullCutoverClaimAllowed}}

package/presets/legacy-migration/templates/visual_map.append.md

@@ -0,0 +1,12 @@
+## Legacy Migration Preset Flow
+
+```mermaid
+flowchart TD
+  A["Recorded migrate-run session"] --> B["Create Complex Task preset"]
+  B --> C["Baseline usable"]
+  C --> D{"User confirms deeper cutover?"}
+  D -- no --> E["Keep residuals owned"]
+  D -- yes --> F["Current work cutover"]
+  F --> G["Historical consolidation"]
+  G --> H["Strict / full-cutover verify"]
+```

package/presets/legacy-migration/workbench/dashboard-panels.yaml

@@ -0,0 +1,2 @@
+id: legacy-migration
+panels: [migration-queue, task-evidence, human-confirmation]

package/presets/legacy-migration/workbench/migration-queue.schema.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "legacy-migration-queue/v2",
+  "staticDashboardRole": "evidence-snapshot",
+  "workbenchRole": "human-confirmation-control-plane",
+  "requiredItemFields": [
+    "taskId",
+    "phase",
+    "mechanicalState",
+    "semanticState",
+    "evidenceSources",
+    "reviewState",
+    "confirmationState",
+    "owner",
+    "residual"
+  ],
+  "allowedPhases": [
+    "baseline",
+    "mechanical-scaffold",
+    "semantic-reconstruction",
+    "cutover-review"
+  ],
+  "semanticRule": "Semantic reconstruction requires evidenceSources and cannot be marked complete by scaffold-only automation."
+}

package/presets/lesson-sedimentation/preset.yaml

@@ -0,0 +1,23 @@
+id: lesson-sedimentation
+version: 1
+purpose: Create a follow-up task for reviewing and sedimenting an accepted lesson candidate into a promoted detail doc.
+compatibleBudgets: [standard, complex]
+localeSupport: [en-US, zh-CN]
+task:
+  kind: lesson-sedimentation
+  projectLevelOnly: true
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/TASKS/**]
+    reads: [docs/09-PLANNING/TASKS/**/lesson_candidates.md]
+    audit: true
+    templates:
+      prompt: templates/prompt.md
+writeScopes:
+  taskDocs:
+    path: docs/09-PLANNING/TASKS/**
+    access: write
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json]

package/presets/lesson-sedimentation/templates/prompt.md

@@ -0,0 +1,23 @@
+You are executing a lesson sedimentation follow-up task.
+
+Source task: {{sourceTaskId}}
+Source candidate: {{candidateId}} - {{candidateTitle}}
+Follow-up task: {{followUpTaskId}}
+
+Candidate scope: {{candidateScope}}
+Candidate module key: {{candidateModuleKey}}
+Detail artifact: {{detailArtifact}}
+Boundary reason: {{boundaryReason}}
+Why it might matter: {{whyItMightMatter}}
+Promotion target: {{promotionTarget}}
+Conflict check: {{conflictCheck}}
+Required standard update: {{requiredStandardUpdate}}
+
+Instructions:
+
+1. Read the source task, its review, findings, progress, lesson_candidates.md, and the task-local detail artifact.
+2. Classify whether the lesson is task-local, module-local, or global; if module-local, preserve the module key/path.
+3. Check for conflicts with existing lesson candidates, promoted lesson detail docs, public docs, and relevant standards.
+4. Propose the smallest diff needed to preserve the lesson.
+5. Do not write a shared Lessons table; accepted candidates become promoted lesson detail docs or target standard updates.
+6. Record evidence and residual risks in the follow-up task before asking for review.

package/presets/module/preset.yaml

@@ -0,0 +1,25 @@
+id: module
+version: 1
+purpose: Create module-scoped tasks with module context entry points and auditable preset metadata.
+compatibleBudgets: [simple, standard, complex]
+localeSupport: [en-US, zh-CN]
+task:
+  kind: module-task
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/**]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+      executionStrategyAppend: templates/execution_strategy.append.md
+templateValues:
+  moduleKey:
+    from: task.moduleKey
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json]
+writeScopes:
+  planningDocs:
+    path: docs/09-PLANNING/**
+    access: write

package/presets/module/templates/execution_strategy.append.md

@@ -0,0 +1,8 @@
+## Module Preset Strategy
+
+| Field | Value |
+| --- | --- |
+| Module Key | {{moduleKey}} |
+| Module Plan | docs/09-PLANNING/MODULES/{{moduleKey}}/module_plan.md |
+
+Keep shared module decisions in the module plan or module context files. Keep task-specific evidence in this task directory.

package/presets/module/templates/task_plan.append.md

@@ -0,0 +1,17 @@
+## Module Preset
+
+This module task was created through the `module` preset.
+
+| Field | Value |
+| --- | --- |
+| Module Key | {{moduleKey}} |
+
+## Module Context Entry Points
+
+Read these module-level entry points before changing shared module behavior. Continue into narrower context only when the task surface requires it.
+
+| Reference | Path | Why / When |
+| --- | --- | --- |
+| Module brief | docs/09-PLANNING/MODULES/{{moduleKey}}/brief.md | Start here for the module purpose and current scope. |
+| Module plan | docs/09-PLANNING/MODULES/{{moduleKey}}/module_plan.md | Use this for module steps, active task links, and handoff state. |
+| Module visual map | docs/09-PLANNING/MODULES/{{moduleKey}}/visual_map.md | Inspect when the change affects module sequencing or dependencies. |

package/presets/standard-task/preset.yaml

@@ -0,0 +1,31 @@
+id: standard-task
+version: 1
+purpose: Create a standard task using the generic declarative preset engine.
+compatibleBudgets: [standard, complex]
+localeSupport: [en-US, zh-CN]
+task:
+  kind: standard-task
+  defaultTaskId: standard-task
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/TASKS/**]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+templateValues:
+  title:
+    from: task.title
+evidence:
+  bundleDir: artifacts/preset
+  files:
+    presetAudit:
+      path: preset-audit.json
+      type: preset-audit
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json]
+writeScopes:
+  taskDocs:
+    path: docs/09-PLANNING/TASKS/**
+    access: write

package/presets/standard-task/templates/task_plan.append.md

@@ -0,0 +1,7 @@
+## Standard Task Preset
+
+This task was created through the declarative `standard-task` preset.
+
+| Field | Value |
+| --- | --- |
+| Preset Title | {{title}} |

package/references/adversarial-review-standard.md

@@ -102,7 +102,7 @@ Reviewer 必须以找问题为目标，而不是证明实现正确。
 - Progress:
 - Findings:
 - Regression SSoT:
-- Lessons SSoT:
+- Lesson Candidates / Detail Docs:
 - Walkthrough:
 ```
 
@@ -150,7 +150,7 @@ Review loop 的固定执行形态：
 - `progress.md` 记录审查发生的时间和处理结果摘要
 - `findings.md` 记录审查中产生的技术决策或研究发现
 - `Regression-SSoT.md` 记录新增或调整的 regression surface
-- `Lessons-SSoT.md` 记录可复用的流程、架构或标准改进建议
+- `lesson_candidates.md` 和 `docs/01-GOVERNANCE/lessons/*.md` 记录可复用的流程、架构或标准改进建议
 - `walkthrough` 收口时引用 `review.md` 的 material finding 状态和 no-finding 结论
 - `Harness Ledger` 记录本轮是否完成 review report
 

package/references/agents-md-pattern.md

@@ -40,7 +40,7 @@ AGENTS.md 只包含两类内容：
   先读 docs/11-REFERENCE/harness-ledger-standard.md
 
 - Walkthrough / Closeout / Lessons 收口：
-  先读 docs/11-REFERENCE/walkthrough-standard.md，然后读 docs/01-GOVERNANCE/Lessons-SSoT.md 和 docs/10-WALKTHROUGH/Closeout-SSoT.md
+  先读 docs/11-REFERENCE/walkthrough-standard.md，然后读 docs/10-WALKTHROUGH/Closeout-SSoT.md、任务本地 lesson_candidates.md 和 docs/01-GOVERNANCE/lessons/
 
 - 开发执行 / 回写流程：
   先读 docs/11-REFERENCE/execution-workflow-standard.md
@@ -100,7 +100,7 @@ CLAUDE.md 控制在 **10-50 行**。它只做 Claude Code 兼容入口，不应
 - agent 做后端重构时，不会被前端规范干扰
 - agent 做测试时，不会被文档治理规则分心
 - 每种任务类型只加载它需要的上下文
-- agent 写 walkthrough 时会被入口显式路由回 Lessons SSoT，但 Lessons 全文不会塞进 AGENTS.md
+- agent 写 walkthrough 时会被入口显式路由回 lesson candidate / detail doc 流程，但 Lessons 全文不会塞进 AGENTS.md
 
 这跟 OpenAI 在 Harness Engineering 实践中得出的结论一致：给 agent 一张地图，不给一本千页手册。
 

package/references/delivery-operating-model-standard.md

@@ -39,7 +39,7 @@ Define who breaks roadmap work into feature blocks:
 | Level | Owner | Artifact | Rule |
 |-------|-------|----------|------|
 | Roadmap | [owner] | [SSoT / issue tracker] | [how priority is chosen] |
-| Feature block | [owner] | `Delivery-SSoT.md` / Feature SSoT | [how blocks are bounded] |
+| Feature block | [owner] | `Delivery-SSoT.md` / generated Harness Ledger | [how blocks are bounded] |
 | Task | [owner] | `docs/09-PLANNING/TASKS/<task>/task_plan.md` | [who can start work] |
 | Review | [owner] | `review.md` / PR review | [required reviewers] |
 | Integration | [owner] | PR / release branch / integration branch | [merge order] |
@@ -50,14 +50,14 @@ Define who breaks roadmap work into feature blocks:
 
 Use when one human directs multiple agents across worktrees.
 
-- One primary Feature SSoT is enough for linear phase work.
+- One generated Harness Ledger is enough for ordinary task lifecycle tracking.
 - Worktree concurrency is central.
 - Merge order is human-decided.
 - Cross-task conflicts are managed by task ownership and shared-file notices.
 
 **模块并行扩展**：当项目有 2+ 个可独立演进的功能域时，启用模块并行开发（见 `references/module-parallel-standard.md`）。此时：
 
-- Module Registry 替代 Feature SSoT 作为进度追踪的主要工具
+- Module Registry 管模块边界；Harness Ledger 生成全局任务生命周期索引
 - 每个模块一个长期 worktree（`codex/<module-key>`）
 - 模块间通过 write scope 声明避免冲突
 - 跨模块修改走独立的基础设施 task

package/references/docs-directory-standard.md

@@ -8,12 +8,11 @@
 
 ```
 docs/
-├── Harness-Ledger.md           ← 全局 harness 上下文回写总账
+├── Harness-Ledger.md           ← CLI 生成的任务生命周期总账
 ├── 00-RAW-PRDS/              ← 原始需求文档、PRD、用户故事
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
 ├── 01-GOVERNANCE/             ← 项目治理规则、决策记录、经验沉淀
-│   ├── Lessons-SSoT.md        ← 经验沉淀建议表
-│   ├── lessons/               ← 具体沉淀内容
+│   ├── lessons/               ← promoted lesson 详情文档
 │   └── _archive/              ← 已处理条目归档
 ├── 02-PRODUCT/                ← 产品设计、用户流程、功能规格
 │   └── _archive/              ← 本层历史文档归档（如该层会增长）
@@ -34,9 +33,8 @@ docs/
 │   │   └── _task-template/    ← 任务模板
 │   ├── MODULES/               ← 模块并行开发计划（启用时）
 │   │   └── _archive/          ← 已完成 / 暂停过久模块归档
-│   ├── _archive/              ← 历史任务、旧 Feature SSoT 明细、过期排期归档
+│   ├── _archive/              ← 历史任务、旧生命周期表明细、过期排期归档
 │   ├── Delivery-SSoT.md       ← 多人 / 多仓 / 传统流程下的交付排期和集成顺序
-│   └── [Feature-SSoT].md     ← 实施排期表
 ├── 10-WALKTHROUGH/            ← Walkthrough 收口记录与 Closeout SSoT
 │   └── _archive/              ← 历史 walkthrough 批量归档（迁移 / 年度收束时）
 ├── 11-REFERENCE/              ← 标准文件（agent 按需加载）
@@ -133,11 +131,11 @@ Checker 规则：
 
 | 对象 | 触发条件 | 归档位置 |
 |------|----------|----------|
-| Feature SSoT Active 表 | 模块并行切换、release 完成、或 completed rows 超过 20 条 | `09-PLANNING/_archive/` |
+| Legacy Feature / Private Feature 生命周期表 | 迁移到 ledger-only 版本 | `09-PLANNING/_archive/` |
 | Delivery SSoT | 集成 wave 结束或 completed/superseded blocks 超过 20 条 | `09-PLANNING/_archive/` |
 | Module Registry / module_plan | 模块 completed 或 paused 超过 60 天 | `09-PLANNING/MODULES/_archive/<key>/` |
 | Regression SSoT | gate 废弃或长期不再运行 | `05-TEST-QA/_archive/` |
-| Lessons SSoT | merged/rejected 条目超过 20 条 | `01-GOVERNANCE/_archive/` |
+| Lesson detail docs | merged/rejected/superseded 详情文档超过 20 条 | `01-GOVERNANCE/_archive/` |
 | Harness Ledger | closed/superseded 超过 50 条 | `01-GOVERNANCE/_archive/` |
 | Walkthrough | 年度/阶段迁移或目录过大 | `10-WALKTHROUGH/_archive/` |
 
@@ -151,6 +149,7 @@ Checker 规则：
 | execution-workflow-standard.md | 开发执行流程、commit 规范、PR 流程 | 是 |
 | delivery-operating-model-standard.md | 工程组织形态、feature block 拆分、跨仓/团队协作模型 | 是 |
 | repo-governance-standard.md | repo platform、branch protection、PR policy、required checks、worktree concurrency | 是 |
+| pull-request-standard.md | PR 描述结构、中英双语要求、版本影响、验证、审查证据、残余风险和引用 | 是 |
 | ci-cd-standard.md | CI/CD profile、workflow、required checks、release/CD residual | 是 |
 | long-running-task-standard.md | 长程任务合同、连续执行权限、review loop、停止条件 | 是 |
 | adversarial-review-standard.md | 对抗性 review 报告、finding 分级、no-finding 结论、residual 路由 | 是 |