ctxr-cli 0.20.0 → 0.21.0

package/templates/skills/ctxr-placement.md

@@ -31,6 +31,11 @@ clutter — worse than a slightly crowded existing one. Starting small and promo
 starting big and hollow is not. Make the promotion trigger a rule, not a vibe, and write it INTO the
 note: "Promote to its own top-level location the moment this holds 3+ distinct notes or topics."
 
+A unit that will carry supporting notes (a project with its research, an exploration with its evidence)
+gets a folder of its own. The graph clusters notes by their first __CLUSTER_DEPTH__ path segments, so
+grouping such units under one common parent at that depth merges their clusters, and the graph then asserts
+a relationship between them that does not exist.
+
 ## 4. What must never enter the store?
 
 Credentials, full account numbers, and secrets never enter the store — last-4 only. This is a placement

package/templates/skills/ctxr-publish.md

@@ -51,7 +51,8 @@ says something.
 When `gather` reports that an existing page belongs at the reported path too, it is because this
 subject is acquiring a second page, and a subject's pages collect under one folder naming it. Move
 that page there before you scaffold the new one, and tell the operator its URL changed — somebody
-may already be holding that link. `gather` moves nothing itself, and it names which signal counted
+may already be holding that link. `ctxr publish urls` reports the old address beside the new one, and
+`ctxr-submit` carries both into the pull request. `gather` moves nothing itself, and it names which signal counted
 the page as this subject's; read that before you move anything, because the signal is a reading of
 the page's README and can be wrong. Lead a page's source notes with the note it is a representation
 of — that lead link is what says whose page this is, and everything after it is a citation.
@@ -99,9 +100,17 @@ before reporting the page as ready. It answers only what's derivable from the fi
 in step 1, the form and reader choices in step 5, and factual accuracy stay judgment calls, not checker output.
 
 `ctxr publish new` and `ctxr publish check` each end by naming the address `ctxr serve` answers for
-this page. Open it and look at the page before you hand it on. Whether the form works, whether the
-prose reads, whether it renders at all is exactly what the checks above cannot answer, and it is
-cheapest to fix while the page is still yours.
+this page. Look at the page before you hand it on. Whether the form works, whether the prose reads,
+whether it renders at all is exactly what the checks above cannot answer, and it is cheapest to fix
+while the page is still yours.
+
+That address may be served from another host, or behind an access proxy, where you cannot reach it.
+You do not need it: from this machine, start `ctxr serve` in the background, open the address it
+prints followed by the page's route in your browser tool, and stop the server when you are done. A
+page still in a session worktree is served there under its previewable route, the same as anywhere
+else. If you have no way to see a rendered page, say in your hand-off that it has not been checked
+visually, so whoever reviews it knows they are the first to look. Never report a page as ready on the
+strength of `ctxr publish check` alone.
 
 A page written in a session worktree is previewable rather than published, because the
 published-pages address reads the store's own checkout and the page has not reached it yet. That
@@ -110,6 +119,11 @@ previewable address stops answering the moment the worktree is reclaimed — the
 Report the address you actually opened, and say which of the two it is, so nobody is handed a link
 that is about to change.
 
+Both addresses are full URLs when the store declares `serve.base_url` in `contexture.yaml`, and bare
+routes such as `/preview/…` when it does not. A bare route is not a link anyone else can open. Do not
+guess a host to put in front of it: hand on the route as it is, and tell the operator that declaring
+`serve.base_url` would make every address a command reports a link.
+
 ## 7. It's a page, not a note
 
 The published-pages location is excluded from retrieval by default — a page never becomes a source for

package/templates/skills/ctxr-second-opinion/lenses.md

@@ -12,4 +12,6 @@ drop one: a collapsed pair adds cost and no breadth.
 - **brand-strategist** — long-term positioning, category ownership, how it ages.
 
 A store may add its own lens inline as `Name:description`, for example
-`"Plainspoken:blunt, substance first, distrusts slogans"`.
+`"Plainspoken:blunt, substance first, distrusts slogans"`. The description may contain commas. A comma starts
+the next lens only when the text after it is exactly a lens name above or begins `Name:`, so keep colons out
+of a description.

package/templates/skills/ctxr-second-opinion/run.mjs

