Draft plan 17 (self-hosting v1) and harden AGENTS.md

[darko-mijic]

Summary

This PR does two related things, both documentation-only:

1. Adds plans/17-self-hosting-v1.md — the DRAFTED execution plan for the first self-hosting slice: author the Protocol’s own delivery as Markdown (.sdp.md) specs, build the product Markdown parser the corpus forces, and prove the loop on this repo itself.
2. Hardens AGENTS.md so agents (and humans) get an honest entrypoint: intended design vs current implementation stay distinct, plan selection matches how this repo actually sequences work, and status language matches what the package has actually shipped (landed on main, not a release).

No engine code changes. The goal is to make plan 17 execution-ready before anyone starts Session 1 on a feature branch.

Why this matters

The carrier competition is settled: authored specs will be Markdown (.sdp.md). The next real work is self-hosting — not more paper design. Plan 17 deliberately reorders the post-ruling schedule so we author the Protocol’s own specs first and let that corpus force the parser, the public carrier seam, and the exact syntax rulings we need.

Before that work starts, the agent entrypoint and the plan itself needed a few honesty fixes. Review of both files found real epistemic and operational gaps; every claim was checked against the codebase (discovery excludes, package version 0.0.0, no release tags, 15a–15d as real execution plans, no root README.md, MD-18 / CONTEXT.md still stating sole-canonical TS, etc.).

What changed

AGENTS.md

Issue	Fix
Blurred intended truth with implementation truth (“prefer src/ over prose”)	Two-layer rule: authored intent / decisions / concept material vs src/ + tests as evidence of realization; disagreement is drift to resolve, never silent promotion of code into intent
Plan-selection ignored letter-suffixed plans (14a / 15a)	Read the highest primary plan and any active subplans it designates; only ignore suffixes when nothing designates them
“Shipped” overstated repo evidence	“Landed on main” / “implemented under src/” — package remains 0.0.0, no tags
Checkout row omitted untracked artifacts	Notes untracked generated/ (regenerated in-pipeline)
Static npm run check row	Still today’s sequence; notes that plan 17 Session 4 will update the row when self-hosting legs land

plans/17-self-hosting-v1.md (new)

The plan covers four progressive sessions after a schema freeze:

1. Root policy, carrier seam, parser core, first specs — including an operative-record gate: before any Markdown-canonical ID, amend MD-18’s Decision text, the CONTEXT.md resolved entry, and the interim sentence in AGENTS.md (not a note-only amendment).
2. Corpus body + anchors on real engine entrypoints.
3. Executable tracer — md → graph → generated contracts → green binding test on the Protocol itself.
4. Decisions, Design Review prose, anti-misleading doc pass, full clean-clone check sequence.

Pinned executable defaults (overturnable at Review #1):

• Exclude: repeatable --exclude with root-relative path-prefix semantics; repo recipe excludes explorations and examples so exploration dual-IDs never pollute the Protocol graph.
• Public seam: CarrierReification + promoted deriveGraph; anchors stay a third surface.
• Clean-clone check order: build → generate (self-hosting + checkout) → typecheck → test → check legs, so tracer imports of untracked generated/ work from a fresh clone.

Out of scope for this phase (tracked in the plan’s docket ledger): sdp import, checkout-v1 migration / full canonical flip, full parser-hardening baseline, markdown pack syntax.

How to read this PR

• Start with the status block and “Where to look” table in AGENTS.md if you care about agent onboarding.
• Read plan 17 Context + §1 + §5 if you care about what Session 1 will implement next.
• The rest of the plan is the session backlog, corpus sketch, and verification bar — useful, not required for merge review of this docs PR.

Test plan

• Diff is documentation-only (AGENTS.md, plans/17-self-hosting-v1.md)
• git diff --check clean
• Spot-check AGENTS opening: epistemic boundary present; no blanket ignore of letter-suffixed plans; no release claim
• Spot-check plan 17: operative-record gate; full check sequence; exclude + CarrierReification contracts; docs/concept/README.md (not a nonexistent root README)
• Confirm no accidental edits to DECISIONS.md / CONTEXT.md / package.json (those are Session 1 / Session 4 targets when plan 17 executes)

Greptile Summary

This PR updates the repo guidance and adds the drafted self-hosting plan.

• Adds plans/17-self-hosting-v1.md for the first Markdown self-hosting slice.
• Clarifies AGENTS.md around design intent, current implementation, plan selection, and check guidance.
• Ignores local .omo/ and .pi/ state directories.

Confidence Score: 5/5

This looks safe to merge.

No blocking issues found in the changed code.

No files need attention.

T-Rex Logs

What T-Rex did

• Reviewed the Docs test plan validation log to verify the code-execution contract, confirming the diff check exited with code 0, the changed-file list contains only .gitignore, AGENTS.md, and plans/17-self-hosting-v1.md, and that there were zero protected-file diffs.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
.gitignore	Adds local task-state directories to the ignore list.
AGENTS.md	Updates repo entrypoint guidance for current implementation status, plan selection, and verification.
plans/17-self-hosting-v1.md	Adds the drafted execution plan for the first self-hosting slice in the Markdown carrier.

_{Reviews (3): Last reviewed commit: "Git ignore omo and pi agent state folder..." | Re-trigger Greptile}