moflo 4.9.19 → 4.9.21

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)