Capstone C2 — a real contribution

C1 proved you can extend a stable seam. C2 is the real thing: a genuine, potentially-mergeable contribution to Clinker, scoped and planned the way the project actually works, under supervision. Unlike C1, it is not pinned to a fixed task. A specific issue would go stale as the codebase moves; instead this capstone specifies the selection criteria and the process, and you pick a live piece of work that fits, at graduation time.

Prerequisites

• Capstone C1 — a synthetic extension

→

Leads to

• Engine Track — overview

What this proves (graduation outcomes 9–13): that you can review against the project’s methods, plan and deliver a substantial supervised feature, explain the architectural decisions and trade-offs it touches, spot boundary/invariant threats, and write a design plan that preserves or deliberately revises a decision.

What you’ll be able to do

• Choose a bounded, real, reviewable contribution from the live backlog or open-questions register, and reject the out-of-scope shapes (XL, redesign, ungroundable behavior).
• Ground the work first: before writing any code, write a Readiness-Review result that states current-vs-desired behavior and the source/tests/docs you inspected.
• Route an unresolved choice (a new dependency, a public-API or schema change, an ungroundable behavior) to a Decision Gate instead of deciding it silently in a diff.
• Deliver the change on a branch with tests at the right boundary, then self-review the diff against the project’s checklist and run the full gauntlet to green.
• Explain which invariant or boundary the change touches and why it’s safe. This is the heart of a review-ready design plan.

This capstone aggregates the whole Engine Track: the gauntlet (review & the gauntlet), error/DLQ behavior (error handling), bounded-memory reasoning (bounded memory in action), and the record-trace habit (trace a record) all reappear here as the methods you ground, test, and review against. There’s no new machinery, just the track working as one supervised contribution.

New terms in this lesson (each is also used in the process steps below):

• Readiness Review: ground the work before you build it.
• Decision Gate, where an unresolved choice is escalated and recorded, not buried in a PR.
• agent-ready Agent Task: a tracked issue already bounded enough to implement.

Predict first

✋ Predict first

You pick an agent-ready Agent Task, ground it, and start implementing. Midway you discover that delivering it cleanly needs a new third-party dependency. Predict: what does the project's process require here, add the dep and note it in the PR, or stop? Write your answer before revealing.

Decide on your answer before you open the reveal — committing a guess is what makes it stick.

Reveal the answer

Stop and open a Decision Gate. A new dependency is one of the named gate triggers. The agent cannot validate the choice from existing source, tests, or docs, so it is not yours to decide silently inside a diff. You record the gate (chosen vs rejected options, the evidence, the consequences), resolve it, and only then implement that part. Gating the choice does not abandon the work; resolving the gate may well let the contribution proceed.

The wrong mental model here is “it’s a small dependency, so the PR description is enough disclosure.” Size is not the trigger; category is. Dependencies, public-API behavior, schema/storage, auth, and cross-crate boundaries are gated regardless of how small the change looks, because each is a decision a future reader (or a future revert) needs to find as a recorded choice, not reverse-engineer from the diff. This capstone is assessed on exactly this judgment: you escalate the category, you don’t minimize it.

Choosing the work (not a fixed task)

A good C2 is bounded, real, and reviewable. Two sources qualify:

1. An agent-ready Agent Task. This is a tracked issue that already meets the project’s implementability bar:

clinker ·GITHUB_ISSUE_AGENT_WORKFLOW.md ·Agent Task doc @19acdcb4

An agent-ready issue must have:
- size `agent-size:S`, `agent-size:M`, or carefully bounded `agent-size:L`
- observable acceptance criteria
- ...
`agent-size:XL` is not implementable. Split it or convert it into a milestone.

2. An item from the open-questions register. docs/ai/80_OPEN_QUESTIONS.md tracks unresolved questions, several of which are bounded, real contributions:

clinker ·80_OPEN_QUESTIONS.md doc @19acdcb4

### 6.  Should user-facing docs be updated to the unified `nodes:` shape ...
### 11. Are parsed CLI flags that appear weakly wired intentional placeholders
        or documentation drift?
### 12. Should `cxl-cli` docs, manifest description, and CLI behavior be aligned?

Good C2 shapes: a documentation-modernization to the unified nodes: shape, resolving a weakly-wired CLI flag, aligning cxl-cli behavior with its docs, or a new builtin/format that’s genuinely wanted (a real version of C1). Avoid anything agent-size:XL, anything that needs a redesign, and anything whose intended behavior you cannot ground in existing source, tests, or docs. Those are not C2-shaped.

The process

C2 is assessed on how you work, not just the diff. Follow the project’s real sequence.

Ground it first (Readiness Review). Before writing code, produce a grounding result: what you understand the work to be, the source/tests/docs you inspected, current vs desired behavior, and your recommended route. If the issue is vague, turning it into agent-ready work is the first deliverable.

Gate any decision. If delivering the change requires an unresolved choice, stop and open a Decision Gate before implementing:

clinker ·GITHUB_ISSUE_AGENT_WORKFLOW.md ·Decision Gate doc @19acdcb4

Create or link a Decision Gate for:
- new dependency or cargo-deny exception
- public API behavior
- data model, schema, storage, or migration behavior
- auth, security, privacy, or credentials
- cross-crate or cross-service architecture boundaries
- any behavior the agent cannot validate from existing docs, tests, or source

Implement, then review against the checklist. Build the change with tests at the right boundary, then self-review your own diff against the project’s checklist before asking for a merge:

