arreio 1.0.0-dev.1 → 1.0.1-dev.0

package/README.md

@@ -78,4 +78,4 @@ Initialize a new project, enabling the project to follow the four phases of the
 
 #### /end-session
 
-Preserve session context with a well-documented commit capturing state, decisions, and next steps.
+Preserve session context with a well-documented commit capturing state, decisions, and next steps — saved as a traceable session artifact (with agent attribution) in `docs/plans/.end-session/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arreio",
-  "version": "1.0.0-dev.1",
+  "version": "1.0.1-dev.0",
   "description": "Arreio transforms agentic coding workflows into a predictable, safe, and high-quality software delivery pipeline. Master the four core phases—Plan, Work, Review, Learn—to orchestrate a highly reliable development cycle.",
   "license": "MIT",
   "author": "Wicttor",

package/skills/arreio-init/SKILL.md

@@ -159,7 +159,17 @@ _No review reports yet._
 
 **Action:** Create all four directories if they don't exist.
 
-### Step 11: Create Learn Category Folders
+### Step 11: Create End-Session Skill Hidden Artifact Directory
+
+**Folder:**
+
+- `docs/plans/.end-session/` — Stores session-end artifacts
+
+**Rationale:** The `end-session/SKILL.md` skill saves a session artifact here for every session-end commit, providing a traceable record of what was done, why, and by which agent.
+
+**Action:** Create the directory if it doesn't exist.
+
+### Step 12: Create Learn Category Folders
 
 **Folders:**
 
@@ -190,6 +200,8 @@ After initialization, verify:
   - `docs/plans/.review/index.md` (review reports registry)
 - ✓ Learn skill hidden artifact directories exist:
   - `docs/plans/.learn/.capture/`, `docs/plans/.learn/.refine/`, `docs/plans/.learn/.index/`, `docs/plans/.learn/.maintain/`
+- ✓ End-session skill hidden artifact directory exists:
+  - `docs/plans/.end-session/`
 - ✓ Learn category folders exist:
   - `docs/learn/decision/`, `docs/learn/pattern/`, `docs/learn/gotcha/`, `docs/learn/workflow/`
 - ✓ Per-plan task indexes created on-demand by plan skill: `docs/tasks/<plan-id>/index.md` (created when Tasks phase runs)
@@ -203,6 +215,7 @@ Downstream skills (plan, learn, work, review) automatically create missing folde
 - **work** skill creates missing `docs/plans/.work/` directories (`.triage/`, `.prepare/`, `.execute/`, `.review/`) on first execution.
 - **review** skill creates missing `docs/plans/.review/` directories and `index.md` registry on first review.
 - **learn** skill creates missing `docs/plans/.learn/` directories and `docs/learn/` category folders on first learning capture.
+- **end-session** skill creates missing `docs/plans/.end-session/` directory (and the `## Session Ends` section in `docs/plans/index.md`) on first session end.
 
 **However**, running `arreio-init` upfront provides several benefits:
 

package/skills/end-session/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: end-session
+description: "Create a single clear commit at session end capturing state. Saves a session artifact to docs/plans/.end-session/ with agent attribution from file changes."
+argument-hint: "[Optional: reason for ending session]"
+disable-model-invocation: true
+version: 2.0.0
+timestamp: "2026-09-01"
+---
+
+# End Session
+
+Create a well-documented commit when a work session ends, with a persistent session artifact for continuity.
+
+## Usage
+
+```text
+/end-session                           # End current session
+/end-session "switching to bugfix"     # End with context note
+```
+
+## Workflow
+
+### 1. Pre-flight: Verify Changes
+
+1. Check working tree for modifications
+2. If no changes, inform the user and exit
+3. Show list of changed files; ask if all should be included
+4. Create `docs/plans/.end-session/` if missing (self-healing)
+
+**Critical failure:** Working tree is unreadable or inaccessible → exit with error.
+
+### 2. Confirm & Prepare
+
+1. Ask user: "Ready to end this session?" (yes/no)
+2. If no, list incomplete work and exit
+3. Draft commit message:
+   - Subject: imperative mood, ≤50 chars, no period (e.g., "Add feature" not "Added")
+   - Body: explain **why**, not what; include skills used (e.g., "Used: -plan, -work")
+   - Add `[AGENT: {AGENT_NAME}]` as last line (mandatory)
+4. Show message for user approval; allow edits
+
+**Critical failure:** User declines or message is empty after body prompt → exit without committing.
+
+### 3. Create & Record
+
+1. Stage approved files and create commit
+2. Capture commit SHA
+3. Allocate session ID: `YYYY-MM-DD-NNN` (date + sequential counter)
+4. Write session artifact to `docs/plans/.end-session/<session-id>.md`
+5. Register in `docs/plans/index.md` under `## Session Ends` (create section if missing)
+6. Report: commit SHA + artifact path + suggest `/learn maintain` if learnings were touched
+
+**Critical failure:** Commit creation fails or artifact write fails → surface error with SHA (if captured) so user can recover manually.
+
+## Session Artifact Format
+
+```markdown
+---
+type: session
+session-id: 2026-09-01-001
+timestamp: "2026-09-01T14:30:00"
+commit-sha: "<short sha>"
+agent: "<agent name>"
+files-changed: <count>
+status: complete
+---
+
+# Session End: <commit subject>
+
+## Reason
+
+<context note or "session complete">
+
+## Changed Files
+
+- <path> (added | modified | deleted)
+
+## Commit Message
+
+<verbatim subject + body>
+
+## Next Steps
+
+<open todos or "none">
+```
+
+## Requirements
+
+- **Changes required**: session ends only if there are staged changes
+- **User approval**: commit message always shown before committing
+- **No push**: changes remain local; user pushes manually
+- **Attribution**: `[AGENT: ...]` trailer derived from session file changes (current agent if mixed)
+- **Artifact**: saved to `docs/plans/.end-session/` and indexed in `docs/plans/index.md`
+
+## References
+
+| Reference                                         | Purpose                                   |
+| ------------------------------------------------- | ----------------------------------------- |
+| [error-handling.md](references/error-handling.md) | Critical failure modes and recovery steps |

