@codedology/code-forge 0.1.0

package/docs/reference/blocks.json

@@ -0,0 +1,288 @@
+{
+  "$comment": "hand-maintained; checked against plan §10.4 + NIGHT-LOG by test/docs-blocks.test.mjs. Ids = every `| **Bxx** |` row in plans/code-forge-plan-v1.3.md §10.4 Waves 2-6 (19 ids), plus the blocks the root orchestrator added during the night run of 2026-09-25 that are not in that table (plans/NIGHT-LOG.md): B1.2, B4.1, B11.1, B12c (B3.1 was already in the v1.3 §10.4 table). Wave 0-1 blocks (B0-B8) are the pre-v1.3 baseline landed before this plan revision; they have no entry under blocks and are listed in baseline_ids so every depends_on id resolves; see plans/code-forge-plan-v1.3.md §10.2-§10.3 for their record. B10c is listed with deleted:true — the maintainer answered Q16 'cut' on 2026-09-25, so B10c (consumer-facing mutation-testing tools) never lands.",
+  "checked_against": [
+    "plans/code-forge-plan-v1.3.md §10.4",
+    "plans/NIGHT-LOG.md"
+  ],
+  "block_count": 23,
+  "baseline_ids": ["B0", "B1", "B2", "B3", "B4", "B5", "B6", "B7", "B8"],
+  "baseline_note": "Wave 0-1 blocks, landed before v1.3; depends_on may name them, but they have no entry under blocks.",
+  "blocks": {
+    "B0.1": {
+      "title": "B0 follow-up: exec stdin input + pid registry, git.mjs GIT_* strip, per-run temp root, orphan reaper, test preload, Stryker removal (R14)",
+      "wave": 2,
+      "level": "L2",
+      "status": "landed",
+      "commit": "cb54864",
+      "owned": [
+        "src/util/exec.mjs", "src/util/git.mjs", "src/util/tmp.mjs", "src/util/reaper.mjs",
+        "test/util/exec.test.mjs", "test/util/git.test.mjs", "test/util/tmp.test.mjs", "test/util/reaper.test.mjs",
+        "test/helpers/isolate.mjs", "test/harness-isolation.test.mjs", "test/no-leak.test.mjs", "test/router.test.mjs",
+        "package.json", "npm-shrinkwrap.json", ".gitignore", ".github/workflows/ci.yml", "stryker.config.mjs (deleted)"
+      ],
+      "depends_on": ["B0"]
+    },
+    "B1.1": {
+      "title": "Schema amendment: the six v1.3 keys, caps.coders 2, two refusals + one warning",
+      "wave": 2,
+      "level": "L1",
+      "status": "landed",
+      "commit": "1cc1de4",
+      "owned": [
+        "schema/code-forge.schema.json", "src/config/validate.mjs", "src/config/schema-paths.mjs",
+        "src/config/defaults/anthropic.mjs", "src/config/defaults/openai.mjs", "src/config/defaults/xai.mjs", "src/config/defaults/index.mjs",
+        "test/config/schema.test.mjs", "test/config/schema-paths.test.mjs", "test/config/validate.test.mjs", "test/config/defaults.test.mjs",
+        "test/fixtures/config/valid-full.code-forge.yml"
+      ],
+      "depends_on": ["B1"]
+    },
+    "B1.2": {
+      "title": "Schema cut (Q16 = cut): remove mutation-tool proof keys (proof.tiers.high.tool/min_msi, proof.js, proof.nightly)",
+      "wave": 2,
+      "level": "L1",
+      "status": "landed",
+      "commit": "1749768",
+      "owned": [
+        "schema/code-forge.schema.json", "src/config/validate.mjs",
+        "test/config/schema-coverage.test.mjs", "test/config/schema.test.mjs", "test/config/secret-leak-cases.mjs", "test/config/validate.test.mjs"
+      ],
+      "depends_on": ["B1.1"],
+      "note": "root-added (night run), not in the v1.3 §10.4 table; landed the Q16 = cut ruling in the schema"
+    },
+    "B10a": {
+      "title": "Proof: two tiers, measurement export (hardened, C5), proof lock, proof verb (baseline, restore, lock)",
+      "wave": 2,
+      "level": "L2",
+      "status": "landed",
+      "commit": "eb969fb",
+      "owned": [
+        "src/proof/tiers.mjs", "src/proof/export.mjs", "src/proof/lock.mjs", "src/cli/proof.mjs",
+        "test/proof/tiers.test.mjs", "test/proof/export.test.mjs", "test/proof/lock.test.mjs", "test/proof/helpers.mjs",
+        "test/fixtures/repos/export-ignore/**"
+      ],
+      "depends_on": ["B3", "B5", "B6", "B8"]
+    },
+    "B9a": {
+      "title": "Isolated sessions: spawn verb (stdin piping V3, outPath, background, pid file + registry, logs, usage, retry ladder V9), s2",
+      "wave": 2,
+      "level": "L2",
+      "status": "landed",
+      "commit": "fc75988",
+      "owned": [
+        "src/session/spawn.mjs", "src/session/s2.mjs", "src/cli/spawn.mjs", "src/cli/s2.mjs",
+        "test/session/spawn.test.mjs", "test/session/s2.test.mjs", "test/session/helpers.mjs", "test/fixtures/bin/**"
+      ],
+      "depends_on": ["B0.1", "B1", "B4", "B6", "B8"]
+    },
+    "B2.1": {
+      "title": "Keys follow-up: security backend writes through stdin",
+      "wave": 2,
+      "level": "L2",
+      "status": "landed",
+      "commit": "1e58b0b",
+      "owned": [
+        "src/keys/backends/security-cli.mjs", "test/keys/backends.test.mjs"
+      ],
+      "depends_on": ["B0.1", "B2"]
+    },
+    "B10b": {
+      "title": "Proof: journaled red->green runner, red-parse (O13)",
+      "wave": 2,
+      "level": "L2",
+      "status": "landed",
+      "commit": "9fd7907",
+      "owned": [
+        "src/proof/red-green.mjs", "src/proof/red-parse.mjs",
+        "test/proof/red-green.test.mjs", "test/proof/red-parse.test.mjs", "test/fixtures/repos/red-green/**"
+      ],
+      "depends_on": ["B10a"]
+    },
+    "B11": {
+      "title": "Worker: queue, tickets, loop, worker verb, review-file enqueue/--wait, key resolution inside the worker, root-relative rows (V4)",
+      "wave": 2,
+      "level": "L2",
+      "status": "landed",
+      "commit": "6b3a68c",
+      "owned": [
+        "src/worker/**", "src/cli/worker.mjs", "src/cli/review-file.mjs", "test/worker/**"
+      ],
+      "depends_on": ["B0.1", "B2", "B8", "B9a"]
+    },
+    "B9b": {
+      "title": "author + loop, facts + plan check (§3.8, C16; V6/R10 checks)",
+      "wave": 2,
+      "level": "L2",
+      "status": "landed",
+      "commit": "b301e94",
+      "owned": [
+        "src/session/author.mjs", "src/session/facts.mjs", "src/session/plan-check.mjs",
+        "src/cli/author.mjs", "src/cli/facts.mjs", "src/cli/plan.mjs", "schema/facts.schema.json",
+        "test/session/author.test.mjs", "test/session/facts.test.mjs", "test/session/plan-check.test.mjs",
+        "test/fixtures/briefs/**", "test/fixtures/plans/**"
+      ],
+      "depends_on": ["B9a", "B1", "B3"]
+    },
+    "B12a": {
+      "title": "Review engine: adaptive + consensus session plans, packet builder + context rule (C10), lenses (incl. recheck), finding schema + stub guard, engine hook into B11, root-relative refusal (V4)",
+      "wave": 3,
+      "level": "L2",
+      "status": "landed",
+      "commit": "5197141",
+      "owned": [
+        "src/review/engine.mjs", "src/review/packet.mjs", "src/review/context.mjs", "src/review/validate-review.mjs",
+        "src/review/lenses/**", "src/review/finding.schema.json",
+        "test/review/engine.test.mjs", "test/review/packet.test.mjs", "test/review/context.test.mjs",
+        "test/review/validate-review.test.mjs", "test/review/helpers.mjs", "test/fixtures/review/**"
+      ],
+      "depends_on": ["B5", "B9a", "B10b", "B11"]
+    },
+    "B13b": {
+      "title": "doctor (table, --quick, --json, live Jev, per-role pings incl. facts, isolation probe, path-deny probe, worker start/stop, signer line, tmp line, Codex rules probe)",
+      "wave": 3,
+      "level": "L2",
+      "status": "landed",
+      "commit": "51a325d",
+      "owned": [
+        "src/cli/doctor.mjs", "src/doctor/**", "test/doctor/**"
+      ],
+      "depends_on": ["B0.1", "B1", "B2", "B4", "B5", "B6", "B7", "B8", "B9a", "B11"]
+    },
+    "B12b": {
+      "title": "Triage (judge-final), fix loop = §4.11 convergence rule, budget (§4.10), block-gate review check, block waive (human-only, forbidden to coders via mergeForbidden)",
+      "wave": 3,
+      "level": "L2",
+      "status": "landed",
+      "commit": "4947f30",
+      "owned": [
+        "src/review/triage.mjs", "src/review/fixloop.mjs", "src/review/budget.mjs", "src/review/gate-check.mjs",
+        "test/review/triage.test.mjs", "test/review/fixloop.test.mjs", "test/review/budget.test.mjs", "test/review/gate-check.test.mjs"
+      ],
+      "depends_on": ["B12a", "B3", "B1.1"]
+    },
+    "B12c": {
+      "title": "Integration: wire worker -> triage -> fixloop so a real review-file call writes the signed review.approved row that block close now requires",
+      "wave": 4,
+      "level": "L2",
+      "status": "in_review",
+      "owned": [
+        "src/worker/**", "src/cli/review-file.mjs", "test/worker/**", "test/integration/**"
+      ],
+      "depends_on": ["B11", "B12a", "B12b"],
+      "note": "root-added (night run, started after B12b landed); not in the v1.3 §10.4 table"
+    },
+    "B13a": {
+      "title": "init wizard (9 steps, flags, --no-interaction, idempotent diff, no-subagent stop text)",
+      "wave": 3,
+      "level": "L2",
+      "status": "landed",
+      "commit": "a211098",
+      "owned": [
+        "src/cli/init.mjs", "src/install/wizard/**", "test/init/**", "test/fixtures/repos/laravel-vue/**"
+      ],
+      "depends_on": ["B13b", "B1", "B2", "B7"]
+    },
+    "B3.1": {
+      "title": "Escalation rules 2b (review_stall) and 6 (review_cap) in escalation.mjs (§3.6)",
+      "wave": 3,
+      "level": "L1",
+      "status": "landed",
+      "commit": "c70f1c5",
+      "owned": [
+        "src/decide/escalation.mjs", "test/decide/escalation.test.mjs"
+      ],
+      "depends_on": ["B3", "B1.1"]
+    },
+    "B4.1": {
+      "title": "Security follow-up: wire the rendered Codex execpolicy rules into the Codex coder invocation (per-run location, never ~/.codex); merge built.env into the child env so a real Codex spawn gets the rules",
+      "wave": 3,
+      "level": "L2",
+      "status": "in_review",
+      "owned": [
+        "src/engines/builders/codex.mjs", "src/engines/codex-home.mjs", "src/session/spawn.mjs",
+        "src/cli/block.mjs", "src/cli/gates.mjs", "src/doctor/probes.mjs", "src/util/forbidden.mjs",
+        "test/engines/builders/argv-snapshots.test.mjs", "test/engines/builders/forbidden-rendering.test.mjs",
+        "test/engines/codex-home.test.mjs", "test/doctor/codex-rules.test.mjs",
+        "test/session/spawn.test.mjs", "test/state/block.test.mjs", "test/util/forbidden.test.mjs", "test/cli/**"
+      ],
+      "depends_on": ["B4", "B8", "B9a", "B13b"],
+      "note": "root-added (night run), not in the v1.3 §10.4 table; closes the B13b follow-up 'codex: forbidden list is prose-only'"
+    },
+    "B11.1": {
+      "title": "No-follow file reads (symlink TOCTOU hardening): readRegularFileNoFollow used by contentHash and every packet content read",
+      "wave": 3,
+      "level": "L2",
+      "status": "landed",
+      "commit": "989efbc",
+      "owned": [
+        "src/review/packet.mjs", "src/worker/ticket.mjs", "test/review/packet.test.mjs", "test/worker/nofollow.test.mjs"
+      ],
+      "depends_on": ["B11", "B12a"],
+      "note": "root-added (night run), not in the v1.3 §10.4 table; the architect's follow-up to B12a"
+    },
+    "B14": {
+      "title": "The skill: SKILL.md, references/*, templates/*, rules-core.md (R1-R16), scripts/forge shim, adapters",
+      "wave": 4,
+      "level": "L3 (architect-authored)",
+      "status": "pending",
+      "owned": [
+        "skill/**", "test/skill/**"
+      ],
+      "depends_on": ["B12b", "B13a"]
+    },
+    "B16": {
+      "title": "Docs: README, CHANGELOG 0.1.0, config reference generated from the schema, docs/reference/blocks.json, marketing corrections (C14), no project name (R13)",
+      "wave": 4,
+      "level": "L0",
+      "status": "in_progress",
+      "owned": [
+        "README.md", "CHANGELOG.md", "docs/reference/config.md", "docs/reference/blocks.json",
+        "scripts/gen-config-doc.mjs", "docs/marketing/code-forge-story.md", "test/docs-marketing.test.mjs",
+        "test/docs-config.test.mjs", "test/docs-blocks.test.mjs"
+      ],
+      "depends_on": ["B13a"]
+    },
+    "B15": {
+      "title": "Evals (19 cases), plugin manifest, publish.yml, ci/outcome.yml template, evals/run.mjs, imports-order test, no-project-names test",
+      "wave": 4,
+      "level": "L1",
+      "status": "pending",
+      "owned": [
+        "evals/**", ".claude-plugin/**", ".github/workflows/publish.yml", "ci/**",
+        "test/evals-smoke.test.mjs", "test/imports-order.test.mjs", "test/no-project-names.test.mjs"
+      ],
+      "depends_on": ["B14", "B16"]
+    },
+    "B17": {
+      "title": "First real use on a neutral example repo shipped inside the package (examples/node-lib/, scripts/first-use.mjs)",
+      "wave": 5,
+      "level": "L1 (coder); orchestrated by the root",
+      "status": "pending",
+      "owned": [
+        "examples/**", "scripts/first-use.mjs", "test/first-use.test.mjs"
+      ],
+      "depends_on": ["B15", "B16"]
+    },
+    "B18": {
+      "title": "Retire the predecessor skill: 5-line alias for one release, then delete",
+      "wave": 5,
+      "level": "human",
+      "status": "pending",
+      "owned": [
+        "the predecessor skill directory (the maintainer only, outside this repo)"
+      ],
+      "depends_on": ["B17"]
+    },
+    "B10c": {
+      "title": "Proof tools for consumers (D14 half): Infection/Stryker wrappers, proof mutate, proof nightly, ci/nightly-proof.yml, proof baseline",
+      "wave": 6,
+      "level": "L1",
+      "status": "deleted",
+      "deleted": true,
+      "deleted_reason": "Q16 answered 'cut' (the maintainer, 2026-09-25): the product ships no tool-made mutation testing for users' code. B10c never lands; proof.tiers.high.tool / proof.js / proof.nightly left the schema in B1.2.",
+      "owned": [
+        "src/proof/tools/**", "src/proof/nightly.mjs", "ci/nightly-proof.yml", "test/proof/tools/**", "test/proof/nightly.test.mjs"
+      ],
+      "depends_on": ["B10a", "B10b"]
+    }
+  }
+}

