fix(hierarchy): include transfer snapshots in replay content comparison

Review round 1 blocker: sameEvent omitted transferFrom/transferTo, so a
retried transfer re-routed to a different destination would silently
replay instead of conflicting. Transfer source/destination are semantic
event content per §5.2. Adds a witness varying the transfer destination
on a duplicate idempotency key; also fixes a stale cross-reference in
the db witness header.

docs/requirements/hierarchy-schema.md

@@ -72,25 +72,6 @@ example now lists the complete measured set, and the import analysis
 is extended to resolve literal dynamic `import()` routes, which two of
 the four members use.
 
-Amendment 1 (Ruling 4b, 2026-08-28): company visibility classes. The
-directory exists so one shared company can serve many users instead of
-each user creating a duplicate private company (Ruling 4b, webui-audit
-lane, ruled 2026-08-27). §2.1 gains a `visibility` column; §2.8 defines
-the two classes (`private`/`directory`), the directory's existence-only
-disclosure, and the pre-binding invariants for the deferred
-see-and-ask-to-join flow (no join-request surface is authorized here —
-its flow is a follow-up contract); §5.2's mutation
-enumeration gains the visibility change; §5.5 defines who may change
-visibility (platform admins, plus a company-CRUD capability whose
-definition is a follow-up amendment to contract 2 — until it ratifies,
-admin-only); §6.1 and §6.9 add the witnesses; §6.7's existence-oracle
-rule is scoped around the ratified directory carve-out. Top-level
-creation (contract 3 §5.2) is unchanged and always yields a private
-company. Upstream, SOT Amendment A2 (native-kanban-sot.md §9, this PR)
-expressly extends A1 §8.1.2 to admit the visibility column and A1
-§8.1.3 to admit the directory function — this contract relies on that
-amendment, not on a reinterpretation of A1.
-
 Scope: the tenancy/authorization structure record class — companies,
 estates, platform-projects, workspaces, hierarchy grants, their parentage,
 and constraints. Out of scope: the RBAC grant vocabulary and evaluation
@@ -105,13 +86,8 @@ legacy flat data (future work; see §1.3).
    AND `hierarchy_grants` (§3) — A1 includes hierarchy-level access grants
    in the class. Every rule addressed to "the class" in this contract
    (payload prohibition, mutation path, audit) binds all five tables. Class
-   rows carry parentage, naming, grant, audit-linkage, and visibility-class
-   data only — never task, plan, or any business/orchestration payload.
-   Visibility (`companies.visibility`, §2.8) is admitted into that
-   enumeration by SOT Amendment A2 §9.1.1, which expressly extends A1
-   §8.1.2 for exactly this one column: it is disclosure data about the
-   class's own nodes — not a payload field, carries no business content,
-   and widens the payload prohibition for nothing else.
+   rows carry parentage, naming, grant, and audit-linkage data only — never
+   task, plan, or any business/orchestration payload.
    References from business/orchestration rows into the class are limited
    to exactly one form: the canonical `workspace_id` tenancy column that
    REQ-TEN-001 requires on every canonical row, referencing
@@ -140,9 +116,7 @@ MUST NOT merge the two. (A rename of either remains an implementation-PR
 decision under A1; this contract pins only that they stay distinct tables.)
 
 1. `companies` — id (uuid pk), name, slug (unique per deployment),
-   `visibility` (text NOT NULL, DEFAULT `private`, CHECK constrained to
-   exactly `private` | `directory`; semantics §2.8), created_at,
-   updated_at. N per deployment (D2).
+   created_at, updated_at. N per deployment (D2).
 2. `estates` — id, name, slug, `company_id` NOT NULL →
    `companies.id` ON DELETE RESTRICT. Exactly one company per estate; a
    company holds any number of estates.
@@ -168,31 +142,6 @@ decision under A1; this contract pins only that they stay distinct tables.)
    free-form payload field. The columns declared in this section and §3
    are exhaustive: a class table's column set is exactly its declared set
    (verified per §6.2) — nothing else (A1 §8.1.2).
-8. **Company visibility classes (Ruling 4b).** Every company is exactly
-   one of two classes, carried by `visibility`:
-   - `private` (the default): the company is disclosed only to subjects
-     holding a grant on it or on a descendant — the resting state every
-     company is created in. Open creation under contract 3 §5.2
-     (Ruling 4) survives unchanged: it creates private companies.
-   - `directory`: the company is listed in the deployment-wide company
-     directory. Directory listing discloses **existence, name, and slug
-     to every authenticated user — nothing else**: no subtree structure,
-     no roll-up aggregates, no workspace content, no grant or membership
-     information.
-     Visibility is disclosure, not authority. Content and structure access
-     to a directory-listed company still require explicit grants —
-     contract 2 §3.1 deny-by-default is unchanged, and the ownership model
-     (§4.4, contract 2 §4.3) is unchanged. Ruling 4b decision 5 wants a
-     see-and-ask-to-join flow for directory-listed companies. **This
-     contract authorizes no join-request runtime surface**: the flow in
-     its entirety — the ability to submit a request, its transport,
-     storage, and request lifecycle — is a follow-up contract, and until
-     that contract ratifies, the directory's only function is the
-     read-only listing above (A2 §9.1.2 admits nothing more). Two
-     invariants pre-bind that future contract now:
-     a join request confers no authority of any kind, and approval is
-     ordinary grant creation by an effective `owner` under contract 2 §4.1
-     — there is no other acceptance path.
 
 ## 3. Grant attachment points
 
@@ -274,8 +223,7 @@ shape contract 2 attaches to:
 2. **Audit parity.** A1 §8.2 leaves every pre-existing REQ binding, so
    hierarchy mutations get REQ-AUD-001's guarantees, not a weakened
    substitute. Concretely:
-   - Every create, rename, transfer, visibility change (§5.5), grant
-     create/change/revoke, and
+   - Every create, rename, transfer, grant create/change/revoke, and
      delete — including every grant deletion cascaded by a node delete —
      emits a semantic audit event carrying actor, verb, target, and (for
      transfers) source and destination parents, with the correlation,
@@ -300,25 +248,6 @@ shape contract 2 attaches to:
    workspace work. Contract 8 owns projection details but cannot narrow
    this rule. This contract additionally guarantees the chain roll-ups
    aggregate over is unique and non-null (§2.5).
-5. **Visibility administration (Ruling 4b decisions 2–3).** Changing
-   `companies.visibility` is a hierarchy mutation through the §5.1
-   command path, audited per §5.2 (the event carries the old and new
-   visibility values as its semantic content). It is authorized for
-   exactly two actor classes: platform admins (`users.role = 'admin'`)
-   and subjects holding the company-CRUD capability that a follow-up
-   amendment to contract 2 will define — until that amendment ratifies,
-   the capability class is empty and the command is admin-only.
-   A company `owner` as such may NOT change visibility: standard users
-   cannot publish a company into the directory. This is the one
-   hierarchy mutation a platform admin performs without holding a
-   hierarchy grant, and it is ratified here as instance administration
-   (directory curation) in contract 2 §1.1's sense, not tenant access:
-   the command mutates the single `visibility` column, reads no tenant
-   content, and confers no grant — contract 2 §1.1's
-   no-implicit-tenant-access rule is otherwise untouched. Top-level
-   company creation (contract 3 §5.2) always creates
-   `visibility = 'private'`; the creation command cannot set or change
-   visibility.
 
 ## 6. Verification requirements
 
@@ -335,10 +264,7 @@ Binding on the implementing PRs (extends A1 §8.3):
    witnessed (zero and two set → refused). Grant uniqueness: a duplicate
    (subject, target, role) row refused for each of the six subject×target
    forms, proving NULLS-NOT-DISTINCT semantics; NOT NULL on `role`,
-   `granted_by`, and all `name`/`slug` columns witnessed. Company
-   visibility (§2.8): a value outside `private`/`directory` refused with
-   both valid values accepted as the control; an insert omitting the
-   column defaults to `private`.
+   `granted_by`, and all `name`/`slug` columns witnessed.
 2. Column allowlist: an information_schema assertion that each class
    table's column set is exactly the set declared in §2/§3 — the bounded
    observable for no-payload (§2.7) and no-`owner_id` (§4.4).
@@ -420,19 +346,9 @@ Binding on the implementing PRs (extends A1 §8.3):
    static analysis cannot see, and any such evasion found later is
    corrected as a conformance defect, not grandfathered.
 4. Audit witnesses: for each mutation class (create, rename, transfer,
-   visibility change, grant create/change/revoke, delete) — the event
-   exists after commit
-   with actor/verb/target and same-transaction atomicity, and the
-   event's outbox record exists after the same commit — state row,
-   audit event, and outbox record are witnessed as one transaction
-   (REQ-AUD-001); a rolled-back
-   mutation leaves no event, no outbox record, AND no state effect —
-   a rolled-back create leaves no row, a rolled-back rename, transfer,
-   or visibility change leaves the prior values in place, and a
-   rolled-back delete or grant revoke leaves the row present
-   (rollback witness on all three legs, per REQ-AUD-001's
-   commit-or-roll-back-together acceptance); a
-   node delete's cascaded
+   grant create/change/revoke, delete) — the event exists after commit
+   with actor/verb/target and same-transaction atomicity; a rolled-back
+   mutation leaves no event (rollback witness); a node delete's cascaded
    grant deletions are each covered by events; events survive deletion of
    their target (query the events of a deleted node).
 5. Transfer tests: parent-FK update moves the subtree resolution and
@@ -452,30 +368,10 @@ Binding on the implementing PRs (extends A1 §8.3):
    endpoints mutate no canonical state anywhere (assert zero writes across
    hierarchy AND workspace tables, not hierarchy only); readers see
    aggregates only over workspaces they are authorized on, with no
-   cross-tenant existence oracles (A1 §8.3 acceptance 3, as narrowed by
-   A2 §9.1.2) beyond the one
-   ratified carve-out — the §2.8 company directory, witnessed in §6.9.
+   cross-tenant existence oracles (A1 §8.3 acceptance 3).
 8. Real-PostgreSQL coverage for every constraint witness (unique/CHECK/
    RESTRICT/NULLS NOT DISTINCT behavior), using the `ci-postgres` service
    in the `test` CI step; mocked specs cannot witness database constraints.
