ctxr-cli 0.20.1 → 0.22.0

package/templates/skills/ctxr-research.md

@@ -0,0 +1,108 @@
+Research a question against real sources and land what you find in this store. The method is a grounded
+adaptation of Stanford's STORM: question the topic from several perspectives, ground each one in sources,
+reconcile what they disagree on, and review the result before anyone acts on it. Grounding beats fluency: every
+load-bearing claim traces to a source of adequate tier, and a confident sentence with nothing behind it is the
+failure this procedure exists to catch.
+
+## When
+
+Use it when the operator asks to research, investigate, compare, or map something and the answer should rest on
+outside sources. For a single fact, fetch it and stop. For a question the store already answers, retrieve it
+(AGENTS.md's retrieval section) instead.
+
+## 1. Frame
+
+1. **What the store already knows.** First check the harness's connected meeting and note sources for primary
+   material on the topic that was never captured, and capture it (`ctxr-capture`): it is the cheapest evidence
+   the pass will get. Then retrieve: the catalog section (`ctxr catalog show --section <id>`), the graph around
+   the nearest note (`ctxr context gather --seed <path> --hops 2`), and your own search for literals. Read the
+   cluster. What is known, and what is missing, decides whether this ends as a new note or an edit.
+2. **One scoping question, then commit.** A research question is nearly always under-specified: the lens, the
+   depth, where the result goes, the constraints. If it is ambiguous, ask one question with up to four explicit
+   options and a stated default, then start. Never make the operator pre-decide six dimensions.
+
+## 2. Perspectives
+
+The quality of research is set by the questions asked, and one viewpoint asks a narrow set. Pick at most three
+angles that fit the topic, plus the basic facts. A starter set — swap in others (the regulator, the operator, the
+competitor) when the topic calls for them:
+
+- **Practitioner** — what does daily use reveal that theory misses?
+- **Academic** — what does the peer-reviewed evidence say, and where does it contradict popular belief?
+- **Skeptic** — what is the strongest counterargument, and what do proponents ignore?
+- **Economist** — who profits from the current narrative, and what incentives shape it?
+- **Historian** — what parallels exist, and how did they play out?
+
+A perspective you name and then cannot source — the fetch failed, the source is paywalled, no primary exists —
+is reported as unsourced, and the findings that lean on it are downgraded. A named angle that was never grounded
+makes single-source research look multi-perspective.
+
+## 3. Search with what the harness has
+
+Never search with the raw question. Turn each angle's questions into two or three search-box queries: strip the
+conversational framing ("how does X compare to Y" becomes `X vs Y benchmark`, `X limitations`), add operators
+that favour primary sources (`site:`, `filetype:pdf`, an exact phrase, a year), and run a query two
+angles both need once.
+
+Web access differs by harness and by machine — one has a native search tool, another a browser reached through
+its own route, another nothing. Use what this harness provides. When the store documents its own browser
+routing (a store skill or convention), follow it. When the harness can reach no web source at all, say so and
+stop: research filled in from memory is the failure mode, not a fallback.
+
+When a fetch comes back empty: official sites often refuse a plain fetch or build their body with JavaScript —
+use a browser, or a static mirror of the same text; a site behind a bot wall that refuses both is a gap to
+report, not to work around. Save a raw API or search response to `__SCRATCH_PATH__` before parsing it, and confirm a
+surprising result with a second, independent query: a parsed response can look authoritative and be wrong. Keep
+the fetched corpus there too, so a follow-up pass re-reads rather than re-fetches.
+
+## 4. Tier the sources
+
+Read in tier order, and never let a lower tier carry a decision alone.
+
+- **Primary** — filings, official documentation, the paper or repository itself, first-party data, named
+  on-record statements, preprint servers, structured company and market databases.
+- **Secondary** — reputable press and analysts. Weight pure opinion down.
+- **Weak** — vendor marketing, content farms, listicles, undated posts, review aggregators, a single social
+  post. Signal only.
+- **Unreliable** — sources known for fabrication. Dropped.
+
+## 5. Map the contradictions
+
+STORM grounds a claim in sources but never reconciles them. Before synthesizing:
+
+- **Direct contradictions** — record both claims with their dates and tiers. Recency and tier break most ties;
+  when they do not, carry the conflict as an open question.
+- **Perspective tension** — angles that reached different conclusions. The tension is often the finding.
+- **Source bias transfer** — a load-bearing claim resting on a weak, partisan, or vendor source, or an apparent
+  consensus whose sources all trace to one origin. Require an independent primary source for anything
+  decision-critical; label vendor and partisan sources inline.
+- **Over-association** — a claim connecting two facts that no single source connects, or one that traces to no
+  source at all. Cut it, or mark it as inferred.
+- **The blind spot** — what no perspective and no source addressed. Often the most valuable finding.
+
+## 6. Synthesize
+
+Draft the structure from what you know, then refine it against the sources: knowledge for the shape, evidence for
+the content. Resolved tensions become findings; unresolved ones become open questions. Then judge against the
+store: what the research confirms, extends, contradicts, or nuances in the notes you read in step 1.
+
+## 7. Review before anyone acts on it
+
+- **Gap pass** — what did the material raise that no angle answered? Those are the open questions.
+- **Self-review against step 5** — did synthesis drop an unresolved tension, promote an inferred claim to fact,
+  or lean on an unsourced perspective? Re-run the bias and over-association checks on the finished text: writing
+  prose invents connective tissue, and a link that felt natural to write is where over-association hides.
+- **Score each key finding** by the tier behind it, not its tone, and re-verify, downgrade, or flag the weakest.
+- **For findings someone will act on**, or that contradict the store's current view, get a model-diverse review
+  (`ctxr-second-opinion`) and treat its dissent as another source, not a vote.
+
+## 8. Land it
+
+When the result belongs in the store, `ctxr-ingest-orchestration` decides how it lands — new note, update,
+merge, restructure, or a section — and its thesis-change rule applies when the research overturns an existing
+conclusion. `ctxr-placement` chooses the folder and template. Capture a source through `ctxr-capture` when a
+decision rests on its content, so the evidence outlives the link; otherwise cite it with its tier and the date
+you read it. A chat-only answer says so and files nothing.
+
+Report what the research found, its open questions, and which notes it touched, and record a pass that filed
+notes in the store log at `__LOG_PATH__`.

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.
 

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`.