package/docs/reference/config.md

@@ -0,0 +1,162 @@
+# `.code-forge.yml` configuration reference
+
+Generated by `node scripts/gen-config-doc.mjs` from `schema/code-forge.schema.json` — do not hand-edit this file. Run `node scripts/gen-config-doc.mjs --check` in CI to catch a schema change that was not followed by a regeneration.
+
+Plan v1.2 §1.3 — every key any section of the plan reads must appear here. additionalProperties: false everywhere a key set is fixed; a typed additionalProperties schema (never bare true) marks the handful of genuinely open-ended maps (thresholds.<question>, system1.criteria_extra, known_extra, keys, review.second_levels — the last restricted to L0..L3 keys only via propertyNames). v1.3 (B1.1) amendment: review.max_rounds_per_file/recheck_scope/late_findings (§4.11), budget.block_cases (§10.7), caps.coders re-defaulted to 2 (R10), tmp.root (§9.6/§1.2, V12).
+
+`version`, `provider` and `levels` are required. `version`, `provider` and `levels` have no schema-level default; a config omitting any of them is refused.
+
+Every other key defaults as shown, or is entirely absent from a minimal file. `additionalProperties: false` applies everywhere a key set is fixed; the rows marked `<key>` are the handful of open-ended maps where the schema accepts a caller-chosen name (a question id, a level name, a key name, a provider id).
+
+| Key | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `version` | const `1` | yes | — |  |
+| `project` | object |  | — |  |
+| `project.name` | string |  | — |  |
+| `project.slug` | string |  | — |  |
+| `project.plans_dir` | string |  | — |  |
+| `project.languages` | object |  | — |  |
+| `project.languages.chat` | string |  | — |  |
+| `project.languages.ui` | string |  | — |  |
+| `project.languages.pr` | string |  | — |  |
+| `provider` | enum: `anthropic`, `openai`, `xai` | yes | — |  |
+| `levels` | object | yes | — |  |
+| `levels.L0` | object | yes | — |  |
+| `levels.L0.model` | string | yes | — | minLength 1 |
+| `levels.L0.effort` | string |  | — |  |
+| `levels.L0.provider` | enum: `anthropic`, `openai`, `xai` |  | — |  |
+| `levels.L0.fallback` | array<object> |  | — |  |
+| `levels.L0.fallback[].provider` | enum: `anthropic`, `openai`, `xai` | yes | — |  |
+| `levels.L0.fallback[].model` | string | yes | — | minLength 1 |
+| `levels.L0.fallback[].effort` | string |  | — |  |
+| `levels.L1` | object | yes | — |  |
+| `levels.L1.model` | string | yes | — | minLength 1 |
+| `levels.L1.effort` | string |  | — |  |
+| `levels.L1.provider` | enum: `anthropic`, `openai`, `xai` |  | — |  |
+| `levels.L1.fallback` | array<object> |  | — |  |
+| `levels.L1.fallback[].provider` | enum: `anthropic`, `openai`, `xai` | yes | — |  |
+| `levels.L1.fallback[].model` | string | yes | — | minLength 1 |
+| `levels.L1.fallback[].effort` | string |  | — |  |
+| `levels.L2` | object | yes | — |  |
+| `levels.L2.model` | string | yes | — | minLength 1 |
+| `levels.L2.effort` | string |  | — |  |
+| `levels.L2.provider` | enum: `anthropic`, `openai`, `xai` |  | — |  |
+| `levels.L2.fallback` | array<object> |  | — |  |
+| `levels.L2.fallback[].provider` | enum: `anthropic`, `openai`, `xai` | yes | — |  |
+| `levels.L2.fallback[].model` | string | yes | — | minLength 1 |
+| `levels.L2.fallback[].effort` | string |  | — |  |
+| `levels.L3` | object | yes | — |  |
+| `levels.L3.model` | string | yes | — | minLength 1 |
+| `levels.L3.effort` | string |  | — |  |
+| `levels.L3.provider` | enum: `anthropic`, `openai`, `xai` |  | — |  |
+| `levels.L3.fallback` | array<object> |  | — |  |
+| `levels.L3.fallback[].provider` | enum: `anthropic`, `openai`, `xai` | yes | — |  |
+| `levels.L3.fallback[].model` | string | yes | — | minLength 1 |
+| `levels.L3.fallback[].effort` | string |  | — |  |
+| `orchestrator` | enum: `L0`, `L1`, `L2`, `L3` |  | — |  |
+| `system1` | object |  | — |  |
+| `system1.provider` | enum: `anthropic`, `openai`, `xai` |  | — |  |
+| `system1.model` | string |  | — |  |
+| `system1.key` | string |  | — |  |
+| `system1.fallback` | enum: `rules`, `s2`, `stop` |  | `"rules"` |  |
+| `system1.criteria_extra` | object |  | — |  |
+| `system1.criteria_extra.<key>` | object |  | — | user-defined key |
+| `system1.criteria_extra.<key>.instructions` | string |  | — |  |
+| `system1.criteria_extra.<key>.criteria` | object |  | — |  |
+| `system1.criteria_extra.<key>.criteria.<key>` | string |  | — | user-defined key |
+| `system1.disable` | array<string> |  | — |  |
+| `thresholds` | object |  | — |  |
+| `thresholds.default` | object |  | — |  |
+| `thresholds.default.act` | number |  | — | min 0; max 1 |
+| `thresholds.default.check` | number |  | — | min 0; max 1 |
+| `thresholds.default.close_margin` | number |  | — | min 0; max 1 |
+| `thresholds.findings` | object |  | — |  |
+| `thresholds.findings.fix` | number |  | `0.9` | min 0; max 1 |
+| `thresholds.findings.nit` | number |  | `0.4` | min 0; max 1 |
+| `thresholds.findings.resolved` | number |  | `0.9` | min 0; max 1 |
+| `thresholds.<key>` | object |  | — | user-defined key |
+| `thresholds.<key>.act` | number |  | — | min 0; max 1 |
+| `thresholds.<key>.check` | number |  | — | min 0; max 1 |
+| `thresholds.<key>.close_margin` | number |  | — | min 0; max 1 |
+| `escalation` | object |  | — |  |
+| `escalation.retries_per_level` | integer |  | `2` | min 0 |
+| `escalation.review_rounds_per_level` | integer |  | `2` | min 0 |
+| `escalation.stop_at` | const `"L3"` |  | `"L3"` |  |
+| `escalation.l3_mode` | enum: `patch`, `code` |  | `"patch"` |  |
+| `review` | object |  | — |  |
+| `review.multimodel` | boolean |  | `false` |  |
+| `review.second_provider` | enum: `anthropic`, `openai`, `xai` \| null |  | `null` |  |
+| `review.second_levels` | null \| object |  | `null` |  |
+| `review.closed_book` | const `true` |  | `true` |  |
+| `review.judge_sees_diff` | boolean |  | `false` |  |
+| `review.budgets` | object |  | — |  |
+| `review.budgets.quick_in` | integer |  | `6000` | min 1 |
+| `review.budgets.full_in` | integer |  | `12000` | min 1 |
+| `review.budgets.judge_in` | integer |  | `8000` | min 1 |
+| `review.budgets.out` | integer |  | `1200` | min 1 |
+| `review.context` | object |  | — |  |
+| `review.context.whole_file_max_lines` | integer |  | `400` | min 0 |
+| `review.context.hunk_context_lines` | integer |  | `40` | min 0 |
+| `review.context.min_context_lines` | integer |  | `10` | min 0 |
+| `review.block_budget_tokens` | integer |  | `150000` | min 1 |
+| `review.block_budget_usd` | number \| null |  | `null` |  |
+| `review.min_tokens_out` | integer |  | `120` | min 1 |
+| `review.batch_small_files` | boolean |  | `true` |  |
+| `review.session_timeout_s` | integer |  | `600` | min 1 |
+| `review.max_rounds_per_file` | integer |  | `4` | min 2; max 6 |
+| `review.recheck_scope` | enum: `fix_hunks`, `file` |  | `"fix_hunks"` |  |
+| `review.late_findings` | enum: `sweep`, `block` |  | `"sweep"` |  |
+| `engine` | enum: `auto`, `solo`, `harness`, `subprocess` |  | `"auto"` |  |
+| `harnesses` | array<string> |  | — |  |
+| `harness` | object |  | — |  |
+| `harness.claude` | object |  | — |  |
+| `harness.claude.worktree` | boolean |  | `false` |  |
+| `harness.solo` | object |  | — |  |
+| `harness.solo.interactive_harden` | boolean |  | `false` |  |
+| `caps` | object |  | — |  |
+| `caps.coders` | integer |  | `2` | min 1 |
+| `gates` | object |  | — |  |
+| `gates.test` | array<string> \| null |  | — |  |
+| `gates.lint` | array<string> \| null |  | — |  |
+| `gates.types` | array<string> \| null |  | — |  |
+| `gates.format` | array<string> \| null |  | — |  |
+| `gates.extra` | object |  | — |  |
+| `gates.extra.secret_scan` | boolean |  | `true` |  |
+| `gates.extra.safe_edit` | boolean |  | `true` |  |
+| `gates.extra.invariants` | string |  | — |  |
+| `gates.full_suite_threshold_files` | integer |  | `10` | min 1 |
+| `proof` | object |  | — |  |
+| `proof.tiers` | object |  | — |  |
+| `proof.tiers.high` | object |  | — |  |
+| `proof.tiers.high.paths` | array<string> |  | — |  |
+| `proof.tiers.light` | object |  | — |  |
+| `proof.extra` | array<string> |  | — |  |
+| `proof.isolation` | enum: `export`, `lock` |  | `"export"` |  |
+| `proof.export` | object |  | — |  |
+| `proof.export.link_dirs` | array<string> |  | `["vendor","node_modules"]` |  |
+| `proof.export.copy_untracked` | array<string> |  | `[".env",".env.testing"]` |  |
+| `budget` | object |  | — |  |
+| `budget.block_lines` | integer |  | `600` | min 1 |
+| `budget.block_tokens_soft` | integer |  | — | min 1 |
+| `budget.block_tokens_hard` | integer |  | — | min 1 |
+| `budget.run_usd_soft` | number |  | — | min 0 |
+| `budget.block_cases` | integer |  | `80` | min 10 |
+| `autonomy` | object |  | — |  |
+| `autonomy.coder_may_open_draft_pr` | boolean |  | `true` |  |
+| `autonomy.coder_may_push` | boolean |  | `true` |  |
+| `commit` | object |  | — |  |
+| `commit.trailers` | enum: `none`, `harness` |  | `"none"` |  |
+| `wip` | object |  | — |  |
+| `wip.ready_prs` | integer |  | `1` | min 1 |
+| `production` | object |  | — |  |
+| `production.markers` | array<string> |  | — |  |
+| `production.names` | array<string> |  | — |  |
+| `known_extra` | object |  | — |  |
+| `known_extra.<key>` | array<string> |  | — | user-defined key |
+| `calibration` | object |  | — |  |
+| `calibration.shadow_rate` | number |  | `0` | min 0; max 0.5 |
+| `keys` | object |  | — |  |
+| `keys.<key>` | string |  | — | user-defined key |
+| `tmp` | object |  | — |  |
+| `tmp.root` | string \| null |  | `null` |  |
+| `telemetry` | const `"off"` |  | `"off"` |  |

