docs(skills): SDP agent on-ramps — graph-first reading, registrar-first authoring, mandatory in AGENTS.md

[darko-mijic]

What this PR introduces

This PR lands the three SDP agent on-ramps and matures them to the flow the engine actually ships: lean, single-file skills that teach coding agents to work with the Protocol graph-first, without a verb wall or duplicated carrier law.

The repo already exposes the sdp CLI and a typed reader; until now that surface lived in code and scattered docs. These skills make the intended workflow explicit and self-contained so agents (and humans) reach for the graph before they reach for the files. This cut also teaches the machinery that landed since the skills were first drafted: runnable registrars, structural anchor fields, and oracle binding, plus an AGENTS.md rewrite that makes the skills the mandatory on-ramps.

New surfaces

.agents/skills/sdp-agent-surface/SKILL.md — the graph-read skill
Tells agents to query the derived graph before reading .sdp.md files. Documents the g / graph / report contract, the anti-anecdote rule, and the refused actions. A new "How delivery state derives" section teaches the three claims (declared / anchored / inferred, never collapsed) and how implemented and has-verifier fall out of edges — direct satisfies resolution, the resolving specTest anchor as sole verifier source, and the enabled-example route — with observed named as the designed-and-deferred liveness fact. Carrying law: spec:consumers.agent-surface; entrance decision: spec:decisions.agent-front-door (MD-22).

.agents/skills/sdp-authoring/SKILL.md — the carrier-and-binding skill
The shortest complete path from build-backlog orientation through sdp new spec, honest readiness, sdp validate --watch, and executable examples. A new "Bind code, tests, and oracles" section teaches the three anchor builders (codeAnchor, specTest, specOracle) and names the two silent non-binding hazards — only the anchor-constant form is extracted, and a builder call through an untrusted import mints nothing and reports nothing — plus the structural component and uses fields and the document-realization convention for Markdown deliverables. The executable transition is now taught registrar-first: example space, bound point, generated contracts, the specOracle-bound oracle, one registrar activation beside the authored suite's specTest anchor, adopted-registrar commit, and a mutation-probed red result, with bindExample named as the low-level adapter beneath the registrar. Carrying workflow: spec:consumers.authoring-on-ramp, whose behavior rules are restated in lockstep (oracle-pinned).

.agents/skills/sdp-sessions/SKILL.md — the advisory routing skill
Routes delivery work through graph-first capture, design, implementation, review, and close shapes without workflow gates, now pointing the implement shape at the registrar-first transition. Carrying guidance: spec:consumers.delivery-session-on-ramp.

AGENTS.md — the handbook rewrite
The three skills are now named mandatory on-ramps: load the matching skill before any corpus question, Spec authoring, or delivery-session routing. Every claim in the file was re-checked against the repo for this rewrite — plan statuses against plans/ headers, the green-gate legs against package.json, the CLI verbs against sdp --help, the recipe count against the catalog — and the prose went through an unslop pass. The public README names only these three on-ramps and the shipped catalog of sixteen graph-first recipes.

Ratified decisions this work exercises

Decision	Ruling	Carrying Spec
MD-22 — agent-front-door	Package exports the reader; CLI carries one evaluation sink.	spec:decisions.agent-front-door
MD-18 — carrier-ruling	Markdown is the default canonical carrier.	spec:decisions.carrier-ruling
MD-25 — pack-syntax	Packs group Specs for review; they state no system truth.	spec:decisions.pack-syntax
MD-27 — gherkin-carrier	.sdp.gherkin is a lawful per-ID carrier for behavior/example Specs.	spec:decisions.gherkin-carrier
Structural anchor semantics	component/uses fields derive anchored structure; no implements field; cycles stay data.	spec:decisions.structural-anchor-semantics
Adopted registrars committed	Adopted registrars are committed and byte-checked; unadopted stay ignored.	spec:decisions.adopted-registrars-committed
Binding, not liveness	Anchors assert identity-only bindings; runtime truth stays out of the graph.	spec:decisions.binding-not-liveness

Try it

