@sparkleideas/claude-flow-patch 3.1.0-alpha.44.patch.10

package/AGENTS.md

@@ -0,0 +1,162 @@
+# @sparkleideas/claude-flow-patch
+
+> Runtime patches for `@claude-flow/cli` v3.1.0-alpha.41, `ruvector`, and `ruv-swarm` v1.0.20
+
+**Claude Code instructions are in [CLAUDE.md](CLAUDE.md). Project-specific instructions (defect index, workflows, policies) are in [README.md](README.md).**
+
+## Project Overview
+
+A Claude Flow powered project
+
+**Tech Stack**: Python (patches), Bash (orchestration)
+**Architecture**: Idempotent runtime patching via string replacement
+
+## Quick Start
+
+### Apply Patches
+```bash
+bash patch-all.sh
+```
+
+### Verify
+```bash
+bash check-patches.sh
+```
+
+## Agent Coordination
+
+### Swarm Configuration
+
+This project uses hierarchical swarm coordination for complex tasks:
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| Topology | `hierarchical` | Queen-led coordination (anti-drift) |
+| Max Agents | 8 | Optimal team size |
+| Strategy | `specialized` | Clear role boundaries |
+| Consensus | `raft` | Leader-based consistency |
+
+### When to Use Swarms
+
+**Invoke swarm for:**
+- Multi-file changes (3+ files)
+- New feature implementation
+- Cross-module refactoring
+- API changes with tests
+- Security-related changes
+- Performance optimization
+
+**Skip swarm for:**
+- Single file edits
+- Simple bug fixes (1-2 lines)
+- Documentation updates
+- Configuration changes
+
+### Available Skills
+
+Use `$skill-name` syntax to invoke:
+
+| Skill | Use Case |
+|-------|----------|
+| `$swarm-orchestration` | Multi-agent task coordination |
+| `$memory-management` | Pattern storage and retrieval |
+| `$sparc-methodology` | Structured development workflow |
+| `$security-audit` | Security scanning and CVE detection |
+
+### Agent Types
+
+| Type | Role | Use Case |
+|------|------|----------|
+| `researcher` | Requirements analysis | Understanding scope |
+| `architect` | System design | Planning structure |
+| `coder` | Implementation | Writing code |
+| `tester` | Test creation | Quality assurance |
+| `reviewer` | Code review | Security and quality |
+
+## Code Standards
+
+### File Organization
+- **NEVER** save to root folder
+- `/src` - Source code files
+- `/tests` - Test files
+- `/docs` - Documentation
+- `/config` - Configuration files
+
+### Quality Rules
+- Files under 500 lines
+- No hardcoded secrets
+- Input validation at boundaries
+- Typed interfaces for public APIs
+- TDD London School (mock-first) preferred
+
+### Commit Messages
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+Sparkling Ideas <henrik@sparklingideas.co.uk>
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
+
+## Security
+
+### Critical Rules
+- NEVER commit secrets, credentials, or .env files
+- NEVER hardcode API keys
+- Always validate user input
+- Use parameterized queries for SQL
+- Sanitize output to prevent XSS
+
+### Path Security
+- Validate all file paths
+- Prevent directory traversal (../)
+- Use absolute paths internally
+
+## Memory System
+
+### Storing Patterns
+```bash
+npx @claude-flow/cli memory store \
+  --key "pattern-name" \
+  --value "pattern description" \
+  --namespace patterns
+```
+
+### Searching Memory
+```bash
+npx @claude-flow/cli memory search \
+  --query "search terms" \
+  --namespace patterns
+```
+
+## Links
+
+- Documentation: https://github.com/ruvnet/claude-flow
+- Issues: https://github.com/ruvnet/claude-flow/issues
+
+## Guidance Lifecycle Wiring (Codex)
+
+Codex does not expose Claude Code-style event-command hook maps in `config.toml`.
+This project uses an explicit bridge script:
+
+- `scripts/guidance-codex-bridge.js` -> dispatches lifecycle events to:
+  - `.claude/helpers/hook-handler.cjs` (enforcement path)
+  - optional `npx @claude-flow/cli@latest hooks ...` telemetry calls
+
+Primary commands:
+
+```bash
+npm run guidance:codex:session-start
+npm run guidance:codex:pre-task -- --description "Implement feature X"
+npm run guidance:codex:pre-command -- --command "git status"
+npm run guidance:codex:pre-edit -- --file src/example.ts
+npm run guidance:codex:post-edit -- --file src/example.ts
+npm run guidance:codex:post-task -- --task-id task-123 --status completed
+npm run guidance:codex:session-end
+```
+
+Control flags:
+- `--skip-cf-hooks` skips secondary `@claude-flow/cli` hook invocations
+- `GUIDANCE_CODEX_SKIP_CF_HOOKS=1` disables secondary invocations globally

