wogiflow 2.32.0 → 2.33.0

package/.claude/docs/claude-code-compatibility.md

@@ -497,6 +497,57 @@ await cancelTask('wf-123', 'superseded', false);
 
 - **Experimental flag**: `CLAUDE_CODE_FORK_SUBAGENT=1` enables forked subagents on external builds. Not currently consumed by WogiFlow. Tracked as a future enhancement for faster IGR sub-agent spawning.
 
+### Features in 2.1.118+ → 2.1.139 (consolidated)
+
+Catch-up pass covering everything between 2.1.118 and 2.1.139 with a WogiFlow-relevant surface. Grouped by topic since most users jump several patch versions at once.
+
+#### Hooks
+- **`PostToolUse` `continueOnBlock` config option (2.1.139)** — when a `PostToolUse` hook returns a blocking decision, set `continueOnBlock: true` on the hook entry to feed the rejection reason back to Claude and continue the turn instead of dead-ending it. **Impact on WogiFlow (acted on, wf-cb951e91)**: WogiFlow's `PostToolUse` hook (`post-tool-use.js` → `core/validation.js runValidation`, adapter emits `decision: 'block'` on lint/typecheck failure) now sets `continueOnBlock: true` in generated settings (`scripts/hooks/adapters/claude-code.js generateConfig()`). Effect: a lint/typecheck failure after an `Edit`/`Write` is surfaced to Claude so it fixes the error in-loop — exactly what CLAUDE.md's "validate after EVERY file edit, don't edit another file until it passes" rule needs. Unknown field on Claude Code < 2.1.139 → silently ignored (prior behavior), so emitting it unconditionally is safe.
+- **Hook `args: string[]` exec form (2.1.139)** — spawns the command directly without a shell, so path placeholders never need quoting. **Impact on WogiFlow**: evaluated and **not adopted** — see `.claude/rules/alternative-hook-args-exec-form.md`. Short version: WogiFlow's generated hook commands already double-quote the absolute path (`command: \`node "${...}"\``, which handles spaces); `args` would *replace* `command` and is silently ignored on Claude Code < 2.1.139, breaking hooks for users on older CC; the robustness delta for real-world project paths is negligible. Revisit when WogiFlow's minimum supported Claude Code version reaches 2.1.139.
+- **Hooks now run without terminal access (2.1.139)** — a hook writing to the terminal could corrupt an on-screen interactive prompt; that's now prevented. **Impact on WogiFlow**: none — WogiFlow hooks communicate via the stdout-JSON protocol and use `console.error` (stderr) for debug logging only; grep-verified no hook touches `/dev/tty` or does raw terminal I/O.
+- **`PostToolUse` / `PostToolUseFailure` inputs include `duration_ms` (2.1.119)** — **Impact on WogiFlow**: `post-tool-use.js` already feeds `selectDuration(parsedInput, …)` into `captureObservation` — when Claude Code supplies `duration_ms` the observation log gets the real tool duration instead of the hook's own wall-clock estimate. Automatic improvement, no change.
+- **Fixed async `PostToolUse` hooks writing empty transcript entries (2.1.119)** — WogiFlow's `PostToolUse` hook is async (`runHook('PostToolUse', async …)`); this fixes a stray empty-entry bug. Automatic.
+- **Hooks receive active effort level via `effort.level` JSON field + `$CLAUDE_EFFORT` env var (2.1.133)**; **`PostToolUse` can replace tool output via `hookSpecificOutput.updatedToolOutput` for all tools (2.1.121)**; **hooks can invoke MCP tools via `type: "mcp_tool"` (2.1.118)** — not currently consumed by WogiFlow; tracked as possible future enhancements (e.g. effort-aware validation strictness).
+- **Fixed a malformed hooks entry invalidating the entire `settings.json` (2.1.122)** — **Impact on WogiFlow (relevant)**: WogiFlow generates the `hooks` block via `generateConfig()`. Before this fix, one bad hook entry would nuke *all* settings (permissions, model, env). Post-fix it's isolated. Reinforces the value of `node --check` + JSON-validity gates after editing hook generators (already in `.claude/settings.local.json`'s allow-list as a test command).
+- **Fixed plugin `Stop`/`UserPromptSubmit` hooks failing when cache cleanup deletes a version still in use (2.1.136)**; **`CLAUDE_ENV_FILE` SessionStart-hook env vars going stale after `/resume` or `/clear` (2.1.136)** — automatic; WogiFlow ships no plugin in this repo and doesn't use `CLAUDE_ENV_FILE`, but target-project users with plugins benefit.
+
+#### Skills & slash commands (WogiFlow `/wogi-*`)
+- **`claude_code.skill_activated` OTel event now fires for user-typed slash commands with an `invocation_trigger` attribute (2.1.126)** — every `/wogi-*` invocation now emits a telemetry event distinguishable as user-typed vs model-invoked. Useful for anyone running WogiFlow with OTel enabled; no code change.
+- **`skillOverrides` setting now works: `off` hides a skill from the model and `/`, `user-invocable-only` hides it from the model only (2.1.129)** — relevant to skill management (`lib/skill-registry.js`, `/wogi-skills`): users can hard-disable a WogiFlow skill via settings without uninstalling it. No code change; worth a `/wogi-skills` docs mention eventually.
+- **`--dangerously-skip-permissions` no longer prompts for `.claude/skills/`, `.claude/agents/`, `.claude/commands/` (2.1.121)** and **`.claude/` / `.git/` / `.vscode/` / shell-config writes (2.1.126)** — `flow hooks setup` / `flow bridge sync` writes under `.claude/` now go through cleanly in skip-permissions mode. Catastrophic deletes still prompt.
+- **Fixed skills invoked before auto-compaction re-executing on the next message (2.1.119)**; **subagents not discovering project/user/plugin skills via the Skill tool (2.1.133)** — **Impact on WogiFlow (HIGH)**: the flow is skill-driven (`/wogi-start` → `/wogi-story` → …) and Explore/Architect/Adversary sub-agents may invoke skills. Pre-fix a skill could double-fire across a compaction boundary, or a sub-agent couldn't see project skills at all. Both fixed; reliability improvement, no code change.
+- **`claude ultrareview [target]` non-interactive subcommand (2.1.120)** — CI/script equivalent of `/ultrareview`. WogiFlow's session guidance already says `/ultrareview` is user-triggered and billed; this adds a headless variant. No change.
+- **Fixed `AskUserQuestion` discarding multi-select answers supplied as an array (2.1.136)** — WogiFlow uses `AskUserQuestion` in interactive flows (blocked only in workspace *worker* mode). Multi-select answers now round-trip correctly. Automatic.
+
+#### Worktrees & sub-agents
+- **`worktree.baseRef` setting (`fresh` | `head`, 2.1.133)** and **`EnterWorktree` now branches from local `HEAD` as documented (2.1.128)** — WogiFlow's own `flow-worktree.js` is independent of native worktrees (different location, branch naming, cleanup — see the comparison table below) but *detects* and reuses a native worktree when launched with `--worktree`. The new `baseRef: head` default aligns native worktrees with what WogiFlow already does (branch from current state). No change.
+- **Fixed `Agent` tool with `isolation: "worktree"` reusing stale worktrees (2.1.119)** — complements the 2.1.97 subagent-worktree-cwd-leak fix. `/wogi-bulk` and parallel-explore spawn worktree-isolated sub-agents; stale-worktree reuse could run a sub-agent against the previous task's tree. Fixed. Automatic.
+- **Sub-agent progress-summary prompt-cache fixes (2.1.128: ~3× `cache_creation` reduction; summaries no longer fire repeatedly while the transcript is static)** — WogiFlow spawns several sub-agents per L1+ task (Explore ×N, Architect, Adversary). Cheaper, quieter sub-agent runs. Automatic.
+
+#### Context, caching, 1M models
+- **Fixed the 1-hour prompt-cache TTL being silently downgraded to 5 minutes (2.1.129)** — **Impact on WogiFlow (HIGH)**: WogiFlow loads a large stable prefix every turn (CLAUDE.md ~300 lines + `decisions.md` + `ready.json` + phase files + pinned spec context). The `ENABLE_PROMPT_CACHING_1H` guidance in the 2.1.108 section assumed 1h TTL actually held; before this fix it could collapse back to 5min, re-billing the whole prefix after any short pause. Fixed in 2.1.129. **Action**: still `export ENABLE_PROMPT_CACHING_1H=1` for API-key/Bedrock/Vertex/Foundry users (subscribers get 1h by default) — just be on 2.1.129+.
+- **Fixed Bedrock/Vertex 400 errors when `ENABLE_PROMPT_CACHING_1H` is set (2.1.132)** — **Impact on WogiFlow (HIGH)**: this is the caveat referenced from the 2.1.108 section. **Concrete version**: Bedrock/Vertex users who set `ENABLE_PROMPT_CACHING_1H=1` MUST be on Claude Code **2.1.132+** — older versions return 400 on every request. Direct-API and subscriber users are unaffected.
+- **Fixed sessions on 1M-context models falsely blocked with "Prompt is too long" before the real API limit (2.1.128)** and **`/context` dumping its rendered ASCII grid into the conversation (~1.6k wasted tokens) (2.1.129)** — **Impact on WogiFlow (HIGH)**: WogiFlow runs on Opus 4.7 with the 1M window and loads heavy context; pre-2.1.128 a long-but-legal prompt could be rejected outright. `scripts/flow-context-estimator.js` works in CC-supplied percentages (audited 2026-04-22, see the 2.1.117 entry), so it consumes the corrected numbers correctly. No code change.
+- **`/config` now persists to `~/.claude/settings.json` and participates in override precedence (2.1.119)** — settings the user changes via `/config` now interact with WogiFlow-generated `.claude/settings.json` / `.claude/settings.local.json` through the normal precedence chain. No conflict; just be aware `/config` writes are now durable.
+- **`CLAUDE_CODE_SESSION_ID` env var in the Bash-tool subprocess environment (2.1.132)**; **`CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1` (2.1.132)** — informational; not consumed by WogiFlow.
+- **Statusline stdin JSON now includes `effort.level` and `thinking.enabled` (2.1.119)** — relevant to `/wogi-statusline-setup`: the WogiFlow statusline could surface the active effort level. Tracked as a future enhancement; the current statusline doesn't use it.
+
+#### MCP
+- **MCP stdio servers now receive `CLAUDE_PROJECT_DIR` in their environment, matching hooks (2.1.139)** — WogiFlow ships no in-repo MCP server; `scripts/flow-mcp-*` only *discover* capabilities Claude Code already exposes (`ToolSearch`, `ListMcpResourcesTool`). User-installed MCP servers (figma, atlassian, gmail, …) benefit automatically.
+- **`/mcp` Reconnect picks up `.mcp.json` edits without restart and shows HTTP status/URL on failure (2.1.139)**; **remote-MCP transient-failure reconnect retry enabled for all users (2.1.139)**; **fixed MCP servers in `.mcp.json`/plugins/connectors silently disappearing after `/clear` (2.1.136)**; **fixed deferred tools unavailable to skills with `context: fork` and subagents on first turn (2.1.126)**; **fixed `ToolSearch` missing MCP tools that connect after session start in nonblocking mode (2.1.122)** — **Impact on WogiFlow**: WogiFlow uses deferred MCP tools (Atlassian/Figma/Gmail/Google Calendar surfaces) and `ToolSearch`; these fixes make deferred-tool availability reliable across `/clear`, forked-context skills, and late-connecting servers. Automatic.
+- **Fixed unbounded memory growth when a stdio/HTTP-SSE MCP server writes non-protocol data (2.1.132; 2.1.139 caps SSE bodies at 16 MB/frame)** — automatic; benefits users with chatty MCP servers.
+
+#### Misc / no WogiFlow surface (automatic after upgrade)
+- `/goal` command (2.1.139): a per-session completion condition Claude works toward across turns. Conceptually overlaps WogiFlow's Autonomous Walk-Away Mode (`go until you finish`) and the `/loop` skill — no conflict; they operate at different layers (`/goal` is a Claude Code session feature; WogiFlow's autonomous mode is task-queue-driven). Not integrated.
+- Agent view / `claude agents` (2.1.139), `/scroll-speed` (2.1.139), `claude plugin details <name>` with projected per-session token cost (2.1.139), transcript-view navigation (2.1.139), `/context all` tokenizer-accurate per-skill estimates (2.1.139): editor/TUI conveniences, no WogiFlow surface.
+- Plugin/project tooling: `claude plugin install <name>@<marketplace>` auto-refresh + retry (2.1.139), `claude plugin prune` (2.1.121), `claude plugin tag` (2.1.118), `claude plugin validate` accepting top-level `$schema`/`version`/`description` (2.1.120), `claude project purge [path]` (2.1.126), `--plugin-url <url>` / `--plugin-dir` accepting `.zip` (2.1.128–2.1.129). `/wogi-register` and plugin-registry routing are unaffected; users authoring WogiFlow-adjacent plugins get nicer tooling.
+- API requests from sub-agents now carry `x-claude-code-agent-id` / `x-claude-code-parent-agent-id` headers and `claude_code.llm_request` OTel spans include `agent_id` / `parent_agent_id` (2.1.139): WogiFlow's Explore/Architect/Adversary sub-agents now show parent-agent attribution in telemetry. No code change.
+- Remote Control, `/schedule`, claude.ai MCP connectors, and notification preferences are disabled when `ANTHROPIC_API_KEY` / `apiKeyHelper` / `ANTHROPIC_AUTH_TOKEN` is set (2.1.139): API-key users lose those claude.ai-tied features (unset the key to use them). Orthogonal to WogiFlow.
+- Compaction prompt now asks the model to preserve sensitive user instructions (2.1.139): complements WogiFlow's "Compact Instructions" block in CLAUDE.md — SYSTEM-side compaction is now likelier to retain critical project rules. No change.
+- Auth/credential reliability: fixed login-loop / concurrent-credential-write / OAuth-refresh-race bugs across 2.1.118, 2.1.126, 2.1.129, 2.1.133, 2.1.136; fixed the `claude auth login/logout/status` deadlock with expired credentials + `forceRemoteSettingsRefresh` (2.1.139). Plus the usual TUI/scroll/Windows-terminal/render fixes (~30 in 2.1.139 alone). All automatic.
+- `Skill(name *)` permission-rule wildcard now works as a prefix match like `Bash(ls *)` (2.1.139): WogiFlow's generated settings allow-list `Skill(wogi-*)` (e.g. `.claude/settings.local.json`). This fix makes that wildcard reliably match all `/wogi-*` skills as a prefix. No code change; confirms the existing form is correct.
+- Permission-matching correctness fixes: `Bash(mkdir *)`/`Bash(touch *)` now honored for in-project paths (2.1.129); `Edit(...)` allow rules scoped to drive root or POSIX `/` no longer always prompt (2.1.133); plan mode now blocks file writes even when a matching `Edit(...)` allow rule exists (2.1.136); `--dangerously-skip-permissions` broadened (2.1.126). See also `.claude/rules/security/security-patterns.md` §6 on scoping destructive commands — WogiFlow's `generateSettings()` already scopes destructive git variants narrowly; no change.
+
 ### Simple Mode Naming Distinction
 
 Claude Code's `CLAUDE_CODE_SIMPLE` environment variable (which enables a simplified tool set) is **unrelated** to WogiFlow's `loops.simpleMode` (a lightweight task completion loop using string detection). They are separate features that happen to share the word "simple":

