​

spec_id: SPEC-060 version: v0.2 status: draft authored_by: Donna date: 2026-04-30

​

SPEC-060 — Operator-Experience Memory Capture

​

Status

​

Origin

​

The five gaps

​

Gap 1 — Operator-visible effects are under-documented

​

Gap 2 — Operator confirmation moments aren’t captured

​

Gap 3 — Cross-cutting “what produced the visible result” narratives are absent

​

Gap 4 — Negative findings / dead ends are mostly absent

​

Gap 5 — Operator inputs (corrections, confirmations, direction-pivots) aren’t captured (NEW in v0.2)

​

What these gaps share

​

Goals

1. Operator-visible effects are first-class memory. Every session_delta whose work touches a surface visible to the operator carries an explicit operator_visible_effect description in operator-facing language.
2. Operator confirmations are durable. A dedicated mechanism captures Frank’s verdicts as structured, queryable records.
3. Integration narratives have a home. A delta-class for “this combo of changes produces this visible result” exists.
4. Negative findings are durable. Every wrap has a “what was tried and ruled out” section.
5. Operator inputs (corrections / confirmations / pivots) are auto-captured. Agent-driven tag at capture time; operator review batched in dashboard.

​

Non-goals

• Forcing operator-language on engineering-only deltas (backend refactor with no UX impact). Scoped to surface-touching work.
• Rewriting historical deltas. SPEC-060 is forward-looking; backfill is out of scope.
• Capturing every prompt verbatim. Routine acks, single-token responses, and conversational chatter are explicitly skipped — only state-change prompts.
• Replacing free-form summaries. The new fields supplement, they don’t supplant.

​

Architecture

​

§3.1 — prism_confirm verb (Gap 2 fix)

prism_confirm(
  pid="PID-PGR01",
  refers_to="delta:2901d7ce" | "signal:<id>" | "spec:SPEC-XYZ" | "commit:<sha>",
  verdict="works" | "broken" | "partial",
  notes="inline note appears above input bar in Codex TUI showing persona+project; rendered when turn/steer fires during active turn"
)

