@codedology/code-forge 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to `@codedology/code-forge` are recorded here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow semver ahead of a 1.0.0 that
+waits on a second real consumer (plan §10.4, Q17).
+
+## [0.1.0] — first release
+
+The `plan` → `harden` → `code` → `review` pipeline for cross-model, parallel, evidence-gated
+feature delivery, as one CLI (`code-forge`) plus one Agent Skill.
+
+### Added
+
+- **CLI verbs:** `init`, `doctor`, `run`, `block`, `worker`, `review-file`, `spawn`, `s2`,
+  `author`, `facts`, `plan check`, `proof`, `gates`, `jev`, `keys`, `ledger`, `report`, `resolve`,
+  `models`, `list`, `remove`, `upgrade`, `validate`, `help`, `version`. Verbs are discovered from
+  `src/cli/*.mjs`, so adding one never touches the router.
+- **Setup wizard** (`code-forge init`): nine steps (tools, harnesses, provider matrix, multimodel,
+  keys, engine, gates, proof, doctor), every question has a default, `--no-interaction` plus one
+  override flag per answer, an agent gets one JSON line, a second run changes nothing.
+- **Decision layer:** System 1 (Jev) answers typed questions in well under a second; System 2 is a
+  fresh top-level session woken only when System 1 is unsure; deterministic escalation precedence
+  (retry → escalate one level → System 2 hand-off → the top level patches once → stop for a human).
+- **Review engine:** a file-done trigger starts one or more fresh, isolated reviewer sessions
+  (adaptive by risk score, or two-provider consensus with a judge); a worker process runs review
+  outside the coder's own sandbox so review keeps moving even when the coder has no network; fix
+  rounds converge under a bounded rule (round ≥ 2 reviews only the fix hunks, the open finding
+  count must strictly shrink every round, four rounds is the cap).
+- **Two-tier proof policy:** `light` and `high` (by risk score, a configured path, or a
+  security-sensitive change); a red→green runner proves a new test actually fails before the fix
+  and passes after. **No tool-made mutation testing ships in 0.1.0** — see "Removed" below.
+- **Engine adapters** for Claude Code, Codex and Grok (subprocess argv snapshots, forbidden-list
+  rendering, closed-book sessions with the packet on stdin); Gemini/Cursor/Copilot get detection
+  and skill linking only.
+- **Ledger and report:** an append-only, signed, per-project ledger (`~/.code-forge/ledger/`) and
+  a `code-forge report` verb with a terminal view and a `--export` JSON snapshot.
+- **JSON Schema** for `.code-forge.yml` (`schema/code-forge.schema.json`) and a generated reference
+  at `docs/reference/config.md` (`node scripts/gen-config-doc.mjs [--check]`).
+
+### Security
+
+- **`signer: same-user boundary only`** — signed ledger rows detect tampering by a different user
+  or a rewritten history; they are not a defense against an attacker who already runs code as you.
+  `doctor` always prints this line so nobody mistakes the signature for more than that.
+- **Keys never reach a coder process.** Provider/Jev keys resolve only inside the worker or the
+  orchestrator's own CLI calls (chain: `env:<NAME>` → OS keychain → 1Password, cached briefly →
+  ask at setup only); `keys list` never prints a value; every output path is redacted.
+- A **forbidden-command list** blocks a coder from starting its own worker, waiving a review, or
+  running other orchestrator-only actions, rendered into each provider's own deny-list mechanism.
+
+### Changed / decided late in the build
+
+- **Q16 = cut (2026-09-25):** code-forge ships **no user-facing mutation-testing tool**. Proof for
+  both the product and this package's own tests is plain unit/feature tests plus the red→green
+  runner — exact assertions on the main behaviour, not "mutation-verified" coverage.
+- **R10:** at most 2 coders run at a time (down from 3) for the rest of the build.
+- **R13:** code-forge never runs against, installs into, or names any of Ricardo's own projects;
+  the first real, end-to-end use is a neutral example repository shipped inside the package.
+
+### Removed
+
+- `@stryker-mutator/core`, `stryker.config.mjs` and the CI mutation-baseline job — this package
+  builds itself with unit and feature tests only (R14); nothing in this repository's own history
+  ran mutation testing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo A. Vargas R.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @codedology/code-forge
+
+A CLI (`code-forge`) plus one Agent Skill that runs the **plan → harden → code → review** pipeline
+for cross-model, parallel, evidence-gated feature delivery — on Claude Code, Codex, Grok, and Solo.
+
+> **Status:** built block by block from a maintainer-only design plan. The CLI, decision layer,
+> review engine, worker, proof policy and installer are landed; the Agent Skill under `skill/` and
+> the shipped example repo under `examples/` land in later blocks (see
+> `docs/reference/blocks.json` for what has landed and what is still pending).
+
+## What ships
+
+- A CLI (`code-forge`), installed globally via `npx @codedology/code-forge init` into every detected
+  harness (Claude Code, Codex, Grok, …).
+- One Agent Skill (`skill/SKILL.md` + `references/`) that is prose only — every fact (model ids,
+  efforts, commands, thresholds, paths) lives in config or in the CLI, never in the skill text.
+- A JSON Schema for `.code-forge.yml` (`schema/code-forge.schema.json`), documented in
+  `docs/reference/config.md` (generated — see below).
+
+See the skill's `skill/references/` for the full architecture, decision layer, review engine, proof
+policy and security model; `docs/reference/blocks.json` lists the build blocks.
+
+## Install
+
+```bash
+npx @codedology/code-forge init
+```
+
+The wizard asks nine short questions (tools, harnesses, provider matrix, multimodel, keys, engine,
+gates, proof, doctor), every one with a default on Enter. Non-interactively:
+
+```bash
+npx @codedology/code-forge init --no-interaction --no-jev
+```
+
+`--no-jev` skips the System-1 key for a first try; drop it and pass `--jev-ref op://vault/item/field`
+or `--jev-env MY_JEV_KEY` once you have one. A second run of `init` changes nothing it already wrote.
+
+## Quickstart
+
+Once `init` has written `.code-forge.yml`, these all run for real:
+
+```bash
+code-forge validate                 # loads and validates .code-forge.yml
+code-forge resolve L1                # {provider, model, effort, fallback, cli} for a level
+code-forge doctor --quick            # config + links + key resolution only
+code-forge list                      # what is installed where, and whether it still resolves
+code-forge keys list                 # NAME / SOURCE / BACKEND / EXPIRES — never a value
+code-forge models                    # the model catalog per provider
+code-forge --help                    # every verb, one per line
+code-forge version
+```
+
+## The verbs
+
+Verbs are discovered from `src/cli/*.mjs` — adding one never touches the router
+(`bin/code-forge.mjs`), so this list is exactly `code-forge --help`'s output plus each verb's own
+usage line.
+
+| Verb | Usage |
+|---|---|
+| `init` | `code-forge init [--no-interaction] [--tools recommended\|current] [--yes-tool <tool>]… [--harness a,b] [-g\|-p] [--copy] [--provider P] [--level Ln=model[:effort][@provider]]… [--refresh-models] [--multimodel on\|off] [--second-provider P] [--jev-ref op://… \| --jev-env NAME \| --no-jev] [--engine auto\|solo\|harness] [--solo-project N] [--gate name=cmd]… [--proof isolation=export\|lock \| high=a,b \| link_dirs=a,b \| copy_untracked=a,b]… [--skip-doctor]` |
+| `doctor` | `code-forge doctor [--quick] [--json] [--cwd <dir>]` |
+| `validate` | `code-forge validate [--file <path>]` |
+| `resolve` | `code-forge resolve <L0\|L1\|L2\|L3>` |
+| `run` | `code-forge run start [--cwd <dir>] [--run <id>] [--engine <e>] [--worker-pid <pid>]` · `run start --reattach --run <id>` · `run status --run <id>` · `run end --run <id>` |
+| `block` | `code-forge block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file>` · `block attempt\|rebase\|claim\|close\|stop\|waive …` (§4.9; `waive` is human-only) |
+| `worker` | `code-forge worker --run <id> [--cwd <dir>] [--poll-ms <n>] [--once]` — started detached by `run start`, never by a coder |
+| `review-file` | `code-forge review-file <path> --block <id> [--run <id>]` (enqueue) · `review-file --wait <ticket> [--max <seconds>s]` (poll) |
+| `spawn` | `code-forge spawn --level L<n> --role <role> --brief <file> [--schema <file>] [--cwd <dir>] [--run <id>] [--block <id>] [--timeout <s>] [--background]` |
+| `s2` | `code-forge s2 --packet <file.json> [--run <id>] [--block <id>] [--timeout <s>]` |
+| `author` | `code-forge author --job plan\|harden --brief <file> [--facts <file>] [--draft <file>] [--answers <file>] [--out <file>] [--run <id>] [--timeout <s>]` |
+| `facts` | `code-forge facts --brief <file> [--sources <path>…] [--out <file>] [--run <id>] [--timeout <s>]` |
+| `plan` | `code-forge plan check <plan-file> [--facts <sheet>]` |
+| `proof` | `code-forge proof tier --file <path> --risk <0-3> [--security] [--cwd <dir>]` · `proof export\|lock\|unlock\|restore <block> --run <r>` |
+| `gates` | `code-forge gates detect\|run\|secret-scan\|safe-edit\|scope\|acceptance\|transcript-grep --cwd <dir> …` |
+| `jev` | `code-forge jev ask <question-id> --state <file.json> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>]` |
+| `keys` | `code-forge keys list \| set <name> [--op <ref>] \| test <name> [--ref <ref>] \| remove <name>` |
+| `ledger` | `code-forge ledger calibration\|outcome\|tail --slug <slug> …` |
+| `report` | `code-forge report --slug <slug> [--json] [--export <dir>]` |
+| `models` | `code-forge models [--refresh --from-cli-caches]` |
+| `list` | `code-forge list` |
+| `remove` | `code-forge remove [<harness>] [--scope project\|global]` |
+| `upgrade` | `code-forge upgrade [--source <path>]` |
+| `help` / `version` | `code-forge --help` (or no verb) · `code-forge --version` |
+
+`run`, `block`, `worker`, `spawn`, `s2`, `author`, `facts` and `review-file` are what the Agent
+Skill's loop calls during a real block; you will not usually type them by hand, but they are plain
+CLI verbs like any other and every one of them is exercised by this package's own test suite.
+
+## Security model
+
+- **`signer: same-user boundary only`.** Every review/gate-relevant ledger row is HMAC-signed with
+  a per-project key, so tampering by a different user or a rewritten history is detectable.
+  `doctor` always prints this line — the signature is not a defense against an attacker who
+  already runs code as you, and no part of code-forge claims otherwise.
+- **Keys never reach a coder process.** Provider and Jev keys resolve only inside the worker or the
+  orchestrator's own CLI calls (`env:<NAME>` → OS keychain → 1Password, cached briefly → ask at
+  setup only). `keys list`/`keys test` never print a value; every stdout/stderr path is redacted.
+- **A forbidden-command list** stops a coder from starting its own worker, waiving a review, or
+  running other orchestrator-only actions — rendered into each provider's own deny-list mechanism
+  (`--disallowedTools` for Claude, an execpolicy rules file plus prose for Codex).
+- **No mutation testing.** Neither this package's own tests nor the product it ships run mutation
+  testing (Ricardo's ruling R14/Q16, 2026-09-25). Proof is plain unit and feature tests with exact
+  assertions, plus a red→green runner that proves a new test fails before the fix and passes after.
+
+## Configuration reference
+
+`schema/code-forge.schema.json` is the source of truth for `.code-forge.yml`.
+`docs/reference/config.md` is generated from it:
+
+```bash
+node scripts/gen-config-doc.mjs          # regenerate docs/reference/config.md
+node scripts/gen-config-doc.mjs --check  # exit 0 if it's already up to date, 1 otherwise
+```
+
+## Development
+
+```bash
+npm install
+npm test              # node --import ./test/helpers/isolate.mjs --test 'test/**/*.test.mjs'
+npm run typecheck     # tsc --checkJs --noEmit
+```
+
+Node >= 22 required (ruling R7). No build step — the package ships plain ESM `.mjs`, run directly
+by Node. `docs/reference/blocks.json` maps each build block to the files it owns and what it
+depends on, kept in sync with the maintainer's design plan.

package/bin/code-forge.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * Verb router. Discovers verbs by `readdir(src/cli)` — a verb is a `.mjs` file's basename.
+ * Adding a new verb NEVER requires editing this file (plan §10.2 acceptance 2): drop
+ * `src/cli/<verb>.mjs` exporting a default `async function run(args) -> number|void` and it is
+ * live. `--help`/`-h` (or no verb at all) and `--version`/`-v` are the only aliases this router
+ * knows by name, and only as a UX convenience — both simply dispatch to the `help`/`version`
+ * verb modules like any other invocation would.
+ */
+
+import { realpathSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { redact } from '../src/util/redact.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_DIR = path.join(__dirname, '..', 'src', 'cli');
+
+const HELP_ALIASES = new Set(['--help', '-h']);
+const VERSION_ALIASES = new Set(['--version', '-v']);
+
+/**
+ * A verb file's basename must match this. Duplicated (not imported) in `src/cli/help.mjs` —
+ * both B0-owned files must stay in sync since there is no shared-util file in B0's scope to hold
+ * this once. Rejects `.mjs` (empty verb name) and names with spaces/other characters that would
+ * break the `/^ {2}\S+$/` verb-line pattern `help.mjs` prints.
+ */
+const VERB_FILE_PATTERN = /^[a-z][a-z0-9-]*\.mjs$/;
+
+/**
+ * @returns {Promise<string[]>} verb names, sorted, discovered from `src/cli/*.mjs`.
+ */
+export async function listVerbs() {
+  const entries = await readdir(CLI_DIR, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && VERB_FILE_PATTERN.test(entry.name))
+    .map((entry) => entry.name.slice(0, -'.mjs'.length))
+    .sort();
+}
+
+/**
+ * @param {number} exitCode
+ * @returns {boolean}
+ */
+function isValidExitCode(exitCode) {
+  return Number.isInteger(exitCode) && exitCode >= 0 && exitCode <= 255;
+}
+
+/**
+ * Point this process's lazy temp root at the project's `tmp.root` (B19, plan §9.6 rule 2): when
+ * `cwd` holds a `.code-forge.yml` with a string `tmp.root` and `env` does not name a base already,
+ * set `env.CODE_FORGE_TMP_ROOT` so `util/tmp.mjs` (and every child) uses it. A relative `tmp.root`
+ * is resolved against the config's directory (`cwd`). A missing or unloadable config changes nothing.
+ * @param {{env?: NodeJS.ProcessEnv, cwd?: string}} [opts]
+ * @returns {Promise<string | undefined>} the value `env.CODE_FORGE_TMP_ROOT` holds afterwards.
+ */
+export async function applyTmpRoot({ env = process.env, cwd = process.cwd() } = {}) {
+  const name = 'CODE_FORGE_TMP_ROOT'; // `util/tmp.mjs` TMP_ROOT_ENV
+  if (typeof env[name] === 'string' && env[name].length > 0) return env[name];
+  let loaded;
+  try {
+    // imported here, not statically: the router must still start when the config loader is absent
+    const { loadProjectConfig } = await import('../src/config/load.mjs');
+    loaded = await loadProjectConfig(cwd);
+  } catch {
+    return env[name];
+  }
+  const root = loaded.ok ? loaded.config?.tmp?.root : undefined;
+  if (typeof root === 'string' && root.length > 0) env[name] = path.resolve(cwd, root);
+  return env[name];
+}
+
+/**
+ * @param {string[]} argv - e.g. `process.argv.slice(2)`.
+ * @returns {Promise<number>} the process exit code.
+ */
+export async function run(argv) {
+  const [first, ...rest] = argv;
+  const verbs = await listVerbs();
+
+  let verb = first;
+  if (verb === undefined || HELP_ALIASES.has(verb)) {
+    verb = 'help';
+  } else if (VERSION_ALIASES.has(verb)) {
+    verb = 'version';
+  }
+
+  if (!verbs.includes(verb)) {
+    process.stderr.write(
+      redact(`code-forge: unknown verb "${verb}"\nVerbs:\n${verbs.map((v) => `  ${v}`).join('\n')}\n`),
+    );
+    return 1;
+  }
+
+  const modulePath = path.join(CLI_DIR, `${verb}.mjs`);
+
+  let exitCode;
+  try {
+    const mod = await import(pathToFileURL(modulePath).href);
+    const handler = mod.default;
+    if (typeof handler !== 'function') {
+      process.stderr.write(redact(`code-forge: verb "${verb}" has no default export function\n`));
+      return 1;
+    }
+    exitCode = await handler(rest, { verbs, verb });
+  } catch (err) {
+    // A verb's error can carry an argv/env token (a fake key in a test, a real one in
+    // production); every stderr path here is redacted, this one included.
+    process.stderr.write(redact(`code-forge: verb "${verb}" failed: ${err?.stack ?? String(err)}\n`));
+    return 1;
+  }
+
+  if (exitCode === undefined || exitCode === null) {
+    return 0;
+  }
+  return isValidExitCode(exitCode) ? exitCode : 1;
+}
+
+/**
+ * Resolve `argv[1]` to the real path `import.meta.url` would report for the same file, so the
+ * comparison survives (a) Node resolving symlinks for the main module — `npm`/`npx .` bin shims
+ * under `node_modules/.bin` are symlinks, and macOS temp dirs are `/var` → realpath `/private/var`
+ * — and (b) `import.meta.url` being percent-encoded while `argv[1]` is a raw path (spaces, `#`,
+ * `%`). Falls back to `false` (never treated as main) if `argv[1]` doesn't resolve to a real file.
+ * @returns {boolean}
+ */
+function computeIsMain() {
+  if (!process.argv[1]) {
+    return false;
+  }
+  try {
+    const realArgvPath = realpathSync(process.argv[1]);
+    return import.meta.url === pathToFileURL(realArgvPath).href;
+  } catch {
+    return false;
+  }
+}
+
+const isMain = computeIsMain();
+if (isMain) {
+  await applyTmpRoot();
+  const code = await run(process.argv.slice(2));
+  process.exitCode = code;
+}

package/docs/README.md

@@ -0,0 +1,37 @@
+# code-forge documentation
+
+These pages explain what `@codedology/code-forge` is, how it works, and how to run it for the first
+time. Every command they show exists in the CLI as built. When a page and a verb's own usage line
+disagree, the verb is right: each verb prints its own usage line when its arguments are wrong.
+
+## Reading order
+
+| # | Page | Read it when you want to… |
+|---|---|---|
+| 1 | [overview.md](overview.md) | know what code-forge is, the problem it solves, who it is for, and what it is not |
+| 2 | [concepts.md](concepts.md) | look up a word: block, level, lane, tier, S1/S2, waiver, ledger… |
+| 3 | [how-it-works.md](how-it-works.md) | follow the full workflow from a brief to a closed block, and see who does what and where state lives |
+| 4 | [getting-started.md](getting-started.md) | install it, answer `init`, run `doctor`, and try the first commands |
+| 5 | [tutorial-first-test.md](tutorial-first-test.md) | run one real end-to-end test: build the code-forge marketing site in a new repo |
+| 6 | [examples/marketing-site/brief.md](examples/marketing-site/brief.md) | copy the brief the tutorial uses |
+| 7 | [marketing.md](marketing.md) | read the product story: the problem, the promise, the honest limits |
+
+New to the tool? Read 1 → 3 → 4, then do 5. Keep 2 open as a glossary.
+
+## Reference pages (already in the repo)
+
+| Page | What it is |
+|---|---|
+| [reference/config.md](reference/config.md) | every `.code-forge.yml` key, its type and default. Generated from `schema/code-forge.schema.json` |
+| [reference/blocks.json](reference/blocks.json) | the build blocks of this package and what each one owns |
+| [marketing/code-forge-story.md](marketing/code-forge-story.md) | the marketing content bank (copy, lessons, what not to claim) |
+| [`skill/SKILL.md`](../skill/SKILL.md) and [`skill/references/`](../skill/references/) | the Agent Skill the orchestrator follows. The deepest and most exact description of the rules |
+
+## Conventions in these pages
+
+- `code-forge <verb>` is the CLI installed globally with `npm install -g @codedology/code-forge`
+  (see [getting-started.md](getting-started.md#install); a per-project pinned install is covered
+  there too). Inside the skill the same CLI is called `forge` (a shim at `skill/scripts/forge`).
+- `<run>` is a run id, `<slug>` is the project slug (`project.slug` in `.code-forge.yml`, else the
+  folder name), `<id>` is a block id such as `B1`.
+- "Not yet" marks something that is designed but not built. Nothing else on these pages is a plan.