# build first if dist/ is absent
npm run build

# graph-read skill in action
pnpm --silent sdp:q 'return { specs: g.specs().length, packs: g.packs().length }' --json

# authoring skill: check a carrier before editing it
pnpm --silent sdp:q 'const c = g.specContext("spec:consumers.authoring-on-ramp"); return { found: c !== undefined, readiness: c?.statedReadiness, findings: c?.findings ?? [] }' --json

# validate the full green gate from the branch
npm run check

Verification (re-measured at close)

• Focused gate: npx vitest run test/skills.test.ts test/recipes.test.ts test/cli-q.test.ts test/package-smoke.test.ts — 56 passed, 0 failed.
• Oracle gates: npx vitest run test/self-hosting-consumers-oracle.test.ts test/self-hosting-consumers.test.ts test/check-self-hosting-gates.test.ts — 12 passed, 0 failed.
• Full gate: npm run check — pass (all 13 legs, preflight clean).
• Packaging gate: npm pack --dry-run --json lists exactly sdp-agent-surface/SKILL.md, sdp-authoring/SKILL.md, sdp-sessions/SKILL.md, and docs/agent-surface/recipes.md; no sdp-base or reference tree.
• Claims audit: every normative sentence added to the skills was re-read against src/graph/delivery-facts.ts, src/extract/anchors.ts, src/extract/protocol-bindings.ts, src/codegen/contracts.ts, and src/testing/ — no drift found.

What is intentionally not here

• No fourth skill, sdp-base, or references/ tree.
• No edit under src/, docs/agent-surface/, generated/, or package.json; no new carrying Spec, recipe, query verb, reader accessor, projection, context bundle, MCP surface, package entry, or runtime behavior.
• The specs/consumers/authoring-on-ramp.sdp.md edit restates existing law to match the shipped machinery; it introduces no new law, and its oracle pins moved in the same commit.
• The README quickstart keeps the low-level bindExample illustration; registrar-first guidance lives in the authoring skill.
• No Gen 1 PatternGraph vocabulary, @architect-* taxonomy, folder-promotion ladder, FSM, scope gate, unlock reason, bySymbol, or skill-local recipe copy.

Forward work

• Watch adoption: if agents keep asking the same corpus questions, promote the answer from a recipe to a reader join rather than expanding the skill prose.
• When the Gherkin carrier gets wider use, consider whether the authoring skill needs a worked .sdp.gherkin example; for now it points to the carrying Spec.
• The next skill iteration should come from observed agent failure modes, not from adding surfaces speculatively.

Plans executed

• sdp-skills-gen1-parity — original Gen 1 skill correction.
• sdp-skills-gen1-parity-unslop — the cleanup/introduction pass.
• The registrar-first maturation and AGENTS.md rewrite in the latest commit are session work reviewed claim-by-claim against the engine; no new plan was opened for them.

Greptile Summary

The authoring bootstrap now directs users to run the catalog’s required recipe bodies through the repository wrapper. The previously reported omission was disproved: executing catalog recipes 1 and 2 through the documented command returned both the ready-work view and the implementation/readiness drift results.

Confidence Score: 5/5

No blocking failure remains.

The documented authoring workflow was exercised with both required catalog recipes and produced the intended backlog and drift information.

T-Rex Logs

What T-Rex did

• The current contract validation across the skills and catalog definitions shows that every session must start with catalog recipes 1 and 2 and identify the catalog as the sole body owner.
• Documentation defines bodies as verbatim inputs and uses the same wrapper form, with recipe 1 and recipe 2 sections described (recipe 1 lines 80-120 and recipe 2 lines 131-155).
• The before capture shows the predecessor bootstrap probe, and the after capture shows the actual current workflow and its output, indicating a transition between states.
• The after capture records that the current workflow uses a wrapper and includes a command to paste each recipe body, such as the pnpm --silent sdp:q '<body>' invocation.

_{Ran code and verified through T-Rex}

_{Reviews (4): Last reviewed commit: "docs(skills): paste catalog bodies in th..." | Re-trigger Greptile}