wtf-p 0.5.0 → 0.6.0-rc.2

package/README.md

@@ -8,254 +8,308 @@
 
 Also: Proposal. Presentation. Poster.
 
-```bash
-npx wtf-p
-```
-
-*Academic writing commands for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Gemini CLI](https://github.com/google-gemini/gemini-cli), and [OpenCode](https://github.com/opencode-ai/opencode).*
+Portable, evidence-grounded academic workflows for modern coding agents.
 
 </div>
 
----
+WTF-P turns an AI coding agent into a structured research and writing system. It plans before drafting, grounds claims in evidence, isolates section context, delegates bounded work to specialist agents, and verifies the result against the approved plan.
 
-## What This Does
+Version `0.6.0-rc.2` is the corrective release candidate for the modernized agent platform. One canonical protocol generates native resources for Clio Coder, Claude Code, Codex, GitHub Copilot CLI, OpenCode, Antigravity CLI, and Gemini CLI; RC2 tightens decision fidelity and durable write/review/pause/resume handling after supervised local-model testing.
 
-WTF-P installs structured commands into your AI coding assistant that turn it into an academic writing system. You get spec-driven workflows, citation grounding, section isolation, and quality verification — not just "write me a paper." Every section is planned before it's written, verified after, and grounded in your actual BibTeX sources.
+## Quick start
 
----
-
-## Quick Start
+Install explicitly for the agent you use:
 
 ```bash
-npx wtf-p                  # Install commands (Claude Code by default)
+npx wtf-p@next install clio --advanced
+npx wtf-p@next install claude --advanced
+npx wtf-p@next install codex --advanced
+npx wtf-p@next install copilot --advanced
+npx wtf-p@next install opencode --advanced
+npx wtf-p@next install antigravity --advanced
+npx wtf-p@next install gemini --advanced
 ```
 
-Then in your AI assistant:
-
-```bash
-/wtfp:new-paper            # Guided interview about your research
-/wtfp:create-outline       # Build section structure + word budgets
-/wtfp:plan-section 1       # Plan first section
-/wtfp:write-section        # Write the section
-```
-
-Run `/wtfp:help` for the full command list.
-
----
+An interactive terminal can also run `npx wtf-p@next` and choose a target. A noninteractive bare invocation refuses to write anything; it requires an explicit target or scope.
 
-## Runtime Support
+Then start a paper with the native WTF-P action exposed by your client. The
+following is the slash-command form used by Clio, Claude, Copilot CLI,
+OpenCode, Antigravity, and Gemini:
 
-| Runtime | Commands | Agents | Extras |
-|---------|----------|--------|--------|
-| **Claude Code** | 36 | 11 | Skills, MCP server, plugin manifest |
-| **Gemini CLI** | 36 | 11 | — |
-| **OpenCode** | 36 | 11 | — |
-
-```bash
-npx wtf-p --global              # Claude Code (default)
-npx wtf-p --global --gemini     # Gemini CLI
-npx wtf-p --global --opencode   # OpenCode
+```text
+/wtfp:new-paper
+/wtfp:create-outline
+/wtfp:plan-section 1
+/wtfp:write-section 1
+/wtfp:review-section 1
 ```
 
----
-
-## Installation
-
-```bash
-# Default: install to Claude Code
-npx wtf-p
-
-# Global install (recommended — persists across projects)
-npx wtf-p --global
+These five lifecycle commands are deliberately unavailable in the Copilot
+cloud projection until that surface has an exact explicit-approval binding.
+
+Clio also ships flat `/wtfp-new-paper` compatibility prompts for current releases. The coordinated Clio integration discovers the preferred nested `/wtfp:new-paper` namespace; installation probes that capability in a credential-free disposable profile and falls back gracefully for legacy clients.
+
+Codex discovers all 36 stable method routes through seven native Agent Skills
+instead of a `/wtfp:*` command namespace. Twenty-four are adapter-available in the
+current adapter; the other 12 carry deterministic `WTFP_ACTION_UNAVAILABLE`
+references instead of unsupported workflow instructions. Select the owning
+plugin skill explicitly when the route must be unambiguous (for example,
+`$wtf-p:wtfp-start-project` followed by the `new-paper` request and its exact
+arguments). Existing user-level commands can take precedence over extension
+commands in clients that support both; use the client's discovery listing to
+confirm the reported source before testing a new installation.
+
+## First-class adapters
+
+| Target | Native envelope | Semantic actions: discoverable / adapter-available | Specialists | Skills | Target-specific capabilities |
+| --- | --- | ---: | ---: | ---: | --- |
+| Clio Coder | Extension | 36 / 24 (72 prompt aliases: 48 available) | 11 | 7 | Strict worker recipes; host-session tool policy for slash prompts; two explicit fleets |
+| Claude Code | Claude plugin | 36 / 24 | 11 | 7 | Native command permissions and plugin validation |
+| Codex | Codex plugin | 36 / 24 through skills | Host-managed | 7 | `.codex-plugin` metadata and marketplace packaging |
+| GitHub Copilot | Native CLI plugin plus committed cloud `.github` projection | CLI 36 / 24; cloud 36 / 5 | 11 | 7 | CLI discovery and cloud-safe prompts, agents, skills, and instructions |
+| OpenCode | Filesystem bundle | 36 / 24 | 11 | 7 | Native commands and agents |
+| Antigravity CLI | `agy` plugin | 36 / 24 | 11 | 7 | Commands converted to native skills by `agy` |
+| Gemini CLI | Gemini extension | 36 / 24 | 11 | 7 | TOML commands and extension context |
+
+Discovery counts stable action routes, including deterministic refusal stubs;
+it does not by itself establish behavioral support. Clio, Claude, Codex,
+Copilot CLI, OpenCode, Antigravity, and Gemini project 24 of the 36 canonical
+actions as adapter-available and return `WTFP_ACTION_UNAVAILABLE` for `analyze-bib`,
+`audit-milestone`, `check-refs`, `contribute`, `create-poster`,
+`create-slides`, `export-latex`, `remove-section`, `report-bug`,
+`request-feature`, `research-gap`, and `update`, because those actions lack an
+exact target binding for at least one declared capability or effect. The
+Copilot cloud projection marks only `add-todo`, `help`, `list-assumptions`,
+`map-project`, and `pause-writing`; it refuses the other 31 because it also
+lacks an exact explicit-approval binding. Each generated target records its
+machine-readable result in `compatibility/action-availability.json`.
+
+An available action has complete semantic capability, effect, and approval
+bindings; that is not automatically an action-scoped host tool allowlist.
+Clio 0.3.8 prompt templates expand into an ordinary main-agent turn and retain
+the session tool surface. The Clio manifest records this as
+`hostToolEnforcement.actionScoped: false`. Use `read-only` for previews or
+supervised `suggest` autonomy for mutations, and deny and stop on any tool call
+outside the action contract. A run under `auto-edit` cannot earn WTF-P's
+no-undeclared-tool safety result merely because the generated prompt told the
+model not to use shell.
+
+The adapters are generated artifacts, not seven hand-maintained copies. Every generated envelope includes a cryptographic inventory and the portable protocol resources needed to understand its workflows. Copilot additionally receives a generated, commit-ready `.github` projection for cloud/repository use.
+
+For a GitHub-hosted Copilot coding agent, review and copy the `.github/` tree from `vendors/copilot/project/` in the release archive into the target repository, then commit it through that repository's normal review process. The user-level `install copilot` command configures the CLI plugin; it deliberately does not write into an unrelated project checkout.
+
+The release-candidate native-discovery matrix was exercised with Claude Code
+2.1.251, Codex CLI 0.144.1, Copilot CLI 1.0.80, OpenCode 1.18.16,
+Antigravity 1.1.22, Gemini CLI 0.57.0, and Clio Coder 0.3.8 at merged
+commit `9b7b80cc`. Real isolated `new-paper` evaluations used Claude Sonnet
+5/xhigh, Codex GPT-5.4/xhigh (GPT-5.6 was unavailable through that CLI's
+ChatGPT-auth route), and Clio GPT-5.6 Terra/xhigh. The compiler-v4 Clio rerun
+earned 8/8 with independent validation of all five previewed records. The
+broader paid routing matrix, full lifecycle chain, and cross-version baseline
+remain separate evidence gates. See [compatibility evidence](docs/COMPATIBILITY.md)
+for exact claims and caveats. WTF-P `0.6.0-rc.1` was published to npm under
+the `next` tag on 2026-08-29; each later candidate remains a separate operator
+publication action.
+
+The first retained local-model lifecycle reading used Clio 0.3.8 with
+`dynamo/qwen3.8-27b`. Both native fleet contracts validated, but the lifecycle
+did not pass: high effort timed out before writing, and an effort-off retry
+stopped after `new-paper` because the model attempted a denied shell call and
+made 5,600 section words disagree with the 6,000-word outline target. The five
+records were individually schema-valid. See the
+[blocked evidence](evaluation/v1/evidence/clio-dynamo-lifecycle-blocked/README.md);
+the remaining lifecycle and routing roadmap items stay open. That reading
+binds the earlier WTF-P source `6b58b298`; it predates later remediation for
+exact outline totals and direct-tool use, and is not a behavioral reading of
+the later source revisions.
+
+Later post-remediation readings are retained separately because they bind
+different WTF-P commits. At `0245818`, exact `/wtfp:new-paper` arguments arrived
+but the model listed excluded `.git` metadata, read an absolute host Clio
+documentation path, looped on agent discovery, and produced no planning
+records. Those accesses were read-only; zero mutating and network effects were
+applied. At `b4f0543`, the plan/check fleet completed structurally but its
+semantic checks were ungrounded. The `cbba38c` manuscript-path projection
+observation placed draft/review manuscript and summary files in the correct
+roots with no boundary violation, but drafted without the required approved
+plan, left portable state unreconciled, and failed its word target. See the
+[retained RC readings](evaluation/v1/evidence/clio-dynamo-rc-readings/README.md).
+Neither the full lifecycle nor a semantic fleet pass is claimed.
+
+A final current-source Dynamo reading at `bf50e23` created exactly five
+initialization records and passed literal schema validation 5/5. It still
+failed the release gate: the outline placed a dependency in the same wave, and
+the model made three successful shell calls plus ten denied shell retries
+despite an explicit no-shell policy. The operator stopped the run before
+`map-project`; no terminal receipt or trustworthy numeric cost exists. See the
+[current-source blocked evidence](evaluation/v1/evidence/clio-dynamo-current-source-blocked/README.md).
+
+The later operator-observed NSF 25-531 toy UAT used Clio Coder 0.3.8 and
+Dynamo `qwen3.8-27b-dynamo` with thinking off in a disposable offline profile.
+It continued an already mapped fixture through outline, discussion, plan,
+write, review, and durable pause for one section during defect-finding before
+the final RC2 write/review/pause hardening. The provisional section's persisted
+writer/state count was 1,019 whitespace-delimited words; the independent
+reviewer used a different tokenizer and counted 1,026. Its review retained four
+author-accepted warning items, and 25/25 portable JSON records passed
+independent schema validation.
+The first genuinely fresh-process resume attempt did not pass: the pre-
+hardening workflow skipped required durable reads and the author gate and
+described mutations that never occurred. With the regenerated RC2 bundle, a
+new process read the durable records, invoked the real Clio `ask_user`
+interview, waited for the author choice, resolved the checkpoint, advanced
+state to revision 7/active while preserving phase `reviewing`, and read both
+records back; independent validation remained 25/25. This is a corrected
+one-section resumption observation, not an end-to-end rerun of the final RC2
+write/review/pause contracts, full proposal, completed research, submission-
+readiness, safety-certification, or improved-writing claim. The final contracts
+have deterministic regression evidence; only resume/progress received the
+post-hardening model rerun.
+
+## The paper lifecycle
+
+WTF-P keeps the human in control while making the repeatable work deterministic:
+
+1. `/wtfp:new-paper` captures research questions, intended contribution, evidence, audience, venue, and constraints.
+2. `/wtfp:map-project` indexes existing drafts, sources, data, figures, and decisions.
+3. `/wtfp:create-outline` turns the argument into sections, dependencies, and word budgets.
+4. `/wtfp:research-gap` and `/wtfp:analyze-bib` define the canonical research methods, but current adapters return `WTFP_ACTION_UNAVAILABLE` until exact logical-tool bindings exist. Available project actions can map supplied sources; placeholders must never be represented as completed research.
+5. `/wtfp:plan-section` creates a traceable section plan and can send it through an independent plan checker.
+6. `/wtfp:write-section` drafts from the approved plan in bounded context.
+7. `/wtfp:review-section`, `/wtfp:verify-work`, and `/wtfp:polish-prose` check argument coverage, evidence, coherence, venue requirements, and prose quality.
+8. `/wtfp:audit-milestone`, `/wtfp:export-latex`, `/wtfp:create-slides`, and `/wtfp:create-poster` prepare deliverables.
+
+Use the native help route—`/wtfp:help` on slash-command clients—to inspect all
+36 stable action contracts. Executable availability is target-specific and
+recorded in the generated compatibility manifest.
+
+## What became portable
+
+The canonical source lives under `protocol/` and has four parts:
+
+- A versioned `.planning` project protocol with 11 JSON schemas and ten templates for the project manifest, configuration, state, sources, evidence, decisions, outline, sections, checkpoints, and validation results.
+- Seven standard Agent Skills for starting a project, literature research, section planning, section writing, manuscript review, project management, and research delivery.
+- Thirty-six semantic action contracts declaring inputs, reads, outputs, specialist delegation, tools, effects, and approval boundaries.
+- Eleven host-neutral specialist roles with strict mutation or verification result contracts.
+
+Concrete model names and client tool syntax do not live in canonical workflow prose. Each adapter maps semantic needs such as filesystem access, research search, user interaction, and delegation into the active client's capabilities.
+
+## Project state
+
+New workflows use a versioned `.planning/` directory. Its records are JSON-schema validated and designed to survive movement between clients:
+
+```text
+.planning/
+├── project.json
+├── config.json
+├── state.json
+├── decisions.json
+├── structure/outline.json
+├── sources/*.json
+├── evidence/*.json
+├── sections/*/section.json
+├── checkpoints/*.json
+└── validations/*.json
+```
 
-# Local to current project only
-npx wtf-p --local
+The protocol records evidence separately from prose and records author decisions explicitly. That lets a reviewer trace a claim back to a source and lets a different agent resume without guessing what the author intended.
 
-# Specify a custom config directory
-npx wtf-p --global --config-dir ~/research/.claude
+## Installation safety
 
-# Check what's installed
-npx wtf-p status
+The `0.6` installer is an ownership-aware transaction engine:
 
-# Diagnose issues
-npx wtf-p doctor
-```
+- It rejects filesystem roots, the home directory itself, the repository root, traversal, and symlink escapes.
+- It snapshots package sources and refuses source or destination path races.
+- It publishes files atomically where possible and rolls back a failed transaction.
+- It compensates native marketplace/plugin registration if a later activation step fails.
+- It does not register a partial adapter when any conflicting file was preserved.
+- It records only files it actually wrote, with SHA-256 hashes, adapter-contract v1, and generator-v4 metadata, in a v2 receipt.
+- Reinstallation cannot claim ownership of files it skipped.
+- Uninstall removes exact unchanged owned files. It preserves modified files and unrelated siblings by default.
+- Dry runs are byte-preserving.
 
-### Upgrading
+Use a custom isolated client root when evaluating an adapter:
 
 ```bash
-npx wtf-p update                    # Check for newer version
-npx wtf-p --global                  # Reinstall (prompts on conflicts)
-npx wtf-p --global --force          # Overwrite everything
-npx wtf-p --global --backup-all    # Backup before overwriting
+CODEX_HOME=/tmp/wtfp-codex npx wtf-p install codex --advanced
+CLIO_CODER_CONFIG_DIR=/tmp/wtfp-clio npx wtf-p install clio --advanced
 ```
 
-### Uninstalling
+Inspect or remove an installation with:
 
 ```bash
-npx wtf-p-uninstall --global
-npx wtf-p-uninstall --global --dry-run   # Preview what would be removed
-```
-
-Only WTF-P files are removed. Your config files and other tools stay intact.
-
----
-
-## Command Reference
-
-### Setup
-
-| Command | Purpose |
-|---------|---------|
-| `/wtfp:new-paper` | Guided interview to define your paper's vision and requirements |
-| `/wtfp:create-outline` | Build section structure, argument map, and word budgets |
-| `/wtfp:map-project` | Index existing drafts, data, and references |
-| `/wtfp:analyze-bib` | Analyze bibliography and map citations to sections |
-
-### Planning
-
-| Command | Purpose |
-|---------|---------|
-| `/wtfp:discuss-section [N]` | Discuss your vision for a section before planning |
-| `/wtfp:plan-section [N]` | Create detailed writing plan with quality validation |
-| `/wtfp:list-assumptions [N]` | Preview intended approach before writing |
-| `/wtfp:research-gap [N]` | Research literature for a section (tiered: Semantic Scholar, Google Scholar, CrossRef) |
-
-### Writing
-
-| Command | Purpose |
-|---------|---------|
-| `/wtfp:write-section` | Execute a section plan with agent-based writing |
-| `/wtfp:execute-outline` | Write all sections in parallel, then check coherence |
-| `/wtfp:quick` | Minimal-ceremony writing for quick tasks |
-| `/wtfp:progress` | Show writing progress and suggest next step |
-| `/wtfp:pause-writing` | Save current progress for later |
-| `/wtfp:resume-writing` | Resume from a previous session |
-
-### Review
-
-| Command | Purpose |
-|---------|---------|
-| `/wtfp:review-section [N]` | Review for citations, coherence, and venue requirements |
-| `/wtfp:verify-work [N]` | Acceptance-test a section against its plan |
-| `/wtfp:plan-revision [N]` | Create revision plan from review issues |
-| `/wtfp:polish-prose` | Improve clarity, flow, and academic voice |
-| `/wtfp:check-refs` | Audit BibTeX for missing, duplicate, or broken references |
-
-### Structure
-
-| Command | Purpose |
-|---------|---------|
-| `/wtfp:create-poster` | Full poster creation workflow |
-| `/wtfp:create-slides` | Presentation deck workflow |
-| `/wtfp:insert-section` | Add a new section to the outline |
-| `/wtfp:remove-section` | Remove a section from the outline |
-
-### Export & Submission
-
-| Command | Purpose |
-|---------|---------|
-| `/wtfp:export-latex` | Export to LaTeX with bibliography and formatting |
-| `/wtfp:audit-milestone` | Pre-submission checks on sections, citations, and word counts |
-| `/wtfp:plan-milestone-gaps` | Create fix plans for gaps found by audit |
-| `/wtfp:submit-milestone` | Archive a completed draft or submission version |
-
-### Settings & Productivity
-
-| Command | Purpose |
-|---------|---------|
-| `/wtfp:settings` | View and edit project settings interactively |
-| `/wtfp:checkpoint` | Save, restore, and list paper state checkpoints |
-| `/wtfp:add-todo` | Capture a quick note or task without breaking flow |
-| `/wtfp:check-todos` | Review pending todos (act, defer, dismiss) |
-| `/wtfp:update` | Check for updates and install newer version |
-
-### Help & Contributing
-
-| Command | Purpose |
-|---------|---------|
-| `/wtfp:help` | Full command reference |
-| `/wtfp:report-bug` | Report a bug via GitHub issue |
-| `/wtfp:request-feature` | Request a new feature via GitHub issue |
-| `/wtfp:contribute` | Walk through contributing code via pull request |
-
----
-
-## Configuration
-
-WTF-P uses a `config.json` in your `.planning/` directory. Key settings:
-
-```jsonc
-{
-  "model_profile": "balanced",        // "quality" | "balanced" | "budget"
-  "workflow": {
-    "research": true,                  // Enable research phase
-    "plan_check": true,                // Pre-write plan validation
-    "verifier": true                   // Post-write verification
-  },
-  "parallelization": {
-    "enabled": false,                  // Parallel section writing
-    "max_concurrent_agents": 3
-  }
-}
+npx wtf-p status
+npx wtf-p doctor
+npx wtf-p uninstall --clio --dry-run
+npx wtf-p uninstall --clio --yes
 ```
 
-**Model profiles** route 11 specialized agents to appropriate models:
-- **quality** — best models for all agents (slower, higher cost)
-- **balanced** — strong models for writing, lighter for validation (default)
-- **budget** — fastest models everywhere (good for iteration)
-
----
-
-## Venue Templates
-
-| Template | Structure |
-|----------|-----------|
-| `acm-cs` | Intro → Background → Approach → Evaluation → Related Work → Conclusion |
-| `ieee-cs` | Intro → Background → Design → Implementation → Evaluation → Conclusion |
-| `arxiv-ml` | Intro → Related Work → Preliminaries → Method → Experiments → Conclusion |
-| `nature` | Intro → Methods → Results → Discussion |
-| `thesis` | Flexible chapter structure |
+The legacy `--global`, `--local`, `--claude`, `--gemini`, and `--opencode` selectors remain compatibility aliases during the release-candidate cycle.
 
----
+## Developing adapters
 
-## How It Works
-
-WTF-P follows a **thin orchestrator → specialized agent → quality loop** architecture:
-
-1. **Specification first** — `/wtfp:new-paper` interviews you to extract research questions, argument structure, evidence inventory, and venue requirements into a `PROJECT.md`.
-2. **Hierarchical planning** — Papers break down: Paper Vision → Section Outline → Section Plan → Paragraph Execution. Each level has its own document.
-3. **Isolated execution** — Each section is written in a fresh context containing only the paper vision, that section's plan, relevant citations, and prior sections. No context pollution.
-4. **Quality loops** — Pre-write plan validation (7 dimensions, up to 3 revisions) and post-write goal-backward verification ensure claims match plans and evidence.
-
-### WCN Mode (Reduced Tokens)
-
-For smaller models or limited context windows, WTF-P includes compressed workflows with 35-50% token reduction:
+Edit canonical resources under `protocol/`, then regenerate every native projection:
 
 ```bash
-./tools/wcn/swap-workflows.sh wcn      # Switch to compressed
-./tools/wcn/swap-workflows.sh verbose   # Switch back
+npm run build:adapters
+npm run check:adapters
+npm test
+npm run test:integration
 ```
 
----
+`check:adapters` fails when committed generated resources drift from their canonical inputs. The test suite also checks action parity, skills, portable roles, `.planning` schemas, resource containment, exact installer ownership, rollback, uninstall preservation, and native envelope structure.
+
+The Clio reference integration is merged into Clio Coder `v0.3.8` at
+`9b7b80cc`. It adds recursive namespaced extension prompts, extension-owned
+agents and fleets, same-extension skill binding, contained `${extensionRoot}`
+resource resolution, exact operator-argument preservation, preservation of
+nested template `state.json` resources, and extension-aware fleet preflight.
+Effective package discovery certifies 72 prompts (36 nested and 36 flat), 11
+agents, seven skills, two fleets, and zero diagnostics. Of those prompts, 48
+aliases represent 24 adapter-available semantic actions and 24 aliases are the nested
+and flat forms of 12 deterministic refusal routes. WTF-P capability-probes that
+surface because Clio currently records, but does not enforce,
+`compatibility.clio`. The generated fleet contracts use directory boundaries
+(`.planning/` and `paper/`) so nested writes are authorized without broadening
+the worker sandbox.
+
+The two Clio fleets are operator-invoked native primitives, not implicit
+routes behind `/wtfp:*`. Use
+`clio-coder fleet run wtfp-plan-section --var section=<id>` or
+`clio-coder fleet run wtfp-draft-review --var section=<id>` when their narrower
+specialist contracts are appropriate; the slash-command orchestrator remains
+responsible for approval and portable-state reconciliation around those worker
+steps.
+
+## Design principles
+
+- Evidence before eloquence: a fluent paragraph is not a substitute for a supported claim.
+- Specification before drafting: author intent and acceptance criteria remain explicit.
+- Portable semantics, native ergonomics: share the method while respecting each client's real plugin model.
+- Bounded delegation: specialists receive the minimum context and authority their task requires.
+- Human approval at consequential boundaries: deletion, commits, merges, package updates, and external issue creation remain explicit effects.
+- Reversible installation: WTF-P never treats an agent's whole configuration directory as its property.
 
 ## Origin
 
-Built at the [Gnosis Research Center](https://www.intelli-gnosis.com/) at Illinois Tech. The problem: research teams with grants to win, papers to publish, and no time for writer's block. The solution: treat your AI coding assistant as a structured writing system — proper context, explicit specs, verification layers.
-
----
+WTF-P was built at the [Gnosis Research Center](https://grc.iit.edu/) at Illinois Tech for research teams with papers to publish, grants to win, and no time for writer's block.
 
 ## Links
 
 - [Changelog](CHANGELOG.md)
+- [Modernization architecture](docs/agent-platform-modernization.md)
+- [Compatibility evidence](docs/COMPATIBILITY.md)
+- [Behavioral evaluation methodology](evaluation/README.md)
+- [Tool execution and MCP decision](docs/adr/0001-hybrid-tool-execution.md)
+- [v0.5 → v0.6 migration guide](docs/MIGRATION_V05_TO_V06.md)
+- [Build and release](docs/BUILD_AND_RELEASE.md)
 - [Contributing](CONTRIBUTING.md)
 - [Roadmap](ROADMAP.md)
-- [License](LICENSE) (MIT)
+- [License](LICENSE)
 - [GitHub](https://github.com/akougkas/wtf-p)
 
----
-
 <div align="center">
-<br>
-<strong>No more excuses. Ship the paper.</strong>
+
+**No more excuses. Ship the paper.**
+
 </div>

package/bin/commands/doctor.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { getClaudeDir, normalizePath, getPathLabel, detectInstallation } = require('../lib/utils');
+const { assertSafeTarget } = require('../lib/ownership');
 
 async function runDoctor(options) {
   const { out, explicitConfigDir } = options;
@@ -22,7 +23,7 @@ async function runDoctor(options) {
   }
 
   // Check 2: Claude directory exists
-  const globalDir = getClaudeDir(explicitConfigDir, true);
+  const globalDir = assertSafeTarget(getClaudeDir(explicitConfigDir, true)).path;
   if (fs.existsSync(globalDir)) {
     checks.push({ name: 'Claude config directory', status: 'pass', detail: getPathLabel(globalDir, true) });
   } else {
@@ -30,20 +31,38 @@ async function runDoctor(options) {
   }
 
   // Check 3: Write permissions
-  const testDir = globalDir.replace(/\.claude$/, '.claude-test-' + Date.now());
+  let testRoot = globalDir;
+  while (!fs.existsSync(testRoot)) {
+    const parent = path.dirname(testRoot);
+    if (parent === testRoot) break;
+    testRoot = parent;
+  }
+  let testDir = null;
   try {
-    fs.mkdirSync(testDir, { recursive: true });
+    testDir = fs.mkdtempSync(path.join(testRoot, '.wtfp-doctor-'));
     fs.writeFileSync(path.join(testDir, 'test'), 'test');
-    fs.rmSync(testDir, { recursive: true });
+    fs.unlinkSync(path.join(testDir, 'test'));
+    fs.rmdirSync(testDir);
+    testDir = null;
     checks.push({ name: 'Write permissions', status: 'pass', detail: 'Can write to config directory' });
   } catch (err) {
     issues.push(`Cannot write to ${getPathLabel(globalDir, true)}: ${err.message}`);
     checks.push({ name: 'Write permissions', status: 'fail', detail: err.message });
+  } finally {
+    if (testDir && fs.existsSync(testDir)) {
+      try {
+        const testFile = path.join(testDir, 'test');
+        if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
+        if (fs.readdirSync(testDir).length === 0) fs.rmdirSync(testDir);
+      } catch {
+        // Leave an exact diagnostic temp directory rather than broadening cleanup.
+      }
+    }
   }
 
   // Check 4: Installation state
   const detection = detectInstallation(globalDir);
-  if (detection.hasCommands || detection.hasWorkflows || detection.hasSkills) {
+  if (detection.hasAny) {
     if (detection.partial) {
       issues.push('Partial installation detected - some files are missing');
       checks.push({ name: 'Installation integrity', status: 'warn', detail: 'Partial install' });
@@ -59,7 +78,9 @@ async function runDoctor(options) {
 
   // Check 5: CLAUDE_CONFIG_DIR env var
   const configDirEnv = process.env.CLAUDE_CONFIG_DIR;
-  if (configDirEnv) {
+  if (explicitConfigDir) {
+    checks.push({ name: 'Config directory source', status: 'pass', detail: '--config-dir override' });
+  } else if (configDirEnv) {
     const expanded = normalizePath(configDirEnv);
     if (fs.existsSync(expanded)) {
       checks.push({ name: 'CLAUDE_CONFIG_DIR', status: 'pass', detail: expanded });
@@ -144,11 +165,11 @@ async function runDoctor(options) {
   }
 
   // Check 7: Dual-installation conflict (global + local both present)
-  const localDir = path.join(process.cwd(), '.claude');
+  const localDir = assertSafeTarget(getClaudeDir(null, false)).path;
   if (localDir !== globalDir) {
     const localDetection = detectInstallation(localDir);
-    if (localDetection.hasCommands && detection.hasCommands) {
-      issues.push('WTF-P is installed both globally and locally — commands will appear twice');
+    if (localDetection.hasAny && detection.hasAny) {
+      issues.push('WTF-P is installed both globally and locally — resources may appear more than once');
       checks.push({
         name: 'Dual installation',
         status: 'warn',