@pennyfarthing/core 10.0.1 → 10.0.3

package/README.md

@@ -0,0 +1,287 @@
+# Pennyfarthing
+
+**v10.0.3** | *The outer loop goes once, the inner loop goes many times.*
+
+<img src="pennyfarthing.png" alt="Pennyfarthing Logo" width="75" style="float:left; margin:10px">
+
+A Claude Code agent orchestration framework built around three pillars: a flexible development platform, scientific personality research, and streamlined integrations.
+
+---
+
+## What is Pennyfarthing?
+
+### 1. Development Platform
+
+A multi-agent system with customizable BikeLane workflows for structured software development:
+
+- **10 Coordinated Agents** - SM, TEA, Dev, Reviewer, Architect, PM, Tech Writer, UX Designer, DevOps, Orchestrator
+- **8 BikeLane Workflows** - Phased (TDD, BDD, Trivial), Stepped (Architecture, Release, Git Cleanup)
+- **49 Slash Commands** - Entry points for agent activation and workflows
+- **22 Skills** - Reusable knowledge domains (testing, code-review, jira, mermaid, etc.)
+- **Prime Context System** - Tiered context injection assembles agent definition, persona, session state, and sidecar memory
+- **Automatic Handoffs** - Context-aware agent transitions via subagent delegation
+- **Agent Sidecars** - Persistent learning files where agents record patterns, gotchas, and decisions across stories
+
+### 2. Personality Research
+
+A scientific study of how strong personalities affect AI agent behavior:
+
+- **OCEAN Profiling** - Big Five personality scores for every character
+- **TRAIL Framework** - Categorizing errors (reasoning, planning, execution) and correlating with personality
+- **Benchmarking System** - `/solo`, `/benchmark-control`, `/benchmark` for statistical evaluation
+- **JobFair** - Discovering which characters excel at roles beyond their native specialization
+
+The 97 persona themes (Discworld, Star Trek, Breaking Bad, etc.) are instruments of inquiry, not decoration. Early findings show character expertise often trumps abstract personality scores.
+
+### 3. Integration & Tooling
+
+- **Cyclist Visual Terminal** - Electron-based IDE with 15 draggable Dockview panels, agent portraits, tool visualization, and workflow controls
+- **Jira Integration** - Bidirectional sync, epic auto-creation, sprint velocity
+- **Sprint Management** - Story tracking with `current-sprint.yaml`
+
+---
+
+### [**Explore the Research Showcase**](https://animated-meme-3e4494y.pages.github.io/)
+
+97 themes with OCEAN spider charts, benchmark tiers, and character profiles.
+
+---
+
+## Quick Start
+
+```bash
+cd your-project
+
+# Install CLI
+npm install --save-dev @pennyfarthing/core
+
+# Initialize (creates symlinks)
+npx pennyfarthing init
+
+# Verify installation
+npx pennyfarthing doctor
+
+# Start working (in Claude Code)
+/new-work
+```
+
+### Optional: Visual Terminal
+
+```bash
+# Install Cyclist (includes portraits)
+npm install --save-dev @pennyfarthing/cyclist
+
+# Launch
+npx pennyfarthing cyclist
+```
+
+## Cyclist Visual Terminal
+
+Cyclist is an Electron-based IDE built on React 19, Tailwind v4, and Dockview. It wraps Claude Code with a rich panel system and workflow controls.
+
+### Panels
+
+All panels are draggable, floatable, and splittable:
+
+| Panel | Purpose |
+|-------|---------|
+| **Message** | Conversation stream (always visible) |
+| **Sprint** | Current sprint stories and progress |
+| **Progress** | TDD/BDD phase visualization |
+| **BikeLane** | Stepped workflow state and navigation |
+| **Acceptance Criteria** | Story ACs with pass/fail tracking |
+| **Changed** | Files added or modified during the session |
+| **Diffs** | Git-based diff viewer for current changes |
+| **Git** | Branch management and git operations |
+| **Todo** | Task list tracking |
+| **Audit Log** | Timestamped action history |
+| **Settings** | Permission mode, relay mode, bell mode toggles |
+| **Debug** | Prime context inspection with token counts |
+| **Background** | Background job monitoring |
+| **TTY** | Integrated terminal |
+| **Workflow** | Workflow navigation and status |
+
+### Tool Visualization
+
+Cyclist renders tool use as human-readable summaries instead of raw JSON. Consecutive identical tool calls are stacked, and results are collapsible.
+
+### Workflow Modes
+
+| Mode | Description |
+|------|-------------|
+| **Permission Mode** | `plan` / `manual` / `accept` — controls how much Claude can do without approval |
+| **Relay Mode** | Automatic agent handoffs — detects `CYCLIST:HANDOFF` markers and runs the next agent |
+| **Bell Mode** | Queue messages while Claude works — injected at next tool execution via hooks |
+
+### Agent Portraits
+
+Each of the 97 persona characters has a unique portrait displayed in the conversation stream, making multi-agent workflows visually distinct.
+
+## Prime Context System
+
+Prime assembles the full agent context at activation: agent definition, persona character, behavior guide, sprint state, active session, and sidecar memory. This is injected via `--append-system-prompt` so agents behave identically whether launched from Cyclist or the CLI.
+
+Prime uses **tiered injection** to manage token overhead:
+
+| Tier | Tokens | When |
+|------|--------|------|
+| **Full** | ~4000 | New session or new agent |
+| **Refresh** | ~2000 | Same agent, stale context |
+| **Handoff** | ~1000 | Agent-to-agent transition |
+| **Minimal** | ~200 | Deep in same agent session |
+
+## Agent Sidecars
+
+Sidecars are persistent learning files where agents record what they discover during story work. Each agent maintains three files in `.pennyfarthing/sidecars/`:
+
+- **`{agent}-patterns.md`** — Strategies and patterns that worked
+- **`{agent}-gotchas.md`** — Mistakes and edge cases to avoid
+- **`{agent}-decisions.md`** — Architecture decisions and rationale
+
+Agents write to sidecars before every handoff. Prime loads them on activation, so agents build on previous experience instead of rediscovering the same issues.
+
+## BikeLane Workflows
+
+BikeLane is the umbrella workflow system supporting two types:
+
+| Type | Description | Examples |
+|------|-------------|----------|
+| **Phased** | Agent-driven with automatic handoffs | tdd, bdd, trivial, agent-docs |
+| **Stepped** | Progressive disclosure with user gates | architecture, release, git-cleanup |
+
+### Example: TDD Workflow (Phased)
+
+| Agent | Role | Phase |
+|-------|------|-------|
+| **SM** | Scrum Master | Story selection, session setup, completion |
+| **TEA** | Test Engineer | Write failing tests (RED) |
+| **Dev** | Developer | Make tests pass (GREEN) |
+| **Reviewer** | Code Reviewer | Quality validation, approve/reject |
+
+Use `/workflow list` to see all workflows. Use `/workflow start <name>` to begin any stepped workflow.
+
+## Benchmarking & Personality Research
+
+Pennyfarthing includes a scientific benchmarking system for evaluating how personality affects agent performance:
+
+```bash
+# Run a single agent on a scenario
+/solo theme:agent --scenario cache-invalidation
+
+# Create a control baseline (10 runs)
+/benchmark-control reviewer --scenario order-service
+
+# Compare persona vs control with statistics
+/benchmark breaking-bad reviewer --scenario order-service
+```
+
+**Key Findings:**
+- Cohen's d effect sizes measure performance differences
+- Multivariate OCEAN patterns predict better than individual traits
+- Character expertise often trumps abstract personality scores
+- The "Stoic Analyst" profile (Low O + High C + Low E + Low N) excels at code review
+
+See [Benchmarking Documentation](docs/BENCHMARKING.md) for methodology.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `pennyfarthing init` | Initialize in a project |
+| `pennyfarthing update` | Update to latest version |
+| `pennyfarthing doctor` | Check installation health |
+| `pennyfarthing doctor --fix` | Auto-fix common issues |
+| `pennyfarthing uninstall` | Remove for clean reinstall |
+| `pennyfarthing theme list` | Show available themes |
+| `pennyfarthing theme set <name>` | Change active theme |
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [**User Guide**](docs/USER-GUIDE.md) | Complete documentation |
+| [Getting Started](docs/GETTING-STARTED.md) | Quick start guide |
+| [Workflow Diagrams](docs/WORKFLOW-DIAGRAMS.md) | Visual Mermaid diagrams for all workflows |
+| [BikeLane](docs/BIKELANE.md) | Workflow system architecture |
+| [Agents](docs/AGENTS.md) | Agent reference |
+| [Commands](docs/COMMANDS.md) | Slash command reference |
+| [Benchmarking](docs/BENCHMARKING.md) | Scientific persona evaluation |
+| [Jira Integration](docs/JIRA-INTEGRATION.md) | Jira CLI and sprint sync |
+| [Cyclist](docs/CYCLIST.md) | Visual terminal documentation |
+
+## Available Themes (97)
+
+Core includes 26 themes. Optional theme packs add 98 more across 7 packages:
+
+| Package | Themes | Examples |
+|---------|--------|----------|
+| `@pennyfarthing/core` (included) | 26 | `the-expanse`, `star-trek-tng`, `breaking-bad`, `discworld`, `game-of-thrones` |
+| `@pennyfarthing/themes-prestige-tv` | 17 | `succession`, `the-wire`, `mad-men`, `fargo`, `the-sopranos` |
+| `@pennyfarthing/themes-literary` | 15 | `shakespeare`, `jane-austen`, `sherlock-holmes`, `1984`, `great-gatsby` |
+| `@pennyfarthing/themes-realistic` | 14 | `ancient-philosophers`, `jazz-legends`, `film-auteurs`, `software-pioneers` |
+| `@pennyfarthing/themes-comedy` | 9 | `the-office`, `parks-and-rec`, `ted-lasso`, `monty-python`, `futurama` |
+| `@pennyfarthing/themes-scifi` | 8 | `foundation`, `snow-crash`, `neuromancer`, `babylon-5` |
+| `@pennyfarthing/themes-mythology-fantasy` | 4 | `greek-mythology`, `norse-mythology`, `his-dark-materials`, `the-witcher` |
+| `@pennyfarthing/themes-superheroes` | 4 | `marvel-mcu`, `avatar-the-last-airbender`, `legion-of-doom` |
+
+All themes include OCEAN (Big Five) personality profiles. See [Theme Comparison](docs/THEME-COMPARISON.md) for personality analysis.
+
+### Installing Theme Packs
+
+```bash
+# Install individual packs
+npm install --save-dev @pennyfarthing/themes-prestige-tv
+
+# Or install all theme packs at once
+npm install --save-dev @pennyfarthing/themes-{comedy,literary,mythology-fantasy,prestige-tv,realistic,scifi,superheroes}
+```
+
+Configure in `.pennyfarthing/config.local.yaml`:
+```yaml
+theme: the-expanse
+```
+
+## Directory Structure
+
+After initialization:
+
+```
+your-project/
+├── .pennyfarthing/
+│   ├── agents/               # → symlink to @pennyfarthing/core
+│   ├── guides/               # → symlink to @pennyfarthing/core
+│   ├── personas/             # → symlink to @pennyfarthing/core
+│   ├── scripts/              # → symlink to @pennyfarthing/core
+│   ├── workflows/            # → symlink to @pennyfarthing/core
+│   ├── sidecars/             # Agent learning files (local, writable)
+│   ├── settings.local.json   # Claude Code settings
+│   └── config.local.yaml     # Theme selection
+├── .claude/
+│   ├── commands/             # → symlinks for Claude Code discovery
+│   └── skills/               # → symlinks for Claude Code discovery
+├── sprint/
+│   ├── current-sprint.yaml   # Active sprint
+│   └── archive/              # Completed sessions
+└── .session/
+    └── {story-id}-session.md # Active work session
+```
+
+## What's New in v10.0.0
+
+- **Clean Install Consolidation** - All managed files under `.pennyfarthing/` instead of scattered across `.claude/`, `.git/hooks/`, `.session/`. Legacy installs migrated automatically via `pennyfarthing update`
+- **Tool Use Approval System** - Hook-based permission flow with severity classification, grant persistence, agent-level scoping, and workflow presets. Replaces legacy IPC approval
+- **Smooth Plan Mode Exit** - Tirepump choice UI for transitioning out of plan mode
+
+### Previous Highlights
+
+- **v9.3** - Theme packages (97 themes across 7 packs), release workflow, shadcn/ui migration
+- **v9.0** - Dockview panel system, React 19 rewrite, tool visualization, prime context, bell/relay modes
+- **v8.x** - BikeLane workflows, scientific benchmarking, JobFair, agent sidecars
+
+See [CHANGELOG.md](CHANGELOG.md) for full details.
+
+---
+
+## License
+
+Copyright 2025-2026 1898 & Co. All rights reserved.