package/examples/first-use/README.md

@@ -0,0 +1,11 @@
+# first-use inputs
+
+What `scripts/first-use.mjs` feeds the one block of the first real use ("add `clamp()` with tests")
+on a copy of `examples/node-lib/`:
+
+- `clamp.brief.md` — the brief; `code-forge facts` builds its facts sheet, `code-forge author --job
+  plan` drafts the plan from both, and `block open --brief` points the coder at the plan.
+- `clamp.acceptance.yml` — the block's acceptance clauses (`block open --acceptance`).
+- `coder/` — the deterministic edit `--coder scripted` applies (the automated test uses it). In a
+  real run the coder is a harness subagent (`--coder harness`) or a `code-forge spawn` coder process
+  (`--engine subprocess`, which spawns it with `--coder spawn`).

package/examples/first-use/clamp.acceptance.yml

@@ -0,0 +1,8 @@
+- clause: clamp returns the value itself when it is inside [min, max]
+  tests: [test/clamp.test.mjs::clamp returns the value inside the range]
+- clause: clamp returns min when the value is below min
+  tests: [test/clamp.test.mjs::clamp returns min below the range]
+- clause: clamp returns max when the value is above max
+  tests: [test/clamp.test.mjs::clamp returns max above the range]
+- clause: clamp throws a RangeError when min > max
+  tests: [test/clamp.test.mjs::clamp refuses min above max]

