moflo 4.12.4-rc.8 → 4.12.4

package/.claude/guidance/shipped/moflo-sdd.md

@@ -27,16 +27,31 @@ Specs and plans persist as Markdown, one directory per unit of work, under the c
 <specs_dir>/<slug>/plan.md   # the "steps" + how each criterion is verified
 ```
 
-They are indexed into memory on session start, so `mcp__moflo__memory_search` surfaces prior specs across sessions. **Always create and mutate them through the `flo sdd` CLI** — never hand-write the path in a skill step (cross-platform, Rule #1: the CLI builds every path with `path.join`).
+**Always create and mutate them through the `flo sdd` CLI** — never hand-write the path in a skill step (cross-platform, Rule #1: the CLI builds every path with `path.join`).
 
-**Where they live is configurable (`sdd.specs_dir`, #1294).** The default `.moflo/specs` is **gitignored** by `flo init` — specs stay local and do not bloat source control, but they also do **not** appear in PRs. To make specs reviewable, point `sdd.specs_dir` at a **tracked** path and commit them:
+### Specs are NOT indexed into memory
+
+Earlier versions indexed `spec.md` / `plan.md` into the `guidance` namespace. They no longer are, and the specs directory is excluded from the guidance walk even when it sits inside a `guidance.directories` entry.
+
+A spec is pre-implementation intent for **one** unit of work, not a project rule. Once implemented it is stale-by-construction, and specs accumulate without bound — so a superseded approach kept surfacing at high similarity alongside real guidance, and the namespace degraded as the project aged. Nothing was gained in exchange: the active spec's path is already known (the `flo sdd` CLI just returned it), so **read it from disk** rather than searching for it.
+
+| To… | Use |
+|---|---|
+| Read the spec/plan you are working on | `Read` the path `flo sdd` returned |
+| Find prior specs across sessions | `flo sdd list` / `flo sdd status <slug>` |
+| Recall what an implementation actually taught you | `memory_search` namespace `learnings` |
+| Recall a past verify verdict | `memory_search` namespace `verify` |
+
+Existing spec rows are removed by the `purge-spec-chunks` migration on the next session start.
+
+**Where specs live is configurable (`sdd.specs_dir`, #1294).** The default `.moflo/specs` is **gitignored** by `flo init`. To make specs reviewable in the PR, point `sdd.specs_dir` at a **tracked** path and commit them:
 
 | `sdd.specs_dir` | Committed? | Use when |
 |-----------------|------------|----------|
-| `.moflo/specs` (default) | No (gitignored) | You want the SDD workflow but not spec artifacts in history |
-| `docs/specs`, `.specs`, … (tracked) | Yes | You want specs reviewed in the PR alongside the code |
+| `.moflo/specs` (default) | No (gitignored) | Specs are scratch — the PR body carries the acceptance criteria. Best at high spec volume. |
+| `docs/specs`, `.specs`, … (tracked) | Yes | You want the spec diffed and reviewed alongside the code |
 
-Set it once in `moflo.yaml`; the `flo sdd` CLI and the session-start indexer both honor it. If the path sits inside a `guidance.directories` entry, specs are indexed once (as guidance), not twice.
+Set it once in `moflo.yaml`; the `flo sdd` CLI and the session-start indexer both honor it — the CLI to write specs there, the indexer to exclude them.
 
 Each artifact carries a `status` of `draft` or `reviewed` in its frontmatter. The constitution layer (`CLAUDE.md` + `.claude/guidance/`) is referenced by every stage — never restate its invariants inside a spec.
 

package/.claude/helpers/gate.cjs

@@ -132,6 +132,26 @@ function readMofloYaml() {
 }
 var MOFLO_YAML = readMofloYaml();
 
+// #1394 — is the hook that transcribes /verify's verdict into workflow-state.json
+// actually wired? Distinguishes "the agent skipped Step 5" from "nothing exists
+// to record the verdict", which need opposite remedies: the first is fixed by
+// re-running /verify, the second cannot be.
+//
+// Deliberately NOT hoisted to module scope like MOFLO_YAML: this is only ever
+// consulted on an already-blocked check-before-done path, so reading it eagerly
+// would add a syscall to every Write/Edit to answer a question almost no gate
+// invocation asks. Substring match (not a JSON walk) so it holds regardless of
+// which matcher block a consumer's hook lives in, or how they hand-edited it.
+// Unreadable/malformed settings → true, so a parse failure falls back to the
+// pre-existing generic message rather than asserting a wiring bug that may not
+// exist.
+function isVerifyOutcomeHookWired() {
+  try {
+    return fs.readFileSync(path.join(PROJECT_DIR, '.claude', 'settings.json'), 'utf-8')
+      .indexOf('record-verify-outcome') >= 0;
+  } catch (e) { return true; }
+}
+
 var config = loadGateConfig();
 var sddConf = loadSddConfig();
 var mergeConf = loadMergeConfig();
@@ -724,7 +744,22 @@ var EDIT_RESET_SKIP_BOTH_RE = /\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:^
 // pure noise. Scoped to the reset only — deliberately NOT added to EXEMPT,
 // which would also un-gate reads of `.moflo/specs/**`, and those are indexed
 // guidance that memory-first should still route through a search.
-var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\/])\.github[\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\/.]|$)|(?:^|[\\\/])\.moflo[\\\/]/i;
+// #1395 — `.claude/` CONFIG joins them, by the same "doesn't expose new runtime
+// surface" reasoning: hook wiring, skills and guidance are not the code under
+// verification. This is the stronger case, in fact — it is the directory a user
+// edits *because a gate told them to*. Before this, fixing hook wiring on a
+// gate's own instruction reset verifyRun and invalidated the verification the
+// fix existed to let through, so the recovery was: fix wiring → verification
+// invalidated → restart session → re-run /verify → retry (#1392 field report).
+//
+// Scoped to config, NOT all of `.claude/**`: `scripts/` and `helpers/` hold
+// executable runtime surface (gate.cjs itself lives there), and editing
+// executable code SHOULD still invalidate a verification. Listing the config
+// subdirectories explicitly keeps that invariant intact.
+//
+// Both separators in every alternative — a bare `/` here would silently no-op
+// on Windows, where TOOL_INPUT paths arrive backslashed (Rule #1).
+var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\/])\.github[\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\/.]|$)|(?:^|[\\\/])\.moflo[\\\/]|(?:^|[\\\/])\.claude[\\\/](?:settings(?:\.local)?\.json$|skills[\\\/]|guidance[\\\/]|agents[\\\/])/i;
 // Test files: invalidate the testing gate (tests are stale once test code changes)
 // but NOT the simplify gate — /simplify already reviewed the production code; touching
 // a test file or fixture doesn't expose new untested surface for code review (#908).
@@ -1728,14 +1763,25 @@ switch (command) {
       process.stderr.write('  - /verify ran and returned ' + sd.verifyOutcome + ' — fix the failing criteria, then re-run /verify\n');
       process.stderr.write('    (a FAIL is a real result, not a gate error; the PR is blocked because the change did not meet its acceptance criteria)\n');
     } else {
-      // Ran, but no verdict reached the gate: /verify was invoked and never
-      // recorded a structured outcome (interrupted, or it stored prose only).
-      process.stderr.write('  - /verify ran but recorded no verdict — re-run it so it stores a structured result\n');
-      process.stderr.write('    (Step 5 of the verify skill must pass metadata.overall to memory_store)\n');
-      // #1348 — the trap this state sets: re-invoking /verify CLEARS any prior
-      // verdict by design (#1332), so the obvious recovery lands right back here
-      // unless Step 5 completes. Say so, rather than letting it be rediscovered.
-      process.stderr.write('    Re-invoking /verify clears the prior verdict, so a re-run that skips Step 5 lands here again.\n');
+      // Ran, but no verdict reached the gate. TWO very different causes, and
+      // #1394 exists because they used to share one message that fit only the
+      // first: either /verify never recorded a structured outcome, or the hook
+      // that TRANSCRIBES the outcome is not wired, in which case a perfectly
+      // correct verdict was stored and nothing could carry it to the gate.
+      // Blaming the agent for the second case sends the user into an unbounded
+      // retry loop — re-running /verify cannot fix absent wiring.
+      if (!isVerifyOutcomeHookWired()) {
+        process.stderr.write('  - `record-verify-outcome` is not wired in .claude/settings.json — the verdict cannot be recorded\n');
+        process.stderr.write('    /verify may well have passed; nothing exists to transcribe its result, so re-running it will not help.\n');
+        process.stderr.write('    Fix: run `flo doctor --fix`, restart the session (Claude Code loads hooks only at start), then re-run /verify.\n');
+      } else {
+        process.stderr.write('  - /verify ran but recorded no verdict — re-run it so it stores a structured result\n');
+        process.stderr.write('    (Step 5 of the verify skill must pass metadata.overall to memory_store)\n');
+        // #1348 — the trap this state sets: re-invoking /verify CLEARS any prior
+        // verdict by design (#1332), so the obvious recovery lands right back here
+        // unless Step 5 completes. Say so, rather than letting it be rediscovered.
+        process.stderr.write('    Re-invoking /verify clears the prior verdict, so a re-run that skips Step 5 lands here again.\n');
+      }
     }
     process.stderr.write(ORDER_HINT);
     process.stderr.write('Disable via moflo.yaml:\n');

package/.claude/helpers/prompt-hook.mjs

@@ -23,6 +23,15 @@ try { if (stdinData.trim()) hookContext = JSON.parse(stdinData); } catch (e) {}
 var userPrompt = hookContext.user_prompt || hookContext.prompt || '';
 var env = Object.assign({}, process.env, { CLAUDE_USER_PROMPT: userPrompt });
 
+// #1397 — forward Claude Code's session_id, same contract as gate-hook.mjs:33.
+// `prompt-reminder` stamps it onto workflow-state.json (gate.cjs), which is the
+// only place `flo runs start` can read it from; without it every run record got
+// sessionId:null and a zeroed token rollup. prompt-reminder is invoked through
+// THIS wrapper, not gate-hook.mjs, so the id has to be forwarded here too.
+if (typeof hookContext.session_id === 'string' && hookContext.session_id) {
+  env.HOOK_SESSION_ID = hookContext.session_id;
+}
+
 // Run prompt-reminder via gate.cjs
 var projectDir = (env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var gateScript = resolve(projectDir, '.claude/helpers/gate.cjs');

package/.claude/skills/fl/phases.md

@@ -161,11 +161,13 @@ The `check-before-pr` gate blocks `gh pr create` until `/flo-simplify` has run s
 git add <specific files>
 git commit -m "type(scope): description
 
-Closes #<issue-number>
-
-Co-Authored-By: moflo <noreply@cielolimitada.com>"
+Closes #<issue-number>"
 ```
 
+**No attribution trailer.** Do not add `Co-Authored-By:`, `Generated with …`, or any
+other tool-attribution line to commits or PR bodies (#1398). This is the consumer's
+repository and their git history is permanent — moflo does not sign their commits.
+
 ### 5.1b Verify-before-done (default; skipped only with `--no-verify`)
 **Delegate to the `/verify` skill** — `Skill({ skill: "verify" })`, passing the issue number or spec slug. That skill owns the mechanics (locate acceptance criteria → reuse Phase 4's already-green tests, no double verify → map each criterion → run only uncovered checks → record the outcome). Don't restate them here or verify in prose — *invoking* `/verify` is what records the run and satisfies the `check-before-done` gate.
 

package/bin/gate.cjs

@@ -132,6 +132,26 @@ function readMofloYaml() {
 }
 var MOFLO_YAML = readMofloYaml();
 
+// #1394 — is the hook that transcribes /verify's verdict into workflow-state.json
+// actually wired? Distinguishes "the agent skipped Step 5" from "nothing exists
+// to record the verdict", which need opposite remedies: the first is fixed by
+// re-running /verify, the second cannot be.
+//
+// Deliberately NOT hoisted to module scope like MOFLO_YAML: this is only ever
+// consulted on an already-blocked check-before-done path, so reading it eagerly
+// would add a syscall to every Write/Edit to answer a question almost no gate
+// invocation asks. Substring match (not a JSON walk) so it holds regardless of
+// which matcher block a consumer's hook lives in, or how they hand-edited it.
+// Unreadable/malformed settings → true, so a parse failure falls back to the
+// pre-existing generic message rather than asserting a wiring bug that may not
+// exist.
+function isVerifyOutcomeHookWired() {
+  try {
+    return fs.readFileSync(path.join(PROJECT_DIR, '.claude', 'settings.json'), 'utf-8')
+      .indexOf('record-verify-outcome') >= 0;
+  } catch (e) { return true; }
+}
+
 var config = loadGateConfig();
 var sddConf = loadSddConfig();
 var mergeConf = loadMergeConfig();
@@ -724,7 +744,22 @@ var EDIT_RESET_SKIP_BOTH_RE = /\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:^
 // pure noise. Scoped to the reset only — deliberately NOT added to EXEMPT,
 // which would also un-gate reads of `.moflo/specs/**`, and those are indexed
 // guidance that memory-first should still route through a search.
-var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\/])\.github[\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\/.]|$)|(?:^|[\\\/])\.moflo[\\\/]/i;
+// #1395 — `.claude/` CONFIG joins them, by the same "doesn't expose new runtime
+// surface" reasoning: hook wiring, skills and guidance are not the code under
+// verification. This is the stronger case, in fact — it is the directory a user
+// edits *because a gate told them to*. Before this, fixing hook wiring on a
+// gate's own instruction reset verifyRun and invalidated the verification the
+// fix existed to let through, so the recovery was: fix wiring → verification
+// invalidated → restart session → re-run /verify → retry (#1392 field report).
+//
+// Scoped to config, NOT all of `.claude/**`: `scripts/` and `helpers/` hold
+// executable runtime surface (gate.cjs itself lives there), and editing
+// executable code SHOULD still invalidate a verification. Listing the config
+// subdirectories explicitly keeps that invariant intact.
+//
+// Both separators in every alternative — a bare `/` here would silently no-op
+// on Windows, where TOOL_INPUT paths arrive backslashed (Rule #1).
+var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\/])\.github[\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\/.]|$)|(?:^|[\\\/])\.moflo[\\\/]|(?:^|[\\\/])\.claude[\\\/](?:settings(?:\.local)?\.json$|skills[\\\/]|guidance[\\\/]|agents[\\\/])/i;
 // Test files: invalidate the testing gate (tests are stale once test code changes)
 // but NOT the simplify gate — /simplify already reviewed the production code; touching
 // a test file or fixture doesn't expose new untested surface for code review (#908).
@@ -1728,14 +1763,25 @@ switch (command) {
       process.stderr.write('  - /verify ran and returned ' + sd.verifyOutcome + ' — fix the failing criteria, then re-run /verify\n');
       process.stderr.write('    (a FAIL is a real result, not a gate error; the PR is blocked because the change did not meet its acceptance criteria)\n');
     } else {
-      // Ran, but no verdict reached the gate: /verify was invoked and never
-      // recorded a structured outcome (interrupted, or it stored prose only).
-      process.stderr.write('  - /verify ran but recorded no verdict — re-run it so it stores a structured result\n');
-      process.stderr.write('    (Step 5 of the verify skill must pass metadata.overall to memory_store)\n');
-      // #1348 — the trap this state sets: re-invoking /verify CLEARS any prior
-      // verdict by design (#1332), so the obvious recovery lands right back here
-      // unless Step 5 completes. Say so, rather than letting it be rediscovered.
-      process.stderr.write('    Re-invoking /verify clears the prior verdict, so a re-run that skips Step 5 lands here again.\n');
+      // Ran, but no verdict reached the gate. TWO very different causes, and
+      // #1394 exists because they used to share one message that fit only the
+      // first: either /verify never recorded a structured outcome, or the hook
+      // that TRANSCRIBES the outcome is not wired, in which case a perfectly
+      // correct verdict was stored and nothing could carry it to the gate.
+      // Blaming the agent for the second case sends the user into an unbounded
+      // retry loop — re-running /verify cannot fix absent wiring.
+      if (!isVerifyOutcomeHookWired()) {
+        process.stderr.write('  - `record-verify-outcome` is not wired in .claude/settings.json — the verdict cannot be recorded\n');
+        process.stderr.write('    /verify may well have passed; nothing exists to transcribe its result, so re-running it will not help.\n');
+        process.stderr.write('    Fix: run `flo doctor --fix`, restart the session (Claude Code loads hooks only at start), then re-run /verify.\n');
+      } else {
+        process.stderr.write('  - /verify ran but recorded no verdict — re-run it so it stores a structured result\n');
+        process.stderr.write('    (Step 5 of the verify skill must pass metadata.overall to memory_store)\n');
+        // #1348 — the trap this state sets: re-invoking /verify CLEARS any prior
+        // verdict by design (#1332), so the obvious recovery lands right back here
+        // unless Step 5 completes. Say so, rather than letting it be rediscovered.
+        process.stderr.write('    Re-invoking /verify clears the prior verdict, so a re-run that skips Step 5 lands here again.\n');
+      }
     }
     process.stderr.write(ORDER_HINT);
     process.stderr.write('Disable via moflo.yaml:\n');

package/bin/index-guidance.mjs

@@ -47,6 +47,28 @@ const DB_PATH = memoryDbPath(projectRoot);
 // Load guidance directories from moflo.yaml, falling back to defaults
 // ============================================================================
 
+/**
+ * Absolute path to the project's SDD specs directory (default `.moflo/specs`).
+ *
+ * Validation MUST match `specsRoot()` in `src/cli/sdd/artifacts.ts` exactly, or
+ * the indexer and the CLI would disagree on where specs live: reject absolute /
+ * drive-letter / parent-escape values and fall back to the default.
+ *
+ * Cross-platform (Rule #1): split the /-written config value and re-join with
+ * `path.resolve`, never hardcode a separator.
+ */
+function resolveSpecsDir(specsDirConfig) {
+  const raw = specsDirConfig || '.moflo/specs';
+  let rel = raw.split(/[\\/]+/).filter(Boolean);
+  const escapes = rel.length === 0
+    || rel.includes('..')
+    || /^([a-zA-Z]:|~)$/.test(rel[0])
+    || raw.startsWith('/')
+    || raw.startsWith('\\');
+  if (escapes) rel = ['.moflo', 'specs'];
+  return resolve(projectRoot, ...rel);
+}
+
 function loadGuidanceDirs() {
   const dirs = [];
 
@@ -115,38 +137,34 @@ function loadGuidanceDirs() {
     dirs.push({ path: bundledSkillsDir, prefix: 'skill-bundled', fileFilter: ['SKILL.md'], kind: 'skill', absolute: true });
   }
 
-  // 6. SDD spec/plan artifacts (Epic #1269) — index <specs_dir>/<slug>/{spec,plan}.md
-  //    so prior specs/plans are searchable across sessions. kind: 'spec' keys each
-  //    file by <slug>-<spec|plan> to avoid collisions between per-slug spec.md files.
-  //    #1294 — the location is configurable (default .moflo/specs). Cross-platform
-  //    (Rule #1): split the /-written value and re-join, never hardcode a separator.
-  //    Validation MUST match specsRoot() in src/cli/sdd/artifacts.ts exactly, or
-  //    the indexer and the CLI would disagree on where specs live: reject
-  //    absolute / drive-letter / parent-escape values and fall back to the default.
-  const rawSpecs = specsDirConfig || '.moflo/specs';
-  let specsRel = rawSpecs.split(/[\\/]+/).filter(Boolean);
-  const specsEscapes = specsRel.length === 0
-    || specsRel.includes('..')
-    || /^([a-zA-Z]:|~)$/.test(specsRel[0])
-    || rawSpecs.startsWith('/')
-    || rawSpecs.startsWith('\\');
-  if (specsEscapes) specsRel = ['.moflo', 'specs'];
-  const projectSpecsDir = resolve(projectRoot, ...specsRel);
-  // Double-index guard: if specs_dir sits inside a guidance dir, the guidance
-  // scan (step 1) already indexes those .md files — skip the 'spec' entry so
-  // they aren't indexed twice under two prefixes.
-  const insideGuidance = userDirs.some(d => {
-    const gd = resolve(projectRoot, ...d.split(/[\\/]+/).filter(Boolean));
-    return projectSpecsDir === gd || projectSpecsDir.startsWith(gd + sep);
-  });
-  if (existsSync(projectSpecsDir) && !insideGuidance) {
-    dirs.push({ path: specsRel.join('/'), prefix: 'spec', fileFilter: ['spec.md', 'plan.md'], kind: 'spec' });
-  }
-
-  return dirs;
+  // 6. SDD spec/plan artifacts are NOT indexed.
+  //
+  //    They were (Epic #1269, kind: 'spec'), into this same `guidance` namespace.
+  //    That was wrong on both axes:
+  //
+  //    - Signal: a spec is PRE-implementation intent for one unit of work, not a
+  //      project rule. Once implemented it is stale-by-construction, and a
+  //      superseded approach surfacing at high similarity alongside real guidance
+  //      is worse than absent. Specs accumulate without bound, so the guidance
+  //      namespace degraded monotonically with project age.
+  //    - Value: the active spec's path is already known (the `flo sdd` CLI just
+  //      returned it) — reading it beats chunked retrieval of a doc you hold the
+  //      path to. Cross-session discovery is served by `flo sdd list`, and the
+  //      durable post-implementation signal already lands in `learnings` /
+  //      `verify`.
+  //
+  //    So the specs directory is EXCLUDED from the walk rather than merely
+  //    skipped. Exclusion (not just dropping the step-6 entry) is what makes this
+  //    correct for the config `moflo-sdd.md` recommends for reviewable specs —
+  //    a tracked `specs_dir` INSIDE a guidance dir, where the step-1 scan would
+  //    otherwise pick spec.md/plan.md up as ordinary guidance markdown and
+  //    reintroduce the pollution under a guidance prefix.
+  const specsDir = resolveSpecsDir(specsDirConfig);
+
+  return { dirs, excludeRoots: [specsDir] };
 }
 