package/package.json

@@ -1,63 +1,59 @@
 {
   "name": "@pennyfarthing/core",
-  "version": "10.0.1",
+  "version": "10.0.3",
   "description": "Claude Code agent framework with TDD workflow and persona system",
   "type": "module",
-  "keywords": [
-    "claude",
-    "claude-code",
-    "agents",
-    "ai",
-    "tdd",
-    "workflow",
-    "anthropic"
+  "bin": {
+    "pennyfarthing": "./packages/core/bin/pennyfarthing.js"
+  },
+  "files": [
+    "packages/core/bin/",
+    "packages/core/dist/",
+    "pennyfarthing-dist/agents/",
+    "pennyfarthing-dist/commands/",
+    "pennyfarthing-dist/guides/",
+    "pennyfarthing-dist/output-styles/",
+    "pennyfarthing-dist/personas/themes/",
+    "pennyfarthing-dist/scripts/",
+    "pennyfarthing-dist/skills/",
+    "pennyfarthing-dist/templates/",
+    "pennyfarthing-dist/workflows/",
+    "pennyfarthing_scripts/",
+    "README.md"
   ],
-  "license": "UNLICENSED",
-  "author": "1898andCo",
   "repository": {
     "type": "git",
-    "url": "https://github.com/1898andCo/pennyfarthing.git",
-    "directory": "packages/core"
+    "url": "https://github.com/1898andCo/pennyfarthing.git"
   },
   "homepage": "https://github.com/1898andCo/pennyfarthing#readme",
   "bugs": {
     "url": "https://github.com/1898andCo/pennyfarthing/issues"
   },
-  "bin": {
-    "pennyfarthing": "./bin/pennyfarthing.js"
+  "scripts": {
+    "build": "pnpm --filter @pennyfarthing/shared build && pnpm --filter @pennyfarthing/core build && pnpm --filter @pennyfarthing/cyclist build && ./scripts/generate-skill-docs.sh",
+    "docs": "./scripts/generate-skill-docs.sh",
+    "dev": "pnpm -r --parallel dev",
+    "test": "pnpm -r test",
+    "lint": "eslint 'packages/*/src/**/*.ts' --max-warnings 0",
+    "clean": "pnpm -r clean"
   },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist/",
-    "bin/"
-  ],
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "fs-extra": "^11.2.0",
     "inquirer": "^9.2.12",
     "open": "^11.0.0",
-    "yaml": "^2.3.4",
-    "@pennyfarthing/shared": "^10.0.1"
+    "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@types/fs-extra": "^11.0.4",
-    "@types/inquirer": "^9.0.7",
-    "@types/node": "^20.10.0",
-    "typescript": "^5.3.3"
-  },
-  "publishConfig": {
-    "access": "public"
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "globals": "^17.0.0",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.53.0"
   },
   "engines": {
     "node": ">=18.0.0"
   },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "node --test dist/**/*.test.js",
-    "lint": "eslint src/",
-    "clean": "rm -rf dist/"
-  }
-}
+  "packageManager": "pnpm@9.0.0"
+}

