Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
ce5982e
chore: capture round-9 bug-hunt findings
REPPL Aug 26, 2026
15e7d91
docs: RS001 requires entering a terminal folder, at every site that s…
REPPL Aug 26, 2026
6428a25
docs: the plugin surface adds three commands, not one
REPPL Aug 26, 2026
a7e602f
docs: the derived changelog signals a pre-1.0 break by the bump, not …
REPPL Aug 26, 2026
371c1f4
docs: no page sets data-theme yet, and the build README says so
REPPL Aug 26, 2026
30b965b
docs: itd-24 cites the glossary's spec term, not its banned synonym
REPPL Aug 26, 2026
66c06e1
chore: pin lf line endings on the served install script template
REPPL Aug 26, 2026
eff3168
docs: sweep the live disciplines bucket onto the intent-auditor rename
REPPL Aug 26, 2026
c961ce6
docs: itd-5 points task_classes at the naming registry, with intent_a…
REPPL Aug 26, 2026
cefa277
docs: itd-43 reconciles onto the delivered glossary rename
REPPL Aug 26, 2026
c3a46c5
fix: intent verbs resolve spec_id by number, the way lint already mat…
REPPL Aug 26, 2026
5d964a9
fix: ScanSpecLinks propagates intent-tree read errors
REPPL Aug 26, 2026
2d00855
fix: lesson prose routes through the canonical CleanProse primitive
REPPL Aug 26, 2026
4fe662d
fix: bound the lifeboat probe's root-sha read
REPPL Aug 26, 2026
15b849d
fix: RD002 sees renames and deletions, and a git failure refuses
REPPL Aug 26, 2026
2e22ac0
docs: the CI account names the site-render and issue-resolution gates
REPPL Aug 26, 2026
a2aa778
fix: capture refuses a --blocked-by target the ledger does not hold
REPPL Aug 26, 2026
9a24c32
fix: a ledger record the reader would skip is now a record_schema blo…
REPPL Aug 26, 2026
40132da
chore: capture the unknown-property half of the ledger-visibility gap
REPPL Aug 26, 2026
84d00cb
chore: resolve round-9 bug-hunt records
REPPL Aug 26, 2026
f5cbae3
Merge origin/main into bughunt-b/round-9
REPPL Aug 26, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .abcd/development/brief/05-internals/06-lint.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ Lint codes are 2-letter category prefix + 3-digit numeric suffix: `AAnnn`. Categ
- `RC007` DONE spec references an itd-N with NO intent file in any bucket — reference-to-nothing. Same DONE-spec walk + extraction priority as `RC006`. Severity: info. **Delivered** in spc-48 .2. The gate keeps its REPORT-not-block exit grammar (clean/info/warn → exit 0; nonzero only for a config-promoted blocker or a malformed invocation) — `RC006`/`RC007` do not change it.

- `RD001` review directory malformed — a directory under `.abcd/work/reviews/` is not named `<YYYY-MM-DD>-<kebab-scope>` or lacks the required `00-summary.md` consolidated report. The charter's `reviews/README.md` sits at the root and is exempt; so are the 40-hex sha-keyed semantic-gate receipt directories (`.abcd/work/reviews/<40-hex>/<gate>.json`, iss-35), a distinct artefact class with their own `receipt_gate` integrity check. Severity: blocker. Enforced now by the standalone pre-push/CI gate `scripts/check-reviews.sh`; ports into `internal/core/lint`.
- `RD002` review file edited after creation — a file inside a dated review directory carries a post-creation modify/rename in committed history, violating the append-only rule (a review is immutable; reality is never edited to match a review, nor a review to match reality). Deletion detection over history is deferred to the ported Go implementation. Severity: blocker. Enforced now by `scripts/check-reviews.sh`, which needs full git history: on a shallow checkout the script refuses (exit 2) rather than pass vacuously, since past the graft boundary every file reads as newly added and the append-only check covers nothing. The RS-family gate (`scripts/check-issue-resolution.sh`) shares the refusal for the same reason — an unfetched commit is indistinguishable from an absent one. The CI `record-lint` job checks out with full depth.
- `RD002` review file changed after creation — a file inside a dated review directory carries a post-creation modify, rename or delete in committed history, violating the append-only rule (a review is immutable; reality is never edited to match a review, nor a review to match reality). All three shapes refuse: the gate makes ONE history pass over the reviews root (`git log --name-status --diff-filter=DMRT`) and flags every status line whose path falls in the dated-directory population, rather than probing each working-tree file — a pathspec-scoped log never reports a rename, and a deleted file leaves no tree path to probe from. Severity: blocker. Enforced now by `scripts/check-reviews.sh`, which needs full git history: on a shallow checkout the script refuses (exit 2) rather than pass vacuously, since past the graft boundary every file reads as newly added and the append-only check covers nothing. Every other git failure refuses the same way (exit 2) instead of reading as a clean history; the one exception is an unborn HEAD — a freshly scaffolded repo — which passes while saying loudly that it covered nothing. `scripts/check-reviews-cases.sh` stages each shape in a scratch repository and asserts both polarities, so the refusal is a watched fact rather than a claim. The RS-family gate (`scripts/check-issue-resolution.sh`) shares the refusal for the same reason — an unfetched commit is indistinguishable from an absent one. The CI `record-lint` job checks out with full depth.
- `RD003` review path leak — a review document contains an absolute personal path (`/Users/…`, `/home/<user>/…`, `C:\Users\…`) rather than a repo-relative one. Severity: blocker. Enforced now by `scripts/check-reviews.sh`; ports into `internal/core/lint`. The privacy scan is narrower here than the launch PII gate — it targets only the personal-path leak the charter forbids.

