orc-pack v1.11.0

[1.11.0] - 2026-10-06

Summary. Every orc run now works to a written work contract, and a new scope-reviewer holds each diff to it. Before it plans, orc writes one sentence naming the exact files and symbols it believes the request means, what's in and out of scope, every integration marked real or mocked, its user-facing assumptions, and three to six acceptance criteria that each name a test. Builders write those tests first and show them failing before they write the change, and the report maps each criterion to its passing test. This targets the two costliest failure modes of unattended runs: a wrong approach (for example, a mock where the real API was wanted) and a misread request. /orc contract first … adds an approval stop before building. A new optional skill, /shipcheck, verifies a pushed commit all the way to the live build: it waits for CI and fixes a red run, checks that the target environment has every required secret, waits until the deployment serves that exact commit, and runs browser smoke checks at phone and desktop widths in both themes. Separately, undirected orc runs stop picking issues that are already fixed: the issue scout checks each candidate against the integration branch's history first, and orc closes the stale ones with evidence.

Changed areas.

• skills/shipcheck/SKILL.md (new) — run after a push. Watches the commit's CI runs with gh run watch; on a red run it reproduces the failing command locally, dispatches a builder to fix it, and re-pushes, at most 2 attempts, never onto main, master, or production. Compares the secret names in .claude/required-secrets.md with what the target environment has (GitHub Actions, GitHub environments, Vercel, Cloudflare Workers), never reading a value, and stops on any missing name. Proves the deployment serves the pushed SHA before testing. Runs every flow in .claude/smoke-checklist.md in Claude in Chrome at 390px and 1440px in light and dark mode, with a screenshot per step. Stops with exact unlock instructions at an SSO, auth, or VPN wall. Turns each confirmed regression into a fix/<slug> branch with a reproducing test (pushed, never merged), or an issue with screenshot paths and a root-cause hypothesis. Both .claude/ files are repo-owned; shipcheck drafts them from the code when they are missing. Copy it in for a copied install.
• skills/orc/references/work-contract.md (new) — the contract template: restatement, in scope (with pre-approved cleanup: touched-file slop, code the change made dead, a typo beside the change), out of scope, integrations (real by default; MOCKED only when asked), assumptions as question and answer, and acceptance criteria with the test that proves each. Pack-owned reference file; copy it with the rest of references/.
• agents/scope-reviewer.md (new) — Opus 5.5 at low effort. Checks a task's diff against the contract: hunks that trace to nothing in it (Warning), criteria with no proving test or a test that passes without the change (Blocker), and mocks or stubs in production paths where the contract says real (Blocker). Copy it in.
• skills/orc/SKILL.md, 3. Make it buildable — new Write the contract step after the ladder: orc writes <scratchpad>/contract.md, states the restatement in one line in chat, and posts the contract on the issue as a Work contract comment. New Contract first (opt-in): with contract first at the start of the invocation, orc asks one approval question before building, takes a change as free text, and builds after at most a second answer. Preflight strips the new opt-in words alongside efficiency mode and, for contract first, stops before touching anything when it can't ask. A batch gets one contract with criteria tagged by issue. What orc does NOT do names the two pre-build questions as the only ones. Refresh.
• skills/orc/SKILL.md, 4 and 5 — tasks are decomposed from the contract's criteria, each criterion owned by one task. Builder dispatches carry the owned criteria with their tests and the contract path. scope-reviewer is a lane on every standard and structural task, and on a trivial task whose files the contract doesn't name. Reviewers get the contract path. Design-brief and design-review dispatches carry the contract and the task's criteria, and the verifier gets the contract when scope-reviewer raised findings. Orc reads each builder's Acceptance line first and sends a test that passed before the change straight back. A scope finding is fixed by reverting the change; one worth keeping becomes its own task, and a contract amendment is recorded in the commit body. Standards lists work-contract.md; Model selection lists scope-reviewer at low effort. Refresh.
• skills/orc/SKILL.md, Cleanup runs and 6. Discoveries — a cleanup run completes its contract after the audit, one In scope line and one criterion per task, with characterization tests exempt from failing-first. Keep the contract current: every task added after the contract (a Small follow-up, a cleanup candidate, a folded-in fix) gets an In scope line tagged follow-up before it is dispatched, so the scope review doesn't flag it. Refresh.
• agents/verifier.md — a confirmed departure from the work contract is a broken documented rule, never a Preference, and not Out of scope merely for sitting in a touched file. Refresh.
• skills/orc/SKILL.md, 9. Report — Landed maps each acceptance criterion to its proving test. Heads-up leads with any MOCKED integration, then the contract's assumptions. Refresh.
• skills/orc/references/builder-contract.md — build mode writes each acceptance test first and confirms it fails for the right reason, then the change; a new rule forbids mocks in production paths unless the contract marks the integration MOCKED; the contract's scope lists are binding; the report gains an Acceptance line (each criterion, its test, before and after). Build steps are renumbered 1 to 10. Refresh; no pack: marker.
• skills/newissue/SKILL.md — new Integrations section (real or mocked), and Done when is now three to six acceptance criteria a test can assert. The self-check covers both. Refresh.
• agents/next-issue-finder.md — new Screen out stale candidates section: two git log calls per candidate (by issue number, and by the paths the issue names) and a code read only on a hit. The output block gains an optional STALE: section, one line per stale issue with the commit and the code evidence. PICK: NONE now also covers a board where every candidate is stale. The agent stays read-only. Refresh.
• skills/orc/SKILL.md, 1. Survey — orc confirms each STALE entry itself, comments the commit and what the code now does, and closes the issue; if the evidence doesn't hold, it leaves the issue alone. Refresh.
• .github/workflows/pack-integrity.yml — the agent-name check also scans skills/shipcheck/SKILL.md, and the reference check covers work-contract.md. Kit CI only.
• INSTALL.md, README.md, CLAUDE.md — list the new skill, agent, and template (23 agents), describe the contract in the run flow, and a 1.11.0 banner. Kit docs only.
• Every skill and agent file — pack: marker moved to orc-pack@1.11.0.