package/skills/end-session/references/error-handling.md

@@ -0,0 +1,80 @@
+---
+title: Error Handling & Recovery
+description: Critical failure modes and recovery steps for end-session
+type: reference
+version: 2.0
+timestamp: "2026-09-01"
+---
+
+# Error Handling & Recovery
+
+Minimal reference for critical failures only. Surface errors explicitly; never silently skip or fabricate data.
+
+## Critical Failures (Exit Immediately)
+
+| Scenario                                                        | Recovery Action                                            |
+| --------------------------------------------------------------- | ---------------------------------------------------------- |
+| Working tree is unreadable (repo access issue)                  | Log error; ask user to verify repository is accessible     |
+| Working tree is clean (no changes)                              | Inform user, exit gracefully (nothing to commit)           |
+| User declines session completion (Phase 2)                      | List incomplete work, exit without committing              |
+| Commit message is empty or invalid                              | Re-prompt user; never commit with placeholder              |
+| Commit creation fails (identity not configured, hook rejection) | Log failure reason; do not fabricate SHA; suggest fix      |
+| File write fails (artifact or index permission denied)          | Log error; provide commit SHA so user can recover manually |
+
+## Self-Healing (Non-Blocking)
+
+- **Missing `docs/plans/.end-session/`** → create it automatically
+- **Missing `## Session Ends` in `docs/plans/index.md`** → create section before appending
+- **Missing `docs/plans/index.md` entirely** → create minimal index with section
+
+## User Decisions Always Required
+
+- Confirm session completion (Phase 2)
+- Approve commit message before committing
+- Approve staging files before commit creation
+
+4. If terminate = Yes: stop and inform the user with:
+   - Error category and trigger
+   - Recovery action attempted
+   - Reason for termination
+5. If terminate = No: after recovery, continue to the next step of the phase
+
+````
+
+## Retry Limits
+
+- **Maximum retries per error:** 1
+- **Maximum total retries per phase:** 2
+- After exhausting retries, terminate with a clear error explaining what failed and suggesting the user resolve the underlying issue and re-run `/end-session`.
+
+## Error Reporting Format
+
+When reporting an error to the user, use this format:
+
+```yaml
+error:
+  phase: pre-flight | confirm-completion | prepare-commit | create-commit | save-artifact | post-commit
+  step: 0 | 1 | 2 | ...
+  category: 1 | 2 | 3 | 4 | 5 | 6
+  trigger: "[specific trigger description]"
+  recovery_attempted: "[action taken]"
+  outcome: recovered | terminated
+  suggestion: "[next step for the user]"
+````
+
+## Cross-Phase Consistency Checks
+
+| Check                                                                      | Action on Failure                                        |
+| -------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `interactionMode` is identical across all phases                           | Log warning; use the earliest non-default value          |
+| Change list in Phase 3/4 matches the Pre-flight list (no silent additions) | Reject; return to Pre-flight                             |
+| Session artifact `commit-sha` matches the commit reported in Phase 4       | Reject the artifact; re-run Phase 5 with the correct SHA |
+| Session artifact `agent` matches the attribution confirmed in Phase 3      | Reject the artifact; re-run Phase 5                      |
+| `session-id` date matches today's date                                     | Reject; re-allocate the session-id                       |
+
+## Notes
+
+- All errors and warnings should be logged with a timestamp for debugging.
+- Graceful exits (clean tree, user-declined completion) are **not** failures — they are valid outcomes of Phases 1–2 and must be reported as such.
+- The skill is not resume-safe by design: a failed session end is re-run from Phase 1 with a fresh look at the working tree. The only idempotent write is the session artifact (overwrite on the same `session-id`, never duplicate).
+- This reference is shared by all six phases; phase-specific handling is documented inline in the SKILL.md workflow.