From 87991032babcf9908c0f7fbfc072d7e7f5595f85 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Sat, 11 Jul 2026 18:03:02 +0100 Subject: [PATCH] docs: itd-80 SOTA declaration (dogfoods sota-per-intent) + run-learnings note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the ## SOTA section to itd-80 — the first intent to carry one — declaring Path 2 (native floor + seam to a mature external, no new dependency) across the spec store, fidelity review, and async ingestion axes; this is the record that explains why the build proceeds without a dependency hard stop. Also starts a run-learnings note capturing the auto-pick-up-merged-PRs workflow gap (rebase/prune/re-test stacked branches) and the duplication-under-subagents observation. Assisted-by: Claude:claude-opus-4-8 --- .../itd-80-intent-lifecycle-automation.md | 33 ++++++++++++ ...26-07-11-intent-lifecycle-run-learnings.md | 52 +++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 .abcd/development/research/notes/2026-07-11-intent-lifecycle-run-learnings.md diff --git a/.abcd/development/intents/drafts/itd-80-intent-lifecycle-automation.md b/.abcd/development/intents/drafts/itd-80-intent-lifecycle-automation.md index 84ffd4ee..3813c931 100644 --- a/.abcd/development/intents/drafts/itd-80-intent-lifecycle-automation.md +++ b/.abcd/development/intents/drafts/itd-80-intent-lifecycle-automation.md @@ -65,6 +65,39 @@ This intent builds the automation. Directory location stays the single source of - **adr-26** (native spec store — directory-as-truth), **adr-25** (host-delegated LLM default), **adr-27** (autonomous-run receipt gating) — the load-bearing decisions this intent instantiates. - **`.abcd/development/plans/2026-07-11-intent-lifecycle.md`** — the SOTA-researched design plan this intent builds to. +## SOTA + +> _Per the [sota-per-intent principle](../../principles/sota-per-intent.md): +> existing alternatives + rough maturity, then the chosen path. Harvested from the +> SOTA-researched design plan +> [`2026-07-11-intent-lifecycle.md`](../../plans/2026-07-11-intent-lifecycle.md)._ + +- **Spec store / lifecycle state.** Alternatives: git-native trackers (git-bug — + CRDT, *mature*; Fossil — *mature*) avoid directory-state for multi-writer merge, + a pressure a single-maintainer config tool does not have; spec-kit branch-per-spec + (*usable*) fragments the durable `shipped/` record we want; the companion harness + spec/task backend (*usable*) is the intended richer engine. → **Path 2**: a + minimal directory-as-truth native floor (`os.Rename`, stdlib) with the adr-26 + seam to adopt an external spec engine later. No dependency. +- **Fidelity review (LLM-as-judge).** Alternatives: eval/judge harnesses (*mature*) + plus the 2025–26 judge-calibration literature. The literature's conclusions + (per-criterion + 4-value ordinal + explicit INCONCLUSIVE + report-not-block, + cited evidence, pinned judge/prompt hashes) are adopted as *design*; the harnesses + themselves force a judge and add heavy deps. → **Path 2**: host-delegated native + emit/ingest (adr-25), the better external judge being whatever the host runs. + No dependency. +- **Async ingestion.** The transactional outbox/inbox pattern (*de-facto standard*) + is adopted as a stdlib pattern (`encoding/json` + hand-rolled validation); the + verdict envelope reuses the repo's existing VSA attestation shape. Pattern reuse, + not a dependency. + +**Verdict — Path 2 on every axis.** No new dependency ⇒ no path-1 hard stop; the +seams are load-bearing (adr-25/26) ⇒ no path-3 review. This is exactly why the +build proceeds autonomously without a dependency gate. The design plan's headline: +abcd's ADRs (25/26/27 + the VSA shape) already sit on or slightly ahead of generic +SOTA here — the work is mostly naming what we have after its mature counterpart and +closing two gaps (cited evidence per criterion; pinned judge/prompt/rubric hashes). + ## Open Questions - **`spc-N` minting under reserved ids.** The corpus pre-references `spc-` ids in planning docs and itd-3 reserved `spc-1`. Slice 1 mints `max(spec-store files ∪ intent `spec_id`) + 1` to avoid live collisions; reconciling the store's sequential minting with the brief's aspirational spec numbering is deferred to the richer spec-store slice. diff --git a/.abcd/development/research/notes/2026-07-11-intent-lifecycle-run-learnings.md b/.abcd/development/research/notes/2026-07-11-intent-lifecycle-run-learnings.md new file mode 100644 index 00000000..01abc677 --- /dev/null +++ b/.abcd/development/research/notes/2026-07-11-intent-lifecycle-run-learnings.md @@ -0,0 +1,52 @@ +# Intent-lifecycle build — run learnings + +Observations captured during the autonomous itd-80 build (intent-lifecycle +automation, slice 1). A running log; graduates into intents/ADRs where a learning +is load-bearing. + +## Workflow gaps (candidate capabilities) + +- **Auto-pick-up of manually-merged PRs (maintainer-flagged).** The autonomous + loop opens a PR per wired section and does not self-merge `feat`. Today, when the + maintainer merges one manually, the loop does not react: it should detect the + merge, prune the merged branch (local + confirm remote auto-delete), pull the new + `main`, **rebase the stacked follow-on branch** onto it, and **re-run the gates** + — then continue. Currently each of these is a manual step the main thread does by + hand (`fetch --prune`, `branch -D` of the squash-merged branch, `rebase + origin/main`). Natural home: [itd-29 autonomous-run-resilience]; worth a dedicated + `abcd` verb (e.g. an `abcd run reconcile-branches` / a post-merge hook) so a long + autonomous run stays in lockstep with the maintainer's async merges without + human-in-the-loop git bookkeeping. Includes: detect when a stacked PR's base has + merged and re-target/rebase it; re-run `make preflight` after every rebase. + +- **Duplication pressure under subagent implementation.** Independent + implementation subagents repeatedly re-copied primitives (the frontmatter + line-scanner, atomic-write, the trust-guarded rename helper). `one-canonical-primitive` + had to be enforced explicitly in each phase brief, and one copy (spec's + atomic-write) slipped through until the review pass. Signals value in a + **duplication-detector** (a lint code, or a review-checklist item) so the rule is + mechanical rather than a per-brief reminder — the same principle-→-discipline + promotion path the record already uses. + +## What is working + +- **Deterministic gates catch real drift early.** `record-lint` blocked a + freshly-authored intent whose Prior-Art links pointed at `drafts/` siblings that + actually live in `planned/` — caught before commit. Directly validates the + gate-over-prose approach, and is itself a small instance of the link-drift the + reconcile automates. + +- **Phased TDD + a review gate per phase keeps the main thread lean.** Each phase is + a background subagent (design → implement → test) whose conclusions return to the + main thread; every phase gets a `ruthless-reviewer` pass, and trust-boundary + phases (the reconcile, the verdict ingest) additionally get `security-reviewer` + before their PR. The ruthless pass on Phases 1–2 returned SHIP but surfaced two + real hardening items (retry-safe `Plan`; the slipped atomic-write copy) that were + fixed test-first before the PR. + +- **Dogfooding earns the SOTA-per-intent principle its keep.** itd-80 is the + pipeline's own payload, and its `## SOTA` declaration (Path 2 on every axis — a + native floor with a seam to a mature external, no new dependency) is exactly the + record that explains *why the build proceeded autonomously without a dependency + hard stop*. The principle is not overhead here; it is the artifact that makes the + no-stop decision auditable after the fact.