@aperant/framework 0.10.0 → 0.11.0

package/package.json

@@ -1,139 +1,139 @@
 {
-  "name": "@aperant/framework",
-  "version": "0.10.0",
-  "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
-  "author": "Mikalsen AI <hello@mikalsen.ai>",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "framework": "./bin/apt-tools.mjs",
-    "apt-tools": "./bin/apt-tools.mjs",
-    "apt-proof-video": "./bin/apt-proof-video.mjs"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/types/index.js"
-    },
-    "./cost": {
-      "types": "./dist/cost/index.d.ts",
-      "import": "./dist/cost/index.js"
-    },
-    "./mappers": {
-      "types": "./dist/mappers/index.d.ts",
-      "import": "./dist/mappers/index.js"
-    },
-    "./schemas": {
-      "types": "./dist/schemas/index.d.ts",
-      "import": "./dist/schemas/index.js"
-    },
-    "./standalone": {
-      "types": "./dist/standalone/index.d.ts",
-      "import": "./dist/standalone/index.js"
-    },
-    "./driver-sdk": {
-      "types": "./dist/driver-sdk/index.d.ts",
-      "import": "./dist/driver-sdk/index.js"
-    },
-    "./coordination/event-schema": {
-      "types": "./src/cli/coordination/event-schema.d.ts",
-      "import": "./src/cli/coordination/event-schema.mjs"
-    },
-    "./roadmap/conductor-view": {
-      "types": "./src/cli/roadmap/conductor-view.d.ts",
-      "import": "./src/cli/roadmap/conductor-view.mjs"
-    },
-    "./design/scan": {
-      "import": "./src/cli/design/scan.mjs"
-    },
-    "./design/extract-repo": {
-      "import": "./src/cli/design/extract-repo.mjs"
-    },
-    "./design/synthesize": {
-      "import": "./src/cli/design/synthesize.mjs"
-    }
-  },
-  "files": [
-    "dist/",
-    "bin/",
-    "src/cli/",
-    "src/cost/",
-    "commands/",
-    "skills/",
-    "agents/",
-    "prompts/",
-    "templates/",
-    "context/",
-    "workflows/",
-    "drivers/",
-    "examples/",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md",
-    "!**/__tests__/**",
-    "!**/*.test.*",
-    "!**/*.spec.*",
-    "!**/*.test.d.ts.map",
-    "!**/*.test.js.map"
-  ],
-  "keywords": [
-    "ai",
-    "framework",
-    "coding-assistant",
-    "claude-code",
-    "codex",
-    "aperant"
-  ],
-  "license": "AGPL-3.0-only",
-  "homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
-  "bugs": {
-    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
-    "directory": "packages/framework"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@clack/prompts": "^1.2.0",
-    "proper-lockfile": "^4.1.2",
-    "yaml": "^2.8.3",
-    "zod": "^4.3.6"
-  },
-  "optionalDependencies": {
-    "@babel/parser": "^7.29.2",
-    "@babel/traverse": "^7.29.0",
-    "@google/genai": "^1.50.1",
-    "css-tree": "^3.2.1",
-    "playwright": "^1.59.1"
-  },
-  "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.5"
-  },
-  "scripts": {
-    "build": "tsc && node scripts/extract-personas-schema.mjs",
-    "dev": "tsc --watch --preserveWatchOutput",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check . --diagnostic-level=error",
-    "lint:fix": "biome check --write . --diagnostic-level=error",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "c28:cutover": "node scripts/c28-cutover.mjs",
-    "build-plugin": "node scripts/build-plugin.mjs",
-    "publish-plugin": "node scripts/publish-plugin.mjs",
-    "publish:verdaccio": "node scripts/publish-verdaccio.mjs",
-    "release:verdaccio": "pnpm build && pnpm publish:verdaccio",
-    "ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
-  }
-}
+	"name": "@aperant/framework",
+	"version": "0.11.0",
+	"description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
+	"author": "Mikalsen AI <hello@mikalsen.ai>",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"bin": {
+		"framework": "./bin/apt-tools.mjs",
+		"apt-tools": "./bin/apt-tools.mjs",
+		"apt-proof-video": "./bin/apt-proof-video.mjs"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./types": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/types/index.js"
+		},
+		"./cost": {
+			"types": "./dist/cost/index.d.ts",
+			"import": "./dist/cost/index.js"
+		},
+		"./mappers": {
+			"types": "./dist/mappers/index.d.ts",
+			"import": "./dist/mappers/index.js"
+		},
+		"./schemas": {
+			"types": "./dist/schemas/index.d.ts",
+			"import": "./dist/schemas/index.js"
+		},
+		"./standalone": {
+			"types": "./dist/standalone/index.d.ts",
+			"import": "./dist/standalone/index.js"
+		},
+		"./driver-sdk": {
+			"types": "./dist/driver-sdk/index.d.ts",
+			"import": "./dist/driver-sdk/index.js"
+		},
+		"./coordination/event-schema": {
+			"types": "./src/cli/coordination/event-schema.d.ts",
+			"import": "./src/cli/coordination/event-schema.mjs"
+		},
+		"./roadmap/conductor-view": {
+			"types": "./src/cli/roadmap/conductor-view.d.ts",
+			"import": "./src/cli/roadmap/conductor-view.mjs"
+		},
+		"./design/scan": {
+			"import": "./src/cli/design/scan.mjs"
+		},
+		"./design/extract-repo": {
+			"import": "./src/cli/design/extract-repo.mjs"
+		},
+		"./design/synthesize": {
+			"import": "./src/cli/design/synthesize.mjs"
+		}
+	},
+	"scripts": {
+		"build": "tsc && node scripts/extract-personas-schema.mjs",
+		"dev": "tsc --watch --preserveWatchOutput",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check . --diagnostic-level=error",
+		"lint:fix": "biome check --write . --diagnostic-level=error",
+		"clean": "rm -rf dist",
+		"test": "vitest run",
+		"c28:cutover": "node scripts/c28-cutover.mjs",
+		"build-plugin": "node scripts/build-plugin.mjs",
+		"publish-plugin": "node scripts/publish-plugin.mjs",
+		"publish:verdaccio": "node scripts/publish-verdaccio.mjs",
+		"release:verdaccio": "pnpm build && pnpm publish:verdaccio",
+		"ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
+	},
+	"files": [
+		"dist/",
+		"bin/",
+		"src/cli/",
+		"src/cost/",
+		"commands/",
+		"skills/",
+		"agents/",
+		"prompts/",
+		"templates/",
+		"context/",
+		"workflows/",
+		"drivers/",
+		"examples/",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md",
+		"!**/__tests__/**",
+		"!**/*.test.*",
+		"!**/*.spec.*",
+		"!**/*.test.d.ts.map",
+		"!**/*.test.js.map"
+	],
+	"keywords": [
+		"ai",
+		"framework",
+		"coding-assistant",
+		"claude-code",
+		"codex",
+		"aperant"
+	],
+	"license": "AGPL-3.0-only",
+	"homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
+	"bugs": {
+		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
+		"directory": "packages/framework"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.2.0",
+		"proper-lockfile": "^4.1.2",
+		"yaml": "^2.8.3",
+		"zod": "^4.3.6"
+	},
+	"optionalDependencies": {
+		"@babel/parser": "^7.29.2",
+		"@babel/traverse": "^7.29.0",
+		"@google/genai": "^1.50.1",
+		"css-tree": "^3.2.1",
+		"playwright": "^1.59.1"
+	},
+	"devDependencies": {
+		"@vitest/coverage-v8": "^4.1.5"
+	}
+}