@@ -33,19 +33,30 @@ const MAX_ARGV_BYTES = 120_000;
 
 const env = (name, fallback) => process.env[`CTXR_SECOND_OPINION_${name}`] || fallback;
 
-/** Model choice lives here, in one table. Override by environment, never by editing a store. */
+/**
+ * Model choice lives here, in one table. Override by environment, never by editing a store.
+ *
+ * Effort is each provider's own recommended default, not one this runner picked:
+ *  - claude: no --effort at all, so Claude Code applies its own default for the model.
+ *  - codex: `medium`, the default its model catalog declares (`default_reasoning_level`). It is passed
+ *    explicitly because the flag cannot simply be left off: with no pin in config.toml, codex resolves to
+ *    `reasoning effort: none` on a ChatGPT login (seen 2026-10-05), which is no review at all. `low` at the
+ *    `fast` tier. A machine that pins its own effort in config.toml is overridden by this; set
+ *    CTXR_SECOND_OPINION_CODEX_EFFORT to use another.
+ *  - agy: the effort is part of the model name; `(High)` is Gemini's default thinking level.
+ * For scale: on one short plan Claude took 35 s at `high` and 514 s at `max`, so a deeper pass is a choice
+ * (CTXR_SECOND_OPINION_CLAUDE_EFFORT=max), not something to leave on by default.
+ */
 function tiers() {
   return {
     strong: {
-      // `high`, not `max`: the same two-and-a-half-thousand-character plan took Claude 35 s at `high` and 514 s at
-      // `max` (and once timed out at 280 s), with a valid critique both times. `max` stays one variable away.
-      claude: { model: env('CLAUDE_MODEL', 'opus'), effort: env('CLAUDE_EFFORT', 'high') },
-      codex: { effort: env('CODEX_EFFORT', 'xhigh') },
+      claude: { model: env('CLAUDE_MODEL', 'opus'), effort: env('CLAUDE_EFFORT', null) },
+      codex: { effort: env('CODEX_EFFORT', 'medium') },
       agy: { model: env('AGY_MODEL', 'Gemini 3.1 Pro (High)') },
     },
     fast: {
-      claude: { model: env('CLAUDE_MODEL', 'haiku'), effort: null },
-      codex: { effort: env('CODEX_EFFORT', 'medium') },
+      claude: { model: env('CLAUDE_MODEL', 'haiku'), effort: env('CLAUDE_EFFORT', null) },
+      codex: { effort: env('CODEX_EFFORT', 'low') },
       agy: { model: env('AGY_MODEL', 'Gemini 3.8 Flash (High)') },
     },
   };
@@ -54,10 +65,11 @@ function tiers() {
 /**
  * The flags this runner passes, so preflight can confirm each CLI's --help still lists them. Only flags
  * the help text documents belong here: `claude` still accepts a hidden --max-turns, but with `--tools ""`
- * there is no tool turn to bound, so it is not passed at all.
+ * there is no tool turn to bound, so it is not passed at all. --effort is not listed because it is only
+ * passed when the environment asks for one.
  */
 const FLAGS_USED = {
-  claude: { helpArgs: ['--help'], flags: ['--tools', '--model', '--effort', '--no-session-persistence', '--disable-slash-commands', '--output-format'] },
+  claude: { helpArgs: ['--help'], flags: ['--tools', '--model', '--no-session-persistence', '--disable-slash-commands', '--output-format'] },
   codex: { helpArgs: ['exec', '--help'], flags: ['--skip-git-repo-check', '--sandbox', '--ephemeral', '--color', '--config'] },
   agy: { helpArgs: ['--help'], flags: ['--print', '--sandbox', '--disable-slash-commands', '--model'] },
 };
@@ -267,13 +279,28 @@ function loadLensRoster() {
   return roster;
 }
 
+/**
+ * Splits `--lens` into one string per lens. Lenses are comma-separated, but an inline description may itself
+ * contain commas: a fragment starts a NEW lens only when it is exactly a roster name or begins `Name:`;
+ * any other fragment continues the lens before it. So `minimalist,House taste:blunt, anti-slogan` is two
+ * lenses, and a description must not contain a colon (that would read as the start of another lens).
+ */
+export function splitLenses(spec, roster) {
+  const lenses = [];
+  for (const fragment of spec.split(',').map((f) => f.trim()).filter(Boolean)) {
+    const startsLens = roster.has(fragment.toLowerCase()) || /^[^:,]{1,40}:/.test(fragment);
+    if (startsLens || lenses.length === 0) lenses.push(fragment);
+    else lenses[lenses.length - 1] += `, ${fragment}`;
+  }
+  return lenses;
+}
+
 function lensBlock(spec) {
   const roster = loadLensRoster();
-  const specs = spec.split(',').map((s) => s.trim()).filter(Boolean);
   const described = [];
-  for (const s of specs) {
+  for (const s of splitLenses(spec, roster)) {
     if (roster.has(s.toLowerCase())) described.push(`- ${s.toLowerCase()} — ${roster.get(s.toLowerCase())}`);
-    else if (s.includes(':')) {
+    else if (/^[^:,]{1,40}:/.test(s)) {
       const [name, ...rest] = s.split(':');
       described.push(`- ${name.trim()} — ${rest.join(':').trim()}`);
     } else throw new UsageError(`unknown lens "${s}" (known: ${[...roster.keys()].join(', ')}; or pass "Name:description")`);

package/templates/skills/ctxr-second-opinion.md

@@ -13,6 +13,11 @@ what it reviews. Weighing the answers is your job, and steps 4 and 5 are how.
 - **Poll** when the question is *which of these is better?* and being wrong costs mild regret: a name, a
   framing, a piece of copy, which of several tools fits. If all three agreeing would settle it, it is a poll.
   If you would still want each reviewer's top objections and a suggested edit, it is a critique.
+A critique is required, not optional, before implementing a change that is architectural, irreversible, or touches
+what may be disclosed and to whom — run it on the written plan before the work, never as a justification after it.
+Its verdict, and the reasoning behind the option chosen, land in the pull request's body: for a structural change
+the pull request and its commit are the decision record, and there is no separate governance step.
+
 - **Answer directly** when there is one right answer, when the operator has already decided and wants
   confirmation, or when the work is read-only investigation.
 
@@ -82,11 +87,17 @@ nothing in the plan, so it was written without reading it; it does not count. **
 two valid critiques: say so at the top of your answer and do not call anything a consensus.
 
 Add `--tier fast` to drop each family to a cheaper model, for a plan that is small and easy to redo. The
-default tier is right for anything the operator will act on. A default critique usually takes under a minute
-and costs a few tens of cents. Claude's highest effort setting (`CTXR_SECOND_OPINION_CLAUDE_EFFORT=max`) is
-a deliberate deep pass, not a default: on the same short plan it took over eight minutes where the default
-took half a minute, and it is the one setting that can reach the runner's ten-minute limit. Start such a run
-in the background and tell the operator it is under way.
+default tier is right for anything the operator will act on.
+
+Each reviewer runs at its provider's own recommended default effort, not one this skill chose. Claude gets no
+effort setting, so Claude Code applies its default for the model. Codex gets `medium`, the default its model
+catalog declares; the runner passes it explicitly because Codex left to itself, with no setting pinned, can
+resolve to no reasoning at all. Gemini's effort is part of its model name, and `High` is its default. Measured on a
+short plan, a default critique took about 40 seconds in all, 30 to 37 seconds per reviewer, and costs a few tens
+of cents. A deeper pass is a choice: set `CTXR_SECOND_OPINION_CLAUDE_EFFORT=max` and Claude alone took over
+eight minutes on the same plan, close enough to the runner's ten-minute limit that you should start such a run
+in the background and tell the operator it is under way. A machine that pins its own Codex effort in its
+configuration is overridden by `medium`; set `CTXR_SECOND_OPINION_CODEX_EFFORT` to use another.
 
 ## 4. Synthesize on the letters first
 
@@ -150,7 +161,9 @@ This mode names its files by model, because what you are reading is whether the
 To get breadth as well as model diversity, add `--lens` with two or three taste lenses. Each model then
 answers as every lens in one response, giving a lens-by-model grid. The built-in lenses are minimalist,
 marketer, contrarian, end-user and brand-strategist. A store's own lens goes in as `Name:description`, for
-example `--lens "minimalist,Plainspoken:blunt and substance first"`. Choose lenses that pull in different
+example `--lens "minimalist,Plainspoken:blunt, substance first, distrusts slogans"`. A description may contain
+commas: a comma starts the next lens only when what follows is a built-in lens name or begins `Name:`. So a
+description must not contain a colon. Choose lenses that pull in different
 directions; if two would obviously agree, drop one.
 
 Read a lens grid on both axes. Down a column (one lens across the three models) agreement means that

package/templates/skills/ctxr-submit.md

@@ -23,13 +23,25 @@ pull request?" — needing to ask is itself the answer: leave, and let the work
 Ending a turn without that signal is normal and is not this skill. Say in one line what is uncommitted
 and which worktree holds it, then stop. The work is safe on the branch and the next message picks it up.
 
+## Routes
+
+Every pull request takes one of three routes. Say which, and why, in its body:
+
+- **Session** (the default): the session's work plus the capture it approved.
+- **Own**: a new skill, a structural change (folders, the entry document, conventions), or a refactor touching five
+  or more files — reviewed on its own so it is not buried in content.
+- **Housekeeping**: small appends nothing else depends on (a log line, a stray link fix), batched rather than folded
+  into unrelated work.
+
 ## Steps
 
 1. Re-scan (mandatory — never replay a plan from an earlier snapshot): `git fetch origin`,
    `git status --short`, `git diff --stat`, `git diff --cached --stat`,
    `git ls-files --others --exclude-standard`, `git log --oneline origin/__DEFAULT_BRANCH__..HEAD`. State moves
    under you while you work; name the delta from the previous scan rather than silently folding new work
-   into old buckets.
+   into old buckets. If the session touched or linked to an entity note, run `ctxr rollup stale --for <entity>`
+   (or a plain `ctxr rollup stale` when unsure which), and offer `ctxr-rollup` on anything flagged — never run a
+   rollup unasked; the operator decides.
 2. Capture pass: run `ctxr-session-capture` exactly once here — closing a session is itself a capture
    trigger; do not fire it again after submitting.
 3. Stage surgically: `git add <paths>`, never `git add -A`; confirm with `git status --short` that the
@@ -39,11 +51,23 @@ and which worktree holds it, then stop. The work is safe on the branch and the n
 5. Validate: run `ctxr doctor` (store scope, not `--staged` — a session's job is to leave the whole store
    healthy, not merely pass one commit's gate). Fix a failure; never bypass it, and never proceed past it.
 6. Commit: `git commit -m "<message>"`, describing the unit staged in step 3.
-7. Name the branch: if it still carries a generated name, `git branch -m "<name>"` before pushing — never
+7. Name the branch: `<prefix>/<short-slug>`, with a prefix from `skill/` `feat/` `project/` `notes/` `chore/`
+   `refactor/` `fix/` unless this store's conventions say otherwise. If it still carries a generated name,
+   `git branch -m "<name>"` before pushing — never
    let a generated name reach the forge. A name given at `ctxr session start` does not settle this: it
    named a worktree when the work began, and what ships is decided here.
-8. Run: `git push -u origin "<branch>"`, then `gh pr create --base __DEFAULT_BRANCH__ --title "<title>" --body
-   "<why / what changed / verification / follow-ups>"`. Do not stop to confirm first — the request to
+8. Before opening the pull request, run `ctxr publish urls --since origin/__DEFAULT_BRANCH__ --json`. When it
+   lists any page, the body gets a **Pages** section: a table with one row per page giving its status, its
+   preview address, and its published address — copied from the report, never rebuilt by hand. Mark a moved
+   page's old address as one that stops working, and a removed page's the same. Under the table state the
+   condition once: a preview resolves only while this pull request is open and the server can see this
+   session's worktree, and the published address resolves once the served checkout takes the landed commit.
+   When the report carries no preview, leave that column out; when it says no base URL is declared, say the
+   addresses are bare routes. When it lists no page, add no section.
+   Then run: `git push -u origin "<branch>"`, then `gh pr create --base __DEFAULT_BRANCH__ --title "<title>" --body
+   "<why / what changed / route / verification / follow-ups>"`. `gh` authenticates from its own credential
+   file: never export or interpolate a token, and never rewrite the origin's URL — it is a credential. The body answers those five questions; write the
+   why so a reviewer need not re-derive it. Do not stop to confirm first — the request to
    submit is the consent for both, and `ctxr doctor` in step 5 is the gate on this path. If `gh` has no
    reachable GitHub remote for this repository, `git push` still succeeds on its own — report the pushed
    branch and give the operator the manual pull-request instructions instead of retrying `gh`.