@getpipher/workspace 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/workspace",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Workspace & context-management skills — repo catch-up, AGENTS.md initialization, ecosystem context-file architecture, doc organization, planning sync, and cross-session handoff. Host-neutral: any AGENTS.md-aware coding agent.",
   "keywords": [
     "pi-package",

package/skills/catch-up/SKILL.md

@@ -11,6 +11,8 @@ Bismillah! Let me show you where we are and what we just did.
 
 Let me gather complete context for you:
 
+0. **Handoff check** — If `$HANDOFF_VAULT/{project}/` (`$HANDOFF_VAULT` defaults to `~/.local/handoffs`) contains session handoffs, surface the newest one (`ls "$HANDOFF_VAULT"/{project}/session-handoff-*.md | sort -r | head -1`) and offer to render its starter prompt before gathering git state.
+
 1. **Extract Mission & Purpose**
    - Read the project context file — `AGENTS.md` (or `CLAUDE.md`, CC's legacy name) — first, for Repository Overview and Tech Stack
    - Fallback to README.md if no context file exists

package/skills/session-handoff/SKILL.md

@@ -18,7 +18,9 @@ Create a starter prompt file that a fresh session can use to continue work witho
 
 ## Output
 
-Write to: `$HANDOFF_VAULT/{project}/session-handoff-{YYYY-MM-DD}.md` (default `$HANDOFF_VAULT`=`~/.local/handoffs`)
+Write to: `$HANDOFF_VAULT/{project}/session-handoff-{YYYY-MM-DD}.md` (default `$HANDOFF_VAULT`=`~/.local/handoffs` — the canonical vault). `$HANDOFF_VAULT` is set machine-globally in the shell profile, never per-session. Durability/backup of the vault is an out-of-band concern (mirror/sync jobs) — never a reason to write elsewhere.
+
+`{project}` = the working directory's repo/bucket folder name (for bug-bounty hunts: the per-target hunt folder name `<platform>-<program>`). Flat, single segment — never a nested path.
 
 If a handoff file already exists for today, append a letter suffix (e.g., `-b`, `-c`).
 
@@ -43,7 +45,7 @@ A **progress table** sits near the top of the handoff (between the header block
 
 **Generate a progress table when ANY apply:**
 
-1. **Predecessor handoff has one** — `ls -t "$HANDOFF_VAULT"/{project}/session-handoff-*.md | head -1` contains `## Progress Table`. Chain consistency > per-session re-evaluation.
+1. **Predecessor handoff has one** — `ls "$HANDOFF_VAULT"/{project}/session-handoff-*.md | sort -r | head -1` contains `## Progress Table`. Chain consistency > per-session re-evaluation. (Reverse-lexicographic sort, not mtime — the `YYYY-MM-DD[-letter]` naming is lexicographically ordered; mtime lies on restore/copy/sync.)
 2. **User explicitly requested** — prompt contains "MUST include progress table" or "include the progress table".
 3. **Work has numbered discrete units** — multi-phase plan with slices/tasks (e.g., "Slice 5.7 done, next 5.8"), or stacked PR chain where order matters.
 4. **More than 3 PRs/issues stacked across sessions** — flat bullet list becomes unscannable.
@@ -61,7 +63,7 @@ A **progress table** sits near the top of the handoff (between the header block
 1. **Find the most recent predecessor handoff** for this project:
 
    ```bash
-   ls -t "$HANDOFF_VAULT"/{project}/session-handoff-*.md 2>/dev/null | head -1
+   ls "$HANDOFF_VAULT"/{project}/session-handoff-*.md 2>/dev/null | sort -r | head -1
    ```
 
    Locate its `## Progress Table` section.
@@ -169,9 +171,22 @@ pbpaste  # macOS — expected: the handoff path
 
 If the clipboard tool isn't available (e.g., remote SSH session without clipboard forwarding), skip silently — don't treat it as an error. The Confirm step still shows the path as text.
 
-### Step 6: Update MEMORY.md
+### Step 6: Update the project chain index
+
+Maintain `$HANDOFF_VAULT/{project}/MEMORY.md` — the ONLY hand-maintained index:
+
+```markdown
+# {Project} — Handoff Chain Index
+
+|Date|Handoff|State at handoff|
+|---|---|---|
+|{date}|{filename}|{one-line state}|
+
+## Standing context
+- {spec of record / conventions / frozen facts — items that outlive any single handoff}
+```
 
-Add a pointer to the handoff file and update any stale progress entries.
+Add the new row at the bottom (newest last); update stale state lines while there. The global vault-level `MEMORY.md` (if present) is GENERATED by tooling — never hand-edit it.
 
 ### Step 7: Confirm
 
@@ -195,7 +210,7 @@ The new session performs the mirror action on arrival: the starter prompt (Step
 - **No secrets in the prompt** — API keys, passwords, keypairs stay out
 - **Specific over general** — "execute Task 3 in docs/plans/foo.md" beats "continue the work"
 - **Include gotchas** — anything surprising or non-obvious that would trip up a fresh session
-- **Private vault only** — `$HANDOFF_VAULT` (default `~/.local/handoffs`) should be a private/encrypted location, safe for strategy context. Override `$HANDOFF_VAULT` to your own private vault (e.g. an iCloud-synced or encrypted dir).
+- **Private vault only** — the vault must be a private, local, strategy-safe location. `~/.local/handoffs` is the canonical home; durability is provided by an out-of-band mirror, not by writers choosing alternate locations.
 - **Progress table is part of the chain contract** — once a chain starts using a progress table, every handoff in the chain MUST include + update it. Skipping breaks scannability for the next session and forces a rebuild from prior handoffs.
 - **Progress table echo is the closer, not the full handoff** — Step 7's inline table is a snapshot for the current chat. The handoff file (`.md`) is the durable artifact. Don't paraphrase or trim the table when echoing — render it verbatim.
 - **Opener-echo mirrors the closer** — when a progress table exists, the starter prompt's FIRST instruction MUST be "render the table before doing anything." Embed the table inside the starter-prompt block (Step 4), not as a file reference, so it survives the user pasting the prompt alone. The fresh session renders it as its first action — a "where we left off" snapshot symmetric to Step 7's "where we ended" closer. No table generated → no opener-echo.