@pennyfarthing/core 11.2.0 → 11.2.2

package/pennyfarthing-dist/commands/pf-theme.md

@@ -16,10 +16,10 @@ Manage persona themes: list available themes, view details, switch themes, creat
 Show current theme or specific theme details.
 
 ```bash
-pf theme show [name]
+pf.sh theme show [name]
 
 # Show extended details (OCEAN scores, quirks, catchphrases)
-pf theme show [name] --full
+pf.sh theme show [name] --full
 ```
 
 ### `/theme list`
@@ -27,7 +27,7 @@ pf theme show [name] --full
 List all available themes with current theme highlighted.
 
 ```bash
-pf theme list
+pf.sh theme list
 ```
 
 Output shows current theme marked with `*` and tier brackets: `[S]` elite, `[A]` excellent, `[B]` strong, `[C]` good, `[D]` below average, `[U]` unbenchmarked.
@@ -37,12 +37,12 @@ Output shows current theme marked with `*` and tier brackets: `[S]` elite, `[A]`
 Set the active persona theme.
 
 ```bash
-pf theme set <name>
+pf.sh theme set <name>
 ```
 
 After setting, refresh the current agent's persona:
 ```bash
-pf agent start "sm"
+pf.sh agent start "sm"
 ```
 
 ### `/theme create <name> [--base <theme>] [--user]`
@@ -51,13 +51,13 @@ Create a new custom theme by copying from a base.
 
 ```bash
 # Create from default base (minimalist)
-pf theme create my-theme
+pf.sh theme create my-theme
 
 # Create from specific base
-pf theme create my-theme --base blade-runner
+pf.sh theme create my-theme --base blade-runner
 
 # Create as user-level theme (available across all projects)
-pf theme create my-theme --user
+pf.sh theme create my-theme --user
 ```
 
 ### `/theme maker`
@@ -90,6 +90,6 @@ Interactive wizard for AI-driven theme creation. Supports three modes:
 
 <reference>
 - **Skill:** `.claude/skills/theme/skill.md`
-- **CLI:** `pf theme [list|show|set|create]`
+- **CLI:** `pf.sh theme [list|show|set|create]`
 - **Config:** `.pennyfarthing/config.local.yaml`
 </reference>

package/pennyfarthing-dist/commands/pf-ux-designer.md

@@ -5,7 +5,7 @@ description: UX Designer - User experience design and UI patterns
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-pf agent start "ux-designer"
+source .pennyfarthing/scripts/lib/env.sh && source "$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/run-pf.sh" && run_pf agent start "ux-designer"
 ```
 This loads your persona and agent context. Adopt the character shown in the output.
 </agent-activation>

package/pennyfarthing-dist/commands/pf-work.md

@@ -7,7 +7,7 @@ description: Resume work or start new - smart entry point that picks up where yo
 <agent-activation>
 **FIRST:** Use Bash tool to run:
 ```bash
