Skip to content

docs(walkthrough): add §5.2 comparing none / warn / exclusive policies#25

Merged
albertgwo merged 1 commit into
mainfrom
docs/policy-comparison
May 12, 2026
Merged

docs(walkthrough): add §5.2 comparing none / warn / exclusive policies#25
albertgwo merged 1 commit into
mainfrom
docs/policy-comparison

Conversation

@albertgwo
Copy link
Copy Markdown
Contributor

Purpose

Give operators an explicit decision table for --policy (none, warn, exclusive) so downstream projects do not invent their own avoidance guidance. The assign update PR (#24) surfaced a recurring failure mode: a downstream AGENTS.md steered workers away from exclusive on race grounds, but the race in question was closed by v0.1.2's BEGIN IMMEDIATE transaction. Without a kernel-side comparison, each consumer reverse-engineers policy semantics from SPEC §15 and §28 separately, and stale guidance persists across consumer repos.

Summary of changes

  • New docs/walkthrough.md §5.2 "Choosing a conflict policy" with a per-policy table covering overlap detection, outcome, lock sentinel, and an operator-facing "when to use" column.
  • Explicit note that all three policies are race-safe under concurrent writers since v0.1.2, with a code citation (internal/domain/domain.go ResolveAndInsertIntent) and a pointer to the tests/integration/concurrent_test.go suite that keeps the guarantee honest under -race.
  • Explicit call-out for downstream projects whose AGENTS.md still avoids exclusive on race grounds: verify the installed agent-ledger --version is at least v0.1.2 and update local guidance.
  • Note that the <ledger-dir>/locks/<path-hash>.lock sentinel is advisory (DB row is authoritative per SPEC §28) and is housekeeping for the verifier, not a public API.

Changes to review

  • docs/walkthrough.md §5.2: confirm the table's "when to use" column matches how you actually want operators to choose between the three policies.
  • Race-safety claim: the section cites v0.1.2 (2026-04-28) as the cut-over. Confirm that v0.1.2 is the canonical version to name (vs. v0.1.0 or a later patch).
  • Tone: the section is direct about stale operator guidance. Confirm the framing is appropriate for the project's voice; soften if it reads too prescriptive for a walkthrough document.

@albertgwo albertgwo merged commit 3c454f3 into main May 12, 2026
7 checks passed
@albertgwo albertgwo deleted the docs/policy-comparison branch May 12, 2026 13:43
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