-9. Visibility witnesses (§2.8, §5.5): the directory read returns exactly
-   the `visibility = 'directory'` companies to any authenticated user,
-   disclosing existence, name, and slug only (closed-field assertion on
-   the response shape); a private company never appears in the directory
-   for a reader without a grant on it (with the control: it appears in
-   that reader's granted-structure reads); a directory-listed company's
-   subtree, aggregates, and content remain refused for a non-granted
-   reader (disclosure ≠ authority); the visibility command is refused
-   for a non-admin actor — including an effective `owner` of the target
-   company — with the platform-admin accept control; top-level creation
-   yields `visibility = 'private'` and accepts no visibility argument;
-   each visibility change emits its §5.2 audit event carrying old and
-   new values — the full audit pattern for the mutation class
-   (same-transaction atomicity of state row, audit event, and outbox
-   record; rollback leaving no state effect, no event, and no outbox
-   record; actor/verb/target) is §6.4's, which enumerates
-   visibility change; this item adds only the old/new-value payload
-   assertion.
 
 ## Ruling request
 

docs/requirements/native-kanban-sot.md

@@ -456,61 +456,3 @@ this line is weakened.
 - Negative tests prove roll-up endpoints cannot mutate state and that a
   reader sees aggregates only over workspaces they are authorized on
   (no cross-tenant existence oracles).
-
-## 9. Amendment A2 — company visibility classes and the company directory
-
-**Status:** amendment to Amendment A1, added by reviewed PR under Ruling 4b
-(operator ruling, 2026-08-27; decision owner Jason; recorded in the webui-audit
-lane RULINGS.md). Everything in §§1–8 remains binding verbatim, with exactly
-the two express modifications below. Nothing else is weakened. The detailed
-contract text lives in the hierarchy schema contract
-(`hierarchy-schema.md` §2.8, §5.5, §6.9); this amendment changes only what A1
-itself permits, so that contract does not stretch A1 by interpretation.
-
-### 9.1 What A2 modifies in A1
-
-1. **Class data (extends §8.1.2's first constraint).** The tenancy/authorization
-   structure record class additionally carries **visibility-class data**: the
-   single column `companies.visibility`, values `private` | `directory`
-   (hierarchy schema §2.8). Visibility is disclosure data about the class's own
-   nodes — what a company row reveals about its own existence — and is part of
-   the class's tenancy/authorization purpose. It is not business or
-   orchestration payload. §8.1.2's payload prohibition is widened for nothing
-   else: hierarchy tables still MUST NOT carry task, plan, or any other
-   business/orchestration payload, and this amendment admits exactly this one
-   column.
-2. **The company directory (extends §8.1.3's function enumeration).** The
-   hierarchy serves one additional, express, narrow runtime function: the
-   **company directory** — a read-only disclosure listing of exactly the
-   companies whose `visibility = 'directory'`, revealing existence, name, and
-   slug to every authenticated user of the deployment and nothing else. It
-   mutates nothing, confers no authority, evaluates no grant down the chain,
-   and aggregates nothing (it is not a roll-up). §8.3's
-   no-cross-tenant-existence-oracle acceptance is narrowed by exactly this one
-   ratified carve-out: the directory is the sole permitted existence
-   disclosure, and it discloses only directory-class companies (witnessed in
-   hierarchy schema §6.7 and §6.9). Private companies remain undisclosed to
-   non-granted subjects everywhere, including the directory.
-
-### 9.2 What A2 explicitly does not change
-
-1. Content access stays grant-only under the RBAC grant model contract:
-   directory listing discloses existence, never content, membership, or any
-   authority (Ruling 3 unchanged; hierarchy schema §2.8).
-2. **No join-request surface is authorized.** Ruling 4b decision 5's
-   see-and-ask-to-join flow is a follow-up contract in its entirety —
-   including the ability to submit a request. A2 admits exactly the
-   read-only listing of §9.1.2 and nothing more; hierarchy schema §2.8
-   states the invariants that pre-bind the future flow contract, and that
-   contract must itself amend this enumeration before any join-request
-   runtime surface exists.
-3. Visibility changes are hierarchy mutations on the existing §8.2.3 audited
-   mutation path — audited maintenance of the class's own structure in
-   §8.1.3's sense, not a further runtime function. Authorization for them is
-   defined in hierarchy schema §5.5 (platform admins plus the future
-   company-CRUD capability; owner-as-such cannot publish).
-4. Company creation is unchanged and always yields `visibility = 'private'`
-   (onboarding wizard §5.2); this amendment adds no creation path and no
-   default-open disclosure.
-5. Every other constraint of A1 — §8.1.2's remaining bullets, §8.2 in full,
-   and §8.3's other acceptance criteria — is untouched.

docs/requirements/onboarding-wizard.md

@@ -397,14 +397,6 @@ seed-workspace-scoped mutant, correctly refusing outside the seed
 set, passes branch (c), so the two branches detect distinct
 mutants. No other change.
 
-Amendment 1 (Ruling 4b, 2026-08-28): §5.2's embedded decision was RULED
-AGREED (Jason, 2026-08-27), and Ruling 4b adds company visibility
-classes (hierarchy schema §2.8): open top-level creation always yields
-a **private** company; publishing a company into the deployment-wide
-directory is a separate, gated visibility mutation (hierarchy schema
-§5.5) that is never part of the creation command. §5.2 is amended to
-state both.
-
 Scope: the Gateway-backed product onboarding wizard. Out of scope: the
 host-local install wizard (`mosaic wizard`, which drives host install and
 gateway bootstrap and is not this artifact — audit REPORT.md layer 3);
@@ -1177,18 +1169,15 @@ collects no sensitive category, so v1 ships no custody surface.
    party, service actor, or wizard-privileged writer exists in this
    flow.
 2. **Post-bootstrap top-level company creation** — the "N companies" flow
-   — RULED AGREED (Jason, 2026-08-27): any **eligible platform user** MAY
+   — is decided by the ruling below: any **eligible platform user** MAY
    create a top-level company and MUST name an initial `owner` grant in
    the same audited operation (contract 2 §4.3); the creator naming
    themselves is the default. Eligible means, in identity-contract
    terms: an authenticated account (identity §2) that is not banned
    (identity §7.1 — deactivation on this platform IS the better-auth
    ban; no separate deactivated state exists). No further role or grant
-   is required. Creation always yields a **private** company
-   (`visibility = 'private'`, hierarchy schema §2.8, Ruling 4b): the
-   creation command accepts no visibility argument, and publishing into
-   the deployment-wide directory is a separate, gated mutation
-   (hierarchy schema §5.5) that standard users cannot perform.
+   is required. Until that ruling, deny-by-default holds (contract 2
+   §3.1): no implicit creation authority exists.
 3. Child-node creation inside the wizard (estate, project, workspace
    under the seeded company) follows contract 2 §4.3: parent
    `owner` authority, no automatic grant needed — for canonical seed
@@ -1943,13 +1932,7 @@ contracts and are not additions:
     suffix at all — each contradicting PRD D4's no-lock-in
     requirement (§4.4).
 
-## Ruling request — RULED AGREED (Jason, 2026-08-27; Amendment 1)
-
-The §5.2 decision below was ruled agreed: open eligible-user creation
-stands (yielding private companies per Amendment 1), and the
-"alternative if rejected" did not take effect. The request is retained
-below as historical record of what was put to ruling; it is no longer
-live.
+## Ruling request
 
 Ratify sections 1–7 as written, with one decision embedded:
 

docs/requirements/rbac-grant-model.md

@@ -1,259 +0,0 @@
-# RBAC Grant Model Contract
-
-Status: DRAFT — awaiting ratification (webui-audit S2, contract 2 of 9).
-Authority: PRD Part I §4 ("Granular RBAC: admins restrict access per company,
-estate, and project; grants are evaluated down the chain") and the
-native-kanban SOT Amendment A1 (§8.1.3 RBAC evaluation, §8.3 acceptance 2).
-This document defines the grant vocabulary, evaluation semantics, and
-revocation propagation that the hierarchy schema contract
-(`docs/requirements/hierarchy-schema.md`, contract 1) attaches to. Contract 1
-pins the `hierarchy_grants` table shape and defers the `role` vocabulary and
-the meaning of "authority" here; the identity contract
-(`docs/requirements/identity-lifecycle.md` §1.4) pins that account creation
-grants nothing.
-
-Revision 2 (independent review, GLM 5.3): §1.1 consequence analysis
-completed — the two existing platform-admin bypass code paths are named as
-non-conformant and §7.4 retires them; team grant subjects suspended pending
-a team contract (§1.4, §3.3–3.4, §7.5); no-self-escalation restated with
-its true rationale and a constructible observable (§4.2, §7.7);
-node-creation seeding scoped to the bootstrap path, resolving the §7.7/§4.3
-contradiction; A1 quotation corrected; audit-field provenance corrected;
-principal-position consequence named (§1.3); membership-row,
-fail-closed-fault, and existence-oracle observables added (§7);
-role-string namespacing rule added (§4.5); ruling request now names the
-interpretive resolution of PRD "admins".
-
-Scope: the roles that can appear in `hierarchy_grants.role`, what a grant at
-each hierarchy level confers, how grants evaluate down the chain, how
-revocation propagates, and who may manage grants. Out of scope: the hierarchy
-tables themselves (contract 1), workspace-internal membership and its
-role/capability vocabulary (native-kanban SOT REQ-ID-001 and its implementing
-schema), roll-up projection semantics (contract 8), wizard seeding
-(contract 3), the team model (suspended here; see §1.4).
-
-## 1. Three authority layers, none substitutable
-
-1. **Platform role** (`users.role`, better-auth: `member` | `admin`) governs
-   instance administration — user management, system settings, provider
-   configuration. It is not tenancy authority: holding platform `admin`
-   confers **no implicit hierarchy grant and no workspace authorization**.
-   An operator who should see tenant content holds an explicit, audited
-   grant like anyone else. This is the deny-by-default consequence of A1
-   §8.1.3 ("not a bypass of workspace authorization"). `AdminGuard`'s
-   `role === 'admin'` check on admin endpoints stays the platform role's
-   only meaning. **Two shipped code paths violate this rule today and are
-   implementation defects this contract makes non-conformant:** (a) the
-   command authorization service short-circuits every command scope to
-   allowed for platform admins
-   (`apps/gateway/src/commands/command-authorization.service.ts`,
-   `hasScope` returning true when `role === 'admin'`), and (b) the MCP
-   scope derivation maps platform `admin` to tenant-admin MCP scopes
-   including task create/update
-   (`apps/gateway/src/mcp/mcp.service.ts`,
-   `deriveMcpToolScopesForUser`). Ratifying this contract revokes both;
-   §7.4 names them as the surfaces the deny-by-default test retires.
-2. **Hierarchy grants** (`hierarchy_grants`, contract 1 §3) declare tenancy
-   authority at company, estate, or platform-project scope and evaluate down
-   the chain to workspace-scoped authorization (§3 below).
-3. **Workspace membership** (SOT REQ-ID-001) remains its own mechanism.
-   A chain grant confers command authorization over descendant workspaces;
-   it does not create membership rows, and row-level principal positions
-   (task owner, proposer, decision actor) still require ACTIVE workspace
-   membership exactly as REQ-TEN-001/REQ-ID-001 acceptance states.
-   Consequence, stated so implementing PRs do not weaken REQ-TEN-001 to
-   remove the friction: a chain-granted actor who is not a workspace member
-   may issue the write commands their role implies but cannot occupy a
-   principal position — any command taking a principal argument must name
-   an ACTIVE member of the target workspace (§7.2 enumerates this cell).
-4. **Team grant subjects are suspended.** Contract 1 §3.1 reserves a
-   `team_id` attachment point, but no ratified contract yet defines the
-   team it would bind: the only existing `teams` table is the legacy global
-   Brain table (own authority columns, no workspace binding, not
-   repurposed per contract 1 §1.3), while the SOT's teams are
-   workspace-bound (REQ-ID-001) — and a workspace-bound team holding a
-   company-level grant would be a cross-workspace authority group nothing
-   has ratified. Until a team contract defines the subject (which table,
-   which membership rows, and its relation to D2/REQ-ID-001), creating a
-   grant with a team subject MUST be refused at the command surface (the
-   schema column remains, per contract 1). §3's evaluation semantics for
-   team-conferred grants are specified now so the team contract activates
-   them without amending this one.
-
-## 2. Role vocabulary
-
-One vocabulary at every hierarchy level, totally ordered — a higher role
-includes everything below it:
-
-1. `viewer` — read: sees the node, its subtree structure, and the roll-up
-   aggregates over descendant workspaces (within contract 8's carve-out
-   bounds); read access to descendant workspace content per the SOT's read
-   command families. No mutation of anything.
-2. `member` — work: everything `viewer` has, plus write authorization for
-   business/orchestration command families in descendant workspaces (the
-   concrete command-family mapping is implementation work under SOT
-   REQ-ID-001; this contract pins that `member` maps to the workspace write
-   families and nothing structural).
-3. `owner` — structure: everything `member` has, plus hierarchy mutations on
-   the subtree (create/rename/delete child nodes, transfers per §5), and
-   grant management on the node and its subtree (§4).
-
-No other value is valid in `hierarchy_grants.role`; the column is
-constraint-checked against exactly these three. Extending the vocabulary is a
-contract amendment, not an implementation decision.
-
-## 3. Evaluation semantics
-
-1. **Deny by default.** No grant on any ancestor → no authority. There are
-   no implicit grants: not from platform role (§1.1), not from creating a
-   node (§4.3), not from workspace membership (membership without a chain
-   grant confers exactly what the SOT's own membership rules confer inside
-   that workspace, nothing up the chain).
-2. **Down-the-chain only.** A grant on a node applies to that node and its
-   entire descendant subtree. Nothing evaluates upward or sideways: a grant
-   on an estate says nothing about the parent company or sibling estates.
-3. **Effective role = maximum.** A subject's effective role at any node is
-   the highest role among grants held directly by the subject's user on
-   that node or any ancestor — and, once the team contract activates team
-   subjects (§1.4), grants held by any team the user is a member of on that
-   node or any ancestor. Roles never subtract — there is no negative/deny
-   grant in this model; revocation is deletion (§6).
-4. **Team grants follow live membership** (specified now, active only per
-   §1.4). A team grant confers its role on the team's current members,
-   evaluated at decision time. Leaving the team is loss of the grant with
-   §6's propagation bound.
-5. **Live evaluation, fail closed.** Authorization decisions derive from the
-   live grant and team-membership rows (or from a cache that is invalidated
-   in the same transaction as any grant/membership/hierarchy mutation). A
-   decision path that cannot read grant state denies. No materialized ACL is
-   ever authoritative.
-6. **Tenant context stays derived from authenticated authority**
-   (REQ-TEN-001). The chain adds where grants can be declared; a workspace
-   request is still authorized against that workspace, with the chain
-   contributing the effective role — never letting the chain become what A1
-   §8.1.3 forbids: "a bypass of workspace authorization".
-
-## 4. Grant management
-
-1. Creating, changing, or revoking a grant on a node requires effective
-   `owner` on that node (directly or via any ancestor).
-2. **No self-escalation.** A grant manager cannot create a grant with a role
-   higher than their own effective role on the target node. Under the §2
-   vocabulary this rule is currently implied by §4.1 (managers are `owner`,
-   the top role — no constructible grant exceeds it); it is stated
-   explicitly so it survives any future amendment that decouples
-   grant-management authority from role height. Its observable is the §7.7
-   audit invariant, not a refusal test.
-3. **Bootstrap of authority is explicit; inheritance covers the rest.**
-   Creating the first company (the wizard path, contract 3) and any
-   top-level company creation MUST name the initial `owner` grant in the
-   same audited operation — a top-level node has no ancestor to inherit
-   from, so without this the node would be unownable. Creating a child node
-   (estate, platform-project, workspace) requires effective `owner` on the
-   parent (§2.3) and confers no automatic grant; the creator's authority
-   over the new node already follows from §3.2 down-the-chain evaluation.
-   The creating command MAY additionally name an explicit initial grant for
-   a child node; it is not required to.
-4. Every grant mutation is a semantic audit event under contract 1 §5.2's
-   guarantees, extended by this contract with two further fields: the event
-   carries actor, verb, target, **subject, and role** (subject and role are
-   this contract's addition; contract 1 §5.2 does not enumerate them).
-5. **Role strings are namespaced.** `viewer`/`member` exist at hierarchy
-   level, `member`/`admin` on `users.role`, and the current command layer
-   uses a third `viewer|member|admin` vocabulary — same strings, different
-   meanings. Any serialized role string (audit events per §4.4, API
-   responses, logs) MUST identify its layer (e.g. `hierarchy:owner`,
-   `platform:admin`); a bare role string in a serialized artifact is
-   non-conformant.
-
-## 5. Transfer authority (completes contract 1 §4.2)
-
-"Authority over BOTH the source and the destination parent" means: effective
-`owner` on the current parent node (or an ancestor) AND effective `owner` on
-the destination parent node (or an ancestor), evaluated at transfer time in
-the transfer's own transaction. One subject must hold both; two cooperating
-half-authorized subjects are not a transfer protocol this contract defines.
-
-## 6. Revocation propagation
-
-1. Revoking a grant (deleting the row), removing a user from a team that
-   carries a grant (once team subjects activate, §1.4), or the cascade
-   deletion of a node's grants during node deletion (contract 1 §3.3) all
-   propagate identically: the authority derived from that grant is gone for
-   every descendant workspace.
-2. **Bound:** the next authorization decision on any affected transport
-   decides against the revoked grant. Concretely: no new HTTP/MCP command
-   authorized by the revoked grant after the revoking transaction commits;
-   an open Socket.IO connection whose subscriptions depend on the revoked
-   grant is re-evaluated within 30 seconds or at its next inbound message,
-   whichever comes first (same bound as the identity contract's §7.1
-   deactivation rule; same mechanism may serve both).
-3. Revocation is subtractive only in effect, not in representation: the
-   evaluator never needs tombstones; deletion of the row is the revocation.
-
-## 7. Verification requirements
-
-Binding on the implementing PRs (extends A1 §8.3 acceptance 2–3 and
-contract 1 §6):
-
-1. Vocabulary: the role CHECK constraint rejects any value outside
-   `viewer|member|owner` (real-PostgreSQL witness, `ci-postgres` service in
-   the `test` CI step).
-2. Per-level conferral: for each of the three levels × three roles, a grant
-   yields exactly the implied workspace authorization in a descendant
-   workspace and nothing in a non-descendant workspace (the A1 §8.3
-   "exactly the permissions the chain implies" matrix, enumerated). The
-   matrix includes: a chain grant creates zero workspace-membership rows
-   (assert row counts); a chain-granted non-member is refused as the
-   principal argument of any principal-taking command while their
-   non-principal writes succeed (§1.3); structure reads leak no existence
-   of nodes the reader holds no grant on (no cross-tenant existence
-   oracle, A1 §8.3 acceptance 3).
-3. Ordering: `owner` ⊇ `member` ⊇ `viewer` behaviorally — each higher role
-   passes every lower role's positive cases.
-4. Deny-by-default: platform `admin` with no grant reaches no tenant
-   content — asserted against the two §1.1 non-conformant surfaces after
-   their retirement: the command-authorization admin short-circuit and the
-   MCP tenant-admin scope derivation both gone (a platform admin with no
-   grant is refused workspace commands and receives no tenant MCP scopes);
-   workspace member with no chain grant gains nothing outside SOT
-   membership semantics; fresh account reaches nothing (identity contract
-   §1.4 cross-check).
-5. Team subjects: while suspended (§1.4), creating a team-subject grant is
-   refused at the command surface. On activation by the team contract:
-   user-direct and team-conferred grants combine to the maximum; team-leave
-   drops authority within the §6.2 bound; decision-time evaluation
-   witnessed (grant added → next decision allows; no restart or re-login
-   required).
-6. Revocation: each revocation path in §6.1 denies the next command on
-   every transport; the socket bound is measured; a cached-authorization
-   implementation proves transactional invalidation (grant revoked and
-   decision made on two distinct physical connections). Fail-closed fault
-   witness for §3.5: with grant state unreadable (fault injection), the
-   decision denies.
-7. Grant management: non-`owner` cannot mutate grants; top-level company
-   creation without the named initial `owner` grant is refused, while child
-   node creation under ancestor authority succeeds without one (§4.3 both
-   directions); every mutation produces its audit event with the §4.4
-   fields. Self-escalation observable: over the audit event stream, every
-   grant-create/change event's role is ≤ the acting user's effective role
-   on the target at event time (reconstructable invariant, not a refusal
-   test — see §4.2).
-8. Transfer: both-sides `owner` accepted, each single-side case refused
-   (completing contract 1 §6.5).
-
-## Ruling request
-
-Ratify sections 1–7 as written, with one decision embedded and one
-interpretive resolution named:
-
-- Decision: platform `admin` confers no implicit tenant access — operators
-  see tenant content only through explicit, audited grants (§1.1), which
-  retires the two existing admin bypass paths named there. Say "agreed" or
-  name the implicit access you want platform admins to keep.
-- Interpretive resolution (for visibility, not a separate question): PRD
-  Part I §4 says "admins restrict access per company, estate, and project";
-  this contract resolves "admins" as hierarchy `owner`s (§4.1), not
-  platform admins. A1 §8.1.3 does not attribute grant declaration to
-  platform admins, and the §1.1 decision above is what makes this reading
-  binding.

packages/mosaic/framework/tools/git/issue-assign.sh

@@ -3,7 +3,6 @@
 # Usage: issue-assign.sh -i ISSUE_NUMBER [-a assignee] [-l labels] [-m milestone]
 
 set -e
-set -o pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
@@ -34,36 +33,25 @@ Examples:
     $(basename "$0") -i 42 -l "in-progress" -m "0.2.0"
     $(basename "$0") -i 42 -a @me
 EOF
-    exit "${1:-2}"
-}
-
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    usage >&2
+    exit "${1:-1}"
 }
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
     case $1 in
         -i|--issue)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE="$2"
             shift 2
             ;;
         -a|--assignee)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ASSIGNEE="$2"
             shift 2
             ;;
         -l|--labels)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