CREATE TABLE operator_confirmations (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id       UUID NOT NULL REFERENCES tenants(id),
    project_id      UUID NOT NULL REFERENCES projects(id),
    refers_to_kind  TEXT NOT NULL,
    refers_to_id    TEXT NOT NULL,
    verdict         TEXT NOT NULL,
    notes           TEXT,
    confirmed_by    TEXT NOT NULL,
    confirmed_via   TEXT NOT NULL,
    confirmed_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX ix_operator_confirmations_refers_to ON operator_confirmations(refers_to_kind, refers_to_id);

​

§3.2 — Mandatory operator_visible_effect on UX-surface deltas (Gap 1 fix)

ALTER TABLE session_deltas ADD COLUMN operator_visible_effect TEXT;

• bin/coder.{sh,ps1}, bin/statusline-claude-code.sh
• cli/src/statusline.ts, cli/src/index.ts editor MCP block writes
• mcp-node/src/strategies/, mcp-node/src/surfaces/, mcp-node/src/bootstrap/channel_bridge.ts
• mcp-node/src/signalCache.ts, dashboard/web/
• backend prism_start / prism_status / prism_whois rendering paths

​

§3.3 — Integration-narrative delta class (Gap 3 fix)

1. What does the operator see now that they didn’t before?
2. What pieces had to land together to produce that? (list of delta IDs / commit SHAs / spec IDs)
3. What would break it? (cross-cutting invariants that future ports/refactors must preserve)

​

§3.4 — Negative-findings discipline (Gap 4 fix)

[
  {
    "approach": "title-watcher daemon to render persona+project in terminal title",
    "outcome": "visually clobbers richer initial title every 1s",
    "ruled_out_in_delta": "fd4d1895"
  }
]

​

§3.5 — Dashboard panel: confirmation rate

​

§3.6 — Operator-input capture (Gap 5 fix, NEW in v0.2)

​

Three prompt classes (closed enum)

​

Capture mechanism — agent-driven auto-tag

prism_operator_input(
  pid="PID-PGR01",
  class="correction" | "confirmation" | "direction_pivot",
  prompt_text="<verbatim Frank typed>",
  triggered_action="<one line: what the agent was doing or about to do>",
  reverses_delta="<delta_id if a correction reverses a specific prior delta>",
  confidence="high" | "low"
)

​

Schema

CREATE TABLE operator_inputs (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id       UUID NOT NULL REFERENCES tenants(id),
    project_id      UUID NOT NULL REFERENCES projects(id),
    captured_via    TEXT NOT NULL,             -- agent persona that captured
    captured_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    class           TEXT NOT NULL CHECK (class IN ('correction','confirmation','direction_pivot')),
    prompt_text     TEXT NOT NULL,
    triggered_action TEXT,
    reverses_delta  UUID REFERENCES session_deltas(id),
    confidence      TEXT NOT NULL CHECK (confidence IN ('high','low')),
    operator_review TEXT CHECK (operator_review IN ('accepted','rejected') OR operator_review IS NULL),
    reviewed_at     TIMESTAMPTZ
);
CREATE INDEX ix_operator_inputs_class_created ON operator_inputs(class, captured_at DESC);
CREATE INDEX ix_operator_inputs_unreviewed ON operator_inputs(captured_at DESC) WHERE operator_review IS NULL;

​

Operator review loop

​

What this solves

• Training-grade labels without operator friction at capture time.
• Repeated-mistake detection (e.g., this session’s “Donna kept going git-first; Frank corrected 5 times” pattern would be a single SQL query in the dashboard).
• prism_vs_native data — confirmation count vs correction count per agent surface is the cleanest single quality metric we’d have.

​

Invariants

• Routine acks NEVER captured. Agent’s job to filter at write time.
• Operator can manually fire the verb if they want — useful for retroactive labels (“that thing yesterday — that was a correction, btw”).
• confidence='low' rows always require review before counting toward agent quality metrics.
• Rejected misclassifications are NOT deleted — they become part of the training corpus showing what NOT to tag.

​

Files changed

​

Acceptance criteria

1. prism_confirm callable; row persists; semantic_recall returns confirmation when target is queried.
2. prism_operator_input callable; row persists; trigraph edge written; review loop accept/reject works.
3. Wrap touching bin/coder.sh (or any allowlisted file) with empty operator_visible_effect emits a non-blocking warning.
4. At least 5 historical “working state” moments retroactively captured via prism_confirm in the first week post-deploy.
5. The tried_and_ruled_out field is populated on all wraps in the first month touching launcher or signal-pipeline surfaces.
6. Dashboard shows non-zero confirmation rate, unreviewed-inputs queue, and at least one captured correction within 24h of merge.
7. Headline test: semantic_recall("Codex inline statusline working state Frank confirmed") returns at least one confirmation row in top-5, where today the same query returns engineering-vocabulary deltas only.
8. Headline test §3.6: semantic_recall("Frank corrected Donna for going to git instead of memory") returns the relevant operator_input rows with class=‘correction’. Today this query returns nothing because the labels don’t exist.

​

Phased rollout

​

Out of scope

• Backfilling historical deltas with operator_visible_effect or retroactive operator_inputs.
• Auto-generating operator_visible_effect via LLM. Keep it human-authored to preserve fidelity.
• Multi-operator support (multiple Franks). Single-operator assumption is fine for v1.
• Verbatim conversation transcript capture. State-change prompts only.

​

Lessons learned (this session, embedded as Frank’s standing convention)

1. Engineering vocabulary doesn’t retrieve by visual outcome. The mechanism Texi shipped was in memory — but searchable only via engineering terms (turn/steer, app_server_inject). Operator-visible effect captured at write time would have ranked it #1 on query #1.
2. The operator’s affirmation IS the test result. No CI test, no smoke output, no internal verification matters as much as “Frank looked at it and said it works.” That datum is the most valuable single piece of memory the system can hold.
3. Memory hygiene is a writer-side problem, not a reader-side problem. I kept “improving” my queries. The actual fix is improving what gets written.
4. Operator corrections are training data the system already produces but throws away (NEW in v0.2). Five+ corrections this session, zero captured. The agent has full context at the moment the correction lands; the cost of prism_operator_input is one tool call per state-change prompt; the value is a permanent, queryable, training-grade label corpus.

​

References

• Specs: SPEC-020 (tri-graph), SPEC-052 (per-identity signal cache), SPEC-057 (prism_start opening), SPEC-058 (signal delivery SSoT), SPEC-059 (tri-graph activation + memory tokenomics).
• Triggering deltas: 2901d7ce (the working turn/steer + turn/start mechanism, accurate but UX-blind), 8b148959 (Texi’s reverse-engineering this week), 1e030e17 (regression diagnosis), journal #7 (terminology cleanup today).
• Memories filed this session:
  • feedback_memory_first_for_historical — query memory before git/SQL
  • feedback_use_existing_verbs_not_manual — use verbs, not manual lane
  • feedback_quoting_across_shell_layers — shell-layer quoting hygiene
  • SPEC-060 is the structural follow-up that addresses the writer-side cause of the same retrieval failures these feedback memories tried to fix on the reader side.

​

Authorship