@aipper/aiws-spec 0.0.28 → 0.0.30

package/templates/workspace/.opencode/lib/aiws-context.js

@@ -0,0 +1,953 @@
+/**
+ * AiwsContext — Shared utility library for aiws OpenCode plugins
+ *
+ * Provides file reading, JSONL parsing (5-field format), session dedup,
+ * change detection, and spec index building.
+ *
+ * Zero external dependencies. All JS, no Python.
+ * Reference: trellis/packages/cli/src/templates/opencode/lib/trellis-context.js
+ */
+
+import { existsSync, readFileSync, appendFileSync, readdirSync, statSync, mkdirSync } from "fs"
+import { join, isAbsolute, relative } from "path"
+
+const DEBUG_LOG = "/tmp/aiws-plugin-debug.log"
+
+export function debugLog(prefix, ...args) {
+  const ts = new Date().toISOString()
+  const msg =
+    `[${ts}] [${prefix}] ${args.map(a => (typeof a === "object" ? JSON.stringify(a) : a)).join(" ")}\n`
+  try {
+    appendFileSync(DEBUG_LOG, msg)
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Check if a string value is non-empty
+ */
+function str(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null
+}
+
+/**
+ * Look up a nested key from an object, trying multiple key names
+ */
+function lookupString(data, keys) {
+  if (!data || typeof data !== "object") return null
+  for (const key of keys) {
+    const v = str(data[key])
+    if (v) return v
+  }
+  // recurse into common wrapper objects
+  for (const nested of ["input", "properties", "event", "hook_input", "hookInput"]) {
+    const v = lookupString(data[nested], keys)
+    if (v) return v
+  }
+  return null
+}
+
+/**
+ * Resolve a relative path against the project directory.
+ * If already absolute, return as-is.
+ */
+function resolvePath(directory, relPath) {
+  if (isAbsolute(relPath)) return relPath
+  return join(directory, relPath)
+}
+
+/**
+ * Read optional numeric sections from a JSONL entry.
+ * Returns null if no sections specified.
+ */
+function parseSections(entry) {
+  const raw = entry.sections
+  if (!Array.isArray(raw) || raw.length === 0) return null
+  return raw.map(s => {
+    if (!Array.isArray(s) || s.length < 2) return null
+    return [Math.max(1, s[0]), Math.max(1, s[1])]
+  }).filter(Boolean)
+}
+
+// ============================================================
+// AiwsContext
+// ============================================================
+
+export class AiwsContext {
+  constructor(directory) {
+    this.directory = directory
+    debugLog("context", "AiwsContext initialized", { directory })
+  }
+
+  // -- Project detection ---------------------------------------
+
+  /** True when this is an aiws-managed project */
+  isAiwsProject() {
+    return (
+      existsSync(join(this.directory, "packages", "spec")) ||
+      existsSync(join(this.directory, "AI_PROJECT.md"))
+    )
+  }
+
+  // -- Session identity -----------------------------------------
+
+  /**
+   * Derive a stable session key from the environment or hook input.
+   *
+   * Priority order (matching trellis getContextKey):
+   *   1. OPENCODE_RUN_ID (set by OpenCode runtime)
+   *   2. input.sessionID (from chat.message or tool.execute.before hook)
+   *   3. input.conversationID
+   *
+   * Returns null when no identity source is available.
+   */
+  getSessionKey(platformInput = null) {
+    const runId = str(process.env.OPENCODE_RUN_ID)
+    if (runId) return `opencode_run_${runId}`
+
+    if (!platformInput || typeof platformInput !== "object") return null
+
+    const sid = lookupString(platformInput, ["session_id", "sessionId", "sessionID"])
+    if (sid) return `session_${sid}`
+
+    const cid = lookupString(platformInput, ["conversation_id", "conversationId", "conversationID"])
+    if (cid) return `conv_${cid}`
+
+    return null
+  }
+
+  // -- File reading ---------------------------------------------
+
+  /** Read a file, returning null on any error */
+  readFile(filePath) {
+    try {
+      if (existsSync(filePath)) return readFileSync(filePath, "utf-8")
+    } catch {
+      // ignore
+    }
+    return null
+  }
+
+  /** Read a file relative to the project root */
+  readProjectFile(relPath) {
+    return this.readFile(resolvePath(this.directory, relPath))
+  }
+
+  // -- JSONL parsing (5-field format) ---------------------------
+
+  /**
+   * Read a JSONL file and load referenced file contents.
+   *
+   * Supports aiws 5-field format:
+   *   {"glob": "path/to/file.md", "sections": [[25,50]], "priority": "high", "kind": "truth", "reason": "why"}
+   *
+   * Returns array of { path, content, priority, kind, reason }
+   * Sorted by priority: high → medium → low
+   */
+  readJsonlWithFiles(jsonlPath) {
+    const content = this.readFile(jsonlPath)
+    if (!content) return []
+
+    const entries = []
+
+    for (const rawLine of content.split(/\r?\n/)) {
+      const line = rawLine.trim()
+      if (!line || line.startsWith("#")) continue
+      try {
+        const item = JSON.parse(line)
+
+        // Resolve glob to actual file
+        const globPattern = item.glob || item.file
+        if (!globPattern) continue
+
+        const priority = item.priority || "medium"
+        const kind = item.kind || "unknown"
+        const reason = item.reason || ""
+        const sections = parseSections(item)
+
+        // Read the file
+        const fullPath = resolvePath(this.directory, globPattern)
+        let fileContent = this.readFile(fullPath)
+        if (!fileContent) continue
+
+        // Apply section filtering if specified
+        if (sections) {
+          const lines = fileContent.split("\n")
+          const filtered = []
+          for (const [start, end] of sections) {
+            const from = Math.max(0, start - 1)
+            const to = Math.min(lines.length, end)
+            filtered.push(...lines.slice(from, to))
+          }
+          fileContent = filtered.join("\n")
+        }
+
+        entries.push({ path: globPattern, content: fileContent, priority, kind, reason })
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    // Sort: high → medium → low
+    const order = { high: 0, medium: 1, low: 2 }
+    entries.sort((a, b) => (order[a.priority] ?? 2) - (order[b.priority] ?? 2))
+
+    return entries
+  }
+
+  // -- Context building ------------------------------------------
+
+  /**
+   * Build injected context text from JSONL entries.
+   * Returns a formatted string with file separators.
+   */
+  buildContextFromEntries(entries) {
+    if (!entries || entries.length === 0) return ""
+    return entries
+      .map(e => {
+        const header = `=== ${e.path} ===${e.reason ? ` (${e.reason})` : ""}`
+        return `${header}\n${e.content}`
+      })
+      .join("\n\n")
+  }
+
+  /** Build context and return a wrapped message block */
+  buildContextBlock(entries) {
+    const body = this.buildContextFromEntries(entries)
+    if (!body) return ""
+    return `<aiws-context>\n${body}\n</aiws-context>`
+  }
+
+  // -- Change detection ------------------------------------------
+
+  /**
+   * Detect currently active change by scanning changes/<id>/.
+   * Returns the most recently modified change's id and detail, or null.
+   */
+  getActiveChange() {
+    const changesDir = join(this.directory, "changes")
+    if (!existsSync(changesDir)) return null
+
+    let dirs
+    try {
+      dirs = readdirSync(changesDir)
+        .filter(name => name !== "archive" && name !== "templates")
+        .map(name => {
+          const full = join(changesDir, name)
+          try {
+            return { name, mtime: statSync(full).mtimeMs, dir: full }
+          } catch {
+            return null
+          }
+        })
+        .filter(Boolean)
+    } catch {
+      return null
+    }
+
+    if (dirs.length === 0) return null
+
+    // Most recently modified directory wins
+    dirs.sort((a, b) => b.mtime - a.mtime)
+    return this.getChangeDetail(dirs[0].name)
+  }
+
+  /**
+   * Get detailed info about a specific change directory.
+   * Scans plan/, analysis/, evidence/, patches/ subdirs.
+   */
+  getChangeDetail(changeId) {
+    const changeDir = join(this.directory, "changes", changeId)
+    if (!existsSync(changeDir)) return null
+
+    const detail = {
+      id: changeId,
+      dir: changeDir,
+      proposal: null,
+      planFiles: [],
+      analysisFiles: [],
+      contextRoles: [],
+      evidenceFiles: [],
+      patchesCount: 0,
+      hasHandoff: false,
+      phase: "unknown",
+    }
+
+    const proposalPath = join(changeDir, "proposal.md")
+    if (existsSync(proposalPath)) {
+      detail.proposal = this.readFile(proposalPath)
+    }
+
+    const planDir = join(changeDir, "plan")
+    if (existsSync(planDir)) {
+      try {
+        detail.planFiles = readdirSync(planDir)
+          .filter(f => f.endsWith(".md"))
+          .sort()
+          .reverse()
+      } catch { /* ignore */ }
+    }
+
+    const analysisDir = join(changeDir, "analysis")
+    if (existsSync(analysisDir)) {
+      try {
+        const files = readdirSync(analysisDir)
+        detail.analysisFiles = files.filter(f => f.endsWith(".md"))
+        detail.contextRoles = files
+          .filter(f => f.endsWith("-context.jsonl"))
+          .map(f => f.replace("-context.jsonl", ""))
+      } catch { /* ignore */ }
+    }
+
+    // Evidence dir
+    const evidenceDir = join(changeDir, "evidence")
+    if (existsSync(evidenceDir)) {
+      try {
+        detail.evidenceFiles = readdirSync(evidenceDir)
+          .filter(f => f.endsWith(".md"))
+      } catch { /* ignore */ }
+    }
+
+    // Patches dir
+    const patchesDir = join(changeDir, "patches")
+    if (existsSync(patchesDir)) {
+      try {
+        detail.patchesCount = readdirSync(patchesDir).length
+      } catch { /* ignore */ }
+    }
+
+    // Handoff
+    detail.hasHandoff = existsSync(join(changeDir, "handoff.md"))
+
+    // Phase estimation
+    detail.phase = this._estimatePhase(detail)
+
+    return detail
+  }
+
+  // State machine: intake → planning → ready-for-dev → in-progress → review → finished
+  static PHASES = [
+    "intake",
+    "planning",
+    "ready-for-dev",
+    "in-progress",
+    "review",
+    "finished",
+  ]
+
+  static PHASE_TRANSITIONS = {
+    intake:        new Set(["planning"]),
+    planning:      new Set(["ready-for-dev", "intake"]),
+    "ready-for-dev": new Set(["in-progress", "planning"]),
+    "in-progress": new Set(["review", "ready-for-dev"]),
+    review:        new Set(["finished", "in-progress"]),
+    finished:      new Set(["intake"]),
+  }
+
+  static isValidTransition(from, to) {
+    const allowed = AiwsContext.PHASE_TRANSITIONS[from]
+    return allowed ? allowed.has(to) : false
+  }
+
+  _estimatePhase(detail) {
+    if (!detail.proposal) return "intake"
+    if (detail.planFiles.length === 0) return "planning"
+    if (detail.hasHandoff) return "finished"
+    if (detail.patchesCount > 0) return "in-progress"
+    if (detail.evidenceFiles.length > 0) return "review"
+    return "ready-for-dev"
+  }
+
+  getPhaseSuggestions(changeId) {
+    const detail = this.getChangeDetail(changeId)
+    if (!detail) return []
+    const current = detail.phase
+    return [...(AiwsContext.PHASE_TRANSITIONS[current] || new Set())]
+  }
+
+  getPhaseSummary(changeId) {
+    const detail = this.getChangeDetail(changeId)
+    if (!detail) return ""
+    const current = detail.phase
+    const suggestions = this.getPhaseSuggestions(changeId)
+    const idx = AiwsContext.PHASES.indexOf(current)
+    const total = AiwsContext.PHASES.length
+    return (
+      `Phase: ${current} (${idx + 1}/${total})\n` +
+      `Valid next: ${suggestions.join(", ") || "(none)"}\n` +
+      `Proposal: ${detail.proposal ? "yes" : "no"}\n` +
+      `Plans: ${detail.planFiles.length}\n` +
+      `Analysis files: ${detail.analysisFiles.length}\n` +
+      `Context JSONLs: ${detail.contextRoles.join(", ") || "none"}\n` +
+      `Evidence: ${detail.evidenceFiles.length}\n` +
+      `Patches: ${detail.patchesCount}\n` +
+      `Handoff: ${detail.hasHandoff ? "yes" : "no"}`
+    )
+  }
+
+  // -- Spec index ------------------------------------------------
+
+  /**
+   * Build an index of packages/spec/docs/*.md files.
+   * Returns a formatted markdown string listing all spec docs with descriptions.
+   */
+  getSpecIndex() {
+    const specDir = join(this.directory, "packages", "spec", "docs")
+    if (!existsSync(specDir)) return ""
+
+    let files
+    try {
+      files = readdirSync(specDir)
+        .filter(f => f.endsWith(".md"))
+        .sort()
+    } catch {
+      return ""
+    }
+
+    if (files.length === 0) return ""
+
+    const parts = ["## packages/spec/docs/ — Spec Index"]
+    for (const f of files) {
+      // Extract first heading as description
+      const content = this.readFile(join(specDir, f))
+      let desc = ""
+      if (content) {
+        const firstH1 = content.match(/^#\s+(.+)/m)
+        const firstH2 = content.match(/^##\s+(.+)/m)
+        desc = firstH1?.[1] || firstH2?.[1] || f.replace(/\.md$/, "")
+      }
+      parts.push(`- \`spec/docs/${f}\` — ${desc}`)
+    }
+
+    return parts.join("\n") + "\n"
+  }
+
+  // -- Change state for continuation / new-session resume -------
+
+  /**
+   * Get the current change state for continuation routing.
+   *
+   * Returns { changeId, phase, lastEvent, lastDelegation, nextAction }
+   *
+   * - `lastEvent`: last breadcrumb event from today's journal (or null)
+   * - `lastDelegation`: last delegation entry from today's journal (or null)
+   * - `nextAction`: derived from phase + delegation status using the
+   *    continuation decision table defined in the using-aiws SKILL.md.
+   *
+   * Safe to call even when no active change or journal exists — returns
+   * a minimal state object with phase="none" and nextAction pointing to
+   * ws-intake/ws-plan.
+   */
+  getChangeState(changeId = null) {
+    const id = changeId || this.getActiveChange()?.id || null
+    if (!id) {
+      return {
+        changeId: null,
+        phase: "none",
+        lastEvent: null,
+        lastDelegation: null,
+        nextAction: "Start with ws-intake or ws-plan to establish a change context",
+      }
+    }
+
+    const detail = this.getChangeDetail(id)
+    const phase = detail?.phase || "unknown"
+
+    // Read today's journal for last event and delegation
+    const journal = new AiwsSessionJournal(this.directory)
+    const todayEntries = journal.readToday()
+    const delegationEntries = todayEntries.filter(e => e.event === "delegation")
+    const breadcrumbEntries = todayEntries.filter(e => e.event === "breadcrumb")
+
+    const lastEvent = breadcrumbEntries.length > 0
+      ? breadcrumbEntries[breadcrumbEntries.length - 1]
+      : null
+
+    const lastDelegation = delegationEntries.length > 0
+      ? delegationEntries[delegationEntries.length - 1]
+      : null
+
+    // Derive next action from continuation decision table
+    const nextAction = this._deriveNextAction(phase, lastDelegation, detail)
+
+    return {
+      changeId: id,
+      phase,
+      lastEvent,
+      lastDelegation,
+      nextAction,
+    }
+  }
+
+  /**
+   * Derive next action from phase + delegation status + detail artifacts.
+   * Mirrors the continuation decision table in using-aiws/SKILL.md.
+   */
+  _deriveNextAction(phase, lastDelegation, detail) {
+    // Check for blocked delegation
+    if (lastDelegation && lastDelegation.status === "BLOCKED") {
+      return `BLOCKED from previous delegation: ${lastDelegation.reason || "unknown reason"}. Resolve blocker before continuing.`
+    }
+
+    // Check for NEEDS_CONTEXT delegation
+    if (lastDelegation && lastDelegation.status === "NEEDS_CONTEXT") {
+      return `NEEDS_CONTEXT: missing context for ${lastDelegation.role || "worker"}. Supplement context and re-dispatch.`
+    }
+
+    // Phase-based routing
+    switch (phase) {
+      case "intake":
+        return "ws-intake or ws-plan to create a change and execution plan"
+      case "planning": {
+        // If plan files exist, recommend verify; otherwise recommend plan
+        if (detail && detail.planFiles.length > 0) {
+          return "ws-plan-verify to review existing plan"
+        }
+        return "ws-plan to complete planning"
+      }
+      case "ready-for-dev":
+        return "dispatch aiws-worker (subagent-first — main session does not write code directly)"
+      case "in-progress": {
+        // If worktree is dirty (patches exist) → recommend reviewer
+        if (detail && detail.patchesCount > 0) {
+          return "dispatch aiws-reviewer + ws-review to audit changes"
+        }
+        // If we have a prior delegation that was DONE_WITH_CONCERNS
+        if (lastDelegation && lastDelegation.status === "DONE_WITH_CONCERNS") {
+          return "ws-quality-review to assess residual risk before continuing"
+        }
+        return "continue implementation or dispatch aiws-reviewer"
+      }
+      case "review": {
+        if (detail && detail.evidenceFiles.length > 0) {
+          return "ws-finish or ws-commit — evidence exists, ready to finalize"
+        }
+        return "collect evidence first, then ws-commit"
+      }
+      case "finished":
+        return "ws-finish to finalize and archive the change"
+      default:
+        return "Review phase and artifacts; consider ws-preflight to reassess"
+    }
+  }
+
+  // -- Git status ------------------------------------------------
+
+  // -- Spec auto-update (P2 #1) ---------------------------------
+
+  /**
+   * Scan the active change's analysis/ directory for spec-update.jsonl.
+   * Returns parsed entries, or empty array if none found.
+   *
+   * Format: same 5-field as context-injection, plus optional "proposal" text.
+   *   {"file": "packages/spec/docs/some-spec.md", "reason": "rule about X missing",
+   *    "sections": [[25,50]], "proposal": "Add: new rule prohibiting async in constructors",
+   *    "priority": "high", "kind": "spec-update"}
+   */
+  scanSpecUpdates(changeId) {
+    const changeDir = join(this.directory, "changes", changeId)
+    if (!existsSync(changeDir)) return []
+
+    const jsonlPath = join(changeDir, "analysis", "spec-update.jsonl")
+    const raw = this.readFile(jsonlPath)
+    if (!raw) return []
+
+    const entries = []
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith("#")) continue
+      try {
+        const item = JSON.parse(trimmed)
+        const filePath = item.file || item.glob
+        if (!filePath) continue
+        entries.push({
+          file: filePath,
+          sections: parseSections(item),
+          priority: item.priority || "medium",
+          kind: item.kind || "spec-update",
+          reason: item.reason || "",
+          proposal: item.proposal || "",
+          status: item.status || "pending",
+        })
+      } catch {
+        // skip malformed lines
+      }
+    }
+
+    return entries
+  }
+
+  /**
+   * Generate structured spec-update alert text from a change's spec-update.jsonl.
+   * For each entry, loads the current spec file content and shows the proposal.
+   */
+  proposeSpecUpdates(changeId) {
+    const entries = this.scanSpecUpdates(changeId)
+    if (entries.length === 0) return ""
+
+    const parts = ["## Spec Updates Pending"]
+    for (const e of entries) {
+      const fullPath = resolvePath(this.directory, e.file)
+      const currentContent = this.readFile(fullPath)
+      const excerpt = currentContent
+        ? currentContent.split("\n").slice(0, 15).join("\n")
+        : "(file not found)"
+
+      parts.push(`\n### ${e.file}`)
+      parts.push(`**Reason:** ${e.reason}`)
+      if (e.proposal) parts.push(`**Proposal:** ${e.proposal}`)
+      parts.push(`**Current (first 15 lines):**\n\`\`\`\n${excerpt}\n\`\`\``)
+    }
+
+    parts.push(
+      "\n**Action required:** Review each proposal. " +
+      "Edit the spec file directly, then update `spec-update.jsonl` with `status: \"applied\"`."
+    )
+
+    return parts.join("\n")
+  }
+
+  /** Get a short git status summary string */
+  getGitStatus() {
+    const head = str(process.env.GIT_HEAD) || null
+    const branch = str(process.env.GIT_BRANCH) || null
+
+    const parts = []
+    if (branch) parts.push(`branch: ${branch}`)
+    if (head) parts.push(`HEAD: ${head.slice(0, 8)}`)
+    return parts.length > 0 ? parts.join(", ") : ""
+  }
+}
+
+// ============================================================
+// Session journal (G11)
+// ============================================================
+
+/**
+ * AiwsSessionJournal — Writes structured JSONL entries to .aiws/journal/.
+ *
+ * Each entry is a single JSONL line with:
+ *   {"ts": "<ISO-time>", "event": "<type>", "session": "<key>", ...data}
+ *
+ * Event types: session_start, delegation, phase_transition, spec_change, milestone
+ */
+export class AiwsSessionJournal {
+  constructor(directory) {
+    this.directory = directory
+    this.journalDir = join(directory, ".aiws", "journal")
+    this._ensureDir()
+  }
+
+  _ensureDir() {
+    try {
+      mkdirSync(this.journalDir, { recursive: true })
+    } catch { /* ignore */ }
+  }
+
+  get _journalPath() {
+    return join(this.journalDir, `${new Date().toISOString().slice(0, 10)}.jsonl`)
+  }
+
+  write(eventType, sessionKey, data = {}) {
+    const entry = JSON.stringify({
+      ts: new Date().toISOString(),
+      event: eventType,
+      session: sessionKey,
+      ...data,
+    })
+    try {
+      appendFileSync(this._journalPath, entry + "\n")
+    } catch { /* ignore */ }
+  }
+
+  readToday() {
+    try {
+      const content = readFileSync(this._journalPath, "utf-8")
+      return content
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map(l => { try { return JSON.parse(l) } catch { return null } })
+        .filter(Boolean)
+    } catch {
+      return []
+    }
+  }
+
+  getRecentSessions(count = 5) {
+    const entries = this.readToday()
+    const seen = new Set()
+    return entries
+      .filter(e => { const k = e.session; return seen.has(k) ? false : (seen.add(k), true) })
+      .slice(-count)
+  }
+
+  /**
+   * Record a delegation event (subagent dispatched).
+   *
+   * Example:
+   *   journal.writeDelegation(sessionKey, "worker", "change-123", {
+   *     taskDescription: "implement auth middleware",
+   *     contextFiles: 3,
+   *   })
+   */
+  writeDelegation(sessionKey, role, changeId, extra = {}) {
+    this.write("delegation", sessionKey, {
+      role,
+      changeId,
+      ...extra,
+    })
+  }
+
+  /**
+   * Record a per-turn breadcrumb event.
+   *
+   * Example:
+   *   journal.writeBreadcrumb(sessionKey, "dev", changeId, { turn: 5 })
+   */
+  writeBreadcrumb(sessionKey, phase, changeId, extra = {}) {
+    this.write("breadcrumb", sessionKey, {
+      phase,
+      changeId,
+      ...extra,
+    })
+  }
+
+  /**
+   * Record a phase transition event.
+   *
+   * Example:
+   *   journal.writePhaseTransition(sessionKey, "planning", "ready-for-dev", changeId)
+   */
+  writePhaseTransition(sessionKey, fromPhase, toPhase, changeId, extra = {}) {
+    this.write("phase_transition", sessionKey, {
+      from: fromPhase,
+      to: toPhase,
+      changeId,
+      ...extra,
+    })
+  }
+
+  /**
+   * Read today's journal and produce a structured summary (markdown).
+   * Returns null if no entries exist for today.
+   *
+   * Summary format:
+   *   ## Session Journal (today)
+   *   - session_start: N entries
+   *   - delegation: N entries (by role: worker=N, explorer=N, ...)
+   *   - breadcrumb: N entries
+   *   - phase_transition: N entries
+   */
+  getJournalSummary() {
+    const entries = this.readToday()
+    if (entries.length === 0) return null
+
+    const counts = {}
+    const roleCounts = {}
+
+    for (const e of entries) {
+      const ev = e.event || "unknown"
+      counts[ev] = (counts[ev] || 0) + 1
+      if (ev === "delegation" && e.role) {
+        roleCounts[e.role] = (roleCounts[e.role] || 0) + 1
+      }
+    }
+
+    const lines = ["## Session Journal (today)"]
+    for (const [ev, n] of Object.entries(counts).sort()) {
+      if (ev === "delegation") {
+        const byRole = Object.entries(roleCounts)
+          .map(([r, n]) => `${r}=${n}`)
+          .join(", ")
+        lines.push(`- **delegation**: ${n} entries (by role: ${byRole})`)
+      } else {
+        lines.push(`- **${ev}**: ${n} entries`)
+      }
+    }
+
+    return lines.join("\n")
+  }
+}
+
+// ============================================================
+// Spec digest (G2)
+// ============================================================
+
+import { createHash } from "crypto"
+
+// sha256 digest of all truth + spec files, hex string or ""
+export function computeSpecDigest(directory) {
+  const targets = [
+    "AI_PROJECT.md",
+    "REQUIREMENTS.md",
+    "AI_WORKSPACE.md",
+  ]
+  const specDir = join(directory, "packages", "spec", "docs")
+  if (existsSync(specDir)) {
+    try {
+      const docs = readdirSync(specDir).filter(f => f.endsWith(".json") || f.endsWith(".md"))
+      for (const d of docs) targets.push(join("packages", "spec", "docs", d))
+    } catch { /* ignore */ }
+  }
+
+  const hash = createHash("sha256")
+  for (const relPath of targets.sort()) {
+    const full = join(directory, relPath)
+    try {
+      const content = readFileSync(full)
+      hash.update(relPath)
+      hash.update("\x00")
+      hash.update(content)
+    } catch { /* skip */ }
+  }
+  return hash.digest("hex")
+}
+
+// ============================================================
+// Session context builder (for session-start plugin)
+// ============================================================
+
+/**
+ * Build the full session-start context block.
+ * This is the aiws equivalent of trellis's buildSessionContext.
+ */
+export function buildSessionContext(ctx, platformInput = null) {
+  const parts = []
+  const digest = computeSpecDigest(ctx.directory)
+  if (digest) {
+    parts.push(`<spec-digest>\n${digest}\n</spec-digest>`)
+  }
+
+  parts.push(`<aiws-context>
+You are starting a new session in an aiws-managed project.
+Read and follow the context below.
+</aiws-context>`)
+
+  const specIndex = ctx.getSpecIndex()
+  if (specIndex) {
+    parts.push("<spec-index>")
+    parts.push(specIndex.trimEnd())
+    parts.push("</spec-index>")
+  }
+
+  const activeChange = ctx.getActiveChange()
+  if (activeChange) {
+    const phaseSummary = ctx.getPhaseSummary(activeChange.id)
+    parts.push("<change-context>")
+    parts.push(phaseSummary)
+    parts.push("</change-context>")
+
+    // Continuation resume recommendation
+    try {
+      const changeState = ctx.getChangeState(activeChange.id)
+      if (changeState && changeState.nextAction) {
+        parts.push("<resume-recommendation>")
+        parts.push("## Continuation / Resume Recommendation")
+        parts.push(`Active Change: ${changeState.changeId}`)
+        parts.push(`Phase: ${changeState.phase}`)
+        if (changeState.lastDelegation) {
+          parts.push(`Last Delegation: ${changeState.lastDelegation.role || "unknown"} (status: ${changeState.lastDelegation.status || "unknown"})`)
+        }
+        parts.push(`Recommended Next: ${changeState.nextAction}`)
+        parts.push("</resume-recommendation>")
+      }
+    } catch {
+      // Non-blocking: resume recommendation is advisory only
+    }
+
+    // P2 #1: Check for pending spec-update proposals
+    const specUpdates = ctx.proposeSpecUpdates(activeChange.id)
+    if (specUpdates) {
+      parts.push(`<pending-spec-update>\n${specUpdates}\n</pending-spec-update>`)
+    }
+  }
+
+  parts.push("<workflow-phases>")
+  parts.push(
+    "## aiws Workflow Phases\n" +
+    "\n" +
+    "The aiws workflow follows a linear pipeline with gates at each stage:\n" +
+    "1. **ws-preflight** — Pre-flight: reads truth files, checks git state, outputs constraints\n" +
+    "2. **ws-plan** — Create change context and execution plan with bindings\n" +
+    "3. **ws-plan-verify** — Review plan before execution\n" +
+    "4. **ws-dev** — Implementation against plan\n" +
+    "5. **ws-review** — Audit changes against spec\n" +
+    "6. **ws-commit** — Validate and commit\n" +
+    "7. **ws-finish** — Finalize and archive change\n" +
+    "8. **ws-deliver** — Push to remote\n" +
+    "\n" +
+    "Each phase has required inputs, outputs, and verification gates. " +
+    "See `packages/spec/docs/workflow-stage-contracts.json` for stage details."
+  )
+  parts.push("</workflow-phases>")
+
+  // -- Journal summary (today's delegation/breadcrumb activity)
+  const journal = new AiwsSessionJournal(ctx.directory)
+  const journalSummary = journal.getJournalSummary()
+  if (journalSummary) {
+    parts.push(`<journal-summary>\n${journalSummary}\n</journal-summary>`)
+  }
+
+  // -- Git status
+  const gitStatus = ctx.getGitStatus()
+  if (gitStatus) {
+    parts.push(`<git-status>\n${gitStatus}\n</git-status>`)
+  }
+
+  // Guidelines
+  parts.push("<guidelines>")
+  parts.push(
+    "Spec files are listed above under <spec-index> (digest: see <spec-digest>). " +
+    "If the digest changed from the previous session, re-read any spec files that may have been updated.\n" +
+    "When delegating sub-agents, include role markers (e.g. 'role: worker') so the inject-context plugin provides the correct JSONL context.\n" +
+    "If an active change is shown above, work inside that change context."
+  )
+  parts.push("</guidelines>")
+
+  const sessionKey = ctx.getSessionKey(platformInput)
+  if (sessionKey) {
+    journal.write("session_start", sessionKey, {
+      change: activeChange?.id || null,
+      phase: activeChange?.phase || null,
+      digest,
+    })
+  }
+
+  return parts.join("\n\n")
+}
+
+// ============================================================
+// Context Collector (session dedup — singleton)
+// ============================================================
+
+export class AiwsContextCollector {
+  constructor(maxSize = 200) {
+    this.processed = new Set()
+    this.maxSize = maxSize
+  }
+
+  markProcessed(sessionKey) {
+    this.processed.add(sessionKey)
+    this._trim()
+  }
+
+  isProcessed(sessionKey) {
+    return this.processed.has(sessionKey)
+  }
+
+  clear(sessionKey) {
+    this.processed.delete(sessionKey)
+  }
+
+  _trim() {
+    if (this.processed.size <= this.maxSize) return
+    // Set preserves insertion order; drop oldest entries
+    const entries = [...this.processed]
+    const overflow = entries.length - this.maxSize
+    this.processed = new Set(entries.slice(overflow))
+  }
+}
+
+/** Singleton instance */
+export const contextCollector = new AiwsContextCollector()