feat(agents): mirror objectui's guard-shared-stash hook + the shared-stash warning (#5742)

[os-project-manager]

Fixes #5742

Why

refs/stash and its reflog live in the common .git directory, so every linked
worktree of a repo shares one LIFO stack. The per-task worktree isolation AGENTS.md
Prime Directive #11 mandates — and guard-main-checkout*.sh enforce — covers the working
tree and HEAD, and does not cover the stash. Two agents stashing at the same time swap
entries: one pop restores the other's changes into your worktree while yours stay on the
stack, pop reports success, and a following git add -A commits their half-finished
work into your PR.

That is not hypothetical: objectui#3430 (2026-08-06) hit two parallel dev agents in the
middle of reverse verification — the workflow every dev agent runs, which is exactly why
the collision window is wide. Both changesets survived only as unreachable commits whose
SHAs were still in scrollback; once the stack empties, refs/stash and logs/refs/stash
are gone (git reflog refs/stash answers fatal: ambiguous argument) and a git gc in
between makes the loss permanent.

objectui landed a guard after its incident. This repo had neither the guard nor the
warning — a gap its own guard-main-checkout-bash.sh header had recorded in prose
("objectui additionally runs guard-shared-stash.sh on the same matcher; this repo has no
such hook"). This PR mirrors the objectui side here.

Premise verification (before implementing)

Both PM assumptions hold at origin/main:

1. No stash guard in this repo. git ls-tree -r --name-only origin/main -- .claude/
   listed guard-main-checkout.sh, guard-main-checkout-bash.sh and its self-test, and
   nothing else; git grep -i stash origin/main -- AGENTS.md CLAUDE.md .claude/ returned
   exactly one hit — the stale note in guard-main-checkout-bash.sh:17 quoted above.
2. objectui's hook + self-test exist at its origin/main and are the
   incident-hardened versions (objectui#3430 acceptance comment records the 32-case matrix
   and its reverse verification). Read via
   git -C /home/user/objectui show origin/main:.claude/hooks/guard-shared-stash.sh, not
   from its working tree. No open issue in objectui records a gap in the hook.
3. Hook registration is in-repo (.claude/settings.json) and a PR can carry it — no
   wiring gap to report.

What landed

1. .claude/hooks/guard-shared-stash.sh — mirrored from objectui. The verdict logic
   (split_segments / check_segment) is kept case-for-case identical so the two repos'
   guards cannot drift; only issue references, example paths and the package name in the
   self-test are localised. The contract is preserved exactly:

   • blocks the mutating forms — push / pop / save / drop / clear / branch,
     bare git stash, and stash@{N} positions (a position in a stack you do not own);
   • allows git stash list / show / create, and apply / store pinned to a
     literal hex object id (the recovery path used to repair the incident);
   • fails open on shapes it cannot parse (bash -c …, xargs), quote-aware so that
     writing or grepping about the ban never trips the ban (objectstack#4890's lesson);
   • exit codes mirror guard-main-checkout.sh: 0 allow, 2 block; escape hatch
     OS_ALLOW_STASH=1.

   Localised beyond objectui's copy: the recommended replacement list leads with
   git checkout origin/main -- PATH, which is the recipe the 2026-08-06 routing comment
   on this issue named for reverse verification.

2. .claude/hooks/guard-shared-stash.selftest.sh — the 32-case matrix, one-for-one
   with objectui's, with objectstack paths/packages.

3. Wiring — registered in .claude/settings.json on the existing Bash
   PreToolUse matcher, ahead of guard-main-checkout-bash.sh (objectui's order), i.e.
   identically to how this repo already registers its guards. The stale
   "this repo has no such hook" note in guard-main-checkout-bash.sh is corrected in the
   same commit — guard-main-checkout.sh 同样只挂 Edit|Write|NotebookEdit,本仓经 Bash 写文件(sed -i / tee / 重定向)可绕过 worktree 强制 #5790's closing observation is now closed.

4. AGENTS.md — the warning next to the worktree rule: a block in the Multi-agent
   working discipline section (mechanism, the objectui#3430 incident, the four
   collision-free replacements, the hook and its escape hatch), plus one clause inside
   Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11 so a reader who never reaches the section still learns that the
   stash is the one thing a worktree does not isolate. Deliberately scoped to that area:
   objectstack#5981 also edits AGENTS.md and should land cleanly on top.

5. .claude/agents/os-dev.md — the producer-side fix. The reverse-verification
   section now prescribes git checkout origin/main -- PATH, a patch file, or a temp
   commit, and forbids bare git stash. This is the recipe that caused objectui#3430;
   fixing it in the agent definition beats patching it per-dispatch.

6. CLAUDE.md — inlined as a fourth never-miss rule (heading count updated
   three → four). Call and reasoning: this file states its own bar as "missing any one of
   them wastes or corrupts other agents' work", and this defect is the only one of the set
   with a measured instance of exactly that — two agents' in-flight changes swapped in
   one morning. objectui made the same call in its CLAUDE.md after the incident, so
   inlining also keeps the two repos' loaded-every-session rule sets aligned. The full
   mechanism stays in AGENTS.md; the inline copy is the rule plus the replacements.

Self-test evidence (the change gate for this hook)

$ .claude/hooks/guard-shared-stash.selftest.sh
== mutating forms must be blocked ==
  ok   block  git stash
  ok   block  git stash push -- packages/spec/src/kernel/metadata-plugin.zod.ts
  ok   block  git stash pop
  ok   block  git stash save wip
  ok   block  git stash drop
  ok   block  git stash clear
  ok   block  git stash branch recovered
  ok   block  git stash pop > /dev/null
== positional stash@{N} is NOT SHA-pinned: still the shared stack ==
  ok   block  git stash pop stash@{0}
  ok   block  git stash apply stash@{1}
== reached through separators, substitution and git -C ==
  ok   block  cd /home/user/objectstack && git stash pop
  ok   block  git -C ../objectstack-issue-5742 stash pop
  ok   block  out=$(git stash pop)
  ok   block  git status && git stash push -m wip; pnpm test
== read-only and SHA-pinned forms are allowed ==
  ok   allow  git stash list
  ok   allow  git stash show -p
  ok   allow  git stash create
  ok   allow  git stash --help
  ok   allow  git stash apply abc1234
  ok   allow  git stash apply --index deadbeefcafe1234
  ok   allow  git stash store -m "WIP issue-5742" b52e3aa1234567
== unrelated commands are untouched ==
  ok   allow  pnpm --filter @objectstack/spec test
  ok   allow  git status
  ok   allow  git commit -am wip
  ok   allow  git diff > /tmp/wip.patch && git checkout -- packages/spec
== writing ABOUT the ban must not trip the ban ==
  ok   allow  grep -n "git stash" AGENTS.md
  ok   allow  grep -rn "cd x && git stash pop" .claude/
  ok   allow  echo "never run git stash pop in a shared checkout"
  ok   allow  git grep -n "git stash"
== escape hatch ==
  ok   allow  git stash pop
== payload with no command fails open ==
  ok   allow  (empty tool_input)
== jq-less fallback still parses the command ==
  ok   block  (no jq on PATH)

32 passed, 0 failed

bash -n clean on both files; .claude/settings.json parses (JSON.parse); both new
files committed mode 100755.

Reverse verification — direction predicted before running

Prediction: neutering check_segment to always return 0 (allow) must turn exactly the
15 block cases red and leave the 17 allow cases green — the usual "red" direction,
because every block case is a positive assertion about the one verdict being removed.
Run on a scratch copy (the committed hook untouched):

152:  return 0   # NEUTERED for reverse verification
…
  FAIL no-jq fallback got=allow

17 passed, 15 failed

15 red / 17 green, as predicted. The matrix cannot go green on a guard that does not
guard.

Gates

Enumerated from .github/workflows/lint.yml (every pnpm step, in order) and run on the
committed tree, not from memory. All green:

• ESLint job — pnpm lint (exit 0) and all 30 check:* steps: slot-lookup,
  query-options-erasure, verify-stand-in, nul-bytes, doc-authoring,
  docs-audit-scope, role-word, quick-reference-counts, adr-anchors,
  org-identifier, authz-resolver, service-providers, route-envelope,
  error-code-casing, wildcard-fallthrough, meta-type-normalized,
  init-service-contract, durability-log-level, startup-registry-verdict,
  objectui-changeset, release-notes, release-body, node-version,
  workflow-status-functions, shard-attestation, published-files,
  engine-double-contract, resume-authority-declared, merge-driver,
  spec-parsed-alias.
• Type-check job — check:type-check-coverage, check:driver-conformance,
  check:stall-guard, check:skill-frame-sync, check:skill-compatibility,
  check:i18n, check:i18n-coverage, spec exec tsc --noEmit, and the
  @objectstack/spec gates check:generated --reconcile-only, skill-docs,
  spec-changes, upgrade-guide, authorable-surface, docs, skill-refs,
  react-blocks, api-surface, exported-any, dual-source-exports,
  skill-examples, plus @objectstack/lint check:doc-formula-expressions.
• check:skill-frame-sync is the one that reads .claude/agents/os-dev.md
  (the internal dev-agent copy of the escalation frame); green — this PR edits the
  reverse-verification section, not the frame.
• Six of those gates were red on first run purely as the unbuilt-worktree trap
  (api-surface, exported-any, dual-source-exports, skill-examples,
  doc-formula-expressions, i18n*); after
  turbo run build --filter='./packages/*' --filter='./packages/*/*' all six are green.
• Not run locally: the turbo run typecheck / examples / downstream-contract steps.
  This PR changes zero .ts/.tsx/.js files (markdown, shell, one JSON), so those
  steps have no input from it; CI runs them.
• node scripts/check-nul-bytes.mjs OK, plus a self-scan beyond the gate
  (grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]') over every touched file: no hits.

Changeset decision: skip-changeset, no changeset file

This PR touches .claude/**, AGENTS.md and CLAUDE.md only. No published package
changes, so there is nothing for changesets to version: a changeset here would have to
name a package it does not touch and would put an agent-protocol edit into that package's
CHANGELOG and the release notes. That is the exact case the dev-agent definition calls
out ("a .claude/-only PR releases nothing and writes no changeset"), so the label is the
honest declaration and it is applied on this PR rather than merely declared here.

Observation, not fixed here

objectui's copy of the hook has a stale header line — # Self-test (26 cases …) while its
matrix has been 32 cases since it landed (the objectui#3430 acceptance comment says 32).
The mirrored copy in this PR states 32, which is the measured number. The objectui-side
drift is cosmetic and belongs to that repo; noted rather than inherited silently.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F8q5J1MQyocgtNspb15fSn

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 8, 2026 7:49am