@theronap/cortex-mcp 0.9.56 → 0.9.58

package/lib/capture.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from 'fs'
-import { spawn } from 'child_process'
+import { spawn, execFileSync } from 'child_process'
 import { homedir } from 'os'
 import { resolve, dirname, join } from 'path'
 import { fileURLToPath } from 'url'
@@ -37,6 +37,45 @@ export function projectFrom(cwd) {
 
 // Claude Code Stop hook → POSTs a session digest to Cortex cloud, which
 // summarizes server-side and upserts ONE record per session. Node-native
+// SHR-01/T6 — parse a git remote URL into GitHub 'owner/name', or null.
+//
+// Handles the four remote forms git emits: scp-like ssh (git@github.com:o/n.git), ssh://, https://,
+// git://. The HOST CHECK IS LOAD-BEARING, not cosmetic: this string becomes a clearance key, and
+// 'owner/name' on gitlab.com or a self-hosted forge would collide in the identifier namespace with an
+// unrelated GitHub repo of the same name — granting its members read access to each other's sessions.
+export function githubFullName(url) {
+  if (!url) return null
+  const m = String(url).trim()
+    .match(/^(?:git\+)?(?:https?:\/\/|ssh:\/\/|git:\/\/)?(?:[^@/]+@)?github\.com[:/]+([^/]+)\/(.+?)(?:\.git)?\/?$/i)
+  if (!m) return null
+  const owner = m[1].toLowerCase()
+  const name = m[2].toLowerCase()
+  if (!owner || !name || name.includes('/')) return null
+  return `${owner}/${name}`
+}
+
+// SHR-01/T6 — the repo this session is working in, as 'owner/name', or null.
+//
+// D2, FAIL CLOSED: anything that is not unambiguously a GitHub worktree — no repo, no origin remote,
+// a non-GitHub host, git not installed — returns null, and the session is then stamped with NO
+// identifier and stays private. There is deliberately no fallback: a brain-level or hostname-level
+// identifier would be held by every member of the org, so overlap would ALWAYS succeed. That is an
+// accidental org-wide grant, i.e. the default-tier flip that was explicitly declined.
+//
+// `git config --get` is local and does no network I/O. Bounded and swallowed regardless: capture must
+// never break a session, and a missing identifier is a private session, not a broken one.
+export function repoFullNameFrom(cwd) {
+  if (!cwd) return null
+  try {
+    const url = execFileSync('git', ['-C', String(cwd), 'config', '--get', 'remote.origin.url'], {
+      encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return githubFullName(url)
+  } catch {
+    return null
+  }
+}
+
 // (no bun, no repo clone). Always exits 0 — capture must never break a session.
 
 function readStdin() {
@@ -159,6 +198,10 @@ async function captureWork(stdinRaw) {
   // summarizer (which has been the silent point of failure). Fall back to shipping the transcript
   // tail only if local extraction is unavailable (e.g. `claude` not on PATH) so we never drop a
   // session. The server re-validates people/entities — the edge is not trusted.
+  // SHR-01/T6: the repo identifier is what lets a PEER read this session (see 0096). Omitted entirely
+  // when the cwd is not a GitHub worktree — the record still lands, it just stays private (D2).
+  const repoFullName = repoFullNameFrom(hook.cwd)
+
   const common = {
     source: 'claude-code',
     project: repo,
@@ -166,6 +209,7 @@ 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 } : {}),
     ...(hydratedFrom.length ? { hydratedFrom } : {}),
   }
   const extracted = transcript ? extractSession(transcript) : null

package/lib/server.mjs

@@ -670,6 +670,121 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'rename_section',
+    {
+      title: 'Rename one section heading on a wiki page',
+      description: 'Rename ONE section\'s heading on a wiki page, in place. Use this instead of re-authoring the page: `author` cannot express a rename, because a section\'s IDENTITY is its heading string — sending a new title reads as "dropped the old section, added a new one" and is rejected 409 would_drop_sections. This route changes the heading and NOTHING else: the section keeps its body, its position, and crucially its as-of date, so renaming does not reset the currency stamp on a claim nobody re-verified. It is also the ONLY way to fix a heading longer than the 80-char limit, which cannot be re-authored at all. Requires base_version (the `version` read_page prints) — that is also how it finds the right brain, so it can never rename on the wrong one. Refuses, rather than guessing, when the page exists at several tiers, when the heading repeats, or when the new heading is already taken.',
+      inputSchema: {
+        name: z.string().describe('the exact page name, as read_page shows it'),
+        from: z.string().describe('the CURRENT heading, exactly as stored (match is case- and whitespace-insensitive)'),
+        to: z.string().describe('the new heading. Max 80 chars. Must not already be used by another section on this page.'),
+        base_version: z.string().describe('the `version` read_page prints for this page (64-hex). REQUIRED — it is the concurrency check AND how the right brain is resolved. A per-SECTION hash is not valid here.'),
+        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('only when the page exists at MORE THAN ONE tier — which one to rename in. A rename never moves content between tiers.'),
+        ordinal: z.number().optional().describe('only when the same heading appears more than once on the page — which occurrence to rename (the error lists the ordinals).'),
+        reason: z.string().optional().describe('why you are renaming it — recorded in page_history like any other edit'),
+      },
+    },
+    async ({ name, from, to, base_version, tier, ordinal, reason }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/rename-section`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            name, from, to, base_version,
+            ...(tier ? { tier } : {}), ...(ordinal !== undefined ? { ordinal } : {}),
+            ...(reason ? { reason } : {}),
+          }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not rename the section: ${e.message}` }] }
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        // Surface the server's hint AND the disambiguators it named, so a 409 is directly actionable
+        // rather than something to retry blindly.
+        const extra = [
+          out?.detail ? `existing: ${out.detail}` : '',
+          Array.isArray(out?.tiers) ? `tiers: ${out.tiers.join(', ')}` : '',
+          Array.isArray(out?.ordinals) ? `ordinals: ${out.ordinals.join(', ')}` : '',
+          out?.currentVersion ? `current version: ${out.currentVersion}` : '',
+        ].filter(Boolean).join(' · ')
+        const hint = out?.hint ? `\n${out.hint}` : ''
+        return { content: [{ type: 'text', text: `Could not rename "${from}" on "${name}": ${out?.error ?? res.status}${extra ? `\n${extra}` : ''}${hint}` }] }
+      }
+      return { content: [{ type: 'text', text: `Renamed on "${name}" (${out.brain} · ${out.tier} tier): "${out.from}" -> "${out.to}". The section kept its body, position and as-of date. New version: ${out.version}` }] }
+    },
+  )
+
+  server.registerTool(
+    'edit_page',
+    {
+      title: 'Change one passage on a wiki page (use this, not author, to fix something)',
+      description:
+        'THE DEFAULT WAY TO CORRECT A PAGE. Replaces ONE passage inside ONE section, by quoting the exact text to replace — like editing a file, not rewriting it. Use this whenever you are fixing, updating or correcting something on an existing page; use `author` only when you are genuinely rewriting a page wholesale or creating one. WHY IT MATTERS: `author` takes the WHOLE page, so every section you did not mean to touch gets retyped by you on the way through, and drifts. Measured 2026-07-30: an edit meant for one section silently deleted a sentence from another, along with a [[link]] — a lost graph edge. Text you never send cannot be damaged. Anchors match the STORED body, so quote from what read_page shows as the section body; if a match fails on whitespace the error tells you so. An anchor matching twice is REFUSED, never guessed — quote more surrounding text. On a stale-version conflict you get the target section back so you can re-anchor without re-reading the page.',
+      inputSchema: {
+        name: z.string().describe('the exact page name, as read_page shows it'),
+        heading: z.string().describe('the heading of the section containing the text you are changing'),
+        old_string: z.string().describe('the exact text to replace. Must appear EXACTLY ONCE within that section — if it repeats, quote more surrounding text to make it unique.'),
+        new_string: z.string().describe('what to replace it with. May be empty, which deletes the anchored text.'),
+        base_version: z.string().describe('the `version` read_page prints for this page (64-hex). REQUIRED — it is the concurrency check AND how the right brain is resolved.'),
+        reason: z.string().describe('WHY you are making this change, in one short phrase — recorded in page_history exactly like an author edit.'),
+        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('only when the page exists at MORE THAN ONE tier — which one to edit. An edit never moves content between tiers.'),
+        ordinal: z.number().optional().describe('only when the same heading appears more than once on the page — which occurrence (the error lists the ordinals).'),
+      },
+    },
+    async ({ name, heading, old_string, new_string, base_version, reason, tier, ordinal }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/edit-page`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            name, heading, old_string, new_string, base_version, reason,
+            ...(tier ? { tier } : {}), ...(ordinal !== undefined ? { ordinal } : {}),
+          }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not edit "${name}": ${e.message}` }] }
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        // Every failure here is meant to be directly actionable — the caller should be able to fix and
+        // retry from this text alone, without re-reading the page.
+        const bits = [
+          Array.isArray(out?.available) ? `sections on this page: ${out.available.join(' | ')}` : '',
+          Array.isArray(out?.tiers) ? `tiers: ${out.tiers.join(', ')}` : '',
+          Array.isArray(out?.ordinals) ? `ordinals: ${out.ordinals.join(', ')}` : '',
+          out?.count ? `matches: ${out.count}` : '',
+          out?.whitespaceNear === true ? 'YOUR TEXT IS PRESENT but the whitespace differs — re-copy it from the stored body' : '',
+          out?.currentVersion ? `current version: ${out.currentVersion}` : '',
+        ].filter(Boolean).join('\n')
+        const cur = out?.currentSectionBody
+          ? `\n\n--- the section as it stands now (re-anchor against this) ---\n${out.currentSectionBody}`
+          : ''
+        // B5: what ANOTHER session changed elsewhere on this page while you were working. Rendered
+        // INLINE, not as a pointer to page_diff — a pointer is something a busy agent skips, and the
+        // whole point is that you cannot be ignorant of it.
+        const cc = Array.isArray(out?.concurrentChanges) && out.concurrentChanges.length
+          ? '\n\n--- changed elsewhere on this page since you read it (READ THIS before retrying) ---\n' +
+            out.concurrentChanges.map((c) =>
+              `§ ${c.heading}\n${(c.lines ?? []).map((l) => `${l.kind === 'add' ? '+' : '-'} ${l.line}`).join('\n')}`,
+            ).join('\n\n')
+          : ''
+        const ccMeta = [
+          Array.isArray(out?.concurrentAdded) && out.concurrentAdded.length ? `sections ADDED elsewhere: ${out.concurrentAdded.join(', ')}` : '',
+          Array.isArray(out?.concurrentRemoved) && out.concurrentRemoved.length ? `sections REMOVED elsewhere: ${out.concurrentRemoved.join(', ')}` : '',
+          Array.isArray(out?.concurrentTruncated) && out.concurrentTruncated.length ? `(truncated, see page_diff for all of: ${out.concurrentTruncated.join(', ')})` : '',
+        ].filter(Boolean).join('\n')
+        return { content: [{ type: 'text', text: `Could not edit "${name}": ${out?.error ?? res.status}${out?.hint ? `\n${out.hint}` : ''}${bits ? `\n${bits}` : ''}${ccMeta ? `\n${ccMeta}` : ''}${cc}${cur}` }] }
+      }
+      const red = Array.isArray(out.redLinks) && out.redLinks.length
+        ? `\nRed-links now on this page: ${out.redLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
+      return { content: [{ type: 'text', text: `Edited "${name}" (${out.brain} · ${out.tier} tier) § ${out.heading}. Only that passage changed; every other section is byte-identical. New version: ${out.version}${red}` }] }
+    },
+  )
+
   server.registerTool(
     'writing_style',
     {
@@ -1462,9 +1577,20 @@ export async function runServer(version) {
       const redList = Array.isArray(out?.redLinks) && out.redLinks.length ? `\nRed-links (wanted nodes): ${out.redLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
       const retiredList = Array.isArray(out?.retiredLinks) && out.retiredLinks.length ? `\nRetired links (not current or wanted): ${out.retiredLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
       const stamps = Array.isArray(out?.identifiers) && out.identifiers.length ? `\nIdentifier stamps (join keys): ${out.identifiers.map((i) => `[[${i}]]`).join(', ')}` : ''
+      // TIER RETARGET — say it out loud. The server has always computed these (AuthorResult.tierCorrections)
+      // and its own comment says corrections are "surfaced (not hidden)", but nothing ever printed them, so
+      // the intent died at the client. That silence is not cosmetic: on 2026-07-29 a correction to
+      // cortex-cross-editor-hub landed on the SCOPED tier while the accessible tier kept serving a claim
+      // known to be false, and the response said only "Authored (1 tier)". Whoever reads this line is the
+      // last chance to notice a page was fixed somewhere nobody reads.
+      const corrections = Array.isArray(out?.tierCorrections) && out.tierCorrections.length
+        ? `\n⚠ TIER: this wrote to ${out.tierCorrections.map((c) => `${c.actualTier} (you asked for ${c.requestedTier})`).join('; ')}.` +
+          ` If that is not the tier you meant, read_page and check which copy you just changed —` +
+          ` a page can exist at several tiers and they drift apart independently.`
+        : ''
       const verb = out?.created ? 'Created + authored' : 'Authored'
-      const note = out?.built ? `${verb} "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${retired} retired, ${red} red.${retiredList}${redList}${stamps}`
-        : `No change to "${name}"${out?.skipped?.length ? ` (${out.skipped.join(', ')})` : ''}.`
+      const note = out?.built ? `${verb} "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${retired} retired, ${red} red.${corrections}${retiredList}${redList}${stamps}`
+        : `No change to "${name}"${out?.skipped?.length ? ` (${out.skipped.join(', ')})` : ''}.${corrections}`
       return { content: [{ type: 'text', text: note }] }
     },
   )

