zugzbot 1.0.21 → 1.0.23

package/.opencode/oh-my-design/data/architecture-proposals/1.7.2-recommend-install-feedback.md

@@ -1,614 +0,0 @@
-# Release 1.7.2 — Recommend→Install Gap Closure + Self-Reinforcing DESIGN.md Loop
-
-**Status:** Proposal (internal — excluded from npm tarball by release-hygiene)
-**Author:** system architect
-**Date:** 2026-06-09
-**Target version:** 1.7.2 (with carve-outs to 1.8.0 — see §6)
-
----
-
-## Revision note (v2)
-
-This revision corrects three load-bearing errors found in adversarial review and re-scopes the release:
-
-1. **Pillar A decision was backwards — flipped A2 → A1.** The chosen A2 (lazy-resolve the reference from the
-   installed package tree via `require.resolve`) is *broken for the documented primary audience*. Official
-   onboarding is bare `npx oh-my-design-cli install-skills` (not `npm i`), so `oh-my-design-cli` is **never**
-   written to the project's `node_modules` — it runs from the transient npx cache that is GC'd after the run.
-   `require.resolve` then throws `MODULE_NOT_FOUND`, the resolver falls through to the absent dev path, exits
-   1, and the bug is **not** fixed. The only moment the reference `DESIGN.md` is reachable is *during* the
-   install run, so install-skills must **copy** it into the project. We now choose **A1 (copy the chosen
-   reference's `DESIGN.md` at install time)**. The inflated "18 MB" size claim is corrected to **markdown
-   only, ~6 MB** (assets are not copied), and a `--no-references` lean flag is added. The resolver script is
-   kept as a fallback chain whose *primary* hit is now the install-copied path.
-2. **Pillar C scoring kept multiplicative.** The proposed additive `w_freq*count + w_rec*Σexp + w_rel*rel`
-   (with `w_rel`=0.5) silently changed behavior and made AC-C6 unsatisfiable. We keep the existing
-   **multiplicative** `count × importanceAvg × recency × 10` core, add the relevance term only as an optional
-   factor gated behind `w_rel` that **defaults to 0**, and explicitly preserve the **`importanceAvg ≥ 2.5`
-   floor** (synced to `src/core/memory.ts`).
-3. **Over-engineered parts deferred to 1.8.0.** Pillar B (need-detector — unvalidated thresholds + a
-   mis-grouped precedence bug in the guard), the `w_rel` relevance *weighting*, the Self-Consistency
-   vote-gate, and the correction-rate reinforcement all move to 1.8.0. The cheap `OMD_TRIGGER=task-complete`
-   trigger stays in 1.7.2 (it fills the real task-context gap). The archive-prune pass moves out of
-   `omd-learn` Phase 5 ("결과 요약", a semantic mismatch) into a dedicated **Phase 6 "prune."**
-
-**Net 1.7.2 scope:** Pillar A (A1) + the deterministic, human-gated consolidation core of Pillar C
-(task-complete trigger + conflict-resolution + prune; multiplicative scoring with `w_rel`=0).
-**1.8.0:** Pillar B + `w_rel` weighting + vote-gate + correction-rate reinforcement.
-
----
-
-## Executive summary
-
-This release does two things, in priority order:
-
-1. **Pillar A (BUG, must ship):** The `recommend → approve → install` chain is broken for npx/installed
-   users. `omd-init` Phase 4.1 reads the chosen reference `DESIGN.md` from one of three paths, but
-   `install-skills.ts` never lands it at path 1 (`.claude/data/references/<id>/DESIGN.md`), and paths 2–3
-   only resolve in the omd dev repo or a vanilla npm layout. Because the documented onboarding is bare
-   `npx oh-my-design-cli install-skills` (no `node_modules`), lazy package-tree resolution cannot work — the
-   package tree vanishes after the npx run. We **close this with option A1 (copy the chosen reference's
-   `DESIGN.md` into `.claude/data/references/<id>/DESIGN.md` at install time)** plus a **fallback resolver**
-   whose primary hit is that copied path. Install weight: **~6 MB of markdown** if all references are copied
-   for offline browsing, or only the consumed reference per project; a `--no-references` flag opts out.
-2. **Pillar C (the core):** Make DESIGN.md **measurably strengthen with use** by layering a
-   recurrence-scored promotion loop on the existing `remember → learn → foldin` chain, with an explicit
-   **conflict-resolution** step. Scoring stays the existing **multiplicative** ACT-R-style
-   `count × importanceAvg × recency × 10` with its `importanceAvg ≥ 2.5` floor; an optional relevance factor
-   is wired behind `w_rel` (default 0, inert in 1.7.2). Grounded only in *verified* research (Reflexion,
-   Generative-Agents memory-stream/reflection, Constitutional-AI critique→revise, ACT-R recency×frequency).
-   The unverified Hermes marketing numbers are **not** cited as fact.
-
-**Deferred to 1.8.0:** the **DESIGN.md-need detector (Pillar B)**, the `w_rel` relevance *weighting* term,
-the Self-Consistency vote-gate, and the correction-rate reinforcement feedback signal — each needs real
-usage data to tune, or carries an unvalidated/mis-specified heuristic. See §6.4.
-
-**Verdict on post-task consolidation (§5):** **YES, but minimal** — do *not* add a new hook or a new
-`omd:consolidate` skill. Extend the existing `session-end-foldin.cjs` to *also* fire on an explicit
-`epic-complete` / `task-complete` signal written to `.omd/timeline.md`, and have `omd-apply` emit that
-signal when a design task closes. Reuses 100% of existing fold-in machinery.
-
----
-
-## Pillar A — Close the install gap (the only confirmed hard bug)
-
-### A.0 What's actually broken
-
-`omd-init` Phase 4.1 (`skills/omd-init/SKILL.md:87-97`) resolves the chosen reference's `DESIGN.md` via:
-
-```
-1. .claude/data/references/<id>/DESIGN.md          ← never created by install-skills
-2. node_modules/oh-my-design-cli/web/references/<id>/DESIGN.md   ← exists in tarball, but path is brittle
-3. web/references/<id>/DESIGN.md                    ← only in the omd dev repo
-```
-
-- **Path 1** is never populated: `install-skills.ts` `installDataFile()` (`:421-459`) only copies the 5
-  flat `data/*.json` files (`dataFiles` array `:753-759`); there is no code that creates
-  `.claude/data/references/<id>/`.
-- **Path 2** exists in the published tarball (`package.json files[]` ships `web/references/*/DESIGN.md`),
-  but the hardcoded `node_modules/oh-my-design-cli/...` string fails for pnpm/yarn-PnP nested layouts,
-  monorepo hoisting, global installs, git installs, and bundled agents.
-- **Path 3** only resolves when cwd is the omd source repo.
-
-Result: for the *primary* audience (npx-installed projects), the recommend flow succeeds through Phase 3,
-then Phase 4.1 fails to read any `DESIGN.md` and Phase 5 generates from nothing.
-
-### A.1 Decision: A1 (copy reference DESIGN.md at install time) over A2 (lazy-resolve from package tree)
-
-| | A1 — copy `web/references/*/DESIGN.md` into `.claude/data/references/` at install | A2 — at `omd:init`, resolve the chosen `<id>` from the installed package tree |
-|---|---|---|
-| Works for **bare `npx install-skills`** (the documented primary path) | **yes** — copied during the install run, before the npx cache is GC'd | **no** — `require.resolve('oh-my-design-cli/...')` throws `MODULE_NOT_FOUND`; no `node_modules` exists |
-| Install size added | **markdown only, ~6 MB** (221 × ~27 KB DESIGN.md; **no assets copied**), or just the consumed reference | 0 bytes |
-| Files written per project | 221 markdown files (or 1 with the lean future option) | 0 at install; 1 read at init |
-| Works offline after install | yes | only if the package survives in `node_modules` (npx flow: it does not) |
-| Moving parts | low (one `cpSync` of `*/DESIGN.md`) | medium (package-root resolution that cannot resolve post-npx) |
-| Drift / staleness | re-run `omd install-skills --force` (same as skills) | n/a (but unusable for npx) |
-
-**Chosen: A1.** The deciding factor is correctness for the *documented primary audience*. Official onboarding
-is bare `npx oh-my-design-cli install-skills` — it never runs `npm i`, so `oh-my-design-cli` is never written
-to the project's `node_modules`; it executes from the transient npx cache that is garbage-collected after the
-run. Under A2, `require.resolve('oh-my-design-cli/package.json', { paths:[projectDir] })` therefore throws
-`MODULE_NOT_FOUND`, the resolver falls through to the absent dev path, and exits 1 → the bug is **not** fixed.
-(Stamping the package-root path into a json file fails for the same reason: for pure-npx that path *is* the
-transient cache, which is unstable and GC'd.) The only moment the reference `DESIGN.md` files are reachable is
-**during the install run**, so install-skills must **copy** them into the project then.
-
-A1 is the only option that is both **offline-safe** *and* **npx-safe**. For a design tool whose references
-*are* the product, **~6 MB of local markdown** (DESIGN.md only — assets are not copied) is acceptable; the
-earlier "18 MB" figure was inflated and assumed assets. Drift is handled exactly like skills: re-run
-`omd install-skills --force`.
-
-- **Lean opt-out (1.7.2):** add a `--no-references` install flag. Default = copy references; with the flag,
-  no reference markdown is written and the skill surfaces the recovery message if one is later needed.
-- **Future lean default (post-1.7.2, not now):** a lazy `npx oh-my-design-cli add-reference <id>` that fetches
-  a single reference on demand. We do **not** make this the 1.7.2 default — it reintroduces a network/registry
-  dependency the offline path must not require.
-
-> We explicitly do **not** fetch from the npm *registry* over the network in 1.7.2. The reference markdown is
-> copied from the package tree *during the install run*, so the flow stays offline-safe and CI-safe.
-
-### A.2 Concrete change 1 — a fallback resolver (new, shared)
-
-The resolver is still the right Phase 4.1 path resolver, but its role changes under A1: it is now a
-**fallback chain whose PRIMARY hit is the install-copied path** (`.claude/data/references/<id>/DESIGN.md`),
-which — because install-skills now copies it (A.3) — **actually exists** for the npx audience. Candidate-2
-(`require.resolve`) stays as a *secondary* fallback for the `npm i` dependency layout (and pnpm/yarn/global),
-and candidate-3 covers the dev repo. The runtime resolution happens inside the skill (skills have no TS
-runtime), so we ship it as a small cjs helper the skill invokes.
-
-**New file:** `scripts/omd-resolve-ref.cjs` (add to `package.json files[]` and to the hook/script install
-list at `install-skills.ts:774-785`).
-
-```js
-#!/usr/bin/env node
-// Resolve a reference DESIGN.md path for a given <id>, regardless of install layout.
-// Usage: node omd-resolve-ref.cjs <id>  → prints absolute path or exits 1.
-'use strict';
-const fs = require('node:fs');
-const path = require('node:path');
-const id = process.argv[2];
-if (!id || !/^[a-z0-9._-]+$/i.test(id)) { process.exit(2); } // path-traversal guard
-const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-
-const candidates = [];
-// 1. PRIMARY: project-local copy written by install-skills (A1). The hit for the npx audience.
-candidates.push(path.join(projectDir, '.claude', 'data', 'references', id, 'DESIGN.md'));
-// 2. SECONDARY fallback: resolve the installed package root via Node's own resolver
-//    (only works under `npm i`/pnpm/yarn/global — NOT under bare npx, where there is no node_modules)
-try {
-  const pkgJson = require.resolve('oh-my-design-cli/package.json', { paths: [projectDir] });
-  candidates.push(path.join(path.dirname(pkgJson), 'web', 'references', id, 'DESIGN.md'));
-} catch { /* not resolvable as a dep — fall through */ }
-// 3. dev repo
-candidates.push(path.join(projectDir, 'web', 'references', id, 'DESIGN.md'));
-
-for (const c of candidates) {
-  if (fs.existsSync(c)) { process.stdout.write(c); process.exit(0); }
-}
-process.stderr.write(`omd: reference '${id}' DESIGN.md not found in any known location\n`);
-process.exit(1);
-```
-
-Why the fallback is robust where it applies: `require.resolve('oh-my-design-cli/package.json', { paths:
-[projectDir] })` delegates to Node's module resolution, which correctly handles pnpm symlink farms, yarn
-hoisting, monorepo workspaces, and `npm root -g` global installs — replacing a hardcoded
-`node_modules/oh-my-design-cli` string. The `paths: [projectDir]` anchor makes it resolve relative to the
-user's project. **But it only fires when the package is actually installed as a dependency** — under bare
-`npx install-skills` there is no `node_modules`, so candidate-2 throws and candidate-1 (the copied path) is
-what carries the npx flow. This is exactly why A1's install-time copy is required, not optional.
-
-#### A.2a Concrete change 1b — copy reference DESIGN.md at install (A1, the actual fix)
-
-The decisive change is in `install-skills.ts`: during the install run, copy each reference's `DESIGN.md`
-into the project so candidate-1 resolves. Details in §A.3.
-
-### A.3 Concrete change 2 — `install-skills.ts` copies reference DESIGN.md (the actual fix)
-
-**File:** `src/cli/install-skills.ts` — extend the data-file install area (the `installDataFile()` /
-`dataFiles` region around `:417-459` and `:753-770`) to **also** copy reference markdown into the project,
-gated by `!opts.noReferences`:
-
-```ts
-// after the existing dataFiles loop (~:753-770), before/after installing the resolver script (~:774-785)
-if (!opts.noReferences) {
-  // copy web/references/<id>/DESIGN.md → <project>/.claude/data/references/<id>/DESIGN.md
-  // markdown only — assets are NOT copied (keeps the footprint to ~6 MB)
-  for (const id of listReferenceIds(packageRoot)) {            // 221 ids under web/references/
-    const src = path.join(packageRoot, 'web', 'references', id, 'DESIGN.md');
-    if (!fs.existsSync(src)) continue;
-    const dst = path.join(projectDir, '.claude', 'data', 'references', id, 'DESIGN.md');
-    fs.mkdirSync(path.dirname(dst), { recursive: true });
-    fs.copyFileSync(src, dst);                                  // overwrite on --force, same as skills
-  }
-}
-```
-
-- This runs **during the install process**, while `packageRoot` (the npx cache or `node_modules`) is still
-  on disk — the only window in which the reference markdown is reachable for the npx audience.
-- New `--no-references` CLI flag sets `opts.noReferences = true` → skip the copy entirely (lean install).
-- The resolver script (`omd-resolve-ref.cjs`, §A.2) is installed alongside the hooks at `:774-785` as before;
-  with this copy in place, the resolver's candidate-1 is now the live primary path.
-
-### A.3b Concrete change 3 — `omd-init` Phase 4.1 rewrite
-
-**File:** `skills/omd-init/SKILL.md` — replace the Phase 4.1 path block (`:87-97`).
-
-Replace the three-path Read cascade with:
-
-```markdown
-### 4.1 경로 결정 (resolver-backed)
-
-선택된 id를 `<id>`로 하고, **먼저** resolver를 Bash로 실행해 절대경로를 얻는다:
-
-  node "$(node -e "try{process.stdout.write(require.resolve('oh-my-design-cli/scripts/omd-resolve-ref.cjs',{paths:[process.cwd()]}))}catch(e){process.stdout.write('scripts/omd-resolve-ref.cjs')}")" <id>
-
-- exit 0 → stdout 의 절대경로를 Read 하여 전체 내용을 `reference_md` 에 보관.
-- exit 1 (DESIGN.md 없음) → 사용자에게 "선택한 reference '<id>' 의 DESIGN.md 를 찾지 못했어요.
-  설치가 손상됐을 수 있어요: `omd install-skills --force` 후 다시 시도하거나 다른 id 를 골라주세요."
-  라고 알리고 Phase 3 로 되돌아간다. (이전: 무음 실패 → 빈 생성)
-- exit 2 (잘못된 id 형식) → "id 형식이 올바르지 않아요" 후 Phase 3.
-```
-
-This also fixes the **Phase 2.1 / Phase 4.1 mismatch** (fingerprints loaded from `data/`, DESIGN.md from
-`web/references/`): the resolver centralizes the `web/references` knowledge in one place, and Phase 2.1's
-fingerprints fallback can adopt the same `require.resolve` trick (optional follow-up, not required for 1.7.2).
-
-### A.4 Acceptance criteria — Pillar A
-
-- **AC-A0 (THE regression test — the real bug):** In a clean temp project with **no prior `npm i`**, run the
-  *literal documented* command `npx oh-my-design-cli install-skills` (no other setup). Then assert
-  `.claude/data/references/toss/DESIGN.md` **exists** on disk, and that `node .../omd-resolve-ref.cjs toss`
-  exits 0 and returns that exact copied path. This is the case the old A2 design silently failed.
-- **AC-A1:** Secondary layout — `npm i oh-my-design-cli && npx omd install-skills`, then
-  `node .../omd-resolve-ref.cjs toss` exits 0 (exercises candidate-2, the `require.resolve` fallback, as well
-  as the copied candidate-1).
-- **AC-A2:** Same under **pnpm** and **yarn** installs (CI matrix) — resolver still exits 0 (secondary
-  fallback path).
-- **AC-A3:** Global install (`npm i -g oh-my-design-cli`) with `paths:[projectDir]` falling back to global
-  root — resolver exits 0 (secondary fallback path).
-- **AC-A4:** Unknown id (`node omd-resolve-ref.cjs zzznotreal`) exits 1; `omd-init` surfaces the recovery
-  message and does **not** proceed to Phase 5.
-- **AC-A5:** Path-traversal id (`../../etc/passwd`) exits 2, nothing read.
-- **AC-A6 (`--no-references`):** `npx oh-my-design-cli install-skills --no-references` writes **no**
-  `.claude/data/references/` directory; a subsequent Phase 4.1 for `toss` falls through candidate-1, and (with
-  no `node_modules`) the resolver exits 1 and the skill surfaces the recovery message.
-
-### A.5 Effort — Pillar A
-**~0.75 day.** New 40-line cjs resolver, the install-skills reference-copy step + `--no-references` flag, one
-SKILL.md block rewrite, two `files[]`/install-list additions, ~6 vitest/CI cases (including the AC-A0 npx
-regression). Highest-value change in the release.
-
----
-
-## Pillar B — DESIGN.md-need detector — **DEFERRED TO 1.8.0**
-
-> **Status: deferred out of 1.7.2.** Two problems block shipping this now: (1) the thresholds
-> (`routes ≥ 10`, `ad-hoc ≥ 3`, `score ≥ 6`) are unvalidated guesses with no usage data behind them; and
-> (2) the premature-guard boolean is **mis-grouped** — `AND` binds tighter than `OR`, so
-> `count<10 OR contributors<=1 AND scaffold_only OR drift` parses as
-> `count<10 OR (contributors<=1 AND scaffold_only) OR drift`, which is **not** what the prose ("too early
-> unless enough surface AND multiple contributors…") intends. Rather than ship a guard that means something
-> different from its description, the entire pillar moves to **1.8.0**, where the thresholds can be tuned
-> against real telemetry and the guard rewritten with explicit parentheses. The section below is retained as
-> the 1.8.0 design starting point; the precedence must be fixed there with explicit grouping. AC-B* move to
-> §6.4 with the pillar.
-
-### B.0 Goal
-Stop offering to bootstrap DESIGN.md indiscriminately. Offer **only when** the project both *wants* design
-work and has *accumulated enough UI surface* to be worth a spec — and explicitly say "too early, revisit at
-N features" otherwise (USWDS L1→L3 ladder: don't mint tokens before an implicit component inventory exists).
-
-### B.1 Where it lives (lightweight, two touch-points)
-
-- **Signal collection — `\.claude/hooks/post-edit-watch.cjs`** (already runs PostToolUse on Edit|Write).
-  It already detects hex colors not in DESIGN.md (`:88-97`). Extend it to *also* increment cheap counters in
-  a new `.omd/need-signals.json` when an edited file looks like UI (`.tsx/.jsx/.vue/.svelte` or contains
-  `className=`/`style=`/`<button`). No scoring in the hook — just append-only signal capture (cheap, matches
-  the memory-stream pattern).
-- **Decision — `omd-apply` Phase 0** (`skills/omd-apply/SKILL.md`, the existing dispatch tree). Add a
-  `need-check` branch that reads `.omd/need-signals.json` + git + filesystem and computes the score below
-  **only when** the user expresses UI/design intent and no usable DESIGN.md exists.
-
-### B.2 The need-score (Groto signals + premature guards)
-
-Computed in `omd-apply` Phase 0 (prose heuristic the model runs, not new TS):
-
-```
-need_score =
-    (distinct_ui_route_or_page_count >= 10        ? +3 : 0)   // enough surface
-  + (repeated_adhoc_button_or_card_styles >= 3     ? +2 : 0)  // component debt (grep ad-hoc styles)
-  + (git_contributors_touching_ui > 1              ? +2 : 0)  // coordination need
-  + (visual_drift_across_surfaces_detected         ? +2 : 0)  // >1 distinct button/color system
-  + (user_intent_is_design_or_ui                   ? +1 : 0)
-
-PREMATURE-GUARD (hard veto → emit "too early"):
-  distinct_ui_route_or_page_count < 10
-  OR git_contributors_touching_ui <= 1 AND scaffold_only
-  OR visual language under active discovery (boilerplate UI only)
-```
-
-- **score ≥ 6 and no veto** → offer bootstrap: *"이 프로젝트는 라우트 N개 + 버튼 스타일 M종이 흩어져
-  있어요. 지금 DESIGN.md 를 잡으면 좋겠어요 — `omd:init` 갈까요?"*
-- **veto fired** → *"아직 일러요(라우트 N개 / 단일 기여자). 기능이 ~10개 넘으면 그때 DESIGN.md 를
-  제안할게요."* (the explicit "revisit at N" message the research asked for).
-- **DESIGN.md exists but stale** (modified < UI files' median mtime, or scopes referenced in recent
-  preferences absent from DESIGN.md) → offer **partial** bootstrap via `omd:sync`, not a full `omd:init`.
-
-### B.3 Acceptance criteria — Pillar B
-- **AC-B1:** Scaffold-only project (Next.js boilerplate, 2 routes, 1 contributor) → detector emits "too
-  early," never offers `omd:init`.
-- **AC-B2:** Project with ≥10 routes, ≥3 ad-hoc button styles, 2 UI contributors, no DESIGN.md, user says
-  "design intent" → need_score ≥ 6, bootstrap offered exactly once.
-- **AC-B3:** Project with a fresh DESIGN.md → detector stays silent (no offer).
-- **AC-B4:** `post-edit-watch.cjs` adds ≤1 file write per edit and stays within its 2000 ms timeout.
-
-### B.4 Effort — Pillar B
-**~1 day.** ~25 lines added to `post-edit-watch.cjs`, one Phase-0 branch + score prose in `omd-apply`,
-3–4 fixture-project tests.
-
----
-
-## Pillar C — Self-reinforcing feedback loop
-
-### C.0 The architecture (memory-stream ⇄ reflection layer)
-
-Adopt the **Generative-Agents** split directly:
-
-- `\.omd/preferences.md` = **memory stream** — append-only raw observations (already specified by
-  `omd-remember`: each entry tagged `id / ts / scope / status:pending / importance / signal`).
-- `DESIGN.md` = **reflection layer** — the low-churn, human-readable, auditable spec. Mutated only by
-  curated promotion (`omd-learn` / fold-in), never by raw appends. This *is* the "constitution" in CAI terms.
-
-The loop: `omd-remember` writes raw → `session-end-foldin` scores recurrence → proposals surfaced → `omd-learn`
-promotes as small curated deltas → DESIGN.md strengthens → next run's critique pass uses the stronger spec.
-
-### C.1 (i) Recurrence scoring & promotion thresholds
-
-**Keep the existing multiplicative core unchanged.** `session-end-foldin.cjs:59-72` already implements an
-ACT-R-style **multiplicative** activation:
-
-```
-score(scope) = count × importanceAvg × recency × 10
-```
-
-guarded by **three gates** (all preserved, none changed):
-
-1. `entries.length ≥ 3` (frequency floor),
-2. **`importanceAvg ≥ 2.5`** — the importance floor, **explicitly synced to `src/core/memory.ts`** (the
-   line ~64 comment in the hook references this duplication; it must stay in sync), and
-3. `score ≥ fold_in_score_threshold` (60),
-
-with a hardcoded `tau = 7` (`recurrence_window_days`) in the recency factor. The earlier draft of this
-section proposed replacing the multiplicative score with an **additive** `w_freq*count + w_rec*Σexp +
-w_rel*relevance` (with `w_rel`=0.5). That silently changed behavior and made AC-C6 ("identical to 1.7.1")
-unsatisfiable. **We do not do that.**
-
-The relevance term is added only as an **optional multiplicative factor gated behind `w_rel` that DEFAULTS
-TO 0** (i.e. inert), so 1.7.1 behavior is reproduced *exactly* by default:
-
-```
-relevance_factor = 1 + w_rel * scope_match_to_active_design_scope   // w_rel default 0 → factor == 1 → no-op
-score(scope)     = count × importanceAvg × recency × 10 × relevance_factor
-```
-
-- **Promotion gate (pending → applied):** unchanged — `entries.length ≥ 3` **AND** `importanceAvg ≥ 2.5`
-  **AND** `score ≥ 60`. (The Self-Consistency vote-gate proposed earlier is **deferred to 1.8.0** — see
-  §6.4; promotion is already human-confirmed in `omd-learn` and again in the C.3 conflict prompt.)
-- **Decay / pruning:** entries older than `recurrence_window_days` (7) already drop out of scoring; the prune
-  pass that flips never-promoted, expired `pending` entries to `status:archived` is **moved to a dedicated
-  `omd-learn` Phase 6 "prune"** (out of Phase 5 "결과 요약", which was a semantic mismatch) — see §C.3a. This
-  keeps `preferences.md` bounded.
-
-`w_rel` lives in `.omd/config.json` (the file the hook already reads) and **defaults to 0**; `w_freq`/`w_rec`
-are not introduced (the score stays multiplicative, not a weighted sum). With `w_rel` absent or 0, the
-relevance factor is exactly 1 and scoring is byte-identical to 1.7.1. **`w_rel` weighting stays inert until
-1.8.0**, where it is tuned against real usage data (§6.4).
-
-### C.2 (ii) Consolidation trigger — session-end exists; do we need task/epic-complete?
-
-**Yes — a task/epic-complete consolidation is worth adding, but as a fired event, not a new mechanism.**
-Rationale: session-end is *temporal* (you closed your laptop), but design preferences cluster by *task*
-("I just finished the checkout flow"). A purely session-bound fold-in mis-scores because it ignores whether
-the recurring signals came from the *same* design task (the documented gap: "Missing: Task context in
-fold-in scoring"). Closing a task is the natural reflection boundary (Reflexion: reflect at the end of a
-trajectory, not on a wall-clock timer).
-
-**Design (minimal):** `omd-apply`, when it detects a design task closed (user says "done with X" / the
-harness reports a run completed), appends a marker block to `.omd/timeline.md`:
-
-```
-## <iso-ts> — task_complete
-scope_hint: components.button, color
-```
-
-`session-end-foldin.cjs` is extended to **also run its fold-in pass immediately when invoked with
-`OMD_TRIGGER=task-complete`** (we add a tiny launcher: `omd-apply` runs
-`OMD_TRIGGER=task-complete node .../session-end-foldin.cjs` after writing the marker). The value of this
-trigger is the **timing boundary**: preferences from the just-finished task get consolidated *while they're
-fresh and coherent*, instead of waiting for session end and being averaged against unrelated scopes — and
-this works with the unchanged multiplicative scoring (no weighting change needed). The `scope_hint` is
-recorded so that, once `w_rel` weighting lands in **1.8.0**, the relevance factor can be boosted for those
-scopes; in 1.7.2 `w_rel`=0, so the trigger purely changes *when* the existing scoring runs, not *how* it
-scores. **No new hook, no new skill** — one env-var branch in an existing hook + one Bash call from an
-existing skill.
-
-### C.3 (iii) Conflict resolution (new preference contradicts DESIGN.md)
-
-This is the **Constitutional-AI critique→revise** step, currently missing. Add to `omd-learn` Phase 3
-(`skills/omd-learn/SKILL.md:37-51`), per scope, before editing DESIGN.md:
-
-1. **Critique:** read the current DESIGN.md rule for that scope. Does the pending preference *contradict*
-   it (e.g. DESIGN.md §2 says "primary = navy"; preference says "make primary green")?
-2. **Classify the conflict:**
-   - *Refinement* (narrows/extends, no contradiction) → apply as a small delta.
-   - *Direct contradiction* → **do not silently overwrite.** Surface to the user:
-     *"DESIGN.md §2 says primary=navy, 하지만 최근 3회 green 을 선호하셨어요. (a) DESIGN.md 를 green 으로
-     바꿀까요, (b) 이번만 예외로 둘까요, (c) 무시할까요?"* — record the decision back into the preference
-     entry (`status: applied | superseded | rejected`).
-   - *Stale rule* → flag for **pruning** from DESIGN.md (CAI: rules that never bind get pruned). **"Never
-     binds" needs an operational definition before this fires automatically; in 1.7.2 it is a 1.8.0
-     heuristic**, not an automatic action. The intended definition (to implement in 1.8.0): *a DESIGN.md rule
-     whose scope had 0 outputs reference it across the last K fold-in cycles (K configurable in
-     `.omd/config.json`)*. Until that counter exists, 1.7.2 only surfaces such a rule for human review when
-     the user is already in the C.3 conflict prompt — it does not auto-prune.
-
-The Self-Consistency **vote-gate** (sample 2–3 candidate phrasings, promote only the recurring one) proposed
-in an earlier draft is **deferred to 1.8.0** (§6.4): promotion is already human-confirmed in `omd-learn`
-Phase 2 and again in the (a)/(b)/(c) conflict prompt above, so the vote-gate is YAGNI for 1.7.2.
-
-This keeps DESIGN.md stable and auditable: contradictions become explicit user decisions, not silent drift.
-
-### C.3a (i, cont.) Prune pass — `omd-learn` Phase 6 (not Phase 5)
-
-The archive-prune pass is a **new dedicated `omd-learn` Phase 6 "prune"** (the earlier draft put it in
-Phase 5 "결과 요약" / results summary — a semantic mismatch). Phase 6 flips never-promoted, expired `pending`
-entries (older than `recurrence_window_days`) to `status:archived`, bounding `preferences.md` (power-law
-forgetting, made concrete). It runs after the Phase 5 summary so the summary reflects the pre-prune state.
-(Alternatively it can run inside `session-end-foldin` after scoring; we choose the explicit `omd-learn`
-Phase 6 so the prune is auditable and human-visible in the learn flow.)
-
-### C.4 (iv) Feedback signal — did the fold-in actually improve things? — **DEFERRED TO 1.8.0**
-
-> **Status: deferred out of 1.7.2** (consistent with §6.4). The correction-rate reinforcement needs
-> accumulated `user-correction` history to be meaningful and benefits from real usage data before tuning the
-> importance-prior bumps. In 1.7.2 only the **timeline reflection-line FORMAT is stubbed and
-> forward-compatible** (so 1.8.0 only *reads* it); no reinforcement is computed. The full design is retained
-> below as the 1.8.0 spec.
-
-The reinforcement signal (Reflexion's verbal eval signal = user edits/corrections; RLAIF/CAI's AI-feedback
-reward proxy):
-
-> **A fold-in into scope S improved things if the rate of subsequent user *corrections* in scope S drops
-> after the fold-in.**
-
-Concrete instrumentation (data already exists — `omd-remember` tags each entry `signal:user-statement` vs
-`signal:user-correction`, scope-tagged, timestamped):
-
-- On each fold-in, `omd-learn` records in `.omd/timeline.md`:
-  `foldin scope=S at=T applied_pref_ids=[...]`.
-- A new **reflection line** computed at the *next* task-complete/session-end for scope S:
-  `correction_rate_after = (#user-correction in S since T) / (#runs touching S since T)`
-  compared to `correction_rate_before`.
-  - **Decreased** → positive reinforcement: bump the *importance prior* for that scope (future signals in S
-    score slightly higher / promote faster). Emit a one-line **verbal reflection** into `preferences.md`:
-    *"hero copy 짧게 + spacing 좁게 선호 → 이후 수정 0건. denser layout 규칙 강화."* (Reflexion verbal buffer;
-    top-K relevant reflections get prepended to the next run's context per C.5).
-  - **Increased/unchanged** → negative: the rule is wrong or under-specified. Re-surface the scope in the
-    next `omd-learn` as *"이 규칙 적용 후에도 수정이 계속돼요 — 다시 볼까요?"* (the CAI "rule keeps getting
-    violated ⇒ revise or prune" path).
-
-This makes "self-reinforcing" measurable and grounded: recurring, *validated* choices compound their weight;
-rules that don't reduce corrections get revised or pruned. **No model retraining** — the improving "policy"
-is `DESIGN.md` + the reflection buffer, exactly the verified Reflexion/memory-stream mechanism.
-
-> **Provenance note:** mechanisms above are cited from verified sources — Reflexion (verbal self-reflection
-> buffer), Generative Agents (memory-stream → reflection promotion; recency×frequency×relevance retrieval),
-> Constitutional AI / RLAIF (critique→revise against a fixed rule-set), Self-Consistency (vote-gated
-> promotion — **applied in 1.8.0, not 1.7.2**), ACT-R (recency×frequency activation). The Hermes
-> "15–30% after 5 cycles" figure and the
-> "observe-reflect-optimize" three-stage optimizer are **secondary-blog / marketing claims and are NOT used
-> as evidence here.**
-
-### C.5 What's stored / scored / promoted / fed back (summary table)
-
-| Stage | File | What | When |
-|---|---|---|---|
-| observe | `.omd/preferences.md` | raw entry `{id, ts, scope, status:pending, importance, signal}` | every `omd-remember` call (`omd-apply` Phase 3, post-edit-watch nudge) |
-| score | (in `session-end-foldin.cjs`) | `count × importanceAvg × recency × 10` (×`w_rel` factor, default 0/inert); floors `entries≥3`, `importanceAvg≥2.5` | session-end **and** task-complete |
-| conflict-check | DESIGN.md ↔ preference | critique→revise; refine / contradict | at promotion |
-| promote | `DESIGN.md` §scope | small curated delta via Edit | user-confirmed in `omd-learn` |
-| prune | `.omd/preferences.md` | expired, never-promoted `pending` → `status:archived` | `omd-learn` **Phase 6** |
-| reflect *(1.8.0)* | `.omd/timeline.md` + `preferences.md` | correction-rate delta + verbal reflection | next run touching that scope |
-| feed back *(1.8.0)* | next run context | top-K reflections prepended; importance prior adjusted | session-state-loader injection |
-
-### C.6 Acceptance criteria — Pillar C
-- **AC-C1:** Seed `preferences.md` with 3 `pending` `components.button` entries within the window → fold-in
-  scores ≥ 60, proposal appears in `timeline.md`; `omd-learn` promotes to DESIGN.md §8 as one coherent edit.
-- **AC-C2:** A 4th preference contradicting an existing DESIGN.md rule triggers the explicit
-  (a)/(b)/(c) user prompt — DESIGN.md is **not** silently overwritten (regression guard for §C.3).
-- **AC-C3:** `OMD_TRIGGER=task-complete node session-end-foldin.cjs` runs the fold-in pass immediately at the
-  task boundary (does not wait for session-end). The `scope_hint` is recorded for 1.8.0 weighting; in 1.7.2
-  scoring is unchanged (w_rel=0), so this AC asserts the *timing* only, not reordering.
-- **AC-C5:** Never-promoted entries older than `recurrence_window_days` flip to `status:archived` on the
-  **Phase 6 prune** pass; `preferences.md` does not grow unbounded.
-- **AC-C6 (back-compat, exact):** With `w_rel=0` (default) and **no `task_complete` markers**, the scoring
-  output of `session-end-foldin.cjs` is **byte-identical** to 1.7.1: the relevance factor evaluates to 1, the
-  multiplicative `count × importanceAvg × recency × 10` and all three gates (`entries≥3`, `importanceAvg≥2.5`,
-  `score≥60`) are unchanged. (The stated defaults achieve this exactly.)
-- *(AC-C4 — correction-rate reflection — **moved to 1.8.0**, §6.4. In 1.7.2 only assert that the timeline
-  reflection-line FORMAT is stubbed and forward-compatible so 1.8.0 can read it.)*
-- **AC-C7:** A runnable end-to-end example exists under `.experiments/` demonstrating capture→score→promote→
-  DESIGN.md-change→prune (closes the documented "no runnable example" gap). *(The reflect step is appended in
-  1.8.0 with the reinforcement feedback.)*
-
-### C.7 Effort — Pillar C (1.7.2 deterministic core only)
-**~1.75 days.** `session-end-foldin.cjs` inert `w_rel` factor (default 0) + `OMD_TRIGGER=task-complete`
-branch, preserving the multiplicative score and all three gates (~0.5d); `omd-learn` Phase 3 critique→revise
-+ Phase 6 prune (~0.75d, prose spec; **no** vote-gate, **no** reflection compute in 1.7.2); stub the
-forward-compatible reflection-line format (~0.1d); example fixture + tests, incl. the AC-C6 byte-identity
-test (~0.4d). *(Vote-gate, `w_rel` weighting, and correction-rate reinforcement are 1.8.0 — see §6.5.)*
-
----
-
-## §5 Verdict — post-task preference consolidation
-
-**YES.** A task/epic-complete consolidation step *is* warranted — but the minimal addition is **not** a new
-hook and **not** a new `omd:consolidate` skill.
-
-**Chosen minimal addition:** extend `session-end-foldin.cjs` to fire its existing fold-in pass on an
-explicit `OMD_TRIGGER=task-complete` invocation, driven by a `## ... — task_complete` marker that `omd-apply`
-writes to `.omd/timeline.md` when a design task closes (§C.2). Rationale:
-
-- A new **hook** can't help: Claude Code has no native "task/epic complete" event; the only real signals are
-  *session-end* (already a Stop hook) and *the agent/user declaring a task done* — which a skill (`omd-apply`)
-  observes far better than any hook matcher.
-- A new **skill** (`omd:consolidate`) would duplicate `omd-learn` + fold-in (the brief forbids duplicating
-  the existing loop).
-- Extending `session-end-foldin.cjs` with one env-var branch reuses the entire scoring/proposal pipeline and
-  only adds the *trigger boundary* and a relevance boost — which is exactly the missing capability
-  (task-scoped consolidation, fresh and coherent), at the cost of ~15 lines.
-
----
-
-## §6 Release plan
-
-### 6.1 File change list
-
-| File | Change | Pillar |
-|---|---|---|
-| `scripts/omd-resolve-ref.cjs` | **new** — fallback resolver (primary hit = install-copied path) | A |
-| `package.json` `files[]` | add `scripts/omd-resolve-ref.cjs` | A |
-| `src/cli/install-skills.ts` (`:417-459`, `:753-770` data-file area) | **copy `web/references/*/DESIGN.md` → `.claude/data/references/<id>/DESIGN.md`** (gated `!opts.noReferences`); add `--no-references` flag; install resolver at `:774-785` | A |
-| `skills/omd-init/SKILL.md` (Phase 4.1 `:87-97`) | replace 3-path Read with resolver call + error handling | A |
-| `.claude/hooks/session-end-foldin.cjs` | inert `w_rel` factor (default 0, multiplicative score + 3 gates preserved); `OMD_TRIGGER=task-complete` branch | C |
-| `src/core/memory.ts` | **no behavior change** — note that the `importanceAvg ≥ 2.5` floor / scoring is **duplicated here** and must stay in sync with `session-end-foldin.cjs` | C |
-| `skills/omd-learn/SKILL.md` (Phase 3 + new Phase 6) | Phase 3 critique→revise; new **Phase 6 prune** (moved out of Phase 5) | C |
-| `skills/omd-apply/SKILL.md` (task close) | write `task_complete` marker + launch fold-in | C |
-| `.experiments/preference-loop-example/` | **new** — runnable end-to-end fixture | C |
-| `CHANGELOG.md` | 1.7.2 entry | all |
-| `.claude/hooks/post-edit-watch.cjs` | UI-signal counters | **B — deferred to 1.8.0** |
-| `skills/omd-apply/SKILL.md` (Phase 0 `need-check`) | need-score branch | **B — deferred to 1.8.0** |
-
-### 6.2 Migration / back-compat
-
-- **No project migration required.** `.omd/*` files are created lazily as before. Missing `task_complete`
-  markers and absent/zero `w_rel` config degrade to **exact 1.7.1 behavior** (AC-C6).
-- **Re-install:** users run `omd install-skills --force` to pick up the new resolver script, the **copied
-  reference `DESIGN.md` files**, and refreshed SKILL.md/hook files. The existing settings.json merge logic
-  (`installSettingsJson` `:380-414`) is unchanged — **no new hook registered**, so settings.json does not
-  change (avoids drift-skip on user-edited configs). This is a key simplicity win of the §5 verdict.
-- **Install footprint:** the default install now copies reference markdown into `.claude/data/references/`
-  (**~6 MB**, markdown only — assets not copied). Users who want a lean install pass `--no-references`. This
-  is the deliberate cost of A1 and the reason the install gap is actually closed for the npx audience.
-- **`.gitignore` / tarball:** `.omd/` stays ignored; `web/references/*/DESIGN.md` shipping is unchanged
-  (install copies it from there — do **not** drop it from `files[]`).
-
-### 6.3 Test additions
-- vitest + CI matrix for the resolver and reference-copy — **AC-A0** (the bare-`npx` regression), AC-A1..A6.
-- preference-loop unit/integration tests + the `.experiments/` example — AC-C1..C3, C5, C6 (incl. the
-  byte-identity back-compat test). *(Need-detector fixtures AC-B1..B4 ship with Pillar B in 1.8.0.)*
-
-### 6.4 One release or split?
-
-**Split.**
-- **1.7.2 (ships now):** **Pillar A (A1 — copy the chosen reference at install)** + the **deterministic,
-  human-gated consolidation core of Pillar C**: the `OMD_TRIGGER=task-complete` trigger, conflict-resolution
-  (critique→revise), and the Phase 6 prune pass — with **multiplicative scoring unchanged and `w_rel`=0**
-  (inert). Everything here is deterministic and testable without telemetry plumbing, and back-compat is exact
-  (AC-C6).
-- **1.8.0 (next):** **Pillar B (the need-detector)** — its thresholds need real telemetry to tune and its
-  premature-guard precedence must be rewritten with explicit parentheses; **the `w_rel` relevance
-  *weighting*** (tuned against usage data); the **Self-Consistency vote-gate** (YAGNI in 1.7.2 — promotion is
-  already human-confirmed twice); and **Pillar C (iv) correction-rate reinforcement** + the verbal-reflection
-  buffer prepended into run context (needs accumulated `user-correction` history). 1.7.2 only **stubs** the
-  forward-compatible timeline reflection-line format so 1.8.0 *reads* it. AC-B1..B4 and AC-C4 ship here.
-
-**Rationale:** Pillar A is a release-blocking bug for the primary install path and should not wait behind
-unvalidated heuristics or telemetry. The deterministic, human-gated half of C completes the foundation with
-zero behavior change by default; the data-dependent and unvalidated parts (B, `w_rel`, vote-gate,
-reinforcement) earn their own minor version where they can be tuned and the guard precedence fixed.
-
-### 6.5 Total effort
-**~2.5 days** for 1.7.2 (A ~0.75 + C-deterministic-core ~1.75 — note B is **not** in 1.7.2).
-**~2.5 days** for 1.8.0 (Pillar B ~1 incl. fixing the guard precedence + fixtures; `w_rel` weighting tuning +
-vote-gate ~0.75; correction-rate reinforcement + reflection buffer ~0.75).