@@ -91,35 +79,20 @@ PLATFORM=$(detect_platform)
 case "$PLATFORM" in
     github)
         if [[ -n "$ASSIGNEE" ]]; then
-            prov_rc=0
-            gh issue edit "$ISSUE" --add-assignee "$ASSIGNEE" || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            gh issue edit "$ISSUE" --add-assignee "$ASSIGNEE"
         fi
         if [[ "$REMOVE_ASSIGNEE" == true ]]; then
             # Get current assignees and remove them
-            # pipefail preserves the provider status through the pipeline;
-            # a FAILED lookup exits here instead of reading as a silent
-            # no-assignees skip (codex PR #1464). A successful lookup with
-            # zero assignees still skips the edit below.
-            CURRENT=$(gh issue view "$ISSUE" --json assignees -q '.assignees[].login' 2>/dev/null | tr '\n' ',') || {
-                echo "Error: could not read current assignees (provider lookup failed)" >&2
-                exit 1
-            }
+            CURRENT=$(gh issue view "$ISSUE" --json assignees -q '.assignees[].login' 2>/dev/null | tr '\n' ',')
             if [[ -n "$CURRENT" ]]; then
-                prov_rc=0
-                gh issue edit "$ISSUE" --remove-assignee "${CURRENT%,}" || prov_rc=$?
-                [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+                gh issue edit "$ISSUE" --remove-assignee "${CURRENT%,}"
             fi
         fi
         if [[ -n "$LABELS" ]]; then
-            prov_rc=0
-            gh issue edit "$ISSUE" --add-label "$LABELS" || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            gh issue edit "$ISSUE" --add-label "$LABELS"
         fi
         if [[ -n "$MILESTONE" ]]; then
-            prov_rc=0
-            gh issue edit "$ISSUE" --milestone "$MILESTONE" || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            gh issue edit "$ISSUE" --milestone "$MILESTONE"
         fi
         echo "Issue #$ISSUE updated successfully"
         ;;
@@ -158,9 +131,7 @@ case "$PLATFORM" in
         fi
 
         if [[ "$NEEDS_EDIT" == true ]]; then
-            prov_rc=0
-            "${CMD[@]}" || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            "${CMD[@]}"
             echo "Issue #$ISSUE updated successfully"
         else
             echo "No changes specified"

packages/mosaic/framework/tools/git/issue-close.sh

@@ -1,7 +1,6 @@
 #!/bin/bash
 # issue-close.sh - Close an issue on GitHub or Gitea
-# Usage: issue-close.sh -i <issue_number> [-b <comment>]
-# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
+# Usage: issue-close.sh -i <issue_number> [-c <comment>]
 
 set -e
 
@@ -13,49 +12,35 @@ source "$SCRIPT_DIR/detect-platform.sh"
 ISSUE_NUMBER=""
 COMMENT=""
 
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1), so a
-# caller or stop gate can tell an invocation defect from a delivery blocker.
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: issue-close.sh -i <issue_number> [-b <comment>] (see --help)" >&2
-    exit 2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -i|--issue)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
-        -b|--body|-c|--comment)
-            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
-            # a backward-compatible alias.
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
+        -c|--comment)
             COMMENT="$2"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: issue-close.sh -i <issue_number> [-b <comment>]"
