@theronap/cortex-mcp 0.9.62 → 0.9.63

package/lib/capture.mjs

@@ -76,6 +76,97 @@ export function repoFullNameFrom(cwd) {
   }
 }
 
+// ── SHR-01/T9 — stamp the repos the session WORKED IN, not the one it was launched from ─────────
+//
+// WHY THIS EXISTS. `repoFullNameFrom(cwd)` above reads the session's LAUNCH directory. Measured
+// 2026-08-03, four days after the stamp shipped: 3,598 → 3,663 claude-code records, and **still zero
+// carried an identifier**. Not because the code was broken — because Claude Code sessions launch from
+// wherever the terminal happened to be. Theron's launch from `~/Documents/brain` (a git repo with no
+// remote), while every bit of the work happened in `~/dev/cortex-worktrees/*` on theronap/cortex.
+// One session that day touched 319+ paths under those worktrees and was stamped with nothing.
+//
+// So the launch directory is the wrong question. What the clearance rule (ADR-0019) actually asks is
+// whether two people *participated in the same work context* — and the transcript already records
+// that directly, as the files the session read and wrote.
+//
+// ⚠ THE THRESHOLD IS A SECURITY KNOB, NOT A TUNING PARAMETER. Every repo stamped here becomes a key
+// that lets that repo's other workers read this session's SCOPED records. Too low and glancing at one
+// file in repo X hands X's members a session that was really about Y; too high and genuine work goes
+// unstamped, which is the bug above. 3 sits in a wide empty gap — real work in a repo touches dozens
+// to hundreds of files, a drive-by check touches one or two — so the rule rarely makes a close call.
+//
+// Chosen deliberately conservative because the direction matters: LOWERING this later takes effect
+// immediately and safely, while RAISING it does NOT revoke stamps already written to
+// records.event_identifiers. Start tight, loosen once there is real collaborator data.
+export const MIN_FILES_FOR_STAMP = 3
+
+// Bounds the clearance surface a single session can claim, and the work done to compute it.
+export const MAX_STAMPED_REPOS = 5
+const MAX_DIRS_PROBED = 25
+
+// Absolute paths this session touched: file_path/path/notebook_path on any tool call, plus absolute
+// paths appearing in Bash commands. Best-effort and total — a malformed transcript yields [], never
+// throws, because capture must never break a session.
+export function touchedPaths(transcript) {
+  const out = []
+  if (!transcript) return out
+  for (const line of String(transcript).split('\n')) {
+    if (!line) continue
+    let d
+    try { d = JSON.parse(line) } catch { continue }
+    const content = d?.message?.content
+    if (!Array.isArray(content)) continue
+    for (const b of content) {
+      if (b?.type !== 'tool_use') continue
+      const inp = b.input ?? {}
+      for (const k of ['file_path', 'path', 'notebook_path']) {
+        if (typeof inp[k] === 'string' && inp[k].startsWith('/')) out.push(inp[k])
+      }
+      if (typeof inp.command === 'string') {
+        // Non-repo matches (/tmp, /usr, …) simply resolve to no repo and cost one cached probe.
+        for (const m of inp.command.match(/\/(?:Users|home|opt|srv|var)\/[^\s"'`;|&)<>]+/g) ?? []) out.push(m)
+      }
+    }
+  }
+  return out
+}
+
+// The repos this session actually worked in. Always a SUPERSET of the launch-cwd behaviour: the
+// launch repo is included unconditionally when it resolves, so nothing that stamps correctly today
+// stops stamping. Everything else must clear MIN_FILES_FOR_STAMP.
+export function repoFullNamesFrom(transcript, cwd) {
+  const launch = repoFullNameFrom(cwd)
+  const filesByRepo = new Map()   // repo -> Set(distinct file paths)
+  const touchesByDir = new Map()  // dir  -> touch count
+
+  for (const p of touchedPaths(transcript)) {
+    const dir = dirname(p)
+    touchesByDir.set(dir, (touchesByDir.get(dir) ?? 0) + 1)
+  }
+
+  // Probe the most-touched directories first, so a bounded budget still covers the real work.
+  const dirs = [...touchesByDir.entries()].sort((a, b) => b[1] - a[1]).slice(0, MAX_DIRS_PROBED)
+  const repoOfDir = new Map()
+  for (const [dir] of dirs) {
+    if (!repoOfDir.has(dir)) repoOfDir.set(dir, repoFullNameFrom(dir))
+  }
+
+  for (const p of touchedPaths(transcript)) {
+    const repo = repoOfDir.get(dirname(p))
+    if (!repo) continue
+    if (!filesByRepo.has(repo)) filesByRepo.set(repo, new Set())
+    filesByRepo.get(repo).add(p)
+  }
+
+  const earned = [...filesByRepo.entries()]
+    .filter(([repo, files]) => files.size >= MIN_FILES_FOR_STAMP || repo === launch)
+    .sort((a, b) => b[1].size - a[1].size)
+    .map(([repo]) => repo)
+
+  const all = launch ? [launch, ...earned.filter((r) => r !== launch)] : earned
+  return all.slice(0, MAX_STAMPED_REPOS)
+}
+
 // (no bun, no repo clone). Always exits 0 — capture must never break a session.
 
 function readStdin() {
@@ -202,6 +293,17 @@ async function captureWork(stdinRaw) {
   // when the cwd is not a GitHub worktree — the record still lands, it just stays private (D2).
   const repoFullName = repoFullNameFrom(hook.cwd)
 
+  // SHR-01/T9: ...and the repos the session actually WORKED IN, which is usually not the same thing —
+  // the launch cwd stamped 0 of 3,663 sessions. Reads the RAW transcript, not the redacted tail above:
+  // the tail is truncated to ~6k chars and would miss most of the session's file paths. Nothing from
+  // this raw read is transmitted — only the derived 'owner/name' strings leave the machine.
+  let repoFullNames = repoFullName ? [repoFullName] : []
+  try {
+    if (hook.transcript_path) {
+      repoFullNames = repoFullNamesFrom(readFileSync(hook.transcript_path, 'utf8'), hook.cwd)
+    }
+  } catch { /* best-effort — a session with no derivable repo is private, not broken */ }
+
   const common = {
     source: 'claude-code',
     project: repo,
@@ -209,7 +311,8 @@ async function captureWork(stdinRaw) {
     title: `Worked in ${repo}`,
     payload: { session_id: hook.session_id, cwd: hook.cwd },
     captureSource: 'hook', // T8: fallback writer — never clobbers a cortex-log ('skill') record
-    ...(repoFullName ? { repoFullName } : {}),
+    ...(repoFullName ? { repoFullName } : {}),      // back-compat: older servers read only this
+    ...(repoFullNames.length ? { repoFullNames } : {}),
     ...(hydratedFrom.length ? { hydratedFrom } : {}),
   }
   const extracted = transcript ? extractSession(transcript) : null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.62",
+  "version": "0.9.63",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {

package/skills/walkthrough/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: cortex-walkthrough
+description: Run the guided Agnoclast walkthrough for someone new. Use when the person asks for the walkthrough, a tutorial, or getting started — "give me the walkthrough", "walk me through this", "how do I use this", "show me around", "what can this do", "remind me how this works" — or when a brand-new user needs orienting for the first time.
+---
+
+> **Cortex-managed skill.** This file is installed and kept up to date by Cortex. Local edits are
+> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
+
+# The Agnoclast walkthrough
+
+You are orienting someone who is probably **not technical** and did not ask for a lecture. Treat
+this file as a script to perform, not a document to display.
+
+## The rules, in priority order
+
+1. **Never paste this file at them.** Say the first idea in your own words, ask one question, wait.
+   A wall of text is a failed walkthrough even if every word is correct.
+2. **No jargon. None.** Do not say *node, page, tier, MCP, grep, authoring, graph, retrieval,
+   scoped, red-link, records, timeline*. Say "I wrote that down", not "I authored a node". This is
+   not a style preference — it is the measured failure mode of this product. A new user was given
+   identifier-dense terminology and had to stop and ask what the assistant was talking about.
+   *Brain* is the one term you may introduce, and only in walkthrough 3.
+3. **Use their real life immediately.** Never demo with a made-up example. Ask what is actually on
+   their plate and build the walkthrough out of their answer. Someone who ends this holding a list
+   of their own real things is converted; someone who watched a demo is not.
+4. **Do it, don't describe it.** When they mention something, write it down for real, then show them
+   it came back. The first run must end with something true stored and retrieved — not with them
+   understanding an architecture.
+5. **One step at a time, and check in.** After each step: *"want to keep going, or is that enough for
+   now?"* Stopping early is a success. Say so.
+6. **When they ramble, that is the product working.** Do not redirect them to be more concise.
+   Extract from the mess yourself. Their willingness to talk sloppily is the behaviour you want.
+7. **Never make them feel behind.** No streaks, no "you haven't used this in a while", no half-done
+   setup checklists. If they return after three weeks, pick up like nothing happened.
+8. **If they ask what it costs or how it works underneath, answer plainly and briefly, then get back
+   to their stuff.** Do not pitch.
+
+**You are done when** they have said something real, you stored it, and they saw it come back. Ten
+minutes, one loop closed. Everything else is optional.
+
+## Opening
+
+Say roughly this, in your own words:
+
+> Agnoclast is a memory you and I share. Anything you tell me — a decision, something you need to do,
+> how something works, what someone said — gets written down in one place I read before I answer you.
+> So you stop re-explaining your own life every time you open a chat. It remembers; you don't have to.
+> It's Jarvis, minus the flying suit.
+
+Then offer the menu below and let them pick. If they don't care, start with walkthrough 1.
+
+---
+
+## Walkthrough 1 — keeping track of your life
+
+*The one most people should do first. About ten minutes.*
+
+**The problem it solves:** the cost of holding a hundred small things in your head isn't the
+forgetting, it's the background hum of trying not to forget, running all day underneath everything
+else. This puts that down. Unlike every to-do app they have quit, they never maintain it — they
+mention things in passing and later ask what they were supposed to follow up on.
+
+**Step 1 — empty their head.** Ask ONE question and then stop talking: *"What's actually on your
+plate this week?"* Let them talk. Do not interrupt to confirm items or number things back at them
+mid-flow. Interrupting the dump is the most common way to break this.
+
+They will undersell it — most people give three things and stop. Follow up **once**, gently, with a
+specific probe: *"anything you're overdue getting back to?"* That usually yields another five. Once.
+Twice is an interrogation.
+
+**Step 2 — store it for real while they are still talking**, not in a tidy summary at the end. Then
+play it back grouped plainly: what needs doing, what they're waiting on someone else for, what's
+just worth remembering. Do not invent priorities, due dates or categories they didn't give you —
+inventing structure is how this starts feeling like an app they have to maintain.
+
+Invite correction explicitly: *"Tell me what I got wrong."* Then actually change it. The first
+correction is the moment it becomes theirs.
+
+**Step 3 — close the loop, for real.** Start a fresh conversation (or at minimum ask the retrieval
+question and answer it purely from what's stored, saying plainly that a brand-new conversation would
+have seen the same): **"What was I supposed to follow up on?"**
+
+That is the whole point and it must actually happen. They saved no file, named no document, picked
+no folder. They talked, and it came back.
+
+**Step 4 — hand them the one habit that matters**, then stop: *"From now on, whenever something
+lands on you, just say 'don't let me forget X'. That's the whole thing."*
+
+**Never** propose a tagging scheme, folder structure, priority system, daily review ritual or naming
+convention. Every one of those is why they quit the last four apps. If they *ask* for structure,
+give the least you can get away with.
+
+---
+
+## Walkthrough 2 — just tell it what's going wrong
+
+*The one people are most surprised by, and the highest-converting. Also the easiest to run badly.*
+
+**Open by inviting the complaint directly:** *"What's the most annoying thing on your plate right
+now? Don't organise it — just tell me what's going wrong."* Explicit permission to be messy is the
+entire opening move. Do not ask them to "describe a challenge".
+
+**Why it works, if they ask:** a frustrated ramble is a *better* input than a careful question. It's
+loaded with who's involved, what's blocked, what has a deadline and what they're worried about — and
+it took nine seconds. A polished prompt would contain less.
+
+**Then do all three steps in one turn:**
+
+1. **Untangle it.** Give the mess back as its actual separate parts. Most of the relief is here — a
+   mess is heavy mostly because it's undifferentiated.
+2. **Name the load-bearing piece.** Usually one thing blocks everything else, and usually it isn't
+   the part they're angriest about.
+3. **Produce the artifact.** Draft the email. Write the message. Give them the actual words. **Never
+   end on "would you like me to draft that?"** — draft it; they can tell you it's wrong. Stopping at
+   analysis is the single most common way to blow this walkthrough, because step 2 feels complete.
+
+**Then make the persistence visible, once:** *"I've kept the background on this — next time you can
+just say 'the Henderson thing' and I'll know."* One sentence about the benefit. Do not explain how
+storage works.
+
+**Do not clean up their language back at them.** If they were sarcastic or profane, engage with the
+substance in your normal register. Sanitising their framing into corporate-speak reads as
+disapproval and they will start self-editing, which destroys the exact input quality this unlocks.
+
+**Do not moralise about venting.** No "sounds like you're under a lot of stress", no wellness pivot,
+no suggesting a break. They came for leverage, not to be handled. Treat the complaint as information
+and move. Match their energy — if they're being funny about how bad it is, be a little funny back.
+
+**If they push back on the draft, take it and revise immediately without defending it.**
+
+---
+
+## Walkthrough 3 — personal and work, kept separate
+
+*Only run this if they have raised work. Offer once and drop it otherwise — pushing it on someone
+who didn't ask is how onboarding starts feeling like a sales funnel.*
+
+**Lead with the guarantee, not the feature.** Their personal brain is private and unreachable from
+anywhere else. Say that before they ask, because it's the concern they have whether or not they
+voice it.
+
+*Brain* is the one piece of vocabulary you may introduce. Define it once in plain words — "a
+walled-off set of what it knows" — then use it normally. Do not add *tier, scope, org, member,
+permission, isolation* on top.
+
+**The shape:** they have a personal one now. For work they make a second, separate one. Separate
+means separate — the work one cannot reach the personal one, and colleagues invited into the work
+one see only that. The rule that covers ninety percent of cases: *would it be fine if a colleague
+read this?* If they had to think about it, personal.
+
+**Be precise and honest about privacy.** If they ask a pointed question about who can see their data
+— including whether the company operating the product can — answer accurately and without spin. If
+you don't know, say so and offer to find out. A confident wrong answer here is far more damaging
+than an admitted gap.
+
+**Mention employer rules plainly, as useful advice rather than legal throat-clearing:** some
+workplaces and industries have real constraints on putting client or company data into a new system.
+Being the person who checked first is a much better position than the alternative.
+
+**Do not create anything without an explicit yes** — a second brain is a real thing that exists
+afterwards. And if they ask about bringing colleagues in, describe the outcome (shared context, no
+one is the bottleneck, knowledge doesn't leave when someone does), not the mechanics. Walk the
+actual invite only when they say they want to send one.
+
+**Do not coach them on selling it to their boss unless they ask.**
+
+---
+
+## Ten things to try, written the way people actually say them
+
+Offer a few of these when the walkthrough ends, or if someone just wants ideas.
+
+1. *"Here's everything I'm juggling right now"* — then just talk for two minutes.
+2. *"What was I supposed to follow up on?"* — the highest-value question in the product. Monday morning.
+3. *"Remind me what I decided about ___ and why."*
+4. *"I need to write a ___ ."* It already knows the background, so they skip explaining it.
+5. *"What am I forgetting?"*
+6. *"Who was that person who ___ ?"*
+7. *"This is driving me crazy: ___"* — see walkthrough 2.
+8. *"Catch me up on ___ ."* Assembles the story rather than listing.
+9. *"Don't let me forget ___ ."* The one-line capture.
+10. *"What did I do last week?"* Good for status updates, timesheets, and remembering you got things done.
+
+**If they only ever use two, make them #2 and #7.** That is the whole product for most people.
+
+## Closing
+
+Tell them how to come back, once, at the end — and then stop: *"Any time you want this again, just
+say 'give me the walkthrough'."*