package/examples/first-use/clamp.brief.md

@@ -0,0 +1,16 @@
+# Block B1 — add `clamp()` with tests
+
+Add `clamp(value, min, max)` to ./src/math.mjs. It returns `value` limited to the closed range
+`[min, max]` and throws a `RangeError` when `min > max`. Nothing else in the module changes.
+
+Tests go in a new file, ./test/clamp.test.mjs, run by the example's `npm test` (plain `node:test`,
+the `--test` runner). One test per acceptance clause, named exactly as the acceptance file names it:
+inside the range ⇒ the value, below min ⇒ min, above max ⇒ max, min above max ⇒ `RangeError`.
+
+So that the red step against the base version (no `clamp` export) is always an assertion failure,
+never an import error or a `TypeError`: import the module as a namespace
+(`import * as ns from '../src/math.mjs'`), start EVERY test with
+`assert.strictEqual(typeof ns.clamp, 'function')`, and check the throw with
+`assert.throws(() => ns.clamp(1, 10, 0), RangeError)`.
+
+Owned files: `src/math.mjs`, `test/clamp.test.mjs`. Level L1.

package/examples/first-use/coder/src/math.mjs

@@ -0,0 +1,31 @@
+/** Small number helpers. */
+
+/** @param {number} a @param {number} b @returns {number} */
+export function add(a, b) {
+  return a + b;
+}
+
+/** @param {number} a @param {number} b @returns {number} */
+export function sub(a, b) {
+  return a - b;
+}
+
+/**
+ * @param {number[]} values
+ * @returns {number} the arithmetic mean
+ * @throws {RangeError} on an empty list
+ */
+export function mean(values) {
+  if (values.length === 0) throw new RangeError('mean of an empty list');
+  return values.reduce(add, 0) / values.length;
+}
+
+/**
+ * @param {number} value @param {number} min @param {number} max
+ * @returns {number} `value` limited to the closed range [min, max]
+ * @throws {RangeError} when `min > max`
+ */
+export function clamp(value, min, max) {
+  if (min > max) throw new RangeError('clamp: min is above max');
+  return Math.min(Math.max(value, min), max);
+}

