coding-agent-harness 1.0.7 → 1.1.0

package/docs-release/guides/typescript-runtime-migration-closeout.md

@@ -1,25 +1,26 @@
 # TypeScript Runtime Migration Closeout
 
 This closeout records the public package rule after the progressive JavaScript to
-TypeScript runtime migration. The package now executes committed
-`dist/**/*.mjs` artifacts, while `scripts/**/*.mts` and `tests/**/*.mts` are the
-source ownership surfaces. Historical checked-in `scripts/**/*.mjs` and
-`tests/**/*.mjs` shims have been removed after the dist observation gates passed.
+TypeScript runtime migration. The package executes generated `dist/**/*.mjs`
+artifacts, while `scripts/**/*.mts` and `tests/**/*.mts` are the source ownership
+surfaces. Historical checked-in `scripts/**/*.mjs` and `tests/**/*.mjs` shims
+have been removed after the dist observation gates passed.
 
 ## Current State
 
 All Node runtime and test sources under `scripts/` and `tests/` are now
 TypeScript-first:
 
-- `scripts/**/*.mts` builds to committed `dist/**/*.mjs` artifacts.
+- `scripts/**/*.mts` builds to generated `dist/**/*.mjs` artifacts.
 - `tests/**/*.mts` runs through the built test runner.
-- `dist/**/*.mjs` is the package runtime surface for npm bin, npm scripts, and
-  postinstall.
+- `dist/**/*.mjs` is the package runtime surface for npm bin and installed
+  execution. Source checkout npm scripts refresh it before running.
 - `scripts/**/*.mjs` and `tests/**/*.mjs` have a final inventory of zero.
 
-The npm package publishes `dist/` and no longer publishes `scripts/` or `tests/`.
-This keeps installed execution independent from TypeScript source files and from
-the deleted historical shims.
+The source repository ignores `dist/`, but the npm package publishes generated
+`dist/` and no longer publishes `scripts/` or `tests/`. This keeps installed
+execution independent from TypeScript source files and from the deleted
+historical shims.
 
 ## Final Closeout Evidence
 
@@ -42,12 +43,15 @@ dashboard exceptions below.
 ## Runtime Contract
 
 The package is an ESM package and its current public runtime contract points at
-the committed dist build output:
+generated dist build output:
 
 - `package.json` maps the `harness` executable to `dist/harness.mjs`.
-- npm postinstall runs `dist/postinstall.mjs`.
+- npm postinstall runs the source-safe `postinstall.mjs` bootstrap, which
+  delegates to `dist/postinstall.mjs` after generating `dist/` in a source
+  checkout.
 - npm helper scripts such as `check`, `status`, and dashboard generation run
