Roadmap

Roadmap

kstrl evolves in named cycles, each governed by a durable tracker checked into docs/. Roadmaps are formal documents, not wish lists: every item has a sizing (diff scope, not duration), explicit dependencies, and a measurable "Done when" gate.

How to read the IDs

The trackers use short item IDs the way an issue tracker uses ticket numbers, and they appear in issues, PRs, and commit messages. Decoding them:

• Cycle prefixes: the first hardening cycle numbered its items A1-H5 by theme; the second used R0-R7 ("remediation"); the Dark Factory cycle continues as R8 (items R8.1-R8.10); continuous learning is R9; the control-loop cycle is R10 (items R10.1-R10.13). The prefix carries no meaning beyond "which tracker owns this item".
• H1-H4 are the standing process rules (no self-review, calibration on prompt change, prompt versions move with snapshots, state tested vs assumed). They originated as items H1-H4 in the first cycle and kept their names when they became permanent rules. See Contributing.
• E6 is the optional human checkpoint before a PR merges - again a first-cycle item ID that stuck as the feature's name.
• Phases 0-4 are pipeline stages (feedforward, mechanical verify, review, security at 2.5, contract tests, and the planned release stage as Phase 4). Fractional numbers exist so ordering never shifts.

When in doubt, Glossary decodes any term, and each tracker doc opens with its own legend.

How roadmaps are governed

Conventions shared by every tracker:

• Status legend: [ ] pending, [~] in progress, [x] done, [-] skipped.
• Sizing: S (small diff, under ~100 lines), M (one PR), L (multi-PR workstream).
• "User decisions required" and "user-run measurements required" are listed up front and block the items that need them.
• Process rules bind every cycle: no self-review (H1), calibration re-run on any prompt change (H2), prompt version and snapshot move together (H3), every done claim states what was tested vs assumed (H4).
• R8 added: no assumed thresholds - every numeric gate is a placeholder until replayed against historical run data.

Cycle 1: Adversarial hardening (A-H) - complete

Tracker: docs/adversarial-roadmap.md

The 42-item cycle that built the adversarial factory itself: the 8-role taxonomy, mechanical verification, hard-mode review gates, contract testing, knowledge distillation, calibration suite, evolution journal, and the process rules (H1-H4) that still bind all work. One deliberate skip: multi-model rotation (E1) was accepted as a known limitation - correlated failure across same-family roles is real and is being addressed differently (cross-family review at high autonomy, R8.5).

Cycle 2: A+ remediation (R0-R7) - substantially complete

Tracker: docs/remediation-roadmap.md

Fixed every finding from a full-system review and raised each dimension to A+: timeout enforcement everywhere (R0.1), worktree/lock lifecycle (R0.5), budget caps and cost metering (R3.1), structured failure parsing, fixtures oracle (R7.2), unified scheduling (R7.3), Linear one-way mirror (R7.4), no-progress breaker and sandbox pass-through (R7.5), and the opt-in claude-sdk adapter (R7.6). This cycle also carried the Ralph -> kstrl rename and the Textual TUI rewrite (events substrate, home shell, ks dash).

Still open in this tracker: user-run calibration baseline captures (R5.x), the same-family vs cross-family reviewer delta (R7.1), and two real factory runs. These are not bookkeeping - they are the authorization evidence the R8 autonomy ladder requires for L2+ entry.

Cycle 3: R8 Dark Factory - current

