feat: inspect role — reference study via a headless REA session (1.33.0)

[choiyounggi]

What

A new capability role, inspect, lets a plan study how an existing product behaves (a reference study) when a feature mirrors it, and brings the result into the pipeline as behavior rows: what the original does, which tool and evidence id saw it, what stayed unknown. Source to copy is never the output.

The default path needs nothing installed or registered. scripts/reference-study.sh starts a headless claude -p session whose only MCP server is the pinned REA (rea-agents@6.5.0, Reverse Engineer Anything), with:

• --mcp-config + --strict-mcp-config, compact schema profile; REA lives and dies with the study's process group
• cwd = the trail dir (<checkout>/.claude/tmp/reference/<slug>/ when .claude/tmp is git-ignored, else --out), --permission-mode acceptEdits, --permission-prompts none, --setting-sources "", Read allowed only for the trail dir and the licence page, Bash denied
• a strict seven-line report contract: the reply is validated (row count against rows.md, no fenced block, no logged ## Fingerprints entry inside the rows), the two path lines are the script's own, invalid replies exit 4
• one study per product: brief checksum, lock, script-owned files in <trail>.run/, planted memory files removed before each run

Pipeline hooks: orchestrate Phase 2 runs the study before Gate 1 (reference-study risk signal, floor R2, licence outcome on the Gate 1 table); the task-analyst receives the rows file as a pointer file and never the tool; the Phase 4 reviewer greps the diff against the trail's fingerprints. wiki-plan A3 and templates/analysis.md carry the same ### Reference study block. A self-registered inspection MCP keeps the fresh-context general-purpose Agent path.

Wiki: qa/exploratory/behavioral-spec-from-a-reference-product.md (what to record, what may enter the repo, licence table as an engineering checklist, not legal advice) and infrastructure/agent-orchestration/reference-study-in-a-plan.md (who runs the study, where artifacts live, risk/brief/review). Supply-chain page: edge row for viral-repo impersonation.

Why

Issue-shaped goals increasingly say "like product X does". Without a contract, the study either does not happen or its captures and pseudocode land in the planner's context and then in the repository. This makes the study a bounded, reviewable step with a clean-room wall that is stated as a convention enforced by the review grep, not as a guarantee.

Verification

• PATH=/opt/homebrew/bin:$PATH bats tests/ on the final tree: see the suite line in the last commit message / CI
• node scripts/wiki-structure-checks.js wiki → findings 0; node scripts/wiki-lint-prohibitions.js → violations 0 (directives 85)
• Real runs of scripts/reference-study.sh from inside a Claude Code session (2.1.300): REA connected (207 tools), list_browser_targets answered, zero permission denials; a negative probe with the same flags: Read/Write/Grep outside the trail dir denied and listed in permission_denials
• REA vetted at commit d69acc3 / npm 6.5.0: MIT, no lifecycle scripts, no telemetry, only hopperapp.com as a non-target host behind --install-hopper
• Reviews: one general and one adversarial pass on the first design (redesigned: fresh-context study, artifacts outside the tree), then one general and one adversarial pass on the script (fixed: scoped reads, report validation, run dir split, process-group kill, checksum/lock, --out guards)

Release

Version 1.33.0 in both manifests. After merge: confirm the tag, let sync-dev-loop-pin move the groundwork pin, then /plugin marketplace update groundwork and /plugin update dev-loop@groundwork.

🤖 Generated with Claude Code

https://claude.ai/code/session_018FPHjM5Pd1ZPUd3SxSCf5x