create-harness-vibe-coding 0.8.8 → 0.8.9

package/templates/common/Harness/scripts/wf-auto-update-prompt.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * wf-auto-update-prompt.mjs
+ *
+ * Lightweight hook helper for Claude Code, Codex, and OpenCode.
+ * It checks the installed Harness update plan and emits a prompt reminder only
+ * when an update is available. It never applies updates.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { spawnSync } from 'child_process';
+
+const DEFAULT_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_NOTICE_INTERVAL_MS = 60 * 60 * 1000;
+const args = process.argv.slice(2);
+const format = readFlagValue('--format') || 'plain';
+const force = args.includes('--force');
+const modeOnly = args.includes('--mode-only');
+const input = readStdinJson();
+const root = findRoot();
+
+function readFlagValue(flagName) {
+  const index = args.indexOf(flagName);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  return value && !value.startsWith('--') ? value : null;
+}
+
+function readStdinJson() {
+  try {
+    if (process.stdin.isTTY) return {};
+    const raw = readFileSync(0, 'utf-8').trim();
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function findRoot() {
+  const candidates = [
+    process.env.WF_ROOT,
+    input.cwd,
+    input.workspace,
+    process.cwd(),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    const found = ascendToHarnessRoot(resolve(candidate));
+    if (found) return found;
+  }
+  return process.cwd();
+}
+
+function ascendToHarnessRoot(start) {
+  let current = start;
+  for (;;) {
+    if (existsSync(resolve(current, 'Harness', '.harness-version'))) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function runtimeDir() {
+  return resolve(root, 'Harness', '.runtime');
+}
+
+function cachePath() {
+  return resolve(runtimeDir(), 'update-check.json');
+}
+
+function modePath() {
+  return resolve(runtimeDir(), 'current-mode.json');
+}
+
+function readJsonFile(file, fallback) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonFile(file, value) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+}
+
+function readVersion() {
+  return readJsonFile(resolve(root, 'Harness', '.harness-version'), null);
+}
+
+function shouldSkipPrompt() {
+  const prompt = String(input.prompt || input.message || '');
+  return /\b\/?wf-update\b|\$wf-update\b/.test(prompt);
+}
+
+function intervalFromEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function runUpdateCheck() {
+  const script = resolve(root, 'Harness', 'scripts', 'wf-update-check.mjs');
+  if (!existsSync(script)) {
+    return { status: 'error', message: 'Harness/scripts/wf-update-check.mjs not found.' };
+  }
+  const result = spawnSync(process.execPath, [script, '--json'], {
+    cwd: root,
+    encoding: 'utf-8',
+    timeout: intervalFromEnv('WF_UPDATE_CHECK_TIMEOUT_MS', 30000),
+    env: process.env,
+  });
+
+  if (result.error) {
+    return { status: 'offline', message: result.error.message };
+  }
+
+  const stdout = (result.stdout || '').trim();
+  if (!stdout) {
+    return { status: 'error', message: `Update checker exited with no JSON output (${result.status ?? 'unknown'}).` };
+  }
+
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return { status: 'error', message: 'Update checker returned invalid JSON.' };
+  }
+}
+
+function isUpdateStatus(status) {
+  return status === 'update-available' || status === 'partial-update';
+}
+
+function buildMessage(update) {
+  const from = update.from || update.version || 'unknown';
+  const to = update.to || update.remote || 'unknown';
+  const parts = [
+    `Harness update available: ${from} -> ${to}.`,
+    `Before unrelated work, ask the user whether to run /wf-update.`,
+  ];
+  // Only include summary counts — never list individual conflict files in hook output
+  if (update.conflict > 0) {
+    parts.push(`${update.conflict} conflict file(s) will need agent/user merge decisions.`);
+  }
+  if ((update.updated > 0 || update.created > 0) && update.updated !== undefined) {
+    const safeCount = (update.updated || 0) + (update.created || 0);
+    parts.push(`${safeCount} safe file update(s) available.`);
+  }
+  // Max 2 lines total, never include plan details
+  return parts.slice(0, 2).join(' ');
+}
+
+function readModeLabel() {
+  const mode = readJsonFile(modePath(), null);
+  if (!mode || !mode.active || !mode.mode) return null;
+  return `${mode.mode} mode on`;
+}
+
+function emit(message, payload = {}) {
+  if (!message && !payload.modeLabel) return;
+
+  if (format === 'claude') {
+    const context = [message, payload.modeLabel].filter(Boolean).join('\n');
+    if (context) console.log(JSON.stringify({ additionalContext: context }));
+    return;
+  }
+
+  if (format === 'codex') {
+    const context = [message, payload.modeLabel].filter(Boolean).join('\n');
+    if (context) {
+      console.log(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: input.hook_event_name || 'UserPromptSubmit',
+          additionalContext: context,
+        },
+      }));
+    }
+    return;
+  }
+
+  if (format === 'json') {
+    console.log(JSON.stringify({ message, ...payload }, null, 2));
+    return;
+  }
+
+  if (message) console.log(message);
+  if (payload.modeLabel) console.log(payload.modeLabel);
+}
+
+function main() {
+  if (!existsSync(resolve(root, 'Harness', '.harness-version'))) return;
+  const version = readVersion();
+  if (version?.autoCheck === false) return;
+
+  const modeLabel = readModeLabel();
+  if (modeOnly) {
+    emit('', { modeLabel, status: 'mode' });
+    return;
+  }
+
+  if (shouldSkipPrompt()) {
+    emit('', { modeLabel, status: 'skipped-update-command' });
+    return;
+  }
+
+  const now = Date.now();
+  const cache = readJsonFile(cachePath(), {});
+  const checkInterval = intervalFromEnv('WF_UPDATE_CHECK_INTERVAL_MS', DEFAULT_CHECK_INTERVAL_MS);
+  const noticeInterval = intervalFromEnv('WF_UPDATE_NOTICE_INTERVAL_MS', DEFAULT_NOTICE_INTERVAL_MS);
+
+  let update = cache.update;
+  const shouldCheck = force
+    || !cache.checkedAt
+    || now - Date.parse(cache.checkedAt) >= checkInterval;
+
+  if (shouldCheck) {
+    update = runUpdateCheck();
+    writeJsonFile(cachePath(), {
+      checkedAt: new Date(now).toISOString(),
+      noticedAt: cache.noticedAt || null,
+      update,
+    });
+  }
+
+  if (!isUpdateStatus(update?.status)) {
+    emit('', { modeLabel, status: update?.status || 'unknown' });
+    return;
+  }
+
+  const shouldNotice = force
+    || !cache.noticedAt
+    || now - Date.parse(cache.noticedAt) >= noticeInterval
+    || cache.update?.to !== update.to
+    || cache.update?.remote !== update.remote;
+
+  if (!shouldNotice) {
+    emit('', { modeLabel, status: update.status, suppressed: true });
+    return;
+  }
+
+  writeJsonFile(cachePath(), {
+    checkedAt: cache.checkedAt || new Date(now).toISOString(),
+    noticedAt: new Date(now).toISOString(),
+    update,
+  });
+
+  emit(buildMessage(update), { modeLabel, status: update.status, update });
+}
+
+try {
+  main();
+} catch {
+  // Hooks must fail open. A broken update reminder should never block work.
+}