-const GUIDANCE_DIRS = loadGuidanceDirs();
+const { dirs: GUIDANCE_DIRS, excludeRoots: EXCLUDE_ROOTS } = loadGuidanceDirs();
 
 // Chunking config - optimized for Claude's retrieval
 const MIN_CHUNK_SIZE = 50;    // Lower minimum to avoid mega-chunks
@@ -612,8 +630,15 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
       };
     });
 
+    // keyPattern is load-bearing, not belt-and-braces: `${chunkPrefix}-%` as a
+    // bare LIKE also matches every chunk of any sibling doc whose name extends
+    // this one's (indexing `flo` matches `chunk-skill-flo-simplify-0`). Those
+    // rows aren't in chunkRows, so the orphan sweep deleted the sibling's whole
+    // index whenever THIS doc changed. Anchoring on the numeric chunk suffix
+    // confines the sweep to the keys this file actually owns.
     const counts = applyIncrementalChunks(db, NAMESPACE, chunkRows, {
       keyPrefix: `${chunkPrefix}-`,
+      keyPattern: new RegExp(`^${chunkPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-\\d+$`),
     });
     if (verbose) {
       debug(`  Doc ${docKey}: inserted=${counts.inserted} updated=${counts.updated} unchanged=${counts.unchanged} removed=${counts.removed}`);
@@ -628,20 +653,28 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
 /**
  * Recursively collect all .md files under a directory.
  * Skips node_modules, .git, and other non-content directories.
+ *
+ * `excludeRoots` (absolute paths) prunes whole subtrees — used to keep the SDD
+ * specs directory out of the index even when it sits inside a guidance dir.
+ * Compares resolved absolute paths, never raw strings, and matches on a
+ * `path.sep` boundary so `docs/specs` cannot also prune `docs/specs-guide`.
  */
-function walkMdFiles(dir) {
+function walkMdFiles(dir, excludeRoots = []) {
   const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.reports']);
   // CLAUDE.md is loaded into context by Claude automatically — skip to avoid duplicate vectors
   const SKIP_FILES = new Set(['CLAUDE.md']);
   const files = [];
 
+  const isExcluded = (p) => excludeRoots.some(root => p === root || p.startsWith(root + sep));
+
   function walk(current) {
     if (!existsSync(current)) return;
     for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const full = resolve(current, entry.name);
       if (entry.isDirectory()) {
-        if (!SKIP_DIRS.has(entry.name)) walk(resolve(current, entry.name));
+        if (!SKIP_DIRS.has(entry.name) && !isExcluded(full)) walk(full);
       } else if (entry.isFile() && entry.name.endsWith('.md') && !SKIP_FILES.has(entry.name)) {
-        files.push(resolve(current, entry.name));
+        if (!isExcluded(full)) files.push(full);
       }
     }
   }
@@ -659,7 +692,7 @@ function indexDirectory(db, dirConfig) {
     return results;
   }
 
-  const allMdFiles = walkMdFiles(dirPath);
+  const allMdFiles = walkMdFiles(dirPath, EXCLUDE_ROOTS);
   const filtered = dirConfig.fileFilter
     ? allMdFiles.filter(f => dirConfig.fileFilter.includes(basename(f)))
     : allMdFiles;
@@ -674,17 +707,6 @@ function indexDirectory(db, dirConfig) {
         extraMetadata: { kind: 'skill', skill_name: skillName },
         extraTags: ['skill', `skill-${skillName}`],
       };
-    } else if (dirConfig.kind === 'spec') {
-      // kind: 'spec' (Epic #1269) — key by <slug>-<spec|plan> so a spec.md and
-      // plan.md under the same slug, and identically-named files across slugs,
-      // never collide on the doc key.
-      const slug = basename(dirname(filePath));
-      const artifact = basename(filePath, extname(filePath)); // 'spec' | 'plan'
-      options = {
-        nameOverride: `${slug}-${artifact}`,
-        extraMetadata: { kind: 'spec', spec_slug: slug, artifact },
-        extraTags: ['spec', `spec-${slug}`, artifact],
-      };
     }
     const result = indexFile(db, filePath, dirConfig.prefix, options);
     results.push(result);
@@ -693,37 +715,77 @@ function indexDirectory(db, dirConfig) {
   return results;
 }
 
+/**
+ * Derive a chunk row's owning doc prefix from its key.
+ *
+ * Chunk keys are `${chunkPrefix}-${i}`, so stripping the FINAL `-<digits>`
+ * recovers the prefix. Only the last segment is stripped, which keeps
+ * docs whose filename itself ends in digits intact:
+ * `chunk-guidance-issue-1402-0` → `chunk-guidance-issue-1402`, not
+ * `chunk-guidance-issue`.
+ *
+ * Returns null for a key with no numeric suffix — those are not chunk rows
+ * this indexer wrote, and the caller leaves them alone rather than guessing.
+ */
+function chunkPrefixOf(key) {
+  const m = key.match(/^(.*)-\d+$/);
+  return m ? m[1] : null;
+}
+
 /**
  * Remove stale entries for files that no longer exist on disk.
- * Uses the set of docKeys seen during the current indexing run to determine
- * which entries are stale, rather than reconstructing file paths from keys
- * (which breaks for files in subdirectories).
+ *
+ * Keyed on the chunk prefixes seen during the current run, NOT on `doc-*` rows.
+ * The original implementation enumerated `key LIKE 'doc-%'` and treated any doc
+ * key absent from the run as a deleted file — but #1053 S4 retired doc rows
+ * (the chunker stopped writing them and `purge-doc-entries` deleted the rest),
+ * so on any current install that query returns zero rows and the sweep was a
+ * silent no-op. Deleting a guidance file left its chunks — embeddings and all —
+ * in the namespace permanently, with nothing downstream to detect it. Specs made
+ * that visible because they accumulate fastest, but it stranded chunks for every
+ * deleted guidance file, skill, and doc.
+ *
+ * Safety: an empty live set means the run indexed nothing (I/O error, config
+ * pointing at a missing tree). Sweeping then would wipe the namespace, so bail
+ * and leave the rows for a later healthy run to reconcile.
  */
-function cleanStaleEntries(db, currentDocKeys) {
-  const docsStmt = db.prepare(
-    `SELECT DISTINCT key FROM memory_entries WHERE namespace = ? AND key LIKE 'doc-%'`
+function cleanStaleEntries(db, currentChunkPrefixes) {
+  if (currentChunkPrefixes.size === 0) {
+    log('  Skipped: this run indexed no files (refusing to sweep on an empty live set)');
+    return 0;
+  }
+
+  const chunkStmt = db.prepare(
+    `SELECT DISTINCT key FROM memory_entries WHERE namespace = ? AND key LIKE 'chunk-%'`
   );
-  docsStmt.bind([NAMESPACE]);
-  const docs = [];
-  while (docsStmt.step()) docs.push(docsStmt.getAsObject());
-  docsStmt.free();
+  chunkStmt.bind([NAMESPACE]);
+  const chunkKeys = [];
+  while (chunkStmt.step()) chunkKeys.push(chunkStmt.getAsObject().key);
+  chunkStmt.free();
+
+  // Group stale chunk keys by prefix so the log reports one line per deleted
+  // file rather than one per chunk.
+  const stalePrefixes = new Map();
+  for (const key of chunkKeys) {
+    const prefix = chunkPrefixOf(key);
+    if (!prefix || currentChunkPrefixes.has(prefix)) continue;
+    stalePrefixes.set(prefix, (stalePrefixes.get(prefix) ?? 0) + 1);
+  }
 
   let staleCount = 0;
-
-  for (const { key } of docs) {
-    // If this doc key was seen during the current indexing run, it's not stale
-    if (currentDocKeys.has(key)) continue;
-
-    const chunkPrefix = key.replace('doc-', 'chunk-');
-    const countBefore = db.exec(`SELECT COUNT(*) as cnt FROM memory_entries WHERE namespace = '${NAMESPACE}'`)[0]?.values[0][0] || 0;
-    db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key LIKE ?`, [NAMESPACE, `${chunkPrefix}%`]);
-    db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key = ?`, [NAMESPACE, key]);
-    const countAfter = db.exec(`SELECT COUNT(*) as cnt FROM memory_entries WHERE namespace = '${NAMESPACE}'`)[0]?.values[0][0] || 0;
-    const removed = countBefore - countAfter;
-    if (removed > 0) {
-      log(`  Removed ${removed} stale entries for deleted file: ${key}`);
-      staleCount += removed;
+  const del = db.prepare(`DELETE FROM memory_entries WHERE namespace = ? AND key = ?`);
+  try {
+    for (const key of chunkKeys) {
+      const prefix = chunkPrefixOf(key);
+      if (!prefix || currentChunkPrefixes.has(prefix)) continue;
+      del.run([NAMESPACE, key]);
+      staleCount++;
     }
+  } finally {
+    del.free();
+  }
+  for (const [prefix, count] of stalePrefixes) {
+    log(`  Removed ${count} stale entries for deleted file: ${prefix}`);
   }
 
   // Also clean any orphaned entries not matching doc-/chunk- patterns
@@ -740,6 +802,22 @@ function cleanStaleEntries(db, currentDocKeys) {
     log(`  Removed orphan entry: ${key}`);
   }
 
+  // Legacy `doc-*` rows from a pre-#1053-S4 install that never ran the
+  // purge-doc-entries migration. Unconditional — the chunker has not written
+  // one since S4, so any survivor is stale by definition.
+  const docStmt = db.prepare(
+    `SELECT key FROM memory_entries WHERE namespace = ? AND key LIKE 'doc-%'`
+  );
+  docStmt.bind([NAMESPACE]);
+  const legacyDocs = [];
+  while (docStmt.step()) legacyDocs.push(docStmt.getAsObject().key);
+  docStmt.free();
+  for (const key of legacyDocs) {
+    db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key = ?`, [NAMESPACE, key]);
+    staleCount++;
+    log(`  Removed legacy doc entry: ${key}`);
+  }
+
   return staleCount;
 }
 
@@ -760,7 +838,10 @@ let docsIndexed = 0;
 let chunksIndexed = 0;
 let unchanged = 0;
 let errors = 0;
-const currentDocKeys = new Set();
+// Chunk prefixes written by this run — the live set the stale sweep diffs
+// against. Populated from every file that indexed OR was skipped as unchanged;
+// an unchanged file is very much still on disk.
+const currentChunkPrefixes = new Set();
 
 if (specificFile) {
   // Index single file
@@ -794,7 +875,7 @@ if (specificFile) {
 
     for (const result of results) {
       if (result.status === 'indexed' || result.status === 'unchanged') {
-        currentDocKeys.add(result.docKey);
+        currentChunkPrefixes.add(result.docKey.replace(/^doc-/, 'chunk-'));
       }
       if (result.status === 'indexed') {
         log(`  ✅ ${result.docKey} (${result.chunks} chunks)`);
@@ -814,7 +895,7 @@ if (specificFile) {
 let staleRemoved = 0;
 if (!specificFile) {
   log('Cleaning stale entries for deleted files...');
-  staleRemoved = cleanStaleEntries(db, currentDocKeys);
+  staleRemoved = cleanStaleEntries(db, currentChunkPrefixes);
   if (staleRemoved === 0) {
     log('  No stale entries found');
   }

package/bin/lib/incremental-write.mjs

@@ -98,9 +98,12 @@ export function schemeTaggedContentHash(files, schemeVersion) {
  * @param {string} namespace
  * @param {string} [keyPrefix] — when set, restricts the scan to `key LIKE '<prefix>%'`.
  *   The same prefix scopes the orphan sweep in {@link applyIncrementalChunks}.
+ * @param {RegExp} [keyPattern] — optional second filter applied in JS after the
+ *   SQL `LIKE`. Required whenever one caller's `keyPrefix` can be a string
+ *   prefix of another's — see {@link applyIncrementalChunks}.
  * @returns {Map<string,string>}
  */
-export function loadExistingContent(db, namespace, keyPrefix) {
+export function loadExistingContent(db, namespace, keyPrefix, keyPattern) {
   const stmt = keyPrefix
     ? db.prepare(
         `SELECT key, content FROM memory_entries WHERE namespace = ? AND key LIKE ? AND status = 'active'`,
@@ -116,7 +119,9 @@ export function loadExistingContent(db, namespace, keyPrefix) {
   const map = new Map();
   while (stmt.step()) {
     const row = stmt.getAsObject();
-    map.set(String(row.key), String(row.content ?? ''));
+    const key = String(row.key);
+    if (keyPattern && !keyPattern.test(key)) continue;
+    map.set(key, String(row.content ?? ''));
   }
   stmt.free();
   return map;
@@ -137,12 +142,21 @@ export function loadExistingContent(db, namespace, keyPrefix) {
  *   when processing a single file's chunks at a time (e.g. index-guidance.mjs
  *   iterates files independently) — without it the sweep would delete every
  *   chunk from every OTHER file as an orphan on each call.
+ * @param {RegExp} [opts.keyPattern] — narrows `keyPrefix` beyond what SQL `LIKE`
+ *   can express. REQUIRED when one file's prefix can be a string prefix of
+ *   another's, which is exactly the case for per-file chunk keys: indexing
+ *   `flo` scopes to `chunk-skill-flo-%`, and that LIKE also matches every chunk
+ *   of `flo-simplify`. Those rows are absent from the caller's `chunks`, so the
+ *   orphan sweep deleted a sibling document's entire index — it reappeared only
+ *   on the next run, re-inserted with a NULL embedding and re-vectorised from
+ *   scratch. Passing `/^chunk-skill-flo-\d+$/` confines the sweep to the chunk
+ *   keys the caller actually owns.
  * @returns {{inserted:number, updated:number, unchanged:number, removed:number}}
  */
 export function applyIncrementalChunks(db, namespace, chunks, opts = {}) {
   const serialize = opts.serialize !== false;
   const keyPrefix = opts.keyPrefix;
-  const existing = loadExistingContent(db, namespace, keyPrefix);
+  const existing = loadExistingContent(db, namespace, keyPrefix, opts.keyPattern);
   const newKeys = new Set();
   let inserted = 0;
   let updated = 0;

package/bin/migrations/purge-spec-chunks.mjs

@@ -0,0 +1,79 @@
+/**
+ * Migration: hard-delete SDD spec/plan chunks from the `guidance` namespace.
+ *
+ * `bin/index-guidance.mjs` used to index `<specs_dir>/<slug>/{spec,plan}.md`
+ * into `guidance` alongside real project guidance (Epic #1269, `kind: 'spec'`).
+ * A spec is pre-implementation intent for one unit of work, not a project rule:
+ * once implemented it is stale-by-construction, and specs accumulate without
+ * bound, so the namespace degraded monotonically with project age. The indexer
+ * now excludes the specs directory outright.
+ *
+ * This clears what earlier versions already wrote. Two shapes existed:
+ *
+ *   1. `chunk-spec-*` keys with `metadata.kind === 'spec'` — the dedicated
+ *      step-6 path, used when `specs_dir` sat OUTSIDE every guidance directory.
+ *   2. Ordinary guidance chunks under a guidance prefix — produced when
+ *      `specs_dir` sat INSIDE a guidance dir (the config `moflo-sdd.md`
+ *      recommends for reviewable specs). These carry no spec marker at all and
+ *      are indistinguishable from real guidance by key or metadata.
+ *
+ * Only shape 1 is purged here, because it is the only one that can be
+ * identified without guessing. Shape 2 is handled by the repaired stale sweep
+ * in `bin/index-guidance.mjs`: the specs directory is now pruned from the walk,
+ * so those chunk prefixes fall out of the live set on the next index run and
+ * are swept as deleted files. Deleting them here by path-matching would risk
+ * taking real guidance with them.
+ *
+ * Idempotent: re-runs find no matching rows.
+ *
+ * @module bin/migrations/purge-spec-chunks
+ */
+
+import { existsSync } from 'fs';
+import { memoryDbPath } from '../lib/moflo-paths.mjs';
+import { openBackend } from '../lib/get-backend.mjs';
+
+export const name = 'purge-spec-chunks';
+// After purge-doc-entries (0) and strip-context-preambles (20) so this operates
+// on an already-normalised chunk table.
+export const order = 30;
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<{purged:number}>}
+ */
+export async function run(projectRoot) {
+  const dbPath = memoryDbPath(projectRoot);
+  if (!existsSync(dbPath)) return { purged: 0 };
+
+  const db = await openBackend(projectRoot, { create: false });
+
+  // Two independent markers, OR'd, because they were written by the same code
+  // path and either alone would leave rows behind on a partial index:
+  //   - key prefix `chunk-spec-` (dirConfig.prefix === 'spec')
+  //   - metadata.kind === 'spec' (survives even if the prefix ever changed)
+  // Scoped to `guidance` — the only namespace bin/index-guidance.mjs writes —
+  // so a user-stored entry elsewhere that happens to match is never touched.
+  const WHERE = `namespace = 'guidance'
+      AND (key LIKE 'chunk-spec-%' OR metadata LIKE '%"kind":"spec"%')`;
+
+  const countStmt = db.prepare(`SELECT COUNT(*) AS cnt FROM memory_entries WHERE ${WHERE}`);
+  countStmt.step();
+  const beforeCount = Number(countStmt.getAsObject().cnt ?? 0);
+  countStmt.free();
+
+  if (beforeCount === 0) {
+    db.close();
+    return { purged: 0 };
+  }
+
+  db.run(`DELETE FROM memory_entries WHERE ${WHERE}`);
+  const purged = db.getRowsModified?.() ?? beforeCount;
+
+  // No explicit HNSW invalidation needed: the delete moves the DB/WAL mtime,
+  // which is exactly what the `hnsw-rebuild` step gates on, so the sidecar
+  // reconciles on the next session-start indexer pass.
+  if (purged > 0) db.save();
+  db.close();
+  return { purged };
+}

package/bin/prompt-hook.mjs

@@ -23,6 +23,15 @@ try { if (stdinData.trim()) hookContext = JSON.parse(stdinData); } catch (e) {}
 var userPrompt = hookContext.user_prompt || hookContext.prompt || '';
 var env = Object.assign({}, process.env, { CLAUDE_USER_PROMPT: userPrompt });
 
+// #1397 — forward Claude Code's session_id, same contract as gate-hook.mjs:33.
+// `prompt-reminder` stamps it onto workflow-state.json (gate.cjs), which is the
+// only place `flo runs start` can read it from; without it every run record got
+// sessionId:null and a zeroed token rollup. prompt-reminder is invoked through
+// THIS wrapper, not gate-hook.mjs, so the id has to be forwarded here too.
+if (typeof hookContext.session_id === 'string' && hookContext.session_id) {
+  env.HOOK_SESSION_ID = hookContext.session_id;
+}
+
 // Run prompt-reminder via gate.cjs
 var projectDir = (env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var gateScript = resolve(projectDir, '.claude/helpers/gate.cjs');

package/bin/session-start-launcher.mjs

@@ -1591,6 +1591,18 @@ try {
             settingsChanges.push(`repaired ${plural(repaired.length, 'hook wiring')}`);
           }
         }
+        // #1398 — strip the legacy attribution block. Claude Code reads this key
+        // and injects it into the agent's instructions, so an upgraded consumer
+        // keeps stamping moflo's identity into their commits until it is removed;
+        // dropping it from the generator alone only fixes fresh installs.
+        // `typeof` guard so an older installed moflo without the export is a
+        // silent no-op rather than a session-start crash.
+        if (typeof mod.removeLegacyAttribution === 'function') {
+          if (mod.removeLegacyAttribution(settings)) {
+            dirty = true;
+            settingsChanges.push('removed legacy attribution block');
+          }
+        }
       }
     } catch (err) {
       emitWarning(`hook-wiring repair skipped (${errMessage(err)})`);

package/dist/src/cli/init/helpers-generator.js

@@ -313,6 +313,18 @@ function readMofloYaml() {
 }
 var MOFLO_YAML = readMofloYaml();
 
+// #1394 — is the hook that transcribes /verify's verdict wired at all?
+// Distinguishes "agent skipped Step 5" from "nothing can record the verdict";
+// only the first is fixable by re-running /verify. Lazy (blocked path only);
+// unreadable settings → true so a parse failure keeps the generic message.
+// SYNC: mirrors bin/gate.cjs isVerifyOutcomeHookWired.
+function isVerifyOutcomeHookWired() {
+  try {
+    return fs.readFileSync(path.join(PROJECT_DIR, '.claude', 'settings.json'), 'utf-8')
+      .indexOf('record-verify-outcome') >= 0;
+  } catch (e) { return true; }
+}
+
 var config = loadGateConfig();
 var sddConf = loadSddConfig();
 var mergeConf = loadMergeConfig();
@@ -670,7 +682,10 @@ var EDIT_RESET_SKIP_BOTH_RE = /\\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:
 // #1297 — path-inert dirs (.github/workflows etc.); SYNC: mirrors bin/gate.cjs EDIT_RESET_SKIP_PATH_RE.
 // #1348 — plus \`.moflo/\`, moflo's own gitignored state dir: nothing written
 // there can reach the branch diff, so it must not invalidate a gate.
-var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\\\\/])\\.github[\\\\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\\\\/.]|$)|(?:^|[\\\\\\/])\\.moflo[\\\\\\/]/i;
+// #1395 — \`.claude/\` CONFIG (settings/skills/guidance/agents) joins them: it is
+// not the code under verification, and it is the directory a user edits because
+// a gate told them to. \`scripts/\`/\`helpers/\` stay OUT — they are executable.
+var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\\\\/])\\.github[\\\\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\\\\/.]|$)|(?:^|[\\\\\\/])\\.moflo[\\\\\\/]|(?:^|[\\\\\\/])\\.claude[\\\\\\/](?:settings(?:\\.local)?\\.json$|skills[\\\\\\/]|guidance[\\\\\\/]|agents[\\\\\\/])/i;
 // Test files: invalidate testsRun but preserve simplifyRun (#908) — /simplify
 // already reviewed the production code, touching tests/fixtures doesn't expose
 // new untested surface for code review.
@@ -1003,6 +1018,12 @@ switch (command) {
       process.stderr.write('  - the change has not been verified since the last code edit (run /verify)\\n');
     } else if (s.verifyOutcome === 'FAIL' || s.verifyOutcome === 'UNVERIFIED') {
       process.stderr.write('  - /verify ran and returned ' + s.verifyOutcome + ' — fix the failing criteria, then re-run /verify\\n');
+      // #1394 — two causes, opposite remedies. Re-running /verify cannot fix
+      // absent wiring, so never prescribe it when the transcriber is missing.
+    } else if (!isVerifyOutcomeHookWired()) {
+      process.stderr.write('  - \`record-verify-outcome\` is not wired in .claude/settings.json — the verdict cannot be recorded\\n');
+      process.stderr.write('    /verify may well have passed; nothing exists to transcribe its result, so re-running it will not help.\\n');
+      process.stderr.write('    Fix: run \`flo doctor --fix\`, restart the session, then re-run /verify.\\n');
     } else {
       process.stderr.write('  - /verify ran but recorded no verdict — re-run it so it stores a structured result\\n');
       // #1348 — re-invoking /verify clears the prior verdict by design (#1332),
@@ -1276,6 +1297,12 @@ try { if (stdinData.trim()) hookContext = JSON.parse(stdinData); } catch (e) {}
 var userPrompt = hookContext.user_prompt || hookContext.prompt || '';
 var env = Object.assign({}, process.env, { CLAUDE_USER_PROMPT: userPrompt });
 
+// #1397 — forward session_id so prompt-reminder can stamp it onto
+// workflow-state.json; \`flo runs start\` has no other source for it.
+if (typeof hookContext.session_id === 'string' && hookContext.session_id) {
+  env.HOOK_SESSION_ID = hookContext.session_id;
+}
+
 // Run prompt-reminder via gate.cjs
 var projectDir = (env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\\/([a-z])\\//i, '$1:/');
 var gateScript = resolve(projectDir, '.claude/helpers/gate.cjs');

package/dist/src/cli/init/moflo-init.js

@@ -21,7 +21,7 @@ import { loadShippedScripts } from './shipped-scripts.js';
 import { DEFAULT_INIT_OPTIONS } from './types.js';
 import { generateSettings } from './settings-generator.js';
 import { applyWholesaleRegeneration, computeHookBlockDrift, isHookBlockLocked, } from '../services/hook-block-hash.js';
-import { rewriteIncorrectHookWiring } from '../services/hook-wiring.js';
+import { rewriteIncorrectHookWiring, removeLegacyAttribution } from '../services/hook-wiring.js';
 export { discoverTestDirs };
 // ============================================================================
 // Init
@@ -253,11 +253,18 @@ function generateHooks(root, force, _answers) {
         // grafted back into the fresh tree.
         preserved = extraCount - removed;
     }
-    // Ensure statusLine + permissions/env/attribution scaffold is present —
-    // mirrors the existing moflo-init.ts UX but no longer overwrites user
-    // values that are already set.
+    // #1398 — strip the legacy attribution block on this path too, so `flo init`
+    // on an existing project and `doctor --fix` heal it as well as session start.
+    // NOT inert: Claude Code reads `settings.attribution` and injects it into the
+    // agent's instructions, so leaving it keeps moflo's trailer on the consumer's
+    // commits regardless of what the generator now emits.
+    const strippedAttribution = removeLegacyAttribution(existing);
+    // Ensure statusLine + permissions/env scaffold is present — mirrors the
+    // existing moflo-init.ts UX but no longer overwrites user values that are
+    // already set. `attribution` is deliberately absent from the scaffold list:
+    // the generator no longer emits it, so it could only ever copy `undefined`.
     const canonical = generateSettings({ ...DEFAULT_INIT_OPTIONS, targetDir: root, force: true });
-    const scaffoldKeys = ['statusLine', 'permissions', 'env', 'attribution'];
+    const scaffoldKeys = ['statusLine', 'permissions', 'env'];
     const scaffoldAdded = [];
     for (const key of scaffoldKeys) {
         if (existing[key] == null && canonical[key] != null) {
@@ -265,7 +272,8 @@ function generateHooks(root, force, _answers) {
             scaffoldAdded.push(key);
         }
     }
-    const dirty = rewroteCommands > 0 || added > 0 || removed > 0 || scaffoldAdded.length > 0;
+    const dirty = rewroteCommands > 0 || added > 0 || removed > 0 || scaffoldAdded.length > 0
+        || strippedAttribution;
     if (!dirty) {
         return { name: '.claude/settings.json', status: 'skipped', detail: 'already at canonical reference' };
     }
@@ -283,6 +291,8 @@ function generateHooks(root, force, _answers) {
         parts.push(`↻${rewroteCommands} rewrites`);
     if (scaffoldAdded.length > 0)
         parts.push(`+scaffold (${scaffoldAdded.join(',')})`);
+    if (strippedAttribution)
+        parts.push('-attribution (#1398)');
     return { name: '.claude/settings.json', status: 'updated', detail: parts.join(', ') };
 }
 // ============================================================================

package/dist/src/cli/init/settings-generator.js

@@ -37,11 +37,11 @@ export function generateSettings(options) {
             'Read(./.env.*)',
         ],
     };
-    // Add claude-flow attribution for git commits and PRs
-    settings.attribution = {
-        commit: 'Co-Authored-By: moflo <noreply@cielolimitada.com>',
-        pr: '🤖 Generated with [moflo](https://github.com/eric-cielo/moflo)',
-    };
+    // #1398 — no attribution block. moflo used to write a `Co-Authored-By` trailer
+    // and a "Generated with moflo" PR banner into every consumer's settings.json.
+    // Nothing ever read the key (the /flo skill hardcoded the literal instead), and
+    // stamping a tool's identity into someone else's permanent git history is not
+    // moflo's call to make. Do not reintroduce — see issue #1398.
     // Note: Claude Code expects 'model' to be a string, not an object
     // Model preferences are stored in moflo settings instead
     // settings.model = 'sonnet'; // Uncomment if you want to set a default model

package/dist/src/cli/memory/bridge-entries.js

@@ -30,6 +30,35 @@ function makeEntryCacheKey(namespace, key) {
     const safeKey = String(key).replace(/:/g, '_');
     return `entry:${safeNs}:${safeKey}`;
 }
+/**
+ * Minimum gap between `access_count` writes for a single key (#1402).
+ *
+ * #1396 made a cache hit bump `access_count`, which is correct — the counter
+ * feeds `sortBy('accessCount')` and stats, so a row read repeatedly inside the
+ * cache TTL must not look untouched. But `bridgeGetEntry` is called in fan-out
+ * loops, not once per user retrieve: the dashboard's `/api/schedules` and
+ * `/api/spells` handlers issue up to 300 `getEntry` calls between them, and the
+ * browser polls both every 5s — ~60 writes/sec against the same hot keys, where
+ * before the fix it was zero I/O.
+ *
+ * A global debounce timer would need a flush-on-exit hook, and moflo's
+ * short-lived CLI processes would silently drop counts on exit — the same
+ * "observability that quietly lies" failure #1396 existed to remove. Throttling
+ * per key needs no timer and no exit hook: the delta rides on the cached record
+ * itself, which every hit already touches.
+ *
+ * KNOWN RESIDUAL — not lossless, and deliberately so. If the cache evicts a
+ * record (5-minute TTL, or LRU at 10k entries) while its delta is unflushed,
+ * those accesses are gone; likewise a process crash mid-interval. Draining on
+ * eviction would mean issuing async DB work from `CacheManager.evictLRU`, a
+ * synchronous path in a different module — real blast radius on the memory
+ * chokepoint to recover at most one interval's counts for a key that, by virtue
+ * of being evicted, is not in a hot read loop. The keys this throttle exists
+ * for flush every interval, well inside the TTL. `access_count` feeds ordering
+ * and stats, not accounting, so a bounded undercount on cold keys is the right
+ * trade; a systematic undercount of HOT keys — the #1396 defect — is not.
+ */
+const ACCESS_FLUSH_INTERVAL_MS = 30_000;
 /** Normalise `metadata` for the `metadata` TEXT column; `undefined` → `'{}'` (#1064). */
 export function serialiseMetadata(metadata) {
     if (metadata == null)
@@ -81,6 +110,7 @@ async function cacheGet(registry, cacheKey) {
         return null;
     return (await cache.get(cacheKey)) ?? null;
 }
+/** Typed on purpose (#1396) — a partial cache value is a compile error, not a silent read-side data loss. */
 async function cacheSet(registry, cacheKey, value) {
     const cache = registry.get('tieredCache');
     if (!cache)
@@ -265,9 +295,18 @@ export async function bridgeStoreEntry(options) {
             // Without this, chunk-row producers writing through the chokepoint would
             // get `{}` back from cache and the full metadata from disk — exactly the
             // divergence the cache is supposed to mask.
+            //
+            // #1396 — and the same argument applies to every other column the reader
+            // returns. Warm the FULL CachedEntry shape, not just the embedding and
+            // metadata, or a retrieve inside the cache TTL reports empty tags, a zero
+            // access count, and a storedAt of "now".
             await cacheSet(registry, cacheKey, {
                 id, key, namespace, content: value,
-                embedding: embeddingJson,
+                accessCount: 0,
+                createdAt: now,
+                updatedAt: now,
+                hasEmbedding: !!embeddingJson,
+                tags,
                 metadata: metadataJson,
             });
         }
@@ -386,10 +425,14 @@ export async function bridgeStoreEntries(items, dbPath) {
                 anyEmbedded = true;
             deferredBookkeeping.push({
                 cacheKey: makeEntryCacheKey(namespace, key),
-                // #1064 — keep cache shape in sync with disk (see single-store path).
+                // #1064 / #1396 — keep cache shape in sync with disk (see single-store path).
                 cacheValue: {
                     id, key, namespace, content: value,
-                    embedding: embeddingJson,
+                    accessCount: 0,
+                    createdAt: now,
+                    updatedAt: now,
+                    hasEmbedding: !!embeddingJson,
+                    tags,
                     metadata: metadataJson,
                 },
                 entryId: id,
@@ -594,24 +637,98 @@ export async function bridgeGetEntry(options) {
         const { key, namespace = 'default' } = options;
         const cacheKey = makeEntryCacheKey(namespace, key);
         const cached = await cacheGet(registry, cacheKey);
-        if (cached && cached.content) {
-            return {
-                success: true,
-                found: true,
-                cacheHit: true,
-                entry: {
-                    id: String(cached.id || ''),
-                    key: cached.key || key,
-                    namespace: cached.namespace || namespace,
-                    content: cached.content || '',
-                    accessCount: cached.accessCount ?? 0,
-                    createdAt: cached.createdAt || new Date().toISOString(),
-                    updatedAt: cached.updatedAt || new Date().toISOString(),
-                    hasEmbedding: !!cached.embedding,
-                    tags: cached.tags || [],
-                    metadata: cached.metadata || undefined,
-                },
+        // A value written by a pre-#1396 build carries only
+        // `{id,key,namespace,content,embedding,metadata}`. Serving it means
+        // fabricating the absent columns — which IS the bug — so treat a partial
+        // value as a miss and fall through to the disk read, which returns the true
+        // row and re-caches the full shape. Self-heals on the first read after an
+        // in-place upgrade, and since the L1 cache is in-memory only, nothing
+        // outlives the process anyway.
+        // `content !== undefined` rather than a truthy test: a row whose content is
+        // legitimately `''` would otherwise fail this check on every read, be
+        // re-fetched from disk, re-cached as `''`, and fail again — a permanent
+        // cache bypass for that key. Pre-existing, but this is the condition it
+        // lives in.
+        const usableCache = cached
+            && cached.content !== undefined
+            && cached.createdAt !== undefined
+            && cached.hasEmbedding !== undefined
+            && Array.isArray(cached.tags);
+        if (usableCache) {
+            // #1396 — a cache hit is still an access. The access_count bump used to
+            // live only on the disk path below, so a row read repeatedly inside the
+            // cache TTL reported the same count forever — and `accessCount` is an
+            // orderable field (query-builder's `sortBy('accessCount')`) plus a stats
+            // input, so the hottest rows ranked as the coldest.
+            //
+            // #1402 — the write is THROTTLED per key. Every hit still increments the
+            // count the caller sees; the DB write is coalesced to at most one per
+            // ACCESS_FLUSH_INTERVAL_MS, because this function runs inside fan-out
+            // loops (see the constant's docstring) where a write-per-hit is ~60
+            // writes/sec against the same handful of keys.
+            //
+            // The UPDATE adds the accumulated delta and is evaluated by SQLite, so
+            // the stored counter stays correct under concurrency and never depends on
+            // a client-computed absolute. No persist call here on purpose — the disk
+            // path below has never had one either, because #1058 removed the
+            // read-side `db.export()` writeback that clobbered concurrent writers.
+            // Under node:sqlite the UPDATE is durable regardless.
+            const now = Date.now();
+            // MUTATE THE CACHED RECORD IN PLACE — do not rebuild it.
+            //
+            // The guarantee this rests on is OBJECT IDENTITY, not synchrony:
+            // `TieredCacheManager.get` is async, but it hands back the stored object
+            // unchanged from `CacheManager.get`, which returns `node.value.data` with
+            // no clone. So every concurrent reader of this key holds the SAME object,
+            // and the two lines below are a read-modify-write with no `await` between
+            // the read and the write — atomic under Node's single thread.
+            //
+            // Building a replacement record and writing it back with `cacheSet`
+            // instead reintroduces a lost update: both callers read the same delta
+            // across the await boundary and the second write clobbers the first,
+            // permanently dropping an access. That interleaving is reachable on the
+            // very workload this throttle is for — the neighbour fan-out fetches
+            // adjacent chunk keys in parallel and two hits can share a neighbour.
+            //
+            // If the cache ever starts cloning on read, the delta stops accumulating
+            // and this silently under-persists. `loses no counts when the same key is
+            // read concurrently` is the test that would catch it.
+            cached.accessCount = (cached.accessCount ?? 0) + 1;
+            cached.pendingAccessDelta = (cached.pendingAccessDelta ?? 0) + 1;
+            // A record with no flush stamp (pre-#1402 shape, or one this process has
+            // never flushed) flushes immediately rather than waiting out the interval.
+            const lastFlushAt = cached.lastAccessFlushAt ?? 0;
+            if (now - lastFlushAt >= ACCESS_FLUSH_INTERVAL_MS) {
+                try {
+                    ctx.db.prepare(`UPDATE memory_entries SET access_count = access_count + ?, last_accessed_at = ? WHERE id = ?`).run([cached.pendingAccessDelta, now, String(cached.id || '')]);
+                    // Clear ONLY after the write lands. Clearing on a throw would discard
+                    // the accumulated hits outright — the throttle defers writes, it does
+                    // not drop them.
+                    cached.pendingAccessDelta = 0;
+                    cached.lastAccessFlushAt = now;
+                }
+                catch {
+                    // Non-fatal — the delta rides along to the next attempt.
+                }
+            }
+            // Built field-by-field from the cached record rather than spread from it,
+            // so the throttle bookkeeping can never surface in an MCP response.
+            const entry = {
+                id: String(cached.id || ''),
+                key: cached.key || key,
+                namespace: cached.namespace || namespace,
+                content: cached.content,
+                accessCount: cached.accessCount,
+                createdAt: cached.createdAt,
+                updatedAt: cached.updatedAt,
+                hasEmbedding: cached.hasEmbedding,
+                tags: cached.tags,
+                metadata: cached.metadata || undefined,
             };
+            // No `cacheSet` here: the record above IS the cached object and was
+            // updated in place, so writing a copy back would be redundant work on the
+            // hot path — and would reopen the lost-update window this branch closes.
+            return { success: true, found: true, cacheHit: true, entry };
         }
         let row;
         try {
@@ -636,8 +753,13 @@ export async function bridgeGetEntry(options) {
         }
         if (!row)
             return { success: true, found: false };
+        // The disk path writes its own +1 immediately (it is by definition not a
+        // repeat read), so it doubles as this key's flush point: stamp `now` below
+        // and start the delta at 0 so the next cache hit begins a fresh interval
+        // rather than re-counting this access (#1402).
+        const diskReadAt = Date.now();
         try {
-            ctx.db.prepare(`UPDATE memory_entries SET access_count = access_count + 1, last_accessed_at = ? WHERE id = ?`).run([Date.now(), row.id]);
+            ctx.db.prepare(`UPDATE memory_entries SET access_count = access_count + 1, last_accessed_at = ? WHERE id = ?`).run([diskReadAt, row.id]);
         }
         catch {
             // Non-fatal
@@ -661,7 +783,11 @@ export async function bridgeGetEntry(options) {
             tags,
             metadata: row.metadata != null ? String(row.metadata) : undefined,
         };
-        await cacheSet(registry, cacheKey, entry);
+        await cacheSet(registry, cacheKey, {
+            ...entry,
+            pendingAccessDelta: 0,
+            lastAccessFlushAt: diskReadAt,
+        });
         return { success: true, found: true, cacheHit: false, entry };
     });
 }

package/dist/src/cli/services/hook-wiring.js

@@ -9,6 +9,52 @@
  * session-start-launcher.mjs in consumer projects, where transitive
  * dependencies (project-root.js, etc.) may not resolve.
  */
+/**
+ * #1398 — remove the legacy `attribution` block from a consumer's settings.json.
+ *
+ * This is NOT cosmetic cleanup. `settings.attribution` is read by Claude Code
+ * itself, which injects `attribution.commit` / `attribution.pr` into the agent's
+ * instructions — which is how the `Co-Authored-By: moflo …` trailer and the
+ * "Generated with moflo" PR banner actually reached commits. No moflo code reads
+ * the key, so it looks inert from inside this repo; it is not.
+ *
+ * Consequence: dropping the block from `settings-generator.ts` fixes FRESH
+ * installs only. Every project that upgrades keeps the key it was given at init
+ * and keeps stamping moflo's identity into its own permanent git history. The
+ * generator edit without this one is precisely the fresh-install-only change
+ * `internal/upgrade-contract.md` § "Design for the upgrade path first" warns about.
+ *
+ * Deletes only the exact keys moflo wrote. A consumer who set their own
+ * `attribution` deliberately keeps it — we remove ours, not theirs.
+ *
+ * @returns true when the settings object was modified.
+ */
+export function removeLegacyAttribution(settings) {
+    const attribution = settings.attribution;
+    // Array.isArray guard: `typeof [] === 'object'`, so a bogus array value would
+    // otherwise fall through to the empty-object check below and be reported as a
+    // change we didn't make — a spurious settings.json write on every session start.
+    if (!attribution || typeof attribution !== 'object' || Array.isArray(attribution))
+        return false;
+    const MOFLO_COMMIT = 'Co-Authored-By: moflo <noreply@cielolimitada.com>';
+    const MOFLO_PR = '\u{1F916} Generated with [moflo](https://github.com/eric-cielo/moflo)';
+    let changed = false;
+    if (attribution.commit === MOFLO_COMMIT) {
+        delete attribution.commit;
+        changed = true;
+    }
+    if (attribution.pr === MOFLO_PR) {
+        delete attribution.pr;
+        changed = true;
+    }
+    // Drop the now-empty container so the key doesn't linger as a puzzle for the
+    // next reader. A block still holding consumer-set values is left alone.
+    if (Object.keys(attribution).length === 0) {
+        delete settings.attribution;
+        changed = true;
+    }
+    return changed;
+}
 /**
  * Required hook matchers that must exist in settings.json for gate enforcement.
  * This is the single source of truth — doctor-checks-deep re-exports it.
@@ -38,9 +84,30 @@ export const REQUIRED_HOOK_WIRING = [
     // start; without it, only consumers who re-run `flo init` would get the
     // escape, and the deadlock would persist everywhere else.
     { event: 'PostToolUse', pattern: 'record-bash-swarm-init' },
+    // #1393 (found by the generator-parity guard) — the MCP halves that #1338
+    // left behind. check-before-agent hard-blocks every Agent spawn under
+    // `/fl -s` until `swarmInitialized` (gate.cjs:1201) and under `/fl -h` until
+    // `hiveInitialized` (gate.cjs:1209); these are the hooks that set them.
+    // #1338 added only the CLI half above, so on an UPGRADED consumer the
+    // primary path — the skill calling mcp__moflo__swarm_init — credited
+    // nothing and swarm/hive runs deadlocked exactly like #1392's verify gate.
+    // Routed via gate.cjs (not gate-hook.mjs) to match getReferenceHookBlock()
+    // in hook-block-hash.ts:164-165 — if the two disagree the drift detector
+    // fights the repair path every session start.
+    { event: 'PostToolUse', pattern: 'record-swarm-init' },
+    { event: 'PostToolUse', pattern: 'record-hive-init' },
     { event: 'PostToolUse', pattern: 'record-skill-run' },
     // Story #1274 — record the native /verify skill run so check-before-done is satisfied.
     { event: 'PostToolUse', pattern: 'record-verify-run' },
+    // #1393 — the transcriber that turns /verify's stored verdict into
+    // `verifyOutcome` on workflow-state.json. #1332 tightened check-before-done to
+    // require verifyOutcome === 'PASS' but wired this hook in settings-generator
+    // ONLY, so every project that UPGRADED (rather than re-running `flo init`) got
+    // a verify-before-done gate that could not be satisfied — /verify stored a
+    // correct PASS, nothing transcribed it, and the sole escape was
+    // `gates: verify_before_done: false`. Listed here so repairHookWiring grafts
+    // it in on next session start.
+    { event: 'PostToolUse', pattern: 'record-verify-outcome' },
     { event: 'PostToolUse', pattern: 'reset-edit-gates' },
     // First UserPromptSubmit hook (prompt-hook.mjs internally calls
     // `gate.cjs prompt-reminder`). Substring check tolerates either the
@@ -95,8 +162,21 @@ export const HOOK_ENTRY_MAP = {
     // #1338 follow-up — same Bash/PowerShell PostToolUse block as record-test-run.
     'record-bash-swarm-init': { event: 'PostToolUse', matcher: '^(Bash|PowerShell)$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" record-bash-swarm-init', timeout: 2000 } },
     'record-skill-run': { event: 'PostToolUse', matcher: '^Skill$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" record-skill-run', timeout: 2000 } },
+    // #1393 — MCP halves of the swarm/hive init recorders. gate.cjs (not
+    // gate-hook.mjs) and these exact matchers mirror hook-block-hash.ts:164-165
+    // and settings-generator.ts; all four copies must agree or the drift
+    // detector and repairHookWiring undo each other on every session start.
+    'record-swarm-init': { event: 'PostToolUse', matcher: '^mcp__moflo__swarm_init$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate.cjs" record-swarm-init', timeout: 2000 } },
+    'record-hive-init': { event: 'PostToolUse', matcher: '^mcp__moflo__hive-mind_init$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate.cjs" record-hive-init', timeout: 2000 } },
     // Story #1274 — record the native /verify skill run (same ^Skill$ matcher as record-skill-run).
     'record-verify-run': { event: 'PostToolUse', matcher: '^Skill$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" record-verify-run', timeout: 2000 } },
+    // #1393 — shares the ^mcp__moflo__memory_store$ block with record-learnings-stored;
+    // repairHookWiring appends it there rather than creating a second block.
+    // MUST route through gate-hook.mjs, NOT gate.cjs: the TOOL_INPUT_* env vars
+    // gate.cjs reads are built by gate-hook.mjs from the hook's stdin payload, so a
+    // direct gate.cjs invocation would see neither the key nor the `metadata` object
+    // carrying the verdict — the hook would fire and record nothing.
+    'record-verify-outcome': { event: 'PostToolUse', matcher: '^mcp__moflo__memory_store$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" record-verify-outcome', timeout: 2000 } },
     'reset-edit-gates': { event: 'PostToolUse', matcher: '^(Write|Edit|MultiEdit)$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" reset-edit-gates', timeout: 2000 } },
     // #931 — Agent-time advisory; never blocks. Pulled the TaskCreate REMINDER
     // and namespace hint out of prompt-reminder so they fire only when Claude is

package/dist/src/cli/shared/hooks/safety/git-commit.js

@@ -93,9 +93,13 @@ const DEFAULT_CONFIG = {
     maxSubjectLength: 72,
     maxBodyLength: 100,
     requireConventional: true,
-    addCoAuthor: true,
+    // #1398 — both default OFF. This hook used to append a "Generated with …"
+    // line and a Co-Authored-By trailer to every commit it processed. Tool
+    // attribution in a consumer's git history is permanent and not moflo's to
+    // add; callers who genuinely want it must opt in explicitly.
+    addCoAuthor: false,
     coAuthor: DEFAULT_CO_AUTHOR,
-    addClaudeReference: true,
+    addClaudeReference: false,
 };
 /**
  * Git Commit Hook Manager

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.12.4-rc.8';
+export const VERSION = '4.12.4';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.12.4-rc.8",
+  "version": "4.12.4",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -98,7 +98,7 @@
     "@typescript-eslint/parser": "^8.65.0",
     "eslint": "^10.8.0",
     "glob": "^11.1.0",
-    "moflo": "^4.12.4-rc.7",
+    "moflo": "^4.12.4-rc.10",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"