The charter's two **semantic** rules — the provenance discriminator ("no abcd verb invocation produced it → it belongs here") and "reviews are not a shadow backlog" (findings graduate to intents/issues/ADRs) — are not machine-decidable and stay conventions, enforced by review, not lint.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,13 @@ release automation:
here is the *recording and cutting* instrument either way, not a second
source of the number.

> **Amendment (2026-08-26).** itd-73 has landed: the ingest derives the
> number and renders the six closed Keep a Changelog sections, so a
> pre-1.0 break is signalled by the minor bump and the section its record
> belongs to, not by a **Breaking** heading — the derived renderer has no
> such section. The "called out under **Breaking**" clause above described
> the interim hand-rolled regime, whose last cut was v0.6.0.

## Alternatives Considered

- **Manual tag push as the decision.** The status quo. Rejected as policy:
Expand Down
20 changes: 10 additions & 10 deletions .abcd/development/intents/disciplines/itd-1-acceptance-gates.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
id: itd-1
slug: acceptance-gates
kind: discipline
kind_notes: "Cross-cutting acceptance-criteria gate; applied via the record lint (internal/core/lint) at /abcd:intent plan time and verified by intent-fidelity-reviewer (single-document role) on every shipped intent."
kind_notes: "Cross-cutting acceptance-criteria gate; applied via the record lint (internal/core/lint) at /abcd:intent plan time and verified by intent-auditor (single-document role) on every shipped intent."
suggested_kind: null
spec_id: null
reclassification_history:
Expand All @@ -14,11 +14,11 @@ severity: critical

## Rule

Every standalone or bundle-member intent in `drafts/` and `planned/` carries a `## Acceptance Criteria` section with at least one well-formed Given-When-Then bullet. Every discipline intent in `disciplines/` carries the same. `/abcd:intent plan` refuses to promote an intent without it (hard block via the record lint, `internal/core/lint`). Every shipped intent's `## Audit Notes` section contains per-criterion verdicts (`MET` / `MET_WITH_CONCERNS` / `NOT_MET` / `INCONCLUSIVE`) emitted by the `intent-fidelity-reviewer` agent's single-document role.
Every standalone or bundle-member intent in `drafts/` and `planned/` carries a `## Acceptance Criteria` section with at least one well-formed Given-When-Then bullet. Every discipline intent in `disciplines/` carries the same. `/abcd:intent plan` refuses to promote an intent without it (hard block via the record lint, `internal/core/lint`). Every shipped intent's `## Audit Notes` section contains per-criterion verdicts (`MET` / `MET_WITH_CONCERNS` / `NOT_MET` / `INCONCLUSIVE`) emitted by the `intent-auditor` agent's single-document role.

## Why

abcd's intent format captures direction (press release or `## Rule`) and scope (in/out lists). Without acceptance criteria it cannot capture **the verifiable bar for "shipped"**. The `intent-fidelity-reviewer` agent is otherwise reduced to interpreting prose, which means drift detection depends on the reviewer's judgement rather than on a pre-committed standard.
abcd's intent format captures direction (press release or `## Rule`) and scope (in/out lists). Without acceptance criteria it cannot capture **the verifiable bar for "shipped"**. The `intent-auditor` agent is otherwise reduced to interpreting prose, which means drift detection depends on the reviewer's judgement rather than on a pre-committed standard.