-  through `dist/harness.mjs`.
+  through `run-dist.mjs`, which refreshes `dist/` in a source checkout and then
+  runs the relevant dist entrypoint.
 - Runtime modules import sibling `.mjs` files inside `dist/`, so installed
   package execution does not depend on TypeScript loaders.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-agent-harness",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Document governance kernel for long-running coding agents.",
   "type": "module",
   "keywords": [
@@ -26,20 +26,23 @@
     "harness": "dist/harness.mjs"
   },
   "scripts": {
-    "check": "node dist/harness.mjs check --profile source-package .",
-    "check:private": "node dist/harness.mjs check --profile private-harness .harness-private",
+    "check": "node run-dist.mjs harness.mjs check --profile source-package .",
+    "check:private": "node run-dist.mjs harness.mjs check --profile private-harness .harness-private",
     "build:runtime": "node scripts/build-dist.mts",
     "prepack": "node scripts/build-dist.mts --quiet",
+    "prepublishOnly": "node run-dist.mjs check-dist-observation.mjs --skip-install-smoke",
+    "prepare": "node postinstall.mjs --build-only",
     "typecheck": "npm exec --yes --package typescript@5.9.3 -- tsc -p tsconfig.json",
-    "typecheck:guards": "node dist/check-type-boundaries.mjs",
-    "status": "node dist/harness.mjs status --json .",
-    "dashboard": "node dist/harness.mjs dashboard --out tmp/harness-dashboard.html examples/minimal-project",
-    "dashboard:folder": "node dist/harness.mjs dashboard --out-dir tmp/harness-dashboard examples/minimal-project",
+    "typecheck:guards": "node run-dist.mjs check-type-boundaries.mjs && node run-dist.mjs check-no-ts-nocheck.mjs",
+    "check:nocheck": "node run-dist.mjs check-no-ts-nocheck.mjs",
+    "status": "node run-dist.mjs harness.mjs status --json .",
+    "dashboard": "node run-dist.mjs harness.mjs dashboard --out tmp/harness-dashboard.html examples/minimal-project",
+    "dashboard:folder": "node run-dist.mjs harness.mjs dashboard --out-dir tmp/harness-dashboard examples/minimal-project",
     "pack:dry-run": "npm pack --dry-run --json",
-    "postinstall": "node dist/postinstall.mjs",
-    "observe:dist": "node dist/check-dist-observation.mjs --skip-pack --skip-install-smoke",
-    "smoke:dashboard": "node dist/run-built-tests.mjs --test tests/smoke-dashboard.mjs",
-    "test": "node dist/run-built-tests.mjs"
+    "postinstall": "node postinstall.mjs",
+    "observe:dist": "node run-dist.mjs check-dist-observation.mjs --skip-pack --skip-install-smoke",
+    "smoke:dashboard": "node run-dist.mjs run-built-tests.mjs --test tests/smoke-dashboard.mjs",
+    "test": "node run-dist.mjs run-built-tests.mjs"
   },
   "files": [
     "README.md",
@@ -48,6 +51,8 @@
     "CONTRIBUTING.md",
     "CHANGELOG.md",
     "SKILL.md",
+    "postinstall.mjs",
+    "run-dist.mjs",
     "tsconfig.json",
     "tsconfig.dist.json",
     "tsconfig.runtime.json",
@@ -62,6 +67,9 @@
     "docs-release/",
     "examples/"
   ],
+  "devDependencies": {
+    "@types/node": "24"
+  },
   "engines": {
     "node": ">=24"
   },

package/postinstall.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const buildScript = path.join(root, "scripts/build-dist.mts");
+const distPostinstall = path.join(root, "dist/postinstall.mjs");
+const buildOnly = process.argv.includes("--build-only");
+const skipPostinstall = process.env.CODING_AGENT_HARNESS_SKIP_POSTINSTALL === "1";
+
+function runBuild() {
+  if (!fs.existsSync(buildScript)) return false;
+  const result = spawnSync(process.execPath, [buildScript, "--quiet"], {
+    cwd: root,
+    stdio: "inherit",
+  });
+  if (result.status !== 0) process.exit(result.status ?? 1);
+  return true;
+}
+
+if (!fs.existsSync(distPostinstall)) {
+  runBuild();
+}
+
+if (buildOnly || skipPostinstall) {
+  process.exit(0);
+}
+
+if (!fs.existsSync(distPostinstall)) {
+  console.error("coding-agent-harness postinstall failed: missing dist/postinstall.mjs");
+  console.error("Run npm run build:runtime from a source checkout, or reinstall a complete package.");
+  process.exit(1);
+}
+
+await import(pathToFileURL(distPostinstall).href);

package/presets/legacy-migration/preset.yaml

@@ -43,7 +43,7 @@ templateValues:
 entrypoints:
   newTask:
     type: template