+            echo "Usage: issue-close.sh -i <issue_number> [-c <comment>]"
             echo ""
             echo "Options:"
             echo "  -i, --issue    Issue number (required)"
-            echo "  -b, --body     Comment to add before closing (optional; canonical)"
-            echo "  -c, --comment  Alias for --body"
+            echo "  -c, --comment  Comment to add before closing (optional)"
             echo "  -h, --help     Show this help"
-            echo ""
-            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    usage_error "issue number is required (-i/--issue)"
+    echo "Error: Issue number is required (-i)"
+    exit 1
 fi
 
 # Detect platform and close issue
@@ -97,22 +82,10 @@ gitea_issue_close_api() {
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
-    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
-    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh_rc=0
-        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
-        if [[ "$gh_rc" -ne 0 ]]; then
-            echo "Error: GitHub comment before close failed (gh exit $gh_rc)" >&2
-            exit 1
-        fi
-    fi
-    gh_rc=0
-    gh issue close "$ISSUE_NUMBER" || gh_rc=$?
-    if [[ "$gh_rc" -ne 0 ]]; then
-        echo "Error: GitHub issue close failed (gh exit $gh_rc)" >&2
-        exit 1
+        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
     fi
+    gh issue close "$ISSUE_NUMBER"
     echo "Closed GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     GITEA_LOGIN_NAME=$(get_gitea_login || true)
@@ -134,9 +107,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 exit 1
             }
         fi
-        prov_rc=0
-        tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME" || prov_rc=$?
-        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+        tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME"
     else
         echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
         if [[ -n "$COMMENT" ]]; then

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -1,7 +1,6 @@
 #!/bin/bash
 # issue-comment.sh - Add a comment to an issue on GitHub or Gitea
-# Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]
-# (-c/--comment is a backward-compatible alias for -b/--body; R1, 2026-08-28)
+# Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]
 #
 # tea v0.11.1 defines no `comment` subcommand under `tea issue` (or `tea pr`);
 # the non-existent `tea issue comment ...` form does not error — tea silently
@@ -33,61 +32,45 @@ ISSUE_NUMBER=""
 COMMENT=""
 LOGIN_OVERRIDE=""
 
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1), so a
-# caller or stop gate can tell an invocation defect from a delivery blocker
-# (CONSTITUTION gate 8 as amended; E2E-DELIVERY).
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>] (see --help)" >&2
-    exit 2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -i|--issue)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
-        -b|--body|-c|--comment)
-            # R1 (2026-08-28): --body is the canonical flag, matching
-            # issue-create/issue-edit/pr-create/pr-edit; -c/--comment stays a
-            # backward-compatible alias.
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
+        -c|--comment)
             COMMENT="$2"
             shift 2
             ;;
         -l|--login)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LOGIN_OVERRIDE="$2"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]"
+            echo "Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]"
             echo ""
             echo "Options:"
             echo "  -i, --issue    Issue number (required)"
-            echo "  -b, --body     Comment text (required; canonical)"
-            echo "  -c, --comment  Alias for --body"
+            echo "  -c, --comment  Comment text (required)"
             echo "  -l, --login    Override the detected Gitea tea login for this call"
             echo "  -h, --help     Show this help"
-            echo ""
-            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    usage_error "issue number is required (-i/--issue)"
+    echo "Error: Issue number is required (-i)"
+    exit 1
 fi
 
 if [[ -z "$COMMENT" ]]; then
-    usage_error "comment is required (-b/--body, or the -c/--comment alias)"
+    echo "Error: Comment is required (-c)"
+    exit 1
 fi
 
 detect_platform >/dev/null
@@ -357,15 +340,7 @@ PY
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
-    # R4 exit-code contract: normalize provider failures to exit 1. gh's own
-    # usage errors exit 2, which would collide with this wrapper's reserved
-    # usage-error status if propagated raw (codex review of 08a00149).
-    gh_rc=0
-    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
-    if [[ "$gh_rc" -ne 0 ]]; then
-        echo "Error: GitHub comment write failed (gh exit $gh_rc; provider/credential failure — usage errors are exit 2)" >&2
-        exit 1
-    fi
+    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
     echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     # A --login override selects a NAMED tea credential and is the only way to

packages/mosaic/framework/tools/git/issue-create.sh

@@ -74,39 +74,26 @@ Examples:
     $(basename "$0") -t "Fix login bug" -l "bug,priority-high"
     $(basename "$0") -t "Add dark mode" -b "Implement theme switching" -m "0.2.0"
     $(basename "$0") -i
-
-Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure.
 EOF
-    exit "${1:-2}"
+    exit "${1:-1}"
 }
 
 # Parse arguments
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    usage >&2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -t|--title)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
         -b|--body)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             BODY="$2"
             shift 2
             ;;
         -l|--labels)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
@@ -144,9 +131,7 @@ case "$PLATFORM" in
         [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
         [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-        prov_rc=0
-        "${CMD[@]}" || prov_rc=$?
-        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+        "${CMD[@]}"
         ;;
     gitea)
         if command -v tea >/dev/null 2>&1; then

packages/mosaic/framework/tools/git/issue-edit.sh

@@ -14,39 +14,25 @@ BODY=""
 LABELS=""
 MILESTONE=""
 
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1), so a
-# caller or stop gate can tell an invocation defect from a delivery blocker.
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: issue-edit.sh -i <issue_number> [-t <title>] [-b <body>] [-l <labels>] [-m <milestone>] (see --help)" >&2
-    exit 2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -i|--issue)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
         -t|--title)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
         -b|--body)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             BODY="$2"
             shift 2
             ;;
         -l|--labels)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
@@ -60,18 +46,18 @@ while [[ $# -gt 0 ]]; do
             echo "  -l, --labels     Labels (comma-separated, replaces existing)"
             echo "  -m, --milestone  Milestone name"
             echo "  -h, --help       Show this help"
-            echo ""
-            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    usage_error "issue number is required (-i/--issue)"
+    echo "Error: Issue number is required (-i)"
+    exit 1
 fi
 
 detect_platform >/dev/null
@@ -82,9 +68,7 @@ if [[ "$PLATFORM" == "github" ]]; then
     [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
     [[ -n "$LABELS" ]] && CMD+=(--add-label "$LABELS")
     [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-    prov_rc=0
-    "${CMD[@]}" || prov_rc=$?
-    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+    "${CMD[@]}"
     echo "Updated GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_SLUG=$(get_repo_slug) || {
@@ -100,9 +84,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
     [[ -n "$BODY" ]] && CMD+=(--description "$BODY")
     [[ -n "$LABELS" ]] && CMD+=(--add-labels "$LABELS")
     [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-    prov_rc=0
-    "${CMD[@]}" || prov_rc=$?
-    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+    "${CMD[@]}"
     echo "Updated Gitea issue #$ISSUE_NUMBER"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/issue-list.sh

@@ -36,46 +36,33 @@ Examples:
     $(basename "$0") -m "0.2.0"               # Issues in milestone 0.2.0
     $(basename "$0") --repo ddk/ai-bma         # List issues from anywhere
 EOF
-    exit "${1:-2}"
+    exit "${1:-1}"
 }
 
 # Parse arguments
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    usage >&2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -s|--state)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             STATE="$2"
             shift 2
             ;;
         -l|--label)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABEL="$2"
             shift 2
             ;;
         -m|--milestone)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
         -a|--assignee)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ASSIGNEE="$2"
             shift 2
             ;;
         -n|--limit)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LIMIT="$2"
             shift 2
             ;;
         -r|--repo)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
@@ -108,9 +95,7 @@ case "$PLATFORM" in
         [[ -n "$LABEL" ]] && CMD+=(--label "$LABEL")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
         [[ -n "$ASSIGNEE" ]] && CMD+=(--assignee "$ASSIGNEE")
-        prov_rc=0
-        "${CMD[@]}" || prov_rc=$?
-        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+        "${CMD[@]}"
         ;;
     gitea)
         if [[ -n "$REPO_OVERRIDE" ]]; then
@@ -129,9 +114,7 @@ case "$PLATFORM" in
         [[ -n "$MILESTONE" ]] && CMD+=(--milestones "$MILESTONE")
         # Note: tea may not support assignee filter directly in all versions.
         [[ -n "$ASSIGNEE" ]] && echo "Note: Assignee filtering may require manual review for Gitea" >&2
-        prov_rc=0
-        "${CMD[@]}" || prov_rc=$?
-        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+        "${CMD[@]}"
         ;;
     *)
         echo "Error: Could not detect git platform" >&2

packages/mosaic/framework/tools/git/issue-reopen.sh

@@ -1,7 +1,6 @@
 #!/bin/bash
 # issue-reopen.sh - Reopen a closed issue on GitHub or Gitea
-# Usage: issue-reopen.sh -i <issue_number> [-b <comment>]
-# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
+# Usage: issue-reopen.sh -i <issue_number> [-c <comment>]
 
 set -e
 
@@ -12,49 +11,35 @@ source "$SCRIPT_DIR/detect-platform.sh"
 ISSUE_NUMBER=""
 COMMENT=""
 
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1), so a
-# caller or stop gate can tell an invocation defect from a delivery blocker.
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: issue-reopen.sh -i <issue_number> [-b <comment>] (see --help)" >&2
-    exit 2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -i|--issue)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
-        -b|--body|-c|--comment)
-            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
-            # a backward-compatible alias.
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
+        -c|--comment)
             COMMENT="$2"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: issue-reopen.sh -i <issue_number> [-b <comment>]"
+            echo "Usage: issue-reopen.sh -i <issue_number> [-c <comment>]"
             echo ""
             echo "Options:"
             echo "  -i, --issue    Issue number (required)"
-            echo "  -b, --body     Comment to add when reopening (optional; canonical)"
-            echo "  -c, --comment  Alias for --body"
+            echo "  -c, --comment  Comment to add when reopening (optional)"
             echo "  -h, --help     Show this help"
-            echo ""
-            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    usage_error "issue number is required (-i/--issue)"
+    echo "Error: Issue number is required (-i)"
+    exit 1
 fi
 
 detect_platform >/dev/null
@@ -95,34 +80,18 @@ gitea_issue_reopen_api() {
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
-    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
-    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh_rc=0
-        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
-        if [[ "$gh_rc" -ne 0 ]]; then
-            echo "Error: GitHub comment before reopen failed (gh exit $gh_rc)" >&2
-            exit 1
-        fi
-    fi
-    gh_rc=0
-    gh issue reopen "$ISSUE_NUMBER" || gh_rc=$?
-    if [[ "$gh_rc" -ne 0 ]]; then
-        echo "Error: GitHub issue reopen failed (gh exit $gh_rc)" >&2
-        exit 1
+        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
     fi
+    gh issue reopen "$ISSUE_NUMBER"
     echo "Reopened GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args || true)
     if [[ -n "$REPO_ARGS" ]]; then
         if [[ -n "$COMMENT" ]]; then
-            prov_rc=0
-            tea issue comment "$ISSUE_NUMBER" "$COMMENT" $REPO_ARGS || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            tea issue comment "$ISSUE_NUMBER" "$COMMENT" $REPO_ARGS
         fi
-        prov_rc=0
-        tea issue reopen "$ISSUE_NUMBER" $REPO_ARGS || prov_rc=$?
-        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+        tea issue reopen "$ISSUE_NUMBER" $REPO_ARGS
     else
         echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
         if [[ -n "$COMMENT" ]]; then

packages/mosaic/framework/tools/git/issue-view.sh

@@ -8,14 +8,6 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: issue-view.sh -i <issue_number> (see --help)" >&2
-    exit 2
-}
-
 ISSUE_NUMBER=""
 
 # get_remote_host and get_gitea_token are provided by detect-platform.sh