package/.claude/docs/scheduled-mode.md

@@ -0,0 +1,213 @@
+# Scheduled / Background Mode (Phase 1A)
+
+Continuous, **read-only**, background-mode quality signal for WogiFlow projects.
+Phase 1A of `epic-quality-loop` (task `wf-b211a076`).
+
+WogiFlow's review/audit/regression skills produce high-quality signal *only*
+when a developer is actively in a Claude Code session. Scheduled mode closes
+that loop by running designated `/wogi-*` commands on a cadence and reporting
+findings as GitHub Issues / PR-comments — **never auto-merges, never edits
+rule files, never pushes commits**.
+
+## The four jobs
+
+| Job | Schedule (UTC) | What it does | Posts to |
+|-----|---------------|--------------|----------|
+| `nightly-regression` | `0 3 * * *` (daily 03:00) | Wraps `scripts/flow-step-regression.js`. Skipped on empty 24h diff. | `wogi/scheduled-nightly-regression` labelled issue (silent on green) |
+| `weekly-audit`       | `0 9 * * 1` (Mon 09:00)  | Headless `claude -p` running `/wogi-audit`. | `wogi/scheduled-weekly-audit` labelled issue |
+| `weekly-digest`      | `0 17 * * 5` (Fri 17:00) | Headless `claude -p` running `/wogi-debt` + `/wogi-gate-stats --since=7d`. | `wogi/scheduled-weekly-digest` labelled issue |
+| `per-pr-review`      | on every PR event        | `claude ultrareview <PR>` headless variant. | PR comment via `gh pr comment` |
+
+## Setup
+
+### Option A — GitHub Actions (recommended)
+
+The workflow lives at `.github/workflows/wogi-scheduled.yml`. To enable:
+
+1. Set `scheduledMode.enabled: true` in `.workflow/config.json`.
+2. Ensure your repo has these secrets:
+   - `ANTHROPIC_API_KEY` — for headless `claude -p` invocations
+   - `GITHUB_TOKEN` — auto-provided by Actions (no setup needed)
+3. The workflow runs automatically on its cron schedule and on every PR.
+
+### Option B — Local scheduler
+
+For users who don't want GH Actions, `flow schedule install` writes
+platform-native unit files:
+
+```bash
+# macOS — LaunchAgent plists in ~/Library/LaunchAgents/
+flow schedule install --target=launchd
+
+# Linux — systemd --user units in ~/.config/systemd/user/
+flow schedule install --target=systemd
+# then activate:
+systemctl --user enable --now wogi-scheduled-nightly-regression.timer
+systemctl --user enable --now wogi-scheduled-weekly-audit.timer
+systemctl --user enable --now wogi-scheduled-weekly-digest.timer
+
+# Any Unix — crontab fragment
+flow schedule install --target=cron
+# then activate:
+(crontab -l 2>/dev/null; cat ~/.config/wogi-flow/crontab-fragment) | crontab -
+
+# Inspect what's installed
+flow schedule status
+
+# Remove
+flow schedule remove --target=launchd|cron|systemd
+```
+
+Use `--dry-run` on `install` to preview the unit files without writing them.
+
+## Cost projection (dry-run mode)
+
+Before enabling, run a dry-run to see projected monthly USD spend:
+
+```bash
+node scripts/flow-scheduled-runner.js weekly-audit --dry-run
+```
+
+Output:
+
+```
+scheduled-runner: DRY-RUN (job=weekly-audit, model=sonnet)
+Projected monthly cost across all configured jobs: $XX.XX
+
+Per-job:
+  nightly-regression     haiku    30× 1,200,000 tok → $1.50
+  weekly-audit           sonnet   4× 600,000 tok → $3.60
+  weekly-digest          sonnet   4× 120,000 tok → $0.72
+  per-pr-review          opus     20× 1,600,000 tok → $48.00
+```
+
+(Numbers are conservative estimates for budgeting. Actual billing varies.)
+
+## Configuration
+
+In `.workflow/config.json`:
+
+```json
+{
+  "scheduledMode": {
+    "enabled": false,
+    "dailyTokenBudget": 5000000,
+    "perJobModel": {
+      "nightly-regression": "haiku",
+      "weekly-audit": "sonnet",
+      "weekly-digest": "sonnet",
+      "per-pr-review": "opus"
+    },
+    "dryRun": false,
+    "jobs": ["nightly-regression", "weekly-audit", "weekly-digest", "per-pr-review"]
+  }
+}
+```
+
+| Key | Meaning |
+|-----|---------|
+| `enabled` | Master switch. Default `false`. |
+| `dailyTokenBudget` | Cap across all jobs for a single calendar day. When projected total would exceed, remaining same-day jobs no-op with a logged warning. |
+| `perJobModel` | Model used per job. Allowlist: `haiku`, `sonnet`, `opus`. |
+| `dryRun` | Force every invocation into dry-run mode. |
+| `jobs` | Subset of jobs to include in cost projections. |
+
+## Read-only-by-default invariants
+
+These are non-negotiable. Enforced both by the runner code and by static-grep
+tests in `tests/flow-scheduled-runner.test.js`:
+
+1. **No `git push` to non-bot refs.** The runner never calls
+   `git push origin master`/`main`.
+2. **No `gh pr merge`.** The PR-review job posts comments only.
+3. **No edits to `.workflow/state/decisions.md`.** Rule files are sacrosanct.
+4. **Default-branch only.** The runner detects `origin/HEAD` and records the
+   current branch in the audit trail. The temp worktree (invariant #5) is
+   created on the default branch regardless, so accidental developer-branch
+   leakage cannot reach scheduled execution.
+5. **Temp worktree (real, hard-enforced).** All work happens in an isolated
+   worktree created via `scripts/flow-worktree.js → runInWorktree()`. If
+   worktree creation fails, the runner opens a `wogi/scheduled-failure` issue
+   and exits non-zero — it does NOT silently fall back to the user's working
+   dir. (Fixed in R-379 / F2; prior versions had the claim in the JSDoc only.)
+
+## Safeguards in detail
+
+| Safeguard | Where |
+|-----------|-------|
+| 10-minute hard timeout per job | `lib/scheduled-mode.js → withTimeout()` + `AbortController` |
+| Retry-1×-then-alert with 30s backoff | `scripts/flow-scheduled-runner.js → runJobWithRetry()` |
+| Token-budget cap | `lib/scheduled-mode.js → enforceTokenBudget()` |
+| Dedup labelled issue (no spam) | `lib/scheduled-mode.js → updateDedupIssue()` |
+| Silence on green | `runNightlyRegression()` exits without posting if all pass |
+| Skip on empty 24h diff | `hasDiffSinceYesterday()` uses `git log --since=24 hours ago` |
+| Stale-marker clearing | `clearStaleMarkers()` removes `routing-pending.json` + `pending-question.json` before each invocation |
+| Failure alerts | `openFailureIssue()` creates a `wogi/scheduled-failure` issue with captured stderr |
+
+## Kill-switch
+
+```json
+{ "scheduledMode": { "enabled": false } }
+```
+
+Or, for the GH Actions path: disable the workflow in **Actions → Workflows →
+"Wogi Scheduled Quality Loop" → Disable workflow**.
+
+Local schedulers: `flow schedule remove --target=<target>`.
+
+## Troubleshooting
+
+**Q: The nightly-regression job posts every night even though tests pass.**
+A: Check the dedup label `wogi/scheduled-nightly-regression`. Silence-on-green
+   only suppresses posts when `result.passed === true`. Check the issue body
+   to see what failed.
+
+**Q: My GH workflow is hitting the 10-min timeout.**
+A: Per-job timeout is set in `lib/scheduled-mode.js` as
+   `DEFAULT_JOB_TIMEOUT_MS`. Either raise it (caveat: cost), or split the
+   job (e.g. run audit on a subset of files via `--scope=`).
+
+**Q: How do I see what's currently scheduled locally?**
+A: `flow schedule status` returns a JSON blob with all installed units across
+   launchd / cron / systemd.
+
+**Q: How does `--dry-run` differ from `enabled: false`?**
+A: `enabled: false` makes the runner exit 0 immediately without any output.
+   `--dry-run` runs the projection logic and prints `$/month` — useful for
+   previewing before flipping `enabled` to `true`.
+
+**Q: What about non-GitHub repos (GitLab, Bitbucket)?**
+A: Phase 1A is GitHub-specific (uses `gh` CLI for dedup issues). Multi-host
+   support is out-of-scope; can be added in a future phase if needed.
+
+## Architecture
+
+```
+.github/workflows/wogi-scheduled.yml   ← cron triggers + permissions matrix
+        │
+        ▼
+scripts/flow-scheduled-runner.js       ← entry point (timeout, retry, budget)
+        │
+        ▼
+lib/scheduled-mode.js                  ← pure helpers (CLI-agnostic)
+        │
+        ▼
+scripts/flow-step-regression.js        ← existing nightly-regression target
+        │     (UNMODIFIED — runner wraps it)
+        ▼
+claude -p --model=<X> /wogi-audit      ← for weekly-audit / weekly-digest / PR-review
+```
+
+The runner follows the hook three-layer pattern: business logic in
+`lib/scheduled-mode.js` (CLI-agnostic, exhaustively unit-tested), thin entry
+point in `scripts/flow-scheduled-runner.js`, no transformation needed for
+its single consumer (CLI / GH workflow).
+
+## Out of scope (Phase 1A)
+
+- **Auto-fix / auto-merge** — by design. Phase 1A is read-only.
+- **Multi-repo aggregation** — single repo per workflow file.
+- **Cross-runner state** — each job is independent. The usage log is the only
+  shared state and is keyed by day, not by run.
+- **Custom job definitions** — the four jobs are fixed. Adding a fifth
+  requires code + a new entry in `JOB_NAMES`.

package/.claude/docs/skill-portability.md

@@ -0,0 +1,190 @@
+# Skill Portability — Export to agentskills.io / Claude Code plugin
+
+Phase 1B of the Continuous Code-Quality Initiative (epic `epic-quality-loop`,
+task `wf-0342fc33`) adds a portable export path for WogiFlow skills. This
+document explains what "portable" means in this context, how the portability
+checker works, how to publish to either supported format, and why **import is
+deliberately deferred**.
+
+## What is a "portable" skill?
+
+A WogiFlow skill is *portable* when its content runs unchanged in a Claude
+Code (or agentskills.io–compatible) environment that does NOT have WogiFlow
+installed. In practice that means:
+
+- No references to `.workflow/` paths (state files, specs, dossiers, epics).
+- No references to WogiFlow state files by name: `ready.json`,
+  `feedback-patterns.md`, `decisions.md`, `app-map.md`, `function-map.md`,
+  `api-map.md`.
+- No mentions of WogiFlow-specific tooling: `flow-utils`, `./scripts/flow`,
+  WogiFlow-specific `flow <subcommand>` invocations.
+- No `/wogi-*` slash-command invocations.
+- No `wogiflow-cloud` references (paid tier is out of scope for the OSS
+  catalog).
+
+Skills that legitimately depend on any of the above are **not** portable.
+That's fine — they remain available in WogiFlow's own catalog (the
+`Wogi-Git/wogi-flow-skills` registry), which is unaffected by this work.
+
+## The `portable` manifest field
+
+Every skill manifest gains an optional `portable: true|false` field. Default
+is `false` — exports refuse skills that haven't opted in.
+
+```yaml
+---
+name: my-skill
+version: 1.0.0
+description: ...
+license: MIT
+portable: true     # <-- new in Phase 1B
+---
+```
+
+Setting `portable: true` only declares the intent. The portability checker
+still runs and overrides the declaration if it finds WogiFlow-specific
+references — fail-loud is the rule.
+
+Setting `portable: false` explicitly short-circuits the checker and blocks
+export. Use this when your skill has an implicit dependency on a project
+convention the scanner can't detect.
+
+## How the portability checker works
+
+`lib/skill-portability.js` walks the skill directory and scans every
+text-y file (`.md`, `.txt`, `.json`, `.yaml`, `.js`, `.ts`, `.sh`, etc.)
+line by line. Each line is matched against a fixed set of blocker patterns;
+matches become citations of the form `file:line — "<offending substring>"`.
+
+Run the checker via the export CLI — it always runs first:
+
+```bash
+flow skill export my-skill
+# → succeeds, or prints the citation list and exits 1.
+```
+
+## Two-catalog principle
+
+WogiFlow maintains two parallel skill catalogs:
+
+| Catalog | Holds | Distribution |
+|---------|-------|--------------|
+| **WogiFlow registry** (`Wogi-Git/wogi-flow-skills`) | All skills, portable or not | `flow skill add <name>` |
+| **agentskills.io / Claude Code plugins** | *Portable subset only* | `flow skill export <name>` |
+
+The WogiFlow registry stays canonical for non-portable skills that depend on
+WogiFlow-specific paths or commands. Phase 1B adds export *alongside* the
+existing registry — it never replaces it.
+
+## Publishing to agentskills.io
+
+```bash
+flow skill export my-skill --format=agentskills@v1
+```
+
+Output (default `dist/skills/my-skill/`):
+
+```
+dist/skills/my-skill/
+├── manifest.json        # agentskills@v1 manifest (schemaVersion pinned)
+├── skill.md             # the skill itself
+├── knowledge/...        # bundled aux files
+└── templates/...
+```
+
+Manifest shape (pinned to `schemaVersion: "agentskills@v1"`):
+
+```json
+{
+  "schemaVersion": "agentskills@v1",
+  "name": "my-skill",
+  "version": "1.0.0",
+  "description": "...",
+  "license": "MIT",
+  "compatibility": "Claude Code 2.1+",
+  "instructions": "<post-frontmatter body of skill.md>",
+  "source": { "type": "wogiflow" },
+  "files": ["skill.md", "knowledge/learnings.md"],
+  "dependencies": []
+}
+```
+
+Note: this module operates offline. We do not fetch the agentskills.io v1
+schema at export time. Our serializer pins `schemaVersion` to a known
+identifier so a future CI contract test (Phase 1B acceptance criterion) can
+catch drift once the network gate is built. Until then, this is our
+authoritative interpretation of the v1 shape; see `lib/skill-export-agentskills.js`
+header comment.
+
+## Publishing as a Claude Code plugin
+
+```bash
+flow skill export my-skill --format=claude-plugin
+```
+
+Output (default `dist/skills/my-skill/`):
+
+```
+dist/skills/my-skill/
+├── .claude-plugin/
+│   └── plugin.json      # Claude Code plugin manifest
+└── skills/
+    └── my-skill/
+        ├── SKILL.md     # normalized from skill.md
+        └── knowledge/...
+```
+
+This layout matches the convention used by shipping Claude Code plugins
+(e.g., the official Figma plugin). It is ready for the
+`claude plugin tag` distribution path (Claude Code 2.1.118+).
+
+## Why import is deferred
+
+The Phase 1B spec explicitly defers `flow skill import <archive>` to a
+follow-up. Reason: importing third-party skills means executing third-party
+content under our existing tool-grant model. Even Markdown-only skills can
+declare `allowed-tools` and ship templates that an agent will treat as
+authoritative. Shipping import without a security model would mean either:
+
+- Granting third-party skills our default tool surface (Read/Write/Edit/
+  Glob/Grep/Bash) on first install — unsafe by default, breaks our
+  no-surprise principle.
+- Or stripping `allowed-tools` and re-prompting the user on every tool use
+  — degraded UX that defeats the point of skills.
+
+The right design is **quarantine + content scanner + opt-in enable**:
+
+1. Imported skills land in `.claude/skills-quarantine/` (off the loader path).
+2. A content scanner flags `allowed-tools`, scripts, bash invocations,
+   and any reference to known sensitive paths for review.
+3. The user explicitly promotes a skill out of quarantine after review.
+
+That work needs a dedicated security-model spec and is the obvious next
+phase after the catalog is seeded with safe exports.
+
+The import insertion point in `scripts/flow-skill-export.js` is marked
+with the comment `[import would go here]` so a future task can locate it
+without grep.
+
+## Which in-repo skills are portable?
+
+At Phase 1B ship:
+
+| Skill | Portable | Why |
+|-------|----------|-----|
+| `_template`            | yes | No WogiFlow refs; a clean template by design. |
+| `conventional-commit`  | yes | Reusable across any git repo. |
+| `figma-analyzer`       | no  | References `.workflow/state/`, `./scripts/flow figma`, `/wogi-flow`, and a WogiFlow MCP server (28 blockers). To make it portable, decouple from the WogiFlow component registry. |
+
+The portability tag also shows up in `flow skill list` output as
+`[portable]` for any installed skill whose local manifest carries
+`portable: true`.
+
+## Roadmap
+
+- Phase 1B (this work) — export only. Two catalog separation. Portability
+  checker is the single source of truth for "exportable".
+- Follow-up (post-security-model) — `flow skill import` with quarantine.
+- Phase 3 candidate — auto-flag drift when a portable skill picks up a
+  WogiFlow-specific reference in a later edit (the same scanner, run via
+  the registry-update gate).

package/.claude/rules/alternative-hook-args-exec-form.md

@@ -0,0 +1,6 @@
+# Alternative: Migrate generated hook registrations to the `args: string[]` exec form
+
+**Rejected**: 2026-05-12
+**Reason**: Claude Code 2.1.139 added an `args: string[]` field for hook entries that spawns the command directly without a shell, so path placeholders never need quoting. WogiFlow's generated hook registrations (`generateConfig()` in `scripts/hooks/adapters/claude-code.js`) already emit `command: \`node "${absolutePath}"\`` — the absolute script path is double-quoted, which already handles spaces in the project path. Switching to `args` would buy only marginal robustness (paths containing a literal `"` or shell metacharacters — vanishingly rare for real project directories) while introducing a real regression: `args` is silently ignored on Claude Code < 2.1.139, and since it *replaces* `command` rather than augmenting it, a hook entry that emits only `args` would do nothing on older Claude Code — breaking task gating, validation, routing enforcement, etc. for any user not yet on 2.1.139. WogiFlow does not currently require a minimum Claude Code version that high (`postinstall.js` version-gates individual hook *events*, but the base hook set must work on much older CC). The shell-chain commands that actually have gnarly quoting (the `&&`/`2>/dev/null`/`$(...)` one-liners) live in the **permissions allow-list**, not in hook registrations, and cannot use exec form at all (no shell = no `&&`).
+**Chose instead**: Keep `command: \`node "${path}"\``. If WogiFlow's minimum supported Claude Code version ever reaches 2.1.139, revisit — at that point `buildHookEntry()` could emit `args: ["node", scriptPath]` for the `command` transport and drop the manual quoting. Until then, the double-quoted `command` form is correct and maximally compatible.
+**Source**: wf-cb951e91 — "Respond to Claude Code v2.1.139 changelog" (AC2).

package/.claude/settings.json

@@ -41,7 +41,8 @@
           {
             "type": "command",
             "command": "node scripts/hooks/entry/claude-code/post-tool-use.js",
-            "timeout": 60
+            "timeout": 60,
+            "continueOnBlock": true
           }
         ]
       }

