Skip to content

docs(engineer): document the .simard-engineer-claim two-layer exclusion (#2621)#2646

Merged
rysweet merged 1 commit into
mainfrom
docs/issue-2621-claim-sentinel-exclusion
Jul 6, 2026
Merged

docs(engineer): document the .simard-engineer-claim two-layer exclusion (#2621)#2646
rysweet merged 1 commit into
mainfrom
docs/issue-2621-claim-sentinel-exclusion

Conversation

@rysweet

@rysweet rysweet commented Jul 6, 2026

Copy link
Copy Markdown
Owner

Summary

Docs-only follow-up to the merged fix for #2621 (delivered by #2623, commit 2c32fe65).

Adds docs/reference/engineer-claim-sentinel-exclusion.md, a reference page that documents the two-layer defense keeping Simard's private per-worktree liveness sentinel (.simard-engineer-claim) from ever registering as an uncommitted change — so the engineer-loop pre-mutation guard cannot trip on it in a target repo that does not gitignore the file.

What it documents

  • The deadlock — how a single ?? .simard-engineer-claim untracked entry made worktree_dirty == true, aborting every mutating engineer with DirtyWorktree before the agent spawned, and driving the infinite re-dispatch loop.
  • Layer 1 (creation-time)exclude_engineer_claim() appends a root-anchored /.simard-engineer-claim to the worktree's info/exclude (resolved via git rev-parse --git-path, idempotent, lock-guarded, non-fatal on failure).
  • Layer 2 (read-time)strip_claim_sentinel() drops the exact-root sentinel from every git status consumer (inspect_workspace, verify_agent_spawn_artifacts) before worktree_dirty is computed.
  • The ENGINEER_CLAIM_FILE single-source-of-truth constant, security properties, and the pinning regression tests in tests_claim_sentinel.rs / tests_extra.rs.

Scope

  • Additive/surgical: one new reference page + one mkdocs.yml nav entry.
  • No code change. No new println!/eprintln!. No "Bridge" names.
  • mkdocs build --strict passes locally (no broken links / nav warnings).
  • Every symbol, test name, and cross-link in the page was verified against the merged source.

Refs #2621.

…on (#2621)

Add a reference page describing the two-layer defense merged in #2623 that
keeps the private per-worktree liveness sentinel (.simard-engineer-claim)
from ever registering as an uncommitted change, so the engineer-loop
pre-mutation guard cannot trip on it in a target repo that does not
gitignore it:

- Layer 1 (creation-time): exclude_engineer_claim() appends a root-anchored
  /.simard-engineer-claim to the worktree info/exclude.
- Layer 2 (read-time): strip_claim_sentinel() drops the exact-root sentinel
  from every git-status consumer before worktree_dirty is computed.

Documents the constant, both layers, security properties, and the pinning
regression tests. Adds the page to the mkdocs nav. Docs-only; no code change.

Refs #2621.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@rysweet rysweet merged commit b20cb12 into main Jul 6, 2026
16 checks passed
@rysweet rysweet deleted the docs/issue-2621-claim-sentinel-exclusion branch July 6, 2026 05:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant