[sellke]

Summary

Implements ADR-029. Writ doesn't get a writ CLI product. Instead, every script it ships to installed projects follows one agent contract, and a pytest test enforces it. Data tools print JSON. Check tools print pass/fail/unverifiable on line 1 and a summary last, and exit 0 when the check ran, 1 on fail, 2 on usage. No script spawns agents, waits without a bound, or calls the network without an opt-in. Six dev-only scripts stop shipping, and update.sh now handles stale scripts/ files correctly.

Changes

• Contract: new .writ/docs/agent-cli-contract.md with the rules and a classification of all 34 shipped scripts. ADR-029 gets a dated amendment covering the two output shapes, the exit codes, usage errors and bounded waits.

• Install and update: install.sh, update.sh and unlink.sh no longer ship pipeline-baseline, measure-invocation, harness-cost, lean-decision, prune-ledger or spawn-cap. update.sh now:

  • resolves scripts/ manifest paths at the project root (before, they were looked up under the platform folder and skipped);
  • removes scripts the ship filter rejects;
  • warns about a locally modified stale script, keeps it, and keeps its baseline so later updates warn again.

• Enforcement: new scripts/tests/test_agent_cli_contract.py checks every shipped script, read from the real is_shippable_script:

  • its classification row;
  • --help and bad-flag handling;
  • AST scans for network imports, agent launches and waits;
  • shape and exit-code smokes, 41 read-only runs.

  Its KNOWN_VIOLATIONS list started at 14 entries and is now empty.

• Script fixes: one commit per script, each carrying its callers and tests.

  • Python data tools:
    • revert-resolve, knowledge-consolidate and change-surface default to JSON, with --pretty for the old output and --json kept as a no-op.
    • boundary-map crossings prints JSON, and compute prints a blocker.
  • Python check tools: goal-emit, verdict-provenance, review-panel (all modes), gen-codex-agent-tomls and app-verify print the verdict first.
  • Shell checks: lint-skill.sh, gen-skill.sh and check-agent-parity.sh print the verdict first and handle --help and usage errors.
  • Other fixes:
    • test-integrity's parent-folder walk is bounded by a for loop.
    • roadmap-sync and goal-emit write atomically.

• Callers:

  • commands/implement-story.md Gates 0.5, 2.5, 3 and 4.5, plus the .lean twin. The file stays at its exact byte pin.
  • revert.md, knowledge.md, create-goal.md, implement-phase.md, create-uat-plan.md, new-skill.md, refresh-command.md, update-writ.md and the adapters.
  • scripts/eval.sh and .github/workflows/eval.yml. The gen-skill CI step now requires line 1 to be pass.

• Issues: resolves .writ/issues/features/2026-10-12-agent-facing-writ-cli.md. Files four problems found along the way:

  • update.sh deletes a modified stale file on its second run;
  • update.sh drops the Codex config baseline;
  • test-integrity's authenticity check flags every shell test;
  • whether shipped scripts should leave the project-root scripts/ folder.

Spec Reference

• Spec: .writ/specs/2026-10-12-agent-cli-contract/spec.md (Complete)
• Stories: story-1-contract-doc-and-adr-amendment.md, story-2-stop-shipping-dev-scripts.md, story-3-contract-test.md, story-4-conformance-fixes.md, story-5-shell-and-app-verify-conformance.md

Test Results

/ship did not run tests before the original PR was opened. The /implement-spec integration run on this branch after the final story:

• uv run pytest: 2614 passed, 2 skipped
• bash tests: 0 failures
• bash scripts/eval.sh: Findings 0
• exit-criteria verdict: met

This /ship (2026-10-20) merged origin/main. The only conflict was the lean-command pin comments in scripts/tests/test_lean_commands.py; both histories were kept, and the hashes already matched the merged command files. Re-run before merge:

• uv run pytest: 2614 passed, 2 skipped
• bash scripts/tests/test_*.sh: 0 failures
• bash scripts/eval.sh: Findings 0

Drift Report

12 Small, 8 Medium, 0 Large (drift-log.md). The Medium entries were each decided or approved by the maintainer during the run:

• The check shape covers every mode, including modes that write files. The conformance work was split into Stories 4 and 5. (Story 1)
• update.sh stale handling goes beyond the filter change. The spec wrongly assumed the old stale logic covered scripts/. (Story 2)
• The exit-code rule was amended to match the existing check scripts: unverifiable exits 0. (Story 3)
• The shell --help rule is stricter, and the smoke covers one mode per script, with modes added as they were fixed. (Story 3)
• The live-repo parity test checks output shape, not zero drift. An AC-4.5 test-citation gap was found by eval.sh after Story 4 was marked complete, and fixed in Story 5. (Story 5)

Review Notes

No standalone /review was run. Each story passed Gate 3:

• Stories 1–3 were reviewed by the evaluator agent.
• Stories 4 and 5 were risk-routed to the review agent.
• Every Gate 3 passed on iteration 1. Minor findings were fixed in follow-up commits.

The configured cross-vendor review panel (.writ/config.md) did not run. review-panel.py status --platform claude-code returns unverifiable (platform_cannot_spawn_other_vendors), and that status line was not printed in the story reports.

Things to check before merging:

• An installed project that updates its scripts without its commands would show /knowledge users JSON instead of the markdown report. update.sh copies both together.
• Gate 4.5 has no explicit branch for app-verify printing no verdict line, because of the byte pin.

🤖 Generated with Claude Code