package/examples/first-use/coder/test/clamp.test.mjs

@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+// A namespace import and a `typeof` assertion first in every case: at the base version `ns.clamp`
+// is undefined, so the red step fails on an assertion (RED), never on an import error or a
+// TypeError (RED_INVALID).
+import * as ns from '../src/math.mjs';
+
+test('clamp returns the value inside the range', () => {
+  assert.strictEqual(typeof ns.clamp, 'function');
+  assert.strictEqual(ns.clamp(5, 0, 10), 5);
+});
+
+test('clamp returns min below the range', () => {
+  assert.strictEqual(typeof ns.clamp, 'function');
+  assert.strictEqual(ns.clamp(-3, 0, 10), 0);
+});
+
+test('clamp returns max above the range', () => {
+  assert.strictEqual(typeof ns.clamp, 'function');
+  assert.strictEqual(ns.clamp(42, 0, 10), 10);
+});
+
+test('clamp refuses min above max', () => {
+  assert.strictEqual(typeof ns.clamp, 'function');
+  assert.throws(() => ns.clamp(1, 10, 0), RangeError);
+});

package/examples/node-lib/.env.example

@@ -0,0 +1,3 @@
+# Copy to .env (never committed). code-forge adds .env to the measurement export through
+# proof.export.copy_untracked, so a test that needs it still runs there. Example values only.
+GREETING=hello