package/skills/apt/SKILL.md

@@ -75,6 +75,34 @@ SessionStart hook — zero latency on /apt. If `update_check` is null,
 no chip. Skip the chip entirely once the user has run `/apt:update`
 in the current session (the cache is cleared there).
 
+**Catch-up panel (runtime-agnostic):** if the route envelope includes a
+non-null `catch_up` field, print the combined panel BEFORE the mode handler
+runs, regardless of runtime (Claude Code, Codex, Gemini, Cursor, …). The
+panel has two halves; render `catch_up.welcome_back` first, then
+`catch_up.team_digest`. Omit a half whose field is null.
+
+If `catch_up.welcome_back` is present (your own half-finished work):
+
+```
+Where you left off: {description} — {lifecycle_phase}{current_subtask ? " · subtask " + current_subtask : ""} ({relative_time})
+{next_step ? "  Next: " + next_step : ""}
+{others_count > 0 ? "  (+" + others_count + " others · /apt:resume)" : ""}
+```
+
+If `catch_up.team_digest` is present (what teammates merged while you were away):
+
+```
+While you were away:
+{for each entry in team_digest.entries: "  #" + number + " " + title + " — " + author}
+{team_digest.more_count > 0 ? "  +" + team_digest.more_count + " more on main" : ""}
+```
+
+This is display-only here — the Last-Seen Marker advance happens in route.mjs,
+not in this skill. The panel is computed lazily on interactive (TTY) calls
+only; non-TTY/background/spawned calls carry no `catch_up` field. Do not call
+it an "activity feed", "changelog", or "notifications" — it is the
+Welcome-Back Summary + Team-Change Digest.
+
 Then proceed to the matching mode handler below. Do NOT deviate from the routing decision.
 </mandatory_first_step>
 
