Absorption Plan

Status: A1–A4 implemented (discovery, ambiguity gate + interview, semantic rung, ecosystem workers doc). Companion: harness.md (H3 hooks / H4 learning loop continue after this plan's A-phases).

Sources studied: oh-my-pi (can1357), oh-my-openagent / oh-my-claudecode (code-yeongyu, Yeachan-Heo), internal-system (Q00), Hermes (NousResearch), a presets-and-catalog library.

Identity invariants (what absorption may NOT bend)

#	invariant	the line it draws
I1	The core stays deterministic; everything generative sits behind the worker contract.	"Console vs worker" is a role label and roles blur (Yardlet already merges code, will run hooks, may ship a native API worker). The enforceable line is mechanism: the orchestrator does only deterministic, auditable operations (templating, rule routing, check-based evaluation, git plumbing, hook execution); anything that generates or judges work goes through packet → process → result files. A Yardlet-shipped worker (e.g. a native API adapter) is fine iff it lives behind that same contract and is routable/swappable like any other worker. Worker-side tool surfaces (LSP, debuggers, kernels) stay with workers — not because tools are forbidden, but because owning them would pull the console into the judgment loop.
I2	The packet is the only shared injection point.	Anything absorbed must reach codex, claude, and custom workers identically — never via one CLI's plugin system.
I3	.agents/ is canonical; sessions are disposable.	Discovered/borrowed assets are read at compile time, not copied into state. Yardlet remains the sole writer of its files.
I4	Minimize human intervention; safety comes from determinism + self-correction + reversibility, not from gates.	Yardlet's whole point is that the human steps back. Safety is not a human approving each change — it is: (a) the deterministic core is the sole writer (LLMs propose, Yardlet writes); (b) an eval feedback loop demotes/prunes what doesn't work (skill scores, routing telemetry); (c) everything is reversible (git, .agents/). Reversible, self-correcting assets — skills, learned rules, eventually routing — are applied automatically. A human gate is reserved only for the irreversible or outward-facing: push, deploy, external sends, secrets, mass deletion. Auto-by-default; opt-outs exist for the cautious.
I5	Explicit contracts over magic.	Intent / scope / acceptance / queue are visible artifacts. No keyword-triggered hidden modes.
I6	Bring-your-own CLI.	Absorption must reduce setup, not add it. Defaults stay zero-config, zero-new-billing.

What each source is, and the one thing worth taking

• oh-my-pi — a worker (Pi fork) with an IDE-grade tool surface. Its magic moment is onboarding: first run inherits rules/skills/MCP from .claude, .cursor, .windsurf, .gemini, .codex, .github/copilot… → take the inheritance idea (A1); register omp itself as a worker (A4); leave the tool surface alone (I1).
• internal-system — spec-first Agent OS with quantified gates: don't build until ambiguity ≤ threshold; verify Mechanical → Semantic → Consensus. → take the ambiguity gate (A2) and the semantic rung (A3); skip the evolutionary spec loop and consensus voting for now (cost, I5).
• oh-my-openagent / oh-my-claudecode — keyword-activated orchestration ("ultrawork"), idle-pullback "your work will definitely finish", curated agent/skill bundles. → the relentless-completion need is already served by auto-drain + partial continuation + adoption; bundles belong to H5; magic keywords rejected (I5) — Yardlet's planning gate IS the explicit version of that UX.
• Hermes — skills as procedural memory, progressive loading (absorbed in H1), agent-created skills via skill_manage (auto-write by default) → Yardlet also auto-writes, but the deterministic core is the writer (workers propose via the result contract, Yardlet records) and an eval loop self- corrects bad skills (I1, I4). See docs/skills.md.

A1 — Harness asset discovery (oh-my-pi's onboarding, Yardlet-shaped) · size M — implemented

Goal: a repo that already has agent assets gets them as a shared harness the moment Yardlet runs — zero setup, all workers.

Discovery sources, in precedence order (later never overrides earlier):

1. .agents/rules/*.md, .agents/skills/*/SKILL.md — Yardlet-native (exists, H1)
2. AGENTS.md, CLAUDE.md (repo root) — treated as a rules source
3. .claude/skills/*/SKILL.md — same format as ours (agentskills.io)
4. .cursor/rules/*.{md,mdc} — rules source
5. .github/copilot-instructions.md — rules source

Worker-aware projection (the part oh-my-pi doesn't need but we do): a worker that natively consumes a source must not get it twice — token discipline. Projection matrix in code, adapter-owned:

source	claude-code	codex	custom
CLAUDE.md	skip (native)	inject	inject
AGENTS.md	inject	skip (native)	inject
.claude/skills	skip (native)	catalog	catalog
.cursor/rules, copilot-instructions	inject	inject	inject

The matrix is the default, not a hardcoded worker list: the first-party rows are built-in declarations, and any profile can state its own via harness.native_rule_files / harness.native_skill_dirs in workers.yaml — so a custom CLI that reads AGENTS.md itself skips it too, and a skills directory it declares joins discovery for the workers that do not read it (README: Adding a worker).

Mechanics: read-only at packet compile (I3 — nothing copied into .agents/); discovered rules share the existing 4 KB inline cap (overflow → anchors); discovered skills join the catalog with an origin suffix (e.g. pr-review — … (.claude)); task.skills may name them. Parallel worktrees: these sources are tracked files, so they exist in the worktree checkout — no copying needed (verify in tests). Opt-out: harness_discovery: false in yardlet.yaml for repos where the borrowed assets are noise.

Tests: per-source discovery; precedence/dedup (same skill name in .agents and .claude → ours wins); projection matrix per worker; cap interaction.

A2 — Ambiguity gate (internal-system's "don't build while guessing") · size S — implemented

The planning schema already returns ambiguity.score (low|medium|high) and questions_for_user — today they are always non-blocking. Change:

• Persist ambiguity + open questions into the intent contract.
• score: high ⇒ the intent starts gated: run --auto/r/A refuse with "the plan is still guessing — answer its questions first"; the TUI pending slot shows the questions; a answers (existing flow) and the answer triggers a re-plan (amend) that re-scores ambiguity.
• Explicit override (I5 — the human can always decide): yardlet run --auto --accept-ambiguity, or ambiguity_gate: off in yardlet.yaml. medium/low: unchanged (non-blocking, assumptions recorded).
• Interview loop (owner request): when the request is thin (high ambiguity, or a very short raw request), planning becomes a bounded Q&A conversation instead of a one-shot guess — the TUI surfaces the planner's questions, each answer triggers an amend-style re-plan that re-scores ambiguity, and the loop continues until the score drops below high, the user says "proceed as is", or a hard cap of 10 turns. Each turn is a planning-worker invocation, so re-plans ride the cheaper amend path with the prior plan as context, and the loop only engages when the gate triggers (not on every plan).

No new scoring math (internal-system's weighted-clarity formula stays theirs); we gate on the planner's own self-report, which we already collect. Mechanism = deterministic gate; policy = the user's answer. (I4, I5)

A3 — Semantic verification rung (internal-system's ladder, bounded) · size S — implemented

Yardlet's evaluator is the Mechanical rung (schema, ids, drift, forbidden paths). Add the Semantic rung as a task, not a smarter evaluator (I1):

• Deterministic rule at queue derivation: if any task has risk: high (or the intent has 3+ tasks) and the plan contains no review-kind task, Yardlet appends one final Acceptance review task (reviewer role, depends_on = all prior tasks) that verifies the intent's acceptance criteria against the actual workspace and reports per-criterion pass/fail.
• The planner prompt also asks for it, but the deterministic append is the guarantee — planner forgetfulness can't skip verification.

Consensus rung (multi-worker vote): deferred — it doubles spend; revisit when routing telemetry can justify it per task kind.

A4 — Workers from the ecosystem (docs only) · size XS — implemented

README "Adding a worker" gains real examples: oh-my-pi (omp) and other agent CLIs as generic-adapter profiles — the ecosystem's workers are Yardlet's supply side, not competition. No code.

Sequence & where this meets the harness plan

A1 discovery ──► A2 ambiguity gate ──► A3 semantic rung ──► (A4 docs, anytime)
        └─► then back to harness.md: H3 hooks ──► H4 learning loop

A1 first: it multiplies the value of every later phase (H4's promoted lessons, A3's review tasks all ride the same discovery-fed packet). A2/A3 are small and independent. H3/H4 resume after, unchanged.

Explicitly rejected (and why)

• Magic keywords / hidden modes — I5. The planning gate is Yardlet's explicit answer to the same need.
• Worker-grade tool surface (LSP, debugger, kernels, browser) — I1. Owning them would pull the deterministic core into the judgment loop; Yardlet benefits by registering the winners as workers instead.
• Worker self-writing canonical state directly — I3. Workers propose (result contract); the deterministic core writes. Auto-application is fine; bypassing the single writer is not.
• Unbounded self-rewrite of specs/intent (internal-system generational rewrite) — the intent contract is the user's; skills/rules self-improve, the contract does not rewrite itself.
• Consensus voting — cost without telemetry-backed justification yet.
• Curated mega-bundles (19 agents / 39 skills) — H5 central-core territory; premature before the in-repo loop proves itself.