-pf agent start "sm"
+source .pennyfarthing/scripts/lib/env.sh && source "$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/run-pf.sh" && run_pf agent start "sm"
 ```
 This loads your persona and agent context. Adopt the character shown in the output.
 </agent-activation>

package/pennyfarthing-dist/gates/approval.md

@@ -0,0 +1,63 @@
+<gate name="approval" model="haiku">
+
+<purpose>
+Verify the reviewer has issued an explicit verdict on the code review.
+This gate runs after the Reviewer agent's review phase to confirm
+the code has been formally approved or rejected before proceeding.
+</purpose>
+
+<pass>
+Check the session file for a Reviewer Assessment section:
+
+1. **Find verdict:** Look for `## Reviewer Assessment` section in the session file.
+   - Search for an explicit APPROVED verdict
+   - The verdict must be unambiguous — not "looks good" but "APPROVED"
+
+2. **Verify completeness:** The assessment should include:
+   - A clear verdict (APPROVED)
+   - Summary of what was reviewed
+
+If the review is APPROVED, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: approval
+  message: "Code review APPROVED by reviewer"
+  checks:
+    - name: reviewer-verdict
+      status: pass
+      detail: "Explicit APPROVED verdict found in Reviewer Assessment"
+```
+</pass>
+
+<fail>
+If the review is not approved, diagnose and report:
+
+1. **REJECTED verdict:** The reviewer found issues that need addressing.
+   - Extract the specific findings from the Reviewer Assessment
+   - List each finding with its severity
+   - These must be addressed before the gate can pass
+
+2. **No verdict found:** The reviewer hasn't completed the review yet.
+   - The Reviewer Assessment section is missing or incomplete
+   - The reviewer needs to complete their review
+
+Return with actionable recovery guidance:
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: approval
+  message: "Gate failed: {REJECTED with findings | No verdict found}"
+  checks:
+    - name: reviewer-verdict
+      status: fail
+      detail: "{REJECTED: list findings | Missing: no assessment found}"
+  recovery:
+    - "Address reviewer findings: {finding1}, {finding2}"
+    - "Request re-review after fixes are applied"
+```
+</fail>
+
+</gate>

package/pennyfarthing-dist/gates/confidence-sm.md

@@ -0,0 +1,71 @@
+<gate name="confidence-sm" model="haiku">
+
+<purpose>
+Check whether the user's instruction to the SM agent is ambiguous or unclear.
+The SM agent handles story management, sprint coordination, and workflow routing.
+Vague commands like "continue", "next", "start", or "do it" without a clear target
+(story ID, agent name, or specific action) risk the SM taking the wrong action.
+This gate evaluates confidence that the instruction has a single unambiguous interpretation.
+</purpose>
+
+<pass>
+The instruction is clear and unambiguous. The SM agent can proceed confidently.
+
+Evaluate the instruction against these criteria:
+1. **Target identified:** A story ID, agent name, or specific action is stated or obvious from context
+2. **Intent clear:** The desired outcome (start work, finish story, check status, hand off) is unambiguous
+3. **No competing interpretations:** Only one reasonable reading of the instruction exists
+
+If the instruction is confident and clear, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: confidence-sm
+  message: "Instruction is clear: {summary of what SM will do}"
+  checks:
+    - name: target
+      status: pass
+      detail: "{what the instruction targets}"
+    - name: intent
+      status: pass
+      detail: "{what action the SM will take}"
+```
+</pass>
+
+<fail>
+The instruction is ambiguous. The SM agent should not guess — ask for clarification instead.
+
+Identify which aspect is unclear and offer specific options the user likely meant:
+
+1. **Missing target:** "continue" / "next" / "start" without specifying a story or action
+   - Did you mean: start a specific story? Continue the current workflow? Check sprint status?
+
+2. **Ambiguous scope:** "do the thing" / "handle it" without enough context
+   - Did you mean: finish the current story? Start new work? Run the backlog?
+
+3. **Multiple interpretations:** The instruction could reasonably mean two or more different actions
+   - List each interpretation and ask which one the user intended
+
+Return with clarifying options so the user can specify their intent:
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: confidence-sm
+  message: "Instruction is ambiguous: {what is unclear}"
+  checks:
+    - name: target
+      status: fail
+      detail: "{what target is missing or unclear}"
+    - name: intent
+      status: fail
+      detail: "{competing interpretations}"
+  recovery:
+    - "Did you mean: {option A}?"
+    - "Did you mean: {option B}?"
+    - "Specify a story ID or action to proceed"
+```
+</fail>
+
+</gate>

package/pennyfarthing-dist/gates/context-ok.md

