@pennyfarthing/core 10.0.1 → 10.0.3

package/pennyfarthing-dist/guides/session-artifacts.md

@@ -0,0 +1,193 @@
+# Session Artifacts Naming Convention
+
+This guide defines the standard naming patterns for all files in `.session/`.
+
+## Why This Matters
+
+Consistent naming enables:
+1. **Predictable cleanup** - Scripts can reliably find and remove artifacts
+2. **Easy debugging** - Quickly identify what story/agent created a file
+3. **No accumulation** - Story-specific cleanup catches everything
+
+## File Categories
+
+| Category | Purpose | Lifecycle |
+|----------|---------|-----------|
+| `session` | Active work session file | Archived on story completion |
+| `context` | Technical context (story/epic) | Archived on completion |
+| `test` | Test execution output | Cleaned after 1 day or story completion |
+| `lint` | Lint execution output | Cleaned after 1 day or story completion |
+| `handoff` | Agent-to-agent transition data | Cleaned on story completion |
+
+## Naming Patterns
+
+### Session Files (Canonical)
+
+The primary work session file. One per active story.
+
+```
+{STORY_ID}-session.md
+```
+
+**Examples:**
+- `36-2-session.md`
+- `10-15-session.md`
+
+**Created by:** `sm-setup MODE=setup`
+**Archived by:** `sm-finish PHASE=execute` → `sprint/archive/story-{STORY_ID}-{DATE}.md`
+
+---
+
+### Context Files
+
+Technical context for stories and epics.
+
+```
+context-story-{STORY_ID}.md
+context-epic-{EPIC_NUM}.md
+```
+
+**Examples:**
+- `context-story-36-2.md`
+- `context-epic-10.md`
+
+**Created by:** SM (epic-tech-context task)
+**Archived by:** `sm-finish PHASE=execute` (story), `/start-epic` or `/retro` (epic)
+
+---
+
+### Test Output Files
+
+Test execution logs and reports.
+
+```
+test-{STORY_ID}-{AGENT}-{PHASE}.log
+test-{STORY_ID}-{AGENT}-{PHASE}.md
+```
+
+**Components:**
+- `{STORY_ID}` - e.g., `36-2`
+- `{AGENT}` - `tea`, `dev`, `reviewer`
+- `{PHASE}` - `red`, `green`, `verify`
+
+**Examples:**
+- `test-36-2-tea-red.log`
+- `test-36-2-dev-green.md`
+- `test-36-2-reviewer-verify.log`
+
+**Created by:** `handoff`, `reviewer-preflight`, `testing-runner`
+**Cleaned by:** `session-cleanup.sh --story {STORY_ID}` or 1-day retention
+
+---
+
+### Lint Output Files
+
+Lint execution logs.
+
+```
+lint-{STORY_ID}-{REPO}.log
+```
+
+**Examples:**
+- `lint-36-2-api.log`
+- `lint-36-2-ui.log`
+
+**Created by:** `reviewer-preflight`
+**Cleaned by:** `session-cleanup.sh --story {STORY_ID}` or 1-day retention
+
+---
+
+### Handoff Files
+
+Agent-to-agent transition data for structured handoffs.
+
+```
+handoff-{STORY_ID}-{FROM_AGENT}.md
+handoff-{STORY_ID}-{FROM_AGENT}.json
+```
+
+**Examples:**
+- `handoff-36-2-tea.md` (TEA → Dev)
+- `handoff-36-2-dev.json` (Dev → Reviewer)
+- `handoff-36-2-reviewer.md` (Reviewer → SM)
+
+**Created by:** Handoff subagents (`tea-handoff`, `dev-handoff`, `reviewer-handoff-*`)
+**Cleaned by:** `session-cleanup.sh --story {STORY_ID}`
+
+---
+
+## System Files
+
+These are managed automatically and should not be manually created.
+
+| File | Purpose | Management |
+|------|---------|------------|
+| `.gitkeep` | Keeps directory in git | Never delete |
+| `session-log.txt` | Session activity log | Rotated to 1000 lines by cleanup |
+| `agents/` | Agent session state (UUIDs) | Cleaned after 1 day |
+
+---
+
+## Cleanup Patterns
+
+The `session-cleanup.sh` script uses these patterns:
+
+### Story-specific cleanup (`--story {ID}`)
+```bash
+test-{STORY_ID}-*.log
+test-{STORY_ID}-*.md
+lint-{STORY_ID}-*.log
+handoff-{STORY_ID}-*.md
+handoff-{STORY_ID}-*.json
+context-story-{STORY_ID}.md
+```
+
+### Time-based cleanup (default: 1 day retention)
+```bash
+test-*.log
+test-*.md
+lint-*.log
+handoff-*.md
+handoff-*.json
+context-story-*.md
+```
+
+### Aggressive cleanup (`--aggressive`)
+```bash
+context-epic-*.md  # Only for completed epics
+```
+
+---
+
+## Migration from Old Patterns
+
+Old patterns that should no longer be used:
+
+| Old Pattern | New Pattern |
+|-------------|-------------|
+| `story-{ID}-context.md` | `context-story-{ID}.md` |
+| `epic-{N}-context.md` | `context-epic-{N}.md` |
+| `test-results-{repo}-{ID}.log` | `test-{ID}-{agent}-{phase}.log` |
+| `tea-{ID}-red-check-results.md` | `test-{ID}-tea-red.md` |
+| `dev-{ID}-red-verify-report.md` | `test-{ID}-dev-red.md` |
+| `{ID}-handoff-summary.md` | `handoff-{ID}-{agent}.md` |
+| `lint-results-{repo}-{ID}.log` | `lint-{ID}-{repo}.log` |
+
+---
+
+## Quick Reference
+
+```
+.session/
+├── .gitkeep                          # Git placeholder
+├── session-log.txt                   # Activity log (auto-rotated)
+├── agents/                           # Agent session state
+│   └── {uuid}.md                     # Per-session state
+├── 36-2-session.md                   # Active story session
+├── context-story-36-2.md             # Story technical context
+├── context-epic-10.md                # Epic technical context
+├── test-36-2-tea-red.log             # TEA test output
+├── test-36-2-dev-green.md            # Dev test report
+├── lint-36-2-api.log                 # Lint output
+└── handoff-36-2-tea.md               # TEA → Dev handoff
+```