package/.claude/skills/_template/skill.md

@@ -9,6 +9,7 @@ agent: developer
 memory: project
 license: MIT
 compatibility: Claude Code 2.1+
+portable: true
 allowed-tools:
   - Read
   - Glob

package/.claude/skills/conventional-commit/knowledge/examples.md

@@ -0,0 +1,65 @@
+# Conventional Commit Examples
+
+Each example shows a diff summary on the left and the commit message that
+fits it on the right. Use these as anchors when classifying ambiguous
+changes.
+
+## feat
+
+```
++ src/auth/oauth-callback.ts
++ src/auth/oauth-callback.test.ts
+```
+
+```
+feat(auth): add Google OAuth callback handler
+
+Wires the OIDC callback to the existing session store. Falls back to
+local password auth when the provider is unconfigured.
+```
+
+## fix
+
+```
+~ src/parser/json.ts (1 hunk)
++ src/parser/json.test.ts (1 hunk)
+```
+
+```
+fix(parser): handle UTF-8 BOM in JSON input
+
+The parser silently truncated the first key when the file began with a
+BOM. Strip the BOM before handing the buffer to JSON.parse.
+
+Closes #142
+```
+
+## refactor
+
+```
+~ src/utils/path-helpers.ts
+~ src/cli/index.ts
+```
+
+```
+refactor(utils): extract path-normalization into a shared helper
+
+No functional change. Removes duplication between cli/index.ts and
+worker/runner.ts.
+```
+
+## BREAKING CHANGE
+
+```
+~ src/api/client.ts
+~ README.md
+```
+
+```
+feat(api)!: rename `client.send()` to `client.dispatch()`
+
+The old name was ambiguous with WebSocket `send`. Update all callers.
+
+BREAKING CHANGE: client.send() has been removed. Use client.dispatch()
+instead. Codemod available at scripts/migrate-v2.js.
+```