@@ -0,0 +1,56 @@
+<gate name="context-ok" model="haiku">
+
+<purpose>
+Verify that Claude Code context usage is below threshold before allowing
+a phase transition. Prevents handoffs when context is too high, which would
+result in degraded agent performance in the next phase.
+</purpose>
+
+<pass>
+Run the context check command and verify usage is acceptable:
+
+1. **Context usage:** Run `pf context --human` to check current context percentage.
+   - Extract the usable percent from output
+   - Threshold: below 60% usable context
+
+2. **Relay mode:** Check if relay mode is active via `pf context` env var output.
+   - If relay mode is on and context is high, TirePump should handle clearing
+
+If context is below threshold, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: context-ok
+  message: "Context at {N}% — safe to continue"
+  checks:
+    - name: context-usage
+      status: pass
+      detail: "{usable_pct}% of available context used ({usable_tokens} tokens)"
+```
+</pass>
+
+<fail>
+If context usage exceeds the threshold:
+
+1. **High context:** Report the current usage level
+2. **Recommendation:** Suggest `/clear` before continuing
+
+Return with guidance:
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: context-ok
+  message: "Context at {N}% — too high for reliable handoff"
+  checks:
+    - name: context-usage
+      status: fail
+      detail: "{usable_pct}% of available context used — threshold is 60%"
+  recovery:
+    - "Run /clear to reset context, then retry the handoff"
+    - "If relay mode is on, TirePump will handle this automatically"
+```
+</fail>
+
+</gate>

package/pennyfarthing-dist/gates/evaluations/confidence-sm.md

@@ -0,0 +1,54 @@
+# Confidence SM Gate — Evaluation Results
+
+**Gate:** `confidence-sm`
+**Evaluation Period:** Sprint 2606 (first sprint deployed)
+**Gate Shipped:** Story 90-2
+
+---
+
+## Trigger Frequency
+
+The confidence-sm gate activated on SM agent startup when processing user instructions. During the evaluation period, the gate triggered on every SM invocation where a user instruction was present — this is by design, as it evaluates instruction clarity before the SM acts.
+
+**Observations:**
+- The gate fired on all SM activations with user input
+- Baseline: prior to the gate, the SM would silently interpret ambiguous commands without confirmation
+- The activation rate is proportional to SM usage — no runaway or unexpected triggering occurred
+- No occurrences of the gate triggering on internal handoff instructions (correctly scoped to user input)
+
+## Wrong-Approach Reduction
+
+Before the confidence-sm gate, the SM occasionally took wrong actions on ambiguous instructions like "continue", "next", or "do it" — starting incorrect stories, routing to the wrong agent, or misinterpreting scope. The gate was designed to catch these ambiguous instructions and request clarification instead of guessing.
+
+**Comparison with baseline:**
+- Prior to the gate, wrong-approach incidents from ambiguous SM instructions were an observed pain point that motivated Epic 90
+- After deployment, instructions that would previously have been misinterpreted now produce clarifying questions with specific options
+- The gate's three-check model (target identified, intent clear, no competing interpretations) effectively catches the most common ambiguity patterns
+- Improvement: the SM no longer silently guesses on vague commands — it surfaces options for the user to choose from
+
+## User Experience
+
+The gate's impact on usability was assessed for friction and override behavior.
+
+**Friction assessment:**
+- The gate adds one evaluation step before SM action, using a Haiku model call — latency impact is minimal
+- When instructions are clear (target + intent present), the gate passes silently with no user-visible friction
+- When instructions are ambiguous, the gate provides structured "Did you mean?" options rather than a generic error
+
+**Override and dismissal behavior:**
+- The gate does not currently support user override or bypass — if it fails, the SM requests clarification
+- No users reported the gate as annoying or attempted to dismiss it
+- The skip/bypass mechanism was deliberately omitted to enforce clarification on genuinely ambiguous input
+- If future feedback indicates excessive friction on borderline cases, a confidence threshold could be added
+
+## Rollout Recommendation
+
+**Decision: Recommend expanding the confidence gate pattern to other agents.**
+
+The confidence-sm gate demonstrated that pre-action ambiguity checking reduces wrong-approach incidents without meaningful friction on clear instructions. The pattern is agent-agnostic — any agent that interprets user instructions could benefit from a similar gate.
+
+**Recommended next steps:**
+- Extend to the TEA and Dev agents, which also receive direct user instructions that can be ambiguous
+- Create a parameterized `confidence-{agent}` template so per-agent gates share the same evaluation structure but customize pass/fail criteria for each agent's domain
+- Hold on extending to Reviewer and other agents that primarily receive structured handoff context (lower ambiguity risk)
+- Defer rollout to all agents until per-agent evaluation data confirms the pattern works across different instruction types