Update steps. Copy the new agents/scope-reviewer.md and skills/orc/references/work-contract.md; orc dispatches the agent and passes the template by name, so an install without them breaks the review loop. Copy skills/shipcheck/SKILL.md to .claude/skills/shipcheck/SKILL.md unless the user declines it (it is optional, like newissue). Refresh agents/next-issue-finder.md, agents/verifier.md, skills/orc/SKILL.md, skills/orc/references/builder-contract.md, and skills/newissue/SKILL.md, and move every pack: marker to orc-pack@1.11.0. Never create or overwrite .claude/required-secrets.md or .claude/smoke-checklist.md; they are repo-owned. No CI, environment, or dependency changes in the target repo. If the install has local edits to next-issue-finder.md, keep the STALE: section of its output block: orc reads it. An install coming from 1.9.x or earlier also applies [1.10.0] and every entry in between.

Breaking changes. No settings or files are removed. Orc runs now post a Work contract comment on the issue they work, standard and structural tasks get one more review lane, and builder reports carry a new Acceptance line. If the install has local edits to builder-contract.md, re-apply them around the renumbered build steps and keep step 4 (tests first) and step 6 (real integrations). Anything that parses the scout's output must tolerate the new optional STALE: section between SET_ASIDE: and GUARDS:.

Files to read. skills/orc/references/work-contract.md, agents/scope-reviewer.md, skills/orc/references/builder-contract.md (Build mode, Scope, Report), skills/shipcheck/SKILL.md, agents/next-issue-finder.md (Screen out stale candidates, Output), and skills/orc/SKILL.md (Preflight, 1. Survey, 3. Make it buildable, 4, 5, Cleanup runs, 6. Discoveries, 9. Report, What orc does NOT do), and agents/verifier.md (Rules).

---