moflo 4.12.4 → 4.12.5

package/.claude/skills/guidance/SKILL.md

@@ -81,6 +81,7 @@ Apply the universal rules from `.claude/guidance/moflo-guidance-rules.md`. The r
 7. Avoid the listed anti-patterns
 8. Optimize for RAG chunking
 9. End with a `## See Also` section
+10. Never cite issue or PR numbers — write the rule, not where it came from
 
 ### Audience: Humans (`-h` flag) — lighter human ruleset
 
@@ -97,6 +98,7 @@ Drop the rules that serve Claude's RAG retrieval and imperative-mood enforcement
 | 7 | Avoid anti-patterns | **Modified** | Short prose preambles ARE allowed for humans; code-comments-as-rules still bad |
 | 8 | Optimize for RAG chunking | **Drop** | Humans don't query a vector index |
 | 9 | `## See Also` section at end | **Keep** | Helps human readers traverse to related docs |
+| 10 | No issue / PR citations | **Keep** | A bare issue number is unresolvable for any reader; provenance belongs in `git log` |
 
 ### Creating a new doc — scaffold this shape
 
@@ -139,6 +141,7 @@ For the loaded file, evaluate against the universal rules and report findings as
 | H2 headings are specific (not "Overview", "Configuration", "Examples") | list any generic ones |
 | Uses imperative voice for rules ("must"/"always"/"never") not hedged ("should"/"might"/"consider") | list hedged phrases found |
 | Has prose preamble before first rule | yes / no |
+| Cites issue or PR numbers (`(#NNNN)`, `issue #NNNN`, `Epic #NNNN`) | list every citation found |
 
 Then propose edits as concrete diffs — never rewrite the whole file unless the user asks.
 

package/.claude/skills/verify/SKILL.md

@@ -14,7 +14,7 @@ Prove the current change **actually does what it was supposed to** before it shi
 
 ## What satisfies the gate
 