package/pennyfarthing-dist/gates/quality-pass.md

@@ -0,0 +1,67 @@
+<gate name="quality-pass" model="haiku">
+
+<purpose>
+Verify that all project quality gates pass locally — lint, type checks, and
+tests — before handing off to the next phase. This gate wraps the check.py
+quality runner to ensure the codebase is clean enough for Reviewer's time.
+</purpose>
+
+<pass>
+Run the quality gate script for the repos listed in the session file:
+
+```bash
+source .venv/bin/activate && python3 .pennyfarthing/scripts/workflow/check.py
+```
+
+The script runs lint, type checks, and tests concurrently. Exit code 0 means
+all checks passed.
+
+If ALL checks pass, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: quality-pass
+  message: "All quality gates passing — lint, typecheck, tests clean."
+  checks:
+    - name: lint
+      status: pass
+      detail: "Lint clean"
+    - name: typecheck
+      status: pass
+      detail: "Type checks passing"
+    - name: tests
+      status: pass
+      detail: "All tests passing"
+```
+</pass>
+
+<fail>
+If the script exits non-zero, parse its output to identify which checks failed.
+The script prints `[PASS]` or `[FAIL]` for each check (Lint, Type Check, Tests).
+
+Return with actionable recovery guidance:
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: quality-pass
+  message: "Quality gate failed: {summary of failures}"
+  checks:
+    - name: lint
+      status: pass | fail
+      detail: "{lint results or specific failures}"
+    - name: typecheck
+      status: pass | fail
+      detail: "{typecheck results or specific errors}"
+    - name: tests
+      status: pass | fail
+      detail: "{test results or failing test details}"
+  recovery:
+    - "Fix lint errors: run `npm run lint` to see details"
+    - "Fix type errors: run `tsc --noEmit` to see details"
+    - "Fix failing tests: run `pnpm test` to see details"
+```
+</fail>
+
+</gate>

package/pennyfarthing-dist/gates/tests-fail.md

@@ -0,0 +1,84 @@
+<gate name="tests-fail" model="haiku">
+
+<purpose>
+Verify tests are RED — failing tests exist that cover the acceptance
+criteria. TEA has written tests but implementation hasn't started.
+This gate runs after the TEA agent's red phase to confirm the codebase
+has proper test coverage before Dev begins implementation.
+</purpose>
+
+<pass>
+Run these checks and report results:
+
+1. **Failing tests exist:** Run the project test suite for the repos listed in the session file.
+   - For `pennyfarthing` repo: `cd pennyfarthing && python3 -m pytest` or `pnpm test`
+   - Record: total tests, passed, failed, skipped
+   - At least one test MUST be failing (RED state)
+
+2. **Tests cover acceptance criteria:** Read the session file's Acceptance Criteria section.
+   - Cross-reference test names/descriptions against each AC
+   - Each AC should have at least one corresponding test
+
+3. **Tests are committed:** Run `git status --porcelain` to check for uncommitted test files.
+   - All test files should be committed to the branch
+   - No uncommitted test files should exist
+
+If ALL checks pass, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: tests-fail
+  message: "{N} failing tests covering {M} acceptance criteria. Tests committed."
+  checks:
+    - name: failing-tests
+      status: pass
+      detail: "{failed}/{total} tests failing (RED state confirmed)"
+    - name: ac-coverage
+      status: pass
+      detail: "All {M} acceptance criteria have test coverage"
+    - name: tests-committed
+      status: pass
+      detail: "All test files committed to branch"
+```
+</pass>
+
+<fail>
+If ANY check fails, diagnose and report:
+
+1. **No failing tests found:** TEA didn't write tests or tests are already passing.
+   - This means implementation may have leaked into the red phase
+   - Or tests are not properly asserting against unimplemented code
+
+2. **Tests don't cover ACs:** Some acceptance criteria lack test coverage.
+   - List which ACs are missing tests
+   - TEA needs to add additional test cases
+
+3. **Tests aren't committed:** Uncommitted test files exist.
+   - List uncommitted test files
+   - TEA needs to commit before handoff
+
+Return with actionable recovery guidance:
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: tests-fail
+  message: "Gate failed: {summary of what's missing}"
+  checks:
+    - name: failing-tests
+      status: pass | fail
+      detail: "{description of test state}"
+    - name: ac-coverage
+      status: pass | fail
+      detail: "{list of uncovered ACs}"
+    - name: tests-committed
+      status: pass | fail
+      detail: "{list of uncommitted files}"
+  recovery:
+    - "Write failing tests for: {uncovered ACs}"
+    - "Commit test files: git add {files} && git commit"
+```
+</fail>
+
+</gate>

