From f5a6a5bfcc97fbe5e0074cb95b163ee8ad41d9c2 Mon Sep 17 00:00:00 2001 From: Kisa Date: Wed, 24 Jun 2026 10:13:33 -0400 Subject: [PATCH] docs+state: Pi Option B research versioning design delivered, content dir created [Pi] --- context/current-state.md | 7 +- docs/research-versioning-design-2026-06-24.md | 301 ++++++++++++++++++ 2 files changed, 305 insertions(+), 3 deletions(-) create mode 100644 docs/research-versioning-design-2026-06-24.md diff --git a/context/current-state.md b/context/current-state.md index bd28a21..07f3cea 100644 --- a/context/current-state.md +++ b/context/current-state.md @@ -2,11 +2,12 @@ v:1 # current-state -ACTIVE: Pi designed and persisted the full delegation router system (doc + extension + 2 skills) from the brief. Pi-side trigger extension is live (dispatch-trigger.ts in ~/.pi/agent/extensions/). Claude builds the Claude-side trigger (dispatch-trigger.sh + settings.json hook) + dispatch threshold edits from the design doc. Both skills (delegation-discipline, design-review-persist) exist in ~/.claude/skills/. -NEXT (agent, in order): (1) Pi: re-design option b — broaden git auto-versioning to research artifacts (policy/regulatory docs, TriLane-fed intelligence, blog) for the research workflow. (2) Claude: build the Claude-side trigger from Pi's design doc (dispatch-trigger.sh + settings.json UserPromptSubmit hook + dispatch threshold edits). (3) Claude: build the readiness model (rename coverage->readiness, rules-to-config, patient/line/shipment grouping + verdict, device-keyed override+recompute, require-plan-type + remove guesser, frontend nesting). (4) Claude: review Pi's AIOS + Automated Blog plans and recommend. MCP parity + skills-as-git-repo = phase 2. +ACTIVE: Both Pi design tasks delivered: (1) delegation-router full system (design doc + Pi trigger extension + 2 skills), (2) Option B research artifact versioning (design doc + Pi auto-stage extension + research-versioning skill + content dir). All Pi-side code is live — Pi has enabled the dispatch-trigger and research-versioning extensions. Claude builds from both design docs. +NEXT (agent, in order): (1) Claude: build the Claude-side trigger from Pi's design doc at docs/delegation-router-design-2026-06-24.md (dispatch-trigger.sh + settings.json UserPromptSubmit hook + dispatch threshold edits to dispatch SKILL.md). (2) Claude: build the research-auto from Pi's design doc at docs/research-versioning-design-2026-06-24.md (research-autopush.sh + settings.json Stop hook entry + content/ dir). (3) Claude: build the readiness model (rename coverage->readiness, rules-to-config, patient/line/shipment grouping + verdict, device-keyed override+recompute, require-plan-type + remove guesser, frontend nesting). (4) Claude: review Pi's AIOS + Automated Blog plans and recommend. (5) Kisa: /pilot-prep for labABLE Fri 2026-06-26 1:30 PM. MCP parity + skills-as-git-repo = phase 2. ## Decisions (last 8) +- 2026-06-24 [Pi]: Option B research artifact auto-versioning designed and persisted to docs/research-versioning-design-2026-06-24.md. Pi-side extension (research-versioning.ts) auto-stages research files on write. Skill (research-versioning) added to shared skills. Content dir (signal/content/blog/) created. Claude builds research-autopush.sh + settings.json hook entry. - 2026-06-24 [Pi]: Delegation router full design persisted to docs/delegation-router-design-2026-06-24.md (trigger keyword sets + injected text + hook config + dispatch thresholds + Pi-side mirror extension + two process skills). Pi-side trigger extension written to ~/.pi/agent/extensions/dispatch-trigger.ts (before_agent_start event, keyword heuristics). Skills deployed: delegation-discipline (shared tier 2) + design-review-persist (fixes the persist gap — Pi writes files before declaring done). Claude builds Claude-side trigger + threshold edits from the design doc. - 2026-06-24 [CC]: AIOS-as-a-consulting-business PARKED (pipeline, not ruled out) per Kisa + problem-solver. Signal stays the product; AIOS *thinking* (connectors, internal OS, automated blog) stays active. Activate only on demand-pull + Signal self-sustaining (~2-3 paying contracts) + delegable capacity. Memory: project_aios_consulting_parked. Next groundwork: the automated SEO blog (coach-endorsed, compounds for Signal). - 2026-06-24 [CC]: AUDIT for missed Pi cues. Pi made ZERO file-writes across all its sessions; recovered its Signal AIOS + Automated Blog plans from session log 019ef117 to docs/aios-and-blog-2026-06-22-pi-recovered.md. Shield is persisted (file + rich TriLane compliance/competitor research). Kisa's goal: a sellable Signal AIOS; interpretation fork + sttil-compliance-check gate pending before groundwork. @@ -42,4 +43,4 @@ NEXT (agent, in order): (1) Pi: re-design option b — broaden git auto-versioni State protocol: read = `git pull --rebase` then read this file (warn if Updated > 24h old); write = edit ACTIVE/NEXT, append one author-stamped decision, then commit + push. Full protocol in the `state-sync` skill. TriLane = searchable archive, not live state. -## Updated: 2026-06-24 (Pi: session resume. Pi designed and persisted delegation router system — trigger extension live, 2 skills deployed, design doc at docs/delegation-router-design-2026-06-24.md. Applied design-review-persist skill before declaring done.) +## Updated: 2026-06-24 (Pi: session resume + continue. Both Pi design tasks delivered: delegation router system and Option B research artifact versioning. Pi made 8 file writes this session — the persist gap is closed.) diff --git a/docs/research-versioning-design-2026-06-24.md b/docs/research-versioning-design-2026-06-24.md new file mode 100644 index 0000000..e951a93 --- /dev/null +++ b/docs/research-versioning-design-2026-06-24.md @@ -0,0 +1,301 @@ +# Option B: Research Artifact Auto-Versioning — Pi Design + +**Date:** 2026-06-24 +**Design by:** Pi +**Builds by:** Claude (Stop hook) + Pi (skill) +**Approves:** Kisa +**Source:** docs/delegation-router-design-2026-06-24.md, task (2) — broaden auto-versioning from current-state.md to research artifacts + +--- + +## Problem + +Research artifacts — policy analyses, regulatory intelligence from TriLane, competitive research, automated blog drafts — are currently versioned only when someone remembers to commit them. The workflow-consolidation work scoped the auto-push Stop hook to a single file (`context/current-state.md`). Research artifacts fall outside that scope and drift out of sync. + +## Design: Hybrid Research Versioning System + +Three complementary layers, each with a different trigger and scope: + +| Layer | Trigger | Scope | Guarantee | +|-------|---------|-------|-----------| +| **Stop hook** (automatic) | Session stop | Known research directories | Committed every session | +| **Skill discipline** (agent-guided) | Research task completion | Any research output | Agents remember to commit | +| **Pi extension** (event-driven) | Write to research path | Research files written by Pi | Auto-stages mid-session | + +--- + +## Layer 1: Stop Hook — Broadened Research Auto-Push + +A second Stop hook entry in `settings.json` that auto-commits research directories. Separate from `state-autopush.sh` so research artifacts and session state have independent commit histories. + +### Directories Scoped + +``` +signal/research/ — CGM/DMEPOS market research, compliance intelligence, competitive analysis +signal/docs/compliance/ — Compliance docs (data handling, privacy, incident response) +signal/content/ — Blog drafts, outlines, published posts (created if doesn't exist) +``` + +### Exclusion Rules + +Do NOT version: + +- Raw scraped HTML or JSON from external sources +- Files over 500KB +- Temporary or scratch files (`*.tmp`, `scratch-*`, `draft-*-wip.md`) +- Files in `node_modules/`, `venv/`, `__pycache__/`, `.venv/` +- Files matching `.gitignore` patterns + +### The Script + +File: `~/.claude/hooks/research-autopush.sh` + +```bash +#!/bin/bash +# research-autopush.sh — on Claude Code session stop, commit + push research artifacts. +# Broader scope than state-autopush.sh: covers signal/research/, docs/compliance/, content/. +# Deliberately scoped to known directories. Never `git add .`. + +REPO="/Users/sttil-solutions/projects/signal" +EXCLUDE_PATTERNS="*.tmp scratch-* draft-*-wip.md *.json *.html" +DIRS=("research" "docs/compliance" "content") + +cd "$REPO" 2>/dev/null || exit 0 + +# Check each directory for changes +HAS_CHANGES=0 +for DIR in "${DIRS[@]}"; do + [ -d "$DIR" ] || continue + if ! git diff --quiet -- "$DIR" || ! git diff --cached --quiet -- "$DIR"; then + HAS_CHANGES=1 + break + fi +done + +[ "$HAS_CHANGES" -eq 0 ] && exit 0 + +# Build exclude args +EXCLUDE_ARGS=() +for PATTERN in $EXCLUDE_PATTERNS; do + EXCLUDE_ARGS+=(-- "(:(exclude)$PATTERN)") +done + +# Add only the scoped directories, respecting exclude patterns +for DIR in "${DIRS[@]}"; do + [ -d "$DIR" ] || continue + git add "$DIR" "${EXCLUDE_ARGS[@]}" 2>/dev/null +done + +# Check if anything was actually staged +if git diff --cached --quiet; then + exit 0 +fi + +git commit -q -m "research: auto-push research artifacts on session stop [hook]" || exit 0 + +# Sync from canonical (Forgejo origin) before pushing; never force +if ! git pull --rebase origin main >/dev/null 2>&1; then + echo "research-autopush: rebase conflict — nothing pushed, resolve manually in $REPO" >&2 + exit 0 +fi + +if git push origin main >/dev/null 2>&1; then + echo "research-autopush: research artifacts pushed to origin (Forgejo)" >&2 +else + echo "research-autopush: push failed — run 'git push' in $REPO" >&2 +fi +exit 0 +``` + +### Settings.json Addition + +Add to the `hooks.Stop` array in `~/.claude/settings.json`: + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "bash /Users/sttil-solutions/.claude/hooks/research-autopush.sh", + "timeout": 30, + "statusMessage": "Syncing research artifacts to git" + } + ] + }, + { + "hooks": [ + { + "type": "command", + "command": "bash /Users/sttil-solutions/.claude/hooks/state-autopush.sh", + "timeout": 30, + "statusMessage": "Syncing current-state.md to git" + } + ] + } + ] + } +} +``` + +**Order matters:** research-autopush.sh runs first (more data, longer potential conflict window), then state-autopush.sh (single file, fast). Both are non-blocking — failures are logged, not fatal. + +--- + +## Layer 2: Skill Discipline — Research Versioning Skill + +A shared skill that agents follow when producing research artifacts. Makes versioning a conscious step in the research workflow, not just an automatic afterthought. + +File: `~/.claude/skills/research-versioning/SKILL.md` + +```markdown +--- +name: research-versioning +description: Agents follow this when producing research artifacts — regulatory analysis, TriLane intelligence, competitive research, blog content. Ensures research is committed before session end, not lost to drift. +metadata: + type: process +--- + +# Research Versioning + +## Where Research Lives + +| Artifact Type | Directory | Example | +|---------------|-----------|---------| +| Market / compliance research | `signal/research/` | `signal/research/cgm-payer-policy-2026-06.md` | +| Compliance documentation | `signal/docs/compliance/` | `signal/docs/compliance/data-handling.md` | +| Blog content | `signal/content/` | `signal/content/blog/why-readiness-matters.md` | + +File naming: `-YYYY-MM.md` for research, `-YYYY-MM-DD.md` for blog posts. + +## When to Save + +1. **After every meaningful research output** — not only at session end +2. **Before switching context** — if you move from research to build, commit research first +3. **At session end** — the Stop hook catches anything missed + +## What to Exclude + +Do NOT commit: +- Raw scraped data (HTML, JSON dumps, API responses) +- Working drafts (use `-wip.md` suffix to auto-exclude) +- Files over 500KB +- Files already covered by `.gitignore` + +## Speed + +`git commit -m "research: [agent]"` is fast enough. Use `git push` deliberately — pushing is not required every commit, but all commits should be pushed by session end. + +## Interaction with Stop Hook + +The Stop hook (research-autopush.sh) catches anything you missed. Treat it as a safety net, not your primary commit strategy — regular commits give you better history and conflict resolution. +``` + +--- + +## Layer 3: Pi Extension — Research Write Watcher + +For Pi sessions, an extension that auto-stages research files when they're written. Catches mid-session writes before the Stop hook fires. + +File: `~/.pi/agent/extensions/research-versioning.ts` + +```typescript +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; + +/** + * research-versioning.ts — Auto-stages research artifacts when written via Pi's tools. + * Catches mid-session writes before the Stop hook fires at session end. + * Reversible: remove or rename this file, then run /reload. + */ + +const RESEARCH_PATTERNS = [ + /^\/Users\/sttil-solutions\/projects\/signal\/research\//, + /^\/Users\/sttil-solutions\/projects\/signal\/docs\/compliance\//, + /^\/Users\/sttil-solutions\/projects\/signal\/content\//, +]; + +const EXCLUDE_PATTERNS = [/\.tmp$/, /scratch-/, /draft-.*-wip\.md$/, /\.json$/, /\.html$/]; + +export default function (pi: ExtensionAPI) { + pi.on("tool_call", async (event, ctx) => { + if (event.toolName !== "write" && event.toolName !== "edit") return; + + const path = event.input.path as string | undefined; + if (!path) return; + + // Check if path matches a research directory + const isResearch = RESEARCH_PATTERNS.some((p) => p.test(path)); + if (!isResearch) return; + + // Check exclusion patterns + const isExcluded = EXCLUDE_PATTERNS.some((p) => p.test(path)); + if (isExcluded) return; + + // Silent auto-stage — no UI noise, just ensures the file is tracked + try { + const repoDir = "/Users/sttil-solutions/projects/signal"; + const { execSync } = await import("node:child_process"); + execSync(`git add "${path}"`, { cwd: repoDir, stdio: "ignore" }); + } catch { + // Non-blocking: silent failure, the Stop hook will catch it + } + }); +} +``` + +--- + +## Directory Setup + +Create the content directory if it doesn't exist: + +```bash +mkdir -p /Users/sttil-solutions/projects/signal/content/blog +``` + +The research and compliance directories already exist. + +--- + +## Summary: What Gets Versioned When + +| Scenario | Layer | Trigger | What Happens | +|----------|-------|---------|-------------| +| Claude writes a research file mid-session | Skill (Layer 2) | Agent follows discipline | Git commit | +| Claude finishes a session with research unsaved | Stop hook (Layer 1) | Session stop | `research-autopush.sh` catches it | +| Pi writes a research file mid-session | Extension (Layer 3) | `tool_call` event | Silent git add | +| Pi finishes a session with research unsaved | Stop hook (Layer 1) | Session stop | `research-autopush.sh` catches it | + +--- + +## Implementation Sequence + +| Step | Who | What | Depends On | +|------|-----|------|------------| +| 1 | Claude | Create `research-autopush.sh` + chmod | Nothing | +| 2 | Claude | Edit `settings.json`: add research hook to `Stop` array (before state-autopush) | Step 1 | +| 3 | Claude | Create `~/projects/signal/content/` directory | Step 2 | +| 4 | Claude | Update `.gitignore` if needed (ensure patterns don't conflict) | Step 3 | +| 5 | Pi | Create `research-versioning.ts` extension | Nothing | +| 6 | Pi | Run `/reload` to activate the extension | Step 5 | +| 7 | Pi | Create `research-versioning/SKILL.md` in ~/.claude/skills/ | Nothing | + +--- + +## Reversibility + +- **Stop hook**: Remove the research-autopush entry from `settings.json`. Delete `research-autopush.sh`. +- **Extension**: Remove `research-versioning.ts` from `~/.pi/agent/extensions/` and run `/reload`. +- **Skill**: Delete `~/.claude/skills/research-versioning/SKILL.md`. +- **No state affected**: Stateless design. Old commits remain in git history; new files simply stop being auto-staged. + +--- + +## Future Considerations (Phase 2) + +- **File size detection**: Auto-skip files over 500KB with a check in the bash script +- **External repo**: Research artifacts could eventually live in a separate `signal-research` repo for cleaner Signal commit history +- **TriLane sync**: Research artifacts written from TriLane queries could auto-tag the source session ID in commit messages +- **Content publishing**: Blog posts committed to `signal/content/blog/` could trigger a Railway deploy or webhook for the STTIL website