describe loop and its fences: within-run abort, actionKey read gate, quoted {page} (Session B: DB-1..DB-4, plugin 0.39.0)

[BradleyDB]

Base branch: dev. Regenerated output: npm run build at the pinned CLI reproduces the committed generated set byte-for-byte (the catalog's wall-clock generatedAt stamp was restored — it moves only on a CLI adoption).

What

Session B of the September rounds (handoff plan items DB-1..DB-4): the describe loop and its fences. Plugin 0.39.0.

• DB-1 · issue capture.mjs --paginate fences spell {page} unquoted — PowerShell eats it #10 — every capture.mjs --paginate fence in the skills quotes its --out value (nine fences, five skills; the one --page-flag none fence quoted for uniformity). The setup canon states the reason beside the fence; capture.mjs's refusal for a missing {page} now names the shell cause; check-doc-drift check 14 holds every paginate fence's {page} --out quoted (mutant 14j). Closes capture.mjs --paginate fences spell {page} unquoted — PowerShell eats it #10.
• DB-2 · F-456 — the read-only gate's describe-shape predicate is one exported function, doc-lib isDescribeRead(verb, cmd): a describe-shaped catalog actionKey admits on its own merits, the path's trailing word admits as before (describe shape or READ_VERB_EXACT), a hand-trimmed catalog decides on the word alone. describe-batch.mjs and capture.mjs both compose it, so cn chain (describe-job-chain) and the sibling the finding did not list, re r execution (describe-execution), are describable and capturable through both sanctioned routes. A committed sweep over the shipped catalog pins the admitted set at the pin (25 commands) so a future refusal is named at adoption time.
• DB-3 · issue describe-batch: abort a domain after 5 consecutive retryable failures #13 — describe-batch.mjs aborts a domain after five consecutive failed marks (a constant, not a flag), leaving every mark exactly as written. Closes describe-batch: abort a domain after 5 consecutive retryable failures #13.
• DB-4 · F-458 — a FAILED spawn carrying the CLI's own re-login sentence (all four auth-path throws in dist/core/auth/index.js at 1.0.9 end with it; doc-lib isAuthDeath, version-stamped as a stale-facts tripwire) aborts on the first sighting with nothing marked: the in-flight entry keeps its status, a designer entry keeps its composite with the item pending, and the next invocation resumes as after a budget cut.
• Both stops are reported as ONE additive summary field, aborted: { reason: "consecutive-failures" | "auth", after, lastError }, absent on a run that did not stop early; budgetExhausted, moreRemaining and failures keep their shapes and meanings (the setup skill branches on them — contract). Setup Phase 5's stop rule names the within-run limit and both reasons; batch sizing names the nearer of the shell timeout and the token's usable life and says to size against the slow end of observed rates; the manual per-asset path and the designer-lane reference carry the same auth exception.

Why

Purpose and value per item (from the handoff plan, ranked by new-user deterrence):

• DB-1 — the first Phase 4 command a Windows newcomer runs failed: Windows PowerShell 5.1 consumes an unquoted {page} (measured: argv arrives as …-). Rank 1; good first issue capture.mjs --paginate fences spell {page} unquoted — PowerShell eats it #10.
• DB-2 — a catalog-declared per-item read was refused by both sanctioned capture paths, leaving no legal route to document the connectors-chains lane (F-456, third note). Rank 3; every tenant with connectors has this lane.
• DB-3 / DB-4 — a dead token or a wrong describeCommand spawned through the whole asset list, and a deadline-ended batch wrote failed onto healthy assets (17 on one live run, the auth error as their reason). Rank 2; routine for any ingest longer than a token's usable life.

Design rulings (Bradley, 2026-09-14, recorded in the bus Fix notes): auth aborts on first sighting with no mark; one aborted object with a reason enum; failed-spawn AND phrase (a successful describe is never reclassified by its stderr); all four re-login literals via the shared sentence; the limit a constant of 5.

Review notes

• Fixtures landed before the fix and were red on the unfixed scripts (the designer auth arm reproduced F-458 exactly: the entry marked failed with the re-login literal). test/describe-batch.mjs (+29 arms: gate, catalog sweep, every-describe-fails stops at exactly 5 spawns counted from the fake's own log, F F F F S runs to completion, F F F F F S stops at 5, resume after abort, auth after two successes, the three sibling literals, four failures then auth, exit-0-with-phrase stays a success, designer per-entry counting, drilldown and template-spawn auth deaths, --upgrade progress freshness), test/capture.mjs (+2), test/doc-lib-fixtures.mjs (+16 predicate arms), build/test-check-doc-drift.mjs (+14j), build/test-check-stale-facts.mjs (carrier stub).

• The PowerShell 5.1 judge for DB-1 was run for real on this machine: the unquoted audit fence is refused by capture ("needs a literal {page} placeholder"), the quoted fence writes three page files and reconciles.

• /code-review medium: 8 findings, all fixed (the prose overstatement of "nothing marked", a stale domainProgress snapshot at an abort, an inconsistent designer per-entry counter, the designer-lane reference, MAINTAINERS' row, a header splice, the auth classifier's home, the fake's silent no-op). Dismissed with reasons in the F-458 Fix note.

• Verbatim battery from validate-plugin.yml and docs-drift.yml: 0 failures locally; both claude plugin validate … --strict pass; npm run build reproduces the committed output.

• Banked live arms (dev/VALIDATION.md, Session B, for the tester round on the minted token): (1) F-456 — deep-ingest of the connectors-chains lane through the RECORDED describe with no --command, no manual fallback, no --normalize, plus one chain through the capture helper; (2) F-458 / describe-batch: abort a domain after 5 consecutive retryable failures #13 — one describe-batch run PAST the token half-life from a terminal, reading aborted.reason: "auth" with failures: [] in the summary and zero auth-failed entries in the manifest, then a resume after gs-admin login; optionally describe-batch: abort a domain after 5 consecutive retryable failures #13 live on a small domain with a mismatched describe (stops after exactly 5 spawns).

• Version collision to watch: draft PR change-request: a Before-building read, and the admin's job in the operating model (plugin 0.39.0) #17 also stages 0.39.0; whichever merges second rebases its bump and CHANGELOG entry.

• Plugin version bumped in .claude-plugin/plugin.json with a CHANGELOG entry (user-visible plugin change).

• Safety boundary: this PR does not touch hooks/gs-admin-guard.mjs or ask-rules generation. The read-only gate's admit set widened by exactly two catalog describe actions, both non-mutating GET reads; the endpoint gate is unchanged and pinned independent of the admit.

• Skill edits: cross-document consistency checked (operating model, managed CLAUDE.md block, cheatsheet renderer — none states the batch summary or the fence quoting; setup, its two references, MAINTAINERS and the CHANGELOG agree), and the changed skills are walked in the tester round (Session B-V): setup (slash-only, the user types it); the fence-only edits in audit, deprecate, email-report, refresh. Session / verdict: B-V, pending.

• No test or dev step touched real gs-admin state (~/.gs-admin/, live tenants) — fixtures only; the PowerShell judge ran a scratch fake CLI.

• No tenant/instance/org-specific data in commit messages or this PR body.