omniconductor 0.3.0

package/core/hooks/stop-cache-hit-baseline-check.sh.template

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: stop-cache-hit-baseline-check
+# trigger: stop
+# action: Read latest Claude Code session JSONL, compute cache hit rate, emit
+#         a non-blocking diagnostic reminder when below baseline.
+# compile_targets: claude
+# fallback: rule-text-reminder
+#
+# Generated by adapters/<tool>/transform.sh.
+#
+# Enforces:
+#   - meta-discipline.md token-economy section (cache hit baseline)
+#
+# Behavior:
+#   1. Locate latest session JSONL under ~/.claude/projects/<encoded>/*.jsonl.
+#   2. Sum cache_read_input_tokens vs uncached input_tokens via python3.
+#   3. If hit_rate < ${CONDUCTOR_CACHE_HIT_FLOOR_PERCENT}% AND total
+#      effective input tokens >= ${CONDUCTOR_CACHE_TOTAL_FLOOR}, emit a
+#      stderr reminder listing the 5 candidate anti-patterns.
+#   4. exit 0 (non-blocking).
+#
+# Override (silence reminder, e.g. CI sessions):
+#   ${CONDUCTOR_CACHE_SKIP_ENV}=1
+#
+# Skip conditions:
+#   - python3 missing
+#   - no session JSONL found
+#   - session token volume below floor (too short to draw conclusions)
+#   - skip env var set
+
+set -u
+
+# Placeholders filled by adapters/<tool>/transform.sh:
+#   ${CONDUCTOR_CACHE_HIT_FLOOR_PERCENT}  — target floor (default 80)
+#   ${CONDUCTOR_CACHE_TOTAL_FLOOR}        — minimum total tokens before report (default 5000)
+#   ${CONDUCTOR_CACHE_SKIP_ENV}           — env var to silence (default CONDUCTOR_SKIP_CACHE_CHECK)
+#   ${CONDUCTOR_ANTI_PATTERNS_PATH}       — relative path to anti-patterns doc
+
+FLOOR_PCT="${CONDUCTOR_CACHE_HIT_FLOOR_PERCENT:-80}"
+TOTAL_FLOOR="${CONDUCTOR_CACHE_TOTAL_FLOOR:-5000}"
+SKIP_ENV_NAME="${CONDUCTOR_CACHE_SKIP_ENV:-CONDUCTOR_SKIP_CACHE_CHECK}"
+ANTI_PATTERNS_DOC="${CONDUCTOR_ANTI_PATTERNS_PATH:-core/anti-patterns/README.md}"
+
+# Honor user opt-out without inspecting payload.
+SKIP_VAL="$(/usr/bin/printenv "$SKIP_ENV_NAME" 2>/dev/null || true)"
+[ "$SKIP_VAL" = "1" ] && exit 0
+
+command -v python3 >/dev/null 2>&1 || exit 0
+
+# Allow tests to inject a fixture directly.
+FIXTURE="${CONDUCTOR_CACHE_TEST_FIXTURE:-}"
+SESSION_PATH=""
+
+if [ -n "$FIXTURE" ]; then
+  [ -f "$FIXTURE" ] || exit 0
+  SESSION_PATH="$FIXTURE"
+else
+  # Find newest *.jsonl under ~/.claude/projects/.
+  if [ ! -d "$HOME/.claude/projects" ]; then
+    exit 0
+  fi
+  SESSION_PATH=$(/usr/bin/find "$HOME/.claude/projects" -name '*.jsonl' -type f 2>/dev/null \
+    | while IFS= read -r f; do
+        m=$(/usr/bin/stat -f '%m' "$f" 2>/dev/null || /usr/bin/stat -c '%Y' "$f" 2>/dev/null || echo 0)
+        printf '%s\t%s\n' "$m" "$f"
+      done \
+    | /usr/bin/sort -rn \
+    | /usr/bin/head -n 1 \
+    | /usr/bin/cut -f2-)
+  [ -n "$SESSION_PATH" ] && [ -f "$SESSION_PATH" ] || exit 0
+fi
+
+# Parse + decide. python3 prints a single line: "<hit_rate> <total_eff>".
+RESULT=$(SESSION="$SESSION_PATH" python3 - <<'PYEOF' 2>/dev/null
+import json, os, sys
+path = os.environ.get("SESSION", "")
+total_input = 0
+total_cache_read = 0
+try:
+    with open(path, "r", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except Exception:
+                continue
+            usage = (obj.get("message") or {}).get("usage") or {}
+            total_input += usage.get("input_tokens") or 0
+            total_cache_read += usage.get("cache_read_input_tokens") or 0
+except Exception:
+    sys.exit(0)
+total_eff = total_input + total_cache_read
+hit = (total_cache_read / total_eff * 100.0) if total_eff > 0 else 100.0
+print(f"{hit:.1f} {total_eff}")
+PYEOF
+)
+
+[ -n "$RESULT" ] || exit 0
+
+HIT_RATE="${RESULT% *}"
+TOTAL_EFF="${RESULT##* }"
+
+# Floor check (integer compare on TOTAL_EFF).
+case "$TOTAL_EFF" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+[ "$TOTAL_EFF" -lt "$TOTAL_FLOOR" ] && exit 0
+
+# Compare HIT_RATE (float) to FLOOR_PCT (int) using awk.
+BELOW=$(/usr/bin/awk -v h="$HIT_RATE" -v f="$FLOOR_PCT" 'BEGIN { print (h+0 < f+0) ? "1" : "0" }')
+[ "$BELOW" = "1" ] || exit 0
+
+# Emit non-blocking reminder to stderr (Stop hook stderr is surfaced to user).
+/bin/cat >&2 <<EOF
+
+[stop-hook cache-baseline] Session cache hit rate: ${HIT_RATE}% (floor ${FLOOR_PCT}%, eff input ${TOTAL_EFF} tokens).
+
+Likely causes (top 5 anti-patterns):
+  1. Dynamic prompt prefix — values change every turn, breaking cache key.
+  2. Large-file Read without offset/limit — pulls entire file into context.
+  3. Monolithic rule file edited mid-session — invalidates cached system prompt.
+  4. No sub-agent isolation — long-running task accumulates context in main thread.
+  5. Frequent CLAUDE.md / settings edits during session — busts the prefix cache.
+
+Diagnostic guide: ${ANTI_PATTERNS_DOC}
+Silence (intentional): export ${SKIP_ENV_NAME}=1
+
+EOF
+exit 0

package/core/hooks/stop-r6-review-check.sh.template

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: stop-r6-review-check
+# trigger: stop
+# action: Remind to run pre-merge code review (Q2) when feature/fix/chore branch
+#         has a recently-pushed open PR.
+# compile_targets: claude
+# fallback: rule-text-reminder
+#
+# Generated by adapters/<tool>/transform.sh.
+#
+# Enforces:
+#   - quality-gates.md Q2 (pre-merge code review on open PR)
+#
+# Skip conditions:
+#   - current branch is in CONDUCTOR_DIRECT_PUSH_BRANCHES (no PR expected)
+#   - no open PR for current branch
+#   - no push in last STALE_MINUTES (nothing new to review)
+#   - cool-down flag present (review reminder already shown recently)
+
+set -u
+
+# Placeholders filled by adapters/<tool>/transform.sh:
+#   ${CONDUCTOR_DIRECT_PUSH_BRANCHES}  — pipe-separated branch list (default: develop|main|release|HEAD)
+#   ${CONDUCTOR_STALE_MINUTES}         — recent-push window (default 30)
+#   ${CONDUCTOR_COOLDOWN_SECONDS}      — cool-down per PR (default 1800 = 30 min)
+#   ${CONDUCTOR_REVIEW_COMMAND}        — slash command or script to run review (default /code-review)
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT" || exit 0
+
+command -v git >/dev/null 2>&1 || exit 0
+command -v gh  >/dev/null 2>&1 || exit 0
+
+DIRECT_PUSH="${CONDUCTOR_DIRECT_PUSH_BRANCHES:-develop|main|release|HEAD}"
+STALE_MINUTES="${CONDUCTOR_STALE_MINUTES:-30}"
+COOLDOWN="${CONDUCTOR_COOLDOWN_SECONDS:-1800}"
+REVIEW_COMMAND="${CONDUCTOR_REVIEW_COMMAND:-/code-review}"
+
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+[ -n "$BRANCH" ] || exit 0
+
+# Skip direct-push branches.
+if echo "$BRANCH" | /usr/bin/grep -qE "^(${DIRECT_PUSH})$"; then
+  exit 0
+fi
+
+# Recent-push detection.
+THIRTY_MIN_AGO=$(date -v-"${STALE_MINUTES}"M '+%s' 2>/dev/null || date -d "${STALE_MINUTES} minutes ago" '+%s' 2>/dev/null)
+[ -n "$THIRTY_MIN_AGO" ] || exit 0
+
+RECENT_PUSH=$(git reflog --date=unix 2>/dev/null \
+  | /usr/bin/awk -v t="$THIRTY_MIN_AGO" '
+      /push/ {
+        if (match($0, /\{([0-9]+)\}/, m)) {
+          if (m[1]+0 >= t+0) { print; exit }
+        }
+      }')
+[ -n "$RECENT_PUSH" ] || exit 0
+
+# Open PR for current branch.
+PR_JSON=$(gh pr list --head "$BRANCH" --state open --json url,number --limit 1 2>/dev/null)
+[ -n "$PR_JSON" ] && [ "$PR_JSON" != "[]" ] || exit 0
+
+PR_URL=$(printf '%s' "$PR_JSON" | /usr/bin/sed -n 's/.*"url":"\([^"]*\)".*/\1/p')
+PR_NUM=$(printf '%s' "$PR_JSON" | /usr/bin/sed -n 's/.*"number":\([0-9]*\).*/\1/p')
+[ -n "$PR_NUM" ] || exit 0
+
+# Cool-down per PR.
+FLAG="/tmp/conductor-q2-flag-${USER:-unknown}-${PR_NUM}"
+if [ -f "$FLAG" ]; then
+  FLAG_AGE=$(( $(date +%s) - $(/usr/bin/stat -f %m "$FLAG" 2>/dev/null || /usr/bin/stat -c %Y "$FLAG" 2>/dev/null || echo 0) ))
+  [ "$FLAG_AGE" -lt "$COOLDOWN" ] && exit 0
+fi
+touch "$FLAG"
+
+/bin/cat <<EOF
+{"decision":"block","reason":"[stop-hook Q2] Open PR #${PR_NUM} on branch \`${BRANCH}\` with recent push. Run \`${REVIEW_COMMAND} ${PR_URL}\` before merge per universal-rules/quality-gates.md Q2 (pre-merge code review). Docs-only PRs are exempt."}
+EOF

package/core/hooks/stop-session-log-check.sh.template

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: stop-session-log-check
+# trigger: stop
+# action: Block stop when recent commits exist but CURRENT_WORK.md or specs are stale.
+# compile_targets: claude
+# fallback: rule-text-reminder
+#
+# Generated by adapters/<tool>/transform.sh.
+#
+# Enforces:
+#   - operations.md O2 (CURRENT_WORK.md must update when work happens)
+#   - spec-as-you-go.md W3 (source change → spec update in same turn)
+#
+# Exit code meaning in Stop hooks (Claude Code):
+#   0 with no JSON output      → allow stop (default)
+#   0 with {"decision":"block"} → inject reason, continue turn
+
+set -u
+
+# Placeholders filled by adapters/<tool>/transform.sh:
+#   ${CONDUCTOR_PROJECT_DIR}       — absolute path to project root
+#   ${CONDUCTOR_STALE_MINUTES}     — staleness threshold (default 30)
+#   ${CONDUCTOR_COOLDOWN_SECONDS}  — cool-down between reminders (default 600)
+#   ${CONDUCTOR_SOURCE_GLOB}       — file extensions tracked as source (default ts|tsx)
+#   ${CONDUCTOR_SPEC_PATH}         — path prefix that counts as spec update (default docs/specs/)
+#   ${CONDUCTOR_PLAN_THRESHOLD}    — source-file count above which a .plan.md is required (default 5)
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT" || exit 0
+
+CURRENT_WORK="docs/CURRENT_WORK.md"
+[ -f "$CURRENT_WORK" ] || exit 0
+
+STALE_MINUTES="${CONDUCTOR_STALE_MINUTES:-30}"
+COOLDOWN="${CONDUCTOR_COOLDOWN_SECONDS:-600}"
+SRC_GLOB="${CONDUCTOR_SOURCE_GLOB:-ts|tsx}"
+SPEC_PATH="${CONDUCTOR_SPEC_PATH:-docs/specs/}"
+PLAN_THRESHOLD="${CONDUCTOR_PLAN_THRESHOLD:-5}"
+
+RECENT_COMMITS=$(git log --since="${STALE_MINUTES} minutes ago" --oneline 2>/dev/null | /usr/bin/wc -l | /usr/bin/tr -d ' ')
+if [ "$RECENT_COMMITS" -eq 0 ]; then
+  exit 0
+fi
+
+# Cool-down: avoid double-reminding within COOLDOWN seconds.
+FLAG="/tmp/conductor-stop-doc-flag-${USER:-unknown}"
+if [ -f "$FLAG" ]; then
+  LAST=$(cat "$FLAG" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  DELTA=$((NOW - LAST))
+  if [ "$DELTA" -lt "$COOLDOWN" ]; then
+    exit 0
+  fi
+fi
+
+# Check 1: CURRENT_WORK.md freshness.
+WORK_STALE=0
+if [ -z "$(/usr/bin/find "$CURRENT_WORK" -mmin -"${STALE_MINUTES}" 2>/dev/null)" ]; then
+  WORK_STALE=1
+fi
+
+# Check 2: Spec-as-you-go (source files changed but no spec touched).
+SPEC_STALE=0
+SRC_CHANGES=$(git diff --name-only HEAD~"${RECENT_COMMITS}"..HEAD 2>/dev/null | /usr/bin/grep -cE "\\.(${SRC_GLOB})$" || echo 0)
+SPEC_CHANGES=$(git diff --name-only HEAD~"${RECENT_COMMITS}"..HEAD 2>/dev/null | /usr/bin/grep -c "${SPEC_PATH}" || echo 0)
+if [ "$SRC_CHANGES" -gt 3 ] && [ "$SPEC_CHANGES" -eq 0 ]; then
+  SPEC_STALE=1
+fi
+
+# Check 3: Plan-first (W1.1) — Medium/Large scope source changes require a .plan.md.
+# Mirrors the reference adopter's stop-session-log-check Check 4. Per workflow.md W1.1,
+# 5+ source-file changes signal Medium scope or larger; orchestrator must produce a .plan.md
+# before implementation. Hook fires post-hoc when no plan file exists in the diff.
+PLAN_STALE=0
+PLAN_CHANGES=$(git diff --name-only HEAD~"${RECENT_COMMITS}"..HEAD 2>/dev/null | /usr/bin/grep -c "\\.plan\\.md$" || echo 0)
+if [ "$SRC_CHANGES" -ge "$PLAN_THRESHOLD" ] && [ "$PLAN_CHANGES" -eq 0 ]; then
+  PLAN_STALE=1
+fi
+
+REASONS=""
+if [ "$WORK_STALE" -eq 1 ]; then
+  REASONS="${REASONS}[CURRENT_WORK.md stale] Update docs/CURRENT_WORK.md with session log. "
+fi
+if [ "$SPEC_STALE" -eq 1 ]; then
+  REASONS="${REASONS}[SPEC-AS-YOU-GO] ${SRC_CHANGES} source files changed but 0 spec files updated. Update relevant ${SPEC_PATH}*.md files to reflect new/changed features. "
+fi
+if [ "$PLAN_STALE" -eq 1 ]; then
+  REASONS="${REASONS}[PLAN-FIRST] ${SRC_CHANGES} source files changed (>=${PLAN_THRESHOLD}) with no .plan.md in diff. Per workflow.md W1.1, Medium/Large scope requires a .plan.md before implementation. Add one retroactively or split the change. "
+fi
+
+if [ -z "$REASONS" ]; then
+  exit 0
+fi
+
+date +%s > "$FLAG"
+
+/bin/cat <<JSON
+{"decision":"block","reason":"[stop-hook] ${RECENT_COMMITS} commit(s) in last ${STALE_MINUTES} min. ${REASONS}Per universal-rules/operations.md O2 + spec-as-you-go.md W3 + workflow.md W1.1."}
+JSON

package/core/hooks/stop-trajectory-log.sh.template

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: stop-trajectory-log
+# trigger: stop
+# action: On session stop, append a normalized trajectory pointer record to
+#         .conductor/trajectories/index.jsonl for the Reflector to consume.
+# compile_targets: claude
+# fallback: rule-text-reminder
+#
+# Generated by adapters/<tool>/transform.sh.
+#
+# Enforces:
+#   - recipes/self-improvement.md (Observe step)
+#
+# Behavior (fail-open, non-blocking):
+#   1. Read the Stop hook's stdin JSON (Claude provides session_id + transcript_path).
+#   2. UPSERT one pointer record per session into the trajectory index.
+#   3. Always exit 0. Never block session stop.
+#
+# Reading transcript_path from stdin (rather than scanning ~/.claude/projects for the
+# newest *.jsonl) makes provenance exact — a concurrent session in another project can
+# no longer be mis-recorded as this project's trajectory. This matches the stdin-based
+# portable logger used by the non-Claude adapters (core/reflector/trajectory-log.sh).
+#
+# Override (disable logging):
+#   set CONDUCTOR_SKIP_TRAJLOG=1  (or the name in CONDUCTOR_TRAJLOG_SKIP_ENV)
+#
+# Skip conditions: self-improvement recipe not installed (no .conductor/reflect/);
+#   no stdin JSON; not inside a project dir.
+
+set -u
+
+# Runtime env overrides (defaults apply if unset — these are NOT compile-time
+# placeholders; the hook reads them at runtime):
+#   CONDUCTOR_TRAJLOG_SKIP_ENV   name of the opt-out var (default CONDUCTOR_SKIP_TRAJLOG)
+#   CONDUCTOR_TRAJ_DIR           trajectory dir (default .conductor/trajectories)
+#   CONDUCTOR_REFLECT_DIR        opt-in gate dir (default .conductor/reflect)
+#   CONDUCTOR_TRAJ_TEST_FIXTURE  test mode: bypass the cwd anchor + opt-in gate
+SKIP_ENV_NAME="${CONDUCTOR_TRAJLOG_SKIP_ENV:-CONDUCTOR_SKIP_TRAJLOG}"
+TRAJ_DIR="${CONDUCTOR_TRAJ_DIR:-.conductor/trajectories}"
+
+# Honor user opt-out.
+SKIP_VAL="$(/usr/bin/printenv "$SKIP_ENV_NAME" 2>/dev/null || true)"
+[ "$SKIP_VAL" = "1" ] && exit 0
+
+# Anchor to the project root. A hook's cwd is not guaranteed to be the project
+# root; the emitted hook lives at <project>/.claude/hooks/, so ../.. is the root.
+# This makes the opt-in gate and the write path resolve correctly regardless of
+# the session's cwd. Test mode (CONDUCTOR_TRAJ_TEST_FIXTURE set) keeps the current
+# directory so tests control the layout.
+if [ -z "${CONDUCTOR_TRAJ_TEST_FIXTURE:-}" ]; then
+  _self_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)" || exit 0
+  _proj_root="$(cd "$_self_dir/../.." 2>/dev/null && pwd)" || exit 0
+  cd "$_proj_root" || exit 0
+fi
+
+# Opt-in gate: the self-improvement recipe creates .conductor/reflect/ at install.
+# Without it this hook is a no-op — trajectory logging is the "observe" step of an
+# opt-in capability, so it must not fire for adopters who did not opt in. Test mode
+# bypasses the gate.
+REFLECT_DIR="${CONDUCTOR_REFLECT_DIR:-.conductor/reflect}"
+if [ -z "${CONDUCTOR_TRAJ_TEST_FIXTURE:-}" ] && [ ! -d "$REFLECT_DIR" ]; then
+  exit 0
+fi
+
+# Read the Stop hook's stdin JSON (Claude pipes it). A manual run with no piped stdin
+# is a no-op; a test pipes the same JSON.
+[ -t 0 ] && exit 0
+INPUT="$(/bin/cat 2>/dev/null || true)"
+[ -n "$INPUT" ] || exit 0
+
+# Tolerant flat-JSON string extraction (snake/camel).
+jval() { printf '%s' "$1" | /usr/bin/grep -oE "\"($2)\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | /usr/bin/head -n1 | /usr/bin/sed -E 's/^.*:[[:space:]]*"([^"]*)"$/\1/'; }
+TRANSCRIPT="$(jval "$INPUT" 'transcript_path|transcriptPath')"
+SESSION_ID="$(jval "$INPUT" 'session_id|sessionId')"
+[ -n "$SESSION_ID" ] || SESSION_ID="unknown"
+
+# UPSERT one record per session (a session may stop more than once).
+esc() { printf '%s' "$1" | /usr/bin/sed 's/\\/\\\\/g; s/"/\\"/g'; }
+/bin/mkdir -p "$TRAJ_DIR" 2>/dev/null || exit 0
+TS="$(/bin/date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)"
+GIT_HEAD="$(git rev-parse --short HEAD 2>/dev/null || echo none)"
+CWD="$(pwd)"
+LINE="$(printf '{"ts":"%s","session":"%s","transcript":"%s","git_head":"%s","cwd":"%s"}' \
+  "$TS" "$(esc "$SESSION_ID")" "$(esc "$TRANSCRIPT")" "$GIT_HEAD" "$(esc "$CWD")")"
+
+IDX="$TRAJ_DIR/index.jsonl"
+if [ -f "$IDX" ]; then
+  _tmp="$IDX.$$.tmp"
+  /usr/bin/grep -vF "\"session\":\"$(esc "$SESSION_ID")\"" "$IDX" > "$_tmp" 2>/dev/null || : > "$_tmp"
+  /bin/mv "$_tmp" "$IDX" 2>/dev/null || true
+fi
+printf '%s\n' "$LINE" >> "$IDX"
+
+exit 0

package/core/memory-pattern/EXAMPLES.md

@@ -0,0 +1,114 @@
+# Memory pattern — worked examples (PLACEHOLDER — P1 fills with sanitized real examples)
+
+> **Status (P0 foundation)**: this file shows the SHAPE of each memory type via skeleton examples. P1 will fill with sanitized real examples derived from the reference adopter's accumulated memory.
+
+## Example 1 — type: `user`
+
+**Filename**: `user_profile.md`
+
+```markdown
+---
+name: user-profile
+description: who the user is and how they collaborate
+type: user
+---
+
+- Korean speaker; bilingual onboarding preferred for headline material.
+- Senior developer; can read code in TS / Python / Go / Rust without explanation.
+- New to <some-specific-area>; benefits from concrete examples there.
+- Prefers terse responses; no trailing summary unless asked.
+- Reviews PRs same day; expects fast iteration.
+```
+
+**Use it for**: knowing how to format responses, what background context to assume, what NOT to over-explain.
+
+---
+
+## Example 2 — type: `feedback`
+
+**Filename**: `feedback_no_silent_recovery.md`
+
+```markdown
+---
+name: no-silent-recovery
+description: when a rule is broken mid-turn, surface it explicitly; never silently fix and move on
+type: feedback
+---
+
+When you realize you broke a rule mid-turn (skipped a phase, used the wrong agent type, etc.), STOP and call it out in the next user-facing message. Then fix the gap. Continue.
+
+**Why**: silent recovery hides a class of recurring bugs from the user, who then can't help correct the upstream cause. Surfaced violations build trust over time.
+
+**How to apply**: in the next message after the violation, lead with one line acknowledging the rule + the fix. Don't bury it in a bullet at the end. Don't omit it.
+```
+
+**Use it for**: any rule violation. Read this memory before deciding to "just quietly do better next time".
+
+---
+
+## Example 3 — type: `project`
+
+**Filename**: `project_launch_blockers.md`
+
+```markdown
+---
+name: launch-blockers
+description: pre-launch blockers and their resolution dates
+type: project
+---
+
+- **Payment-provider live activation**: blocked on business registration. Resolved YYYY-MM-DD. NOW UNBLOCKED.
+- **Bank-aggregator production**: deferred to post-launch (manual entry MVP first). NOT a launch blocker.
+- **iOS push notifications**: pending app store review. Target: YYYY-MM-DD.
+
+**Why**: avoids re-asking the user the same status question every session.
+
+**How to apply**: before recommending work on a blocked item, check this list. If the entry says BLOCKED, surface the blocker before doing the work.
+```
+
+**Use it for**: project-state questions. Decay fast — verify before acting on entries older than 2 weeks.
+
+---
+
+## Example 4 — type: `reference`
+
+**Filename**: `reference_external_systems.md`
+
+```markdown
+---
+name: external-systems
+description: where information lives in external systems
+type: reference
+---
+
+- **Payment provider live IDs (products, prices, webhooks)**: provider dashboard → Live mode → Products. Backup: `<your-secrets-vault>/payment-live.json`.
+- **DNS records**: DNS provider account `<your-dns-org>`. CNAME / A records documented in `docs/legal/dns-snapshot-YYYY-MM-DD.md`.
+- **Email infra dashboard**: <your-email-provider>.com console.
+- **Cron monitoring**: hosting provider's deployments tab → Cron Jobs.
+```
+
+**Use it for**: "where do I find X?" questions. NEVER include actual secrets in memory entries — only pointer to the source-of-truth.
+
+---
+
+## MEMORY.md index — example
+
+When you save a memory file, add a one-line pointer to `MEMORY.md`:
+
+```markdown
+- [User Profile](user_profile.md) — Korean senior dev; terse responses; bilingual onboarding
+- [No Silent Recovery](feedback_no_silent_recovery.md) — surface rule violations explicitly
+- [Launch Blockers](project_launch_blockers.md) — payment-provider live UNBLOCKED; iOS push pending
+- [External Systems](reference_external_systems.md) — pointers to payment / DNS / hosting dashboards
+```
+
+The index is ALWAYS LOADED at session start (when the tool supports it). Keep ≤ 200 lines. Archive older entries by removing them from the index when no longer relevant; the source files stay on disk in case you need to retrieve.
+
+## Pattern conventions
+
+- File names: `<type>_<short-slug>.md` (snake_case).
+- Title in body: human-readable.
+- Frontmatter `description:` is what the index uses; keep ≤ 80 chars.
+- For `feedback` and `project`: always include **Why** and **How to apply** lines. Without these, the entry is just trivia.
+- For `user`: bullet list of facts. No need for Why/How.
+- For `reference`: bullet list of pointers. NEVER inline the secret/data — just pointer to source.

package/core/memory-pattern/README.md

@@ -0,0 +1,133 @@
+# `core/memory-pattern/` — 4-type memory pattern (universal)
+
+CONDUCTOR's memory pattern. Tool-agnostic in *intent*; tool-native in *mechanism*.
+
+## The 4 types
+
+| Type | When to save | Example |
+|---|---|---|
+| **user** | Learn role, preferences, knowledge level | "Senior Go dev, new to React" |
+| **feedback** | User corrects OR validates an approach | "Don't mock the DB in integration tests — burned by mock/prod divergence" |
+| **project** | Who's doing what, why, by when (convert relative dates to absolute) | "Merge freeze begins 2026-03-05 for mobile release" |
+| **reference** | Where info lives in external systems | "Pipeline bugs tracked in Linear project INGEST" |
+
+## What NOT to save
+
+- Code patterns / conventions / file paths (read the code).
+- Git history (use `git log`).
+- Debugging fix recipes (the fix is in the commit).
+- Anything in CLAUDE.md / `.cursorrules` / equivalent (those rules are universal).
+- Ephemeral state (use TaskCreate or `docs/CURRENT_WORK.md` instead).
+
+## Where memory lives — per tool
+
+| Tool | Built-in directory? | Recommended path |
+|---|---|---|
+| Claude Code | ✅ | `~/.claude/projects/<encoded-project-path>/memory/` |
+| Cursor | ❌ | `.memory/` at project root (gitignored) — DIY |
+| Copilot | ❌ | `.memory/` (DIY) |
+| Gemini CLI | ❌ | `.memory/` (DIY) |
+| Codex | ❌ | `.memory/` (DIY) |
+| Windsurf | ❌ | `.memory/` (DIY) |
+
+The pattern is the same. The directory location varies. On non-Claude tools, add `.memory/` to your `.gitignore` so personal memory entries don't leak into the repo.
+
+## File structure
+
+Inside the memory directory:
+
+```
+memory/
+├── MEMORY.md              # Index (always loaded into context, ≤ 200 lines)
+├── user_*.md              # User profile, preferences, role, knowledge
+├── feedback_*.md          # Corrections + validated approaches
+├── project_*.md           # Ongoing work, goals, deadlines
+└── reference_*.md         # Pointers to external systems
+```
+
+## How to save
+
+1. Write content to its own file with frontmatter:
+
+```markdown
+---
+name: short-name
+description: one-line for relevance matching
+type: user|feedback|project|reference
+---
+
+Body. For feedback/project: lead with rule, then **Why:** and **How to apply:** lines.
+```
+
+2. Add one-line pointer to `MEMORY.md`: `- [Title](file.md) — one-line hook`
+
+## Lessons (Reflector-produced feedback)
+
+Lessons distilled by the `reflector` role are a specialization of the `feedback`
+type. File name: `feedback_lesson-<slug>.md`. They carry the standard three keys
+plus reflector bookkeeping keys:
+
+```markdown
+---
+name: lesson-<slug>
+description: one-line for relevance matching
+type: feedback
+id: lesson-<slug>          # stable id for delta ops
+added: <YYYY-MM-DD>
+source: <session-id | commit | retro-line>   # provenance (required)
+hits: 1                    # times reinforced
+last_used: <YYYY-MM-DD>
+status: active             # active | stale | merged
+confidence: medium         # low | medium | high
+---
+
+<the lesson, one paragraph>
+
+**Why:** <why this matters>
+**How to apply:** <the concrete change to make next time>
+```
+
+Delta operations (applied by a human, or by the orchestrator on explicit GO):
+- `ADD` — new `feedback_lesson-*.md`.
+- `UPDATE` — bump `hits`, raise `confidence`, or refine wording of an existing lesson.
+- `STALE` — set `status: stale`; keep the file, drop its `MEMORY.md` index line.
+
+Proposals are staged (not applied) in `docs/REFLECTION-PROPOSALS.md`. The
+deterministic prune script (`.conductor/reflect/prune-lessons.sh`) keeps the
+active set bounded: it marks decayed and dead-path lessons `status: stale`
+(non-destructive) and removes only exact byte-duplicate files.
+
+## Anti-staleness
+
+Before recommending FROM memory, verify it's still true:
+- File path mentioned? Check it exists (`ls`, `Glob`).
+- Function/flag mentioned? `Grep` for it.
+- Recent activity claim? Prefer `git log` over recalling.
+
+"The memory says X exists" ≠ "X exists now."
+
+## Relationship to in-repo `docs/`
+
+| | `docs/` (in repo) | memory/ (per-user) |
+|---|---|---|
+| Travels with code | YES | NO |
+| Shared with collaborators | YES | NO |
+| Persists for the user | (if not deleted) | YES, across sessions/branches/clones |
+| Contains personal taste | NO (project conventions only) | YES |
+| Contains feedback history | NO | YES |
+
+The two are complementary. `docs/` is the project's brain; memory is YOUR brain on top of the project.
+
+## Tool-specific enforcement
+
+> **Claude-only mechanism**: Claude Code auto-loads `MEMORY.md` at session start (when configured) and surfaces relevant `*.md` files based on the user's question.
+
+> **Other tools**: paste relevant memory entries into your prompt manually, or use the tool's "include this file" feature (Cursor: @-mention; Copilot: workspace context).
+
+## Examples
+
+See `EXAMPLES.md` for tool-agnostic worked examples of each memory type.
+
+## Status (P0 foundation)
+
+`EXAMPLES.md` is a placeholder. P1 fills with sanitized real examples derived from the reference adopter.