@pennyfarthing/core 7.9.3 → 8.0.0

package/packages/core/dist/cli/workspace.test.js

@@ -0,0 +1,158 @@
+/**
+ * Story 11-2: pnpm Workspace Structure Tests
+ *
+ * These tests verify the monorepo workspace structure is correctly configured.
+ * Tests are designed to FAIL until the workspace conversion is complete.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { execSync } from 'node:child_process';
+import { findMonorepoRoot } from './utils/files.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Use shared utility to find monorepo root
+const PROJECT_ROOT = findMonorepoRoot(__dirname);
+describe('Story 11-2: pnpm Workspace Structure', () => {
+    describe('AC1: packages/core/src/ contains former src/', () => {
+        it('should have packages/core directory', () => {
+            const coreDir = join(PROJECT_ROOT, 'packages', 'core');
+            assert.ok(existsSync(coreDir), 'packages/core/ directory must exist');
+        });
+        it('should have packages/core/src directory', () => {
+            const coreSrcDir = join(PROJECT_ROOT, 'packages', 'core', 'src');
+            assert.ok(existsSync(coreSrcDir), 'packages/core/src/ directory must exist');
+        });
+        it('should have CLI commands in packages/core/src/cli', () => {
+            const cliDir = join(PROJECT_ROOT, 'packages', 'core', 'src', 'cli');
+            assert.ok(existsSync(cliDir), 'packages/core/src/cli/ directory must exist');
+        });
+        it('should have packages/core/bin/pennyfarthing.js', () => {
+            const binFile = join(PROJECT_ROOT, 'packages', 'core', 'bin', 'pennyfarthing.js');
+            assert.ok(existsSync(binFile), 'packages/core/bin/pennyfarthing.js must exist');
+        });
+        it('should have packages/core/package.json', () => {
+            const packageJson = join(PROJECT_ROOT, 'packages', 'core', 'package.json');
+            assert.ok(existsSync(packageJson), 'packages/core/package.json must exist');
+        });
+        it('should have @pennyfarthing/core as package name', () => {
+            const packageJsonPath = join(PROJECT_ROOT, 'packages', 'core', 'package.json');
+            if (!existsSync(packageJsonPath)) {
+                assert.fail('packages/core/package.json must exist first');
+            }
+            const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            assert.strictEqual(pkg.name, '@pennyfarthing/core', 'Package name must be @pennyfarthing/core');
+        });
+    });
+    describe('AC2: pnpm-workspace.yaml defines packages/*', () => {
+        it('should have pnpm-workspace.yaml at project root', () => {
+            const workspaceYaml = join(PROJECT_ROOT, 'pnpm-workspace.yaml');
+            assert.ok(existsSync(workspaceYaml), 'pnpm-workspace.yaml must exist at project root');
+        });
+        it('should define packages/* in workspace', () => {
+            const workspaceYamlPath = join(PROJECT_ROOT, 'pnpm-workspace.yaml');
+            if (!existsSync(workspaceYamlPath)) {
+                assert.fail('pnpm-workspace.yaml must exist first');
+            }
+            const content = readFileSync(workspaceYamlPath, 'utf-8');
+            const workspace = parseYaml(content);
+            assert.ok(workspace.packages, 'workspace.packages must be defined');
+            assert.ok(workspace.packages.some((p) => p.includes('packages')), 'workspace.packages must include packages/* or similar');
+        });
+    });
+    describe('AC3: pnpm install works from root', () => {
+        it('should have pnpm-lock.yaml after install', () => {
+            // This test assumes pnpm install has been run
+            // The presence of pnpm-lock.yaml indicates pnpm is the package manager
+            const lockFile = join(PROJECT_ROOT, 'pnpm-lock.yaml');
+            assert.ok(existsSync(lockFile), 'pnpm-lock.yaml must exist (run pnpm install first)');
+        });
+    });
+    describe('AC4: pnpm build compiles all packages', () => {
+        it('should have tsconfig.base.json for shared config', () => {
+            const tsconfigBase = join(PROJECT_ROOT, 'tsconfig.base.json');
+            assert.ok(existsSync(tsconfigBase), 'tsconfig.base.json must exist at project root');
+        });
+        it('should have packages/core/tsconfig.json', () => {
+            const tsconfig = join(PROJECT_ROOT, 'packages', 'core', 'tsconfig.json');
+            assert.ok(existsSync(tsconfig), 'packages/core/tsconfig.json must exist');
+        });
+        it('should have packages/core/dist after build', () => {
+            // This test assumes build has been run
+            const distDir = join(PROJECT_ROOT, 'packages', 'core', 'dist');
+            assert.ok(existsSync(distDir), 'packages/core/dist/ must exist (run pnpm build first)');
+        });
+        it('should have packages/shared/dist after build', () => {
+            // packages/shared already exists from Story 11-1
+            const distDir = join(PROJECT_ROOT, 'packages', 'shared', 'dist');
+            assert.ok(existsSync(distDir), 'packages/shared/dist/ must exist (run pnpm build first)');
+        });
+    });
+    describe('AC5: pennyfarthing CLI still functional', () => {
+        it('should have bin entry in packages/core/package.json', () => {
+            const packageJsonPath = join(PROJECT_ROOT, 'packages', 'core', 'package.json');
+            if (!existsSync(packageJsonPath)) {
+                assert.fail('packages/core/package.json must exist first');
+            }
+            const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            assert.ok(pkg.bin, 'packages/core/package.json must have bin field');
+            assert.ok(pkg.bin.pennyfarthing || pkg.bin === './bin/pennyfarthing.js', 'bin must include pennyfarthing entry');
+        });
+        // SKIP: chalk 5.x ESM incompatibility with inquirer->ora->log-symbols
+        // log-symbols uses `chalk.blue()` (CJS API) but chalk 5 uses named exports
+        // This is a transitive dependency issue - inquirer needs to update ora
+        // See: https://github.com/chalk/chalk/issues/585
+        // TODO(MSSCI-12192): Re-enable when inquirer updates to chalk 5-compatible deps
+        it.skip('should execute pennyfarthing --version without error', () => {
+            // This test runs the actual CLI
+            // After workspace conversion, we need to test from packages/core
+            try {
+                const binPath = join(PROJECT_ROOT, 'packages', 'core', 'bin', 'pennyfarthing.js');
+                if (!existsSync(binPath)) {
+                    assert.fail('packages/core/bin/pennyfarthing.js must exist first');
+                }
+                const result = execSync(`node "${binPath}" --version`, {
+                    encoding: 'utf-8',
+                    timeout: 10000,
+                });
+                assert.ok(result.includes('.'), 'Version output should contain a version number');
+            }
+            catch (error) {
+                assert.fail(`CLI execution failed: ${error.message}`);
+            }
+        });
+    });
+    describe('AC6: Existing tests pass', () => {
+        it('should have test files in packages/core/src', () => {
+            // After move, test files should be in packages/core/src
+            const testPattern = join(PROJECT_ROOT, 'packages', 'core', 'src');
+            assert.ok(existsSync(testPattern), 'packages/core/src/ must exist for tests to be found');
+        });
+    });
+    describe('Workspace Dependencies', () => {
+        it('should have @pennyfarthing/shared in packages/core dependencies', () => {
+            const packageJsonPath = join(PROJECT_ROOT, 'packages', 'core', 'package.json');
+            if (!existsSync(packageJsonPath)) {
+                assert.fail('packages/core/package.json must exist first');
+            }
+            const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const deps = pkg.dependencies || {};
+            assert.ok(deps['@pennyfarthing/shared'], 'packages/core should depend on @pennyfarthing/shared');
+            // Accept either workspace protocol (development) or version (for npm publish)
+            const sharedDep = deps['@pennyfarthing/shared'];
+            assert.ok(sharedDep.includes('workspace') || sharedDep.match(/^\^?\d+\.\d+\.\d+/), 'Dependency should use workspace protocol or semver version');
+        });
+    });
+    describe('Root package.json', () => {
+        it('should be a workspace root (has workspaces config or pnpm-workspace.yaml)', () => {
+            // In pnpm workspaces, root can have dependencies for npm publishing
+            // The key indicator is pnpm-workspace.yaml existence, not package.json structure
+            const workspaceYamlPath = join(PROJECT_ROOT, 'pnpm-workspace.yaml');
+            assert.ok(existsSync(workspaceYamlPath), 'Root should have pnpm-workspace.yaml (workspace root indicator)');
+        });
+    });
+});
+//# sourceMappingURL=workspace.test.js.map

package/packages/core/dist/cli/workspace.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.test.js","sourceRoot":"","sources":["../../src/cli/workspace.test.ts"],"names":[],"mappings":"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"}

package/pennyfarthing-dist/agents/README.md

@@ -0,0 +1,348 @@
+# Pennyfarthing Core Agents
+
+## Overview
+
+This directory contains the **single source of truth** for all Pennyfarthing agent definitions. Agents are coordinated across both `API` and `UI` repositories.
+
+**See:** `../ AGENT-COORDINATION.md` for complete architecture documentation.
+
+## Main Agents
+
+| Agent | Role |
+|-------|------|
+| **SM** | Story coordination, session management |
+| **TEA** | Test writing, TDD guidance |
+| **Dev** | Feature implementation |
+| **Reviewer** | Adversarial code review |
+| **Orchestrator** | Process improvement, meta-ops |
+| **PM** | Planning, prioritization |
+| **Architect** | System design, ADRs |
+| **DevOps** | Infrastructure, deployment |
+| **Tech Writer** | Documentation |
+| **UX Designer** | UI design, accessibility |
+
+### Official Subagents (Haiku-based)
+Lightweight subagents for mechanical tasks. Invoked via `Task tool` with `subagent_type: "general-purpose"` and `model: "haiku"`.
+
+**Invocation pattern:**
+```yaml
+Task tool:
+  subagent_type: "general-purpose"
+  model: "haiku"
+  run_in_background: true   # For independent work; omit for sequential workflows
+  prompt: |
+    Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+    {PARAMETERS}
+```
+
+**See `agent-behavior.md` → "Interactive Background Task Protocol"** for when to use background vs foreground execution.
+
+- **`workflow-status-check.md`** - Detect workflow state
+- **`sm-setup.md`** - Research OR setup mode (Story 31-11)
+- **`sm-finish.md`** - Preflight OR execute phase (Story 31-11)
+- **`handoff.md`** - Workflow-driven handoff (Stories 31-7, 31-10)
+- **`sm-handoff.md`** - SM→TEA/Dev handoff with Jira/branch verification
+- **`sm-file-summary.md`** - Summarize file changes
+- **`reviewer-preflight.md`** - Gather review data
+- **`testing-runner.md`** - Execute tests, report results
+
+### Removed Files (Stories 31-11, 31-12)
+These files have been deleted and replaced by consolidated versions:
+
+**SM Subagents (Story 31-12):**
+- `sm-work-research.md` → use `sm-setup` with MODE=research
+- `sm-story-setup.md` → use `sm-setup` with MODE=setup
+- `sm-finish-bookkeeping.md` → use `sm-finish` with PHASE=preflight
+- `sm-finish-execution.md` → use `sm-finish` with PHASE=execute
+
+**Handoff Subagents (Story 31-11):**
+- `tea-handoff.md` → use `handoff` with CURRENT_PHASE=red
+- `dev-handoff.md` → use `handoff` with CURRENT_PHASE=green
+- `reviewer-handoff-approve.md` → use `handoff` with VERDICT=approved
+- `reviewer-handoff-reject.md` → use `handoff` with VERDICT=rejected
+
+## Context Loading
+
+Agents load context based on their type:
+
+### Strategic Agents Load:
+- Full sprint status
+- Both API and UI contexts
+- Epic definitions
+- Active work
+
+### Tactical Agents Load:
+- Story section of sprint status
+- Active work
+- Target repo context only (based on story)
+
+**Configuration:** `.claude/project/docs/agent-scopes.yaml`
+
+## Usage
+
+### Activate an Agent
+
+```bash
+# Via workflow
+@/pm
+@/dev
+@/tea
+
+# Or mention in chat
+"Let's activate the PM agent"
+"Activate Dev to implement this story"
+```
+
+### Agent Files
+
+Each agent file contains:
+- **Persona:** Character and expertise
+- **Responsibilities:** What they handle
+- **Context:** Project information
+- **Context Loading:** What files to load on activation
+- **Activation:** How they operate
+- **Workflows:** Common tasks and patterns
+- **Handoffs:** How they coordinate with other agents
+
+## File Structure
+
+```
+.pennyfarthing/agents/
+├── README.md                  # This file
+│
+│ # Main Agents (10)
+├── orchestrator.md            # Master orchestrator
+├── pm.md                      # Product Manager
+├── sm.md                      # Scrum Master
+├── architect.md               # System Architect
+├── devops.md                  # DevOps Engineer
+├── dev.md                     # Developer
+├── tea.md                     # Test Engineer
+├── reviewer.md                # Code Reviewer
+├── tech-writer.md             # Technical Writer
+├── ux-designer.md             # UX Designer
+│
+│ # Official Subagents (8 active)
+├── workflow-status-check.md   # Detect workflow state
+├── sm-setup.md        # Research or setup mode (Story 31-11)
+├── sm-finish.md       # Preflight or execute (Story 31-11)
+├── handoff.md         # Workflow-driven handoff (Stories 31-7, 31-10)
+├── sm-handoff.md              # SM→TEA/Dev handoff with Jira/branch
+├── sm-file-summary.md         # Summarize files
+├── reviewer-preflight.md      # Review prep
+└── testing-runner.md          # Run tests
+```
+
+## Context Budget
+
+Each agent is designed to work within **~500-800 line context budget**:
+
+### Strategic Agent Budget
+- Agent file: ~200-300 lines
+- Sprint status: ~100-150 lines
+- Repo contexts: ~60 lines
+- Epics/docs: ~100 lines
+- Active work: ~50 lines
+- **Total:** ~500-660 lines
+
+### Tactical Agent Budget
+- Agent file: ~250-400 lines
+- Sprint status (story): ~50 lines
+- Active work: ~50 lines
+- Target repo context: ~100 lines
+- **Total:** ~450-600 lines
+
+## Common Handoffs
+
+```
+SM → TEA/Dev:    Story setup complete
+TEA → Dev:       Tests written
+Dev → Reviewer:  Implementation complete
+Reviewer → SM:   Story approved
+Reviewer → Dev:  Changes requested
+```
+
+## Creating New Agents
+
+1. Create `.pennyfarthing/agents/[name].md`
+2. Follow existing agent structure
+3. Update this README
+4. Create command in `.claude/commands/[name].md`
+
+### Agent Template Structure
+
+```markdown
+# [Agent Name] Agent - [Role]
+
+## Persona
+[Character description and expertise]
+
+## Responsibilities
+[What they handle]
+
+## Context
+[Project information]
+
+## Context Loading
+[What files to load on activation]
+
+## Activation
+[How they operate]
+
+## Key Workflows
+[Common tasks]
+
+## Handoffs
+[Coordination with other agents]
+
+## Activation Command
+[@/agent-name]
+
+## Exit
+[How to exit agent mode]
+```
+
+## Benefits
+
+✅ **Single Source of Truth** - All agents in one place
+✅ **Coordinated Planning** - Strategic agents see full scope
+✅ **Focused Implementation** - Tactical agents load only what they need
+✅ **Clear Hierarchy** - Strategic coordinate, tactical execute
+✅ **Scalable** - Easy to add new agents
+
+## Path Standards
+
+**IMPORTANT:** Scripts self-locate via `BASH_SOURCE`. Use direct script invocation.
+
+### Standard Pattern
+```bash
+# ✅ CORRECT - Direct script invocation (scripts self-locate via BASH_SOURCE)
+.pennyfarthing/scripts/core/agent-session.sh start "Agent Name"
+
+# ✅ CORRECT - Relative paths for files (Claude starts in project root)
+.session/{STORY_ID}-session.md
+
+# ✅ CORRECT - Commands use climber pattern to find project root
+d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
+"$d/.pennyfarthing/scripts/core/agent-session.sh" start "sm"
+
+# ❌ WRONG - $CLAUDE_PROJECT_DIR doesn't exist in Claude Bash calls
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/agent-session.sh  # BROKEN!
+
+# ❌ WRONG - Don't hardcode absolute paths
+/Users/someone/project/.pennyfarthing/scripts/core/agent-session.sh
+```
+
+### Why Relative Paths?
+- `$CLAUDE_PROJECT_DIR` is available in hooks but NOT in Claude's Bash tool calls
+- Scripts self-locate via `BASH_SOURCE` and `find-root.sh`
+- Claude Code always starts in the project root directory
+- The climber pattern handles subdirectory execution if needed
+
+### Path Context
+| Context | `$CLAUDE_PROJECT_DIR` | Relative Paths |
+|---------|----------------------|----------------|
+| Hooks (settings.json) | ✅ Available | ✅ Works |
+| Claude Bash calls | ❌ Not set | ✅ Works |
+| Inside scripts | ❌ Use `$PROJECT_ROOT` | ✅ Works |
+
+## Background Subagent Execution
+
+Subagents can run in background using Claude Code's `run_in_background` parameter. This allows the user to continue interacting while slow operations complete asynchronously.
+
+**IMPORTANT:** See `agent-behavior.md` → "Interactive Background Task Protocol" for the authoritative guidance.
+
+### The Key Insight
+
+**Background + immediate blocking is an anti-pattern.** If you spawn with `run_in_background: true` then immediately call `TaskOutput` with `block: true`, you've blocked the conversation - the user can't interact.
+
+### When to Use Background Execution
+
+**Good candidates (truly independent work):**
+- Test runs while writing more code
+- Multiple independent file explorations
+- Long-running builds while discussing next steps
+- Parallel searches where you don't need results immediately
+
+**When NOT to use (sequential workflow):**
+- Status checks that determine your next action
+- Handoff operations that must complete before continuing
+- Any operation where you need the result to proceed
+
+### Cyclist Integration
+
+When running in Cyclist, background tasks are automatically tracked:
+- OTEL spans detect `run_in_background: true` Task calls
+- Completion notifications appear in MessageView
+- User can expand to see full output
+
+**This means:** Fire the task, tell the user it's running, and keep working. Cyclist handles the notification when it finishes.
+
+### Tracking Background Tasks in Session Files
+
+Use the background task tracking utilities to manage session file entries:
+
+```bash
+source .pennyfarthing/scripts/utils/background-tasks.sh
+SESSION_FILE=".session/${STORY_ID}-session.md"
+
+# After spawning, record the task:
+bg_task_add "$SESSION_FILE" "$TASK_ID" "testing-runner" "Background test run"
+
+# After checking TaskOutput, update status:
+bg_task_update "$SESSION_FILE" "$TASK_ID" "completed"  # or "error"
+
+# Clean up finished tasks:
+bg_task_cleanup "$SESSION_FILE"
+```
+
+**Available functions:**
+| Function | Purpose |
+|----------|---------|
+| `bg_task_add` | Record new background task |
+| `bg_task_update` | Update task status (running/completed/error) |
+| `bg_task_cleanup` | Remove completed and errored tasks |
+| `bg_task_list` | Show all running tasks |
+| `bg_task_check` | Return 0 if any tasks running |
+| `bg_task_summary` | Print counts by status |
+
+### Background Execution Constraints
+
+1. **No concurrent state mutation** - Don't have multiple background tasks writing to the same file
+2. **Independent operations only** - Each background task should be self-contained
+3. **Check before proceeding** - If you need the result, wait for it with `block: true`
+4. **Clean up tracking** - Use `bg_task_cleanup` after processing results
+
+### Example: Background Tests While Coding
+
+```bash
+# 1. Spawn testing-runner with run_in_background: true
+# 2. Record: bg_task_add "$SESSION_FILE" "$TASK_ID" "testing-runner" "Tests while coding"
+# 3. Continue writing code
+# 4. Periodically check TaskOutput with block: false
+# 5. When complete: bg_task_update "$SESSION_FILE" "$TASK_ID" "completed"
+# 6. Cleanup: bg_task_cleanup "$SESSION_FILE"
+# 7. If RED: stop and fix
+# 8. If GREEN: continue with confidence
+```
+
+## Quick Reference
+
+```bash
+# View agent scope configuration
+cat .claude/project/docs/agent-scopes.yaml
+
+# List all agents
+ls .pennyfarthing/agents/
+
+# View agent definition
+cat .pennyfarthing/agents/pm.md
+
+# Activate agent
+@/pm
+```
+
+---
+
+**Your coordinated Pennyfarthing agent system is ready!**