mosaicstack/stack
1
0
Fork 1
Code Issues 143 Pull Requests 5 Actions Packages Projects Releases 15 Wiki Activity

feat(agent-reflection): durable kernel — reflection.v1 capture + risk-floor + Phase-0 #545

Merged
jason.woltje merged 1 commits from feat/agent-reflection-loop into main 2026-06-16 21:35:41 +00:00
Conversation 0 Commits 1 Files Changed 17
+1498
jason.woltje commented 2026-06-16 20:56:31 +00:00
Owner
Copy Link
Copy Source

Summary

Bakes in the durable kernel of the agent reflection loop. Passive end-of-run capture of the doer's end-state as structured reflection.v1 data, plus a deterministic diff review risk-floor. The closed calibration / skill-synthesis loop (design §7–§8) stays gated behind Phase-0 experiments P1/P2/P3.

Spec: docs/plans/agent-reflection-loop-PRD.md · Tasks: docs/tasks/544-agent-reflection-loop.md

What's included

  • packages/macp — evaluateRiskFloor (pure, deterministic surface classifier; auth/data/infra → review) + reflection.v1.schema.json. 15 unit tests.
  • packages/types — reflection.v1 zod schemas + ReflectionSelfReportDto. 10 unit tests.
  • packages/mosaic/framework — fail-closed Stop hook (reflect-stop-hook.sh) writing the sidecar, registered as hooks.Stop in runtime/claude/settings.json. Strict no-op unless REFLECTION_MODE=solo|orchestrated; never blocks or fails a session, never emits a decision.
  • scripts/analysis — P1/P2/P3 experiment harnesses with pre-registered kill conditions + structured output.

Design notes

  • Mechanical vs self-reported. Hook writes mechanical fields (risk, files_changed, ids, provenance); self-report (confidence, most_likely_wrong, known_not_in_diff) is merged from an optional $REFLECTION_INPUT, else null + provenance.degraded=true.
  • Risk-floor authority is the TS evaluateRiskFloor; the hook ports the same surface table inline to stay node/build-free, documented as kept in sync.
  • Hook registration is in the canonical settings.json (the settings-overlays/ dir has no merge mechanism — would be inert).

Verification

  • macp: 88 tests pass (15 new) · types: 64 tests pass (10 new).
  • Root pnpm typecheck / lint / format:check / build — all green.
  • Stop hook smoke: fail-closed no-op, solo capture (degraded), self-report merge, re-fire lock guard, empty-diff still writes — all pass, always exit 0.
  • All bash shellcheck-clean.
  • Independent code review passed after remediating 2 findings (empty/all-.mosaic diff no longer aborts the write; session_id sanitized before path use).

Activation (post-merge, not a blocker)

Hook activates only when a launcher/profile sets REFLECTION_MODE; unset/off is a strict no-op, so global registration is safe. framework/install.sh rsyncs the hook; the mosaic launcher reflects the updated settings.json into ~/.claude/settings.json.

Closes #544

Fixes #544

## Summary Bakes in the **durable kernel** of the agent reflection loop. Passive end-of-run capture of the doer's end-state as structured `reflection.v1` data, plus a deterministic diff **review risk-floor**. The closed calibration / skill-synthesis loop (design §7–§8) stays **gated** behind Phase-0 experiments P1/P2/P3. Spec: `docs/plans/agent-reflection-loop-PRD.md` · Tasks: `docs/tasks/544-agent-reflection-loop.md` ## What's included - **`packages/macp`** — `evaluateRiskFloor` (pure, deterministic surface classifier; auth/data/infra → review) + `reflection.v1.schema.json`. 15 unit tests. - **`packages/types`** — `reflection.v1` zod schemas + `ReflectionSelfReportDto`. 10 unit tests. - **`packages/mosaic/framework`** — fail-closed Stop hook (`reflect-stop-hook.sh`) writing the sidecar, registered as `hooks.Stop` in `runtime/claude/settings.json`. **Strict no-op unless `REFLECTION_MODE=solo|orchestrated`**; never blocks or fails a session, never emits a `decision`. - **`scripts/analysis`** — P1/P2/P3 experiment harnesses with pre-registered kill conditions + structured output. ## Design notes - **Mechanical vs self-reported.** Hook writes mechanical fields (risk, files_changed, ids, provenance); self-report (confidence, most_likely_wrong, known_not_in_diff) is merged from an optional `$REFLECTION_INPUT`, else null + `provenance.degraded=true`. - **Risk-floor authority** is the TS `evaluateRiskFloor`; the hook ports the same surface table inline to stay node/build-free, documented as kept in sync. - **Hook registration** is in the canonical `settings.json` (the `settings-overlays/` dir has no merge mechanism — would be inert). ## Verification - macp: 88 tests pass (15 new) · types: 64 tests pass (10 new). - Root `pnpm typecheck` / `lint` / `format:check` / `build` — all green. - Stop hook smoke: fail-closed no-op, solo capture (degraded), self-report merge, re-fire lock guard, empty-diff still writes — all pass, always exit 0. - All bash shellcheck-clean. - Independent code review passed after remediating 2 findings (empty/all-`.mosaic` diff no longer aborts the write; `session_id` sanitized before path use). ## Activation (post-merge, not a blocker) Hook activates only when a launcher/profile sets `REFLECTION_MODE`; unset/`off` is a strict no-op, so global registration is safe. `framework/install.sh` rsyncs the hook; the `mosaic` launcher reflects the updated `settings.json` into `~/.claude/settings.json`. Closes #544 Fixes #544
jason.woltje added 1 commit 2026-06-16 20:56:32 +00:00
feat(agent-reflection): durable kernel — reflection.v1 capture + risk-floor + Phase-0 (#544)
ci/woodpecker/push/ci Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details
b76666166e 
Build the durable kernel of the agent reflection loop. Passive end-of-run
capture of the doer's end-state as structured `reflection.v1` data, plus a
deterministic diff review risk-floor. The closed calibration/skill-synthesis
loop (design §7–§8) stays gated behind Phase-0 experiments P1/P2/P3.

- packages/macp: evaluateRiskFloor (pure, deterministic surface classifier)
  + reflection.v1 JSON Schema; 15 unit tests.
- packages/types: reflection.v1 zod schemas + self-report DTO; 10 unit tests.
- framework: fail-closed Stop hook (reflect-stop-hook.sh) writing the sidecar,
  registered as hooks.Stop in runtime/claude/settings.json. Strict no-op unless
  REFLECTION_MODE=solo|orchestrated; never blocks or fails a session.
- scripts/analysis: P1/P2/P3 experiment harnesses with pre-registered kill
  conditions and structured output.

Mechanical fields (risk, files_changed, ids, provenance) are written by the
hook; self-report fields (confidence, most_likely_wrong, known_not_in_diff) are
merged from an optional $REFLECTION_INPUT, else null + provenance.degraded=true.

Independent review remediations: empty/all-.mosaic diff still writes a sidecar
(grep no-match no longer aborts); session_id sanitized before path use.

Refs #544

Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje merged commit b8807e60df into main 2026-06-16 21:35:41 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
coder-mos1 coder-mos2 f10-coder jason.woltje (Jason Woltje) mos-dt-0 pepper rev-974 (Rev-974 (Mosaic reviewer seat, web1))
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#545