@@ -82,7 +74,6 @@ if comments:
 while [[ $# -gt 0 ]]; do
     case $1 in
         -i|--issue)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
@@ -97,21 +88,21 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    usage_error "Issue number is required"
+    echo "Error: Issue number is required (-i)"
+    exit 1
 fi
 
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    prov_rc=0
-    gh issue view "$ISSUE_NUMBER" || prov_rc=$?
-    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+    gh issue view "$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if command -v tea >/dev/null 2>&1; then
         # --comments is what makes tea print the comment bodies (#1357 F3).

packages/mosaic/framework/tools/git/lane-brief.sh

@@ -28,25 +28,18 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 REPO="" MILESTONE="" LABEL="" LOGIN="" LIMIT=100
-# R2 (2026-08-28): long-flag aliases with the same usage-error contract the
-# wrapper family shares (rc 2, stderr). getopts could not take long flags.
-usage_error() {
-  echo "Error: $*" >&2
-  echo "Usage: lane-brief.sh -r <owner/repo> [-m milestone] [-l label] [-L login] [-n limit]" >&2
-  exit 2
-}
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    -r|--repo) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; REPO="$2"; shift 2 ;;
-    -m|--milestone) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; MILESTONE="$2"; shift 2 ;;
-    -l|--label|--labels) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LABEL="$2"; shift 2 ;;
-    -L|--login) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LOGIN="$2"; shift 2 ;;
-    -n|--limit) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LIMIT="$2"; shift 2 ;;
-    -h|--help) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
-    *) usage_error "unknown option: $1" ;;
+while getopts "r:m:l:L:n:h" opt; do
+  case "$opt" in
+    r) REPO="$OPTARG" ;;
+    m) MILESTONE="$OPTARG" ;;
+    l) LABEL="$OPTARG" ;;
+    L) LOGIN="$OPTARG" ;;
+    n) LIMIT="$OPTARG" ;;
+    h) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) echo "see -h" >&2; exit 2 ;;
   esac
 done
-[[ -n "$REPO" ]] || usage_error "-r/--repo <owner/repo> required"
+[[ -n "$REPO" ]] || { echo "FATAL: -r <owner/repo> required" >&2; exit 2; }
 
 # Resolve login: explicit -L, then $GITEA_LOGIN, then owner inference, then the
 # shared default-login resolver. Owner inference comes before the shared fallback
@@ -79,7 +72,7 @@ if [[ -z "$LOGIN" ]]; then
     fi
   fi
 fi
-[[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 1; }
+[[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 2; }
 
 command -v tea >/dev/null || { echo "FATAL: tea not found" >&2; exit 1; }
 command -v jq  >/dev/null || { echo "FATAL: jq not found" >&2; exit 1; }

packages/mosaic/framework/tools/git/milestone-close.sh

@@ -8,20 +8,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: milestone-close.sh -t <title> (see --help)" >&2
-    exit 2
-}
-
 TITLE=""
 
 while [[ $# -gt 0 ]]; do
     case $1 in
         -t|--title)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
@@ -34,30 +25,28 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$TITLE" ]]; then
-    usage_error "Milestone title is required"
+    echo "Error: Milestone title is required (-t)"
+    exit 1
 fi
 
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    prov_rc=0
-    gh api -X PATCH "/repos/{owner}/{repo}/milestones/$(gh api "/repos/{owner}/{repo}/milestones" --jq ".[] | select(.title==\"$TITLE\") | .number")" -f state=closed || prov_rc=$?
-    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+    gh api -X PATCH "/repos/{owner}/{repo}/milestones/$(gh api "/repos/{owner}/{repo}/milestones" --jq ".[] | select(.title==\"$TITLE\") | .number")" -f state=closed
     echo "Closed GitHub milestone: $TITLE"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args) || {
         echo "Error: Could not resolve Gitea repo/login for remote host" >&2
         exit 1
     }
-    prov_rc=0
-    tea milestone close "$TITLE" $REPO_ARGS || prov_rc=$?
-    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+    tea milestone close "$TITLE" $REPO_ARGS
     echo "Closed Gitea milestone: $TITLE"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/milestone-create.sh

@@ -3,7 +3,6 @@
 # Usage: milestone-create.sh -t "Title" [-d "Description"] [--due "YYYY-MM-DD"]
 
 set -e
-set -o pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
@@ -38,31 +37,21 @@ Examples:
     $(basename "$0") -t "0.0.1" -d "Pre-MVP Foundation Sprint"
     $(basename "$0") -t "0.1.0" -d "MVP Release" --due "2025-03-01"
 EOF
-    exit "${1:-2}"
+    exit "${1:-1}"
 }
 
 # Parse arguments
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    usage >&2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -t|--title)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
         -d|--desc)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             DESCRIPTION="$2"
             shift 2
             ;;
         --due)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             DUE_DATE="$2"
             shift 2
             ;;
@@ -85,18 +74,14 @@ PLATFORM=$(detect_platform)
 if [[ "$LIST_ONLY" == true ]]; then
     case "$PLATFORM" in
         github)
-            prov_rc=0
-            gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number)\t\(.title)\t\(.state)\t\(.open_issues)/\(.closed_issues) issues"' || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number)\t\(.title)\t\(.state)\t\(.open_issues)/\(.closed_issues) issues"'
             ;;
         gitea)
             REPO_ARGS=$(get_gitea_repo_args) || {
                 echo "Error: Could not resolve Gitea repo/login for remote host" >&2
                 exit 1
             }
-            prov_rc=0
-            tea milestones list $REPO_ARGS || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            tea milestones list $REPO_ARGS
             ;;
         *)
             echo "Error: Could not detect git platform" >&2
@@ -107,7 +92,8 @@ if [[ "$LIST_ONLY" == true ]]; then
 fi
 
 if [[ -z "$TITLE" ]]; then
-    usage_error "Title is required (-t) for creating milestones"
+    echo "Error: Title is required (-t) for creating milestones" >&2
+    usage
 fi
 
 case "$PLATFORM" in
@@ -123,9 +109,7 @@ case "$PLATFORM" in
              + (if $d != "" then {"description": $d} else {} end)
              + (if $due != "" then {"due_on": ($due + "T00:00:00Z")} else {} end)')
 
-        prov_rc=0
-        gh api repos/:owner/:repo/milestones --method POST --input - <<< "$JSON_PAYLOAD" || prov_rc=$?
-        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+        gh api repos/:owner/:repo/milestones --method POST --input - <<< "$JSON_PAYLOAD"
         echo "Milestone '$TITLE' created successfully"
         ;;
     gitea)
@@ -136,9 +120,7 @@ case "$PLATFORM" in
         CMD=(tea milestones create --title "$TITLE")
         [[ -n "$DESCRIPTION" ]] && CMD+=(--description "$DESCRIPTION")
         [[ -n "$DUE_DATE" ]] && CMD+=(--deadline "$DUE_DATE")
-        prov_rc=0
-        "${CMD[@]}" $REPO_ARGS || prov_rc=$?
-        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+        "${CMD[@]}" $REPO_ARGS
         echo "Milestone '$TITLE' created successfully"
         ;;
     *)

packages/mosaic/framework/tools/git/milestone-list.sh

@@ -8,20 +8,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: milestone-list.sh [-s <state>] (see --help)" >&2
-    exit 2
-}
-
 STATE="open"
 
 while [[ $# -gt 0 ]]; do
     case $1 in
         -s|--state)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             STATE="$2"
             shift 2
             ;;
@@ -34,7 +25,8 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
@@ -42,17 +34,13 @@ done
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    prov_rc=0
-    gh api "/repos/{owner}/{repo}/milestones?state=$STATE" --jq '.[] | "\(.title) (\(.state)) - \(.open_issues) open, \(.closed_issues) closed"' || prov_rc=$?
-    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+    gh api "/repos/{owner}/{repo}/milestones?state=$STATE" --jq '.[] | "\(.title) (\(.state)) - \(.open_issues) open, \(.closed_issues) closed"'
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args) || {
         echo "Error: Could not resolve Gitea repo/login for remote host" >&2
         exit 1
     }
-    prov_rc=0
-    tea milestone list $REPO_ARGS || prov_rc=$?
-    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+    tea milestone list $REPO_ARGS
 else
     echo "Error: Unknown platform"
     exit 1

packages/mosaic/framework/tools/git/pr-close.sh

@@ -1,7 +1,6 @@
 #!/bin/bash
 # pr-close.sh - Close a pull request without merging on GitHub or Gitea
-# Usage: pr-close.sh -n <pr_number> [-b <comment>]
-# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
+# Usage: pr-close.sh -n <pr_number> [-c <comment>]
 
 set -e
 
@@ -12,80 +11,50 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 COMMENT=""
 
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1), so a
-# caller or stop gate can tell an invocation defect from a delivery blocker.
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: pr-close.sh -n <pr_number> [-b <comment>] (see --help)" >&2
-    exit 2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
-        -b|--body|-c|--comment)
-            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
-            # a backward-compatible alias.
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
+        -c|--comment)
             COMMENT="$2"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: pr-close.sh -n <pr_number> [-b <comment>]"
+            echo "Usage: pr-close.sh -n <pr_number> [-c <comment>]"
             echo ""
             echo "Options:"
             echo "  -n, --number   PR number (required)"
-            echo "  -b, --body     Comment before closing (optional; canonical)"
-            echo "  -c, --comment  Alias for --body"
+            echo "  -c, --comment  Comment before closing (optional)"
             echo "  -h, --help     Show this help"
-            echo ""
-            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    usage_error "PR number is required (-n/--number)"
+    echo "Error: PR number is required (-n)"
+    exit 1
 fi
 
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
-    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh_rc=0
-        gh pr comment "$PR_NUMBER" --body "$COMMENT" || gh_rc=$?
-        if [[ "$gh_rc" -ne 0 ]]; then
-            echo "Error: GitHub PR comment before close failed (gh exit $gh_rc)" >&2
-            exit 1
-        fi
-    fi
-    gh_rc=0
-    gh pr close "$PR_NUMBER" || gh_rc=$?
-    if [[ "$gh_rc" -ne 0 ]]; then
-        echo "Error: GitHub PR close failed (gh exit $gh_rc)" >&2
-        exit 1
+        gh pr comment "$PR_NUMBER" --body "$COMMENT"
     fi
+    gh pr close "$PR_NUMBER"
     echo "Closed GitHub PR #$PR_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if [[ -n "$COMMENT" ]]; then
-        prov_rc=0
-        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args) || prov_rc=$?
-        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args)
     fi
-    prov_rc=0
-    tea pr close "$PR_NUMBER" $(get_gitea_repo_args) || prov_rc=$?
-    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+    tea pr close "$PR_NUMBER" $(get_gitea_repo_args)
     echo "Closed Gitea PR #$PR_NUMBER"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/pr-create.sh

@@ -135,51 +135,37 @@ Examples:
     $(basename "$0") -i 42 -b "Implements the feature described in #42"
     $(basename "$0") -t "WIP: New feature" --draft
 EOF