-    writes: [coding-agent-harness/planning/tasks/**]
+    writes: [{{paths.tasksRoot}}/**]
     reads: [session.json]
     audit: true
     templates:
@@ -55,19 +55,19 @@ entrypoints:
   plan:
     type: script
     command: scripts/plan-work-queue.mjs
-    writes: [coding-agent-harness/planning/tasks/**]
+    writes: [{{paths.tasksRoot}}/**]
     reads: [docs/**, .git/**]
     audit: true
   scaffold:
     type: script
     command: scripts/scaffold-task-contracts.mjs
-    writes: [coding-agent-harness/planning/tasks/**]
+    writes: [{{paths.tasksRoot}}/**]
     reads: [docs/**]
     audit: true
   check:
     type: check
     command: checks/preset-check.mjs
-    writes: [coding-agent-harness/planning/tasks/**]
+    writes: [{{paths.tasksRoot}}/**]
     reads: [docs/**]
     audit: true
 workbench:
@@ -130,5 +130,5 @@ audit:
   evidenceFiles: [preset-manifest.json, preset-audit.json, write-scope.json]
 writeScopes:
   taskArtifacts:
-    path: coding-agent-harness/planning/tasks/**
+    path: {{paths.tasksRoot}}/**
     access: write

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

@@ -15,4 +15,4 @@ Declare lanes before dispatching workers.
 
 | Lane ID | Allowed globs | Forbidden globs | Shared file owner | Worktree / branch | Handoff path | Merge order | Verification command |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| coordinator | coding-agent-harness/planning/tasks/** | AGENTS.md, CLAUDE.md, coding-agent-harness/governance/generated/Harness-Ledger.md until closeout | coordinator | current | progress.md | 1 | harness check --profile target-project . |
+| coordinator | {{paths.harnessRoot}}/planning/tasks/** | AGENTS.md, CLAUDE.md, {{paths.harnessRoot}}/governance/generated/Harness-Ledger.md until closeout | coordinator | current | progress.md | 1 | harness check --profile target-project . |

package/presets/lesson-sedimentation/preset.yaml

@@ -9,14 +9,14 @@ task:
 entrypoints:
   newTask:
     type: template
-    writes: [coding-agent-harness/planning/tasks/**]
-    reads: [coding-agent-harness/planning/tasks/**/lesson_candidates.md]
+    writes: [{{paths.tasksRoot}}/**]
+    reads: [{{paths.tasksRoot}}/**/lesson_candidates.md]
     audit: true
     templates:
       prompt: templates/prompt.md
 writeScopes:
   taskDocs:
