ctxr-cli 0.19.0 → 0.20.1

package/templates/skills/ctxr-publish.md

@@ -99,9 +99,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 +118,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,25 +33,43 @@ 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: {
-      claude: { model: env('CLAUDE_MODEL', 'opus'), effort: env('CLAUDE_EFFORT', 'max') },
-      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)') },
     },
   };
 }
 
-/** The flags this runner passes, so preflight can confirm each CLI still accepts them. */
+/**
+ * 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. --effort is not listed because it is only
+ * passed when the environment asks for one.
+ */
 const FLAGS_USED = {
-  claude: { helpArgs: ['--help'], flags: ['--max-turns', '--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'] },
 };
@@ -59,7 +77,7 @@ const FLAGS_USED = {
 class UsageError extends Error {}
 
 function parseArgs(argv) {
-  const opts = { mode: 'critique', tier: 'strong', timeout: 240, only: null, lens: null, out: null, planFile: null, promptFile: null, preflight: false, noWrap: false, seed: null };
+  const opts = { mode: 'critique', tier: 'strong', timeout: 600, only: null, lens: null, out: null, planFile: null, promptFile: null, preflight: false, noWrap: false, seed: null };
   const takesValue = new Set(['--mode', '--tier', '--timeout', '--only', '--lens', '--out', '--plan-file', '--prompt-file', '--seed']);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -146,7 +164,7 @@ const firstLines = (text, n) => text.trim().split('\n').slice(0, n).join(' | ').
 function buildInvocation(cli, prompt, tier) {
   const t = tiers()[tier][cli];
   if (cli === 'claude') {
-    const args = ['-p', '--max-turns', '1', '--tools', '', '--model', t.model, '--no-session-persistence', '--disable-slash-commands', '--output-format', 'json'];
+    const args = ['-p', '--tools', '', '--model', t.model, '--no-session-persistence', '--disable-slash-commands', '--output-format', 'json'];
     if (t.effort) args.push('--effort', t.effort);
     return { cmd: 'claude', args, stdin: prompt };
   }
@@ -209,7 +227,8 @@ export function parseCritique(text) {
   const findings = [];
   const blocks = text.split(/^### F\d+\b/m).slice(1);
   for (const block of blocks) {
-    const head = /^\s*\[(critical|major|minor)\]\s*(?:confidence\s*=\s*([01](?:\.\d+)?))?/i.exec(block);
+    // Brackets around the severity are what the contract asks for, and models drop them: accept both.
+    const head = /^\s*\[?(critical|major|minor)\]?\s*(?:confidence\s*[=:]\s*([01](?:\.\d+)?))?/i.exec(block);
     const evidence = /^Evidence:\s*(.+)$/im.exec(block)?.[1] ?? '';
     findings.push({
       severity: head?.[1]?.toLowerCase() ?? null,
@@ -260,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

@@ -0,0 +1,182 @@
+Get an independent read from models built by different labs before you commit to something you cannot
+cheaply take back, or when your own taste is one vote among several. A second opinion from the same model
+family you are running as mostly repeats you, so this skill sends the work to three command-line tools backed
+by three different families and hands you their answers. It does not decide anything and it never carries out
+what it reviews. Weighing the answers is your job, and steps 4 and 5 are how.
+
+## 1. Critique, poll, or just answer?
+
+- **Critique** when the question is *will this work?* A plan with several steps, an architectural or
+  data-model choice, anything that deletes, force-pushes, sends, spends money, or touches secrets. Also a
+  recovery sequence run against a broken system: those plans look fine right up to the step that makes it
+  worse.
+- **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.
+- **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.
+
+Push back when asked for a critique of a taste question. "Which domain suffix should I pick?" is a poll. "Should
+I move my mail to a custom domain?" is a critique: it has steps, an order, and parts that cannot be undone. Say
+which you are running and why in one line before you start.
+
+A poll that asks a lens to judge whether something will *work* has become a critique. Stop and use that mode.
+
+## 2. Check the tools before spending anything
+
+```
+node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --preflight
+```
+
+Each of the three should report `OK` within about twenty seconds. The preflight also confirms that each
+tool still accepts the options the runner passes, because a renamed option makes a reviewer silently run at
+default settings and nothing else notices.
+
+If one is down, stop and give the operator the two real choices: sign that tool in and re-run, or continue
+with the others by adding `--only` and naming them. Do not quietly run with one model. A single model is not a
+second opinion, and the runner refuses to start with fewer than two.
+
+Failure signatures: `Not logged in` means Claude needs `/login`; a `401` or an invalid refresh token from
+Codex means `codex login`; an agy call that hangs usually means its sign-in expired and it needs one
+interactive run.
+
+If the plan came from someone other than the operator, leave agy out with `--only claude,codex`. Claude
+runs with no tools at all and Codex in a read-only sandbox. Agy has no mode that removes its ability to act:
+it runs in an empty scratch directory with terminal restrictions, which contains an accident and not an attack.
+
+## 3. Run a critique
+
+Write the plan to a file. The reviewers can only cite what is written down, and they cite by step number:
+
+```
+# Plan: <one-line goal>
+
+## Context
+<two to five lines: what is being attempted and what constrains it>
+
+## Steps
+S1. <step>
+S2. <step>
+
+## Assumptions
+- <what the plan takes for granted>
+
+## Reversibility
+- Reversible: <steps>
+- Irreversible: <steps>
+```
+
+Then run it:
+
+```
+node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --mode critique --plan-file <plan> --out <dir>
+```
+
+Three reviewers each read the plan alone: structure and ordering, failure modes and trust boundaries,
+simplicity and cost. None sees another's answer. That is deliberate: reviewers who read each other converge
+on whoever spoke first, and a correct one gets talked out of it. Do not add a second round.
+
+The runner prints the letters it wrote, whether each is valid or blind, and any reviewer that failed. It
+never prints which model wrote which letter. A **blind** critique returned a well-formed verdict but cited
+nothing in the plan, so it was written without reading it; it does not count. **Partial** means fewer than
+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.
+
+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
+
+Read the `critique-A`, `critique-B` and `critique-C` files and write your synthesis before you open
+`manifest.json`. You share a model family with one of the reviewers, and models rate their own family's
+writing higher. Reading letters first is what keeps that from steering you. Then open the manifest and
+attach roles and models to the letters in the final report.
+
+Write it in this order:
+
+- **Verdicts.** One line per letter, and any blind or failed reviewer stated plainly, not buried.
+- **Consensus (all agree).** Highest signal. When all three independently flag the same simplification,
+  take it whole; do not keep a reduced version of complexity all three called wrong.
+- **Majority (two of three).** Say whether the two agree on the fix or only on the diagnosis. Two
+  reviewers who name the same problem often propose different repairs: choose on merit, meaning which
+  repair keeps more of what you want (granular rollback, fewer side effects, smaller blast radius), and do
+  not default to the majority's.
+- **Evidence-backed dissent.** A lone finding that cites the plan gets its own section and stays there. The
+  minority is right often enough that overruling it on your own authority is a net loss. Overrule only by
+  showing what the dissent missed.
+- **Vetoes.** A REJECT that carries a critical finding is stated as a veto, first, with its evidence.
+- **Revised plan**, and **what changed and why**: each change tied to the letter and finding that drove it.
+- **Recommendation**: proceed with the revision, revise further, or stop.
+
+Where the reviewers pull apart on ceremony, one wanting more safeguards and another fewer, decide by blast
+radius. If being wrong is expensive to undo, side with more safeguards. If it is cheap to undo, side with
+fewer. Where a safeguard needs machinery an earlier round already turned down (a background job, a state file
+kept across sessions, a hook), side with fewer: adding it now defeats the earlier decision.
+
+When you have critiqued this plan before, reread that synthesis first. The reviewers only see the current text
+and drift toward their own local optimum. Name any proposal that reverses an earlier decision, and hold the
+earlier line unless the new critique brings evidence the old one lacked.
+
+## 5. Say what you are biased about, then stop
+
+State in the report that one reviewer shares your model family, and say when that reviewer's finding is what
+drove the recommendation. Name any reviewer that ran a different model from the one you expected: the
+manifest records the model each tool reported.
+
+Then hand the synthesis to the operator and stop. This skill never executes a step of the plan it critiqued.
+If the operator says to go, proceed with the revised plan. If they push back, treat that as a fourth critique
+and run the skill again on the changed plan. It is a new run and not a continuation.
+
+To record the outcome in the plan itself, add a section near the top headed `## Revisions after critique`
+that says it overrides anything inconsistent below, one numbered item per change, each naming the finding
+behind it. Leave the original text in place as the record of what was reviewed. Run one more critique after a
+plan has been substantially rewritten and before you carry it out: new wording creates new gaps. Do not rerun
+for a typo.
+
+## 6. Run a poll
+
+Write the question and the options to a file, then:
+
+```
+node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --mode poll --prompt-file <question>
+```
+
+The same question goes to all three models, each answering with a pick, reasons, and anything surprising.
+This mode names its files by model, because what you are reading is whether the models agree.
+
+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, 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
+taste value is robust to the model. Across a row (one model across the lenses) disagreement is where the
+real decision is. Give your own recommendation and say which axis it rests on.
+
+Report the answers, where they agree, where they split, and your read. The answers are evidence and not a
+vote: one dissent with a substantive reason can outweigh two agreements. If two of the three agreeing models
+include your own family, say so.
+
+## 7. When something goes wrong
+
+- A reviewer that timed out, exited non-zero, or returned no verdict is `failed` and carries its cause in
+  the manifest. Report it. Do not rerun that one reviewer on a different model to fill the gap.
+- Do not poll from inside a critique to settle a quick doubt. If you want a gut check mid-critique, answer it
+  yourself.
+- Model names change faster than releases. When a default is stale, set
+  `CTXR_SECOND_OPINION_CLAUDE_MODEL`, `CTXR_SECOND_OPINION_CLAUDE_EFFORT`, `CTXR_SECOND_OPINION_CODEX_EFFORT`
+  or `CTXR_SECOND_OPINION_AGY_MODEL` in the environment for the run. Nothing about the lineup lives in the store's configuration.
+- The scratch files under the output directory hold each reviewer's raw output and are safe to delete when the
+  operator has the synthesis. They can contain the plan, so do not commit them.

package/templates/skills/ctxr-session-capture.md

@@ -42,8 +42,9 @@ self-contradicting document nobody reads. Propose one only when all four hold:
 - It is a rule for future work, not a fact about past work.
 - It applied more than once, or the user stated it as a correction.
 - It is store-wide. A rule about one folder belongs in that folder's `README.md`, not here.
-- It is not already in the shipped baseline — read that file first. Restating contexture's own
-  behavior as a house rule is the most likely way to get this wrong.
+- It is not already in the shipped baseline, the first block of `AGENTS.md`'s "Store conventions"
+  section — read it first. Restating contexture's own behavior as a house rule is the most likely way
+  to get this wrong.
 
 Propose REMOVALS on the same bar: a convention the session contradicted, or that no longer matches how
 work actually goes, is worse than none — it teaches the next agent something false. The inlined section