-    exit "${1:-2}"
-}
-
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    usage >&2
+    exit "${1:-1}"
 }
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
     case $1 in
         -t|--title)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
         -b|--body)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             BODY="$2"
             shift 2
             ;;
         -B|--base)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             BASE_BRANCH="$2"
             shift 2
             ;;
         -H|--head)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             HEAD_BRANCH="$2"
             shift 2
             ;;
         -l|--labels)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
         -i|--issue)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE="$2"
             shift 2
             ;;
@@ -280,9 +266,7 @@ case "$PLATFORM" in
         [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
         [[ "$DRAFT" == true ]] && CMD+=(--draft)
-        prov_rc=0
-        "${CMD[@]}" || prov_rc=$?
-        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+        "${CMD[@]}"
         ;;
     gitea)
         # tea pull create syntax. Always pass --repo because tea repo inference

packages/mosaic/framework/tools/git/pr-edit.sh

@@ -50,45 +50,38 @@ Options:
     -H, --host HOST        Explicit Gitea host (required with --repo off-host)
     -h, --help             Show this help message
 EOF
-    exit "${1:-2}"
-}
-
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    usage >&2
+    exit "${1:-1}"
 }
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        -n|--number) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; PR_NUMBER="${2:-}"; shift 2 ;;
-        -t|--title) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; TITLE="${2:-}"; shift 2 ;;
-        -b|--body) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; BODY="${2:-}"; shift 2 ;;
-        -B|--base) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; BASE_BRANCH="${2:-}"; shift 2 ;;
+        -n|--number) PR_NUMBER="${2:-}"; shift 2 ;;
+        -t|--title) TITLE="${2:-}"; shift 2 ;;
+        -b|--body) BODY="${2:-}"; shift 2 ;;
+        -B|--base) BASE_BRANCH="${2:-}"; shift 2 ;;
         --draft)
-            [[ "$DRAFT_MODE" != "ready" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 2; }
+            [[ "$DRAFT_MODE" != "ready" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 1; }
             DRAFT_MODE="draft"; shift ;;
         --ready)
-            [[ "$DRAFT_MODE" != "draft" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 2; }
+            [[ "$DRAFT_MODE" != "draft" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 1; }
             DRAFT_MODE="ready"; shift ;;
-        -l|--login) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LOGIN_OVERRIDE="${2:-}"; shift 2 ;;
-        -r|--repo) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; REPO_OVERRIDE="${2:-}"; shift 2 ;;
-        -H|--host) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; HOST_OVERRIDE="${2:-}"; shift 2 ;;
+        -l|--login) LOGIN_OVERRIDE="${2:-}"; shift 2 ;;
+        -r|--repo) REPO_OVERRIDE="${2:-}"; shift 2 ;;
+        -H|--host) HOST_OVERRIDE="${2:-}"; shift 2 ;;
         -h|--help) usage 0 ;;
         *) echo "Unknown option: $1" >&2; usage ;;
     esac
 done
 
-[[ -n "$PR_NUMBER" ]] || { echo "Error: Pull request number is required (-n)" >&2; exit 2; }
-[[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "Error: Pull request number must be a positive integer" >&2; exit 2; }
+[[ -n "$PR_NUMBER" ]] || { echo "Error: Pull request number is required (-n)" >&2; exit 1; }
+[[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "Error: Pull request number must be a positive integer" >&2; exit 1; }
 if [[ -z "$TITLE" && -z "$BODY" && -z "$BASE_BRANCH" && -z "$DRAFT_MODE" ]]; then
     echo "Error: At least one edit option is required" >&2
-    exit 2
+    exit 1
 fi
 [[ -z "$REPO_OVERRIDE" || "$REPO_OVERRIDE" =~ ^[^/[:space:]]+/[^/[:space:]]+$ ]] || {
     echo "Error: --repo must be OWNER/REPO" >&2
-    exit 2
+    exit 1
 }
 
 if [[ -n "$HOST_OVERRIDE" || -n "$REPO_OVERRIDE" ]]; then
@@ -99,24 +92,18 @@ fi
 
 case "$PLATFORM" in
     github)
-        [[ -z "$LOGIN_OVERRIDE" ]] || { echo "Error: --login is only valid for Gitea" >&2; exit 2; }
+        [[ -z "$LOGIN_OVERRIDE" ]] || { echo "Error: --login is only valid for Gitea" >&2; exit 1; }
         if [[ -n "$TITLE" || -n "$BODY" || -n "$BASE_BRANCH" ]]; then
             CMD=(gh pr edit "$PR_NUMBER")
             [[ -n "$TITLE" ]] && CMD+=(--title "$TITLE")
             [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
             [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
-            prov_rc=0
-            "${CMD[@]}" || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            "${CMD[@]}"
         fi
         if [[ "$DRAFT_MODE" == "draft" ]]; then
-            prov_rc=0
-            gh pr ready "$PR_NUMBER" --undo || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            gh pr ready "$PR_NUMBER" --undo
         elif [[ "$DRAFT_MODE" == "ready" ]]; then
-            prov_rc=0
-            gh pr ready "$PR_NUMBER" || prov_rc=$?
-            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
+            gh pr ready "$PR_NUMBER"
         fi
         ;;
     gitea)

packages/mosaic/framework/tools/git/pr-review.sh

@@ -43,92 +43,60 @@ LOGIN_OVERRIDE=""
 REPO_OVERRIDE=""
 HOST_OVERRIDE=""
 
-# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1), so a
-# caller or stop gate can tell an invocation defect from a delivery blocker.
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: pr-review.sh -n <pr_number> -a <action> [-b <comment>] (see --help)" >&2
-    exit 2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
         -a|--action)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ACTION="$2"
             shift 2
             ;;
-        -b|--body|-c|--comment)
-            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
-            # a backward-compatible alias.
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
+        -c|--comment)
             COMMENT="$2"
             shift 2
             ;;
         -l|--login)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LOGIN_OVERRIDE="$2"
             shift 2
             ;;
         -r|--repo)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
         -H|--host)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             HOST_OVERRIDE="$2"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-b <comment>] [--login <name>] [-r owner/repo] [-H host]"
+            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>] [-r owner/repo] [-H host]"
             echo ""
             echo "Options:"
             echo "  -n, --number   PR number (required)"
             echo "  -a, --action   Review action: approve, request-changes, comment (required)"
-            echo "  -b, --body     Review comment (required for request-changes; canonical)"
-            echo "  -c, --comment  Alias for --body"
+            echo "  -c, --comment  Review comment (required for request-changes)"
             echo "  -l, --login    Override the detected Gitea tea login (approve/request-changes only)"
             echo "  -r, --repo     Explicit owner/repo slug (skips git-remote slug inference)"
             echo "  -H, --host     Explicit Gitea host (skips remote-host inference)"
             echo "  -h, --help     Show this help"
-            echo ""
-            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    usage_error "PR number is required (-n/--number)"
+    echo "Error: PR number is required (-n)"
+    exit 1
 fi
 
 if [[ -z "$ACTION" ]]; then
-    usage_error "Action is required (-a/--action): approve, request-changes, comment"
-fi
-
-# Validate the action BEFORE any provider contact (codex review of PR #1464:
-# an unsupported --action previously reached platform detection and could
-# touch the provider before failing with a provider-class status).
-case "$ACTION" in
-    approve|request-changes|comment) ;;
-    *) usage_error "unknown action '$ACTION': approve, request-changes, comment" ;;
-esac
-
-# Body-required actions fail fast too (codex follow-up on PR #1464):
-# request-changes and comment both require a body; validate before any
-# provider contact.
-if [[ ( "$ACTION" == "request-changes" || "$ACTION" == "comment" ) && -z "$COMMENT" ]]; then
-    usage_error "comment required for $ACTION (-b/--body)"
+    echo "Error: Action is required (-a): approve, request-changes, comment"
+    exit 1
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then
@@ -711,18 +679,15 @@ PY
 if [[ "$PLATFORM" == "github" ]]; then
     case $ACTION in
         approve)
-            gh_rc=0
-            gh pr review "$PR_NUMBER" --approve ${COMMENT:+--body "$COMMENT"} || gh_rc=$?
-            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub approve failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
+            gh pr review "$PR_NUMBER" --approve ${COMMENT:+--body "$COMMENT"}
             echo "Approved GitHub PR #$PR_NUMBER"
             ;;
         request-changes)
             if [[ -z "$COMMENT" ]]; then
-                usage_error "comment required for request-changes (-b/--body)"
+                echo "Error: Comment required for request-changes"
+                exit 1
             fi
-            gh_rc=0
-            gh pr review "$PR_NUMBER" --request-changes --body "$COMMENT" || gh_rc=$?
-            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub request-changes failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
+            gh pr review "$PR_NUMBER" --request-changes --body "$COMMENT"
             echo "Requested changes on GitHub PR #$PR_NUMBER"
             ;;
         comment)
@@ -730,13 +695,12 @@ if [[ "$PLATFORM" == "github" ]]; then
                 echo "Error: Comment required"
                 exit 1
             fi
-            gh_rc=0
-            gh pr review "$PR_NUMBER" --comment --body "$COMMENT" || gh_rc=$?
-            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub review comment failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
+            gh pr review "$PR_NUMBER" --comment --body "$COMMENT"
             echo "Added review comment to GitHub PR #$PR_NUMBER"
             ;;
         *)
-            usage_error "unknown action: $ACTION"
+            echo "Error: Unknown action: $ACTION"
+            exit 1
             ;;
     esac
 elif [[ "$PLATFORM" == "gitea" ]]; then
@@ -774,7 +738,8 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             ;;
         request-changes)
             if [[ -z "$COMMENT" ]]; then
-                usage_error "comment required for request-changes (-b/--body)"
+                echo "Error: Comment required for request-changes"
+                exit 1
             fi
             # Best-effort host for credential resolution only (gitea_resolve_api_for_login
             # below re-derives the real host from HOST_OVERRIDE/remote independently and
@@ -829,7 +794,8 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             echo "Added and verified comment on Gitea PR #$PR_NUMBER (comment ID $comment_id)"
             ;;
         *)
-            usage_error "unknown action: $ACTION"
+            echo "Error: Unknown action: $ACTION"
+            exit 1
             ;;
     esac
 else

packages/mosaic/framework/tools/git/test-issue-assign-usage-contract.sh