package/packages/core/dist/cli/commands/doctor-file-layout.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tests for MSSCI-14372: Update doctor to validate new file layout
+ *
+ * Tests verify:
+ * - checkFileLayout() detects files at correct .pennyfarthing/ locations
+ * - checkFileLayout() flags files at old .claude/ locations with migration instructions
+ * - Fix functions migrate files automatically
+ * - New "layout/" check category is used for result names
+ *
+ * Run with: npm test
+ */
+export {};
+//# sourceMappingURL=doctor-file-layout.test.d.ts.map

package/packages/core/dist/cli/commands/doctor-file-layout.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-file-layout.test.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor-file-layout.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/packages/core/dist/cli/commands/doctor-file-layout.test.js

@@ -0,0 +1,234 @@
+/**
+ * Tests for MSSCI-14372: Update doctor to validate new file layout
+ *
+ * Tests verify:
+ * - checkFileLayout() detects files at correct .pennyfarthing/ locations
+ * - checkFileLayout() flags files at old .claude/ locations with migration instructions
+ * - Fix functions migrate files automatically
+ * - New "layout/" check category is used for result names
+ *
+ * Run with: npm test
+ */
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { existsSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+// Import the new function - does NOT exist yet, tests will fail (RED)
+import { checkFileLayout } from './doctor.js';
+describe('MSSCI-14372: Doctor file layout validation', () => {
+    let testDir;
+    let claudeDir;
+    let pennyfarthingDir;
+    beforeEach(() => {
+        testDir = join(tmpdir(), `pf-layout-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        claudeDir = join(testDir, '.claude');
+        pennyfarthingDir = join(testDir, '.pennyfarthing');
+        mkdirSync(claudeDir, { recursive: true });
+        mkdirSync(pennyfarthingDir, { recursive: true });
+    });
+    afterEach(() => {
+        if (existsSync(testDir)) {
+            rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+    describe('Result naming convention', () => {
+        it('should use layout/ prefix for all results', () => {
+            // AC5: New check category "File Layout"
+            // Setup: valid layout so we get pass results
+            mkdirSync(join(pennyfarthingDir, 'scripts/misc'), { recursive: true });
+            writeFileSync(join(pennyfarthingDir, 'manifest.json'), JSON.stringify({ version: '10.0.0' }));
+            writeFileSync(join(pennyfarthingDir, 'config.local.yaml'), 'theme: west-wing');
+            const results = checkFileLayout(testDir);
+            assert.ok(results.length > 0, 'Should return at least one result');
+            for (const result of results) {
+                assert.ok(result.name.startsWith('layout/'), `Result name "${result.name}" should start with "layout/"`);
+            }
+        });
+    });
+    describe('Manifest validation', () => {
+        it('should pass when manifest exists at .pennyfarthing/manifest.json', () => {
+            // AC1: Doctor checks files are in correct .pennyfarthing/ locations
+            writeFileSync(join(pennyfarthingDir, 'manifest.json'), JSON.stringify({ version: '10.0.0', installationType: 'symlink' }));
+            const results = checkFileLayout(testDir);
+            const manifestResult = results.find((r) => r.name === 'layout/manifest');
+            assert.ok(manifestResult, 'Should have a manifest check result');
+            assert.strictEqual(manifestResult.status, 'pass', 'Should pass when manifest exists');
+        });
+        it('should fail when manifest is missing from .pennyfarthing/', () => {
+            // AC1: Doctor checks files are in correct .pennyfarthing/ locations
+            const results = checkFileLayout(testDir);
+            const manifestResult = results.find((r) => r.name === 'layout/manifest');
+            assert.ok(manifestResult, 'Should have a manifest check result');
+            assert.strictEqual(manifestResult.status, 'fail', 'Should fail when manifest missing');
+        });
+    });
+    describe('Config validation', () => {
+        it('should pass when config exists at .pennyfarthing/config.local.yaml', () => {
+            // AC1: correct location
+            writeFileSync(join(pennyfarthingDir, 'config.local.yaml'), 'theme: west-wing');
+            const results = checkFileLayout(testDir);
+            const configResult = results.find((r) => r.name === 'layout/config');
+            assert.ok(configResult, 'Should have a config check result');
+            assert.strictEqual(configResult.status, 'pass', 'Should pass when config exists');
+        });
+        it('should warn when config is missing from .pennyfarthing/', () => {
+            // AC1: flag missing files
+            const results = checkFileLayout(testDir);
+            const configResult = results.find((r) => r.name === 'layout/config');
+            assert.ok(configResult, 'Should have a config check result');
+            assert.strictEqual(configResult.status, 'warn', 'Should warn when config missing');
+        });
+        it('should flag config at old .claude/persona-config.yaml with migration instructions', () => {
+            // AC2: flags old .claude/ locations with migration instructions
+            writeFileSync(join(claudeDir, 'persona-config.yaml'), 'theme: star-wars');
+            const results = checkFileLayout(testDir);
+            const oldConfigResult = results.find((r) => r.name === 'layout/config-old-location');
+            assert.ok(oldConfigResult, 'Should detect config at old location');
+            assert.strictEqual(oldConfigResult.status, 'warn', 'Should warn about old location');
+            assert.ok(oldConfigResult.detail?.includes('.pennyfarthing/config.local.yaml'), 'Detail should include migration instruction with correct path');
+        });
+        it('fix should migrate config from .claude/ to .pennyfarthing/', () => {
+            // AC3: --fix migrates automatically
+            writeFileSync(join(claudeDir, 'persona-config.yaml'), 'theme: west-wing');
+            const results = checkFileLayout(testDir);
+            const oldConfigResult = results.find((r) => r.name === 'layout/config-old-location');
+            assert.ok(oldConfigResult?.fix, 'Should have fix function');
+            oldConfigResult.fix();
+            assert.ok(existsSync(join(pennyfarthingDir, 'config.local.yaml')), 'Config should exist at new location after fix');
+        });
+    });
+    describe('Settings.local.json symlink validation', () => {
+        it('should pass when settings.local.json exists', () => {
+            // AC1: correct location
+            writeFileSync(join(claudeDir, 'settings.local.json'), JSON.stringify({ hooks: {} }, null, 2));
+            const results = checkFileLayout(testDir);
+            const settingsResult = results.find((r) => r.name === 'layout/settings');
+            assert.ok(settingsResult, 'Should have a settings check result');
+            assert.strictEqual(settingsResult.status, 'pass', 'Should pass when settings exists');
+        });
+        it('should fail when settings.local.json is missing', () => {
+            // AC1: check critical files
+            const results = checkFileLayout(testDir);
+            const settingsResult = results.find((r) => r.name === 'layout/settings');
+            assert.ok(settingsResult, 'Should have a settings check result');
+            assert.strictEqual(settingsResult.status, 'fail', 'Should fail when settings missing');
+        });
+    });
+    describe('Sidecars directory validation', () => {
+        it('should pass when sidecars exist at .pennyfarthing/sidecars/', () => {
+            // AC1: correct location
+            mkdirSync(join(pennyfarthingDir, 'sidecars/sm'), { recursive: true });
+            writeFileSync(join(pennyfarthingDir, 'sidecars/sm/patterns.md'), '# patterns');
+            const results = checkFileLayout(testDir);
+            const sidecarsResult = results.find((r) => r.name === 'layout/sidecars');
+            assert.ok(sidecarsResult, 'Should have a sidecars check result');
+            assert.strictEqual(sidecarsResult.status, 'pass', 'Should pass when sidecars at correct location');
+        });
+        it('should warn when sidecars exist at old .claude/project/agents/ location', () => {
+            // AC2: flags old .claude/ locations
+            const legacyDir = join(claudeDir, 'project/agents/sm-sidecar');
+            mkdirSync(legacyDir, { recursive: true });
+            writeFileSync(join(legacyDir, 'patterns.md'), '# old patterns');
+            const results = checkFileLayout(testDir);
+            const oldSidecarsResult = results.find((r) => r.name === 'layout/sidecars-old-location');
+            assert.ok(oldSidecarsResult, 'Should detect sidecars at old location');
+            assert.strictEqual(oldSidecarsResult.status, 'warn', 'Should warn about old location');
+            assert.ok(oldSidecarsResult.detail?.includes('.pennyfarthing/sidecars/'), 'Detail should include migration path');
+        });
+        it('fix should migrate sidecars from old location', () => {
+            // AC3: --fix migrates
+            const legacyDir = join(claudeDir, 'project/agents/sm-sidecar');
+            mkdirSync(legacyDir, { recursive: true });
+            writeFileSync(join(legacyDir, 'patterns.md'), '# old patterns');
+            const results = checkFileLayout(testDir);
+            const oldSidecarsResult = results.find((r) => r.name === 'layout/sidecars-old-location');
+            assert.ok(oldSidecarsResult?.fix, 'Should have fix function');
+            oldSidecarsResult.fix();
+            assert.ok(existsSync(join(pennyfarthingDir, 'sidecars/sm/patterns.md')), 'Sidecar files should exist at new location after fix');
+        });
+    });
+    describe('Project hooks validation', () => {
+        it('should pass when project hooks at .pennyfarthing/project/hooks/', () => {
+            // AC1: correct location
+            mkdirSync(join(pennyfarthingDir, 'project/hooks'), { recursive: true });
+            writeFileSync(join(pennyfarthingDir, 'project/hooks/setup-env.sh'), '#!/bin/bash');
+            const results = checkFileLayout(testDir);
+            const hooksResult = results.find((r) => r.name === 'layout/project-hooks');
+            assert.ok(hooksResult, 'Should have a project hooks check result');
+            assert.strictEqual(hooksResult.status, 'pass', 'Should pass when hooks at correct location');
+        });
+        it('should flag project hooks at old .claude/project/hooks/ location', () => {
+            // AC2: flags old locations
+            mkdirSync(join(claudeDir, 'project/hooks'), { recursive: true });
+            writeFileSync(join(claudeDir, 'project/hooks/setup-env.sh'), '#!/bin/bash\nold hook');
+            const results = checkFileLayout(testDir);
+            const oldHooksResult = results.find((r) => r.name === 'layout/project-hooks-old-location');
+            assert.ok(oldHooksResult, 'Should detect hooks at old location');
+            assert.strictEqual(oldHooksResult.status, 'warn', 'Should warn about old location');
+            assert.ok(oldHooksResult.detail?.includes('.pennyfarthing/project/hooks/'), 'Detail should include migration path');
+        });
+        it('fix should migrate project hooks from old location', () => {
+            // AC3: --fix migrates
+            mkdirSync(join(claudeDir, 'project/hooks'), { recursive: true });
+            writeFileSync(join(claudeDir, 'project/hooks/setup-env.sh'), '#!/bin/bash\nold hook');
+            const results = checkFileLayout(testDir);
+            const oldHooksResult = results.find((r) => r.name === 'layout/project-hooks-old-location');
+            assert.ok(oldHooksResult?.fix, 'Should have fix function');
+            oldHooksResult.fix();
+            assert.ok(existsSync(join(pennyfarthingDir, 'project/hooks/setup-env.sh')), 'Hook should exist at new location after fix');
+        });
+    });
+    describe('Edge cases', () => {
+        it('should handle empty project directory gracefully', () => {
+            // No .claude or .pennyfarthing contents at all
+            const emptyDir = join(tmpdir(), `pf-empty-test-${Date.now()}`);
+            mkdirSync(emptyDir, { recursive: true });
+            try {
+                const results = checkFileLayout(emptyDir);
+                assert.ok(Array.isArray(results), 'Should return an array even for empty dir');
+            }
+            finally {
+                rmSync(emptyDir, { recursive: true, force: true });
+            }
+        });
+        it('should not flag files when both old and new locations exist and new is valid', () => {
+            // AC4: preserve existing checks — don't double-warn
+            writeFileSync(join(pennyfarthingDir, 'config.local.yaml'), 'theme: west-wing');
+            writeFileSync(join(claudeDir, 'persona-config.yaml'), 'theme: star-wars');
+            const results = checkFileLayout(testDir);
+            // Config at new location should pass
+            const configResult = results.find((r) => r.name === 'layout/config');
+            assert.ok(configResult, 'Should still have config check');
+            assert.strictEqual(configResult.status, 'pass', 'New location check should pass');
+            // Old location should still warn
+            const oldConfigResult = results.find((r) => r.name === 'layout/config-old-location');
+            assert.ok(oldConfigResult, 'Should still flag old location');
+            assert.strictEqual(oldConfigResult.status, 'warn', 'Should warn about old location');
+        });
+        it('should not interfere with existing doctor check categories', () => {
+            // AC4: existing checks preserved
+            // The layout/ prefix should not collide with existing prefixes
+            const results = checkFileLayout(testDir);
+            const prefixes = results.map((r) => r.name.split('/')[0]);
+            const uniquePrefixes = [...new Set(prefixes)];
+            // All results should be in layout/ category
+            assert.deepStrictEqual(uniquePrefixes, ['layout'], 'All results should use layout/ prefix only');
+        });
+        it('fix should not overwrite existing files at new location', () => {
+            // AC3: safe migration — don't clobber existing
+            writeFileSync(join(pennyfarthingDir, 'config.local.yaml'), 'theme: west-wing');
+            writeFileSync(join(claudeDir, 'persona-config.yaml'), 'theme: star-wars');
+            const results = checkFileLayout(testDir);
+            const oldConfigResult = results.find((r) => r.name === 'layout/config-old-location');
+            assert.ok(oldConfigResult?.fix, 'Should have fix function');
+            oldConfigResult.fix();
+            // The existing new-location config should NOT be overwritten
+            const configContent = readFileSync(join(pennyfarthingDir, 'config.local.yaml'), 'utf8');
+            assert.strictEqual(configContent, 'theme: west-wing', 'Should not overwrite existing config');
+            // Old file should still be removed (it's a shadow)
+            assert.strictEqual(existsSync(join(claudeDir, 'persona-config.yaml')), false, 'Old config should be removed even when new exists');
+        });
+    });
+});
+//# sourceMappingURL=doctor-file-layout.test.js.map