feat(ultraplan-local): Spor 3 — semantic plan-critic, examples, CC features, security docs

- agents/plan-critic.md: rule #7 split into literal blockers (TBD/TODO/FIXME)
  + semantic rubric with 8 deferred-decision tests; calibrated against the
  5-phrase corpus from the v3.1.0 quality brief
- hooks/hooks.json: rebuilt from corrupted state; valid JSON, registers
  PreToolUse(Bash,Write), UserPromptSubmit, PostToolUse(Bash), PreCompact
- hooks/scripts/session-title.mjs: NEW — sets ultra:<cmd>:<slug> session
  title for ultra commands (CC v2.1.94+)
- hooks/scripts/post-bash-stats.mjs: NEW — appends duration_ms per Bash
  call to ultraexecute-stats.jsonl (CC v2.1.97+)
- SECURITY.md: NEW — Forgejo private-issue reporting, supported = current
  minor only, scope = 4 hooks + denylist, hardening recommendations
- docs/architect-bridge-test.md: NEW — manual smoke checklist for the
  ultraplan ↔ ultra-cc-architect bridge
- examples/01-add-verbose-flag/: NEW — calibrated end-to-end (brief +
  research + plan + progress.json) for fork-er onramp; all four artifacts
  pass their validators
- README.md: + Extending the plugin, + Headless multi-session tuning
  (MCP_CONNECTION_NONBLOCKING), + Session titles, + Per-step timing,
  + disableSkillShellExecution recommendation
- CLAUDE.md: documents session-title.mjs and post-bash-stats.mjs
- root README.md: v3.1.0 entry expanded with Spor 2+3 deliverables

CC features adopted: F8, F9, F12 implemented; F3 implemented as Bash
PostToolUse logger; F2 (hook 'if'-field scoping) deferred — universal
protection beats reduced-scope protection for blocked commands.

Tests: 109/109 green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

plugins/ultraplan-local/README.md

@@ -339,6 +339,23 @@ The executor implements defense-in-depth security across four layers:
 3. **Pre-execution plan scan** — Phase 2.4 scans all `Verify:` and `Checkpoint:` commands against the denylist before execution begins, catching dangerous commands before they reach the executor
 4. **Scoped tool access** — Headless child sessions use `--allowedTools "Read,Write,Edit,Bash,Glob,Grep"` instead of `--dangerously-skip-permissions`, blocking Agent spawning, MCP tools, and web access in parallel sessions
 
+#### Recommended: disable Skill shell execution (CC v2.1.91+)
+
+For fork-ers handling untrusted task briefs or plans from external
+sources, set `disableSkillShellExecution: true` in `~/.claude/settings.json`
+or in the project's `.claude/settings.json`:
+
+```json
+{
+  "disableSkillShellExecution": true
+}
+```
+
+This prevents Skills from invoking arbitrary shell, which closes a
+prompt-injection vector that the plugin's own hooks cannot fully mitigate
+(Skills can fire before `pre-bash-executor` matches). See
+[SECURITY.md](SECURITY.md) for the full hardening list.
+
 ### Headless execution
 
 `/ultraexecute-local` is designed for `claude -p` headless sessions:
@@ -347,6 +364,45 @@ The executor implements defense-in-depth security across four layers:
 - **Scope fence enforcement** — never touches files outside the session's scope
 - **JSON summary** — machine-parseable `ultraexecute_summary` block for log parsing
 
