From b26fc551bea30a9d5fc843052bbd0f77b092e885 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Mon, 27 Jul 2026 19:25:40 +0100 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20settle=20the=20itd-101=E2=80=93104?= =?UTF-8?q?=20grills=20into=20the=20intents?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Six maintainer decisions from the 2026-07-27 grill written into the four drafts as acceptance criteria, remaining open questions, and a Grill Settlements section each; DECISIONS carries the roll-up. All four are now plan-ready drafts under the itd-1 discipline. Assisted-by: Claude:claude-fable-5 --- ...cd-publishes-is-provably-alive-and-honestly.md | 15 +++++++++++++-- ...e-same-thing-about-itself-everywhere-becaus.md | 13 +++++++++++-- ...o-agents-the-shell-commands-they-must-never.md | 13 +++++++++++-- ...idea-before-it-becomes-a-record-entry-resea.md | 13 +++++++++++-- .abcd/work/DECISIONS.md | 1 + 5 files changed, 47 insertions(+), 8 deletions(-) diff --git a/.abcd/development/intents/drafts/itd-101-every-citation-abcd-publishes-is-provably-alive-and-honestly.md b/.abcd/development/intents/drafts/itd-101-every-citation-abcd-publishes-is-provably-alive-and-honestly.md index 72d0038..6d4be28 100644 --- a/.abcd/development/intents/drafts/itd-101-every-citation-abcd-publishes-is-provably-alive-and-honestly.md +++ b/.abcd/development/intents/drafts/itd-101-every-citation-abcd-publishes-is-provably-alive-and-honestly.md @@ -22,11 +22,22 @@ impact: additive ## Acceptance Criteria -> _Required (the itd-1 discipline): add at least one Given-When-Then bullet describing the verifiable bar for "shipped" before this draft can be planned._ +- Given `abcd docs lint` runs in the commit gate, when the citations family evaluates, then it uses zero network: footnote structure (marker-definition bijection, and every crosswalk table row carrying at least one footnote), URL/DOI syntax, and source-domain policy come from committed config and the committed baseline. +- Given `abcd docs cite refresh` runs, when it writes the baseline, then each URL entry records the final resolved address, when it was checked, and whether verification was automatic or manual (with its date) — never how. +- Given a baseline entry older than 180 days, when docs lint runs, then it warns; given one older than 365 days, when the release gate runs, then it blocks; human-verified entries age on the same clock and re-enter the manual queue when stale. +- Given a source that blocks automated fetchers, when the maintainer clears the manual queue, then a printed checklist plus a confirm verb writes the dated receipt; the later generated checklist page hands back a receipt file the same verb ingests — one receipt schema for both rungs. +- Given a specialist link checker is adopted later, then it slots behind the refresh seam as an adapter without changing gate semantics — internal basic first, SOTA dependency later. ## Open Questions -_None recorded yet._ +- The generated checklist page's receipt-file format details (settled only as: same schema as the confirm verb writes). +- Where the scheduled-CI refresh wrapper lands when it earns its own sign-off (explicitly out of this intent's scope, per the 2026-07-27 grill). + +## Grill Settlements (2026-07-27) + +- Refresh is manual now, surfaced by ahoy status and release-preflight nagging; a scheduled-CI wrapper is a later, separately signed-off change. +- Staleness policy: warn at 180 days in docs lint; blocker at 365 days at the release gate only — commits are never calendar-blocked. +- The row-has-footnote structural rule deferred from spc-15 is homed here (DECISIONS 2026-07-27): implemented in this intent or not at all. ## Audit Notes diff --git a/.abcd/development/intents/drafts/itd-102-your-repo-says-the-same-thing-about-itself-everywhere-becaus.md b/.abcd/development/intents/drafts/itd-102-your-repo-says-the-same-thing-about-itself-everywhere-becaus.md index 424028e..100f758 100644 --- a/.abcd/development/intents/drafts/itd-102-your-repo-says-the-same-thing-about-itself-everywhere-becaus.md +++ b/.abcd/development/intents/drafts/itd-102-your-repo-says-the-same-thing-about-itself-everywhere-becaus.md @@ -22,11 +22,20 @@ impact: additive ## Acceptance Criteria -> _Required (the itd-1 discipline): add at least one Given-When-Then bullet describing the verifiable bar for "shipped" before this draft can be planned._ +- Given repo onboarding runs (the install or prepare flow), when the identity interview completes, then title, tagline, and pitch land in a parseable markdown identity block (fixed bullet shape) whose location the repo's abcd config records — markdown stays the single source of truth. +- Given a rendered surface (README strapline, manifest description, conventions-file opening) diverges from the identity block, when the positioning check runs, then a warn-tier finding names the exact drifted line; per-repo config may upgrade the finding to blocker. +- Given drift is found, then abcd never rewrites a surface autonomously — re-rendering from the block is always a proposed diff a human adopts. +- Given abcd-cli itself, then the check points at the brief product chapter's existing Identity section unchanged, and iss-143 (the three-variant drift) is the acceptance corpus the check must catch. ## Open Questions -_None recorded yet._ +- Interview wording and which surfaces are registered for checking by default beyond the canonical three. +- Whether the pitch is required or optional at onboarding (title and tagline are required). + +## Grill Settlements (2026-07-27) + +- Identity home is a parseable markdown block, not a structured JSON file — consistent with markdown-as-single-source-of-truth; the config records only where the block lives. +- The check is warn-tier by default (highlight, never gate) and per-repo upgradeable; autonomous rewriting is permanently out. ## Audit Notes diff --git a/.abcd/development/intents/drafts/itd-103-abcd-teaches-repo-agents-the-shell-commands-they-must-never.md b/.abcd/development/intents/drafts/itd-103-abcd-teaches-repo-agents-the-shell-commands-they-must-never.md index cae4ed8..ea3e42a 100644 --- a/.abcd/development/intents/drafts/itd-103-abcd-teaches-repo-agents-the-shell-commands-they-must-never.md +++ b/.abcd/development/intents/drafts/itd-103-abcd-teaches-repo-agents-the-shell-commands-they-must-never.md @@ -22,11 +22,20 @@ impact: additive ## Acceptance Criteria -> _Required (the itd-1 discipline): add at least one Given-When-Then bullet describing the verifiable bar for "shipped" before this draft can be planned._ +- Given the guard hook cannot execute the abcd binary, when any command runs, then the guard fails OPEN with an unmissable in-session warning, and guard health is reported by ahoy status — never a silent no-op, never a bricked session. +- Given a command matches a blocker-tier registry entry, then it is refused with the safe successor as the block message; warn-tier matches pass with the warning injected; no in-session override exists — the only escape is a committed per-repo config override. +- Given a hazard pattern appears inside a quoted string argument (for example a ledger capture whose text mentions a dangerous command), when the guard evaluates, then it does not fire: matching is shell-token-aware and applies in command position only, including cd-chain structure across compound separators. +- Given a registry entry is proposed for the bundled defaults, then it ships with known-bad and known-good fixtures (known-good at least 40% of its corpus) and clears a declared true-negative-rate floor before admission; string payloads inside eval or shell -c are a documented v1 gap, not a silent one. ## Open Questions -_None recorded yet._ +- The registry config's file home (extend rules.json with a guard domain vs a dedicated committed file) — a spec-time decision. +- Which non-shell tool calls (if any) the guard family later covers. + +## Grill Settlements (2026-07-27) + +- Fail-open-loud on guard breakage; blocker/warn tiers mirror the docs-lint family; overrides are committed and reviewable only. +- Shell-token-aware matching in command position was chosen precisely because a raw-regex guard would have blocked this repo's own incident-capture command — the known-good corpus is not optional. ## Audit Notes diff --git a/.abcd/development/intents/drafts/itd-104-abcd-gates-a-new-idea-before-it-becomes-a-record-entry-resea.md b/.abcd/development/intents/drafts/itd-104-abcd-gates-a-new-idea-before-it-becomes-a-record-entry-resea.md index 290210b..abd2f3f 100644 --- a/.abcd/development/intents/drafts/itd-104-abcd-gates-a-new-idea-before-it-becomes-a-record-entry-resea.md +++ b/.abcd/development/intents/drafts/itd-104-abcd-gates-a-new-idea-before-it-becomes-a-record-entry-resea.md @@ -22,11 +22,20 @@ impact: additive ## Acceptance Criteria -> _Required (the itd-1 discipline): add at least one Given-When-Then bullet describing the verifiable bar for "shipped" before this draft can be planned._ +- Given a one-line idea, when the user runs the intent or capture verb, then no ideate step is required or suggested as blocking — ideate is an optional verb, never a pre-capture gate; the routing help names it for big, unproven ideas. +- Given /abcd:ideate runs, then it executes three legs in order: primary-source research (every load-bearing claim checked against its primary), a record grill (does the brief, an intent, an ADR, or a principle already cover, contradict, or supersede this?), and an adversarial review that is fresh-context and off-policy — conducted by a session that did not do the research, receiving the idea as an artefact of unknown authorship. +- Given a verdict, then the decision is recorded with rejected alternatives whether the idea survives or dies; only a surviving idea graduates to a draft intent. +- Given the record grill leg runs, then a hit on an existing record entry (covered, contradicted, or superseded) is cited by id in the verdict — the check-the-record-first step that killed one of the three ideas in the proven manual run. ## Open Questions -_None recorded yet._ +- The verdict's schema and where it is stored (ledger entry vs a dedicated ideate record family) — a spec-time decision. +- Whether ideate can consume a lifeboat or external document as the idea source. + +## Grill Settlements (2026-07-27) + +- Optional verb, never a gate: capture friction stays at one line, and the routing help carries the nudge. +- The adversarial leg codifies the fresh-context, off-policy, unknown-authorship pattern — the only measured debiasing effect, per the salvaged 2026-07-14 research record. ## Audit Notes diff --git a/.abcd/work/DECISIONS.md b/.abcd/work/DECISIONS.md index 272ca10..13cf41c 100644 --- a/.abcd/work/DECISIONS.md +++ b/.abcd/work/DECISIONS.md @@ -859,3 +859,4 @@ parallel-agent merge contention bites. layout, the canonical home, rather than a new doc. - 2026-07-27 (salvage): the four 2026-07-13/14 ideation-session entries above are appended out of chronological order — recovered from an unmerged ideation branch during branch cleanup, together with their research/plan docs; the /abcd:ideate seed from that session is re-recorded as itd-104 (its branch-local iss-93 capture id had collided with main's iss-93 and is retired unused). - 2026-07-27 — DEFERRED the row-has-footnote structural docs-lint rule (spc-15 out-of-scope): no existing rule shape covers table-row-to-footnote structure, so it would need a bespoke check; the grill left it optional and the citation-gate intent (itd-101) is now its natural home — implement it there or not at all. Recorded per spc-15's deferral-is-recorded clause; surfaced by the itd-100 fidelity audit's gap check. +- 2026-07-27 — GRILLED itd-101/102/103/104 to settlement (six decisions, each now in its intent's Grill Settlements + acceptance criteria): itd-103 guard fails open loudly, blocker/warn tiers with committed-only overrides, shell-token-aware command-position matching with an itd-81-style TNR-floored corpus; itd-101 refresh is manual-with-nagging (scheduled CI later, own sign-off), staleness warns at 180d and blocks releases at 365d, human verifications age on the same clock; itd-102 identity lives in a parseable markdown block (config points at it), check is warn-tier and never rewrites; itd-104 ideate is an optional verb, never a pre-capture gate, with a fresh-context off-policy adversary. All four drafts are grill-settled and await intent plan. From e946cbcf5869345c6b27814e526d116c0d101465 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Mon, 27 Jul 2026 19:25:40 +0100 Subject: [PATCH 2/2] chore: capture receipts-cannot-gate-maintainability (iss-145) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Candidate principle from the 2026-07 software-factories critique: maintainability has no fast oracle, so no receipt or deterministic gate can certify design quality — that verdict stays human, and the maintainer merge is load-bearing. Adoption is the maintainer's call. Assisted-by: Claude:claude-fable-5 --- .../iss-145-receipts-cannot-gate-maintainability.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 .abcd/work/issues/open/iss-145-receipts-cannot-gate-maintainability.md diff --git a/.abcd/work/issues/open/iss-145-receipts-cannot-gate-maintainability.md b/.abcd/work/issues/open/iss-145-receipts-cannot-gate-maintainability.md new file mode 100644 index 0000000..946cb35 --- /dev/null +++ b/.abcd/work/issues/open/iss-145-receipts-cannot-gate-maintainability.md @@ -0,0 +1,12 @@ +--- +schema_version: 1 +id: "iss-145" +slug: "receipts-cannot-gate-maintainability" +severity: "minor" +category: "observation" +source: "user-observation" +found_during: "2026-07-27 external-source review" +found_at: ".abcd/development/principles/" +--- + +receipts gate process integrity, not maintainability: candidate principle surfaced by the 2026-07 software-factories critique (primary observation: RL rewards fast oracles — tests pass in seconds — while bad architecture's cost function is measured in months, so maintainability has no fast oracle and models are not penalised for eroding it). Consequence for abcd: no receipt or deterministic gate can certify design quality; that verdict stays human (verifier-selects-gates-decide), and the maintainer merge on every PR is load-bearing, not ceremony. Candidate homes: a principle file or a brief mental-model line; adoption is the maintainer's call. \ No newline at end of file