package/examples/node-lib/.gitattributes

@@ -0,0 +1,3 @@
+# Release archives leave these out. code-forge's measurement export restores them (plan §4.7 b).
+/.github export-ignore
+CHANGELOG.md export-ignore

package/examples/node-lib/.github/workflows/test.yml

@@ -0,0 +1,11 @@
+name: test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm test

package/examples/node-lib/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.3.0
+
+- `list.chunk()` refuses a size below 1.
+
+## 0.2.0
+
+- `strings.pad()` pads on either side.
+
+## 0.1.0
+
+- First release: `math`, `strings`, `list`.

package/examples/node-lib/README.md

@@ -0,0 +1,17 @@
+# node-lib (example)
+
+A three-module ESM library with a `node:test` suite. It ships inside `@codedology/code-forge` as the
+repository the **first real use** runs on (`scripts/first-use.mjs`): the script copies it to a temp
+directory, `git init`s it and runs one block — "add `clamp()` with tests" — end to end.
+
+- `src/math.mjs` — `add`, `sub`, `mean`
+- `src/strings.mjs` — `pad`, `capitalize`, `greet`
+- `src/list.mjs` — `chunk`, `unique`
+
+`npm test` runs the suite. `.gitattributes` marks `/.github` and `CHANGELOG.md` `export-ignore`, and
+`test/package.test.mjs` reads both, so the suite only passes in code-forge's measurement export when
+the export restores them. `.env.example` is copied to `.env` (untracked) before the run; `greet()`
+reads `GREETING` from it.
+
+The ignore rules ship as `gitignore` (npm pack drops a nested `.gitignore`); `first-use.mjs` renames
+it to `.gitignore` in the copy before `git init`.

package/examples/node-lib/gitignore

@@ -0,0 +1,3 @@
+.code-forge/
+node_modules/
+.env

package/examples/node-lib/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "node-lib-example",
+  "version": "0.3.0",
+  "description": "A tiny ESM library that code-forge's first-use run works on.",
+  "type": "module",
+  "private": true,
+  "license": "MIT",
+  "exports": {
+    "./math": "./src/math.mjs",
+    "./strings": "./src/strings.mjs",
+    "./list": "./src/list.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/examples/node-lib/src/list.mjs

@@ -0,0 +1,23 @@
+/** Small array helpers. */
+
+/**
+ * @template T
+ * @param {T[]} items @param {number} size
+ * @returns {T[][]} consecutive slices of at most `size` items
+ * @throws {RangeError} when `size` is below 1
+ */
+export function chunk(items, size) {
+  if (!Number.isInteger(size) || size < 1) throw new RangeError('chunk size must be an integer >= 1');
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+
+/**
+ * @template T
+ * @param {T[]} items
+ * @returns {T[]} the first occurrence of each item, in order
+ */
+export function unique(items) {
+  return [...new Set(items)];
+}