docs(git): never stash — the stack is shared repo-wide, park work as a wip commit (#14078)

[mrveiss]

Thinking Path

Ask 3 of #14078 — "stop the source" — was the only part of that umbrella still unaddressed after
its 18 rescued stashes were triaged. The umbrella's own wording: "Sessions should commit
incrementally on their own worktree branch instead of stashing, since the stack is shared. Worth a
line in the git/worktree developer doc."

The doc already had half of it. CLAUDE_GIT.md step 2 of the Pre-Flight Checklist says to read
git stash list and ask before proceeding if it is non-empty. What it never said is that you must
not write to the stack — which is the behaviour that produced 113 entries over three months. A
reader who follows the checklist literally learns to be careful about someone else's stash and
learns nothing about creating their own.

So the gap is a rule, not a warning: never stash, park work as a wip: commit on your own branch.
That also lines up with the surrounding protocol, which already tells sessions to leave nothing
uncommitted and to give WIP a wip: prefix — stashing is the one path that quietly opts out of
every ownership guarantee the worktree mandate provides.

I put it next to Branch Safety rather than inside the checklist because it is a standing prohibition
with a recovery procedure, not a per-task step, and the checklist entry now links to it so the
existing step gains the missing half without growing.

The recovery half matters as much as the prohibition. Someone will find a non-empty stack, and the
wrong instinct is to clear it. The section says what #14078 actually did: rescue each entry to a
branch, open an issue naming that branch, and drop only what is demonstrably present in base.
Without that, "never stash" reads as "so delete the ones you find".

What Changed

• docs/developer/CLAUDE_GIT.md — new "Never Stash (chore(git): 113 stashes — 18 stranded, now rescued to branches; each needs an owner and a verdict #14078)" section: the stack is shared
  repo-wide; never stash, never pop/drop/clear/apply, never
  git restore --staged --worktree; park work as a wip: commit instead. Carries the concrete
  cost (113 entries, 18 rescued, 17 already landed, 1 a security gap — security(bedrock): AWS credentials no longer read from the secrets manager — SecretsService path and audit trail dropped in a formatting auto-fix #15023) so it reads as a
  post-mortem rather than a preference, and gives the rescue-not-sweep procedure for a stack you
  inherit.
• docs/developer/CLAUDE_GIT.md Pre-Flight step 2 — now links to that section, so the "read the
  stack" step points at the "do not write to it" rule.
• CLAUDE.md — the CLAUDE_GIT.md trigger row gains "stashing", so the rule is reachable from
  the index by the word someone would actually be looking for.

Verification

• Docs only — no code, no behaviour change, nothing to execute.
• Anchor checked: the section heading ## Never Stash (#14078) renders as #never-stash-14078,
  which is the link target used in Pre-Flight step 2.
• Both edited files were verified to contain the intended text after the edit; the CLAUDE.md
  trigger row was matched exactly before replacement, so a silent no-op was not possible.
• The claims in the new section are the findings from the chore(git): 113 stashes — 18 stranded, now rescued to branches; each needs an owner and a verdict #14078 triage: 113 stash entries, 18
  rescued to rescued/* branches, 17 of those closed as landed/superseded/obsolete with per-file
  evidence, and rescued stash: issue-MVA-3047: 17e4c442b feat(chat): context overflow protection — auto-summarize conve #14087 left open over the Bedrock credential-audit gap now tracked as security(bedrock): AWS credentials no longer read from the secrets manager — SecretsService path and audit trail dropped in a formatting auto-fix #15023.

Model Used

Claude Opus 5 (1M context)

Refs #14078

[mrveiss]

Review verdict: MERGE, with one MEDIUM finding I have fixed in this PR rather than deferring — because leaving it would have undermined the doctrine the PR exists to establish.

The contradiction. docs/developer/CLAUDE_WORKFLOW.md:118 said "Do NOT create/apply/drop git stash unless explicitly requested" — a conditional permission — while the new CLAUDE_GIT.md:91 says "Never git stash" unconditionally. Two docs disagreeing on whether stash is ever permitted is exactly the documentation-fork case: coverage unions, but conflicting claims resolve against reality, and reality here is #14078's 113 unowned entries, one of which was hiding a security fix. Replaced the conditional line with the absolute rule plus a cross-link to the canonical section.

Second, smaller fix. The git restore --staged --worktree prohibition was filed under "Never Stash" as "the same reason in miniature" — but it never touches refs/stash. It is a different destructive-discard risk: it resets your own index and worktree from HEAD. The prohibition is right; the stated mechanism was not. Now says what it actually does, and why to back files up first.

The core claim checks out. refs/stash is a single ref in the repository's common .git directory — unlike HEAD and the index, which git worktree add gives each worktree its own copy of. So every stash list/push/pop/drop/apply reads and writes the one shared stack from any linked worktree. The doctrine is accurate, which matters: an overstated rule gets disbelieved and ignored.

The alternative it offers is real too — the wip: convention it points at already exists at CLAUDE_WORKFLOW.md:98, and the recovery procedure mirrors what #14078's own triage actually did, verified against the 19 rescued/stash-* branches in this clone.

Refs #14078 is correct: this delivers ask 3 (document the rule). Asks 1 and 2 — the inventory and the per-entry disposition — were resolved outside this diff, with 17 of #14082–#14099 closed and #14087 open because it turned out to be a real security finding, now #15023.

New head f4bcc5e3c, 0 behind base.