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 038828c..7cc9a06 100644 --- a/.abcd/work/DECISIONS.md +++ b/.abcd/work/DECISIONS.md @@ -861,3 +861,4 @@ parallel-agent merge contention bites. - 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 — ADOPTED the canonical tagline: "A host-agnostic configuration layer for intent-driven development." Canonical identity home is the brief product chapter (01-product README, Identity section: title / tagline / pitch); README strapline, plugin manifest description, and AGENTS.md opening render from it. README's former strapline ("An opinionated, intent-driven development framework for product thinkers") is retired as a surface line; the product-thinker framing lives on in the README body. Rejected wordings: "for agent harnesses" (object shift, host/harness redundancy, plural over-promise), "over any agent harness" (drops the domain). Resolves iss-143; itd-102 generalises the drift check for managed repos. - 2026-07-27 — itd-93 parity tension resolved: Branch A. The scaffold template is the single source for release.yml/auto-release.yml; abcd-cli's live workflows are regenerated from it; the only sanctioned live diff is the additive workflow_dispatch rehearsal (trigger + non-publishing dry-run job). Rejected: substitution-gating the rehearsal off for abcd (weakens the parity guarantee on the one novel component). +- 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. 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