Prior art ([PAUL][paul]) treats acceptance criteria as a hard gate: defined before tasks, verified by an Execute/Qualify loop, with multi-state escalation outcomes (`DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`). The full PAUL framework is more than abcd currently needs; the **acceptance-criteria pattern** ([Given-When-Then][bdd-given-when-then]) is the load-bearing piece.

Expand All @@ -28,7 +28,7 @@ This is a small schema bump with a large quality return. Every intent gets a mea

- **`## Acceptance Criteria` section** required in every intent template (standalone, bundle-member, *and* discipline). At least one Given-When-Then bullet. The section header is fixed (parser depends on it).
- **Hard-block validation in `/abcd:intent plan`** — intent cannot transition `drafts/` → `planned/` (or `drafts/` → `disciplines/`) without at least one well-formed acceptance criterion. Lint code: `IL002` (delivered by spc-8; see `05-internals/06-lint.md`).
- **`intent-fidelity-reviewer` single-document role** — when auditing a shipped intent, the agent emits a per-criterion verdict block into the intent's own `## Audit Notes` section. The writer maintains a single delimited `### itd-1 review <ts>` block (machine-fenced so a repeat review *replaces* it in place — the section never accumulates stale blocks; git history is the prior-review trail):
- **`intent-auditor` single-document role** — when auditing a shipped intent, the agent emits a per-criterion verdict block into the intent's own `## Audit Notes` section. The writer maintains a single delimited `### itd-1 review <ts>` block (machine-fenced so a repeat review *replaces* it in place — the section never accumulates stale blocks; git history is the prior-review trail):
```
## Audit Notes

Expand All @@ -42,11 +42,11 @@ This is a small schema bump with a large quality return. Every intent gets a mea

Overall: MET / MET_WITH_CONCERNS / NOT_MET / INCONCLUSIVE
```
This `## Audit Notes` write is the **verdict of record**; each run also writes a per-run forensic copy at `.abcd/logbook/audit/review-<ts>/report.{json,md}`. **spc-12 ships the manual reviewer** (`/abcd:intent review <itd-N>`) plus the `## Audit Notes` / `review-<ts>` writers; **automatic invocation on the `planned → shipped` transition is deferred to the lifecycle-owning spec** (`spc-6`). Until that lands, a shipped intent's `## Audit Notes` is populated only when `/abcd:intent review` is run by hand.
This `## Audit Notes` write is the **verdict of record**; each run also writes a per-run forensic copy at `.abcd/logbook/audit/review-<ts>/report.{json,md}`. **spc-12 ships the manual reviewer** (`/abcd:intent audit <itd-N>`) plus the `## Audit Notes` / `review-<ts>` writers; **automatic invocation on the `planned → shipped` transition is deferred to the lifecycle-owning spec** (`spc-6`). Until that lands, a shipped intent's `## Audit Notes` is populated only when `/abcd:intent audit` is run by hand.
- **Escalation states** — four states, lifted from PAUL. Binary pass/fail loses information; four states preserve nuance without exploding.
- **Verdict family disjointness** (cross-referenced from [`05-internals/01-agents.md § Verdict-tag protocol`](../../brief/05-internals/01-agents.md#verdict-tag-protocol)). The four criterion verdicts above (`MET` / `MET_WITH_CONCERNS` / `NOT_MET` / `INCONCLUSIVE`) score *promise vs reality on a shipped intent* — they belong to `intent-fidelity-reviewer`'s Role 1 output. They are **deliberately disjoint from review verdicts** (`SHIP` / `NEEDS_WORK` / `MAJOR_RETHINK`) which score *changes/runs* (oracle reviews of plans, implementations, completions; consumed by the native receipt schema validator). The two enums never mix — review verdicts emit on a *change*, criterion verdicts emit on a *promise*. This disjointness was reinforced 2026-05-08 when idea-4's pre-review draft conflated the two families ("NOT_MET on an agent run" — wrong; criterion verdicts apply to intents not agents). Closing-the-loop signals on agents (per Frontier Awareness, idea-4) MUST use canary/golden-test/operator-tagged failure signals, NOT spec-level criterion verdicts.
- **Verdict family disjointness** (cross-referenced from [`05-internals/01-agents.md § Verdict-tag protocol`](../../brief/05-internals/01-agents.md#verdict-tag-protocol)). The four criterion verdicts above (`MET` / `MET_WITH_CONCERNS` / `NOT_MET` / `INCONCLUSIVE`) score *promise vs reality on a shipped intent* — they belong to `intent-auditor`'s Role 1 output. They are **deliberately disjoint from review verdicts** (`SHIP` / `NEEDS_WORK` / `MAJOR_RETHINK`) which score *changes/runs* (oracle reviews of plans, implementations, completions; consumed by the native receipt schema validator). The two enums never mix — review verdicts emit on a *change*, criterion verdicts emit on a *promise*. This disjointness was reinforced 2026-05-08 when idea-4's pre-review draft conflated the two families ("NOT_MET on an agent run" — wrong; criterion verdicts apply to intents not agents). Closing-the-loop signals on agents (per Frontier Awareness, idea-4) MUST use canary/golden-test/operator-tagged failure signals, NOT spec-level criterion verdicts.
- **Intent template update** — the intent template the binary scaffolds (`internal/core`) includes the `## Acceptance Criteria` section with one example criterion. The discipline template (separate file) includes the same section.
- **Inheritance into every other spec** — every native spec plan-reviewed under abcd inherits the discipline's gate: the spec must reference the parent intent's acceptance criteria as the verification bar, and `intent-fidelity-reviewer` checks delivered reality against them on shipping.
- **Inheritance into every other spec** — every native spec plan-reviewed under abcd inherits the discipline's gate: the spec must reference the parent intent's acceptance criteria as the verification bar, and `intent-auditor` checks delivered reality against them on shipping.

## What's Out of Scope

Expand All @@ -58,12 +58,12 @@ This is a small schema bump with a large quality return. Every intent gets a mea

## Acceptance Criteria

> _Yes, this discipline eats its own dog food. The criteria below describe how the discipline itself is checked — by the record lint (`internal/core/lint`) at promotion time and by `intent-fidelity-reviewer`'s single-document role on every shipped intent._
> _Yes, this discipline eats its own dog food. The criteria below describe how the discipline itself is checked — by the record lint (`internal/core/lint`) at promotion time and by `intent-auditor`'s single-document role on every shipped intent._

- **Given** a draft intent without an `## Acceptance Criteria` section, **when** the user runs `/abcd:intent plan itd-N`, **then** the command refuses to promote the intent and lists the missing section as the reason.
- **Given** a draft intent with a malformed acceptance section (e.g. no Given-When-Then bullets, or a header but empty body), **when** `/abcd:intent plan` runs, **then** the lint emits a specific error pointing at the malformed line.
- **Given** a discipline-kind intent in `drafts/` without a `## Acceptance Criteria` section, **when** the user attempts to promote it via `/abcd:intent plan --kind discipline`, **then** the same hard-block applies — disciplines are not exempt from their own rule.
- **Given** a shipped intent with three acceptance criteria, **when** `intent-fidelity-reviewer` runs, **then** the resulting Audit Notes contain exactly three per-criterion verdict lines plus an overall status. *(Audit note 2026-05-07: this criterion is verifiable only after the reviewer's implementation lands in a separate spec; until then it is a paper-only gate. The reviewer itself will retroactively run against this discipline when implemented.)*
- **Given** a shipped intent with three acceptance criteria, **when** `intent-auditor` runs, **then** the resulting Audit Notes contain exactly three per-criterion verdict lines plus an overall status. *(Audit note 2026-05-07: this criterion is verifiable only after the reviewer's implementation lands in a separate spec; until then it is a paper-only gate. The reviewer itself will retroactively run against this discipline when implemented.)*
- **Given** a reviewer verdict of `NOT_MET` on any criterion, **when** the reviewer writes its report, **then** the report includes a "Divergence" sub-section explaining what was delivered vs. what was promised — not just a label.
- **Given** the brief is updated, **when** a contributor reads `04-surfaces/05-intent.md` (intent system), **then** they find the acceptance-pattern requirement and one worked example with all four verdict types.
- **Given** a native spec that traces back to a parent intent, **when** the spec's plan-review runs, **then** the review verifies the spec's acceptance section references (or is structurally compatible with) the parent intent's `## Acceptance Criteria` bullets — drift between the two surfaces is flagged.
Expand All @@ -79,7 +79,7 @@ This is a small schema bump with a large quality return. Every intent gets a mea

## Audit Notes

_Empty. Populated by intent-fidelity-reviewer's single-document role when this discipline is first audited. Note: disciplines never "ship" in the standalone-intent sense — they are audited continuously via the rule-applies-to-every-spec semantics rather than via a planned→shipped transition. The reviewer's findings here record any spec that violated this discipline (e.g., merged without an AC section)._
_Empty. Populated by intent-auditor's single-document role when this discipline is first audited. Note: disciplines never "ship" in the standalone-intent sense — they are audited continuously via the rule-applies-to-every-spec semantics rather than via a planned→shipped transition. The reviewer's findings here record any spec that violated this discipline (e.g., merged without an AC section)._

## References

Expand Down
Loading
Loading