moflo 4.9.20 → 4.9.22

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

@@ -6,7 +6,7 @@ arguments: "[-a] <topic-or-path>"
 
 # /guidance — Author and audit project guidance
 
-Help the user write, edit, or audit guidance files in their `.claude/guidance/` directory so Claude actually follows the rules they wrote. The skill applies the universal rules from `.claude/guidance/shipped/moflo-guidance-rules.md` — that doc is the single source of truth, do not paraphrase or duplicate it here.
+Help the user write, edit, or audit guidance files in their `.claude/guidance/` directory so Claude actually follows the rules they wrote. The skill applies the universal rules from `.claude/guidance/moflo-guidance-rules.md` — that doc is the single source of truth, do not paraphrase or duplicate it here.
 
 **Arguments:** $ARGUMENTS
 
@@ -43,7 +43,7 @@ If single-doc and the file already exists, briefly summarize what it contains (o
 
 ## Step 2 — Single-Doc Mode
 
-Apply the universal rules from `.claude/guidance/shipped/moflo-guidance-rules.md`. The rules cover (do not paraphrase — read the source):
+Apply the universal rules from `.claude/guidance/moflo-guidance-rules.md`. The rules cover (do not paraphrase — read the source):
 
 1. Lead with `**Purpose:**` line after the H1
 2. Be imperative, not descriptive
@@ -107,7 +107,15 @@ Audit mode runs **two passes**, then merges them into one triage report. Both pa
 
 Scan the guidance directory and score each `.md` against the universal rules. Walk the directory yourself with `Glob` and `Read`; do not delegate to a subagent for the audit itself unless the user has 30+ files.
 
-For each `.md` file:
+**Skip moflo-managed synced files first.** Read the first ~5 lines of every candidate file and check for an auto-generated marker matching `<!-- AUTO-GENERATED by (moflo|flo-setup)`. Files with that marker are mirrored from `node_modules/moflo/.claude/guidance/shipped/` on every session start — any audit-driven edit gets silently clobbered next session, so they MUST NOT enter the per-file scoring or appear in the fix triage.
+
+Aggregate skipped files into a single rollup line in the report (count only, not actionable). Format:
+
+```
+moflo-managed synced files: <N> skipped (auto-generated; rule violations belong upstream — file an issue against the moflo package)
+```
+
+Then for each remaining (user-authored) `.md` file:
 
 1. Count lines (`wc -l` via Bash, or read + split)
 2. Check for `**Purpose:**` line right after H1
@@ -170,7 +178,7 @@ Once the user confirms the doc looks right:
 
 ## Cheatsheet — Universal Rules Recap
 
-The full rules live in `.claude/guidance/shipped/moflo-guidance-rules.md`. Quick recap:
+The full rules live in `.claude/guidance/moflo-guidance-rules.md`. Quick recap:
 
 | # | Rule | One-line |
 |---|------|----------|
@@ -187,14 +195,14 @@ The full rules live in `.claude/guidance/shipped/moflo-guidance-rules.md`. Quick
 ## Important
 
 - **Memory-first is mandatory.** Always run `mcp__moflo__memory_search` in step 0 — the gate blocks reads otherwise.
-- **Never duplicate the rules in this skill.** Reference `.claude/guidance/shipped/moflo-guidance-rules.md` and ask the user to read it if they want depth.
+- **Never duplicate the rules in this skill.** Reference `.claude/guidance/moflo-guidance-rules.md` and ask the user to read it if they want depth.
 - **Never auto-write opinionated content.** Guidance is the user's project policy; ask before injecting your own opinions.
 - **Confirm per file in audit mode.** Bulk edits to the user's guidance directory are high-blast-radius — confirm each one.
 - **The `moflo-` filename prefix is moflo-only.** Consumer projects writing their own guidance do not need it; it exists to avoid collisions when moflo's shipped guidance syncs into a consumer's directory.
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-guidance-rules.md` — Universal writing rules this skill enforces
-- `.claude/guidance/shipped/moflo-memory-strategy.md` — How well-written guidance feeds the RAG index
-- `.claude/guidance/shipped/moflo-task-icons.md` — UX rule the skill checks for any TaskCreate examples in the user's guidance
-- `.claude/guidance/shipped/moflo-user-facing-language.md` — Companion rule for any user-visible text the user's guidance discusses
+- `.claude/guidance/moflo-guidance-rules.md` — Universal writing rules this skill enforces
+- `.claude/guidance/moflo-memory-strategy.md` — How well-written guidance feeds the RAG index
+- `.claude/guidance/moflo-task-icons.md` — UX rule the skill checks for any TaskCreate examples in the user's guidance
+- `.claude/guidance/moflo-user-facing-language.md` — Companion rule for any user-visible text the user's guidance discusses

package/.claude/skills/memory-patterns/SKILL.md

@@ -133,4 +133,4 @@ This is the same fan-out the `/flo` spell does — cheap (HNSW, parallel) and re
 
 - `vector-search` skill — RAG patterns over your own documents
 - `memory-optimization` skill — HNSW tuning, quantization, batch ops
-- `.claude/guidance/shipped/moflo-core-guidance.md` — CLI/MCP reference
+- `.claude/guidance/moflo-core-guidance.md` — CLI/MCP reference

package/.claude/skills/publish/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: publish
 description: Bump version, build, test, publish to npm, and install locally
-arguments: "[patch|minor|major] [-rc]"
+arguments: "<patch|minor|major> <-rc> <--check|-ch>"
 ---
 
 # /publish - Version Bump, Build, Test & Publish
@@ -13,30 +13,33 @@ Automated release pipeline for moflo. Bumps version, commits, builds, tests, run
 ## Usage
 
 ```
-/publish              # patch bump (4.8.56 → 4.8.57)
+/publish              # patch bump, default mode (skips CI-covered gates)
 /publish minor        # minor bump (4.8.56 → 4.9.0)
 /publish major        # major bump (4.8.56 → 5.0.0)
-/publish -rc          # patch RC bump (4.8.56 → 4.8.57-rc.1, or 4.8.57-rc.1 → 4.8.57-rc.2)
+/publish -rc          # patch RC bump (4.8.56 → 4.8.57-rc.1)
 /publish minor -rc    # minor RC bump (4.8.56 → 4.9.0-rc.1)
-/publish patch        # explicit patch bump
+/publish --check      # full pre-flight (lint + test + smoke + everything)
+/publish -ch          # short form of --check
+/publish minor -ch    # combine: full pre-flight on a minor bump
 ```
 
-## Pre-Publish Gate — REQUIRED
+## --check / -ch flag (presence-only)
 
-**Before Step 1, walk the full pre-flight checklist in `.claude/guidance/internal/pre-publish-rules.md`.** That document is the authoritative ruleset for every publish — the seven layered gates (lint, build, tests, doctor, smoke, populated smoke, manifest sanity) plus the cross-platform and consumer-install posture checks. Do not paraphrase or shortcut the rules here; read them and confirm every item.
+**Default (flag absent):** runs build + doctor + trigger-based manual checks only. Skips lint/test/smoke because those gates are covered by CI on every PR + push to main (`ci.yml`, `consumer-install-smoke.yml`).
 
-If you cannot confirm all ten checklist items at the bottom of `pre-publish-rules.md`, STOP. Fix the failing gate first and only then resume from Step 1 below. Skipping the gate to "just get this small change out" is the antipattern that produced the historical incidents named in the rules doc.
+**With `--check` or `-ch` (any presence):** runs the full pre-flight from `pre-publish-rules.md` — lint, build, test, doctor (strict), clean smoke, populated smoke, and a forced full walk of every manual gate. Use this for publishes that didn't go through a green PR, risky releases, or when you want belt-and-suspenders.
+
+The flag is presence-only. `--check` and `-ch` both set it to true. There is no `--check=true` / `--check=false` syntax — absence means false.
 
 ---
 
 ## Step-by-Step Procedure
 
-Follow docs/BUILD.md exactly. Every step must succeed before proceeding to the next.
-
-### Step 1: Parse Arguments
+### Step 0: Parse Arguments
 
 - Default bump type is `patch` if not specified
-- If `-rc` flag is present, produce a release candidate version
+- `-rc` flag: produce a release candidate
+- `--check` or `-ch` (presence): set `CHECK_MODE=true`. Otherwise `CHECK_MODE=false`.
 - Determine the new version string:
   - **Without `-rc`:** Use `npm version <patch|minor|major> --no-git-tag-version`
   - **With `-rc`:** Calculate manually:
@@ -44,33 +47,96 @@ Follow docs/BUILD.md exactly. Every step must succeed before proceeding to the n
     - Otherwise, bump the base version and append `-rc.1` (e.g., `4.8.56` → `4.8.57-rc.1`)
     - Write with: `npm version <new-version> --no-git-tag-version`
 
-### Step 2: Rebuild After Version Bump
+### Step 1: Compute Manual-Check Fingerprint (always)
+
+```bash
+bash .claude/skills/publish/fingerprint.sh
+```
+
+The script diffs `HEAD` against the most recent `chore: install moflo@*` commit and pattern-matches the file list against the manual-gate triggers from `pre-publish-rules.md`. Output is one block:
+
+```
+Triggered manual checks: bin-scriptfiles-sync info-loss-audit
+Diff range: <last-publish-sha>..HEAD
+Changed files: 7
+```
+
+`Triggered manual checks: none` means gates 1/2/6 don't apply to this diff — skip them entirely.
+
+This step costs ~50 tokens and is the cornerstone of token-efficient default mode.
+
+### Step 2: Build (always)
 
 ```bash
 npm run build
 ```
 
-This syncs the version to `src/cli/version.ts` via the `version` lifecycle script, then compiles all TypeScript.
+Always runs regardless of `CHECK_MODE`. Syncs the version to `src/cli/version.ts` via the `version` lifecycle script, then compiles all TypeScript. Confirms the deliverables on disk are correct.
 
 **Must exit 0.** If it fails, stop and fix the build error.
 
-### Step 3: Run Tests
+### Step 3: Lint (only if `CHECK_MODE=true`)
+
+```bash
+npm run lint
+```
+
+Skipped by default — `ci.yml` runs lint on every PR with `max-warnings 0`. Run when `--check` is set.
+
+### Step 4: Tests (only if `CHECK_MODE=true`)
 
 ```bash
 npm test
 ```
 
+Skipped by default — `ci.yml` runs the full test suite on every PR. Run when `--check` is set.
+
 **Must have 0 test file failures.** If any test files fail, retest them individually to distinguish real failures from flaky ones (per broken window theory). Fix all real failures before proceeding.
 
-### Step 4: Run Doctor
+### Step 5: Doctor (always)
 
+Default mode:
 ```bash
 npx moflo doctor --fix
 ```
 
-All checks must pass (warnings are acceptable on Windows for sandbox tier). If doctor finds fixable issues, it will auto-fix them. If manual fixes are needed, stop and address them.
+Check mode (`CHECK_MODE=true`):
+```bash
+npx moflo doctor --strict
+```
+
+Doctor is the only check with no CI equivalent — it inspects local state (daemon lock, embeddings hygiene, sandbox tier, vector-stats freshness) that CI cannot validate for you. Always runs.
+
+### Step 6: Smoke Tests (only if `CHECK_MODE=true`)
+
+```bash
+npm run test:smoke
+npm run test:smoke:populated
+```
+
+Skipped by default — `consumer-install-smoke.yml` runs both profiles on Ubuntu/macOS/Windows on every PR + push to main. Run when `--check` is set.
+
+### Step 7: Manual Gate Walk (trigger-based, even in default mode)
+
+Read the fingerprint output from Step 1.
 
-### Step 5: Commit & Push
+| Trigger | Manual check (gate) | What to walk |
+|---------|---------------------|--------------|
+| `split-newlines` | Gate 7 | Diff the changed file-reading code; verify any newline split uses `/\r?\n/` not `'\n'` |
+| `homedir-tmpdir` | Gate 7 | Verify env-var literals use `os.homedir()` / `os.tmpdir()`, not raw `process.env.HOME` / `/tmp` |
+| `bwrap-permissions` | Gate 7 | Spell bash steps that need network declare `permissionLevel: elevated` |
+| `posix-only-spell-bash` | Gate 7 | Spell bash steps avoid `mkdir`/`rm`/`cp`; use `node -e` with `fs`/`os` for cross-platform file ops |
+| `bin-scriptfiles-sync` | Gate 8 | New `bin/` script appears in all three `scriptFiles` arrays (`session-start-launcher.mjs`, `init/moflo-init.ts`, third sync site) |
+| `helper-static-files` | Gate 8 | New helpers ship as static `bin/` files, not generated at runtime |
+| `shipped-guidance-prefix` | Gate 8 | New shipped guidance has `moflo-` prefix and lives in `.claude/guidance/shipped/` |
+| `files-glob-coverage` | Gate 9 | Run `npm pack --dry-run` and confirm new shipped files appear in the tarball listing |
+| `info-loss-audit` | Gate 10 | For each deleted/renamed file, audit destinations bullet-by-bullet — every piece of removed content has a home |
+
+If `CHECK_MODE=true`, walk **all** manual gates regardless of triggers (full audit). If `CHECK_MODE=false`, walk **only triggered** ones.
+
+If the trigger set is `none` AND `CHECK_MODE=false`: skip Step 7 entirely.
+
+### Step 8: Commit & Push
 
 Commit the version bump files:
 
@@ -82,15 +148,13 @@ git push origin main
 
 Only commit version-related files. Do not stage unrelated changes.
 
-### Step 6: Verify npm Authentication
-
-Before publishing, verify npm auth is valid:
+### Step 9: Verify npm Authentication
 
 ```bash
 npm whoami
 ```
 
-If this returns a 401 or "not logged in" error, the auth token in `~/.npmrc` is missing or expired. Ask the user to provide a valid npm publish token.
+If 401 or "not logged in": auth token in `~/.npmrc` is missing or expired. Ask the user for a valid npm publish token.
 
 **How to create a token** (provide these instructions to the user if needed):
 1. Go to https://www.npmjs.com/settings/~/tokens
@@ -104,9 +168,9 @@ Once the user provides the token, write it to `~/.npmrc`:
 echo "//registry.npmjs.org/:_authToken=<token>" > ~/.npmrc
 ```
 
-Then verify with `npm whoami` before proceeding.
+Verify with `npm whoami` before proceeding.
 
-### Step 7: Publish to npm
+### Step 10: Publish to npm
 
 ```bash
 npm publish --tag <tag>
@@ -120,7 +184,7 @@ npm publish --tag <tag>
 - Then retry with: `npm publish --otp=<code> --tag <tag>`
 - Tip: Granular access tokens created on npmjs.com do NOT require OTP — prefer those over legacy tokens
 
-### Step 8: Verify Publication
+### Step 11: Verify Publication
 
 ```bash
 npm view moflo version
@@ -129,7 +193,7 @@ npm view moflo dist-tags
 
 Confirm the published version matches what we just built.
 
-### Step 9: Install Locally
+### Step 12: Install Locally
 
 ```bash
 npm install moflo@<new-version> --save-dev
@@ -137,7 +201,7 @@ npm install moflo@<new-version> --save-dev
 
 This updates `package.json` and `package-lock.json` to use the newly published version as a devDependency.
 
-### Step 10: Final Commit
+### Step 13: Final Commit
 
 If `package.json` or `package-lock.json` changed from the install:
 
@@ -147,6 +211,8 @@ git commit -m "chore: install moflo@<new-version>"
 git push origin main
 ```
 
+The `chore: install moflo@<version>` commit message is the anchor the fingerprint uses to bound future diffs — keep the prefix exact.
+
 ## Output
 
 Print a summary at the end:
@@ -154,13 +220,18 @@ Print a summary at the end:
 ```
 Publish Summary
 ───────────────
-Version:    <old> → <new>
-Tag:        latest | rc
-Build:      passed
-Tests:      <N> files passed, <N> tests passed
-Doctor:     <N> passed, <N> warnings
-Published:  moflo@<new-version>
-Installed:  moflo@<new-version> (devDependency)
+Mode:            default | --check
+Version:         <old> → <new>
+Tag:             latest | rc
+Build:           passed
+Tests:           skipped (CI-covered) | <N> files passed, <N> tests passed
+Lint:            skipped (CI-covered) | passed
+Doctor:          <N> passed, <N> warnings
+Smoke (clean):   skipped (CI-covered) | passed
+Smoke (popl):    skipped (CI-covered) | passed
+Triggered gates: <list> | none
+Published:       moflo@<new-version>
+Installed:       moflo@<new-version> (devDependency)
 ```
 
 ## Important
@@ -168,13 +239,27 @@ Installed:  moflo@<new-version> (devDependency)
 - All commands run from the project root — never cd into subdirectories
 - Never use `--force` on npm publish
 - Never install moflo globally — it is always a local devDependency
-- If any step fails, stop and fix the issue before proceeding — do not skip steps
-- The `prepublishOnly` script in package.json runs `npm run build` automatically, so npm publish will fail-fast on any TypeScript or asset-bundling error
+- If any step that DID run fails, stop and fix the issue before proceeding — do not skip steps
+- The `prepublishOnly` script in package.json runs `npm run build` automatically, so npm publish will fail-fast on any TypeScript or asset-bundling error even if Step 2 had been skipped (it isn't — Step 2 always runs)
 - Pre-publish rules live in `.claude/guidance/internal/pre-publish-rules.md` — never duplicate or paraphrase them in this skill; reference and follow
 
+## When to use `--check`
+
+Use `--check` / `-ch` when:
+
+- The PR didn't go through CI (e.g., publishing from a local-only branch)
+- You're publishing a risky change (broad refactor, infrastructure surface, packaging changes)
+- CI was red on something orthogonal you waived, and you want belt-and-suspenders locally
+- You explicitly want to re-walk gates 7/8/10 manually regardless of trigger output
+
+For the common case — publishing right after a merged green PR — the default mode is correct and meaningfully cheaper in tokens and time.
+
 ## See Also
 
-- `.claude/guidance/internal/pre-publish-rules.md` — Mandatory cross-platform + consumer-install gates that gate every publish
+- `.claude/skills/publish/fingerprint.sh` — Trigger-fingerprint script invoked by Step 1
+- `.claude/guidance/internal/pre-publish-rules.md` — Authoritative gate ruleset (gates 1–10) and trigger map
 - `docs/BUILD.md` — Step-by-step build/publish process this skill mirrors
 - `.claude/guidance/internal/dogfooding.md` — Why we catch consumer-facing regressions first as our own dependency
 - `harness/consumer-smoke/README.md` — Smoke harness profiles (clean + populated) that prove a consumer install works
+- `.github/workflows/ci.yml` — Lint/build/test gates this skill skips by default
+- `.github/workflows/consumer-install-smoke.yml` — Smoke gates this skill skips by default

package/.claude/skills/reset-epic/SKILL.md

@@ -13,14 +13,14 @@ Fully resets an epic so it can be re-tested from scratch.
 ## Usage
 
 ```
-/reset-epic 287       # Reset epic #287 for retesting
+/reset-epic <epic-number>     # e.g. /reset-epic 287, to reset that epic for retesting
 ```
 
 ## What It Does
 
 Given an epic issue number, perform ALL of the following:
 
-1. **Identify stories**: Parse the epic body for linked issue numbers (e.g., `#284`, `#285`, `#286`)
+1. **Identify stories**: Parse the epic body for linked issue numbers
 2. **Close open PRs**: Find all open PRs referencing any story number or the epic number. Close them.
 3. **Delete remote branches**: Find and delete any remote branches related to the epic (e.g., `epic/<number>-*`, `feat/<story>-*`, `revert/epic-<number>-*`)
 4. **Delete local branches**: Delete any local branches matching the same patterns (skip the current branch)