package/CLAUDE.md

@@ -0,0 +1,506 @@
+# @sparkleideas/claude-flow-patch
+
+Runtime patches for `@claude-flow/cli` **v3.1.0-alpha.41**, `ruvector`, and `ruv-swarm` **v1.0.20**.
+
+## Terminology
+
+| Term | Meaning | Example |
+|------|---------|---------|
+| **Defect** | A tracked problem (bug or missing feature). Each defect has its own directory under `patch/` with a README.md and fix.py. | "Defect HW-001", "29 defects across 13 categories" |
+| **Patch** | The code change that addresses a defect. Implemented as `fix.py` (or `fix.sh`) using `patch()`/`patch_all()` calls. We patch because we can't fix upstream. | "fix.py contains 3 patch ops" |
+| **GitHub issue** | The upstream issue on github.com/ruvnet/claude-flow. Always say "GitHub issue", never just "issue". | "GitHub issue #1111" |
+| **Defect ID** | The unique identifier for a defect: `{PREFIX}-{NNN}`. | HW-001, NS-003, RS-001 |
+| **Execution order number** | 3-digit numeric prefix on the directory name that controls patch application order. Spaced by 10 to allow insertions. | `010-`, `170-`, `270-` |
+
+- Use **defect** for the tracked problem (the folder, the ID, the concept).
+- Use **patch** for the code change applied to the library (`fix.py`, `patch()`, `patch-all.sh`).
+- Always say **GitHub issue** for the upstream reference -- never bare "issue".
+
+## Rules
+
+- NEVER modify files inside the npm/npx cache directly -- edit `fix.py` scripts in `patch/`
+- NEVER run individual `fix.py` files standalone -- always use `bash patch-all.sh`
+- NEVER delete a defect without confirming it is truly obsolete -- see "Removing a Defect" below
+- NEVER reuse a defect ID that was previously assigned to a different GitHub issue
+- ONE defect directory and ONE fix.py per GitHub issue -- do not combine multiple GitHub issues into one defect or split one GitHub issue across multiple defects
+- ALWAYS verify with `bash check-patches.sh` after applying
+- ALWAYS run `npm run preflight` before staging — the pre-commit hook (`hooks/pre-commit`) enforces this via `--check` mode
+- ALWAYS update ALL listing files when adding/removing a defect (see checklist)
+- Execution order is determined by the numeric prefix on each defect directory name. Dependencies between defects are expressed by assigning lower numbers to prerequisites.
+
+## Project Structure
+
+```
+patch-all.sh            # Orchestrator -- globs patch/*/fix.py (no hardcoded list)
+check-patches.sh        # Sentinel -- reads patch/*/sentinel files dynamically
+repair-post-init.sh     # Post-init helper repair for existing projects
+lib/
+  common.py             # Shared helpers: patch(), patch_all(), path variables
+  discover.mjs          # Dynamic discovery: scans patch/*/ → structured JSON
+  categories.json       # Prefix-to-label mapping (one line per category)
+scripts/
+  preflight.mjs         # Pre-commit sync: doc tables, versions, config (npm run preflight)
+  upstream-log.mjs      # Show recent upstream releases (npm run upstream-log [count])
+patch/
+  {NNN}-{PREFIX}-{NNN}-{slug}/    # NNN = 3-digit execution order
+    README.md           # Defect report: title, severity, root cause, fix
+    fix.py              # patch()/patch_all() calls
+    sentinel            # Verification directives for check-patches.sh
+```
+
+## Target Packages
+
+| Package | Version | Location | Env var |
+|---------|---------|----------|---------|
+| `@claude-flow/cli` | `3.1.0-alpha.41` | `~/.npm/_npx/*/node_modules/@claude-flow/cli/dist/src/` | `BASE` |
+| `ruvector` | (bundled) | `~/.npm/_npx/*/node_modules/ruvector/bin/cli.js` | `RUVECTOR_CLI` |
+| `ruv-swarm` | `1.0.20` | `~/.npm/_npx/*/node_modules/ruv-swarm/` | (found via glob) |
+
+`BASE` is set by `patch-all.sh`. All path variables in `lib/common.py` derive from it.
+`RUVECTOR_CLI` is set by `patch-all.sh` to the ruvector CLI entry point.
+RS-001 locates its own target via `find`.
+
+## GitHub Issue Policy
+
+Every defect MUST link to exactly one GitHub issue. No exceptions. One defect = one GitHub issue.
+
+### Where the fix description goes
+
+The `## Fix` section MUST always be present. Where it lives depends on who created the GitHub issue:
+
+| Who created the issue? | Where does `## Fix` go? |
+|------------------------|------------------------|
+| **sparkling** (us) | In the **issue body** — edit the issue to include `## Fix` |
+| **Someone else** | In a **single comment** on the issue — do NOT edit their body |
+
+This rule is absolute. Every linked GitHub issue must have a `## Fix` section visible — either in the body (if we created it) or in exactly one comment (if someone else created it).
+
+### Before creating a new defect, always search first:
+
+```bash
+gh issue list --repo ruvnet/claude-flow --search "<keywords>" --limit 10
+```
+
+### If an open GitHub issue exists (created by someone else):
+
+Post a single comment with the patch details. Do NOT edit the issue body. Do NOT post multiple comments, closing remarks, or history. One clean comment per defect:
+
+```bash
+gh issue comment <NUMBER> --repo ruvnet/claude-flow --body "$(cat <<'EOF'
+## Fix
+
+Defect **{PREFIX}-{NNN}** in [claude-flow-patch](https://github.com/sparkling/claude-flow-patch).
+
+**Root cause:** <1-2 sentences explaining why the bug occurs at the code level>
+
+<What the patch does. Be specific. Include a table if multiple ops.>
+
+**Affected versions:** `@claude-flow/cli` 3.1.0-alpha.44 through current
+
+**Related issues:** #NNN, #NNN
+EOF
+)"
+```
+
+### If no GitHub issue exists (we create it):
+
+The `## Fix` section goes directly in the issue body. This is mandatory — sparkling-created issues MUST contain the fix in the body, not in a follow-up comment.
+
+```bash
+gh issue create --repo ruvnet/claude-flow \
+  --title "Bug: <short description>" \
+  --body "$(cat <<'EOF'
+## Summary
+<1-2 sentences>
+
+## Root Cause
+<what's wrong and why>
+
+## Fix
+<what the patch does — be specific, include a table if multiple ops>
+
+## Files Affected
+- <dist/src/path/to/file.js>
+
+## Affected Versions
+`@claude-flow/cli` 3.1.0-alpha.44 through current
+
+## Related Issues
+- #NNN — <short description of relationship>
+EOF
+)"
+```
+
+Save the returned GitHub issue number for the defect README.md.
+
+### Comment hygiene:
+
+- One comment per defect, describing the patch. No meta-commentary.
+- Every comment/body MUST include affected versions and related issues (use "None" if truly standalone).
+- If you need to replace a comment, delete the old one first (`gh api -X DELETE`).
+- Do not reference defect history, deletion/restoration, or internal decisions.
+
+## Defect Categories
+
+<!-- GENERATED:defect-tables:begin -->
+| Prefix | Category | Count |
+|--------|----------|-------|
+| CF | Config & Doctor | 2 |
+| DM | Daemon & Workers | 6 |
+| EM | Embeddings & HNSW | 2 |
+| GV | Ghost Vectors | 1 |
+| HK | Hooks | 5 |
+| HW | Headless Worker | 4 |
+| IN | Intelligence | 1 |
+| MM | Memory Management | 1 |
+| NS | Memory Namespace | 3 |
+| RS | ruv-swarm | 1 |
+| RV | RuVector Intelligence | 3 |
+| SG | Settings Generator | 4 |
+| UI | Display & Cosmetic | 2 |
+
+## All 35 Defects
+
+| ID | GitHub Issue | Severity |
+|----|-------------|----------|
+| CF-001 | [#1141 Doctor ignores YAML config files](https://github.com/ruvnet/claude-flow/issues/1141) | Low |
+| CF-002 | [#1142 Config export shows hardcoded defaults](https://github.com/ruvnet/claude-flow/issues/1142) | Medium |
+| DM-001 | [#1116 daemon.log always 0 bytes](https://github.com/ruvnet/claude-flow/issues/1116) | Medium |
+| DM-002 | [#1138 maxCpuLoad=2.0 blocks all workers on multi-core](https://github.com/ruvnet/claude-flow/issues/1138) | Critical |
+| DM-003 | [#1077 macOS freemem() always ~0% — workers blocked](https://github.com/ruvnet/claude-flow/issues/1077) | Critical |
+| DM-004 | [#1139 Preload worker stub + missing from defaults](https://github.com/ruvnet/claude-flow/issues/1139) | Enhancement |
+| DM-005 | [#1140 Consolidation worker stub (no decay/rebuild)](https://github.com/ruvnet/claude-flow/issues/1140) | Enhancement |
+| EM-001 | [#1143 Embedding system ignores project config (model + HNSW dims)](https://github.com/ruvnet/claude-flow/issues/1143) | High |
+| EM-002 | [#1144 @xenova/transformers cache EACCES](https://github.com/ruvnet/claude-flow/issues/1144) | Medium |
+| GV-001 | [#1122 HNSW ghost vectors persist after memory delete](https://github.com/ruvnet/claude-flow/issues/1122) | Medium |
+| HK-001 | [#1155 post-edit hook records file_path as "unknown"](https://github.com/ruvnet/claude-flow/issues/1155) | Medium |
+| HK-002 | [#1058 MCP hook handlers are stubs that don't persist data](https://github.com/ruvnet/claude-flow/issues/1058) | High |
+| HK-003 | [#1158 hooks_metrics MCP handler returns hardcoded fake data](https://github.com/ruvnet/claude-flow/issues/1158) | High |
+| HK-004 | [#1175 hooks_session-start ignores daemon.autoStart from settings.json](https://github.com/ruvnet/claude-flow/issues/1175) | High |
+| HK-005 | [#1171 Multiple MCP servers start independent in-process daemons](https://github.com/ruvnet/claude-flow/issues/1171) | Critical |
+| HW-001 | [#1111 Headless workers hang — stdin pipe never closed](https://github.com/ruvnet/claude-flow/issues/1111) | Critical |
+| HW-002 | [#1112 Headless failures silently swallowed as success](https://github.com/ruvnet/claude-flow/issues/1112) | High |
+| HW-003 | [#1113 Worker scheduling intervals too aggressive + settings ignored](https://github.com/ruvnet/claude-flow/issues/1113) | High |
+| IN-001 | [#1154 intelligence.cjs is a stub that doesn't actually learn](https://github.com/ruvnet/claude-flow/issues/1154) | Critical |
+| MM-001 | [#1152 Remove dead persistPath config option](https://github.com/ruvnet/claude-flow/issues/1152) | Low |
+| NS-001 | [#1123 Discovery ops default to wrong namespace](https://github.com/ruvnet/claude-flow/issues/1123) | Critical |
+| NS-002 | [#581 Store/delete/retrieve fall back to 'default' + accept 'all'](https://github.com/ruvnet/claude-flow/issues/581) | Critical |
+| NS-003 | [#1136 Namespace typo 'pattern' vs 'patterns'](https://github.com/ruvnet/claude-flow/issues/1136) | Medium |
+| RS-001 | [ruv-FANN#185 ruv-swarm MCP fails on Node 24 — better-sqlite3 missing native bindings](https://github.com/ruvnet/ruv-FANN/issues/185) | Critical |
+| RV-001 | [#1156 force-learn command calls intel.tick() which doesn't exist](https://github.com/ruvnet/claude-flow/issues/1156) | Medium |
+| RV-002 | [#1157 activeTrajectories not loaded from saved file](https://github.com/ruvnet/claude-flow/issues/1157) | High |
+| RV-003 | [ruv-FANN#186 trajectory-end does not update stats counters](https://github.com/ruvnet/ruv-FANN/issues/186) | Medium |
+| SG-001 | [#1150 Init generates invalid settings](https://github.com/ruvnet/claude-flow/issues/1150) | High |
+| SG-003 | [#1169 Init missing helpers for --dual, --minimal, hooks, and upgrade paths](https://github.com/ruvnet/claude-flow/issues/1169) | Critical |
+| UI-001 | [#1145 intelligence stats crashes on .toFixed()](https://github.com/ruvnet/claude-flow/issues/1145) | Critical |
+| UI-002 | [#1146 neural status shows "Not loaded"](https://github.com/ruvnet/claude-flow/issues/1146) | Low |
+| DM-006 | [#1114 No log rotation — logs grow unbounded](https://github.com/ruvnet/claude-flow/issues/1114) | Medium |
+| HW-004 | [#1117 runWithTimeout rejects but does not kill child process](https://github.com/ruvnet/claude-flow/issues/1117) | Medium |
+| SG-004 | [#1181 init wizard lacks parity with init](https://github.com/ruvnet/claude-flow/issues/1181) | High |
+| SG-005 | [#1177 add 'start all' subcommand to start everything at once](https://github.com/ruvnet/claude-flow/issues/1177) | Enhancement |
+<!-- GENERATED:defect-tables:end -->
+
+---
+
+## Creating a New Defect
+
+Follow every step. Do not skip any.
+
+### Step 1: Find or create a GitHub issue
+
+Search first:
+
+```bash
+gh issue list --repo ruvnet/claude-flow --search "<keywords>" --limit 10
+```
+
+- **GitHub issue exists and is open**: note the number, post a patch comment (see GitHub Issue Policy above).
+- **GitHub issue exists but is closed**: reopen it with a comment explaining why.
+- **No GitHub issue exists**: create one (see GitHub Issue Policy above). Save the returned `#number`.
+
+### Step 2: Choose a defect ID
+
+Format: `{PREFIX}-{NNN}`
+
+- `PREFIX`: 2-letter category code from the table above. Create a new prefix if no existing category fits.
+- `NNN`: next sequential number within that category (e.g. if HK-002 exists, next is HK-003).
+- NEVER reuse an ID previously assigned to a different GitHub issue, even if that defect was deleted.
+
+### Step 3: Create the defect directory
+
+```bash
+mkdir -p patch/{ORDER}-{PREFIX}-{NNN}-{slug}/
+```
+
+`ORDER`: 3-digit execution order number in 10-increments (e.g. `300`). Choose the next available number. If this defect depends on another, its number must be higher than the dependency's.
+
+`slug`: lowercase-kebab-case summary (e.g. `post-edit-file-path`).
+
+### Step 4: Write README.md
+
+Create `patch/{PREFIX}-{NNN}-{slug}/README.md`:
+
+```markdown
+# {PREFIX}-{NNN}: Short title
+
+**Severity**: Critical | High | Medium | Low | Enhancement
+**GitHub**: [#{number}](https://github.com/ruvnet/claude-flow/issues/{number})
+
+## Root Cause
+
+<What's wrong and why. Include code snippets showing the bug.>
+
+## Fix
+
+<What the patch does. Be specific about each change.>
+
+## Files Patched
+
+- <relative path from dist/src/ for each file>
+
+## Ops
+
+<N> ops in fix.py
+```
+
+### Step 5: Write fix.py and sentinel
+
+Create `patch/{PREFIX}-{NNN}-{slug}/fix.py` with patch calls:
+
+```python
+# {PREFIX}-{NNN}: Short title
+# GitHub: #{number}
+
+patch("{PREFIX}-{NNN}a: description of first change",
+    TARGET_VAR,        # Path variable from lib/common.py
+    """old string""",  # Exact string to find (copy-paste from target file)
+    """new string""")  # Replacement string
+```
+
+Create `patch/{PREFIX}-{NNN}-{slug}/sentinel` to declare how `check-patches.sh` verifies this patch:
+
+```
+grep "unique_string" path/to/target.js
+```
+
+**Sentinel directives** (one per line):
+
+```
+grep "unique_string" path/to/target.js     # String must be present
+absent "old_string" path/to/target.js       # String must be absent
+none                                         # No sentinel (e.g. permissions-only)
+package: ruvector                            # Gate on optional package
+```
+
+Paths are relative to `@claude-flow/cli/dist/src/` (e.g. `services/worker-daemon.js`, `init/executor.js`). For external packages, add `package: ruvector` or `package: ruv-swarm` and use paths relative to that package root.
+
+The sentinel pattern must:
+- Only appear in the target file AFTER the patch is applied
+- Be specific enough not to match unrelated code
+
+**Patch API**:
+- `patch(label, filepath, old, new)` -- replace first occurrence only
+- `patch_all(label, filepath, old, new)` -- replace ALL occurrences
+
+Both are idempotent: skip if `new` already present, warn if `old` not found.
+
+**Path variables** (defined in `lib/common.py`):
+
+| Variable | File | Package |
+|----------|------|---------|
+| `HWE` | `services/headless-worker-executor.js` | @claude-flow/cli |
+| `WD` | `services/worker-daemon.js` | @claude-flow/cli |
+| `DJ` | `commands/daemon.js` | @claude-flow/cli |
+| `DOC` | `commands/doctor.js` | @claude-flow/cli |
+| `MI` | `memory/memory-initializer.js` | @claude-flow/cli |
+| `MCP_MEMORY` | `mcp-tools/memory-tools.js` | @claude-flow/cli |
+| `MCP_HOOKS` | `mcp-tools/hooks-tools.js` | @claude-flow/cli |
+| `CLI_MEMORY` | `commands/memory.js` | @claude-flow/cli |
+| `CONF` | `commands/config.js` | @claude-flow/cli |
+| `HOOKS_CMD` | `commands/hooks.js` | @claude-flow/cli |
+| `NEURAL` | `commands/neural.js` | @claude-flow/cli |
+| `EMB_TOOLS` | `mcp-tools/embeddings-tools.js` | @claude-flow/cli |
+| `SETTINGS_GEN` | `init/settings-generator.js` | @claude-flow/cli |
+| `HELPERS_GEN` | `init/helpers-generator.js` | @claude-flow/cli |
+| `EXECUTOR` | `init/executor.js` | @claude-flow/cli |
+| `INIT_CMD` | `commands/init.js` | @claude-flow/cli |
+| `START_CMD` | `commands/start.js` | @claude-flow/cli |
+| `CMDS_INDEX` | `commands/index.js` | @claude-flow/cli |
+| `ruvector_cli` | `bin/cli.js` | ruvector |
+| `ruv_swarm_root` | (package root) | ruv-swarm |
+
+To target a new file, add a variable to `lib/common.py` following the existing pattern.
+
+### Step 6: Update docs and test
+
+```bash
+# Regenerate all documentation from dynamic discovery
+npm run preflight
+
+# Apply -- should show "Applied: ..."
+bash patch-all.sh --global
+
+# Idempotency -- should show "0 applied, N already present"
+bash patch-all.sh --global
+
+# Sentinel -- should show "OK: All patches verified"
+bash check-patches.sh
+
+# Tests
+npm test
+```
+
+**No manual edits needed** to `patch-all.sh`, `check-patches.sh`, `README.md`, `CLAUDE.md`, `npm/README.md`, or `npm/config.json`. Dynamic discovery handles everything.
+
+### Full Checklist
+
+- [ ] GitHub issue exists (searched first, created only if none found)
+- [ ] GitHub issue comment posted with patch details
+- [ ] `patch/{PREFIX}-{NNN}-{slug}/README.md` created with all required sections
+- [ ] `patch/{PREFIX}-{NNN}-{slug}/fix.py` created with `patch()`/`patch_all()` calls
+- [ ] `patch/{PREFIX}-{NNN}-{slug}/sentinel` created with verification directives
+- [ ] Path variable added to `lib/common.py` (if targeting a new file)
+- [ ] If new category prefix: add one line to `lib/categories.json`
+- [ ] `npm run preflight` regenerates all doc tables
+- [ ] `bash patch-all.sh` applies successfully
+- [ ] `bash patch-all.sh` is idempotent (0 applied on re-run)
+- [ ] `bash check-patches.sh` shows OK
+- [ ] Tests added to `03-patch-apply.test.mjs` and `04-idempotency.test.mjs`
+- [ ] `npm test` passes
+
+---
+
+## Removing a Defect
+
+Before removing any defect:
+
+1. Confirm the bug is genuinely fixed upstream or the patch is truly unreachable.
+2. Do NOT remove a defect just because a local workaround exists -- the MCP-level patch may still be needed.
+3. If removing, retire the defect ID permanently. Never reassign a deleted ID to a different GitHub issue.
+4. Run `npm run preflight` to regenerate all documentation.
+
+---
+
+## Testing
+
+```bash
+npm test                                    # run all tests
+node --test tests/02-common-library.test.mjs  # run one suite
+```
+
+Uses `node:test` (built-in, zero dependencies). Tests live in `tests/`.
+
+| Suite | File | What it covers |
+|-------|------|----------------|
+| CLI dispatch | `01-cli-dispatch.test.mjs` | `--help`, unknown commands, `apply` valid/invalid IDs, `check` delegation |
+| common.py | `02-common-library.test.mjs` | `patch()` apply/skip/warn/idempotent, `patch_all()`, path resolution from `BASE` |
+| Patch apply | `03-patch-apply.test.mjs` | Individual patches (HW-001, DM-002, SG-002) applied against fixtures |
+| Idempotency | `04-idempotency.test.mjs` | Double-apply produces identical files, second run reports skipped |
+| Error handling | `05-error-handling.test.mjs` | Empty `BASE`, `/dev/null`, nonexistent dir, unknown options |
+| Discovery | `06-discovery.test.mjs` | Direct/umbrella/multi-install discovery, deduplication, npx cache roots |
+
+### Fixtures
+
+`tests/fixtures/cli/dist/src/` mirrors the subset of `@claude-flow/cli` that patches target. Each file contains the exact `old` strings patches search for — just enough for `patch()` to match, not full upstream JS files.
+
+`tests/helpers/` provides:
+- `fixture-factory.mjs` — copies fixtures to a temp dir, returns `{ base, cleanup }`
+- `run-cli.mjs` — wraps `spawnSync('node', ['bin/claude-flow-patch.mjs', ...args])`
+- `run-python.mjs` — concatenates `common.py` + `fix.py` and pipes to `python3` with `BASE` set
+
+### Adding tests for a new defect
+
+1. Ensure `tests/fixtures/cli/dist/src/<target-file>.js` contains the `old` string from the new `fix.py`
+2. Add a row to the `TESTS` array in `03-patch-apply.test.mjs`
+3. Add a row to the `PATCHES` array in `04-idempotency.test.mjs`
+4. Run `npm test`
+
+---
+
+## Commands
+
+```bash
+# Apply all patches (default: --global)
+bash patch-all.sh
+
+# Patch only the npx cache
+bash patch-all.sh --global
+
+# Patch a specific project's node_modules
+bash patch-all.sh --target /path/to/project
+
+# Patch both
+bash patch-all.sh --global --target /path/to/project
+
+# Verify patches
+bash check-patches.sh
+
+# Repair a project initialized before patching
+bash repair-post-init.sh --target /path/to/project
+
+# Check target version
+grep '"version"' ~/.npm/_npx/*/node_modules/@claude-flow/cli/package.json
+
+# Show recent upstream releases (requires npm; gh optional for commit messages)
+npm run upstream-log           # last 10 versions
+npm run upstream-log -- 20     # last 20 versions
+npm run upstream-log -- --diff # also show dependency changes vs baseline
+```
+
+### Target Options
+
+| Flag | Target | When to use |
+|------|--------|-------------|
+| (none) | Global npx cache (default) | Most common — patches the npx cache |
+| `--global` | `~/.npm/_npx/*/node_modules/` | Explicit global-only |
+| `--target <dir>` | `<dir>/node_modules/` | Project with a local install |
+| `--global --target <dir>` | Both locations | Covers both invocation paths |
+
+`npx @claude-flow/cli` uses local `node_modules` if present, otherwise the global npx cache.
+
+## Dependency Order
+
+Execution order is controlled by the 3-digit numeric prefix on each directory name.
+`patch-all.sh` globs `patch/*/fix.py` which sorts lexicographically, so numeric prefixes
+execute in the correct order automatically.
+
+Two dependency chains exist:
+
+| Chain | Directories | Reason |
+|-------|-------------|--------|
+| IN-001 -> SG-003 | `170-IN-001-*` before `270-SG-003-*` | SG-003's `old_string` contains code introduced by IN-001 |
+| NS-001 -> NS-002 -> NS-003 | `190-NS-001-*` before `200-NS-002-*` before `210-NS-003-*` | Sequential namespace fixes |
+
+All other patches are independent.
+
+## Preflight & Pre-Commit Hook
+
+A git pre-commit hook at `hooks/pre-commit` runs automatically on every commit. It calls `npm run preflight:check` (read-only) and `npm test`. If anything is stale or tests fail, the commit is blocked.
+
+**Setup** (one-time, already done for this clone):
+```bash
+git config core.hooksPath hooks
+```
+
+**Before staging**, run:
+```bash
+npm run preflight    # Syncs doc tables, defect counts, version strings, config
+npm test             # Runs all tests
+```
+
+Then `git add -u` to stage the regenerated files.
+
+**What `preflight` syncs**:
+- Defect tables in README.md, CLAUDE.md, npm/README.md (from `patch/*/README.md`)
+- Defect counts in `npm/config.json` (from discovery)
+- `npm/config.json` version.current (from `package.json`)
+- Upstream baseline version in prose (from `npm/config.json` targets)
+
+Manual edits to generated sections (`<!-- GENERATED:*:begin/end -->`) will be overwritten.
+
+## Key Design Decisions
+
+- **Idempotent**: `patch()` checks if `new` string is already present before replacing.
+- **Non-destructive**: patches only modify the npx cache, never the npm registry package.
+- **Platform-aware**: DM-003 is macOS-only (auto-skipped on Linux).
+- **Sentinel-guarded**: `check-patches.sh` detects cache wipes and auto-reapplies.