phase-trace

state/lib/phase-trace.ts - pure in-memory accumulator. Pairs with the PhaseDisclosure shape registered in web/src/components/phase-disclosure.tsx (snappy-chat). One trace per tick, many phases per trace, optional body per phase.

The disclosure pattern matches Claude Desktop's "Cowork" layout (cd-23 in the design references): a vertical stack of rows, each with a chevron, status dot, mono label, and a one-line summary. Click any row to expand the multi-paragraph body underneath.

Steps

1. Open a trace with optional title:

   import { startTrace } from "../lib/phase-trace.ts";
   const t = startTrace("Charlotte execute");

1. Add phases as the work progresses. Each .phase(label, opts) returns

a fluent handle:

   const p = t.phase("Loaded tools", { summary: "Probing connectors", status: "running" });
   p.body("Now let me probe the actual connector data shapes...");
   p.done();

1. When the tick finishes, emit() returns the canonical payload shape:

   const { phaseDisclosure } = t.emit();
   // → { phases: [{ label, summary, body?, status? }, ...], title? }

1. The dispatcher in state/bin/head-screen/server.ts wraps the payload

in a TOOL_CALL_* triple keyed PhaseDisclosure and the snappy-chat surface renders the disclosure rows inline.

Status enum

pending | running | done | error. The renderer maps each to a colored status dot (text-tertiary / accent w/ glow / ok-green / danger-red).

Eval

Shape gate. The actor is startTrace().emit() and the auditor is the parser parsePhaseDisclosureArgs in web/src/tool-args.ts. A row passes if every phase has both label and summary strings and the status (when present) is in the four-value enum.

Rubric

- id: payload-shape
  kind: deterministic
  check: emit().phaseDisclosure.phases is a non-empty array of {label, summary} objects
- id: status-enum
  kind: deterministic
  check: every phase.status (when present) is one of pending|running|done|error
- id: parser-roundtrip
  kind: deterministic
  check: parsePhaseDisclosureArgs(JSON.stringify(emit().phaseDisclosure)) returns a non-null shape

phase-trace - loader

Per-turn rules for the phase-trace skill. Full reference: state/skills/phase-trace/SKILL.md.

phase-trace is the builder API long-running snappy-os skills use to accumulate phase rows (label + summary + body + status) as they work, then emit one canonical PhaseDisclosure payload at end of tick. The snappy-chat generative UI renders that payload inline as a vertical stack of collapsible disclosure rows - chevron + status dot + mono label + one-line summary, expanding to multi-paragraph body. Visual pattern matches Claude Desktop's "Cowork" layout (cd-23 in design references). Pure in-memory accumulator. Pairs with web/src/components/phase-disclosure.tsx in snappy-chat. Lib: state/lib/phase-trace.ts.

Critical Rules

1. Status enum is pending|running|done|error exactly - parsePhaseDisclosureArgs in web/src/tool-args.ts kills any card with off-enum status.
2. Both label and summary are REQUIRED on every phase. body is optional; status is optional (defaults handled downstream).
3. emit() is one-shot. Call it at end of tick. Do NOT re-emit during streaming - the renderer expects one payload per trace.
4. Pure in-memory accumulator. Do NOT persist phase rows to disk; the eval row in state/log/evals.ndjson is the persistence record of record.
5. Phase ordering = insertion order. Sort upstream of t.phase() calls if you want a different display order.

Commands

| ui dashboard | state/skills/phase-trace/resources/ui.openui | |invoke: import { startTrace } from "../lib/phase-trace.ts" |usage: const t = startTrace("Charlotte execute"); const p = t.phase("Loaded tools", {summary:"Probing connectors", status:"running"}); p.body("...long body..."); p.done(); ... t.emit() returns {phaseDisclosure: {phases: [...], title?}} |dispatcher: state/bin/head-screen/server.ts - regex matcher + emitTriple("PhaseDisclosure", payload.phaseDisclosure) |trigger phrases (matched in dispatcher regex, extended at L7029): running / currently-running / happening right now |eval log: state/log/evals.ndjson (skill: "phase-trace", eval_mode: shape) |tested: 2026-04-29 end-to-end with shape PhaseDisclosure paired against snappy-chat renderer; parser roundtrip OK; dispatcher routing hooked

Status enum

Trigger phrases

• running
• currently running / currently-running
• happening right now

(Dispatcher regex extended at L7029 in state/bin/head-screen/server.ts to route these to PhaseDisclosure.)

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/phase-trace/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

• A phase missing summary fails the parser shape gate and the card is dropped silently. Always set summary, even a one-word placeholder.
• body strings can be long (multi-paragraph) - the renderer truncates inside the closed disclosure row; full text appears on expand. Don't pre-truncate upstream.
• status:"error" paints a red dot. Reserve it for actual failures; using it for "warning" or "skipped" misleads the cockpit reader.

Self-Test

An agent reading this should correctly:

1. [ ] Confirm emit() output shape matches parsePhaseDisclosureArgs (label + summary required, status enum exact)
2. [ ] Confirm phase ordering is insertion order
3. [ ] Confirm status enum is strictly pending|running|done|error
4. [ ] Confirm emit() is called once per tick, not per phase
5. [ ] Confirm trigger phrases running / currently running / happening right now route to PhaseDisclosure via the dispatcher regex

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] phase-trace: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> 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)] phase-trace: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they must be equal so state/lib/controller-tune.ts can pair the brief.

• 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.

• action_kind is the SECOND pairing predicate (added 2026-04-27, task #327).

Pick the value that describes what you actually did - same slug, different action_kind means the writeback satisfies a different brief layer:

• shape-ok - only frontmatter-shape verification passed (rare from

a human; usually emitted by the lint, not a loader echo)

• skill-ran - the skill ran end-to-end and an eval row landed

in state/log/evals.ndjson

• loader-rewritten - you EDITED this AGENTS.md inline (the FIXED case),

OR the regen drain rewrote it

• pattern-elevated - you promoted a recurring failure to a Critical Rule

(rule fix or new-skill scaffold) If you LOGGED (couldn't fix inline), omit action_kind - the inferrer will pick it up from your body keywords.

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.