implement-spec

Every file written by a subagent during Wave 1+2 of the snappy-os launch produced ZERO eval rows. program.md §4 says "Every run writes an eval score to state/log/evals.ndjson. This is non-optional." Build work was the one hole. This verb closes it.

Any time the system dispatches a subagent to produce files against a plan section, run implement-spec. It is the build-surface of the PID loop. Without it, every implementation run is dark, the quorum gate starves, and the thesis fails silently.

Steps

1. Scope - no side effects

Read spec_ref (load the plan section). Parse targets[] (must be absolute paths under ~/projects/snappy-os/ or ~/projects/snappy-skills/ or ~/projects/snappy-kernel/). Read each target's current SHA if it exists. Nothing written yet.

2. Gate

Hard-fail if:

• spec_ref file doesn't resolve
• any targets[] path escapes the three canonicals
• brief is empty or shorter than 40 chars
• .machine_id missing (bootstrap didn't run)

3. Act - dispatch the actor

Write chain.ndjson row {action: "implement-spec-dispatch", run_id, skill: "implement-spec", spec_ref, targets, actor: "subagent-general-purpose"}.

Dispatch the subagent with a self-contained brief including: spec_ref contents, target paths, hard rules ("do not touch anything outside targets"; "do not push or commit"; "report deliverables under 400 words"). Capture its return text into state/log/dispatches/<run_id>.md.

4. Audit - auditor ≠ actor

Invoke state/bin/implement-spec-audit.ts <run_id>. The auditor:

• SHA-diffs each targets[] path post vs pre
• Scope-leak check: walks canonicals, flags any file modified in the session that isn't in targets[] (penalty 0.2)
• Stub detector: greps produced files for TODO Wave, placeholder, throw new Error("not implemented"), // stub (penalty 0.2 if any found)
• Lint chain: runs every state/lint/*.ts whose scope overlaps produced files; counts fails (penalty 0.3 × fail-fraction)
• Spec compliance: extracts bulleted requirements from spec_ref section; each bullet unmapped to a produced artifact = penalty (0.3 × unmapped-fraction)
• Syntax/typecheck: node --check for .js, npx tsc --noEmit for .ts, bash -n for .sh

Returns {score, breakdown, notes}.

5. Log + eval

append("chain", { run_id, skill: "implement-spec", action: "implement-spec-done", spec_ref, score });
score("implement-spec", run_id, {
  score: auditor.score,
  primary_issue: auditor.primary_issue,
  spec_ref,
  files_touched: auditor.files_touched.length,
  scope_leak: auditor.scope_leak,
  stub_detected: auditor.stub_detected,
  lint_fail_count: auditor.lint_fail_count,
  unmapped_spec_bullets: auditor.unmapped_bullets.length,
  mode: "auto",
});

Eval

Actor: general-purpose subagent dispatched by state/bin/implement-spec.ts. Auditor: state/bin/implement-spec-audit.ts - independent process, reads filesystem state + lint results without any reference to actor's self-reported claims.

Score formula:

score = 1.0
     - 0.2 * scope_leak         (binary: any file outside targets)
     - 0.2 * stub_detected       (binary: any stub marker found)
     - 0.3 * (lint_fails / max(lints_run, 1))
     - 0.3 * (unmapped_bullets / max(spec_bullets, 1))

Clamp to [0.0, 1.0]. A perfect run = 1.0. A run that lands every file with green lints but leaked scope once = 0.8. A run that punted the whole job with TODO stubs = 0.5. A run that wrote nothing against a spec with requirements = 0.0.

Gotchas

• Actor may self-report success while leaving stubs. The stub detector is why we read the files ourselves, not the actor's summary.
• Scope leak during test-harness reinitialization (see Wave 2: wire-hooks agent touched real ~/.codex/hooks.json during smoke, then restored). The auditor treats any write outside targets[] as a leak even if reverted - the score reflects risk, not current state.
• Spec bullets are hard to extract. The auditor uses a line-based heuristic: - **bold requirement** or 1. **bold** → bullet. Misses free-prose requirements. Accept the signal is lossy; a 0.7 score doesn't mean 30% incomplete, it means the signal is noisy. Tune via lint if too permissive.
• Parallel waves clobber each other's targets[]: if two dispatches target overlapping paths simultaneously, both see scope-leak. Enforce serial execution per-target or partition in the parent.

Graduation

Graduated on day one - has state/bin/implement-spec.ts (executor) and state/bin/implement-spec-audit.ts (auditor). No prose-only phase because this is load-bearing from the first invocation. <!-- kernel-ok: documentation of the porting process / catalog -->

Rubric

criteria:
  - name: eval_row_generated
    kind: deterministic
    check: "A new row for 'implement-spec' with a 'score' field is appended to 'state/log/evals.ndjson' at the end of execution, as indicated by 'score(\"implement-spec\", run_id, { ... })' in the skill's log+eval step."
  - name: no_scope_leak_detected
    kind: deterministic
    check: "The 'scope_leak' field in the 'implement-spec-done' chain.ndjson entry or eval row must be false, signifying that the auditor detected no unauthorized file modifications outside of the specified 'targets[]' by checking all canonical paths."
  - name: auditor_invoked_correctly
    kind: deterministic
    check: "The skill invokes 'state/bin/implement-spec-audit.ts <run_id>' before logging the final 'implement-spec-done' event, and the auditor's return data '{score, breakdown, notes}' is used to populate the eval row fields."
  - name: no_stub_code_introduced
    kind: deterministic
    check: "The 'stub_detected' field in the 'implement-spec-done' chain.ndjson entry or eval row must be false, indicating that the auditor did not find any placeholder text like 'TODO Wave' or 'not implemented' within the produced files."

implement-spec - loader

Per-turn rules for the implement-spec skill. Full reference: state/skills/implement-spec/SKILL.md. Do not skip these.

Critical Rules

• NEVER trust the actor's self-summary - re-read produced files and SHA-diff them yourself
• NEVER allow writes outside targets[] - any escape is a 0.2 scope-leak penalty even if reverted
• ALWAYS dispatch the auditor as a separate process (implement-spec-audit.ts) - actor ≠ auditor or the score is invalid
• ALWAYS hard-fail Step 2 gate if brief is shorter than 40 chars or .machine_id is missing
• Serialize parallel dispatches that touch overlapping targets[] - concurrent waves both register scope-leak

Commands

| ui dashboard | state/skills/implement-spec/resources/ui.openui | |invoke: npx tsx state/bin/implement-spec.ts <spec_ref> <targets...> <brief> |audit: npx tsx state/bin/implement-spec-audit.ts <run_id> |eval log: state/log/evals.ndjson (skill: "implement-spec") |dispatch transcript: state/log/dispatches/<run_id>.md

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/implement-spec/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Stub markers (TODO Wave, placeholder, throw new Error("not implemented"), // stub) ship inside files an actor reports as complete - the stub detector exists because actor summaries lie
• Spec-bullet extraction is line-based heuristic (- **bold** only); free-prose requirements are missed, so a 0.7 score means noisy signal not exactly 30% incomplete
• A wire-hooks-style test that touches real config then "restores" still scores as scope-leak - risk is what's measured, not current state

Self-Test

An agent reading this should correctly:

1. [ ] Refuse to score a run where the same script generated and audited?
2. [ ] Reject a brief under 40 chars at the gate?
3. [ ] Locate the executor at state/bin/implement-spec.ts and the auditor at state/bin/implement-spec-audit.ts?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] implement-spec: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] implement-spec: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.