Kjell Tore Guttormsen 9ecd225018 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>

2026-05-01 06:28:44 +02:00

3.5 KiB

Raw Blame History

Security Policy — ultraplan-local

Reporting a vulnerability

Open a private issue on Forgejo:

https://git.fromaitochitta.com/open/ktg-plugin-marketplace

Tag it security and mark it private. Do not file public issues for unpatched vulnerabilities. There is no SLA — this is a solo-maintained plugin — but acknowledged reports are usually triaged within 7 days.

Supported versions

Only the current minor version receives security fixes. When v3.2.0 ships, v3.1.x stops receiving patches. Pin to the latest minor and update on the next bump.

Version	Supported
3.1.x	Yes
3.0.x	No (upgrade to 3.1.x)
< 3.0	No

Scope

The plugin's security posture covers:

Plugin-owned hooks (`hooks/scripts/`)

Hook	Trigger	Purpose
`pre-bash-executor.mjs`	`PreToolUse` for Bash	BLOCKs known-dangerous shell patterns; WARNs on suspicious ones; fails open on parse errors
`pre-write-executor.mjs`	`PreToolUse` for Write	BLOCKs writes to `.git/hooks/`, `~/.ssh/`, `.env`, and other sensitive paths
`pre-compact-flush.mjs`	`PreCompact`	Flushes `progress.json` from git history before compaction (P0 drift fix); read-only beyond `progress.json`
`session-title.mjs` (planned, F9)	`UserPromptSubmit`	Sets session title `ultra:<command>:<slug>` for headless multiplexing

All hooks are zero-dependency Node.js (.mjs) scripts and are designed to fail open — a hook crash never blocks the user's work. Hooks log to stderr only; they never write to user files outside their declared scope.

Prompt-level denylist (`commands/ultraexecute-local.md`)

The execute command embeds a denylist that takes effect even in headless sessions where hooks may not fire. This is layer 4 of the defense-in-depth model and protects against plan-injected destructive commands.

Validators (`lib/validators/*.mjs`)

Read-only. Never write to user files. Used both by hooks and by command phases to detect malformed artifacts before they propagate.

Out of scope

ultra-cc-architect plugin. Separate plugin with its own SECURITY.md. The architecture-discovery validator in this plugin treats architecture/overview.md as an external contract (drift-WARN, never drift-FAIL).
LLM output content. The plugin validates artifact shape, not artifact truthfulness. A plan that passes plan-validator --strict may still contain hallucinated file paths or unsafe commands; that is why pre-bash-executor exists.
The Claude Code CLI itself. Report Claude Code vulnerabilities to Anthropic via https://github.com/anthropics/claude-code/issues.

Hardening recommendations

For fork-ers handling untrusted task briefs or plans:

Set disableSkillShellExecution: true in ~/.claude/settings.json (CC v2.1.91+) to prevent Skills from invoking arbitrary shell.

Run plan validation in --strict mode before any execute:

node ${CLAUDE_PLUGIN_ROOT}/lib/validators/plan-validator.mjs --strict plan.md

Review the plan-critic adversarial output before approving plans from external sources — semantic rubric (rule #7) catches deferred decisions that an attacker could exploit.
Pin a CC version floor. v3.1.0 of this plugin assumes CC ≥ 2.1.85 for the if-field on hooks; older CC silently ignores the field, weakening the scoping.

Past advisories

None as of v3.1.0. This section will list CVE-style entries if any are discovered.

3.5 KiB Raw Blame History