package/templates/common/{scripts → Harness/scripts}/wf-update-check.mjs

@@ -7,8 +7,12 @@
  * Usage:
  *   node Harness/scripts/wf-update-check.mjs              # full dry-run plan
  *   node Harness/scripts/wf-update-check.mjs --json       # JSON output for AI consumption
+ *   node Harness/scripts/wf-update-check.mjs --json              # summary/counts + short agent hints only (token-safe)
+ *   node Harness/scripts/wf-update-check.mjs --json --full-plan  # also include full plan + conflict details (verbose)
  *   node Harness/scripts/wf-update-check.mjs --apply-safe # apply SAFE+NEW, leave CONFLICT for AI
  *   node Harness/scripts/wf-update-check.mjs --apply      # apply only when no CONFLICT exists
+ *
+ *   --full-plan and --verbose are aliases.
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, lstatSync } from 'fs';
@@ -187,9 +191,18 @@ async function main() {
   // 1. Read local state
   if (!existsSync(VERSION_FILE)) {
     if (jsonOut) {
-      console.log(JSON.stringify({ status: 'error', message: 'Local Harness/.harness-version not found.' }));
+      console.log(JSON.stringify({
+        status: 'error',
+        message: 'Local Harness/.harness-version not found. Is Harness installed?',
+        recovery: 'If this is an old Harness install that predates .harness-version, do not reinstall blindly. Restore Harness/.harness-version from backup if available. If the updater script is also missing, run from the project root: npx create-harness-vibe-coding@latest <name> . -y --on-conflict skip --json to restore missing updater infrastructure without overwriting user files.',
+      }));
     } else {
       console.error('ERROR: Harness/.harness-version not found. Is Harness installed?');
+      console.error('  If this is an old Harness install without version tracking, do not reinstall blindly.');
+      console.error('  Restore Harness/.harness-version from backup if available.');
+      console.error('  If the updater script is also missing, recover with:');
+      console.error('    npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip --json');
+      console.error('  This restores missing updater infrastructure without overwriting user data.');
     }
     process.exitCode = 1;
     return;
@@ -200,10 +213,16 @@ async function main() {
     localVersion = JSON.parse(readFileSync(VERSION_FILE, 'utf-8'));
   } catch (e) {
     if (jsonOut) {
-      console.log(JSON.stringify({ status: 'error', message: 'Failed to parse Harness/.harness-version: ' + e.message }));
+      console.log(JSON.stringify({
+        status: 'error',
+        message: 'Failed to parse Harness/.harness-version: ' + e.message,
+        recovery: 'The .harness-version file may be corrupted. Do not overwrite user files. Back up or move the corrupted Harness/.harness-version before manual recovery. If the updater script is also missing, run from the project root: npx create-harness-vibe-coding@latest <name> . -y --on-conflict skip --json to restore missing updater infrastructure.',
+      }));
     } else {
       console.error('ERROR: Failed to parse Harness/.harness-version:', e.message);
-      console.error('  The file may be corrupted. If this is an old project, try reinstalling the harness.');
+      console.error('  The file may be corrupted. Back up or move Harness/.harness-version before manual recovery.');
+      console.error('  If the updater script is also missing, recover with:');
+      console.error('    npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip --json');
     }
     process.exitCode = 1;
     return;
@@ -320,16 +339,26 @@ async function main() {
   }
 
   function buildJsonPlan() {
+    const verbose = args.includes('--verbose') || args.includes('--full-plan');
     return {
       updated: plan.updated.map(withRemoteMeta),
       created: plan.created.map(withRemoteMeta),
       adopted: plan.adopted.map(withRemoteMeta),
-      conflict: plan.conflict.map(withConflictActions),
+      conflict: verbose ? plan.conflict.map(withConflictActions) : plan.conflict.map(withConflictActions).slice(0, 5),
+      conflictTruncated: !verbose && plan.conflict.length > 5 ? plan.conflict.length - 5 : undefined,
       skipped: plan.skipped.map(withRemoteMeta),
     };
   }
 
   function buildAgentHints(jsonPlan) {
+    // Token-safe by default: omit the conflict array; full list available via --json --verbose (or --full-plan)
+    const verbose = args.includes('--verbose') || args.includes('--full-plan');
+    const maxConflictDetails = verbose ? Infinity : 5;
+    const totalConflicts = plan.conflict.length;
+    const conflicts = jsonPlan.conflict.slice(0, maxConflictDetails);
+    const truncated = totalConflicts > maxConflictDetails
+      ? totalConflicts - maxConflictDetails
+      : 0;
     return {
       mode: 'script-first-ai-conflicts',
       dryRunJsonCommand: 'node Harness/scripts/wf-update-check.mjs --json',
@@ -338,8 +367,10 @@ async function main() {
       finalizeCommand: 'node Harness/scripts/wf-update-check.mjs --finalize',
       partialUpdate: localVersion.partialUpdate || null,
       acceptedConflicts: localVersion.acceptedConflicts || {},
-      aiMergeRequired: jsonPlan.conflict,
-      aiMergeRequiredCount: jsonPlan.conflict.length,
+      // aiMergeRequired array is attached only in verbose mode to keep default output token-safe.
+      ...(verbose ? { aiMergeRequired: conflicts } : {}),
+      aiMergeRequiredCount: totalConflicts,
+      aiMergeRequiredTruncated: truncated > 0 ? truncated : undefined,
       conflictPolicy: 'Use the script for SAFE/NEW/adopted files. For each CONFLICT file, compare local content with templateHint/remoteUrl, then record the decision with --accept-local, --accept-merged, or --accept-template. Do not hand-edit Harness/.harness-version.',
       postUpdateCommands: [
         'node Harness/scripts/validate-harness.mjs',
@@ -512,6 +543,7 @@ async function main() {
 
   // 3. Output
   if (jsonOut) {
+    const verbose = args.includes('--verbose') || args.includes('--full-plan');
     const jsonPlan = buildJsonPlan();
     console.log(JSON.stringify({
       status: localVersion.partialUpdate ? 'partial-update' : 'update-available',
@@ -525,7 +557,8 @@ async function main() {
       adopted: plan.adopted.length,
       conflict: plan.conflict.length,
       skipped: plan.skipped.length,
-      plan: jsonPlan,
+      // Token-safe by default: attach the full plan only when --verbose / --full-plan is passed.
+      ...(verbose ? { plan: jsonPlan } : {}),
       agent: buildAgentHints(jsonPlan),
     }, null, 2));
     return;

package/templates/common/Harness/subagents.md

@@ -2,7 +2,7 @@
 
 Purpose: coordinate subagents for speed without losing control of scope, evidence, or integration.
 
-Use this file when work needs multiple roles, parallel reading, independent review, broad context, repeated failures, or `/wf`.
+Use this file when work needs multiple roles, parallel reading, independent review, broad context, repeated failures, or explicit `/wf` / `/wf-max` invocation.
 
 project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
@@ -43,20 +43,22 @@ Subagents provide bounded work. They do not own final scope, architecture, relea
 
 Use the installed roster under `.claude/agents/` before inventing ad hoc roles.
 
-| Agent | Default Use |
-| --- | --- |
-| `planner` | decompose goals, map unknowns, define success criteria and write sets |
-| `researcher` | local/external ecosystem context, comparable projects, current facts |
-| `docs-researcher` | official docs, SDK/API behavior, browser/tool constraints |
-| `architect` | boundaries, interface decoupling, state ownership, data flow, migration risk |
-| `test-writer` | failing tests, manual check contracts, browser/API evidence plan |
-| `implementer` | bounded code or doc changes after the second plan |
-| `reviewer` | spec compliance, code quality, maintainability, security, missing tests |
-| `debugger` | reproduced failures, root cause isolation, smallest safe fix |
-| `verifier` | command execution, real browser/API checks, final evidence |
-| `reflector` | closeout synthesis, unresolved-risk check, acceptance gate verdict |
-| `memory-master` | write/consolidate memory entries, dedup, cross-project extraction; dispatched on repeated failures, user corrections, and WF closeout |
-| `context-master` | analyze context usage, recommend compression at ~85% window, extract durable session knowledge during closeout |
+| Agent | Default Use | Model Tier |
+| --- | --- | --- |
+| `planner` | decompose goals, map unknowns, define success criteria and write sets | standard |
+| `researcher` | local/external ecosystem context, comparable projects, current facts | standard |
+| `docs-researcher` | official docs, SDK/API behavior, browser/tool constraints | standard |
+| `architect` | boundaries, interface decoupling, state ownership, data flow, migration risk | standard |
+| `test-writer` | failing tests, manual check contracts, browser/API evidence plan | standard |
+| `implementer` | bounded code or doc changes after the second plan | standard |
+| `reviewer` | spec compliance, code quality, maintainability, security, missing tests | standard |
+| `debugger` | reproduced failures, root cause isolation, smallest safe fix | standard |
+| `verifier` | command execution, real browser/API checks, final evidence | standard or small-fast |
+| `reflector` | closeout synthesis, unresolved-risk check, acceptance gate verdict | standard |
+| `task-scribe` | task state, heartbeat, dispatch ledger, evidence pointers — NEVER source code | small-fast (haiku) |
+| `codebase-explorer` | scoped read-only source exploration, file discovery, symbol tracing | small-fast (haiku) |
+| `context-master` | analyze context usage, recommend compression at ~85% window, extract durable session knowledge during closeout | small-fast (haiku) |
+| `memory-master` | write/consolidate memory entries, dedup, cross-project extraction; dispatched on repeated failures, user corrections, and WF closeout | standard |
 
 ## Acceptance Role Passes
 
@@ -80,8 +82,10 @@ Hard rule: implementer may not be the independent validator for the same AC ID.
 
 ## WF Default Fan-Out
 
-Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` requires complete
-role-chain coverage from `.claude/agents/` before closeout: plan,
+Explicit `/wf`, `$wf`, or `/skills wf` requires tier-specific role coverage per `Harness/WF.md`.
+WF-Light: planner + test-writer + implementer + verifier.
+WF-Standard: adds research/docs + one review lens.
+WF-Full: complete role-chain coverage from `.claude/agents/` before closeout: plan,
 research/docs research as needed, architecture, test, implement, independent
 validation, cross-review, reflector, and accept.
 
@@ -102,7 +106,7 @@ Then add phase-specific agents:
 - `context-master` before closeout for knowledge extraction
 - `memory-master` after repeated failures and during closeout for consolidation
 
-Collaboration mode is determined by concrete conditions, not a fixed ratio. See `Harness/WF.md#Complete Role Chain Requirement` for the full decision tree. Summary: explicit WF/WK mode always uses the complete role chain. 3+ files or cross-layer work uses multi-agent orchestration. 1-2 local files, well-understood, not in WF mode can be solo. Repeated failure stops solo work and switches to multi-agent.
+Collaboration mode is determined by WF tier and concrete conditions, not a fixed ratio. See `Harness/WF.md` for the tier decision guide. Summary: WF-Light uses minimal roles. WF-Standard uses moderate roles with one review lens. WF-Full always uses the complete role chain. Non-WF complex work may still use subagents and planning without entering any WF mode. Repeated failure after two attempts escalates to next tier.
 
 ## Efficiency Ladder
 
@@ -115,7 +119,7 @@ Choose the cheapest coordination level that is safe.
 | Parallel read-only | broad reading, research, architecture, multiple independent failures | 2-3 read-only agents |
 | Serial build lane | normal feature or fix | acceptance/contract -> test-writer -> implementer -> verifier evidence -> cross-review -> reflector -> acceptance |
 | Isolated lanes | disjoint write sets or competing approaches | separate worktrees, then review and merge |
-| Max parallelism | 5+ disjoint files, fan-out benefit > coordination cost | /wf max: write-set coloring -> wave dispatch -> parallel review |
+| Max parallelism | 5+ disjoint files, fan-out benefit > coordination cost | /wf-max: write-set coloring -> wave dispatch -> parallel review |
 
 Max parallelism removes the Harness default cap, not the runtime's physical or
 account cap. For WF-MAX, record the current runtime budget, use native
@@ -127,10 +131,7 @@ bottleneck, ask the user before raising `agents.max_threads` and keep
 `max_depth = 1` unless recursive delegation is explicitly approved. Do not rely
 on undocumented fork/derive bypasses as stable capacity.
 
-Default for automatic WF triggers: 3-5 active read-only agents before second
-planning. For explicit WF/WK mode, never use the solo pass; schedule the
-complete role chain and use bounded role passes as the recorded fallback when
-subagents are unavailable.
+Default for explicit WF invocation: tier-based. WF-Light: planner + test-writer + implementer + verifier (bounded passes acceptable). WF-Standard: adds research/docs + one independent review lens. WF-Full: complete role chain, use bounded role passes as the recorded fallback when subagents are unavailable.
 
 ## WF Orchestration Shape
 
@@ -148,10 +149,10 @@ controller intake
 -> close with evidence
 ```
 
-Use this shape for `/wf`, long tasks, multi-file changes, architecture work, migrations, browser/API behavior, or repeated failures.
+Use this shape for explicit `/wf`, `/wf-max`, or non-WF complex work with subagents.
 
 ```text
-/wf max orchestration shape:
+/wf-max orchestration shape:
 controller intake
 -> wave 0: max-parallel exploration (4-14 read-only agents)
 -> E-GATE: Exploration Gate - all questions answered, findings synthesized (per WF-MAX.md)
@@ -167,14 +168,14 @@ controller intake
 
 ## Dispatch Pack
 
-Use the canonical dispatch input and handoff format in `Harness/dispatch.md`. Every subagent dispatch must be self-contained - inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`.
+Use the canonical dispatch input and handoff format in `Harness/dispatch.md`. Every subagent dispatch must be self-contained - inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`. On session start, the controller reads `Harness/tasks/<task-id>/STATE.json` per [WF-STATE.md](WF-STATE.md) to resume the dispatch ledger and ready queue.
 
 ## Parallelism Rules
 
 - Read-only agents may run in parallel.
 - Writing agents run serially unless write sets are disjoint and the controller has chosen an isolated worktree.
 - Reviewers may run in parallel after implementation, but spec compliance is evaluated before code-quality approval.
-- Subagents are readers and reporters. They return findings and PLAN patch suggestions. Only the controller (main agent) commits state changes to task files.
+- Subagents are readers and reporters. They return findings and PLAN patch suggestions. Only the controller (main agent) or task-scribe commits state changes to task files. Production source agents (implementer, debugger, test-writer) never write task state unless explicitly dispatched as task-scribe.
 - Do not let two agents edit `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, `Harness/MEMORY.md`, or `Harness/memory/*` concurrently. The controller writes durable state.
 - If two agents disagree, the controller records the conflict in `Harness/tasks/<task-id>/PLAN.md` and chooses the smallest reversible next step.
 

package/templates/common/Harness/tasks/_template/PLAN.md

@@ -35,6 +35,11 @@ Forbidden:
 -
 - Truth files (PRD, ACs, UI/API contracts, test plan, validation report) unless a Change Request is recorded.
 
+## Memory Preflight
+
+- Memory preflight: done | exempt | blocked
+- Memory hints: none | <file/path + reason>
+
 ## Context
 
 - Loaded:

package/templates/common/Harness/tasks/_template/STATE.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "taskId": "task-example",
+  "status": "active",
+  "mode": "direct",
+  "tier": "none",
+  "phase": "intake",
+  "gate": null,
+  "updatedAt": "2026-07-16T00:00:00.000Z",
+  "activeQuestion": null,
+  "nextAction": "Define goal and acceptance criteria",
+  "acceptance": [],
+  "queues": {
+    "ready": [],
+    "running": [],
+    "blocked": [],
+    "done": []
+  },
+  "dispatchLedger": [],
+  "decisions": [],
+  "risks": [],
+  "artifacts": []
+}

package/templates/common/README.md

@@ -37,7 +37,7 @@ The agentic engineering harness lives in `Harness/`.
 - Start at `Harness/README.md`.
 - Load memory and resource registrations from `Harness/MEMORY.md`.
 - Track active work in `Harness/PROGRESS.md` and `Harness/tasks/<task-id>/PROGRESS.md`.
-- Use `Harness/WF.md` for long, difficult, multi-agent work.
+- Use `Harness/WF.md` only when the user explicitly invokes a WF command such as `/wf` or `/wf-max`; complex work may still use direct planning, tests, and subagents without entering WF.
   - Claude Code: invoke the `wf` skill with `/wf`.
   - Codex: invoke the `wf` skill with `$wf` or `/skills`.
 - Use `Harness/subagents.md` when coordinating multiple agents.

package/templates/common/memory/agent-lessons-patterns.md

@@ -7,15 +7,16 @@ Write here when:
 - A validation failure exposes a missing regression check.
 - A handoff, dispatch, or context-loading pattern should be repeated or avoided.
 
-Entry format, newest first:
+Entry format (compact, default no date):
 
 ```markdown
-## YYYY-MM-DD - Short Lesson Name
-
-- Lesson: the reusable pattern.
-- Source: review finding, debug loop, failed verification, or handoff.
-- Apply when: the task shape or files where this matters.
-- Regression guard: test, validator check, docs update, or manual evidence to keep it from recurring.
+- When <scenario>: <rule>. Avoid <over-application>. Signals: <signals>.
 ```
 
-Keep entries lightweight and actionable. Avoid secrets and speculative lessons.
+Only use date/timestamp headings when:
+- Entry supersedes prior conflicting guidance
+- Time-sensitive context (version, deprecation)
+- Conflict resolution needed
+
+Keep entries lightweight and actionable. Avoid secrets, speculative lessons, task logs, and process summaries.
+- Entry supersedes prior conflicting guidance: add date stamp.

package/templates/common/memory/routes.md

@@ -0,0 +1,43 @@
+# Memory Routes (L3 Route Index)
+
+> L3 = 详细 durable memory 路由索引。不是详细 memory，而是命中规则索引。
+> 详细 memory 文件按 scenario 匹配后按需加载。
+
+| id | signals | load | avoid |
+| --- | --- | --- | --- |
+| explicit-user-preference | remember, next time, 下次, 记住, 不要再, never, always, I prefer | user-corrections-preferences.md | current-task-only notes, transient mood |
+| hooks-only-wf-auto | hook, runtime hook, .claude/settings.json, .codex/hooks.json, WF-AUTO.md | agent-lessons-patterns.md#only-wf-auto-may-use-runtime-hooks | non-runtime docs, broad hook designs |
+| tool-repeat-failure | same command fails 3x, error signature repeats | tool-usage-reflections.md | one-off command failures |
+| review-debug-lesson | reusable review/debug/validation pattern | agent-lessons-patterns.md | task-specific logs |
+| startup-digest | new session, startup | startup-hints.md | full MEMORY.md index |
+| wf-closeout | /wf-learn, workflow closeout | all memory files via context-master -> memory-master | premature writes before extraction |
+
+## Matching Algorithm
+
+1. 把当前请求压缩成 **scenario pack**: intent / files / commands / signals / risk
+2. 与上表 Signals 列匹配，计算 score:
+   - +4 exact file/path match
+   - +3 explicit trigger phrase match
+   - +3 command/error signature match
+   - +2 workflow/mode match
+   - +1 keyword overlap
+   - -4 avoid match
+3. 阈值:
+   - score >= 5: 加载对应 memory entry/file section
+   - score 3-4: 只加载 route 摘要，必要时再读详细文件
+   - score < 3: 不加载
+4. Hard trigger 优先:
+   - 用户显式记忆语句 -> user-corrections-preferences.md
+   - 同命令失败 3 次 -> tool-usage-reflections.md
+   - review/debug/validation 可复用 lesson -> agent-lessons-patterns.md
+   - 修改 hook 相关文件 -> 加载 only-wf-auto hook lesson
+   - /wf-learn -> 完整 learning cycle
+
+## Load Logging
+
+每次加载 memory hints 需说明原因:
+```
+memory hints loaded: <id> because <signal>
+```
+
+不使用 embedding；保持稳定、可解释、省 token。

package/templates/common/memory/startup-hints.md

@@ -0,0 +1,32 @@
+# Startup Hints (L2 Memory Digest)
+
+> L2 = 启动极简 memory digest。每次 Harness 会话启动可读此文件，但不要加载完整 Harness/MEMORY.md 或 Harness/README.md。
+
+## Core Principles
+
+- Memory 是短场景规则，不是 task log。
+- 时间戳默认不要写；只有 superseded / conflict / time-sensitive 才写。
+- Broad runtime hooks 禁止；只有 `/wf-auto` bounded tick hook 例外。
+- Direct mode 不加载完整 Harness router，但 startup-hints 是允许的轻量启动提示。
+- 详细 memory 仍按 `MEMORY_PROTOCOL.md` 场景命中后再读。
+
+## Memory Candidate Detection
+
+用户说以下触发词时，识别为 memory candidate：
+
+**英文**: remember, next time, don't, do not, never, always, I prefer, I want you to
+**中文**: 记住, 下次, 以后, 不要再, 总是, 永远不要, 我偏好, 我希望你以后
+
+## When to Write Memory
+
+- **Explicit user preference**: 清晰、安全、场景明确时，可立即写入 L3，不必等 `/wf-learn`。
+- **Repeated implicit correction**: 同一假设/模式被纠正 2+ 次。
+- **Tool/command failure**: 同类工具/命令失败 3+ 次。
+- **Review/debug lesson**: 只有可复用、能防回归时才写。
+
+## What NOT to Write
+
+- Task log、过程总结、一次性情绪
+- Raw logs、transcripts
+- Secrets, tokens, credentials, private data
+- 临时偏好、无复用价值的笔记

package/templates/common/memory/tool-usage-reflections.md

@@ -7,15 +7,16 @@ Write here when:
 - A more reliable command pattern replaces a brittle one.
 - The environment needs a durable fix, flag, path rule, shell syntax, or startup sequence.
 
-Entry format, newest first:
+Entry format (compact, default no date):
 
 ```markdown
-## YYYY-MM-DD - Short Pattern Name
-
-- Trigger: what failed or repeated.
-- Better pattern: the command, tool usage, or sequence to use next time.
-- Evidence: command output summary, error text, or affected environment.
-- Scope: when this applies and when it does not.
+- When <scenario>: <rule>. Avoid <over-application>. Signals: <signals>.
 ```
 
-Keep entries concise. Do not record secrets, credentials, private tokens, or one-off noise.
+Only use date/timestamp headings when:
+- Entry supersedes prior conflicting guidance
+- Time-sensitive context (version, deprecation)
+- Conflict resolution needed
+
+Never record one-off command failures. Never store secrets, credentials, or private tokens.
+- Entry supersedes prior conflicting guidance: add date stamp.