package/.claude/skills/conventional-commit/skill.md

@@ -0,0 +1,76 @@
+---
+name: conventional-commit
+version: 1.0.0
+description: Format git commit messages following the Conventional Commits 1.0 specification
+scope: project
+user-invocable: true
+context: inline
+agent: developer
+memory: project
+license: MIT
+compatibility: Claude Code 2.1+
+portable: true
+allowed-tools:
+  - Read
+  - Bash(git *)
+lastUpdated: 2026-05-13
+---
+
+# Conventional Commit Skill
+
+A reusable, project-agnostic skill that helps an agent compose
+[Conventional Commits 1.0](https://www.conventionalcommits.org/en/v1.0.0/)
+messages from the staged diff.
+
+## When to Use
+
+- The user asks to "commit" recent changes.
+- An automated workflow wraps up and needs to record a commit.
+- A patch series should be split into typed, scoped commits.
+
+## Format
+
+```
+<type>(<scope>): <description>
+
+[body]
+
+[footer(s)]
+```
+
+| Type       | When to use |
+|------------|-------------|
+| `feat`     | New feature or capability |
+| `fix`      | Bug fix |
+| `docs`     | Documentation only |
+| `style`    | Formatting, whitespace (no logic change) |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `perf`     | Performance improvement |
+| `test`     | Adding or updating tests |
+| `chore`    | Build process, tooling, dependencies |
+
+The optional `BREAKING CHANGE:` footer escalates the commit to a major bump
+for tools that consume Conventional Commits (semantic-release, changelog
+generators, etc.).
+
+## Workflow
+
+1. Read the staged diff with `git diff --staged`.
+2. Classify the change against the type table above. If multiple types
+   apply, split into multiple commits rather than mixing.
+3. Choose a scope — usually a module name, directory, or feature area.
+4. Draft a one-line description in the imperative mood (50 chars max).
+5. If the change is non-obvious, add a body explaining the *why*.
+6. Run the commit. Don't push.
+
+## Output
+
+The skill produces a commit message that an agent can pass to
+`git commit -F -`. It does not run `git push`, does not edit code, and
+does not touch the working tree.
+
+## Why this skill is portable
+
+This skill references no project-specific paths, state files, or slash
+commands. It works in any git repository regardless of which AI workflow
+framework is in use. That makes it a clean Phase 1B export target.

package/bin/flow

@@ -229,6 +229,22 @@ function main() {
     return;
   }
 
+  if (command === 'schedule') {
+    // Scheduled-mode unit installer (Phase 1A — wf-b211a076).
+    // Lightweight wrapper; the actual logic lives in scripts/flow-schedule.js
+    // so it can be unit-tested without spawning the CLI.
+    try {
+      const schedule = require('../scripts/flow-schedule');
+      const result = schedule.dispatch(args.slice(1));
+      if (result.output) console.log(result.output);
+      process.exit(result.ok ? 0 : 1);
+    } catch (err) {
+      console.error(`Schedule error: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   // For all other commands, try to find project context
   const projectRoot = findProjectRoot();