From 9e6f8a6e08a9914aa581d66f902a7e83592f86b1 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 7 Jun 2026 14:58:03 +0200 Subject: [PATCH] Register WP-0007 (Distribute), WP-0008 (Read-before-Edit), WP-0009 (Measure) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three workplans queued and registered with the State Hub (via REST — MCP write layer is erroring this session): - AGENTIC-WP-0007 Phase 3 Distribute: per-flavor distributor adapters render approved catalog patterns into proposed (HITL) artifacts, scoped by repo/domain. - AGENTIC-WP-0008 Read-before-Edit reflex: act on the #1 friction finding. - AGENTIC-WP-0009 Phase 4 Measure: baseline + before/after effectiveness + trend. Proceeding in that order. Co-Authored-By: Claude Opus 4.8 --- .../AGENTIC-WP-0007-session-memory-phase3.md | 100 ++++++++++++++++++ ...AGENTIC-WP-0008-read-before-edit-reflex.md | 56 ++++++++++ .../AGENTIC-WP-0009-session-memory-phase4.md | 68 ++++++++++++ 3 files changed, 224 insertions(+) create mode 100644 workplans/AGENTIC-WP-0007-session-memory-phase3.md create mode 100644 workplans/AGENTIC-WP-0008-read-before-edit-reflex.md create mode 100644 workplans/AGENTIC-WP-0009-session-memory-phase4.md diff --git a/workplans/AGENTIC-WP-0007-session-memory-phase3.md b/workplans/AGENTIC-WP-0007-session-memory-phase3.md new file mode 100644 index 0000000..fe59b30 --- /dev/null +++ b/workplans/AGENTIC-WP-0007-session-memory-phase3.md @@ -0,0 +1,100 @@ +--- +id: AGENTIC-WP-0007 +type: workplan +title: "Coding Session Memory — Phase 3 (Distribute: per-flavor artifacts, HITL)" +domain: helix_forge +repo: agentic-resources +status: ready +owner: codex +topic_slug: helix-forge +created: "2026-06-07" +updated: "2026-06-07" +state_hub_workstream_id: "766c9089-d5de-472a-8c0f-85529028cfb9" +--- + +# Coding Session Memory — Phase 3 (Distribute) + +Implements **Distribute** (PRD §6.4, FR-X1–FR-X4), continuing +[AGENTIC-WP-0004](AGENTIC-WP-0004-session-memory-phase2.md) (Curate). Distributor +adapters render the **approved / `distribution_ready`** SolutionPatterns from the +Pattern Catalog into per-flavor artifacts, using the `rendering_hints` produced in +Phase 2. Mirror image of the collector design: **agnostic core, thin adapters at +the edges** (FR-A2) — adding a flavor = one collector + one distributor. + +Key boundary (FR-X3): output is **proposed, not auto-applied** — artifacts are +written as reviewable proposals (HITL), scoped by repo/domain (FR-X2), with an +active-pattern registry tracking which patterns are live where (FR-X4). + +## Distributor Adapter Interface + Artifact Base + +```task +id: AGENTIC-WP-0007-T01 +status: todo +priority: high +state_hub_task_id: "ff618fa6-a78b-4b80-846b-8cde7ad65451" +``` + +Define a `Distributor` protocol and an `Artifact` dataclass (flavor, target_path, +content, pattern_id) in `session_memory/distribute/`. `render(pattern, scope)` +reads the agnostic `SolutionPattern` plus its per-flavor `rendering_hints`; base +helpers handle idempotent snippet markers. Agnostic core; flavor logic only in +adapters. Unit-tested. + +## Claude Distributor (CLAUDE.md snippet) + +```task +id: AGENTIC-WP-0007-T02 +status: todo +priority: high +state_hub_task_id: "64f50bd4-1fdf-452e-ae14-890253ab9f33" +``` + +`distribute/claude.py`: render an approved pattern into a `CLAUDE.md` snippet block +(or skill stub) with stable `BEGIN/END` markers so re-distribution updates in +place rather than duplicating. Uses `rendering_hints["claude"]`. Unit-tested. + +## Codex + Grok Distributors + +```task +id: AGENTIC-WP-0007-T03 +status: todo +priority: high +state_hub_task_id: "382790f5-1fb4-4394-b039-1649cbf3b20a" +``` + +`distribute/codex.py` (`AGENTS.md` snippet) and `distribute/grok.py` (native +instruction format), each rendering the *same* agnostic pattern via its +`rendering_hints`. Confirms FR-A3: a pattern discovered via one flavor is +expressible for all. Unit-tested. + +## Scoping + Proposed-Not-Applied Output + Active-Pattern Registry + +```task +id: AGENTIC-WP-0007-T04 +status: todo +priority: high +state_hub_task_id: "2c690f29-2aee-460a-b9cd-3566018f6b3c" +``` + +Filter patterns by `Scope` (repos/domains/flavors) so a pattern only lands where it +applies (FR-X2). Write artifacts as **proposals** under a `proposals/` dir, never +auto-applied (FR-X3, HITL). Track which patterns are active in which environments +in an active-pattern registry (FR-X4). Unit-tested. + +## Distribute Entrypoint + Tests + Verify + +```task +id: AGENTIC-WP-0007-T05 +status: todo +priority: medium +state_hub_task_id: "f9e24c13-7049-4c1c-a2d6-3a4dc4e752fd" +``` + +`python -m session_memory.distribute`: read approved catalog patterns, render +per-flavor proposals scoped by repo/domain, emit a proposal summary + JSON. +Document in `session_memory/README.md`. Verify end-to-end against the real catalog. +After workplan updates, notify the operator to run from `~/state-hub`: + +```bash +make fix-consistency REPO=agentic-resources +``` diff --git a/workplans/AGENTIC-WP-0008-read-before-edit-reflex.md b/workplans/AGENTIC-WP-0008-read-before-edit-reflex.md new file mode 100644 index 0000000..fcc5ea9 --- /dev/null +++ b/workplans/AGENTIC-WP-0008-read-before-edit-reflex.md @@ -0,0 +1,56 @@ +--- +id: AGENTIC-WP-0008 +type: workplan +title: "Act on #1 friction — Read-before-Edit reflex" +domain: helix_forge +repo: agentic-resources +status: ready +owner: codex +topic_slug: helix-forge +created: "2026-06-07" +updated: "2026-06-07" +state_hub_workstream_id: "6aac5cfc-4799-4d07-9537-42a203af2d1b" +--- + +# Act on #1 Friction — Read-before-Edit Reflex + +The error-body mining ([AGENTIC-WP-0006](AGENTIC-WP-0006-error-body-mining.md)) +found that the single most common error across real coding sessions is +**`File has not been read yet. Read it first before writing to it.`** — Edit/Write +before Read, in **12 of 27 sessions across 8 repos** — followed by the stale-read +**`File has been modified since read`** (6 sessions). See +[ASSESSMENT-infra-friction.md](../docs/ASSESSMENT-infra-friction.md). + +This is the cheapest high-value fix surfaced by the whole analysis: a short +behavioural reflex in the agent instructions. We also capture it as a curated +SolutionPattern so Phase 3 Distribute can propose it to other repos/flavors — +closing the assess → curate → distribute loop by hand for one real pattern. + +## Add Read-before-Edit Reflex to Agent Instructions + +```task +id: AGENTIC-WP-0008-T01 +status: todo +priority: high +state_hub_task_id: "549c84c1-5bd8-4ff6-b61d-1c72946b8b8e" +``` + +Add a concise, data-cited **Read-before-Edit / re-read-on-"modified since read"** +reflex to `AGENTS.md` (and note for `CLAUDE.md`), targeting the #1 and #2 recurring +errors. Keep it short to avoid context bloat (cf. PRD OQ6 — pattern bloat degrades +context budgets). + +## Capture as Curated SolutionPattern for Distribute + +```task +id: AGENTIC-WP-0008-T02 +status: todo +priority: medium +state_hub_task_id: "c007baf9-db14-40fa-b944-d1f1a71ea28b" +``` + +Promote the recurring "file not read" problem into a curated `SolutionPattern` in +the Pattern Catalog with per-flavor `rendering_hints`, so Phase 3 Distribute can +render and propose it across repos/flavors. Links assess → curate → distribute end +to end on a real pattern. After updates, notify the operator to run +`make fix-consistency REPO=agentic-resources`. diff --git a/workplans/AGENTIC-WP-0009-session-memory-phase4.md b/workplans/AGENTIC-WP-0009-session-memory-phase4.md new file mode 100644 index 0000000..0342c06 --- /dev/null +++ b/workplans/AGENTIC-WP-0009-session-memory-phase4.md @@ -0,0 +1,68 @@ +--- +id: AGENTIC-WP-0009 +type: workplan +title: "Coding Session Memory — Phase 4 (Measure: effectiveness + fleet trend)" +domain: helix_forge +repo: agentic-resources +status: ready +owner: codex +topic_slug: helix-forge +created: "2026-06-07" +updated: "2026-06-07" +state_hub_workstream_id: "99f1d836-3be0-40e5-9f17-63d3ecc5fcca" +--- + +# Coding Session Memory — Phase 4 (Measure) + +Implements **Measure** (PRD §6.5, FR-M1–FR-M3) — the loop-closer. After patterns +are distributed (Phase 3) and changes land (e.g. the State Hub skill +[STATE-WP-0058] and the Read-before-Edit reflex +[AGENTIC-WP-0008](AGENTIC-WP-0008-read-before-edit-reflex.md)), Measure answers: +**did it actually help?** + +Reuses what is already captured — WP-0005 tool buckets, WP-0006 error mining — so +this is computation over existing digests, not new capture. + +## Baseline Metrics Module + Persisted Baseline + +```task +id: AGENTIC-WP-0009-T01 +status: todo +priority: high +state_hub_task_id: "e5c2016a-2d51-4382-a013-7153e053e8ed" +``` + +`session_memory/measure/metrics.py`: compute fleet metrics over real sessions +(infra-overhead share, error rate, recurring-error count, schema-thrash, cost +percentiles) and persist a **timestamped baseline snapshot**. Reuses +`detect.signals.tool_bucket` and the digest `error_snippets`. Unit-tested. + +## Before/After Per-Pattern Effectiveness + +```task +id: AGENTIC-WP-0009-T02 +status: todo +priority: high +state_hub_task_id: "aa097a00-3462-41da-a137-67e1d61d8d33" +``` + +Given a change/pattern with an applied-at date, compare sessions **after** it +against the pre-change baseline (cost, error rate, infra-overhead, success) to +surface **per-pattern effectiveness** so ineffective patterns can be revised or +retired (FR-M1/FR-M2). Unit-tested. + +## Fleet-Trend Report + Entrypoint + Tests + +```task +id: AGENTIC-WP-0009-T03 +status: todo +priority: medium +state_hub_task_id: "f1147d59-2fb7-4d35-baec-b8f001bb9d62" +``` + +`python -m session_memory.measure`: fleet-level trend (is the median session +getting cheaper / more reliable over time, FR-M3) plus per-pattern effectiveness; +markdown + JSON. Document in `session_memory/README.md`. After updates, notify the +operator to run `make fix-consistency REPO=agentic-resources`. + +[STATE-WP-0058]: handed off to the state-hub repo worker