beads/docs
ecuthiell 70a12ba664
fix(init): write embedded excludes in the selected project (#6462)
* fix(worktree): scrub inherited Git routing state

Establish CWD as the worktree repository boundary before discovery can consume inherited Git routing. Fence the startup config probe, clear routing in-process before root pre-run discovery, and retain command-owned subprocess scrubbing as defense in depth without changing PID or signal semantics.

Fixes #5531

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell

* refactor(worktree): explain owned filtering and remove an unused shim

Document why filtering the fresh routing slice in place is safe and call
the shared routing-key classifier directly from tests. Retain the two
forwarders used by production worktree subprocess/removal paths.

Review: https://github.com/gastownhall/beads/pull/5623#pullrequestreview-5098421671
Bead: saa-cgh.23
Agent-Signature: unknown-model/unknown-reasoning

* fix(config): isolate identity and tracked-file Git probes from routing

Reuse the worktree routing owner for GetIdentity and isGitTracked so
explicit cwd/path selection is not displaced by inherited repository,
index or injected config state. Preserve identity precedence and the
tracked-secret refusal contract, with real target/decoy regressions.

Follow-up: https://github.com/gastownhall/beads/issues/6222
Dependency: https://github.com/gastownhall/beads/pull/5623
Reported-by: bee-ghosttrack
Bead: saa-cgh.93
Agent-Signature: unknown-model/unknown-reasoning

* fix(config): share subprocess key identity for Git routing (saa-cgh.93)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(exec): match Windows environment key identity (#5618)

Centralize os/exec-compatible environment-key comparison and use it for credential, metrics, Git-hook, trace, and repro subprocess filters. Preserve exact Unix semantics and Unicode near-collisions.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>

* test(execenv): exercise every environment operation under both host rules

Thread the host choice through narrow private helpers behind the existing
exported functions. Keep one normalization owner and retain native wrapper
tests; the additional table covers both host branches for equality, prefix
matching, last-wins lookup, filtering and input preservation.

Review: https://github.com/gastownhall/beads/pull/5672#pullrequestreview-5096948965
Bead: saa-cgh.78
Agent-Signature: unknown-model/unknown-reasoning

* test(execenv): exercise exported host policy wiring (saa-cgh.78)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* docs(worktree): explain startup Git environment scope (saa-cgh.23)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(config): isolate role commands from Git routing (saa-cgh.99)

Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6357.

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(env): exercise shared key helpers on native Windows (saa-cgh.78)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* refactor(gitenv): share key parsing and normalize routing membership once (saa-cgh.93)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* docs(config): explain role command routing policy (saa-cgh.99)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): isolate role configuration from inherited Git routing (saa-cgh.109.3)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): use the selected origin in contributor setup (saa-cgh.109.7)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): isolate Git writes in planning repositories (saa-cgh.109.9)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(init): retain inherited planning commit author (saa-cgh.109.9)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): align embedded role gates with selected Git context (saa-cgh.109.12)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): scope embedded artifact Git operations to selected directory (saa-cgh.109.15)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(init): cover selected optional artifacts and explain refused commits (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* Honor role-probe cancellation and exercise actual fork planning (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): warn when automatic contributor role write fails (saa-cgh.109.3)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(init): cover successful nonquiet contributor role writes (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* Assert the automatic contributor setup banner alongside warnings (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* test(init): read persisted role routing from the store (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* fix(git): isolate domain role configuration from inherited routing (saa-cgh.109.5)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): probe the selected repository before configuring roles (saa-cgh.109.8)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* docs(init): explain role probe discovery ceiling behavior (saa-cgh.109.8)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): bind proxied tail Git operations to selected directory (saa-cgh.109.14)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(gitignore): preserve CRLF when appending project rules (saa-cgh.96)

Reported by bee-ghosttrack in gastownhall/beads#6343.

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(gitignore): pin detector edge cases and clarify append behavior (saa-cgh.96)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(gitignore): preserve line endings in Git exclude appends (saa-cgh.104)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* test(gitignore): clarify exclude fixture path variable (saa-cgh.104)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(gitignore): refuse exclude writes after read errors (saa-cgh.110)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* refactor(gitignore): share append byte composition (saa-cgh.105)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* docs(gitignore): explain append aliasing and trailing CR completion (saa-cgh.105)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* refactor(gitignore): use shared composition for exclude rules (saa-cgh.111)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(gitignore): omit the empty exclude leading separator (saa-cgh.112)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): bind exclude writers to the selected Git directory (saa-cgh.109.16)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* Explain restoration of absent routing variables in selected exclude tests (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* Keep init role operations on the captured selected Git context (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* Align selected-tail fixtures with captured role authority (saa-cgh.120)

Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): write embedded excludes in the selected project (saa-cgh.120.11)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(init): scrub the fork auto-detect gate; scope the startup-scrub claims

Maintainer review fixup for PR #6462 (adoption review iterations 1-2).

Gating major — hardened startup probe with an unhardened twin
------------------------------------------------------------
config.gitDirsForRepo (internal/config/config.go:419-424) is scrubbed by this
stack, but its byte-identical database-path twin
beads.worktreeFallbackBeadsDirForRepo (internal/beads/beads.go:1054-1058) runs
the same `git -C <repoPath> rev-parse --git-dir --git-common-dir` for the same
purpose and is not. Two claims added in this range asserted the boundary was
universal:

  - docs/reference/worktrees.md:15 "Startup Git discovery probes for every `bd`
    command scrub inherited Git routing variables" (false universal)
  - cmd/bd/worktree_cmd.go:712 "Startup config discovery applies the same
    boundary to its one pre-hook Git probe" (false singular)

Both are narrowed here to name only the plane that is actually scrubbed, and to
state that the `.beads` database-discovery probes still honor inherited routing.

The review offered a code arm (scrub beads.gitOutput,
beads.worktreeFallbackBeadsDirForRepo, and internal/git/gitdir.go:32) as the
alternative. That arm is DECLINED for this leaf, measured rather than assumed:

  - Open sibling PR #6461 already carries it. At refs/pull/6461/head,
    internal/beads/beads.go:293 routes gitOutput through
    gitOutputEnv(gitenv.ScrubRouting(os.Environ())) and :1069 sets
    cmd.Env = gitenv.ScrubRouting(os.Environ()) in the ResolveBeadsDirForRepo
    twin, with internal/beads/{beads,context}_test.go coverage. Our head has
    zero gitenv references under internal/beads (grep control).
  - internal/git/gitdir.go is restructured wholesale by open sibling PR #6464
    (loadGitContext/ResolveHooksContext), which documents "Routing variables are
    honored, not filtered" as a deliberate choice.
  - internal/beads/ and internal/git/ are not among this PR's 47 files, so the
    code arm would rewrite two functions an open, non-ancestor sibling is
    already rewriting in files this PR does not otherwise touch.

The twin is filed as bd-p4che with the failure scenario, the three unhardened
sites, the required decoy test, and the #6461 merge-order note, so the work is
tracked whether or not #6461 lands.

Minor — fork auto-detect gate left on inherited routing
------------------------------------------------------
cmd/bd/init.go:2002 gated the fork auto-detect block on the unscrubbed
isGitRepo() while the same single hunk hardened three setupForkExcludeAt(cwd, …)
call sites around it, and five sibling role gates in this PR already use the
scrubbed isInitRoleGitRepo(ctx). Under the invalid inherited GIT_DIR this PR's
own matrix uses, that gate returns false in a real fork clone and silently
suppresses the whole block — prompt, non-interactive auto-configure, and the
hardened writer at :2007/:2019. Switched to isInitRoleGitRepo(ctx) (same argv,
plus the scrub).

Pinned by a new fork_auto_invalid row in
TestEmbeddedInitSelectedExcludeRouting: it drops --setup-exclude so the exclude
write is reachable only through the gate, adds an upstream remote so the
already-scrubbed detectForkSetup reports a fork, and keeps --role=maintainer so
autoConfigureForkContributor stays an early return and the gate is the only path
that can add the pattern. The row carries the same fixture guard the sibling
role test uses, asserting the inherited probe really is refused.

Mutation-proved: with the gate reverted to isGitRepo() and the row in place,
only fork_auto_invalid fails ("selected exclude = "# owned project
exclude\nkeep-me/\n"; want ... "**/RECOVERY*.md"") while all six incumbent
subtests stay green — so the row adds coverage rather than duplicating an
existing fixture.

Not taken (non-gating, recorded so the next pass grades the call rather than
re-filing it)
----------------------------------------------------------------------------
  - per-key `beads.role` scrub inside the generic accessor
    (internal/storage/domain/git/git.go:110,133): the constructor contract it
    straddles is owned by the parent legs; #6464 also edits this file.
  - splitting gitenv.routingKeys into redirect vs fence sets
    (internal/gitenv/routing.go): the class was filed on the parent PRs and the
    set is shared by the whole family; changing it here would fork a primitive
    five open branches consume.
  - deleting the three zero-caller wrappers in cmd/bd/init_stealth.go:
    cmd/bd/init_stealth.go is concurrently rewritten by open sibling #6461,
    which does not carry this leg's setupStealthModeAt/setupGitExcludeAt split
    (base 566c84ba8 greps 0 for those names; this head greps 5), so deleting
    them here would conflict that rewrite.
    Correction (iteration 2): the earlier reason for this bullet — "the file is
    byte-identical across the open siblings at this head" — does not reproduce
    and is withdrawn. git diff --name-only HEAD refs/adopt/pr6461 --
    cmd/bd/init_stealth.go is NON-empty precisely because this PR created the
    ...At split; byte-identity with a sibling is only obtainable for siblings
    that already carry this leg (empty against refs/adopt-pr-probe/6464). The
    decision stands on the concurrent-rewrite reason above.
  - nit, non-git `bd init` note (cmd/bd/init.go): no code change is owed on the
    merits, which is its own reason rather than the execenv one it previously
    borrowed. commitEmbeddedInitArtifacts (cmd/bd/init.go:3477-3483)
    re-establishes the dropped repo gate as its own SCRUBBED
    `rev-parse --git-dir` probe via initArtifactGitCommand (:3537-3541); only
    the added stderr line is new.
  - nit, unexporting execenv.KeyHasPrefixForOS: internal/execenv/execenv.go is
    byte-identical to both siblings resolvable at this head
    (refs/adopt/pr6461 and refs/adopt-pr-probe/6464 both diff empty), so
    unexporting it here would fork a file they share.
    Correction (iteration 2): the earlier "across all four open siblings"
    quantifier overstated what is measurable — iteration 1's other two probe
    refs no longer exist in this worktree, so the claim is scoped to two.

Iteration 2 (non-gating cleanup; no code, test, or behavior change)
------------------------------------------------------------------
The iteration-2 review found zero blockers and zero majors in this fixup's
delta and the quality scorecard decided approve. All three of its items were
documentation or record-keeping and are discharged here:

  - Contract fidelity nit: the narrowed worktrees.md sentence had fixed WHICH
    PLANE scrubs but kept the original's unconditional frequency ("on every
    `bd` command"), while the probe its appositive names —
    worktreeFallbackConfigPath — runs only under
    `primaryConfigPath == "" && beadsEnvConfigPath == ""`
    (internal/config/config.go:183). Reworded to separate the two: the scrub is
    unconditional FOR THAT PROBE, and the probe itself is a fallback that runs
    only when nothing earlier in startup already resolved a config path, with
    an ancestor .beads/config.yaml or an explicit BEADS_DIR as the
    short-circuits. Stated as a general condition plus examples rather than
    swapping one unconditional claim for another. The review's suggested
    wording cited internal/config/config.go:183; the line number is dropped
    because no file under docs/reference cites Go line numbers (6 Go-path
    mentions across that tree, none with :NNN) and a line citation in a doc
    rots. The file reference is kept so the claim stays checkable.
  - Release-safety minor: bd-p4che's required-fix section now also names the
    two PROSE sites that assert the unhardened state (this worktrees.md
    paragraph and clearWorktreeGitRoutingEnv's doc comment), with a
    drift-proof `git grep "still honor inherited routing"` anchor, because its
    close-out instruction previously named only the three code sites. If #6461
    merges first, it adds the byte-for-byte pre-image of this paragraph at the
    same location, so this fixup's hunk applies CLEANLY and would leave the
    falsified wording behind silently; nothing in CI pins the file (absent from
    scripts/check_doc_freshness_test.go). Only that merge order is silent, and
    the direction is safe either way since stale wording under-claims
    protection.
  - Debuggability nit: the two "Not taken" bullets above are corrected, see the
    inline "Correction (iteration 2)" notes.

Validation
----------
  - git diff --check clean; go build + go vet ./cmd/bd ./internal/config green.
  - 25 blast-radius cmd/bd tests green with BEADS_TEST_EMBEDDED_DOLT=1 and
    BEADS_TEST_REQUIRE_EXCLUDE_PERMISSION=1 (exclude/stealth writers, fork
    auto-detect, init-role and worktree routing), incl.
    TestEmbeddedInitSelectedExcludeRouting 7/7. The one skip
    (TestInitPromptNonGitRepo) is the pre-existing "Dolt test server not
    running" opt-in.
  - An initial run showed 21 reds at 0.00s from a concurrent session sweeping
    the shared /tmp/beads-bd-tests-* root; all pass under an isolated TMPDIR.
  - Iteration 2 touches one Markdown file and no Go source, so the code
    validation above still stands at this tree: git diff --name-only for the
    iteration-2 delta is docs/reference/worktrees.md alone. git diff --check
    clean. worktrees.md is not in scripts/check_doc_freshness_test.go's
    freshnessDocuments and is named by no workflow, Makefile target, or test,
    so no gate covers it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(git): reconcile role-config tests with the preserved read-error contract

Base advanced 11 commits during finalize and #6477 ("preserve config read
errors instead of treating them as absent", cf683435e) landed in the one
package this PR co-edits, internal/storage/domain/git. The rebase was clean
and no production code conflicts, but the two changes falsify each other's
test expectations in opposite directions:

- #6477's invalid_routing_boolean row injects GIT_CONFIG_NOSYSTEM to force a
  beads.role read failure. This PR scrubs routing for beads.role, and
  gitenv.IsRoutingKeyForOS classifies every GIT_CONFIG* key as routing, so the
  injector can no longer reach that read. Retarget the row to test.marker so it
  still proves a routing-induced failure is surfaced rather than swallowed, and
  narrow the BeadsRole propagation assertion to malformed_config, which breaks
  the repository's own config and is therefore immune to the scrub. Add a
  positive pin that beads.role now resolves as absent without error under the
  same poison.

- This PR's captured_home asserted NoError on the strength of "the existing
  reader maps Git exit errors to absence", which is exactly the contract #6477
  removed. Expect the error instead, matching the adjacent assertion that the
  inherited writer fails on the same broken HOME.

#6477's guarantee is unchanged: the merged GetConfig keeps its classification
block and still uses cmd.Output(), which is what populates exitErr.Stderr.
Only this one injector for this one key stopped producing a failure.

internal/storage/domain/git 45/45 pass; removing the scrub from GetConfig makes
the new pin fail, so it is non-vacuous. cmd/bd blast radius 28/28 pass with
BEADS_TEST_EMBEDDED_DOLT=1, covering all six base-added init/temp-root tests.

---------

Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-27 15:13:36 -07:00
..
architecture fix(gc): flatten/compact run full GC after the rewrite; bd gc --full; low-reclaim hint (#5907) (#6057) 2026-08-29 05:19:06 +00:00
cli-reference docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
core-concepts docs: supersedes is a replacement link, not a version chain (#6212) 2026-09-12 06:41:33 -07:00
diagrams docs: port the Excalidraw diagram pipeline (machinery only) 2026-07-12 10:37:17 -07:00
getting-started fix(notion): keep notion.token out of the Dolt database (#6676) (#6724) 2026-09-27 14:53:11 -07:00
images docs: port user docs into the Mintlify site tree under docs/ 2026-07-12 10:37:07 -07:00
integrations docs: document ado.reconcile_interval and inventory every storage span 2026-08-07 21:20:41 +00:00
multi-agent fix(reclaim): correct the heartbeat re-home invariant's scope in the new docs (wy-sp2l4) 2026-08-13 04:30:30 -07:00
recovery docs(recovery): init-safety re-clone playbook covers damaged-store and fresh-clone gotchas (#6431) 2026-09-27 03:41:05 -07:00
reference fix(init): write embedded excludes in the selected project (#6462) 2026-09-27 15:13:36 -07:00
workflows docs(gates): document multi-rig/proxied gate limitations for 1.3.0 (#6052) 2026-08-28 23:23:15 -07:00
cli-docs.pin chore(release): forward-port v1.2.2 to main (version record, retracts, recovery guide, gate record) (#5782) 2026-08-14 21:45:02 -07:00
CLI_REFERENCE.md docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
community-tools.md docs: add Maggie to community tools (#6446) 2026-09-26 19:12:59 -07:00
docs.json chore(release): forward-port v1.2.2 to main (version record, retracts, recovery guide, gate record) (#5782) 2026-08-14 21:45:02 -07:00
index.md release: prep v1.3.0 — version bump, changelog rollup, release process docs, formula fixes (#6038) 2026-08-30 22:19:35 -07:00
RECOVERY.md docs(recovery): reduce the stub to a pure pointer 2026-07-17 18:56:33 -07:00
related-projects.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00