+#### Headless multi-session tuning (CC v2.1.89+)
+
+When running multiple parallel `claude -p` sessions (decomposed plans
+or wave-based execution), set `MCP_CONNECTION_NONBLOCKING=true` in the
+launching environment so MCP server connection latency does not
+serialize startup across waves:
+
+```bash
+export MCP_CONNECTION_NONBLOCKING=true
+bash .claude/projects/{slug}/sessions/launch.sh
+```
+
+Without this, each child session can spend 1-3 s blocking on MCP
+connect, multiplying across waves. Setting it lets MCP connect lazily
+on first tool call.
+
+### Session titles for ultra commands (CC v2.1.94+)
+
+A `UserPromptSubmit` hook (`hooks/scripts/session-title.mjs`) sets the
+session title to `ultra:<command>:<slug>` whenever you invoke one of
+the four ultra commands. This makes multi-session headless runs and
+session-picker output trivially identifiable. Slug derivation:
+
+| Invocation | Session title |
+|-----------|---------------|
+| `/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth` | `ultra:plan:jwt-auth` |
+| `/ultrabrief-local --quick` | `ultra:brief:ad-hoc` |
+| `/ultraexecute-local --project .claude/projects/2026-05-10-cleanup --resume` | `ultra:execute:cleanup` |
+
+The hook is fail-open — any error → title is left untouched.
+
+### Per-step timing (CC v2.1.97+)
+
+A `PostToolUse` hook (`hooks/scripts/post-bash-stats.mjs`) appends
+`duration_ms` from each Bash tool call to
+`${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl`. One line per Bash
+call; useful for identifying long-running verify or checkpoint commands
+across executions.
+
 ---
 
 ## The full pipeline
@@ -605,6 +661,82 @@ CC-feature catalog, skill-factory, and architect/skill-author commands moved to
 
 Pure markdown commands and agents. Hooks are self-contained Node.js with zero dependencies.
 
+## Extending the plugin
+
+Common modifications fork-ers make. None require touching `lib/` —
+all of these are surface-level changes to commands, agents, or settings.
+
+### Add a new exploration agent
+
+Exploration agents run in parallel during `/ultraplan-local` Phase 5.
+They read the codebase and contribute structured findings to plan
+synthesis.
+
+1. Copy `agents/architecture-mapper.md` as a template:
+   ```bash
+   cp agents/architecture-mapper.md agents/my-new-agent.md
+   ```
+2. Update the frontmatter `name`, `description`, `tools`, and `model`.
+   Use `sonnet` unless the agent needs deep reasoning (most don't).
+3. Add the agent to the swarm in `agents/planning-orchestrator.md`
+   Phase 5 — register it under the codebase-size bucket where it
+   should fire (always / medium+ / large only).
+4. Update the agent table in `CLAUDE.md` and `README.md` to keep the
+   doc-consistency test green:
+   ```bash
+   npm test -- tests/lib/doc-consistency.test.mjs
+   ```
+
+### Switch the planning model
+
+The default for `/ultrabrief-local`, `/ultraresearch-local`,
+`/ultraplan-local`, and `/ultraexecute-local` is `opus` (deep
+reasoning). To run on Sonnet for cost or latency, search-and-replace
+the frontmatter in three files:
+
+```bash
+sed -i.bak 's/^model: opus$/model: sonnet/' \
+  commands/ultrabrief-local.md \
+  commands/ultraresearch-local.md \
+  commands/ultraplan-local.md \
+  commands/ultraexecute-local.md
+```
+
+The exploration agents stay on Sonnet — only the orchestrator is bumped.
+
+### Disable external research
+
+`/ultraresearch-local --local` skips Tavily, Microsoft Learn, and the
+Gemini bridge. To make `--local` the default, edit the front of
+`commands/ultraresearch-local.md` Phase 1 and flip the default branch
+of the `--local` argument check. Or just always pass `--local` and
+document it in your team's CLAUDE.md.
+
+### Plugin data contract
+
+The four commands write to a single project directory (`.claude/projects/{date}-{slug}/`).
+The full schema for every artifact is in [docs/HANDOVER-CONTRACTS.md](docs/HANDOVER-CONTRACTS.md).
+That document is the single source of truth for:
+
+- File paths each command reads/writes
+- Frontmatter schema for `brief.md`, `research/*.md`, `plan.md`
+- `progress.json` schema
+- Validator → handover mapping
+- Versioning and breaking-change protocol
+
+If you fork the plugin and change the schema for any artifact, update
+that doc *and* the corresponding `lib/validators/*.mjs` *and* run
+`npm test` — the validators and doc-consistency tests will catch
+schema drift.
+
+### Disable the architect bridge
+
+`/ultraplan-local` auto-discovers `architecture/overview.md` if the
+separate `ultra-cc-architect` plugin produced one. To suppress this,
+either don't install `ultra-cc-architect`, or set `architecture/`
+absent in your project directory. Discovery is additive — missing
+file is fine, no error.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).