@@ -129,6 +157,7 @@ Show available commands table:
 | `apt:scan` | Discover standards + refresh feature registry |
 | `apt:docs` | Generate/update documentation |
 | `apt:resume` | Restore context after session break |
+| `apt:catch-up` | Re-view the catch-up panel (Welcome-Back + Team-Change Digest) — never advances the Last-Seen Marker |
 | `apt:pause` | Human-initiated handoff — save state when YOU need to stop |
 | `apt:ship` | Create PR with traceability |
 | `apt:close-task` | Post-merge closer — confirm PR merged, flip phase, drain narration ledger |

package/skills/apt-catch-up/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: apt:catch-up
+description: "Re-view the catch-up panel (Welcome-Back + Team-Change Digest) on demand"
+apt-skill-version: {{APT_VERSION}}
+stage: resume
+intent: capture
+when_to_use: "The user dismissed the auto catch-up panel on their last /apt and wants to re-summon it — an idempotent re-view of where they left off plus what teammates merged. Distinct from /apt:resume (full context restore) and never advances the Last-Seen Marker."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_execution_mode: auto
+execution_modes:
+  - auto
+allowed-tools: "Bash, Read"
+argument-hint: "apt:catch-up"
+gates: []
+---
+<objective>
+Recompute and display the combined catch-up panel — the **Welcome-Back
+Summary** (your most-recently-active task, phase, next step) and the
+**Team-Change Digest** (the PRs teammates merged to main since you last
+pulled) — exactly as the auto-on-apt display would show it, but **without
+advancing the Last-Seen Marker**. This is a read-only re-view: a user who
+dismissed the auto panel can re-summon it without disturbing the baseline and
+without invoking the heavier `/apt:resume`.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root (where you were invoked)
+- **apt-tools:** `node packages/framework/bin/apt-tools.mjs` or the installed `apt-tools` binary
+- **Last-Seen Marker:** `.aperant/last-seen/{email-slug}.json` (gitignored, per-machine) — this skill READS it but NEVER writes it.
+</your_environment>
+
+<process>
+
+## 1. Recompute the panel (read-only)
+
+```bash
+node packages/framework/bin/apt-tools.mjs catch-up .
+```
+
+This computes the SAME panel the interactive route call produces, against the
+**current** marker — and deliberately does **NOT** call `advanceLastSeen`
+(recompute-only contract). Parse the JSON `catch_up` field from the envelope.
+
+## 2. Render the panel
+
+Render exactly as the `apt/SKILL.md` "Catch-up panel" block does — Welcome-Back
+half first, then the Team-Change Digest half. Omit a half whose field is null.
+
+If `catch_up` is null, tell the user there is nothing new since their last
+visit (no active stale task and no new merges on main).
+
+```
+Where you left off: {description} — {lifecycle_phase} · subtask {current_subtask} ({relative_time})
+  Next: {next_step}
+  (+{others_count} others · /apt:resume)
+
+While you were away:
+  #{number} {title} — {author}
+  +{more_count} more on main
+```
+
+</process>
+
+<notes>
+- **Never advances the marker.** Unlike the auto-on-apt display (which advances
+  the Last-Seen Marker after the panel is evaluated), this command is purely a
+  re-view. Re-running it is idempotent.
+- **Distinct from `/apt:resume`.** Resume restores full context and routes to
+  the next action; catch-up is a lightweight orientation re-view.
+- **v1 is lazy compute.** The panel is computed on demand here, bounded by the
+  commits since your last pull. A background pre-warm worker (like the
+  update-check worker) is a tracked follow-up (LD-12), not part of v1.
+- **Vocabulary.** This is the Welcome-Back Summary + Team-Change Digest — not an
+  "activity feed", "changelog", or "notifications".
+</notes>

package/skills/apt-pr-review/SKILL.md

@@ -247,10 +247,11 @@ The command resolves in this precedence order:
 
 1. `config.json:pr_review.authorship_overrides['pr-${PR_NUMBER}']` (per-PR pin)
 2. `config.json:pr_review.authorship_override` (global: `owned` | `external` | `auto`)
