issue_80: Present the toolkit through capabilities

[dieterbaier]

Summary

Adds a Capabilities section to README.md, above everything else, because presentation was the problem it exists to fix. Six capabilities, each naming the moment it starts from, the outcome it produces, and the canonical skills that collaborate to produce it.

The strongest claim the toolkit can make was previously invisible: eight skills together already deliver an architecture-aware Spec-Driven Development workflow, from feature request through to a checked convergence, and a flat list of eighteen bullets cannot show that.

Closes #80

Feature map validated before writing

The first acceptance criterion, recorded on the issue. Two findings changed the map #77 proposed:

Decision and Impact Management is a strict subset of Spec-Driven Development — all five of its skills also appear there. #77 permits a skill in several capabilities, which is right, but a feature that is a subset of another feature is a phase, not a peer. It becomes a real distinction when framed by entry point: a feature request versus an architecture question arriving on its own. Both entries are now written that way, and the overlap with Reviewable Delivery is stated rather than hidden.

Session Continuity is a group of its own. clock-in and clock-out post-date #77 and appear in none of its five groups. They are also the only skills a user invokes by name, daily — omitting them describes the toolkit as less usable than it is.

Five skills the proposed map left unplaced are now placed: commit-message under Reviewable Delivery, clock-in/clock-out under Session Continuity, architecture-core as a precondition above the list rather than a member of one, and presentation named explicitly outside the map. A feature map that stretches to include everything stops describing what the toolkit is for.

The arc closes through the Convergence Check

Rebased onto #84 after review. Spec-Driven Development no longer stops where its skills stop; it states what the capability produces:

Produces a delivered change whose request, behaviour specification, architecture knowledge, implementation, tests and delivery metadata tell one consistent story — checked, not assumed.

and closes with the gate, its four result states, and the non-repair rule. Reviewable Architecture Delivery uses the same gate before a pull request is declared mergeable — the second place it applies, and leaving it out would have implied the gate belongs only to feature work.

Verification

• All 20 adapter-exposed skills appear in the section, convergence-check included — checked mechanically against skills/**/SKILL.md frontmatter.
• Every link target in README.md resolves to an existing path — checked mechanically.
• ./build.sh test — 35 JS tests, 157 Ruby assertions, 0 failures.
• ./build.sh check-adapters — current.

Every acceptance criterion of #80 is met, including "from feature request to convergence", which an earlier revision of this PR deferred while the gate did not yet exist.

Notes for the reviewer

Placement is the deliberate part: the section goes before "Relationship to docToolchain", not next to the skill list. A capability overview buried at line 245 would not have solved the problem that produced #77. The existing "AI Skills" list stays exactly as it was and is now introduced as the reference view, with a link back up.

The stale passages an earlier version of this description carried — a skill count of 19, and a section claiming the Convergence Check did not exist — were exactly what question 7 of the new gate asks about: whether the issue, the pull request and the source documentation describe the same resulting state. They did not. Fixed.

[dieterbaier]

Review: change needed before merge

The capability map is well structured, and the distinction by entry point makes the overlap between Spec-Driven Development and Decision/Impact Management understandable. The validation workflow is also green.

One acceptance criterion of #80 is nevertheless knowingly left unmet: the Spec-Driven Development capability must describe the workflow “from feature request to convergence”, while this version ends at Reviewable Architecture Delivery. Because the PR also uses Closes #80, merging it in the proposed order would close the slice with an unchecked acceptance criterion.

Please resolve this before merge. The cleanest sequence seems to be:

1. merge issue_81: Define the canonical Convergence Check #84 first;
2. rebase this PR;
3. add convergence-check as the final gate and describe the end-to-end outcome through convergence.

Alternatively, keep this PR independent but do not close #80 until a concrete follow-up in the same delivery chain completes that criterion. Given that #84 already provides the missing canonical target, wiring it in here after #84 lands is clearer and avoids advertising a nonexistent skill.

[dieterbaier]

Reworked in 529d61c, following your prescribed sequence: #84 merged, this rebased onto it, convergence-check wired in as the final gate.

You were right that the alternative — keep this independent and leave #80 open — was the worse option. Closes #80 with an unchecked criterion is precisely the drift the Convergence Check itself is meant to catch, and shipping it in the same delivery chain as the gate would have been an awkward first example.

Spec-Driven Development now states what the capability actually produces rather than where its skills stop:

Produces a delivered change whose request, behaviour specification, architecture knowledge, implementation, tests and delivery metadata tell one consistent story — checked, not assumed.

and closes with the gate, its four result states, and the non-repair rule.

Reviewable Architecture Delivery gained the same gate before a pull request is declared mergeable. That is the second place the check applies, and leaving it out would have implied the gate belongs only to feature work.

Verification, all mechanical:

• every adapter-exposed skill appears in the section — now 20, including convergence-check
• every link target in README.md resolves
• ./build.sh test 35 JS / 157 Ruby, 0 failures; check-adapters current

All acceptance criteria of #80 are now met, including the one this PR previously deferred.

One consequence for #82: its first carry-over is done. The remaining work there is the wiring into architecture-impact, implement-issue-workflow and pr-review — I will update the note on that issue once this lands.

[dieterbaier]

Re-review: implementation is sound; PR description still needs alignment

The rework in 529d61c resolves the substantive finding:

• Spec-Driven Development now runs explicitly from feature request through the Convergence Check.
• The four result states and the non-repair rule are represented without duplicating the canonical skill.
• Reviewable Architecture Delivery correctly uses the same gate before mergeability.
• The current validation workflow is green.

One delivery-metadata inconsistency remains in the PR body:

• Verification still says 19 adapter-exposed skills, while the updated map has 20.
• The section “One acceptance criterion is deliberately incomplete” still says that the Convergence Check does not exist and that Slice #77.1: Present the toolkit through features in the README #80 remains incomplete. Both statements are obsolete after issue_81: Define the canonical Convergence Check #84 and 529d61c.

Please update or remove those stale passages. This is especially worth fixing here because the new gate explicitly asks whether the pull request and source documentation describe the same resulting state.

Once the PR description is aligned, I see no remaining blocker to merge.

[dieterbaier]

Description aligned: skill count corrected to 20, and the "deliberately incomplete" section removed — both statements it made were obsolete after #84 and 529d61c.

Worth recording why this one stings: the stale passages were a question-7 finding against this very pull request — do the issue, the pull request, the source documentation and the code describe the same resulting state? They did not. The code converged and the delivery metadata did not follow, which is the exact drift the gate exists to catch, found by a human on the pull request that introduces it.

I have added a short note at the end of the description saying so, rather than quietly editing the numbers. The first use of a gate is worth keeping visible.

Merging now, then continuing with #82.