docs(agent-orientation): add exec-bit staging guidance for new shebang files

[kyle-sexton]

Summary

Restores exec-bit staging guidance to components/agent-orientation/orientation.md — the source of the materialized AGENTS.md synced into consumer repos — so a Windows-specific staging trap is caught before a commit instead of after a CI round trip.

Fix

• components/agent-orientation/orientation.md: adds a second section, "New shebang files land in the index as non-executable." Explains that core.filemode=false (the Windows default) makes a newly staged shebang file land at git mode 100644 regardless of intended use, that the exec-bit gate (components/local-lane-guards/check-exec-bit.sh) rejects any tracked 100644 shebang file, and that the failure only surfaces after a CI round trip — so it names the fix (git update-index --chmod=+x -- <path>) to run before committing, not after the gate fails.
• Placed in orientation.md rather than components/local-lane-guards/README.md (which already documents the guard's layout and local invocation) because the README is not synced anywhere — distribution/sync-manifest.yml ships only the guard scripts under local-lane-guards to tools/shared/local-lane-guards/<file>, never the README. orientation.md is the only artifact of this component that reaches an agent working in a consumer repo, so pointer-not-copy isn't available here: the guidance has to live where it's read.

This re-adds content to a file #394 deliberately trimmed to only the synced-standards warning, under the rebuild rule established there ("lines return only with stumble-ledger evidence"). The evidence is below.

Verification

• npm run lint:md — 0 issues across 113 files.
• distribution/sync-manifest.sh validate — manifest valid (37 components, 8 targets).
• bash distribution/sync-manifest.test.sh — 1312/1314 pass. The 2 failures (manifest symlink is rejected before parsing, its diagnostic-text sibling) reproduce identically in a fresh clone of main at this PR's base commit (2386434), unmodified — a Windows environment limitation (ln -s needs elevated privileges/Developer Mode), not a regression from this diff.
• bash components/local-lane-guards/run-local-lane-guards.sh exec-bit — dogfoods the guard this note documents; passes (no shebang files in this change).
• lefthook pre-commit (editorconfig, typos, gitleaks, markdownlint) green on the commit.

Related

No linked issue.

• feat(testing): can't-fail test audit — detector plus fail-closed --check mode claude-code-plugins#2684 — the stumble evidence: the exec-bit workaround (git update-index --chmod=+x) had to be inlined into the issue body because the guidance existed nowhere else, costing a CI round trip.
• components/agent-orientation/orientation.md — trimmed to its current single section by fix(distribution): align PR-body policy with the enforced contract and trim agent-orientation #394, which established the rebuild rule this PR satisfies.
• components/local-lane-guards/README.md — the guard's contributor-facing documentation (not synced; the reason this guidance lives in orientation.md instead of there).

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 1m 47s —— View job

---

Code review complete

• Gather context (PR diff, orientation.md, check-exec-bit.sh, sync-manifest.yml, components/local-lane-guards/README.md, REVIEW.md)
• Run /review:code-review criteria against the diff
• Post findings

Scope: single file, doc-only addition (components/agent-orientation/orientation.md, +12/-0). No code, no security surface — this repo has no claude-security-review workflow, but nothing in the diff touches the security-scope checks either.

Findings: none that clear the high-signal bar. This is a clean, low-risk addition.

What I independently checked (not just restating the PR body):

• Cross-referenced the new section's technical claims against components/local-lane-guards/check-exec-bit.sh — the gate does reject only tracked shebang files staged as 100644, and its own error message emits the exact same fix command (git update-index --chmod=+x -- "$path") the new doc section prescribes.
• Confirmed the "not wired into local pre-commit" claim: local-lane-guards/exec-bit is absent from lefthook.yml and components/lefthook-base/lefthook.yml, so the failure genuinely doesn't surface until CI runs the guard — that grounds the doc's "one round trip after the commit" framing.
• Confirmed the placement rationale: distribution/sync-manifest.yml syncs only the guard scripts under local-lane-guards (tools/shared/local-lane-guards/<file>), not components/local-lane-guards/README.md — so orientation.md is indeed the only artifact of this component an agent working in a consumer repo would ever see.
• Checked markdown structure/style by hand against .markdownlint-cli2.jsonc (ATX headings, dash bullets, backtick code spans, no line-length rule) — the new section matches the existing file's conventions. I could not execute markdownlint-cli2 myself in this sandbox (command execution is restricted here), so I did not independently reproduce the author's "0 issues" claim — noting that as author-claimed, not verified by me.
• No existing file cites orientation.md by heading anchor, so the new ## heading has no cross-file citation to keep in sync.

No inline comments were needed — nothing anchored to a specific line rose to blocking or important.

[github-actions]

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[kyle-sexton]

Closing this against the rebuild rule it would have to clear. The work is sound; the evidence bar is not met. Recording the full analysis so a future re-add starts from here rather than re-deriving it.

Why this is closed rather than merged

#392/#394 trimmed orientation.md under the unhobble evidence gate one commit before this PR
was authored, and set the bar for restoring anything:

an instruction returns only after repeated same-cause failures, with the re-add citing its
evidence.

Neither half is met.

• No failure occurred. The cited motivation is that melodic-software/claude-code-plugins#2684
  inlined the exec-bit workaround into its issue body. That is evidence the guidance is useful,
  not that its absence caused a failure. The work that issue tracked shipped with both .sh files
  correctly staged 100755 — verified directly at the merged tree. No exec-bit CI failure occurred
  anywhere in that chain.
• Not repeated. Even counting the inlined warning as a stumble, that is one instance against a
  rule asking for a pattern.

And #392's own removal reasoning applies to this addition. It deleted the Conventional-Commits
PR-title rule for being "redundant with a deterministic machine gate (pr-title.yml already
enforces it in consuming repos, and the gate itself teaches)." This PR's own verification
establishes exec-bit is that identical shape: check-exec-bit.sh scans all tracked shebang files
repo-wide with no allowlist, and its CI message already prints the fix command. Enforced
deterministically, and it teaches.

The honest counter-argument is that the doc prevents a CI round-trip where the gate only teaches
after a failure. That is real, but "saves one round-trip" is not a keep case under a discipline
adopted after two days of bare-model operation logged zero observation-ledger rows.

Findings worth keeping, independent of this PR

local-lane-guards' README never reaches a consumer. Per distribution/sync-manifest.yml, that
component syncs only the guard scripts, to tools/shared/local-lane-guards/<file>. So
pointer-not-copy is structurally unavailable for guard documentation — orientation.md is the
only artifact of the agent-orientation component that reaches an agent working in a consumer repo.
Anyone later reasoning about where guard documentation belongs needs this fact; it settles the
question more firmly than observing that orientation.md is single-topic today.

check-exec-bit.sh mechanism, verified: scans all tracked shebang files repo-wide, no allowlist,
no path exemption, and prints the fix command in its own failure output. The Windows trap is that
core.filemode is conventionally false, so git add records 100644 — the working-tree file is
not POSIX-executable in the first place, rather than executable-but-misrecorded.

What would reopen this

A stumble ledger showing repeated exec-bit failures from the same cause. If that accumulates,
this branch (docs/exec-bit-orientation-guidance) is a ready-made re-add: the home determination,
the mechanism verification, and the guidance text are already done and CI-green.