@@ -1,154 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for issue-assign.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-assign-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-assign.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/issue-assign.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: issue-assign.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -i exits 2"
-expect_stderr "Issue number is required" "missing -i message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -i -a -l -m --issue --assignee --labels --milestone; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -i 5 -a --help
-expect_rc 2 "short flag value rejected" -i 5 -a -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -a; do
-    rc=0
-    run_wrapper_sandboxed -i 5 "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-# 6b. Provider-exit normalization (codex PR #1464): a provider stub exiting
-# 2 (its own usage-error status) must surface as wrapper exit 1, never 2.
-GH_REPO="$WORK_DIR/repo-gh"
-mkdir -p "$GH_REPO"
-git -C "$GH_REPO" init -q
-git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
-cat > "$BIN_DIR/gh" <<GHSTUB
-#!/usr/bin/env bash
-echo "gh \$*" >> "$PROBE_LOG"
-if [[ "\$1 \$2" == "issue edit" ]]; then exit 2; fi
-exit 0
-GHSTUB
-chmod +x "$BIN_DIR/gh"
-rc=0
-(
-    cd "$GH_REPO"
-    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-        "$SCRIPT_DIR/issue-assign.sh" -i 5 -a someone >"$OUT_FILE" 2>"$ERR_FILE"
-) || rc=$?
-[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
-grep -q "provider" "$ERR_FILE" || fail "GitHub path: normalized provider error missing from stderr"
-
-echo "issue-assign.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-close-usage-contract.sh

@@ -1,136 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for issue-close.sh (R1/R4, 2026-08-28).
-#
-# R4: usage errors print to STDERR and exit 2, distinct from provider,
-# credential, and verification failures (exit 1). R1: -b/--body is the
-# canonical comment flag; -c/--comment remains a compatible alias.
-# The comment is OPTIONAL here (an issue may close without one), so unlike
-# issue-comment there is no missing-comment arm.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-close-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 0
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-close.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/issue-close.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: issue-close.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "unknown option" "unknown option names itself on stderr"
-
-# 3. Missing required issue number: rc 2, stderr.
-expect_rc 2 "missing -i exits 2"
-expect_stderr "issue number is required" "missing -i message on stderr"
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -i -b -c --issue --body --comment; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -i 5 -b --help
-expect_rc 2 "short flag value rejected" -i 5 -b -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -b -c; do
-    rc=0
-    run_wrapper_sandboxed -i 5 "$flag" "closing note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Sandbox arms may issue DETECTION reads only (tea login list via the
-# stub); no gh/curl write or read may occur.
-if grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" | grep -q .; then
-    echo "FAIL: a sandbox arm performed a non-detection provider request:" >&2
-    grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" >&2
-    exit 1
-fi
-if grep -qE '^(gh|curl)' "$PROBE_LOG"; then
-    echo "FAIL: gh or curl was invoked during a sandbox arm:" >&2
-    grep -E '^(gh|curl)' "$PROBE_LOG" >&2
-    exit 1
-fi
-
-echo "issue-close.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-comment-readback.sh

@@ -42,8 +42,6 @@
 #  10. leaves NO temp files behind (POST/GET bodies + metadata) on either the
 #      success or the failure path — nested function-scoped RETURN traps do not
 #      clobber each other and every scratch file is removed on all exit paths.
-#  11. accepts the canonical -b/--body flag exactly like the -c/--comment alias
-#      (R1, 2026-08-28): a full verified write via -b alone.
 
 set -euo pipefail
 
@@ -411,28 +409,11 @@ run_comment() {
     seed_state "$mode"
     (
         cd "$REPO_DIR"
-        # Provisioned seats export MOSAIC_GIT_IDENTITY and MOSAIC_BRAIN_HOME
-        # seat-wide (launcher), and both escape this harness's sandboxed HOME:
-        # detect-platform.sh consults MOSAIC_GIT_IDENTITY BEFORE the repo-local
-        # mosaic.gitIdentity pin, and resolves the brain home (whose
-        # fleet/agents presence arms the no-identity fail-loud branch) from
-        # MOSAIC_BRAIN_HOME before $HOME. Without these explicit empties the
-        # wrapper either resolves the REAL seat-slot token (stub curl rejects
-        # it: the documented HTTP 401) or fails loud before any request.
-        # Set-but-empty reads as unset to detect-platform's "${VAR:-}" forms.
-        # NOTE: keep this comment block ABOVE the assignment chain — a comment
-        # inside a backslash-continued prefix chain terminates the command and
-        # silently demotes every earlier assignment to an unexported subshell
-        # assignment (measured 2026-08-28: the wrapper then ran without
-        # MOSAIC_CREDENTIALS_FILE and the suite died at credential resolution
-        # with zero diagnostic output).
         PATH="$BIN_DIR:$PATH" \
         TMPDIR="$TMP_SCRATCH" \
         HOME="$HOME_DIR" \
         XDG_CONFIG_HOME="$XDG_DIR" \
         MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
-        MOSAIC_GIT_IDENTITY="" \
-        MOSAIC_BRAIN_HOME="" \
         ISSUE_COMMENT_TEA_LOG="$TEA_LOG" \
         ISSUE_COMMENT_CURL_LOG="$CURL_LOG" \
         ISSUE_COMMENT_CURL_ARGV_LOG="$CURL_ARGV_LOG" \
@@ -449,7 +430,7 @@ run_comment() {
         ISSUE_COMMENT_REPO_SLUG="$REPO_SLUG" \
         ISSUE_COMMENT_API_BASE="$API_BASE" \
         ISSUE_COMMENT_API_ROOT="$API_ROOT" \
-        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" "${BODY_FLAG:--c}" "$BODY" "$@"
+        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" -c "$BODY" "$@"
     ) > "$OUTPUT_FILE" 2>&1
 }
 
@@ -633,21 +614,4 @@ done
 # issue_url (already exercised by Case 1's fresh-success), so the tightened check
 # is not rejecting genuine writes.
 
-# Case 11 (R1, 2026-08-28): -b/--body is the canonical comment flag and must
-# drive a full verified write exactly like the -c/--comment alias. BODY_FLAG
-# swaps only the flag spelling; every assertion below is case 1's contract.
-BODY_FLAG="-b"
-run_comment fresh-success
-grep -q 'Added and verified comment on Gitea issue #7 (comment ID 51)' "$OUTPUT_FILE"
-grep -q "^POST $API_BASE/issues/7/comments$" "$CURL_LOG"
-if grep -Eq '^comment |^issue comment ' "$TEA_LOG"; then
-    echo "FAIL: --body write went through tea instead of REST" >&2
-    exit 1
-fi
-grep -q "^GET $API_BASE/issues/comments/51$" "$CURL_LOG"
-grep -q "^POST $API_BASE/issues/7/comments $ACTING_LOGIN$" "$AUTH_LOG"
-assert_no_temp_leak "fresh-success-body-flag"
-assert_token_not_in_argv "fresh-success-body-flag"
-unset BODY_FLAG
-
 echo "issue-comment.sh REST create + exact-id read-back regression passed"

packages/mosaic/framework/tools/git/test-issue-comment-usage-contract.sh

@@ -1,172 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for issue-comment.sh (R1/R4 remediation, 2026-08-28).
-#
-# R4: usage errors print to STDERR and exit 2, distinct from provider,
-# credential, and verification failures (exit 1), so a caller (or a stop gate)
-# can tell an invocation defect from a delivery blocker. Before this contract
-# the wrapper exited 1 for usage errors with messages on STDOUT, and a
-# value-less flag (-c with no value) died SILENTLY at rc=1 because set -e
-# killed the failed `shift 2`. That silent shape is what full-stopped a fleet
-# seat: a caller could not distinguish "I invoked it wrong" from "delivery is
-# blocked".
-#
-# R1: -b/--body is the canonical comment flag (matching issue-create,
-# issue-edit, pr-create, pr-edit); -c/--comment remains a backward-compatible
-# alias.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. Missing required comment exits 2 (stderr).
-#   5. A value-less flag (-i -b -c -l and long forms) exits 2 with a
-#      "requires a value" message on stderr (the former silent-death class).
-#   6. -b and -c both pass parsing (the run then fails at platform detection
-#      in this non-repo fixture, nonzero and NOT 2), proving alias acceptance
-#      without any provider fixture.
-#   7. No arm performs any provider request: PATH shims for gh/tea/curl
-#      record every invocation and the probe log must stay empty.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-comment-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Provider shims: any invocation is recorded and fails the run at the end.
-# Usage-error arms must exit during argument parsing, before detect_platform,
-# so these prove "no provider request on parser failure".
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-# gh doubles as platform probe AND write path in arm 6b: probes exit 0; the
-# comment write exits 2 (gh's own usage-error status) to prove the wrapper
-# normalizes provider failures to exit 1 instead of propagating 2.
-if [[ "\$1 \$2" == "issue comment" ]]; then exit 2; fi
-exit 0
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-comment.sh" "$@" )
-}
-
-# Hermetic variant for parse-acceptance arms: neutralizes every identity/
-# credential source the wrapper consults (seat env vars, HOME, XDG tea config)
-# so the arm fails at credential resolution in ANY cwd repo, never reading a
-# real token or contacting a provider. Measured 2026-08-28: without this, the
-# arm's outcome depended on incidental URL-resolution state (brain cwd died at
-# URL-not-found; a stack worktree cwd resolved a configured URL, read the real
-# seat token, and invoked the curl stub — the suite then failed its own
-# no-provider-contact check, correctly).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/issue-comment.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage on stdout.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: issue-comment.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, message on stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "unknown option" "unknown option names itself on stderr"
-
-# 3. Missing required issue number: rc 2, stderr.
-expect_rc 2 "missing -i exits 2"
-expect_stderr "issue number is required" "missing -i message on stderr"
-
-# 4. Missing required comment: rc 2, stderr.
-expect_rc 2 "missing comment exits 2" -i 5
-expect_stderr "comment is required" "missing comment message on stderr"
-
-# 5. Value-less flags: rc 2 with "requires a value" on stderr. The old parser
-# died here silently (set -e on the failed shift 2).
-for flag in -i -b -c -l --issue --body --comment --login; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -i 5 -b --help
-expect_rc 2 "short flag value rejected" -i 5 -b -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 6. Alias acceptance at parse level: both -b and -c carry a value past
-# parsing; the wrapper then fails at platform detection (not a git repo)
-# nonzero but NOT as a usage error (rc must not be 2).
-for flag in -b -c; do
-    rc=0
-    run_wrapper_sandboxed -i 5 "$flag" "some text" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6b. GitHub-path exit normalization (codex blocker on 08a00149): gh's own
-# usage errors exit 2; the wrapper must NOT propagate that status (reserved
-# for the wrapper's usage-error contract). With a github remote and a gh stub
-# whose comment write exits 2, the wrapper must exit 1 with the normalized
-# error on stderr.
-GH_REPO="$WORK_DIR/repo-gh"
-mkdir -p "$GH_REPO"
-git -C "$GH_REPO" init -q
-git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
-git -C "$GH_REPO" config mosaic.gitIdentity ""
-rc=0
-(
-    cd "$GH_REPO"
-    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-        "$SCRIPT_DIR/issue-comment.sh" -i 5 -b "text" >"$OUT_FILE" 2>"$ERR_FILE"
-) || rc=$?
-[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
-grep -q "GitHub comment write failed" "$ERR_FILE" || fail "GitHub path: normalized error missing from stderr"
-grep -q "^gh issue comment" "$PROBE_LOG" || fail "GitHub path: gh write was not invoked"
-
-# 7. No provider contact from any usage-error arm (arm 6b's deliberate gh
-# invocation is the only permitted entry in the probe log).
-if grep -v '^gh issue comment' "$PROBE_LOG" | grep -q .; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    grep -v '^gh issue comment' "$PROBE_LOG" >&2
-    exit 1
-fi
-
-echo "issue-comment.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-create-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for issue-create.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-create-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-create.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/issue-create.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: issue-create.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -t exits 2"
-expect_stderr "Title is required" "missing -t message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -t -b -l -m --title --body --labels --milestone; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -t smoke -b --help
-expect_rc 2 "short flag value rejected" -t smoke -b -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -b; do
-    rc=0
-    run_wrapper_sandboxed -t "smoke" "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "issue-create.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-edit-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for issue-edit.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-edit-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-edit.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/issue-edit.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: issue-edit.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "unknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -i exits 2"
-expect_stderr "issue number is required" "missing -i message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -i -t -b -l -m --issue --title --body --labels --milestone; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -i 5 -b --help
-expect_rc 2 "short flag value rejected" -i 5 -b -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -b; do
-    rc=0
-    run_wrapper_sandboxed -i 5 "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "issue-edit.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-list-usage-contract.sh

@@ -1,130 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for issue-list.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-list-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-list.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/issue-list.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: issue-list.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -s -l -m -a -n -r --state --label --milestone --assignee --limit --repo; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -s --help
-expect_rc 2 "short flag value rejected" -s -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -s; do
-    rc=0
-    run_wrapper_sandboxed -s open >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "issue-list.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-reopen-usage-contract.sh

@@ -1,136 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for issue-reopen.sh (R1/R4, 2026-08-28).
-#
-# R4: usage errors print to STDERR and exit 2, distinct from provider,
-# credential, and verification failures (exit 1). R1: -b/--body is the
-# canonical comment flag; -c/--comment remains a compatible alias.
-# The comment is OPTIONAL here (an issue may close without one), so unlike
-# issue-comment there is no missing-comment arm.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-reopen-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 0
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-reopen.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/issue-reopen.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: issue-reopen.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "unknown option" "unknown option names itself on stderr"
-
-# 3. Missing required issue number: rc 2, stderr.
-expect_rc 2 "missing -i exits 2"
-expect_stderr "issue number is required" "missing -i message on stderr"
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -i -b -c --issue --body --comment; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -i 5 -b --help
-expect_rc 2 "short flag value rejected" -i 5 -b -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -b -c; do
-    rc=0
-    run_wrapper_sandboxed -i 5 "$flag" "closing note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Sandbox arms may issue DETECTION reads only (tea login list via the
-# stub); no gh/curl write or read may occur.
-if grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" | grep -q .; then
-    echo "FAIL: a sandbox arm performed a non-detection provider request:" >&2
-    grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" >&2
-    exit 1
-fi
-if grep -qE '^(gh|curl)' "$PROBE_LOG"; then
-    echo "FAIL: gh or curl was invoked during a sandbox arm:" >&2
-    grep -E '^(gh|curl)' "$PROBE_LOG" >&2
-    exit 1
-fi
-
-echo "issue-reopen.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-view-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for issue-view.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-view-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-view.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/issue-view.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: issue-view.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -i exits 2"
-expect_stderr "Issue number is required" "missing -i message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -i --issue; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -i --help
-expect_rc 2 "short flag value rejected" -i -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -i; do
-    rc=0
-    run_wrapper_sandboxed -i 5 >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "issue-view.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-lane-brief-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for lane-brief.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/lane-brief-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/lane-brief.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/lane-brief.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "owner/repo" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -r exits 2"
-expect_stderr "required" "missing -r message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -r -m -l -L -n --repo --milestone --label --login --limit; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -r owner/repo -m --help
-expect_rc 2 "short flag value rejected" -r owner/repo -m -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -r; do
-    rc=0
-    run_wrapper_sandboxed -r owner/repo >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "lane-brief.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-milestone-close-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for milestone-close.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/milestone-close-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/milestone-close.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/milestone-close.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: milestone-close.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -t exits 2"
-expect_stderr "Milestone title is required" "missing -t message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -t --title; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -t --help --help
-expect_rc 2 "short flag value rejected" -t --help -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -t; do
-    rc=0
-    run_wrapper_sandboxed -t "smoke" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "milestone-close.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-milestone-create-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for milestone-create.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/milestone-create-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/milestone-create.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/milestone-create.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: milestone-create.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -t exits 2"
-expect_stderr "Title is required" "missing -t message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -t -d --due --title --desc; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -t smoke -d --help
-expect_rc 2 "short flag value rejected" -t smoke -d -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -t; do
-    rc=0
-    run_wrapper_sandboxed -t "smoke" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "milestone-create.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-milestone-list-usage-contract.sh

@@ -1,153 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for milestone-list.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/milestone-list-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/milestone-list.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/milestone-list.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: milestone-list.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -s --state; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -s --help
-expect_rc 2 "short flag value rejected" -s -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -s; do
-    rc=0
-    run_wrapper_sandboxed -s open >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-# 6b. Provider-exit normalization (codex PR #1464): a provider stub exiting
-# 2 (its own usage-error status) must surface as wrapper exit 1, never 2.
-GH_REPO="$WORK_DIR/repo-gh"
-mkdir -p "$GH_REPO"
-git -C "$GH_REPO" init -q
-git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
-cat > "$BIN_DIR/gh" <<GHSTUB
-#!/usr/bin/env bash
-echo "gh \$*" >> "$PROBE_LOG"
-if [[ "\$1" == "api" ]]; then exit 2; fi
-exit 0
-GHSTUB
-chmod +x "$BIN_DIR/gh"
-rc=0
-(
-    cd "$GH_REPO"
-    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-        "$SCRIPT_DIR/milestone-list.sh" >"$OUT_FILE" 2>"$ERR_FILE"
-) || rc=$?
-[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
-grep -q "provider" "$ERR_FILE" || fail "GitHub path: normalized provider error missing from stderr"
-
-echo "milestone-list.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-close-usage-contract.sh

@@ -1,133 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for pr-close.sh (R1/R4, 2026-08-28).
-#
-# R4: usage errors print to STDERR and exit 2, distinct from provider,
-# credential, and verification failures (exit 1). R1: -b/--body is the
-# canonical comment flag; -c/--comment remains a compatible alias.
-# The comment is OPTIONAL here (an issue may close without one), so unlike
-# issue-comment there is no missing-comment arm.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-close-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-close.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/pr-close.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: pr-close.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "unknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -n exits 2"
-expect_stderr "PR number is required" "missing -n message on stderr"
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -n -b -c --number --body --comment; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -n 5 -b --help
-expect_rc 2 "short flag value rejected" -n 5 -b -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -b -c; do
-    rc=0
-    run_wrapper_sandboxed -n 5 "$flag" "closing note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "pr-close.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-create-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for pr-create.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-create-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-create.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/pr-create.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: pr-create.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -t exits 2"
-expect_stderr "Title is required" "missing -t message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -t -b -B -H -l -m -i --title --body --base --head --labels --milestone --issue; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -t smoke -b --help
-expect_rc 2 "short flag value rejected" -t smoke -b -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -b; do
-    rc=0
-    run_wrapper_sandboxed -t "smoke" "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "pr-create.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-edit-usage-contract.sh

@@ -1,140 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for pr-edit.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-edit-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-edit.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/pr-edit.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: pr-edit.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -n exits 2"
-expect_stderr "Pull request number is required" "missing -n message on stderr"
-expect_rc 2 "no edit option exits 2" -n 5
-expect_stderr "At least one edit option is required" "no-edit-option message on stderr"
-expect_rc 2 "non-integer PR number exits 2" -n abc -t x
-expect_stderr "positive integer" "integer check on stderr"
-expect_rc 2 "mutually exclusive draft/ready exits 2" -n 5 --draft --ready
-expect_stderr "mutually exclusive" "mutual exclusion on stderr"
-expect_rc 2 "bad repo format exits 2" -n 5 -t x -r not-a-slug
-expect_stderr "OWNER/REPO" "repo format on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -n -t -b -B -l -r -H --number --title --body --base --login --repo --host; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -n 5 -t smoke -b --help
-expect_rc 2 "short flag value rejected" -n 5 -t smoke -b -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -b; do
-    rc=0
-    run_wrapper_sandboxed -n 5 "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "pr-edit.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-review-repo-host-override.sh

@@ -218,7 +218,7 @@ if grep -q 'Unknown option' "$OUTPUT_FILE"; then
     cat "$OUTPUT_FILE" >&2
     exit 1
 fi
-grep -q "unknown action 'bogus-action'" "$OUTPUT_FILE"
+grep -q 'Unknown action: bogus-action' "$OUTPUT_FILE"
 
 # --- Case 2: -h/--help documents both overrides.
 HELP_TEXT="$("$SCRIPT_DIR/pr-review.sh" -h)"

packages/mosaic/framework/tools/git/test-pr-review-usage-contract.sh

@@ -1,148 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for pr-review.sh (R1/R4, 2026-08-28).
-#
-# R4: usage errors print to STDERR and exit 2, distinct from provider,
-# credential, and verification failures (exit 1). R1: -b/--body is the
-# canonical comment flag; -c/--comment remains a compatible alias.
-# Required: -n AND -a. The comment is required only for the
-# request-changes action (semantic usage check, also rc 2).
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-review-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-review.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/pr-review.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: pr-review.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "unknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -n exits 2"
-expect_stderr "PR number is required" "missing -n message on stderr"
-expect_rc 2 "missing -a exits 2" -n 5
-expect_stderr "Action is required" "missing -a message on stderr"
-expect_rc 2 "request-changes without comment exits 2" -n 5 -a request-changes
-expect_stderr "comment required for request-changes" "request-changes message on stderr"
-expect_rc 2 "comment without body exits 2 pre-detection" -n 5 -a comment
-expect_stderr "comment required for comment" "comment-without-body message on stderr"
-expect_rc 2 "invalid action exits 2 pre-detection" -n 5 -a bogus
-expect_stderr "unknown action" "invalid action message on stderr"
-# Invalid-action arms must not contact any provider (validation precedes
-# detect_platform): probe log empty at this point.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: an invalid-action arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -n -a -b -c -l -r --number --action --body --comment --login --repo; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -n 5 -a comment -b --help
-expect_rc 2 "short flag value rejected" -n 5 -a comment -b -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -b -c; do
-    rc=0
-    run_wrapper_sandboxed -n 5 -a comment "$flag" "review note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "pr-review.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/quality/test-enumeration-exclusions.txt

@@ -14,6 +14,7 @@
 packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix (git -C scoping)
 packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix
 packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh | resolves real credentials (#1007 census, fourth entry via family-grep); joins CI after the wrapper-half hermeticity fix
+packages/mosaic/framework/tools/git/test-issue-comment-readback.sh | resolves real credentials (#1007 census, fifth entry); joins CI after the wrapper-half hermeticity fix
 
 # --- tools/git: push guards — measured green locally, CI-image fitness unverified ---
 packages/mosaic/framework/tools/git/test-push-guard.sh | measured green at 826a8b3b (46 passed / 0 failed, one run, 2026-07-31); CI-image fitness unverified; #1017 burndown

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-edit.sh && bash framework/tools/git/test-pr-create-fallback-default-base.sh && bash framework/tools/git/test-repo-decl-consumption.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-no-status.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-ci-queue-wait-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-fork-ci-status.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-issue-comment-usage-contract.sh && bash framework/tools/git/test-issue-comment-readback.sh && bash framework/tools/git/test-issue-close-usage-contract.sh && bash framework/tools/git/test-issue-reopen-usage-contract.sh && bash framework/tools/git/test-pr-close-usage-contract.sh && bash framework/tools/git/test-pr-review-usage-contract.sh && bash framework/tools/git/test-issue-edit-usage-contract.sh && bash framework/tools/git/test-issue-create-usage-contract.sh && bash framework/tools/git/test-pr-edit-usage-contract.sh && bash framework/tools/git/test-pr-create-usage-contract.sh && bash framework/tools/git/test-issue-assign-usage-contract.sh && bash framework/tools/git/test-milestone-close-usage-contract.sh && bash framework/tools/git/test-milestone-list-usage-contract.sh && bash framework/tools/git/test-issue-view-usage-contract.sh && bash framework/tools/git/test-issue-list-usage-contract.sh && bash framework/tools/git/test-milestone-create-usage-contract.sh && bash framework/tools/git/test-lane-brief-usage-contract.sh && bash framework/tools/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/_scripts/test-structure-anchor-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh && bash framework/tools/fleet/test-agent-session-legacy-socket-guard.sh && bash framework/tools/git/test-grant-reviewer.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-edit.sh && bash framework/tools/git/test-pr-create-fallback-default-base.sh && bash framework/tools/git/test-repo-decl-consumption.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-no-status.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-ci-queue-wait-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-fork-ci-status.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/_scripts/test-structure-anchor-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh && bash framework/tools/fleet/test-agent-session-legacy-socket-guard.sh && bash framework/tools/git/test-grant-reviewer.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",