-Invoking this skill (name `verify`) trips the `record-verify-run` hook, which flips the `verifyRun` state. **That alone does not open the gate** (#1332): `check-before-done` also requires the recorded verdict to be `PASS`, which reaches it from the `metadata.overall` your Step 5 store writes. So a run returning FAIL leaves `gh pr create` blocked — as it should, since the change did not meet its criteria — and a run that stores prose without `metadata` counts as *no verdict* and blocks too.
+Invoking this skill (name `verify`) trips the `record-verify-run` hook, which flips the `verifyRun` state. **That alone does not open the gate**: `check-before-done` also requires the recorded verdict to be `PASS`, which reaches it from the `metadata.overall` your Step 5 store writes. So a run returning FAIL leaves `gh pr create` blocked — as it should, since the change did not meet its criteria — and a run that stores prose without `metadata` counts as *no verdict* and blocks too.
 
 **Only `/verify` satisfies it** — `/ward` and `/quicken` are targeted audits, not an end-to-end verification. A source edit *after* verifying invalidates both the flag and the verdict, so run `/verify` as the last step before the PR.
 
@@ -26,7 +26,7 @@ Search memory before reading files, same as any task (satisfies `memory_first`,
 mcp__moflo__memory_search { query: "verify <feature keywords>", namespace: "verify" }
 ```
 
-**Search `verify`, never `learnings`.** Verdict records moved out of `learnings` in #1375 — see Step 5.
+**Search `verify`, never `learnings`.** Verdict records moved out of `learnings` — see Step 5.
 
 ## Step 1 — Locate the acceptance criteria
 
@@ -97,13 +97,13 @@ mcp__moflo__memory_store {
 }
 ```
 
-**Store to `verify`, never `learnings` (#1375).** A verdict is audit exhaust — one commit, one issue, criteria that never apply again — and `memory_search` returns a bounded set, so every verdict parked in `learnings` displaced a reusable lesson. The move is free: `record-learnings-stored` matches any `memory_store`, and `record-verify-outcome` keys on the `verify:` **key prefix**, not the namespace. Both gates still fire.
+**Store to `verify`, never `learnings`.** A verdict is audit exhaust — one commit, one issue, criteria that never apply again — and `memory_search` returns a bounded set, so every verdict parked in `learnings` displaced a reusable lesson. The move is free: `record-learnings-stored` matches any `memory_store`, and `record-verify-outcome` keys on the `verify:` **key prefix**, not the namespace. Both gates still fire.
 
 **Why both.** `value` is what gets embedded for semantic search, so it stays prose — a JSON blob there would degrade every future `verify` search. `metadata` is stored verbatim and not embedded, so the structure survives without that cost. `memory_retrieve` returns the parsed `metadata` object for non-chunk entries, which is what makes the record readable rather than write-only.
 
 **`freshlyExecuted` is required on every criterion, not optional.** Step 3 deliberately permits *citing* an earlier green run instead of re-executing. That is a sound cost optimisation, but it means evidence may be a citation rather than a fresh result — set `freshlyExecuted: false` when you cited. Without that flag a later reader silently inherits stale evidence and cannot tell a re-verified criterion from a re-cited one.
 
-**Never record an exit code.** Claude Code's `tool_response` for Bash carries `stdout`/`stderr` but **no exit status**, and PostToolUse does not fire at all when a command exits non-zero (#1322). `evidence` is therefore descriptive by necessity; a field named `exitCode` would be agent-narrated fiction, which is the problem this record exists to remove.
+**Never record an exit code.** Claude Code's `tool_response` for Bash carries `stdout`/`stderr` but **no exit status**, and PostToolUse does not fire at all when a command exits non-zero. `evidence` is therefore descriptive by necessity; a field named `exitCode` would be agent-narrated fiction, which is the problem this record exists to remove.
 
 `overall` MUST agree with the Step 4 rule — PASS iff no criterion is FAIL or UNVERIFIED. Record a FAIL as a FAIL; the store is the audit trail, and a verdict that only ever reads PASS is worth nothing.
 

package/bin/gate.cjs

@@ -963,6 +963,45 @@ function creditIsLive(flag, stored, scope) {
   return stored === now;
 }
 
+// #1410 — is this Bash command actually a `gh pr create` invocation? Delegates
+// to pr-create-command.cjs, which sanitises data regions (quotes, heredoc
+// bodies, comments) before looking for the command, so the gate neither misses
+// real invocations (newline-separated, piped, parenthesised) nor fires on
+// commands that merely quote the literal (`git commit -m "...gh pr create..."`).
+//
+// Fail-safe, in BOTH directions, because this runs on every Bash call in every
+// consumer. gate-hook.mjs maps a non-zero exit from this script to exit 2, so an
+// uncaught throw here does not degrade one gate — it blocks every Bash call the
+// consumer makes. So a load failure (partial `.claude/helpers` sync mid-upgrade,
+// hand-pruned install) AND a throw from the matcher itself both fall back to the
+// pre-#1410 regex: previous behaviour, not a wedged session.
+//
+// Not silent (#854, hook-authoring §4): the fallback path advises on stderr and
+// continues. If this ever fires it means the matcher crashed, which is worth
+// being loud about — and it cannot spam a healthy session, because a healthy
+// session never reaches it.
+var LEGACY_PR_CREATE_RE = /(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/;
+var prCreateMatcher = null;
+function isPrCreateCommand(cmd) {
+  if (prCreateMatcher === null) {
+    try {
+      prCreateMatcher = require('./pr-create-command.cjs').isPrCreateCommand;
+    } catch (e) {
+      prCreateMatcher = false;
+      process.stderr.write('moflo: pr-create-command.cjs unavailable (' + (e && e.message) + ') — PR gates fall back to the legacy matcher. Run `npx flo doctor --fix`.\n');
+    }
+    if (typeof prCreateMatcher !== 'function') prCreateMatcher = false;
+  }
+  if (prCreateMatcher) {
+    try {
+      return prCreateMatcher(cmd);
+    } catch (e) {
+      process.stderr.write('moflo: pr-create matcher threw (' + (e && e.message) + ') — falling back to the legacy matcher. Please report with the command that triggered it.\n');
+    }
+  }
+  return LEGACY_PR_CREATE_RE.test(cmd);
+}
+
 // Classifier-aware simplify gate skip. Returns a string reason if the gate
 // can be auto-passed, or null if /simplify must run. Uses simplify-classify.cjs
 // so the gate's "trivial" definition matches the skill's exactly.
@@ -1600,12 +1639,12 @@ switch (command) {
     break;
   }
   case 'check-before-pr': {
-    // Anchored to command-start (or chained via && / || / ;) so heredoc bodies
-    // and quoted strings that contain the literal "gh pr create" don't trip
-    // the gate during regular `git commit -m "...gh pr create..."` flows. The
-    // optional ENV=val prefix segment catches `GH_TOKEN=x gh pr create`.
+    // Anchored to command-start so heredoc bodies and quoted strings that
+    // contain the literal "gh pr create" don't trip the gate during regular
+    // `git commit -m "...gh pr create..."` flows, while still catching the
+    // chained, piped, parenthesised, and multi-line shapes (#1410).
     var cmd = process.env.TOOL_INPUT_command || '';
-    if (!/(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/.test(cmd)) break;
+    if (!isPrCreateCommand(cmd)) break;
     // #1374 — close the loop the TaskCreate reminder opens. Advisory: stdout,
     // no exit, and worded as a reminder, because a message may only claim to
     // block when it blocks (#1326). An open task list is a reporting failure,
@@ -1680,7 +1719,7 @@ switch (command) {
       }
     }
     var missing = [];
-    if (config.testing_gate && !s.testsRun) missing.push('tests have not run green since the last code edit (run npm test, vitest, jest, pytest, or similar — a run whose output reports failures does not count, #1322)');
+    if (config.testing_gate && !s.testsRun) missing.push('tests have not run green since the last code edit (run npm test, vitest, jest, pytest, or similar — a run whose output reports failures does not count)');
     if (config.simplify_gate && !s.simplifyRun) missing.push('/flo-simplify (or /distill) has not run since the last code edit');
     if (config.learnings_gate && !s.learningsStored) missing.push('learnings have not been stored (call mcp__moflo__memory_store)');
     if (missing.length === 0) break;
@@ -1716,7 +1755,7 @@ switch (command) {
     // command (docs-only diffs are exempt, so this never blocks a docs PR).
     if (!config.verify_before_done) break;
     var cmd = process.env.TOOL_INPUT_command || '';
-    if (!/(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/.test(cmd)) break;
+    if (!isPrCreateCommand(cmd)) break;
     // No-source-files exemption — a docs-only / path-inert diff needs no verify.
     var changedD = getChangedFilesVsBase();
     if (changedD && changedD.length > 0) {

package/bin/hooks.mjs

@@ -23,6 +23,9 @@ import { spawn } from 'child_process';
 import { existsSync, appendFileSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
+// A builtin, deliberately: this file is a shipped hook entry point, and pulling
+// in a bin/lib/ module here would widen its resolve closure for one call site.
+import { randomBytes } from 'node:crypto';
 import { createProcessManager } from './lib/process-manager.mjs';
 import { shouldDaemonAutoStart } from './lib/daemon-config.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
@@ -240,7 +243,7 @@ async function main() {
       case 'pre-task': {
         const description = getArg('description') || process.env.TOOL_INPUT_prompt;
         if (description) {
-          const taskId = `task-${Date.now()}`;
+          const taskId = `task-${Date.now()}-${randomBytes(6).toString('hex')}`;
           await runClaudeFlow('hooks', ['pre-task', '--task-id', taskId, '--description', description]);
         }
         break;

package/bin/lib/retired-files.mjs

@@ -123,6 +123,8 @@ export function loadRetiredManifest(manifestPath) {
 /**
  * Decide what to do with a consumer-side path against a retirement entry:
  *
+ *   - 'shipped'    — the installed package STILL ships this path, so the
+ *                    manifest entry contradicts the package; skip it entirely
  *   - 'absent'     — path doesn't exist on disk; nothing to do
  *   - 'prune'      — file exists and content hash matches a known-shipped
  *                    value; safe to delete (consumer didn't customize)
@@ -131,13 +133,34 @@ export function loadRetiredManifest(manifestPath) {
  *   - 'unknown'    — file exists but its hash couldn't be read (transient
  *                    error); leave alone, retry next session
  *
+ * The `shipped` check exists because a path can be retired and later RESTORED
+ * under the same name (#1414). The stale entry then holds only pre-deletion
+ * hashes, so the consumer's copy — which moflo itself just synced from the
+ * package — matches nothing and is reported as a customized retired file every
+ * session. Asking the package what it ships is the only source that cannot
+ * drift from the manifest, so it wins.
+ *
+ * `packageRoot` is optional and defaults to no cross-check: callers that don't
+ * know where the package lives keep exactly the pre-#1414 semantics.
+ *
+ * Order matters. The consumer-path check runs FIRST because most entries are
+ * `absent` on a typical install (already pruned, or never had the file), and
+ * those need no package stat at all — this runs on every consumer's session
+ * start, where a doubled stat count is 10-40ms on Windows with a scanner or a
+ * network `node_modules`. Entries that are absent locally are also exactly the
+ * ones a contradiction cannot hurt: there is nothing to delete or report.
+ *
  * @param {string} projectRoot
  * @param {{path:string, knownContentHashes:string[]}} entry
- * @returns {{ action: 'absent'|'prune'|'preserve'|'unknown', actualHash: string|null }}
+ * @param {string|null} [packageRoot] - root of the installed moflo package
+ * @returns {{ action: 'shipped'|'absent'|'prune'|'preserve'|'unknown', actualHash: string|null }}
  */
-export function classifyRetiredFile(projectRoot, entry) {
+export function classifyRetiredFile(projectRoot, entry, packageRoot = null) {
   const abs = resolve(projectRoot, entry.path);
   if (!existsSync(abs)) return { action: 'absent', actualHash: null };
+  if (packageRoot && existsSync(resolve(packageRoot, entry.path))) {
+    return { action: 'shipped', actualHash: null };
+  }
   const actualHash = fileSha256(abs);
   if (!actualHash) return { action: 'unknown', actualHash: null };
   if (entry.knownContentHashes.includes(actualHash)) {
@@ -167,15 +190,24 @@ export function classifyRetiredFile(projectRoot, entry) {
  * `preservedDetails` carries the same set with the manifest's retirement
  * provenance attached, for the machine-readable record (#1307 finding 3).
  *
+ * `shipped` collects entries the installed package still ships (#1414). They
+ * are neither pruned nor preserved — the manifest is simply wrong about them,
+ * and reporting them as retained is what produced the false banner. Nothing
+ * reads it today; it is here so the return value is a complete accounting of
+ * every entry's disposition rather than silently dropping one class, and so
+ * tests can assert the skip happened instead of inferring it from an absence.
+ *
  * @param {string} projectRoot
  * @param {string} manifestPath
- * @returns {{ pruned: string[], preserved: string[], preservedDetails: Array<{path:string, retiredIn?:string, retiredBy?:string}>, unknown: string[], failed: Array<{path:string, message:string}> }}
+ * @param {string|null} [packageRoot] - root of the installed moflo package
+ * @returns {{ pruned: string[], preserved: string[], preservedDetails: Array<{path:string, retiredIn?:string, retiredBy?:string}>, shipped: string[], unknown: string[], failed: Array<{path:string, message:string}> }}
  */
-export function applyRetiredPrune(projectRoot, manifestPath) {
+export function applyRetiredPrune(projectRoot, manifestPath, packageRoot = null) {
   const { entries } = loadRetiredManifest(manifestPath);
-  const report = { pruned: [], preserved: [], preservedDetails: [], unknown: [], failed: [] };
+  const report = { pruned: [], preserved: [], preservedDetails: [], shipped: [], unknown: [], failed: [] };
   for (const entry of entries) {
-    const { action } = classifyRetiredFile(projectRoot, entry);
+    const { action } = classifyRetiredFile(projectRoot, entry, packageRoot);
+    if (action === 'shipped') { report.shipped.push(entry.path); continue; }
     if (action === 'absent') continue;
     if (action === 'preserve') {
       report.preserved.push(entry.path);

package/bin/lib/shipped-scripts.json

@@ -22,7 +22,8 @@
     "gate-hook.mjs",
     "prompt-hook.mjs",
     "hook-handler.cjs",
-    "simplify-classify.cjs"
+    "simplify-classify.cjs",
+    "pr-create-command.cjs"
   ],
   "sourceHelperFiles": [
     "auto-memory-hook.mjs",

package/bin/lib/skill-categories.mjs

@@ -74,6 +74,13 @@ export const SKILL_CATEGORY_NAMES = Object.keys(SKILL_CATEGORIES_MAP);
  */
 export const ALWAYS_INSTALLED_SKILLS = ['flo', 'fl'];
 
+/**
+ * How far `parseSkillCategories` will look ahead for the `]` closing a
+ * flow-style `categories: [...]` list. Bounded so an unterminated bracket costs
+ * a fixed amount of work rather than a scan to end-of-file per candidate line.
+ */
+const FLOW_LOOKAHEAD_LINES = 50;
+
 /**
  * Extract the selected skill categories from raw `moflo.yaml` text.
  *
@@ -89,6 +96,14 @@ export const ALWAYS_INSTALLED_SKILLS = ['flo', 'fl'];
  *         - core
  *         - memory
  *
+ * Scanned line by line rather than with one multi-line regex. The regex form
+ * spanned the gap between `skills:` and `categories:` with
+ * `(?:[ \t]+[^\r\n]*\r?\n)*?`, whose `[ \t]+` and `[^\r\n]*` overlap — every
+ * indented line could be split many ways, so a `skills:` block with no
+ * `categories:` key backtracked exponentially and hung the launcher at session
+ * start on the consumer's own `moflo.yaml` (#1418). Line scanning is linear and
+ * matches the same inputs.
+ *
  * @param {string} yamlContent
  * @returns {string[]|null} selected categories, or null when unconfigured
  *   (meaning "no restriction" — sync everything).
@@ -102,29 +117,78 @@ export const ALWAYS_INSTALLED_SKILLS = ['flo', 'fl'];
 export function parseSkillCategories(yamlContent) {
   if (typeof yamlContent !== 'string' || yamlContent.length === 0) return null;
 
-  // Flow style: categories: [a, b]
-  const flow = yamlContent.match(/^[ \t]*skills:[ \t]*\r?\n(?:[ \t]+[^\r\n]*\r?\n)*?[ \t]+categories:[ \t]*\[([^\]]*)\]/m);
-  if (flow) {
-    return flow[1]
-      .split(',')
-      .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
-      .filter((s) => s.length > 0);
-  }
+  const lines = yamlContent.split(/\r?\n/);
 
-  // Block style: categories:\n  - a\n  - b
-  const block = yamlContent.match(/^[ \t]*skills:[ \t]*\r?\n(?:[ \t]+[^\r\n]*\r?\n)*?[ \t]+categories:[ \t]*\r?\n((?:[ \t]*-[ \t]*[^\r\n]+\r?\n?)+)/m);
-  if (block) {
-    return block[1]
-      .split(/\r?\n/)
-      .map((line) => line.match(/^[ \t]*-[ \t]*(.+?)[ \t]*$/))
-      .filter(Boolean)
-      .map((m) => m[1].replace(/^['"]|['"]$/g, '').trim())
-      .filter((s) => s.length > 0);
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^[ \t]*skills:[ \t]*$/.test(lines[i])) continue;
+
+    // Walk the indented block under `skills:`. A dedent (or a blank line) ends
+    // it, exactly as the old `[ \t]+`-per-line repetition required.
+    for (let j = i + 1; j < lines.length; j++) {
+      const line = lines[j];
+      if (!/^[ \t]/.test(line)) break;
+
+      // Flow style: categories: [a, b], possibly wrapped across lines — the old
+      // regex accepted that because its `[^\]]*` spanned newlines, so dropping
+      // it would be a silent behaviour regression.
+      //
+      // Lookahead is bounded and accumulates FORWARD rather than re-slicing the
+      // remainder of the file. `lines.slice(j).join('\n')` on every candidate
+      // line is O(n^2) on a file with many unterminated `categories: [` lines —
+      // a smaller version of exactly the attacker-controlled-YAML blowup this
+      // rewrite exists to close. A real flow list is one or two lines; 50 is
+      // already far past any legitimate input.
+      if (/^[ \t]+categories:[ \t]*\[/.test(line)) {
+        let buffer = line;
+        for (let k = j + 1; k < lines.length && k <= j + FLOW_LOOKAHEAD_LINES; k++) {
+          if (buffer.includes(']')) break;
+          buffer += '\n' + lines[k];
+        }
+        const flow = buffer.match(/^[ \t]+categories:[ \t]*\[([^\]]*)\]/);
+        if (flow) {
+          return flow[1]
+            .split(',')
+            .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+            .filter((s) => s.length > 0);
+        }
+      }
+
+      // Block style: categories:\n  - a\n  - b
+      if (/^[ \t]+categories:[ \t]*$/.test(line)) return parseBlockItems(lines, j + 1);
+    }
   }
 
   return null;
 }
 
+/**
+ * Collect `- item` lines following a bare `categories:` key.
+ *
+ * Returns `null` when there is not a single dash item, mirroring the old block
+ * regex's `+` quantifier failing to match: a `categories:` key with nothing
+ * under it is unconfigured ("sync everything"), NOT an empty selection ("sync
+ * nothing"). Conflating those would strip every skill from a consumer who left
+ * the key dangling (Rule #2).
+ *
+ * @param {string[]} lines
+ * @param {number} start - index of the first candidate item line
+ * @returns {string[]|null}
+ */
+function parseBlockItems(lines, start) {
+  const items = [];
+  let sawItem = false;
+
+  for (let k = start; k < lines.length; k++) {
+    const item = lines[k].match(/^[ \t]*-[ \t]*(.+?)[ \t]*$/);
+    if (!item) break;
+    sawItem = true;
+    const value = item[1].replace(/^['"]|['"]$/g, '').trim();
+    if (value.length > 0) items.push(value);
+  }
+
+  return sawItem ? items : null;
+}
+
 /**
  * Resolve the set of top-level skill directory names the launcher must NOT
  * sync, given a selection.