Tracker: docs/dark-factory-roadmap.md (landed via PR #157) - milestone - tracking issue #156

Provenance: the item designs come from current agentic practice and from a gap analysis that measured kstrl against what any software factory needs to run without a person watching each change. The verification core met the bar; four structural gaps did not: continuous intake, a release stage, runtime feedback, and an explicit earned-autonomy model. See Vision and Philosophy for the frame.

The eight items, in four dependency-ordered waves:

Wave	Item	Issue	One line
1 - governance core	R8.1 Policy envelope	#148	Declarative [policy] block enforced mechanically on diffs and lockfiles
1	R8.4 Health trending	#151	EWMA + Western Electric rules over run metrics; evidence for demotion
1	R8.2 Autonomy ladder	#149	L1-L4 levels: earned by evidence + human ack, demoted automatically
1	R8.3 Exception inbox	#150	One surface for everything awaiting a human decision; ntfy push
2 - adequacy	R8.5 Test adequacy gate	#152	Oracle linting, patch coverage, diff-scoped mutation, fixtures at L3+
3 - operation	R8.6 Continuous intake	#153	.kstrl/queue/ substrate, ks serve, GitHub Issues label polling
4 - release + loop	R8.7 Release stage	#154	Phase 4: deploy drivers, SHA-stamped verification ladder, rollback doctrine
4	R8.8 Runtime feedback	#155	Error/health signals polled into the queue; reproducing-test rule

Explicit non-goals for R8: 100% dark operation, two-machine queues, per-platform deploy adapters, webhook infrastructure, and building queue/monitoring/policy engines in-house.

Cycle 4: R9 Continuous learning - proposed

Tracker: docs/continuous-learning-design.md - milestone - tracking issue #217

An audit found the "harness improves itself" claim unsupported: learning was siloed per repository, proposals were string templates, and nothing read a proposal back into a run. The design routes each kind of learning to one destination with one gate: facts stay per project; rules go to a global playbook shared across projects, injected under a token cap, and each bullet is attributed and retired when the failure it targets keeps recurring; the adversarial prompts themselves are optimised offline against planted-bug fixtures and land only through calibration, a human, and the prompt-versioning rule; infrastructure failures are routed out of learning and filed as issues. The gating rule: learning whose failure announces itself by recurrence may be automatic; learning whose failure mode is silence needs a human and a held-out eval.

Cycle 5: R10 Control loop - current

Tracker: docs/control-loop-design.md (landed via PR #221) - milestone - tracking issue #235

The cycle that names what kstrl was already becoming and closes the gaps the name makes visible. Three findings drove it, each verified against the code: the engineer agent was the only writer of the flag that says a story is done, and the harness read it back as if it were a measurement; the retry context accumulated across attempts and never discharged; and no check could be run without a full paid factory run, which is why every threshold in the codebase was an unmeasured placeholder.

Thirteen items in dependency order, every gate advisory-first, no prompt body edited:

Order	Item	Issue	One line
1	R10.1 ks sense	#222	Run the mechanical sensors standalone on any tree, JSON output, no spend
2	R10.2 Level-triggered retry context	#223	Current failures in full; un-re-measured findings listed; resolved ones omitted
3	R10.3 Set-point agreement	#224	A story is done only when the reviewer confirms it; blocking mode reverts the flag
4	R10.4 Safe mode	#225	One predicate over the four existing degraded states
5	R10.5 Budget halts in hard mode	#226	An exhausted adversarial budget halts rather than merges unreviewed
6	R10.6 Dampener	#227	A baseline in version control and an advisory regression comment on every PR
7	R10.7 Flow control	#228	The daemon admits no new work while a kstrl PR is open (default 1)
8	R10.8 Golden patterns	#229	An operator-authored file of what good looks like, injected beside the knowledge prefix
9	R10.9 Memory file	#230	Standing feedback loaded last, after the retry context
10	R10.10 Polled steering	#231	/memory and /iterate comments on kstrl PRs reach the next run
11	R10.11 Demotion triggers	#232	Calibration regression opens an inbox item and, behind a switch, demotes
12	R10.12 Iterate faster	#233	A fast sensor inside the engineer loop and a convergence check; blocked on an entry criterion
13	R10.13 Reframe the architecture doc	#234	The loop nest and glossary become the primary frame

Where to watch progress

• The R8 milestone shows live item status; #156 is the sequenced checklist.
• Merged work always updates the tracker doc in the same PR (audit-trail doctrine), so docs/dark-factory-roadmap.md on main is authoritative.