📝 docs: two false claims about what assent writes — --arm and REVIEW auto-merge (D-134/D-135, blocks v0.2.0)

[konih]

P1 blocking the v0.2.0 tag — documentation only, zero behaviour change

assent approves and merges other people's merge requests. The --arm flag's help
string and the published CLI reference promised approve/merge happens "only when set
and the decision is APPROVE." That has been false since c05cde0 (E4-S06, 2026-08-04),
which replaced Preconditions{ArmEligible: cfg.arm} with the forge-probed
armEligible and updated buildDesired's own comment but nothing else —
git show c05cde0 -- cmd/assent/run.go | grep BoolVar returns nothing.

The default is false, so every run that never passes --arm was in the state the
help string described as safe. The unsafe path needs no operator error: follow
walkthrough.md, copy its CI snippet (which omits --arm), harden the project until
assent doctor reports the precondition MET, and the pipeline begins approving and
merging while cli.md says it will not. cli.md ships with the release, so
re-publishing it under a new tag is a knowing act.

Measured, not transcribed

Through the production entry point runRun against the repo's own fakeGitLab:

fixture	args	exit	approvals	merges	summary
probe-eligible APPROVE	[]	0	1	1	decision=APPROVE arm=false → 3 forge operation(s) written
probe-eligible APPROVE	[--arm=false]	0	1	1	byte-identical
probe-eligible APPROVE	[--arm=true]	0	1	1	decision=APPROVE arm=true → 3 forge operation(s) written
probe-ineligible (C3 gate absent)	[--arm]	0	0	0	… → advisory-only (arming precondition unmet, no approve/merge)
probe-ineligible (C3 gate absent)	[]	0	0	0	same
.assent/** self-edit	[]	0	0	0	decision=BLOCK → assent-policy self-edit, no forge writes (fail-closed)

What is NOT changed

The engine behaviour is correct and intentional (D-074/D-078, REQ-E4-S06-05) and is
pinned by TestRunForgeProbedArmingGatesWrites, which passes no --arm and asserts the
writes happen. Making --arm gate writes, or removing it, are post-tag follow-ups needing
an openspec change proposal and their own red tests.

Surfaces corrected

• cmd/assent/run.go:136 — flag help: advisory only, points at assent doctor
• cmd/assent/run.go:86 — runRun exit-code comment
• cmd/assent/provider_host.go:34 and :102 — a repo-wide sweep found a second
  copy of "ArmEligible stays --arm ∧ APPROVE", outside the reported finding
• docs/usage/cli.md — flag row + exit-codes paragraph, plus a new
  What gates approve and merge section naming the three default-deny preconditions
  (C17 / C3 / C6-C7), their typed refusal codes, the four further guards, and how to
  actually stay advisory
• docs/usage/walkthrough.md — its CI snippet already omits --arm and no prose
  reintroduces that claim, but Step 6 carried a different false claim, now also fixed
  here as D-135 — see below

The flag help carries no backquotes on purpose: flag.PrintDefaults reads ` as the
value-name placeholder, and a first draft rendered as -arm assent doctor.

D-134 supersedes D-041

D-041 stays byte-identical (verified against origin/main); the diff to
decisions.md adds exactly one line. D-134 retracts D-041's live-forge claim
"unarmed APPROVE → advisory-only, zero writes" and states that it was true when
recorded — git merge-base --is-ancestor 4addc3d c05cde0 confirms its evidence commit
precedes the one that invalidated it.

ARM-04 closed

cfg.arm had zero discriminating coverage — verified, not accepted: on the pristine
tree, mutating summarize(result.Decision, cfg.arm, …) to summarize(…, true, …) at
run.go:447 leaves the whole cmd/assent package ok. TestRunArmFlagIsAdvisoryOnly
pins the arm=<bool> token — the flag's only remaining observable effect — in both
polarities, plus the advisory semantics itself (write outcome and rest of summary
identical with and without the flag). Mutation-proven each direction:

• …, true, … → reds without_flag_reports_arm_false + flag_changes_nothing_but_the_token
• …, false, … → reds with_flag_reports_arm_true

Deliberately not red-first: cfg.arm was already threaded to summarize, so there was no
implementation to add; mutation-kill is the honest form of the TDD obligation here, and
the test's doc comment says so.

Gates

task check exit 0, all 14 stages: fmt · vet · lint · test · coverage · build ·
dogfood-comparison · compare-exitgate-test · changelog-verify · release-changelog-gate-test ·
release-verify-tag-gate-test · docs-gates · lint-depguard-test · lint-workflow-pins-test.
Plus go vet -tags e2e ./... clean. No docs truth-lag pin was keyed to the old wording.

Second defect, ALSO fixed here (D-135) — operator override

walkthrough.md:149 claimed that on the REVIEW path "assent had already armed the forge's
auto-merge… the moment the last thread is resolved, GitLab itself merges (ADR-0009
amendment)." This is implementation-vs-design drift, not a transcription slip: ADR-0009's
challenge-resolution amendment really does specify "approves conditionally and arms forge
auto-merge pinned to the evaluated SHA". The mechanism was never built.

Verified three independent ways:

• buildDesired's REVIEW/BLOCK branch sets desired.Thread only and returns a zero
  forge.Preconditions{} — no Approve, no Merge, no ArmEligible.
• The forge.Forge port has no deferred-merge verb at all. Approve and MergeCAS are
  the only write verbs and MergeCAS issues an immediate PUT /merge?sha=. A grep for
  merge_when / auto_merge / when_pipeline across internal/ + cmd/ returns nothing
  but AutoMergeEligible — a doctor-report field never consulted for arming.
• Thread.Resolved is read only inside internal/forge's thread-idempotence logic, never by
  internal/core. Thread resolution is not evidence and cannot move a decision.

Measured through runRun against fakeGitLab, replaying the walkthrough's own narrative:

step	exit	threads	notesPosted	notesUpdated	approvals	merges	decision
run 1	0	1	1	0	0	0	REVIEW
contributor resolves every thread
run 2	0	1	1	1	0	0	REVIEW (unchanged)

The MR never merges. Rerun idempotence holds — no duplicate thread; the summary comment is
updated in place.

Direction of the error, which differs from the --arm one: this over-states
automation, so its risk direction is fail-safe — no unintended write can follow from it.
It is nonetheless false rather than merely optimistic: the mechanism is absent from the
codebase, and the failure mode is someone waiting indefinitely for a merge that will never
arrive with no diagnostic saying why. Same defect class as D-134 (a false claim about tool
behaviour in docs that ship with the release), so tag-blocking on the same reasoning.

Step 6's prose now states the measured behaviour, its > **Shipped** banner (kept for the
DOC-09 pin) names the unimplemented arming as an explicit exception, and a What this means
in practice callout closes the operator loop.

ADR-0009 — annotated, NOT decided. The ADR ships with the docs site (mkdocs.yml nav
carries ADRs: adr/README.md, whose index links every ADR page), so it was a published
document specifying a mechanism the tool does not have. Its Amendment now carries an
Implementation status note recording that point 1's deferred forge auto-merge is
unimplemented, citing D-135, with the three code facts and the measurement — and naming the
two honest resolutions as open options without picking one: (a) build the deferred arming
(GitLab C11), or (b) retract the amendment and re-derive the challenge-resolution story around
the immediate merge that exists. The amendment's normative text is untouched and the
decision stays open — recording that a specified mechanism is unbuilt is a verifiable fact
(AGENTS.md rule 6); choosing what to do about it is the architecture decision and remains the
operator's. D-135 and the ADR note link to each other in both directions.

Placed in the amendment body, not the Status row — by choice, not constraint. Probed
empirically: appending to Status and re-running truthlag_pins_test.sh still gives
PASS ADR index: 20 ADR status rows agree with their files, because the pin compares only the
first whitespace token of the Status cell. Status is nonetheless the wrong home — it is the
ADR lifecycle field the index renders, an implementation gap is a different axis, and trailing
free-text there would never surface on the index page a reader scans.

Third-surface sweep

Because the D-135 fix makes the word "armed" load-bearing, I swept every user-facing
surface for a deferred-arming promise: merge when / when pipeline / pipeline succeeds
/ forge merges / GitLab itself / when every thread over docs/, README.md, cmd/.
None found. Every product-doc and CLI use of "arm"/"auto-merge" maps to assent's own
ArmEligible — permission to perform the immediate approve+merge, which does exist.
assent doctor prints arming precondition MET — forge-probed, auto-merge may be armed /
advisory-only — auto-merge NOT armed; README, docs/index.md and docs/vision.md use
"auto-merge" as the product category. The only surviving deferred-arming text is ADR-0009's
amendment (left to its own amendment) and the two docs/planning/forge-dossier-*.md research
notes, which are out of the mkdocs nav per GUIDELINES and correctly describe what the forge
can do (GitLab C11).

No further defect — but one sentence was added to cli.md's assent doctor section, a
surface this lane already edited, saying which arming is meant. The doctor synopsis line
is deliberately untouched: it is pinned verbatim by TestCLIDocCoversSubcommands against
main.go's dispatch table, so rewording it would be a CLI change, not a docs change.

Review round 2 — REQUEST CHANGES addressed

ARM-08 (P1, introduced by my own diff). The "stay advisory" advice I added recommended
phase: observe. False in the unsafe direction, twice. Both re-measured myself:

(i) Structural exclusion removes the findings that were withholding approval.
CoverWithPhaseCeiling over an enforcing BLOCK rule:

binding	enforce	observe	off
require: [signal]	BLOCK	REVIEW	REVIEW
(no require:)	BLOCK	APPROVE	APPROVE

Only an enforce-phase rule marks a required obligation covered (coverage.go:150), so the
binding's require: list is the only thing holding the line — and require is optional in
the frozen schema ("Absent or empty ⇒ vacuously covered"), which is exactly the first-pack
rollout state the advice targeted.

(ii) spec.phase is inert unless --pack is passed (run.go:247). Against a fake serving
no pack route: without --pack → exit=0 approvals=1 merges=1 (proving no pack is read);
with --pack → the read happens and fails loudly. Edit the manifest, change nothing else,
stay fully enforcing — ARM-01's shape, reintroduced by ARM-01's fix.

Replaced with the measured truth, published as a matrix rather than a summary: no dry-run
mode exists (assent run --dry-run exits 2, flag provided but not defined: -dry-run,
verified on the built binary), no phase is a safety switch (off approves too), and the only
reliable lever is leaving one of the three arming preconditions unmet.

SURF-07 (P2). ADR-0009's mode table specifies six entrypoints; only run exists —
explain, serve, scan, stats all exit 2 against the shipped dispatch table. Annotated
with the same restraint as the amendment (fact recorded, normative text untouched, options
named, neither picked), following the walkthrough's "Planned — assent explain does not exist"
precedent. This is ARM-08's root cause: the sanctioned advisory mechanism was never built,
so the docs substituted one, and the substitute was unsafe.

ADR9-ST (P3). Status row extended to Substantially unimplemented as of 2026-08-09 so an
index reader sees the gap. Free, as proved earlier — the pin reads only the first token.

SURF-09 (P3). The p4-e1-s11 evidence README keeps its historical text verbatim and
gains a note that --arm semantics changed at c05cde0, pointing at D-134.

D135-CAL (P3). Corrected my own overstatement: D-135 claimed the walkthrough defect was
"tag-blocking on the same reasoning" as D-134. Same class, not same reasoning — ARM-01 blocked
because it ran unsafe on the primary surface; this one over-states automation and fails
loudly and recoverably. Standing alone it is P2, and the row now says so.

SURF-08 → OQ-29 (recorded, NOT fixed). PolicyProfile.spec.writes: false is documented as
an architectural invariant (writes:false "Never calls Reconcile") with zero runtime
enforcement — cmd/assent/run.go contains the string Profile zero times and evaluates via
CoverWithPhaseCeiling; ResolveProfile/WriteAllowed have non-test consumers only in
internal/lint; LoadProfile only in compare.go. Meanwhile writes is a required
frozen-schema field and the single-writer-profile lint hard error compels adopters to author
it. Logged as OQ-29 for an operator ruling; schema and lint rule untouched.

Merge of origin/main (#36 landed). Only CHANGELOG.md conflicted. Both append-only
tables auto-merged with nothing lost — decisions.md 129 rows on each parent → 131 merged,
no D-id missing from either side; same for OQ. The merge commit's subject is
:wrench: chore(release): on purpose: cliff.toml skips exactly that, and anything else falls
through to the .* catch-all and renders a merge subject into the changelog (D-125). Verified
this lane's merge subject does not appear in CHANGELOG.md. Pre-existing, not mine: two
unskipped merge subjects from lane/fix-provider-symlink-containment did land at
CHANGELOG.md:184-185 via #36, alongside older ones — same D-125 trap, flagged for the
coordinator.

Review round 3 — ADV-01

The advisory section opened with "There is no dry-run mode today" but never said the run
still comments on the merge request. Measured through runRun with the C3 gate absent — the
state the section recommends:

scenario	threads	notesPosted	approvals	merges
APPROVE	0	1	0	0
REVIEW	1	1	0	0
BLOCK (ordinary effect: block)	1	1	0	0
BLOCK (.assent/** self-edit)	0	0	0	0

forge.Reconcile posts the summary comment before the arming branch is reached, so it lands
on every path except the self-edit guard.

The suggested parenthetical — "(and, on REVIEW/BLOCK, one resolvable thread)" — holds for
REVIEW and for an ordinary block effect, but not for the .assent/** self-edit BLOCK,
which writes nothing at all. Every run-path BLOCK fixture in the suite happens to be that
guard, so an ordinary effect: block policy was authored to measure the other half honestly.
The exception is named rather than omitted — this page has already shipped two false safety
instructions, so a claim with a known counterexample is not worth the brevity.

Landed, three sentences, in the advisory section:

"Advisory" means no approve and no merge — not no writes. The run still posts its
summary comment to the merge request, and on REVIEW or BLOCK one resolvable thread as well.
The only path that writes nothing at all is a self-modifying .assent/** merge request,
which fails closed for a separate reason.

Scope held: the advisory definition is not restated beyond the clause itself, the phase matrix
is untouched, and cliff.toml is left alone for lane/cliff-skip-merge-commits (CL-01).

Disclosure

Every commit on this lane used git -c core.hooksPath=/dev/null. Per D-125 the changelog
must be the last commit, so changelog-verify (stage 9 of 14) is red by construction on
every intermediate commit and a per-commit task check is unreachable. The gate matrix was
run green on the final tree seven times, most recently after the ADV-01 clause, with both
GOLANGCI_LINT_CACHE and GOCACHE isolated.