package/pennyfarthing-dist/guides/session-schema.md

@@ -0,0 +1,346 @@
+# Session File XML Schema
+
+Session files track active work sessions for stories. They are the highest-frequency agent interaction point in Pennyfarthing, making structured XML critical for reliable agent behavior.
+
+## File Location
+
+```
+.session/{STORY_ID}-session.md
+```
+
+**Examples:**
+- `.session/MSSCI-12142-session.md`
+- `.session/36-2-session.md`
+
+## Complete Schema
+
+```xml
+<session story="STORY_ID" workflow="WORKFLOW_TYPE">
+  <meta>
+    <jira>MSSCI-XXXXX</jira>
+    <epic>MSSCI-XXXXX</epic>
+    <points>3</points>
+    <started>2026-01-22</started>
+  </meta>
+
+  <status phase="PHASE" next-agent="AGENT" handoff-ready="BOOLEAN"/>
+
+  <acceptance-criteria>
+    <ac id="1" status="done">Description of AC1</ac>
+    <ac id="2" status="pending">Description of AC2</ac>
+    <ac id="3" status="blocked">Description of AC3 - blocked reason</ac>
+  </acceptance-criteria>
+
+  <context>
+    Technical context, approach, key files involved...
+    See: `.session/context-story-{id}.md` for full context.
+  </context>
+
+  <work-log>
+    <entry agent="sm" date="2026-01-22">
+      Setup notes...
+    </entry>
+    <entry agent="tea" date="2026-01-22" phase="red">
+      Test writing notes...
+    </entry>
+    <entry agent="dev" date="2026-01-22" phase="green">
+      Implementation notes...
+    </entry>
+    <assessment agent="reviewer" verdict="approved">
+      Review findings...
+    </assessment>
+  </work-log>
+</session>
+```
+
+## Element Reference
+
+### `<session>` (Root Element)
+
+**Purpose:** Container for all session data.
+
+**Attributes:**
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `story` | Yes | Story identifier (Jira key or local ID) |
+| `workflow` | Yes | Workflow type: `tdd`, `trivial`, `bdd`, `agent-docs` |
+
+---
+
+### `<meta>`
+
+**Purpose:** Story metadata that doesn't change during the session.
+
+**Child Elements:**
+| Element | Required | Description |
+|---------|----------|-------------|
+| `<jira>` | Yes | Jira issue key (e.g., `MSSCI-12142`) |
+| `<epic>` | No | Parent epic's Jira key |
+| `<points>` | No | Story points (1, 2, 3, 5, 8) |
+| `<started>` | Yes | Session start date (YYYY-MM-DD) |
+
+---
+
+### `<status>`
+
+**Purpose:** Machine-readable workflow state. Updated by agents at phase transitions.
+
+**Attributes:**
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `phase` | Yes | Current workflow phase (see Phase Values) |
+| `next-agent` | Yes | Agent that should handle next (e.g., `tea`, `dev`, `reviewer`, `sm`) |
+| `handoff-ready` | No | `true` if current agent has completed work and is ready to hand off |
+
+**Phase Values:**
+| Workflow | Valid Phases |
+|----------|--------------|
+| `tdd` | `setup`, `red`, `green`, `review`, `finish` |
+| `trivial` | `setup`, `implement`, `review`, `finish` |
+| `bdd` | `setup`, `scenarios`, `implement`, `review`, `finish` |
+| `agent-docs` | `setup`, `document`, `review`, `finish` |
+
+---
+
+### `<acceptance-criteria>`
+
+**Purpose:** Track acceptance criteria completion status.
+
+**Child Elements:**
+
+#### `<ac>`
+
+**Attributes:**
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `id` | Yes | Numeric identifier (1, 2, 3...) |
+| `status` | Yes | `pending`, `in-progress`, `done`, `blocked` |
+
+**Content:** Human-readable description of the acceptance criterion.
+
+---
+
+### `<context>`
+
+**Purpose:** Brief technical context for the work. Can reference external context files for longer content.
+
+**Content:** Free-form text describing:
+- Technical approach
+- Key files involved
+- Relevant prior decisions
+- Links to detailed context files
+
+---
+
+### `<work-log>`
+
+**Purpose:** Chronological record of agent contributions.
+
+**Child Elements:**
+
+#### `<entry>`
+
+**Purpose:** Standard work log entry from any agent.
+
+**Attributes:**
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `agent` | Yes | Agent identifier: `sm`, `tea`, `dev`, `reviewer`, `architect`, etc. |
+| `date` | Yes | Entry date (YYYY-MM-DD) |
+| `phase` | No | TDD phase for TEA/Dev entries: `red`, `green`, `refactor` |
+
+**Content:** Free-form text describing work done.
+
+#### `<assessment>`
+
+**Purpose:** Formal verdict from Reviewer agent.
+
+**Attributes:**
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `agent` | Yes | Must be `reviewer` |
+| `verdict` | Yes | `approved`, `rejected`, `needs-work` |
+
+**Content:** Review findings, issues found, recommendations.
+
+---
+
+## Usage Examples
+
+### New Session (SM Setup)
+
+```xml
+<session story="MSSCI-12345" workflow="tdd">
+  <meta>
+    <jira>MSSCI-12345</jira>
+    <epic>MSSCI-12300</epic>
+    <points>3</points>
+    <started>2026-02-03</started>
+  </meta>
+
+  <status phase="setup" next-agent="tea" handoff-ready="false"/>
+
+  <acceptance-criteria>
+    <ac id="1" status="pending">User can create new account</ac>
+    <ac id="2" status="pending">Email validation works correctly</ac>
+    <ac id="3" status="pending">Password strength indicator shows</ac>
+  </acceptance-criteria>
+
+  <context>
+    Implementing user registration feature.
+    See: `.session/context-story-MSSCI-12345.md`
+  </context>
+
+  <work-log>
+    <entry agent="sm" date="2026-02-03">
+      Story setup complete. Jira claimed, branch created.
+      Technical context written with file mapping.
+    </entry>
+  </work-log>
+</session>
+```
+
+### After TEA Handoff
+
+```xml
+<session story="MSSCI-12345" workflow="tdd">
+  <!-- meta unchanged -->
+
+  <status phase="red" next-agent="dev" handoff-ready="true"/>
+
+  <acceptance-criteria>
+    <ac id="1" status="pending">User can create new account</ac>
+    <ac id="2" status="pending">Email validation works correctly</ac>
+    <ac id="3" status="pending">Password strength indicator shows</ac>
+  </acceptance-criteria>
+
+  <!-- context unchanged -->
+
+  <work-log>
+    <entry agent="sm" date="2026-02-03">
+      Story setup complete. Jira claimed, branch created.
+    </entry>
+    <entry agent="tea" date="2026-02-03" phase="red">
+      Wrote failing tests for all 3 ACs.
+      - `registration.test.ts`: 5 test cases
+      - All tests verified failing (RED)
+    </entry>
+  </work-log>
+</session>
+```
+
+### After Review (Approved)
+
+```xml
+<session story="MSSCI-12345" workflow="tdd">
+  <!-- meta unchanged -->
+
+  <status phase="review" next-agent="sm" handoff-ready="true"/>
+
+  <acceptance-criteria>
+    <ac id="1" status="done">User can create new account</ac>
+    <ac id="2" status="done">Email validation works correctly</ac>
+    <ac id="3" status="done">Password strength indicator shows</ac>
+  </acceptance-criteria>
+
+  <!-- context unchanged -->
+
+  <work-log>
+    <entry agent="sm" date="2026-02-03">
+      Story setup complete. Jira claimed, branch created.
+    </entry>
+    <entry agent="tea" date="2026-02-03" phase="red">
+      Wrote failing tests for all 3 ACs.
+    </entry>
+    <entry agent="dev" date="2026-02-03" phase="green">
+      Implemented registration feature.
+      - All tests passing (GREEN)
+      - PR: #456
+    </entry>
+    <assessment agent="reviewer" verdict="approved">
+      **Verdict: APPROVED**
+
+      All ACs verified, tests comprehensive, code follows patterns.
+      No security issues found.
+    </assessment>
+  </work-log>
+</session>
+```
+
+---
+
+## Parsing Guidance
+
+### Extracting Status
+
+Scripts and agents can extract status using simple patterns:
+
+```bash
+# Extract phase
+grep -oP 'phase="[^"]*"' session.md | head -1 | cut -d'"' -f2
+
+# Extract next agent
+grep -oP 'next-agent="[^"]*"' session.md | head -1 | cut -d'"' -f2
+
+# Check handoff readiness
+grep -oP 'handoff-ready="[^"]*"' session.md | head -1 | cut -d'"' -f2
+```
+
+### Extracting AC Status
+
+```bash
+# Count pending ACs
+grep -c 'status="pending"' session.md
+
+# Count done ACs
+grep -c 'status="done"' session.md
+```
+
+---
+
+## Migration Notes
+
+### Converting Old Format
+
+Old session files use plain markdown:
+
+```markdown
+## Workflow Status
+- **Current Phase:** implement
+- **Next Agent:** Reviewer
+- **Handoff Ready:** Yes
+```
+
+Convert to:
+
+```xml
+<status phase="implement" next-agent="reviewer" handoff-ready="true"/>
+```
+
+### AC Conversion
+
+Old format:
+```markdown
+## Acceptance Criteria
+- [x] AC1: User can create account
+- [ ] AC2: Email validation
+```
+
+New format:
+```xml
+<acceptance-criteria>
+  <ac id="1" status="done">User can create account</ac>
+  <ac id="2" status="pending">Email validation</ac>
+</acceptance-criteria>
+```
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `guides/xml-tags.md` | Complete XML tag taxonomy |
+| `guides/session-artifacts.md` | Session file naming conventions |
+| `scripts/session/create-session.sh` | Create new session files |
+| `scripts/session/update-session.sh` | Update session fields |