package/pennyfarthing-dist/gates/tests-pass.md

@@ -0,0 +1,79 @@
+<gate name="tests-pass" model="haiku">
+
+<purpose>
+Verify that all tests pass and the working tree is clean before handing off
+to the reviewer. This gate runs after the Dev agent's implementation phase
+to confirm the codebase is in a GREEN state.
+</purpose>
+
+<pass>
+Run these checks and report results:
+
+1. **Test suite:** Run the project test suite for the repos listed in the session file.
+   - For `pennyfarthing` repo: `cd pennyfarthing && pnpm test`
+   - For `orchestrator` repo: tests in the orchestrator root if applicable
+   - Record: total tests, passed, failed, skipped
+
+2. **Working tree:** Run `git status --porcelain` in each repo listed in session `**Repos:**`.
+   - Verify no uncommitted or untracked files (empty output = clean)
+
+3. **Branch status:** Run `git branch --show-current` and `git log --oneline -1`.
+   - Confirm on the expected feature branch from session `**Branch:**`
+
+If ALL checks pass, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: tests-pass
+  message: "All {N} tests passing. Working tree clean. Branch: {branch}"
+  checks:
+    - name: test-suite
+      status: pass
+      detail: "{passed}/{total} tests passing ({skipped} skipped)"
+    - name: working-tree
+      status: pass
+      detail: "No uncommitted changes"
+    - name: branch-status
+      status: pass
+      detail: "On branch {branch}, HEAD at {short-sha}"
+```
+</pass>
+
+<fail>
+If ANY check fails, diagnose and report:
+
+1. **Failing tests:** List each failing test file and line number.
+   - Run tests with verbose output to capture failure details.
+   - Group failures by file.
+
+2. **Dirty working tree:** List uncommitted and untracked files.
+   - Run `git status --porcelain` and report each file with its status code.
+
+3. **Wrong branch:** Report actual vs expected branch name.
+
+Return with actionable recovery guidance:
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: tests-pass
+  message: "Gate failed: {summary of failures}"
+  checks:
+    - name: test-suite
+      status: pass | fail
+      detail: "{description of test results or failures}"
+    - name: working-tree
+      status: pass | fail
+      detail: "{list of uncommitted files, or 'clean'}"
+    - name: branch-status
+      status: pass | fail
+      detail: "{branch info or mismatch details}"
+  recovery:
+    - "Fix failing tests in: {file1}, {file2}"
+    - "Commit or stash uncommitted changes before handoff"
+    - "Switch to correct branch: git checkout {expected-branch}"
+```
+</fail>
+
+</gate>