claude-company 0.2.0 → 0.2.3

package/.claude/hooks/guard_models.py

@@ -43,6 +43,26 @@ def load_manifest(root):
     return roles
 
 
+def load_builtins(root):
+    """Return {type: model} from company/models.json `builtins`, or None.
+
+    Mirrors load_manifest and fails open (None) on a missing/malformed/
+    unreadable file or section. Keys starting with '$' (e.g. "$comment") are
+    dropped so they are never treated as a spawnable type, and only string
+    model values are kept.
+    """
+    cfg = c.read_json_file(os.path.join(root, "company", "models.json"))
+    if not isinstance(cfg, dict):
+        return None
+    builtins = cfg.get("builtins")
+    if not isinstance(builtins, dict):
+        return None
+    return {
+        k: v for k, v in builtins.items()
+        if not k.startswith("$") and isinstance(v, str)
+    }
+
+
 def is_hotfix(root):
     task = c.active_task(root)
     return isinstance(task, dict) and task.get("type") == "hotfix"
@@ -67,15 +87,53 @@ def new_text(tool_name, tool_input):
     return "\n".join(parts)
 
 
-def handle_spawn(root, tool_input, roles):
+def handle_spawn(root, tool_input, roles, builtins):
     role = None
     for field in SPAWN_TYPE_FIELDS:
         val = tool_input.get(field)
         if val:
             role = val
             break
-    if role is None or role not in roles:
-        return  # unknown role -> allow
+    if role is None:
+        return  # no spawn type -> allow
+    if role in roles:
+        # OQ-MRA-02 assumption: roles governs on any collision - a type present
+        # in both `roles` and `builtins` is decided here, by the roles branch.
+        handle_role_spawn(root, tool_input, roles, role)
+        return
+    # Not a manifest role. A built-in agent type has no .claude/agents
+    # frontmatter to inherit from, so a bare spawn would silently take the
+    # SESSION model - require an explicit matching override.
+    if builtins is None:
+        return  # no builtins section -> builtin enforcement inert (fail open)
+    if role not in builtins:
+        return  # unknown type -> allow
+    pin = builtins[role]
+    override = tool_input.get("model")
+    if override == pin:
+        return  # explicit matching override -> allow
+    if is_hotfix(root):
+        c.log_bypass(root, HOOK, "spawn " + role, "hotfix mode")
+        return
+    if not override:
+        c.block(
+            root, HOOK, "spawn " + role,
+            "builtin spawn no override (pin {})".format(pin),
+            "BLOCKED: spawning built-in '{}' with no model override would "
+            "inherit the session model - built-in agent types have no "
+            "company/models.json frontmatter pin to fall back on.\n"
+            "Fix: pass model: '{}'".format(role, pin),
+        )
+    c.block(
+        root, HOOK, "spawn " + role,
+        "builtin spawn override {} != pin {}".format(override, pin),
+        "BLOCKED: spawning built-in '{}' with model '{}' contradicts "
+        "company/models.json (built-in pin: '{}').\n"
+        "Fix: pass model: '{}'".format(role, override, pin, pin),
+    )
+
+
+def handle_role_spawn(root, tool_input, roles, role):
     override = tool_input.get("model")
     if not override:
         return  # no override -> role inherits the manifest model, allow
@@ -124,8 +182,53 @@ def handle_frontmatter_edit(root, tool_name, tool_input, roles):
     )
 
 
+def check_spawn_wiring(root):
+    """Assert .claude/settings.json wires guard_models on the Task spawn tool.
+
+    Passes when some PreToolUse group has a matcher covering the Task tool -
+    "Task" is one of its "|"-separated alternatives (the shipped matcher is
+    "Task|Agent") - and one of that group's hooks runs a command referencing
+    guard_models.py. Only the project settings.json counts; settings.local.json
+    is ignored. Returns (ok, fixit_message).
+    """
+    fixit = (
+        "spawn enforcement is not wired: .claude/settings.json has no "
+        "PreToolUse matcher covering the Task spawn tool that runs "
+        "guard_models.py - re-run `claude-company install` or `update` to "
+        "re-add it."
+    )
+    settings = c.read_json_file(
+        os.path.join(root, ".claude", "settings.json")
+    )
+    if not isinstance(settings, dict):
+        return False, fixit
+    hooks = settings.get("hooks")
+    if not isinstance(hooks, dict):
+        return False, fixit
+    groups = hooks.get("PreToolUse")
+    if not isinstance(groups, list):
+        return False, fixit
+    for group in groups:
+        if not isinstance(group, dict):
+            continue
+        matcher = group.get("matcher") or ""
+        if "Task" not in matcher.split("|"):
+            continue
+        for h in group.get("hooks") or []:
+            if isinstance(h, dict) and "guard_models.py" in (
+                h.get("command") or ""
+            ):
+                return True, ""
+    return False, fixit
+
+
 def run_check(root):