package/package.json

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

package/skills/author-docs/SKILL.md

@@ -24,8 +24,25 @@ the doc and author a synthesis. Never dump raw markdown into a page.
 1. **Detect:** run `npx -y @theronap/cortex-mcp docs-scan --json`. If `pending` is empty, stop —
    report nothing. (If no roots are registered and you just wrote docs somewhere, suggest
    `docs-scan --add-root <dir>` to the user once; don't nag.)
-2. **Author each pending doc** (skip any you judge non-substantive — scratch notes, generated
-   output; leave them unmarked and say so):
+2. **Triage each pending doc into exactly ONE of three dispositions.** Every pending doc gets one —
+   there is no fourth "deal with it later" state:
+   - **AUTHOR** it (below), then mark it.
+   - **ABSORBED** — the doc is substantive, but an existing page *already covers it as well or
+     better*. Common for build-notes and handoffs: the page kept getting updated while the doc
+     stayed frozen at its writing date. Authoring it again would duplicate, or worse, overwrite a
+     current page with a stale snapshot. **Mark it anyway** (`--mark`), and say which page absorbed
+     it. Do NOT leave it unmarked: it is genuinely handled, and leaving it pending makes every
+     future sweep re-read and re-litigate it. If the doc has one or two durable details the page
+     lacks, add just those to the page, then mark.
+   - **NON-SUBSTANTIVE** — scratch notes, generated output, throwaway logs. Leave unmarked and say
+     so, so a human can decide whether it should be registered at all.
+
+   ⚠ **A doc records the state at its writing date, never the state now.** Before writing any status
+   claim into a page, verify it against the code — a build-notes doc saying "NOT built yet" is
+   evidence about the past, not the present. Copying its status forward is the single most common way
+   this skill injects a false claim into the wiki.
+
+   To author:
    - Read the file. Decide the target node: a substantial standalone doc becomes its own
      project-kind node named by the doc's H1 title; a small note folds into its parent project's
      page as a section. Check the namespace first (`authoring_context`) — enrich an existing node
@@ -38,10 +55,14 @@ the doc and author a synthesis. Never dump raw markdown into a page.
      page just to add a link back to a doc. Fan-in is queryable (`grep "[[hub]]"` = backlinks;
      `read_page history:true` = the node's event ledger) — hub pages stay curated prose, and a doc
      belongs on the hub only when a human-judged synthesis mentions it.
-3. **Mark:** after each successful `author`, run
-   `npx -y @theronap/cortex-mcp docs-scan --mark <path>`. Never mark a doc whose author failed —
-   it should stay pending for the next sweep.
-4. **Report:** one short block — each doc → the page it became (or why skipped).
+3. **Mark:** run `npx -y @theronap/cortex-mcp docs-scan --mark <path>` for every doc you AUTHORED or
+   judged ABSORBED. Never mark a doc whose `author` failed — it must stay pending for the next sweep.
+4. **Verify before reporting.** For each doc you claim you authored, confirm the write actually landed
+   (`read_page` or `page_history`) — an `author` that returns "no change" when you intended an update
+   did NOT land. Never report a page you did not confirm.
+5. **Report:** one short block — each doc → the page it became, the page that absorbed it, or why it
+   was left unmarked. The count of pending docs should be zero afterwards except for the
+   non-substantive ones you deliberately left.
 
 ## Safety rules