@vortex-os/base 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vortex-os/base",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Base entry point for VortEX — a Multi-Agent Personal AI Work OS framework",
   "license": "MIT",
   "author": "vortex-os-project",

package/templates/commands/resume.md

@@ -0,0 +1,52 @@
+---
+description: Reconstruct what the PREVIOUS session was doing and whether it was wrapped up — for after a crash / abrupt close when no handoff was written
+allowed-tools: Bash, Read, Grep, Glob
+---
+Back-trace the last session to answer three things: **what was being worked on, how far it got, and is anything left unfinished or broken.** Use this after an abrupt close or a crash, or whenever the start-of-session report flags carried-over uncommitted work.
+
+INVARIANTS (never break):
+- **READ-ONLY**: never modify the instance or any repo you inspect, and never commit. (Parsing a transcript into a throwaway scratch file under the OS temp dir is fine — just never touch the user's work or repos.)
+- **OFFER, don't act**: report findings and offer to continue or to commit/record loose ends; fix nothing without the user's go-ahead.
+- **Token-frugal**: lead with the cheap signals; read a transcript ONLY if they're inconclusive, and even then extract just the bounded narrative — never the whole `.jsonl` into context.
+
+## 1. Cheap signals first (almost free — often enough)
+In the instance root and any repo you know you were modifying:
+- `git status --porcelain` — uncommitted changes are work that was **not saved**. List them.
+- Interrupted git op — check via `git rev-parse --git-path MERGE_HEAD` / `… rebase-merge` / `… rebase-apply` (the `.git` dir can be a FILE in worktrees/submodules, so resolve the path, don't hardcode `.git/…`), or a stray `*.lock` in the git dir. `COMMIT_EDITMSG` alone is normal — ignore it; a lock can also be stale from non-crash tooling — treat it as a hint, not proof.
+- `git diff --stat` over the uncommitted files → what was being edited.
+- `git log --oneline -6`; compare to today's worklog under `data/worklog/<YYYY>/<MM>/`. A commit dated today with no matching worklog = a record gap.
+
+If the git-tracked signals are all clean, say "**git-tracked work looks wrapped up**" — but note this only covers git: edits to **non-git folders, gitignored/generated files, or another repo you can't see from here won't show**. So if there's any reason to suspect more (the report flagged a crash, or the user is unsure), continue to step 2 anyway; otherwise you may stop here.
+
+## 2. If inconclusive: find the PREVIOUS session's transcript
+**Prefer the normalized archive** under `data/_session-archive/normalized/.../` — those are PAST sessions (archived at this session's start), so they cannot include the live `/resume` session. Take the most recently modified one there.
+Only if needed, fall back to the live Claude Code transcripts at `~/.claude/projects/<slug>/*.jsonl` (slug = the cwd path with `/`, `\`, `:` replaced by `-`). **The current session's transcript is the newest and still growing — EXCLUDE it**; take the one immediately before it (its last activity predates this session's start).
+
+## 3. Extract ONLY a bounded narrative (the token-saver)
+Do **not** `Read` the raw `.jsonl` into context. Pull just **the first user turn (the original task) plus the last ~12 user/assistant text turns (where it stopped)**, dropping every `tool_use` / `tool_result`, each truncated. Use whatever your platform has — `jq`, a `node` one-liner, or PowerShell `ConvertFrom-Json`. Reference logic (node):
+```js
+// node <script> <transcript.jsonl>  → first user turn + last 12 text turns, tool noise dropped
+import { readFileSync } from "node:fs";
+const turns = [];
+for (const line of readFileSync(process.argv[2], "utf8").split("\n")) {
+  if (!line.trim()) continue;
+  let o; try { o = JSON.parse(line); } catch { continue; }
+  if (o.type !== "user" && o.type !== "assistant") continue;
+  const c = o.message?.content;
+  const text = Array.isArray(c)
+    ? c.filter((x) => x && x.type === "text").map((x) => x.text).join("")
+    : (typeof c === "string" ? c : "");
+  if (text.trim()) turns.push(`### ${o.type}\n${text.slice(0, 600)}`);
+}
+const picked = turns.length > 13 ? [turns[0], "… (middle elided) …", ...turns.slice(-12)] : turns;
+console.log(picked.join("\n\n"));
+```
+Read only that output. The first user turn = the session's original task; the last turns = where it stopped.
+
+## 4. Cross-reference and report (concise)
+- **What it was** — the original task / goal.
+- **How far** — what's done & committed vs. what's in progress.
+- **Loose ends** — uncommitted files, missing worklog, interrupted git op, an unrun build/test — each with *where* it stopped.
+- **Verdict** — "wrapped up", or exactly what remains to finish.
+
+Then **offer** to continue, or to commit / record the loose ends — never act without the user's go-ahead.

package/templates/manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "vortex-template-index/1",
-  "baseVersion": "0.5.0",
+  "baseVersion": "0.6.0",
   "files": [
     {
       "templateId": "commands/agenda.md",
@@ -17,6 +17,11 @@
       "path": "commands/recall.md",
       "sha256": "913451c33a6313c923e8433a198846bd5c6616234b1b1b337e15e0d5afe27337"
     },
+    {
+      "templateId": "commands/resume.md",
+      "path": "commands/resume.md",
+      "sha256": "b83ca17624e90508eb913d8fc96164846570af1e6f3cc7f7d5f221f2f9e9c46d"
+    },
     {
       "templateId": "config/vortex.json",
       "path": "config/vortex.json",
@@ -35,12 +40,12 @@
     {
       "templateId": "routers/AI-RULES.md",
       "path": "routers/AI-RULES.md",
-      "sha256": "4048467df07f6e344ba09ef5e7044fb21492fc63cd4c16e4ba2ffd5c7e15facf"
+      "sha256": "6cf0485783bfecad6d09546bf319242d02e7e8db2ae9b46309dcee4ccb49eab4"
     },
     {
       "templateId": "routers/CLAUDE.md",
       "path": "routers/CLAUDE.md",
-      "sha256": "b778d6d322d7436d1391881fe9c9a16d17a99231bbd5fb6955c7bee1a08b5597"
+      "sha256": "36b1b475de280a8e36fe7562574af19a0820c89f4211bef00435ac00c6c95392"
     },
     {
       "templateId": "routers/GEMINI.md",

package/templates/routers/AI-RULES.md

@@ -18,7 +18,8 @@ This instance was created from the `@vortex-os/base` framework. The framework co
 If `data/_memory/user_profile.md` is missing, this instance has not been set up yet. Run:
 
 ```
-npx vortex init --name "<your name>" --role "<your role>" --task "<what you're working on>"
+npx vortex init --name "<your name>" --role "<your role>"
+# optional: add --task "<what you're working on>" to seed your first worklog (otherwise it gets a default focus)
 ```
 
 `init` creates a user-profile memory, today's first worklog, the agent slash-commands, and wires the session hooks. Everything after that grows as you work.
@@ -48,7 +49,7 @@ Before you start **substantively modifying files in a git repository** (any fold
 
 Session start checks **once per session** whether a newer `@vortex-os/base` is published — this **contacts the npm registry over the network**. Mention that to the user when it first comes up, and note they can turn it off with `.agent/vortex.json` → `"updates": { "check": "off" }`. Two kinds of notice may appear in the start report:
 
-- **"template update(s) ready to apply"** — the installed package already has newer framework templates this instance has not applied. Offer to run `npx vortex update` — it refreshes the routers / command prompts / config, **hash-guarded: your edits are never overwritten** (a framework file you changed is parked alongside as `<file>.new` for you to merge).
+- **"template update(s) ready to apply"** — the installed package already has newer framework templates this instance has not applied. Offer to run `npx vortex update` — it refreshes the routers / command prompts / config, **hash-guarded: your edits are never overwritten** (a framework file you changed is parked alongside as `<file>.new` for you to merge). If `update` reports a framework file as **diverged and not getting updates** (one you edited before it was tracked), run `npx vortex update --adopt <path>` to force it back to the current template and resume tracking — your version is backed up first. Your settings file (`.agent/vortex.json`) is user-owned and is never adopted (new options fall back to defaults).
 - **"update available: @vortex-os/base X → Y"** — a newer version is published. Tell the user in one sentence and **ask once** whether to update now. On yes, run **the exact command the report printed** — it is tailored to this instance (local vs global; npm/pnpm/yarn), e.g. `npm i @vortex-os/base@latest && npx vortex update` (install the new package, then apply its templates); use the printed command, not this example. Then confirm it landed with `npx vortex check-updates`. On no, drop it for the session. **Never install without asking.**
 
 When the user asks whether there's an update, run `npx vortex check-updates` (read-only — contacts the npm registry and prints the latest version and the exact update command).
@@ -57,6 +58,8 @@ When the user asks whether there's an update, run `npx vortex check-updates` (re
 
 **Explain simply and briefly — assume the user is not an IT expert.** Default to plain language. Lead with the conclusion. Keep ordinary replies short (a few lines, at most a few bullets); add tables/code only when they earn their place. Unpack any unavoidable technical term in a line or with a plain analogy, and when you must use a technical or non-native term, gloss it in the user's language in parentheses right after it. Write in a **standard written register** — clear and plain, never casual or colloquial speech. Match the user's *level* of detail, not their *voice*: don't echo their slang, tics, or phrasing back (it drifts your tone across the session and the next), unless the current request explicitly asks for a particular style.
 
+**Plain ≠ dumbed-down.** Aim for an educated non-specialist: mainstream terms most people already know (AI, agent, app, install, command, code, bug) need no gloss — reserve glosses for genuine jargon, and skip forced childish analogies. The goal is usability: a VortEX user should feel the explanation is *noticeably clearer than a plain agent*, never patronized. Before sending, re-read it once at that level — too technical and too childish are both misses.
+
 **Ask one decision at a time.** When you need the user to decide, ask a single question and wait — do not stack several at once. Only batch when the choices are genuinely independent.
 
 **Match reasoning effort to the task.** Don't over-reason trivial asks — a status check, a one-line edit, a lookup; don't under-reason heavy ones — architecture design, multi-file refactors, large debugging or migration, broad reviews. If the host exposes a tunable reasoning/thinking level and the task ahead clearly needs a different one than the session is set for, recommend the change — but rarely: only at a real boundary (a sizable task's start, a major topic shift, a substantial new directive), one or two times across a long session, never per question.
@@ -71,6 +74,17 @@ When the user asks whether there's an update, run `npx vortex check-updates` (re
 
 **Protect the main thread's context — delegate heavy, self-contained work.** A long session fills its context window (the reason you end up reopening sessions); offloading keeps the main thread lean *without* losing quality, if done right. When a task is self-contained and clearly specifiable — a broad search, multi-file exploration, a long-output investigation, bulk generation — hand it to a separate agent/subtask with a **precise spec and acceptance criteria**, and bring back only the conclusion. The main thread keeps the plan, the decisions, and the synthesis — it never delegates the *judgment* — and **verifies a delegated result before building on it** (so have the sub-agent report its evidence: what it inspected, the key findings, what's uncertain). **Don't delegate** when the spec is fuzzy, the call is a judgment, the material is sensitive, the work is tightly coupled to the edit you're making, or verifying the result would cost as much as just doing it. Scale the mechanism to the host (the per-host file, e.g. `CLAUDE.md`, names the concrete tools); where a host has no sub-agents, the fallback is a fresh session plus a short handoff note.
 
+**Pre-send gate.** A few of the rules above slip during long, heavy work — your active context fills with the task and a rule fades to passive knowledge, so dumping the live working vocabulary into the reply is the path of least resistance. The short block below is last on purpose (closest to what you write next, where it stays salient against "lost in the middle"); re-read it right before you reply. It is a *reduction* in drift, not a cure — the one reliable catch for what you cannot self-see is the cross-check, so escalate to it on anything that matters.
+
+<critical_rules>
+Pre-send gate — re-read right before replying:
+- Use plain, standard written language for an educated non-specialist: conclusion first, gloss only genuine jargon, no childish analogies.
+- Match the user's *level* of detail, not their slang, tics, or voice.
+- If a decision is needed, ask only the first blocking question.
+- For a significant design / implementation / fix / security-sensitive change, run the host-appropriate adversarial cross-check (named in your per-agent router) before relying on the answer.
+- Self-check the style on routine replies; on important output, do not trust self-check alone.
+</critical_rules>
+
 ## The `data/` layout
 
 Your content lives under `data/`. Each category answers a different question:
@@ -99,12 +113,14 @@ These slash-commands are installed into `.claude/commands/` by `vortex init` (th
 
 | Command | What it does |
 |---|---|
-| `/vortex` | Instance operations: `init`, `status`, `import`, `doctor`, `update`, `help`. |
+| `/vortex` | Instance operations: `init`, `status`, `import`, `doctor`, `update`, `global-setup`, `help`. |
+| `/vortex global-setup` | Use VortEX from **any** folder — merges an instance pointer + session hooks into your global `~/.claude` (merge-safe, idempotent; `--decline` to dismiss the offer). |
 | `/session-start` | Start-of-session report — recent work, current counts, the time. |
 | `/log <section>` | Append a section to today's worklog (creates it if needed). |
 | `/decision <slug> <title>` | Create a new Decision Log entry from the template. |
 | `/recall <query>` | Keyword + semantic (hybrid) search over your memories and past sessions; the agent picks the mode. *(Only when the optional `@vortex-os/memory-extended` add-on is installed.)* |
 | `/agenda` | "What should I focus on?" — synthesizes open tasks, decisions, recent activity. |
+| `/resume` | After a crash / abrupt close with no handoff: back-traces git state + the last session transcript to find what was in progress and whether it's wrapped up. Read-only; cheap signals first, transcript only if needed. |
 | `/reindex [dir]` | Regenerate `_INDEX.md` for a category (or all). Idempotent. |
 
 You can also run any of these directly: `npx vortex <command> [args]`.

package/templates/routers/CLAUDE.md

@@ -34,6 +34,6 @@ Do **not** delegate the judgment — the main thread owns the plan, the decision
 
 ## Cross-check tool (per `AI-RULES.md` → "Cross-check significant decisions")
 
-For the adversarial cross-check that `AI-RULES.md` calls for: use a **Task sub-agent with a clean context** (give it only the relevant facts + acceptance criteria) for a same-model check; if the **Codex CLI** is installed, `codex exec -C <repo> -s read-only` is a stronger **cross-model** check. Bring back only the verdict — the main thread still decides and closes by verifying against the code/tests. When you shell out to `codex exec`: close stdin (`< /dev/null`) so it doesn't stall waiting for input, set your own timeout (the host's may not stop a runaway), and keep the reviewer read-only (`-s read-only`).
+For the adversarial cross-check that `AI-RULES.md` calls for: use a **Task sub-agent with a clean context** (give it only the relevant facts + acceptance criteria) for a same-model check; if the **Codex CLI** is installed, `codex exec -C <repo> -s read-only` is a stronger **cross-model** check. Bring back only the verdict — the main thread still decides and closes by verifying against the code/tests. When you shell out to `codex exec`: close stdin (`< /dev/null`) so it doesn't stall waiting for input, set your own timeout (the host's may not stop a runaway), and keep the reviewer read-only (`-s read-only`). On **Windows PowerShell** `< /dev/null` doesn't exist — pipe input instead (`git diff | codex exec …`, or `'' | codex exec …` for a non-diff review) to hand stdin an EOF, and pass the prompt as a **single-quoted here-string** (`@'…'@`, closing `'@` at column 0): a double-quoted prompt makes PowerShell treat the backtick as an escape character, so a prompt containing backticks (e.g. a backticked command name like `update --adopt`) fails to parse with an "invalid Unicode escape" error.
 
 For the **security-review** lens (per `AI-RULES.md` → "Security-review code changes"): Claude Code ships a `/security-review` command that reviews the pending diff on the current branch — use it for the security pass. For a stronger or independent check, the same `codex exec -C <repo> -s read-only` (cross-model) or a clean-context Task sub-agent (give it only the diff + the threat surface) applies, prompted for the security classes rather than general correctness.