v0.7.0

Cleanup + performance release. Honors the --tool both deprecation from v0.6.0 and delivers a measured 3× speedup on doctor and pilot warm calls via cached hardware probing.

Highlights

Removed (breaking)

• --tool both removed. The CLI exits with the standard three-line error block when it's used. Replace with --tool opencode,openclaude. See Upgrading.
• _normalize_persisted_intake back-fill helper removed. A project.json written by 0.5.x that was never updated through 0.6.x silently ignores its legacy tool / agent keys and falls back to DEFAULT_TOOLS (opencode). Re-run coding-scaffold setup run to regenerate.
• IntakeAnswers.agent property removed. Use IntakeAnswers.tools[0].
• Stale "both"-handling branches in installers.build_install_plans and cli._maybe_setup_knowledge cleaned up.

Changed

• probe_hardware() is now cached at $XDG_CACHE_HOME/coding-scaffold/hardware.json (default ~/.cache/coding-scaffold/hardware.json). 1-hour TTL keyed on OS / arch / Python version so it self-invalidates when any change.

  Surface	Cold	Warm	Speedup
  doctor	243ms	78ms	3.1×
  pilot	235ms	79ms	3.0×

  New --no-probe-cache flag on doctor / pilot / probe forces a fresh probe — use after installing a new local runtime like ollama.

• CODING_TOOLS / VALID_TOOLS consolidated into one source of truth in intake.py. The drift-detection test that policed the previous duplication is replaced with a one-line derivation invariant.

Tests

• pytest-xdist enabled. Test suite ~22s sequential → ~3s parallel (-n auto). 637 tests passing.

Upgrading from 0.6.x

uv tool upgrade coding-scaffold     # or: pipx upgrade coding-scaffold
coding-scaffold setup update --target .

If any of your scripts still call --tool both, replace with --tool opencode,openclaude. If you have a project.json written by 0.5.x that was never updated through 0.6.x, run setup run to regenerate it in the modern shape. See the Upgrading guide for the full breaking-change story.

What's not here

Release-cycle discipline matters: this release honors only the deprecation promise from v0.6.0 and delivers one real perf optimization. No new features.

v0.6.0

First release with multi-tool projects as a first-class concept: a single repo can configure (and a single user can pilot) two coding tools — e.g., Codex + Claude Code — in one setup run.

coding-scaffold setup run --target . --tool codex --tool claude-code
# or equivalently:
coding-scaffold setup run --target . --tool codex,claude-code

coding-scaffold pilot --target . --tool codex,claude-code

Pilot prints one shared setup step plus a per-tool agent step at the bottom; setup update keeps both tools' adapter files (AGENTS.md for Codex, CLAUDE.md for Claude Code) in sync.

Highlights

Added

• Multi-tool --tool support across setup run, tools adapt, setup tool, and pilot. See Two tools in one repo.
• coding-scaffold tour — read-only five-screen walkthrough explaining the tool, artifact families, and daily workflow. Closes #91.
• --persona flag on doctor and pilot — beginner, control, security, team-lead. Closes #90.
• Stability markers in --help — [stable] / [preview] / [experimental] next to every top-level command. See Stability. Closes #95.
• Per-subcommand --help with descriptions, when-to-run, and worked examples. Closes #89.
• Doctor rationale lines — each artifact doctor surveys now carries a → why this matters line. Closes #87.
• setup update --force + min_supported_scaffold_version field — guards against running an older scaffold on a project upgraded with a newer one. Closes #96.
• setup update prints a .new reconciliation recipe when sidecars are produced (diff → merge → delete → eval).

Fixed

• Template renderer no longer leaks ${undefined} into user files — missing keys or surviving ${...} tokens raise UnresolvedTemplateError naming the template + key, before the file is written. Fixes #94.

Changed (breaking)

• routing.json, project.json, and pilot JSON output now carry tools (a list) only. The singular tool key is gone. Read tools[0] if you need a single value. Legacy project.json files are back-filled when setup update reads them; the back-fill helper is removed in 0.7.0.
• Unified error message style — every CLI failure prints the same error: ... / next: ... / see: ... three-line block. See Errors and Recovery. Closes #92.

Deprecated

• --tool both is deprecated (still works in 0.6.x with a stderr warning) and will be removed in 0.7.0. Use --tool opencode,openclaude instead.

Documentation