-    """Compare every agent frontmatter against the manifest. Exit 0/1."""
+    """Compare every agent frontmatter against the manifest. Exit 0/1.
+
+    FR-MRA-06: this frontmatter/agent-file comparison is based ONLY on `roles`.
+    Built-in types live in the separate `builtins` section and never demand a
+    .claude/agents/<type>.md file, so their absence is never a mismatch here.
+    """
     roles = load_manifest(root)
     if roles is None:
         print("company/models.json missing or unreadable")
@@ -178,6 +281,19 @@ def run_check(root):
         print("\nmismatches:")
         for m in mismatches:
             print("  - " + m)
+
+    # LOUD wiring assertion (FR-MRA-07), gated on builtins presence.
+    # OQ-MRA-04 assumption: guard_models asserts only its OWN enforcement
+    # wiring. Old manifests without a `builtins` section (load_builtins ->
+    # None) skip this entirely and behave exactly as before.
+    wiring_ok = True
+    if load_builtins(root) is not None:
+        wiring_ok, fixit = check_spawn_wiring(root)
+        if not wiring_ok:
+            print("\nspawn wiring:")
+            print("  - " + fixit)
+
+    if mismatches or not wiring_ok:
         return 1
     print("\nall agent models agree with company/models.json")
     return 0
@@ -206,7 +322,7 @@ def main():
         if roles is None:
             sys.exit(0)  # no manifest -> fail open
         if tool_name in ("Task", "Agent"):
-            handle_spawn(root, tool_input, roles)
+            handle_spawn(root, tool_input, roles, load_builtins(root))
         elif tool_name in ("Edit", "Write", "MultiEdit"):
             handle_frontmatter_edit(root, tool_name, tool_input, roles)
     except SystemExit:

package/.claude/settings.json