-3. `gh pr view` → `authorAssociation` + `headRepository.owner.login` vs. viewer login
-   - `authorAssociation IN (OWNER, MEMBER, COLLABORATOR)` AND same-repo branch → **owned**
-   - Fork OR `authorAssociation IN (NONE, CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR)` → **external**
-4. Offline / gh unavailable / ambiguous payload → **unknown**
+3. `gh pr view` → `gh.author.login` vs. viewer login (G44 — `owned` means a PR you **authored**, not a branch you can push to)
+   - Same-repo branch AND `gh.author.login === viewer login` → **owned**
+   - Any other same-repo PR (a teammate's, or a repo-`OWNER` viewing someone else's PR) → **external** (`authorAssociation` is no longer consulted for the `owned` decision — it is retained only in the human-readable signal)
+   - Fork (head-repo owner ≠ base-repo owner) → **external**
+4. Offline / gh unavailable / ambiguous payload → **unknown** (treated as `external` for safety, see below)
 
 When the result is `unknown`, treat it as `external` for safety and prompt the user:
 

package/skills/apt-setup/SKILL.md

@@ -205,6 +205,7 @@ AskUserQuestion([
 - "Visibility" → jump to **Step 3e** (Batch 6 only), then skip to **Step 4** and **Step 5**
 - "Task Tracking" → jump to **Step 3g** (Batch 8 only), then skip to **Step 4** and **Step 5**
 - "Changelog & Release Notes" → jump to **Step 3h** (Batch 9 only), then skip to **Step 4** and **Step 5**
+- "Collaboration" → jump to **Step 3i** (Batch 10 only), then skip to **Step 4** and **Step 5**
 - "Everything" → proceed to **Step 2** and run all batches (same as fresh setup). **Legacy-completes-Everything marker write:** if the starting config has no `onboarding` block (legacy unmarked config) and the user completes the full flow, write a full `onboarding` block at Step 5 as `{ completed: true, seeded_from_template: false, seeded_at: <ISO-8601 now> }` to record the explicit onboarding pass.
 - "Done" → display "Settings unchanged." and exit
 
@@ -1180,6 +1181,74 @@ The selective-edit pass through Batch 9 MUST respect the §1b dispatch — it do
 
 ---
 
+## 3i. Present Settings (Batch 10: Collaboration Catch-Up)
+
+The **collaboration catch-up** surfaces show on every interactive (TTY) `/apt`
+call: a **Welcome-Back Summary** (your most-recently-active task + next step,
+always-on, local-only) and a **Team-Change Digest** (the PRs teammates merged
+to main since you last pulled — gated to `share.visibility` `team`/`oss`).
+Written to `.aperant/config.json.collaboration`.
+
+```
+AskUserQuestion([
+  {
+    question: "Show the Welcome-Back Summary when you return after a break?",
+    header: "Welcome-Back",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "On your next /apt after the staleness window, surface where you left off — task, phase, next step. Local only." },
+      { label: "No", description: "Never show the welcome-back nudge." }
+    ]
+  },
+  {
+    question: "How many hours away before the Welcome-Back Summary fires?",
+    header: "Threshold (hours)",
+    multiSelect: false,
+    options: [
+      { label: "16 (Recommended)", description: "Roughly 'since yesterday' — fires after an overnight gap." },
+      { label: "8", description: "Fires after a long lunch / half-day gap." },
+      { label: "24", description: "Once-a-day cadence." }
+    ]
+  },
+  {
+    question: "Show the Team-Change Digest (teammates' merged PRs since your last pull)?",
+    header: "Team Digest",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Only computes when share.visibility is team/oss; reads local git history, never fetches." },
+      { label: "No", description: "Never show the digest, even in team/oss mode." }
+    ]
+  },
+  {
+    question: "Maximum PRs to list in the digest before '+N more on main'?",
+    header: "Digest Max Entries",
+    multiSelect: false,
+    options: [
+      { label: "7 (Recommended)", description: "Low-noise ceiling; the rest collapse into a '+N more' tail." },
+      { label: "5", description: "Tighter." },
+      { label: "12", description: "Roomier." }
+    ]
+  }
+])
+```
+
+For hosts without structured prompts, present the same four questions as
+numbered lists (Batch 5 style) and read single-index responses.
+
+### 3i.1 Review-Mode routing entry
+
+The "1b. Review Mode" routing table (§1b) includes "Collaboration" as a
+selectable edit target — jumping directly back into this Batch 10 picker.
+
+### 3i.2 Confirmation row
+
+Add a row to the Step 8 table:
+```
+| Collaboration | welcome-back {on/off} ({N}h) · team-digest {on/off} (max {M}) |
+```
+
+---
+
 ## 4. Map Answers to Config
 
 **AUDIT-001 — file-routing contract for per-device fields (UPDATED 0.8.1 for FRAMEWORK-RFC-001):** the
@@ -1295,6 +1364,12 @@ Note: task ids are slug-first since v0.6.6 — the date-format setting controls
 - "Sub-Agents" → `"sub-agents"`
 - "Sequential" → `"sequential"`
 
+**Collaboration Catch-Up (Batch 10):**
+- Welcome-Back "Yes" → `collaboration.welcome_back.enabled: true`, "No" → `false`
+- Threshold → `collaboration.welcome_back.threshold_hours: <8|16|24>`
+- Team Digest "Yes" → `collaboration.team_digest.enabled: true`, "No" → `false`
+- Digest Max Entries → `collaboration.team_digest.max_entries: <5|7|12>`
+
 ## 5. Write Config
 
 Write merged config to two files per AUDIT-001 routing (see Step 4 block):
@@ -1402,6 +1477,7 @@ Display:
 | Debate Mode          | {Auto / Agent Team / Sub-Agents / Sequential} |
 | Visibility           | {solo / team / oss} (overrides if any)        |
 | Changelog & Release Notes | dev: {Yes/No}; release-notes: {Yes/No} (audience, persona-filter) |
+| Collaboration        | welcome-back {on/off} ({N}h) · team-digest {on/off} (max {M}) |
 | Saved as Defaults    | {Yes/No}                     |
 
 Config saved to: .aperant/config.json

package/src/cli/commands/catch-up.mjs

@@ -0,0 +1,67 @@
+/**
+ * commands/catch-up.mjs — read-only re-view of the combined catch-up panel
+ * (LD-13). Backs the `/apt:catch-up` skill.
+ *
+ * Recompute-only contract: this command computes the SAME panel the
+ * interactive route call would show (Welcome-Back + gated Team-Change Digest)
+ * against the CURRENT Last-Seen Marker, but it NEVER advances the marker. A
+ * user who dismissed the auto-on-apt display can re-summon it without
+ * disturbing their baseline. Distinct from /apt:resume (full context restore).
+ */
+
+import { resolve } from 'node:path'
+import { loadProjectConfig } from '../config/load.mjs'
+import { resolveSharePolicy } from '../config/share-policy.mjs'
+import { computeCatchUpPanel } from '../coordination/catch-up.mjs'
+import { createCoordinationStore } from '../coordination/store.mjs'
+import { resolveLocalDefaultBranch } from '../git/default-branch.mjs'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * @param {string} projectDir
+ * @returns {{ envelope: object, exitCode: number }}
+ */
+export function cmdCatchUp(projectDir) {
+	if (!projectDir) return err('Usage: apt-tools catch-up <project-dir>')
+	const targetDir = resolve(projectDir)
+
+	// Setup mirrors computeCatchUpForRoute in commands/route.mjs (advances marker).
+	const config = loadProjectConfig(targetDir)
+	if (!config) {
+		return ok({
+			status: 'ok',
+			command: 'catch-up',
+			catch_up: null,
+			reason: 'No .aperant/config.json — nothing to catch up on',
+		})
+	}
+
+	const store = createCoordinationStore(targetDir)
+	const marker = store.readLastSeen()
+	const td = config?.collaboration?.team_digest
+	const vis = resolveSharePolicy(config).visibility
+	const needsDigest = td?.enabled !== false && (vis === 'team' || vis === 'oss')
+	const defaultBranch = needsDigest ? resolveLocalDefaultBranch(targetDir) : null
+
+	let catch_up = null
+	try {
+		catch_up = computeCatchUpPanel(targetDir, {
+			config,
+			now: Date.now(),
+			marker,
+			defaultBranch,
+		})
+	} catch (e) {
+		console.warn('[apt] catch-up:', e?.message ?? e)
+		catch_up = null
+	}
+
+	// NOTE: recompute-only — we deliberately do NOT call store.advanceLastSeen.
+	// The marker baseline is owned by the interactive route path (route.mjs).
+	return ok({
+		status: 'ok',
+		command: 'catch-up',
+		catch_up,
+		reason: catch_up ? 'Catch-up panel recomputed' : 'Nothing new since your last visit',
+	})
+}