clinker ·GITHUB_ISSUE_AGENT_WORKFLOW.md ·Review doc @19acdcb4

- PR maps to exactly one issue or one coherent sub-issue.
- No hidden public API, schema, dependency, auth, security, memory, or architecture change.
- Acceptance criteria are satisfied.
- Tests were not weakened to pass.
- Verification commands were run or skipped with a reason.
- Follow-up work is captured as issues, not hidden TODO drift.

Deliverables

1. A grounding result / design plan, a short document: the work as you understand it, the evidence you inspected, the chosen approach, and which invariant(s) the change touches and why it’s safe (or, if it revises a decision, a Decision Gate that records the choice). This is the heart of outcomes 11 and 13.
2. The implementation, on a branch, with tests at the right boundary, following the conventions of the code it sits next to.
3. A PR description with a definition-of-done summary: behavior changed, files/crates touched, acceptance criteria status, verification run, follow-ups filed.
4. A green full gauntlet: fmt, both clippy passes, and cargo test --workspace (the full CI parity, review & the gauntlet).

Supervision

C2 is supervised: a maintainer (or mentor) reviews the grounding result before you implement, and the PR before it would merge. The capstone’s bar is to “produce a contribution a maintainer can review and reason about,” with the design plan and review-readiness front and center, rather than to “get it merged.” Merging is the project’s call, not the rubric’s.

The rubric

Dimension	Below	Meets	Exceeds
Scoping & grounding	starts coding from a vague issue	grounds the work first; scope is bounded and clear	turns a vague issue into a clean agent-ready spec
Architectural fit	crosses a boundary unknowingly	respects layering + invariants; gates real decisions	articulates which decision/invariant it touches and why it’s safe
Tests & verification	no tests / weakened tests	tests at the right boundary; full gauntlet green	regression + property/insta tests where apt; cross-platform reasoning
Review & conventions	ignores the checklist	follows the issue/PR + DoD conventions; clean self-review	a design plan + DoD summary a reviewer can approve with minimal back-and-forth
Decision handling	silently decides an open question	routes unresolved choices to a Decision Gate	records the decision with options, evidence, and consequences

Retrieval checkpoint

✓ Capstone C2 — self-assessment gate

// quick check

Midway through a C2, you realize delivering it cleanly would require adding a new dependency. What does the process require?

• Add the dependency and mention it in the PR description
• Stop and open a Decision Gate (a new dependency is an explicit gate trigger), then resolve it (chosen vs rejected options, evidence, consequences) before implementing that part
• Abandon the C2 and pick a different issue

// quick check

Your C2's full-gauntlet run finishes and cargo test --workspace passes, but the change you made routes some malformed rows to the dead-letter queue at runtime. From the error-handling lesson: is a non-empty DLQ on a continue strategy a failure of your contribution?

• Yes: any record that doesn't make it through means the run failed and the PR isn't done
• No: under a continue strategy the DLQ is the designed side-channel for recoverable per-row errors; the run completes and your tests assert that behavior on purpose
• Only if the DLQ count is greater than the number of output rows

// quick check

Two graduates describe what a passing C2 is. Which statement is the MISCONCEPTION to correct?

• The grounding result and review-readiness are assessed alongside the diff; a clean plan a maintainer can approve quickly is part of passing
• C2 passes the moment the PR is merged: getting a maintainer to merge it is the real bar, and an unmerged contribution can't pass
• An unresolved choice belongs in a Decision Gate record, not as a unilateral call buried in the diff

💡 Hint 1

Don’t start at the code. Start at the grounding result: state what the work is, what you read to confirm it, and the current-vs-desired behavior. If you can’t ground the desired behavior in existing source/tests/docs, that’s a Decision Gate, not a guess.

💡 Hint 2

Keep scope honest: one issue, one coherent change, follow-ups filed as separate issues rather than smuggled into the diff. The review checklist’s “no unrelated cleanup” and “no hidden change” items are where most real PRs slip.

What a passing C2 looks like

A passing C2 is small and unglamorous on purpose: a bounded change (say, wiring a documented-but-inert CLI flag, or modernizing docs/examples to the unified nodes: shape) delivered with a grounding result up front, tests at the boundary, a green gauntlet, and a PR whose definition-of-done summary lets a maintainer approve it quickly. Where the change touched an open question or a decision, there’s a Decision Gate record, not a unilateral call buried in the diff. The graduate’s value shows in the plan and the review-readiness as much as the code: the work respects every boundary the Engine Track taught, and says so explicitly.

You should be able to:

• I chose bounded, real work (an agent-ready Agent Task or a tractable open-questions item), not XL and not a redesign
• I grounded the work first and wrote a design plan / grounding result before coding
• Any unresolved choice (dependency, API, schema, behavior, cross-crate) went through a Decision Gate, not a silent PR decision
• The change has tests at the right boundary and the full gauntlet is green
• My PR description has a definition-of-done summary and I self-reviewed against the checklist
• A maintainer/mentor reviewed the plan before implementation and the PR before merge

Verify in the checkout:

cargo fmt --all --check
cargo clippy --workspace -- -D warnings
cargo clippy --workspace --all-targets -- -D warnings
ulimit -n 4096 && cargo test --workspace

That’s graduation. From “build and run Clinker” to a real, boundary-respecting contribution planned and reviewed the way the project works: you’ve read the engine, extended it, and learned to change it safely.

Mark this lesson complete