@@ -1,4 +1,7 @@
 {
+  "env": {
+    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
+  },
   "permissions": {
     "deny": [
       "Read(./.env)",

package/ORCHESTRATOR.md

@@ -178,6 +178,11 @@ building agents into isolated worktrees:
 git worktree add .claude/worktrees/<task-slug> -b task/<task-slug>
 ```
 
+The Workflow tool is FORBIDDEN by default: its internal `agent()` spawns fire no
+PreToolUse events, so `guard_models` cannot pin their model - permit it only
+with explicit owner authorization and a `model` pin in every `agent()` call,
+including all early stages (see `company/METHOD.md`).
+
 Skeleton for a tech-lead (adapt for direct developer dispatch on `quick`):
 
 ```

package/company/GATES.md

@@ -65,7 +65,9 @@ These rungs are wired for this repo; a project inherits them and adds its own.
 - **G7 models (`python3 .claude/hooks/guard_models.py --check`).** The model
   routing manifest and agent frontmatter must agree: spawn overrides and
   per-agent model declarations match `models.json`, so no agent silently runs
-  on the wrong model. (Shipped in wave 1.)
+  on the wrong model. It also asserts the Task|Agent spawn hook is wired into
+  `.claude/settings.json`, so the enforcement cannot ship as code without teeth.
+  (Shipped in wave 1.)
 - **G8 audit - the last rung, network-bound.** A dependency and CVE scan: no
   known-vulnerable dependency ships. It runs last because it reaches the
   network; keep it blocking anyway.

package/company/METHOD.md

@@ -163,6 +163,16 @@ All under `company/state/`, all owned by the CEO:
 6. Business-policy open questions. Agents run on tagged fallbacks; the owner
    answers the question.
 
+## The Workflow tool is outside enforcement
+
+The Workflow tool runs its own internal `agent()` spawns that fire NO PreToolUse
+events - the hooks never see them, so `guard_models` cannot pin their model and
+they inherit the main-loop model. It is therefore FORBIDDEN by default in
+company projects. It is permitted only with explicit owner authorization AND a
+`model` pin in EVERY `agent()` call, including all early-stage agents: resuming
+a dead workflow re-runs the incomplete early-stage agents live, so partial
+pinning does not hold.
+
 ## Writing discipline
 
 All writing in this repository stays hook-clean: straight quotes, ' - ' rather

package/company/models.json

@@ -7,6 +7,13 @@
     "security-reviewer": "opus", "devops-engineer": "opus",
     "docs-librarian": "opus", "ideation-strategist": "opus"
   },
+  "builtins": {
+    "$comment": "Built-in agent types (Explore, general-purpose, Plan, claude) have no .claude/agents frontmatter pin, so a bare spawn silently inherits the SESSION model - guard_models therefore requires an explicit matching model override for these. The Workflow tool is hook-invisible (its agent() spawns fire no PreToolUse events) and is forbidden by default - see company/METHOD.md.",
+    "Explore": "opus",
+    "general-purpose": "opus",
+    "Plan": "opus",
+    "claude": "opus"
+  },
   "pricing": {
     "$comment": "OQ-W1-01 estimate only, NOT billing truth - used by .claude/hooks/cost_capture.py for rough spend visibility in company/state/costs.log and /standup. USD per million tokens (MTok). cache_write is 1.25x input, cache_read is 0.1x input.",
     "opus": {"input": 15, "output": 75, "cache_write": 18.75, "cache_read": 1.5}

package/company/state/DECISIONS.md

@@ -13,4 +13,10 @@ fallbacks until a row lands here._
 | 5 | 2026-07-10 | Enforcement design direction | Owner REJECTED budgets/role bans twice; approved principle-derived gates (mechanism 5 + written-record consistency) and demanded low-token injection + GitHub tracking gate | all future gate design |
 | 6 | 2026-07-15 | cli-update delivery (update subcommand + provenance manifest, PR #57, issues #54-#56) | ACCEPTED - owner: "test it, the merge it to main"; CEO re-tested end-to-end (edit kept, .new written, deleted file restored, config untouched), merged 7726c99, integrated main verified (213 hooks + 40 CLI + 56 engine green), witnesses W-014..W-016 | CLI, installer, frozen registry |
 | 7 | 2026-07-15 | cli-self-update delivery (update refreshes the CLI first via npx handoff, PR #60, issue #59) | ACCEPTED - owner: "push to main, then to npm"; merged a09b463, integrated main verified (213 + 57 green), witnesses W-017..W-018 | CLI driver |
-| 8 | 2026-07-15 | Release v0.2.0 to npm (target: the release/0.2.0 merge commit; notes: PR #57/#60 bodies) | Owner ORDERED the publish ("push changes to npm", "push to main, then to npm"). Semver: minor (two additive features). Publish executes with AUTHORIZED=1 once npm auth exists; whoami was 401 at prep time | npm registry |
+| 8 | 2026-07-15 | Release v0.2.0 to npm (tag v0.2.0 at 5913374; notes: PR #57/#60 bodies) | PUBLISHED 2026-07-15 by the OWNER manually from the clean tag clone (link-based npm 2FA - publishes are always owner-manual or git-CI, never agent-run). Registry verified: dist-tags.latest 0.2.0. Semver minor | npm registry |
+| 9 | 2026-07-15 | DevMesh migration (owner: "use claude-company on this WITHOUT breaking custom changes... preserve DevMesh specific context") | DELIVERED - umbrella root git-initialized (machinery only), primitive company ported to company/, all customizations preserved, stale docs archived (nothing deleted). Verification: invariants gate PASS, 6 frozen surfaces probe-blocked. Found+fixed upstream #67/#68 | DevMesh polyrepo |
+| 10 | 2026-07-15 | Release v0.2.1 to npm (patch: #64 enforcer arming, #67 merger fix + field-heal, #68 record-leak) | PREPPED by CEO (bump PR + tag on merge); publish is the owner's button per standing rule (link-based 2FA). SUPERSEDED by v0.2.2 (#12) before publish - registry never received 0.2.1 | npm registry |
+| 11 | 2026-07-22 | model-routing-arming delivery (builtins enforcement + wiring gate + migration + Workflow doctrine, PR #77, issues #74-#76) | ACCEPTED - owner: "merge everything and give command to push to npm"; CEO merged cd07fb6, integrated main verified (hooks 222 + npm 61 + engine 111 green, gates stamped), live enforcement certified (contradict/bare exit 2, match 0, dormancy probe red), witnesses W-026/W-027/W-028 | hooks, models.json, installer, doctrine |
+| 12 | 2026-07-22 | Release v0.2.2 to npm (rolls up unpublished 0.2.1 + #77 model-routing arming) | PREPPED by CEO; owner pushed tag v0.2.2 (at ad3dda8) but publish SUPERSEDED by v0.2.3 (#14) which adds #83 - registry goes 0.2.0 -> 0.2.3 directly | npm registry |
+| 13 | 2026-07-23 | spawn-depth-shipping delivery (CC 2.1.21 depth-1 flattening; template env + installer env merge + guards, PR #83, issues #79-#82) | ACCEPTED - owner: "merge it"; merged 6061814, CEO independent verification (224/61/123 green, merge probes, byte-identity), witness W-029 | template settings, installer, tests |
+| 14 | 2026-07-23 | Release v0.2.3 to npm (v0.2.2 content + #83 spawn-depth) | PREPPED by CEO per owner direction ("change to v0.2.3"); owner tags v0.2.3 at the release-PR merge commit and publishes from a clean tag clone (link-based 2FA, owner-manual); notes: PR #77/#83 bodies | npm registry |

package/company/state/RESUME.md

@@ -14,6 +14,35 @@ witnesses/models/tests/audit. Owner acceptance recorded (DECISIONS #3).
 
 ## 2. Next actions, in order
 
+000. model-routing-arming SHIPPED 2026-07-22 (PR #77 merged cd07fb6,
+   closes #74-#76; acceptance DECISIONS #11; witnesses W-026 wiring
+   assertion / W-027 merge byte-identity / W-028 bare-builtin block).
+   Integrated main verified by CEO: hooks 222 OK, npm 61, update
+   engine 111, --check 0, trace 21/21 after citation fix, live
+   certification (contradict/bare exit 2, match 0; dormancy probe:
+   Task|Agent group stripped -> --check exit 1 + fix-it). Worktree
+   and task branch removed; brief+spec archived to shipped/.
+   RELEASE 0.2.2 PREPPED (task release-0.2.2-closeout, quick): rolls
+   up unpublished 0.2.1 + #77. Release PR carries version bump,
+   trace-citation fix (test-side FR/BR citations + new
+   test_template_and_doctrine_shipped covering FR-MRA-01/11/12),
+   paperwork archive, DECISIONS #11/#12, board sync. AWAITING OWNER:
+   merge release PR if session dies before merge, then tag v0.2.2 at
+   its merge commit and publish from a clean tag clone (memory:
+   npm-publish-owner-only; registry still on 0.2.0). Near-miss worth
+   remembering: a .format arg mismatch made the wrong-override path
+   fail OPEN until the live replay caught it - pinned by
+   test_builtin_spawn_wrong_override_blocked.
+00. provenance-shipping SHIPPED 2026-07-15 (PR #65, d624cc3, closes #64;
+   witnesses W-019/W-020, 20/20): fresh installs now ship
+   company/provenance.json (enforcer armed by default); update NEVER
+   auto-arms, prints one notice line. Owner field audit found the gap.
+   PENDING OWNER BUTTON: 0.2.1 patch release to npm (0.2.0 on the
+   registry still has the gap - fresh 0.2.0 installs stay dormant).
+   Same flow as 0.2.0: bump PR, tag, owner publishes from clean tag
+   clone (memory: npm-publish-owner-only). Field guidance given: owner's
+   research repo stays disarmed until they create provenance.json after
+   Jul 28; gitignore data/ to stop stop_gate churn from training jobs.
 0. cli-update SHIPPED 2026-07-15: PR #57 merged (7726c99, closes #54-#56),
    owner acceptance DECISIONS #6, witnesses W-014..W-016 recorded (16/16),
    spec+brief archived to shipped/, worktree+branch removed, integrated main
@@ -29,14 +58,17 @@ witnesses/models/tests/audit. Owner acceptance recorded (DECISIONS #3).
 0c. cli-self-update SHIPPED 2026-07-15: PR #60 merged (a09b463, closes
    #59), acceptance DECISIONS #7, witnesses W-017..W-018 (18/18),
    integrated main 213+57 green. Worktree+branch removed.
-0d. ACTIVE: npm-release-0.2.0 (owner ORDERED publish - DECISIONS #8, do
-   not re-ask). On release/0.2.0 branch: version 0.1.1 -> 0.2.0,
-   spec/brief archived, board rows. Remaining: commit branch -> PR -> CI
-   -> merge -> `git tag v0.2.0 <merge commit> && git push origin v0.2.0`
-   -> `AUTHORIZED=1 npm publish` (prepublishOnly runs CLI+TUI+install
-   suites). ONLY blocker: npm whoami 401 - owner must run `npm login`
-   interactively. active-task.json cleared at release close (test_scope
-   was reset with the clear).
+0d. v0.2.0 PUBLISHED to npm 2026-07-15 (DECISIONS #8): tag v0.2.0 at
+   5913374, owner published manually from the clean tag clone. FIELD
+   LESSON (memory npm-publish-owner-only.md): owner npm 2FA is
+   LINK-BASED - no OTP codes exist; publishes are ALWAYS owner-manual or
+   git-CI, agent only prepares (bump PR, tag, clean tag clone, verified
+   placeholder gates.config). NEVER publish from the working checkout -
+   local gates.config wiring fails the placeholder test. Witnesses
+   W-017/18 landed via PR #62 (fab01e1). Candidate next: publish via CI
+   workflow (owner hinted "or through git ci"), #36, #37, tarball ships
+   repo board state (P3 hygiene, install never copies it), roadmap
+   #1-#11.
 1. delegation-enforcement SHIPPED 2026-07-10 (PR #49, f9e5dae, closes
    #42-#47; acceptance DECISIONS #4). Close-out PR in flight if session
    died mid-close: witnesses W-011..W-013 recorded, brief archived to

package/company/state/STATUS.md

@@ -3,13 +3,20 @@
 _Maintained by the CEO. Updated after every dispatch, merge, and CR decision._
 _Red stays red until proven green. Never average a status._
 
-_Last updated: 2026-07-15 - cli-update SHIPPED (PR #57 merged 7726c99, acceptance DECISIONS #6)._
+_Last updated: 2026-07-22 - model-routing-arming SHIPPED (PR #77 merged cd07fb6, acceptance DECISIONS #11); release 0.2.2 prepped._
 
 ## Active tasks
 
 | Task | Class | Lead/Agent | State | Gates | Notes |
 |---|---|---|---|---|---|
-| npm-release-0.2.0 | release | CEO | IN FLIGHT | integrated main green (213+57) | v0.2.0 bump + close-out on release/0.2.0 branch -> PR -> merge -> tag v0.2.0 -> AUTHORIZED=1 npm publish. ONLY blocker: npm whoami 401 - owner must `npm login`. Release record DECISIONS #8. |
+| spawn-depth-shipping | quick | developer | SHIPPED 2026-07-23 (PR #83 merged 6061814, closes #79-#82) | 224 hooks + 61 CLI + 123 engine green (dev AND CEO reruns); integrated main stamped | Template ships env CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=2; install/update merge env additively (user pin survives - proven); witness W-029. NOT yet on npm - registry still 0.2.0; owner has v0.2.2 tag+publish pending, and this lands in the NEXT release after that. |
+| release-0.2.3 | release | CEO | BUMP PR IN FLIGHT | 224 hooks + 61 CLI + 123 engine green on main | Supersedes unpublished v0.2.2 (tag pushed, never published): 0.2.3 = 0.2.2 content + #83 spawn-depth. Owner buttons after merge: tag v0.2.3 at merge commit, publish from clean tag clone. Registry 0.2.0 -> 0.2.3 directly. DECISIONS #12-#14. |
+
+## Shipped (recent)
+
+| Task | Date | Evidence |
+|---|---|---|
+| model-routing-arming | 2026-07-22 | PR #77 merged cd07fb6 (closes #74-#76); acceptance DECISIONS #11; witnesses W-026/W-027/W-028; live certification: builtin contradict/bare spawn exit 2, match 0, dormancy probe turns --check red; migration: builtins merge lands on install AND update automatically. |
 
 ## Wave position (programs only)
 
@@ -18,7 +25,12 @@ _Last updated: 2026-07-15 - cli-update SHIPPED (PR #57 merged 7726c99, acceptanc
 | adoption program 1-3 | all | SHIPPED 2026-07-10 | PRs 27/33/34/32/35 merged; acceptance DECISIONS #3 |
 | follow-up pair | docs-sync + adr-hardening | SHIPPED 2026-07-10 | PRs 38/39/40/41 merged; #28 + #31 closed; witnesses 10/10 on main |
 | cli-update | single workstream | SHIPPED 2026-07-15 | PR #57 merged (7726c99, closes #54-#56); integrated main 213+40+56 green; witnesses W-014..W-016; acceptance DECISIONS #6 |
-| cli-self-update | single workstream | SHIPPED 2026-07-15 | PR #60 merged (a09b463, closes #59); integrated main 213+57 green; witnesses W-017..W-018; acceptance DECISIONS #7 |
+| cli-self-update | single workstream | SHIPPED 2026-07-15 | PR #60 merged (a09b463, closes #59); integrated main 213+57 green; witnesses W-017..W-018 (landed via PR #62); acceptance DECISIONS #7 |
+| v0.2.0 npm release | release | PUBLISHED 2026-07-15 | PR #61 merged, tag v0.2.0 (5913374), owner published manually (link-based 2FA); registry latest=0.2.0; DECISIONS #8 |
+| provenance-shipping | quick fix | SHIPPED 2026-07-15 | PR #65 merged (d624cc3, closes #64); fresh installs arm the delegation enforcer, update never auto-arms; witnesses W-019/W-020; NOTE: 0.2.0 on npm still has the gap - 0.2.1 patch release recommended (owner button) |
+| settings-merger-fix | quick fix | SHIPPED 2026-07-15 | PR #69 merged (f17c3c4, closes #67); dedup per (matcher, command) in both engines; update HEALS broken field installs (hand-proven); witnesses W-021/W-022. DevMesh hand-patched meanwhile (its c1ecbf7) |
+| pack-leak-fix | quick fix | SHIPPED 2026-07-15 | PR #71 merged (d714892, closes #68); record trees scaffold empty + tarball negations; seeded negative test; witnesses W-023/W-024 |
+| devmesh-migration | consulting | DELIVERED 2026-07-15 | DevMesh polyrepo migrated to claude-company (its commits b3f0a47/7e08247/c1ecbf7): docs/team ported to company/, frozen registry live (6 surfaces probe-verified), make-gates mirrored, custom agents/skills/memory preserved, 2 upstream bugs found (#67/#68 - both now fixed) |
 
 ## Open CRs
 

package/company/state/WORRIES.md

@@ -15,8 +15,12 @@ wave/merge; P3 is polish._
 | P3 | git -C evades guard_commit subcmd parse | guard_commit.git_subcmd treats -C <dir> as the subcommand token, so `git -C x commit` bypasses commit gates (pre-existing, Mode C inherits) | Anti-adversary, out of doctrine scope; candidate issue against guard_commit |
 | P3 | Mode D lacks worktree-cwd exemption | Stop close-gate block message reads wrong if a worktree session ever gets an active-task.json (moot today - file is untracked) | Auditor worry #3; per-spec (mirrors stop_gate); revisit only if worktree sessions gain task state |
 | P2 | session_start 60-line cap can hide digest | Saturated RESUME+STATUS could truncate the active-task + execution digest lines | Lead worry P2, inherited behavior; candidate tail-reservation tweak in session_start |
+| P2 | provenance audit verdict parser is substring-naive | guard_provenance.py:487 records do-not-ship if the literal phrase appears ANYWHERE in the audit payload - a dispatch prompt that names the verdict vocabulary poisons its own record (hit 3x on release-0.2.2) | Candidate fix: parse the verdict from the response's verdict line only, or match anchored '## Verdict:'; file issue next machinery pass; interim rule: never write the phrase in an auditor prompt |
+| P2 | guard_tests resolves test_scope from main checkout | Worktree builders cannot commit brief-granted test edits until the CEO sets test_scope in MAIN's active-task.json - has now blocked two workstreams (cli-update, model-routing-arming) | Candidate fix: resolve test_scope from the target worktree, or dispatch protocol sets it whenever a brief grants test dirs; follow-up brief |
+| P3 | models.json merge is now a THIRD duplicated heredoc | install.sh/update.sh byte-identical coupling grew (settings, CLAUDE block, now models.json builtins) - divergence risk compounds | Same root cause as existing heredoc row; the byte-identity witness candidate (lead proposal 3) mitigates; fold into any future extraction task |
 | P2 | update.sh duplicates install.sh merge heredocs | The three merges (settings/mcp/CLAUDE block) + CC_BLOCK are copied verbatim; a future install.sh merge change silently diverges update | cli-update lead worry; candidate fixture test asserting install and update produce identical merges; extraction forbidden this pass by additive-only brief |
 | P3 | update spawns python3 per file (~3x/file) | ~180 spawns for 61 files - seconds today, slow at scale | Candidate manifest.py hashtree batch subcommand; not blocking |
 | P3 | manifest emission fails open at install | lib/ or package.json missing -> no manifest, update runs bootstrap-safe forever (never clean "updated") | By design (safe); revisit only if field reports show chronic manifest-less installs |
 | P3 | extensionless files count as source | guard_spec.is_source flags any extensionless file outside company/.claude/docs/.github (e.g. Makefile, a bare "report") - a non-code agent writing one hits the execution gate | Found in owner-requested gate probe 2026-07-15; md/json/state are proven exempt; candidate: extensionless allowlist if it ever bites |
 | P3 | guard_tests gates md inside tests/ | Any write under a tests/ segment is blocked without test_scope regardless of extension, incl. tests/**/*.md (docs-librarian MODULE.md case) | Defensible (tests are the oracle) but extension-blind; candidate: exempt NON_SOURCE_EXT under tests/ if doc syncs start colliding |
+| P3 | background writers stale the gate stamp | Field report 2026-07-15: a training job writing untracked non-ignored files (data/) stales work_hash every turn - stop_gate demands gate reruns | By design (.gitignore IS the ignore mechanism); candidate one-line docs FAQ: gitignore background-process output dirs |

package/company/witnesses.json

@@ -145,7 +145,106 @@
       "regex": false,
       "why": "Manifest byte-determinism contract: sorted keys, no clock field - the bin-vs-bare parity test depends on it",
       "added_at": "2026-07-14T22:13:07Z"
+    },
+    {
+      "id": "W-017",
+      "task": "cli-self-update",
+      "file": "lib/update.js",
+      "must_contain": "if (process.env.CC_SELFUPDATE_DONE) return null;",
+      "regex": false,
+      "why": "Handoff-exactly-once loop guard: the re-exec child never re-checks the registry",
+      "added_at": "2026-07-14T23:25:27Z"
+    },
+    {
+      "id": "W-018",
+      "task": "cli-self-update",
+      "file": "lib/update.js",
+      "must_contain": "if (versionCompare(latest, PKG.version) <= 0) {",
+      "regex": false,
+      "why": "Strictly-newer is the only re-exec trigger; equal or older proceeds silently with the current CLI",
+      "added_at": "2026-07-14T23:25:27Z"
+    },
+    {
+      "id": "W-019",
+      "task": "provenance-shipping",
+      "file": "install.sh",
+      "must_contain": "copy_if_absent \"$SRC/company/provenance.json\"        \"$TARGET/company/provenance.json\"",
+      "regex": false,
+      "why": "Fresh installs ship the arming manifest - the delegation enforcer is armed by default in the field",
+      "added_at": "2026-07-15T01:01:51Z"
+    },
+    {
+      "id": "W-020",
+      "task": "provenance-shipping",
+      "file": "update.sh",
+      "must_contain": "note: delegation enforcer installed but disarmed - create company/provenance.json to arm",
+      "regex": false,
+      "why": "update never auto-arms - a payload refresh must not switch a project's enforcement regime",
+      "added_at": "2026-07-15T01:01:51Z"
+    },
+    {
+      "id": "W-021",
+      "task": "settings-merger-fix",
+      "file": "install.sh",
+      "must_contain": "have = commands_by_matcher(existing_groups)  # issue-67: dedup per matcher",
+      "regex": false,
+      "why": "Settings merge dedups per (matcher, command) - reverting to command-per-event re-drops multi-matcher hook groups",
+      "added_at": "2026-07-15T10:34:04Z"
+    },
+    {
+      "id": "W-022",
+      "task": "settings-merger-fix",
+      "file": "update.sh",
+      "must_contain": "have = commands_by_matcher(existing_groups)  # issue-67: dedup per matcher",
+      "regex": false,
+      "why": "update.sh merge block stays byte-identical to install.sh - the heal path for broken field installs depends on it",
+      "added_at": "2026-07-15T10:34:04Z"
+    },
+    {
+      "id": "W-023",
+      "task": "pack-leak-fix",
+      "file": "install.sh",
+      "must_contain": "\"$TARGET/company/change-requests\"   # issue-68",
+      "regex": false,
+      "why": "Record trees are scaffolded empty, never copied - reverting to copy_tree_if_absent re-leaks repo records into git-clone installs",
+      "added_at": "2026-07-15T11:14:01Z"
+    },
+    {
+      "id": "W-024",
+      "task": "pack-leak-fix",
+      "file": "package.json",
+      "must_contain": "\"!company/briefs/**\",",
+      "regex": false,
+      "why": "Tarball belt - dropping the files-negations re-ships repo records via npm",
+      "added_at": "2026-07-15T11:14:01Z"
+    },
+    {
+      "id": "W-026",
+      "task": "model-routing-arming",
+      "file": ".claude/hooks/guard_models.py",
+      "must_contain": "def check_spawn_wiring",
+      "regex": false,
+      "why": "run_check wiring assertion - regression means the models gate reads green while Task|Agent enforcement is unwired (code-without-wiring)",
+      "added_at": "2026-07-22T15:23:53Z"
+    },
+    {
+      "id": "W-027",
+      "task": "model-routing-arming",
+      "file": "update.sh",
+      "must_contain": "BYTE-IDENTICAL to the",
+      "regex": false,
+      "why": "models.json merge heredoc coupling marker - install and update must migrate identically",
+      "added_at": "2026-07-22T15:23:53Z"
+    },
+    {
+      "id": "W-028",
+      "task": "model-routing-arming",
+      "file": ".claude/hooks/guard_models.py",
+      "must_contain": "inherit the session model",
+      "regex": false,
+      "why": "Bare builtin-spawn BLOCK path - regression means built-in spawns silently inherit the session model (the live incident)",
+      "added_at": "2026-07-22T15:24:05Z"
     }
   ],
-  "checksum": "1179d1ca054e151ab34c6a0535acc2969de82f42991939c48a66f6b1acc18b02"
+  "checksum": "5789e76d6242c45d3e82f0ca3da8895c3e19753e2b88100fe8a44e6f38b6615f"
 }

package/docs/customizing.md

@@ -80,6 +80,8 @@ Each role is one markdown file in `.claude/agents/`. The file's frontmatter sets
 
   The same file carries a `pricing` map (USD per million tokens) that `cost_capture.py` reads to estimate spend in `company/state/costs.log` and the `/standup` Spend line. Update it when your rates differ; leave a model out of it and the standup reports raw token counts for that model instead of dollars. The numbers are estimates for visibility, never a bill.
 
+- **Arm or disarm the delegation enforcer**: `company/provenance.json` is the switch. A fresh install ships it, so the enforcer is armed by default; delete it to disarm every provenance mode (same rollout posture as `company/models.json`). An `update` never creates it - if a project lacks the file, update prints a one-line notice and leaves the enforcement regime unchanged, so refreshing the payload never silently arms a project.
+
 Two roles are load-bearing; change them carefully. `tech-lead` is the only agent allowed to spawn other agents, and `developer` carries the working rules every builder inherits.
 
 ## Adjust the founding defaults

package/install.sh

@@ -123,12 +123,56 @@ info "Installing project config and state (existing files preserved)"
 copy_if_absent "$SRC/company/gates.config"           "$TARGET/company/gates.config"
 copy_if_absent "$SRC/company/frozen-surfaces.json"   "$TARGET/company/frozen-surfaces.json"
 copy_if_absent "$SRC/company/models.json"            "$TARGET/company/models.json"
+# FR-MRA-09: arm model routing on a PRE-EXISTING models.json that predates the
+# builtins section by injecting the packaged template's builtins in place. On a
+# fresh install the target was just copied from the template (already carries
+# builtins), so the python no-ops and the file stays byte-identical to it.
+# COUPLING: the heredoc between <<'PY' and PY below is BYTE-IDENTICAL to the
+# models.json builtins-injection block in update.sh. Keep them identical; both
+# must merge the same way.
+MODELS_SRC="$SRC/company/models.json"
+MODELS_DST="$TARGET/company/models.json"
+if [ -f "$MODELS_SRC" ] && [ -f "$MODELS_DST" ]; then
+  python3 - "$MODELS_SRC" "$MODELS_DST" <<'PY'
+import json, sys
 
-# work directories - preserve any existing content
-mkdir -p "$TARGET/company/specs" "$TARGET/company/briefs" "$TARGET/company/change-requests"
-copy_tree_if_absent "$SRC/company/specs"           "$TARGET/company/specs"
-copy_tree_if_absent "$SRC/company/briefs"          "$TARGET/company/briefs"
-copy_tree_if_absent "$SRC/company/change-requests" "$TARGET/company/change-requests"
+# OQ-MRA-01 assumption: additive builtins injection by canonical
+# json.load/json.dump re-serialization on the one injecting run. Inject the
+# packaged template's `builtins` only when the target manifest lacks it,
+# preserving the VALUES of roles/pricing/version and any user keys. When
+# `builtins` is already present, emit the target bytes verbatim (no write) so
+# the file stays byte-unchanged.
+src_path, dst_path = sys.argv[1], sys.argv[2]
+with open(src_path) as f:
+    src = json.load(f)
+try:
+    with open(dst_path) as f:
+        tgt = json.load(f)
+except (FileNotFoundError, ValueError):
+    sys.exit(0)  # nothing to merge into - config-if-absent restores separately
+if not isinstance(tgt, dict) or "builtins" in tgt:
+    sys.exit(0)  # already armed (or unmergeable) - leave the target untouched
+src_builtins = src.get("builtins")
+if not isinstance(src_builtins, dict):
+    sys.exit(0)  # template carries no builtins - nothing to inject
+tgt["builtins"] = src_builtins
+with open(dst_path, "w") as f:
+    json.dump(tgt, f, indent=2, sort_keys=False)
+    f.write("\n")
+PY
+fi
+# issue-64: ship provenance.json copy_if_absent so a fresh install arms the
+# delegation enforcer by default (present is never touched, not in the manifest).
+copy_if_absent "$SRC/company/provenance.json"        "$TARGET/company/provenance.json"
+
+# work directories - scaffold as EMPTY dirs only. issue-68: these trees are
+# where a target project writes its OWN specs, briefs, and change requests; we
+# never copy this package's records (spec-*.md, brief-*.md, CR-*.md, shipped/**)
+# into a target. Copying them leaked our work records into every install.
+mkdir -p \
+  "$TARGET/company/specs" "$TARGET/company/specs/shipped" \
+  "$TARGET/company/briefs" "$TARGET/company/briefs/shipped" \
+  "$TARGET/company/change-requests"   # issue-68
 
 # --- 4. scaffold state stubs (only if absent) -----------------------------
 info "Scaffolding company/state"
@@ -178,14 +222,22 @@ except (FileNotFoundError, ValueError):
     theirs = {}
 
 # --- merge hooks: append our command entries unless already present -------
-def commands_in_event(groups):
-    cmds = set()
+# issue-67: dedup key is (matcher, command), not command-per-event. A command
+# may legitimately appear under several matcher groups of one event
+# (guard_provenance under Edit|Write|MultiEdit AND Task|Agent AND Bash); a
+# per-event set dropped every repeat after the first, emptying and then losing
+# whole groups. Keying by matcher keeps each group complete.
+_NO_MATCHER = object()  # sentinel key for groups that carry no matcher
+
+def commands_by_matcher(groups):
+    seen = {}
     for g in groups or []:
+        bucket = seen.setdefault(g.get("matcher", _NO_MATCHER), set())
         for h in (g.get("hooks") or []):
             c = h.get("command")
             if c is not None:
-                cmds.add(c)
-    return cmds
+                bucket.add(c)
+    return seen
 
 our_hooks = ours.get("hooks") or {}
 their_hooks = theirs.setdefault("hooks", {}) if isinstance(theirs.get("hooks", {}), dict) else {}
@@ -198,16 +250,17 @@ for event, our_groups in our_hooks.items():
     if not isinstance(existing_groups, list):
         existing_groups = []
         their_hooks[event] = existing_groups
-    have = commands_in_event(existing_groups)
+    have = commands_by_matcher(existing_groups)  # issue-67: dedup per matcher
     for g in (our_groups or []):
+        bucket = have.setdefault(g.get("matcher", _NO_MATCHER), set())
         new_hooks = []
         for h in (g.get("hooks") or []):
             c = h.get("command")
-            if c is not None and c in have:
-                continue  # identical command already present
+            if c is not None and c in bucket:
+                continue  # identical command already present under this matcher
             new_hooks.append(h)
             if c is not None:
-                have.add(c)
+                bucket.add(c)
         if new_hooks:
             ng = dict(g)
             ng["hooks"] = new_hooks
@@ -229,6 +282,23 @@ if our_deny:
         if entry not in their_deny:
             their_deny.append(entry)
 
+# --- merge env: add our keys the user lacks, never overwrite theirs --------
+# spawn-depth fix: ship CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=2 so a tech-lead
+# can still spawn its developers/QA (Claude Code 2.1.21 defaulted subagent
+# spawn depth to 1, flattening the org). Additive-only, same spirit as
+# permissions.deny above: a user-pinned value (e.g. depth "3") is NEVER
+# overwritten. A theirs.env that is not a dict is replaced-safe (treated as
+# empty, then ours is set) so the merger never bricks an install.
+our_env = ours.get("env") or {}
+if our_env:
+    their_env = theirs.get("env")
+    if not isinstance(their_env, dict):
+        their_env = {}
+        theirs["env"] = their_env
+    for key, value in our_env.items():
+        if key not in their_env:
+            their_env[key] = value
+
 with open(dst_path, "w") as f:
     json.dump(theirs, f, indent=2, sort_keys=False)
     f.write("\n")