@pennyfarthing/core 9.2.0 → 9.3.0

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

@@ -1,346 +0,0 @@
-# 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 |