• Four new wiki pages: Glossary, Stability, Upgrading, Errors and Recovery.
• Wiki index + README route to the new pages; FAQ gained entries for unfamiliar terms, persona-targeted recipes, error recovery, stability marker contract, and the upgrade path.

Tests

• Test count: 351 → 635 (filled coverage gaps for file_ops, scaffold_version, doctor, pilot, session round-trip, pr_template; added acceptance-criteria audit suite for the team/knowledge issues #97–#105; added end-to-end multi-tool coverage). Closes #93.

Upgrading from 0.5.x

uv tool upgrade coding-scaffold     # or: pipx upgrade coding-scaffold
coding-scaffold setup update --target .

If your project.json was written by 0.5.x with a singular tool field, setup update back-fills it to the new tools list automatically. See the Upgrading guide for the full contract — .new recipe, rollback, version pinning, and the planned 0.7.0 breaking changes.

Closed issues

#87, #88, #89, #90, #91, #92, #93, #94, #95, #96, #97, #98, #99, #100, #101, #102, #103, #104, #105.

v0.5.1

Fixed

• pilot now prints a valid setup recipe using setup run --install-tools when the selected tool is missing.
• pilot readiness now accounts for whether the selected coding tool is installed.
• doctor default text output is focused; legacy hardware/provider details are available with doctor --verbose.

Documentation

• README and docs site now route users by need with a clearer first-contact command map.
• Published docs homepage, wiki index, Getting Started, FAQ, Team Rollout, and Team Onboarding emphasize doctor + pilot for first contact and postpone advanced features.
• Cleaned up stale docs paths and command wording.

Validation

• uv run ruff check
• uv run pytest -q
• npm run build (docs)
• uv build

v0.5.0 — Progressive CLI UX: doctor + pilot + grouped help

Minor release. The CLI surface is unchanged from v0.4.2, but the entry point for new users is finally clear: `doctor` and `pilot`. No commands removed or renamed; every hidden compatibility alias still parses.

The three commands a new user needs today

```bash
coding-scaffold doctor --target . # what's set up, what's next
coding-scaffold pilot --target . --tool opencode # print the 10-minute happy path

follow the printed steps

```

What's new

Top-level help grouped by user journey

`coding-scaffold --help` now opens with four labelled sections:

• START HERE — `doctor`, `pilot`, `setup run --mode beginner`
• 10-MINUTE PILOT — the exact three commands the printed recipe expands to
• DAILY WORKFLOW — `session init`, `context lint`, `eval run`
• ADVANCED / GOVERNANCE — `policy`, `mcp`, `skills`, `memory`, `team`, `permissions`, `tools`, `knowledge distill` — explicitly marked as safe to ignore until the team needs them

The full alphabetical command list still prints below as usual.

`coding-scaffold doctor` as accessibility hub

• Accepts `--target` and `--json`.
• Surveys 14 scaffold-artifact paths (AGENTS.md, PR template, `.coding-scaffold/` and sub-directories, eval-config, language signal files).
• Recommends 1-3 context-aware next commands tailored to what's present. Empty repo → `pilot` + `setup run`. Partial setup → `pr-template init` or `session init`. Fully set up → `eval run`.
• Explicitly names the advanced surfaces under "Ignore for now (advanced)" so a new user doesn't have to keep them in their head.

`coding-scaffold pilot --target . --tool opencode`

A safe guided wrapper. Runs only read-only local checks (Python version, `git` on PATH, the chosen tool's binary on PATH, credentials in env, local-runtime CLIs) and then prints the exact three-step recipe tailored to your environment.

• Never installs anything. The printed recipe may include `--install` flags, but the user makes that call.
• Never writes files.
• Supports all six tools: `opencode`, `claude-code`, `codex`, `openclaude`, `hermes`, `pi`.
• `--json` for machine consumption.

Docs

• README adds a "30-Second Start" block at the top.
• `docs/wiki/Getting-Started.md` adds a "Smallest Useful Path" section.

Verification

• `uv run ruff check` clean.
• `uv run pytest -q` → 327 passed (was 311, +16 new tests).
• `coding-scaffold eval run --target .` → 9/9 passed on this repo.

Backwards compatibility

Fully backwards compatible with v0.4.2. Power users: every existing command and every hidden compatibility alias still works identically. The grouped help description is additive; argparse still lists every visible command alphabetically below.

Full notes: CHANGELOG.md.

v0.4.2 — Dogfooded baseline + MCP detection fix

Patch release. Two changes since v0.4.1, plus a doc clarification.

Added

Dogfooded baseline on the scaffold's own repo (narrow scope)

The scaffold now runs itself on its own repository, adopting only the bits the project actually uses:

• `AGENTS.md` at the repo root documents the real maintainer workflow: verification commands (`uv run ruff check`, `uv run pytest -q`), the no-runtime-dependency / no-LLM-calls / no-network / no-telemetry posture, the plain commit-message convention, and when to use session traces (3+ modules touched, or architectural changes).
• `.github/PULL_REQUEST_TEMPLATE/agentic-change.md` generated by `coding-scaffold pr-template init` — same artifact users get.
• `.coding-scaffold/eval-config.json` runs the readiness benchmark as a smoke check with `policy_exists` and `denied_files_configured` disabled. This repo IS the policy generator; it does not generate policy for its own development. The MCP check auto-skips because no MCP servers are declared.
• `.coding-scaffold/sessions/.gitkeep` keeps the session-trace location available for larger PRs.

Result: `coding-scaffold eval run --target .` reports 9/9 checks passed on the scaffold's own repo.

Fixed

`eval mcp_policy_exists_if_mcp_detected` no longer false-flags on file presence alone

The check previously treated any of `opencode.json`, `.claude/settings.json`, `.claude/settings.local.json`, or `.codex/config.toml` existing as "MCP in use". But `.claude/settings.local.json` is commonly present in Claude Code installs without any MCP entries — file existence alone, not declared servers.

The check now uses `scan_mcp` and only fires when at least one server is actually parsed from a config. One new regression test.

Documentation

The 10-minute team pilot path is now clearer in README.md, docs/wiki/Getting-Started.md, and docs/wiki/Team-Rollout.md.

Verification

• `uv run ruff check` clean.
• `uv run pytest -q` → 311 passed.
• `coding-scaffold eval run --target .` → 9/9 passed on the scaffold's own repo.
• `coding-scaffold context lint --target .` → 0 findings on the scaffold's own repo.

Backwards compatibility

Fully backwards compatible with v0.4.1. Users running `coding-scaffold eval` against a project that has a `.claude/settings.local.json` without MCP entries will now correctly see the check skip rather than incorrectly fail.

Full notes: CHANGELOG.md.

v0.4.1 — Codex review fixes (eval / MCP / lockfile)

Patch release. Three Codex-review findings, all real bugs, fixed in one focused PR.

Fixed

eval `test_command_detected` false positive on empty repos

The check previously trusted the absence of the linter's `missing-build-test-commands` finding as proof. But that finding only fires when context files exist, so an empty repo got the contradictory pair "no agent-context files exist" + "recognizable test commands mentioned."

The check now scans agent-context files directly for any of the recognized verifier tokens, with word-boundary-aware matching so short tokens like `ci` no longer match inside `precise` or `decision`.

MCP `server-not-approved` toothless under default policy

The generated default policy declares `unapproved_servers: "deny"` with an empty `approved_servers` list. But `_check_server` short-circuited the unapproved check on empty allowlist, silently allowing every detected server under the default policy.

The check now tracks the policy posture: `deny` → severity `error`; `requires_approval` → severity `warning`; permissive default stays informational. Without a policy file, the scanner has no opinion (unchanged).

`uv.lock` stale

`uv.lock` recorded `coding-scaffold v0.1.0` even though `pyproject.toml` had moved to 0.4.0 across the v0.2.0, v0.3.0, and v0.4.0 cuts. Re-locked so `uv sync` no longer produces an accidental local diff on first checkout.

Verification

• `uv run ruff check` clean.
• `uv run pytest -q` → 310 passed (was 304, +6 regression tests).

Known dogfooding gap

The Codex review noted that the scaffold's own repo scores low on `coding-scaffold eval run`. True. Addressing that requires running `setup run` on this codebase and committing the generated artifacts, which deserves its own PR. Tracked as future work, not in this patch.

Backwards compatibility

Backwards compatible with v0.4.0. Two minor behavior changes worth knowing:

• Repos with a default-policy file but no `approved_servers` entries will now see `server-not-approved` (severity `error`) for every detected MCP server. This is intentional — the previous behavior contradicted the policy's stated `deny` default.
• `eval run` against an empty repo now correctly fails the `test_command_detected` check (it previously passed by accident).

Full notes: CHANGELOG.md.

v0.4.0 — Reversible agentic work, memory governance, Codex MCP

Minor release. Closes the last two priorities from the maintainer brief plus the deferred Codex TOML parsing.

Reversible agentic work (priority 5)

coding-scaffold session start [--worktree]  Create a branch (or worktree); commit a baseline
coding-scaffold session checkpoint -m ...   git add -A + commit + record in session state
coding-scaffold session diff                Files changed since the start commit
coding-scaffold session rollback            Preview by default; --confirm for soft reset;
                                            --confirm --hard for a destructive reset
coding-scaffold session summary             Branch, baseline, checkpoint count, files changed

Never auto-pushes. Never deletes work without `--confirm --hard`. The per-session state file is git-ignored so it doesn't pollute checkpoint commits.

Memory governance (priority 6)

coding-scaffold memory capture --class X --content ...  Reviewable Markdown entry; class=secret
                                                        is refused outright; personal_data requires
                                                        --allow-personal; content matching the
                                                        secret-pattern heuristic is refused
coding-scaffold memory review               List active entries; flag unowned / expiring / expired
coding-scaffold memory promote <id> --to Y  Copy to a more durable class; original is kept and
                                            marked status=promoted (audit trail)
coding-scaffold memory expire               Move past-expiry entries to memory/_expired/
coding-scaffold memory audit                Heuristic scan for secrets (error severity) and
                                            PII (warning); exits non-zero on error
coding-scaffold memory init                 Optional config.json documenting the backend

Memory classes: `project_fact`, `team_preference`, `decision`, `session_lesson` (default 30-day TTL), `failed_attempt`, `personal_data` (restricted), `secret` (never stored).

Backend: Markdown only in v1. SQLite / MemPalace / vector are reserved for future versions.

Codex .codex/config.toml parsing

`mcp scan` now reads Codex's TOML configuration in addition to `opencode.json` and `.claude/settings.json`:

• Canonical form: `[mcp_servers.]`
• Legacy fallback: `[mcp.]`
• Malformed TOML is a warning, not a crash.
• Uses stdlib `tomllib`. No new dependencies.

The eval harness's MCP-policy check inherits the new source automatically.

Verification

304 tests passing, ruff clean, CI green on Linux.

Properties

• Zero new dependencies.
• Zero LLM calls.
• Zero network calls.
• Zero telemetry.
• Every new command supports `--json` for CI / scripting.
• Backwards compatible with v0.3.0.

Cumulative scope across v0.1.0 → v0.4.0

All seven maintainer-brief priorities are now implemented:

Priority	Theme
1	Agent-context linter (`context lint` / `explain`)
2	PR template + session traces (`pr-template init`, `session init / summarize`)
3	MCP and skill governance (`mcp policy / scan / snapshot / diff`, `skills new / lint / approve / export`)
4	Machine-readable permissions (`permissions write`)
5	Reversible work (`session start / checkpoint / diff / rollback / summary`)
6	Memory governance (`memory capture / review / promote / expire / audit / init`)
7	Readiness benchmark (`eval init / run / report`)

Full notes: CHANGELOG.md.

v0.3.0 — Reviewable agent surface + governance + readiness benchmark

Minor release. 17 new commands since v0.2.0, split across two themes.

Reviewable agent surface (priorities 1 & 2)

coding-scaffold context lint        Heuristic linter for AGENTS.md / CLAUDE.md / llms.txt
coding-scaffold context explain     Summary of the agent-context surface

coding-scaffold session init        New session-trace Markdown file
coding-scaffold session summarize   Read structured fields back

coding-scaffold pr-template init    Write .github/PULL_REQUEST_TEMPLATE/agentic-change.md

Governance + readiness (priorities 3, 4, 7)

coding-scaffold permissions write   Machine-readable agent-permissions.json

coding-scaffold mcp policy init     Team MCP policy
coding-scaffold mcp scan            Inspect opencode.json + .claude/settings.json
coding-scaffold mcp snapshot        Record current server set with fingerprints
coding-scaffold mcp diff            Drift detection (exits non-zero on drift)

coding-scaffold skills new <name>   Scaffold a reviewable skill pack
coding-scaffold skills lint         Flag broad-usage / hidden-instruction / undeclared caps
coding-scaffold skills approve      Record CHECKSUM
coding-scaffold skills export       tar.gz a skill for sharing

coding-scaffold eval init           Optional config for the readiness benchmark
coding-scaffold eval run            Deterministic readiness checks; exits non-zero on fail
coding-scaffold eval report         Print the most recent run

Verification

266 tests passing, ruff clean, CI green on Linux.

Properties

• Zero new dependencies.
• Zero LLM calls.
• Zero network calls.
• Zero telemetry.
• Every new command supports `--json` for CI / scripting.
• Backwards compatible with v0.2.0 — every existing command and generated file is unchanged.

Out of scope (deferred)

• Priority 5 — git worktree / checkpoint mode for reversible agentic work.
• Priority 6 — memory governance (capture / review / promote / expire / audit with memory classes).

Both will land in a follow-up.

Full notes: CHANGELOG.md.

v0.2.0 — Foam knowledge backend + docs consistency

Minor release. Headline addition is the Foam knowledge backend; the rest is the docs/consistency work and the case-collision regression guard that landed since v0.1.0.

Added

Foam knowledge backend

coding-scaffold knowledge create --target . --backend foam

Generates a self-contained VS Code workspace under .coding-scaffold/knowledge/:

• .vscode/extensions.json — recommends foam.foam-vscode on first open.
• .vscode/settings.json — Foam workspace defaults (graph view, daily-note directory, ignores .git/ and team _repo/).
• .foam/templates/{decision,skill,agent}.md — note templates.
• FOAM.md — entry note explaining the workflow.

Foam is MIT-licensed and runs entirely in VS Code — a commercial-friendly alternative to Obsidian for organizations of more than two people that would otherwise need a paid Obsidian Commercial license. See Knowledge Base / Foam.

Fixed

• Knowledge index case-collision hardening. Stale index.md reference in the generated AGENTS.md cleaned up; golden-output tests gained an automatic _casefold_collisions guard so any future case-sensitive vs case-insensitive filesystem mismatch is caught at test time, not in Linux CI after the fact.
• Misleading setup tool --install example in the README. Reworked so every tool is listed once for validate-and-configure and --install is shown once as a universal modifier — it's a flag on setup tool itself, not OpenCode-specific.
• Non-existent policy --strict flag removed from the control-and-reproducibility persona path.

Changed

• Compatibility matrix dedup. The README compatibility table was diverging from the canonical 11-row capability matrix in docs/wiki/Tool-Adapters.md. Collapsed to a quick-scan tool → support-depth strip linking to the canonical version.

Documentation

• 14 audit findings reconciled between code and docs (knowledge tree listings completed in README and Knowledge-Base.md to match what knowledge.py actually writes; INDEX.md casing corrected; Claude Code and Codex added to installer sentence; .coding-scaffold/team/sources/ added to outputs inventory).
• Review-Backlog reorganized: twelve items delivered as of v0.1.0 moved to a Delivered as of v0.1.0 section so the priority lists actually reflect remaining work.
• --share and --relaxed-permissions flags surfaced in docs/wiki/Policy-Packs.md.
• Wiki-style [[X]] links converted to relative Markdown so the docs render correctly when browsing docs/wiki/ in the repo on GitHub.

Verification

168 tests passing, ruff clean, CI green on Linux.

Upgrade notes

No breaking changes from v0.1.0. The Foam backend is additive — existing markdown, obsidian, and mempalace knowledge bases continue to work unchanged.

Full notes: CHANGELOG.md.

v0.1.0 — First tagged release

First tagged release of CodingScaffold. Positioned for a controlled team pilot, not yet for enterprise-wide governance.

Highlights

• Tool adapters for OpenCode (deep), Claude Code (native config), Codex (native config), OpenClaude / Hermes / Pi (guidance). Full capability matrix in Tool-Adapters.md.
• Policy packs that generate reviewable defaults for sharing, permissions, MCP servers, and provider allow/deny lists.
• Team-onboarding manifest workflow (team init / connect / sync / doctor) that confines third-party imports to .coding-scaffold/team/sources/ and never overwrites curated knowledge.
• Safe regeneration via setup update: drift in generated content is staged as .new; the version file only advances for files actually written to destination.
• Threat model documented in Security.md — install scripts, MCP, local runtimes, cloud providers, generated policy, team manifest content, audit expectations.

Start here

• Beginner / control / security review / team lead entry points are in Team-Rollout / Persona Paths.
• Pilot measurement template is in Team-Rollout / Pilot Metrics.

Install

git clone https://github.com/JRS1986/CodingScaffold.git
cd CodingScaffold
uv venv && source .venv/bin/activate
uv sync --extra dev
coding-scaffold setup run --target /path/to/your/project

See the full CHANGELOG for details.