-    path: coding-agent-harness/planning/tasks/**
+    path: {{paths.tasksRoot}}/**
     access: write
 audit:
   manifestRequired: true

package/presets/module/preset.yaml

@@ -8,7 +8,7 @@ task:
 entrypoints:
   newTask:
     type: template
-    writes: [coding-agent-harness/planning/**]
+    writes: [{{paths.planningRoot}}/**]
     audit: true
     templates:
       taskPlanAppend: templates/task_plan.append.md
@@ -21,5 +21,5 @@ audit:
   evidenceFiles: [preset-audit.json]
 writeScopes:
   planningDocs:
-    path: coding-agent-harness/planning/**
+    path: {{paths.planningRoot}}/**
     access: write

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

@@ -3,6 +3,6 @@
 | Field | Value |
 | --- | --- |
 | Module Key | {{moduleKey}} |
-| Module Plan | coding-agent-harness/planning/modules/{{moduleKey}}/module_plan.md |
+| Module Plan | {{paths.harnessRoot}}/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

@@ -12,6 +12,6 @@ Read these module-level entry points before changing shared module behavior. Con
 
 | Reference | Path | Why / When |
 | --- | --- | --- |
-| Module brief | coding-agent-harness/planning/modules/{{moduleKey}}/brief.md | Start here for the module purpose and current scope. |
-| Module plan | coding-agent-harness/planning/modules/{{moduleKey}}/module_plan.md | Use this for module steps, active task links, and handoff state. |
-| Module visual map | coding-agent-harness/planning/modules/{{moduleKey}}/visual_map.md | Inspect when the change affects module sequencing or dependencies. |
+| Module brief | {{paths.harnessRoot}}/planning/modules/{{moduleKey}}/brief.md | Start here for the module purpose and current scope. |
+| Module plan | {{paths.harnessRoot}}/planning/modules/{{moduleKey}}/module_plan.md | Use this for module steps, active task links, and handoff state. |
+| Module visual map | {{paths.harnessRoot}}/planning/modules/{{moduleKey}}/visual_map.md | Inspect when the change affects module sequencing or dependencies. |

package/presets/release-closeout/checks/check-release-package.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const context = JSON.parse(fs.readFileSync(process.env.HARNESS_PRESET_CONTEXT, "utf8"));
+const release = String(context.inputs.release || "").trim();
+const governanceRoot = context.paths?.governanceRoot;
+if (!governanceRoot) {
+  console.error("release-closeout check requires structure-aware context.paths from the preset runner");
+  process.exit(2);
+}
+const releaseRoot = path.join(context.targetRoot, governanceRoot, "releases", release);
+const required = ["INDEX.md", "task-aggregate.json", "task-archive-plan.md", "public-summary.md", "public-redaction-report.json"];
+const missing = required.filter((file) => !fs.existsSync(path.join(releaseRoot, file)));
+if (missing.length) {
+  console.error(`release package missing files: ${missing.join(", ")}`);
+  process.exit(2);
+}
+const redaction = JSON.parse(fs.readFileSync(path.join(releaseRoot, "public-redaction-report.json"), "utf8"));
+if (redaction.status !== "pass") {
+  console.error("release public redaction report is not passing");
+  process.exit(3);
+}
+fs.writeFileSync(context.materializationManifestPath, `${JSON.stringify({
+  schemaVersion: "preset-materialization/v1",
+  status: "pass",
+  writes: [],
+}, null, 2)}\n`);

package/presets/release-closeout/preset.yaml

@@ -0,0 +1,100 @@
+id: release-closeout
+version: 1
+purpose: Create and run a release closeout task that aggregates version tasks into an auditable release package
+compatibleBudgets: [complex]
+localeSupport: [en-US, zh-CN]
+task:
+  kind: release-closeout
+  defaultTaskId: release-closeout
+  defaultOutcome: Produce a release closeout task whose runner entrypoints generate the version package, archive plan, and public summary.
+  projectLevelOnly: true
+inputs:
+  release:
+    type: text
+    flag: --release
+    required: true
+  previousRelease:
+    type: text
+    flag: --previous-release
+    required: false
+  nextRelease:
+    type: text
+    flag: --next-release
+    required: false
+  taskQuery:
+    type: text
+    flag: --task-query
+    required: false
+  taskList:
+    type: json-file
+    flag: --task-list
+    required: false
+  publicSummary:
+    type: flag
+    flag: --public-summary
+    required: false
+templateValues:
+  release:
+    from: inputs.release
+  previousRelease:
+    from: inputs.previousRelease
+  nextRelease:
+    from: inputs.nextRelease
+  taskQuery:
+    from: inputs.taskQuery
+  taskId:
+    from: task.id
+entrypoints:
+  newTask:
+    type: template
+    writes: [{{paths.tasksRoot}}/**]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+      executionStrategyAppend: templates/execution_strategy.append.md
+      findingsSeed: templates/findings.seed.md
+      reviewSeed: templates/review.seed.md
+  plan:
+    type: script
+    command: scripts/generate-release-package.mjs
+    writes: [{{paths.governanceRoot}}/releases/**]
+    reads: [{{paths.tasksRoot}}/**, {{paths.modulesRoot}}/**]
+    audit: true
+  scaffold:
+    type: script
+    command: scripts/generate-release-package.mjs
+    writes: [{{paths.governanceRoot}}/releases/**]
+    reads: [{{paths.tasksRoot}}/**, {{paths.modulesRoot}}/**]
+    audit: true
+  check:
+    type: check
+    command: checks/check-release-package.mjs
+    writes: [{{paths.governanceRoot}}/releases/**]
+    reads: [{{paths.governanceRoot}}/releases/**, {{paths.tasksRoot}}/**, {{paths.modulesRoot}}/**]
+    audit: true
+evidence:
+  bundleDir: artifacts/preset
+  files:
+    release:
+      path: release.txt
+      type: text
+      value: inputs.release
+    presetAudit:
+      path: preset-audit.json
+      type: preset-audit
+    presetManifest:
+      path: preset-manifest.json
+      type: preset-manifest
+    writeScope:
+      path: write-scope.json
+      type: write-scope
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
+writeScopes:
+  taskDocs:
+    path: {{paths.tasksRoot}}/**
+    access: write
+  releasePackage:
+    path: {{paths.governanceRoot}}/releases/**
+    access: write