ctxr-cli 0.32.0 → 0.34.0

package/templates/skills/ctxr-submit.md

@@ -5,9 +5,9 @@ a session, the conflict playbook, sequencing several pull requests) and is not r
 ## When
 
 Fires on an explicit request to wrap up — "submit", "open the PR", "push it", "ship it" — or on the
-operator's own closing utterance ("done", "that's all", a sign-off). That request is the whole reason step 8
+operator's own closing utterance ("done", "that's all", a sign-off). That request is the whole reason step 7
 needs no further confirmation: it is the consent for the push and the pull-request open. Enter without
-one and there is nothing behind those steps.
+one and there is nothing behind that step.
 
 Anti-triggers — do not enter this skill when: you have merely finished the task you were given (a
 delivered piece of work is not a closing signal, and the next message is as likely to extend it as to
@@ -16,13 +16,19 @@ asked for more work. Your own judgment that the work looks complete is never the
 your own summary saying so.
 
 Two tells that you are here uninvited. Reaching for `ctxr doctor`, `ctxr lint`, or `ctxr catalog check`
-to decide *whether* to submit — those live at step 5 and after, inside a submit already asked for, and
-running them ahead of one is a rehearsal, not a check. And composing a question like "shall I open the
-pull request?" — needing to ask is itself the answer: leave, and let the work continue.
+to decide *whether* to submit — those live at step 4 and inside `ctxr session submit`, in a submit already
+asked for, and running them ahead of one is a rehearsal, not a check. And composing a question like "shall
+I open the pull request?" — needing to ask is itself the answer: leave, and let the work continue.
 
 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.
 
+## A session in a mounted store
+
+A session started inside `shared/<name>` belongs to that mounted store. Run every step below from that session's worktree. The pull request opens on that store's repository. The hand-off names that store's approval page, from its own `contexture.yaml`.
+
+A session started with `ctxr session start --joins` is one part of a session of this store. Submit every part of the session. Run `ctxr session submit` once in each part's worktree. Why: each store gets its own pull request, and the command marks each pull request with the session. Do not write a session marker into a body yourself. Why: the command writes it, and it refuses a body that already carries one.
+
 ## Routes
 
 Every pull request takes one of three routes. Say which, and why, in its body:
@@ -35,57 +41,60 @@ Every pull request takes one of three routes. Say which, and why, in its body:
 
 ## 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. 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.
+`<session>` below is the session worktree's directory name, as `ctxr session list` prints it.
+
+1. Re-scan (mandatory — never replay a plan from an earlier snapshot): `ctxr session status <session>`, with
+   `--diff` when you need the changes themselves. It fetches `__DEFAULT_BRANCH__` and reports what is
+   uncommitted, the diff stat of committed and uncommitted work, and the commits ahead of
+   `origin/__DEFAULT_BRANCH__`. State moves under you while you work; name the delta from the previous scan
+   rather than silently folding new work 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
-   staged set matches the intended unit. Derived artifacts under the cache paths never stage.
-4. One coherent unit per pull request. If the session produced two disjoint units, say so and ask
-   whether to split.
-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: `<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. Before you open the pull request, run `ctxr publish urls --since origin/__DEFAULT_BRANCH__ --json`.
-   When it lists a page, add a **Pages** section to the body. The section is a table with one row per page.
-   Each row gives the page's status, its lifespan (permanent or disposable), its preview address, and its
-   published address. Copy every value from the report, never rebuilt by hand. Why: the report reads the
-   change set, and a guess from the path can be wrong. Mark the old address of a moved page as one that
-   stops working. Mark the address of a removed page the same way. Under the table, state the condition
-   one time: a preview resolves only while this pull request is open and the server can see this
-   session's worktree, and the published address resolves when the served checkout has the landed commit.
-   When the report has no preview, leave out that column. When it says that no base URL is declared, say
-   that the addresses are bare routes. When it lists no page, add no section.
-   Then run `ctxr graph diff --since origin/__DEFAULT_BRANCH__ --format markdown`. Paste its output into the
-   body verbatim, as the **Knowledge changes** section. Do not add, remove, or change a word of it. Why: you
-   wrote the change, and the reviewer checks your account against this record, which the command wrote.
-   Always paste the block, also when it says that the range changes no note. Why: a missing section looks the
-   same as a skipped step. The block is the record of the change. The review address in the block is a
-   convenience only. Why: it resolves only while this session's worktree exists and the server can reach it.
-   Then run `git push -u origin "<branch>"`. Then run `gh pr create --base __DEFAULT_BRANCH__ --title "<title>"
-   --body "<why / what changed / route / verification / follow-ups>"`. `gh` reads its own credential file, so
+3. One coherent unit per pull request. `ctxr session submit` commits every change in the worktree outside
+   the derived paths, so what the re-scan shows is what ships. If the session produced two disjoint units,
+   say so and ask whether to split; anything that should not ship leaves the worktree before step 7. Derived
+   artifacts under the cache paths never ship, and the command refuses an index that holds one, whoever
+   staged it.
+4. 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). `ctxr session submit` runs the same check as its gate and
+   commits nothing when it fails. Fix a failure; never bypass it, and never proceed past it.
+5. Name the branch: `<prefix>/<short-slug>`, with a prefix from `skill/` `feat/` `project/` `notes/` `chore/`
+   `refactor/` `fix/` unless this store's conventions say otherwise. Never let a generated name reach the
+   forge: the name you pass at step 7 replaces it. 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.
+6. Write the commit message, the title and the body. The body answers
+   `<why / what changed / route / verification / follow-ups>`. Write the why so that a reviewer does not
+   have to find it again. Do not write a Knowledge changes section or a Pages section: the command appends
+   both after your body — the Pages table from the change set's page report when a page changed, and the
+   Knowledge changes block always — and refuses a body that already carries either heading. Why: you wrote
+   the change, and the reviewer checks your account against the record the command wrote.
+7. Submit: `ctxr session submit <session> --branch "<name>" --message "<message>" --title "<title>"
+   --body-file <file>` (or `--body "<body>"` for a short one). It stages, runs the gate, commits, renames the
+   branch, pushes, and opens the pull request against `__DEFAULT_BRANCH__`, or updates the one already open
+   for the branch. Do not stop to confirm first. Why: the request to submit is the consent, and the
+   command's store-scope check is the gate on this path. Never push or open the pull request any other way;
    never export or interpolate a token, and never rewrite the origin's URL. Why: that URL can hold a
-   credential. The body answers those five questions and carries the sections above. Write the why so that a
-   reviewer does not have to find it again. Do not stop to confirm first. Why: 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 alone. Then report the pushed branch, and give the
-   operator the manual pull-request instructions. Do not retry `gh`.
-9. Verify before any retry: a transport error can arrive AFTER the push or the pull-request open already
-   succeeded. Before retrying anything, `git ls-remote origin <branch>` and `gh pr list --head <branch>` —
-   never replay a push or a pull-request open blindly.
-10. Hand off: report the pull request's number and its url, and name what landing it takes —
-    `ctxr-land`, targeting that number — so the next step is one word away instead of something to
-    reconstruct later. When this store declares `change_approval`, also give the approval page address:
-    `serve.base_url`, then `/approve/`, then the session worktree's directory name and a `/`. Why: a person
-    without a forge account approves the change there, and the change then lands without further steps.
-    Landing stays a separate decision, made on the approval page or by an explicit go. Never run it from here.
+   credential.
+   Exit `0` means the pull request is open. Exit `3` names the step that stopped it, with everything before
+   that step left in place: a failed gate (fix it and run the same submit again), a derived path in the
+   index (unstage it), a rebase in progress (finish it with the conflict playbook), or a push or forge
+   failure. Exit `2` is a refused argument: a branch name the default branch or another branch carries, or
+   a body with a generated heading. If the forge cannot be reached, report the pushed branch and give the
+   operator the manual pull-request instructions.
+8. Verify before any retry: a transport error can arrive AFTER the push or the pull-request open already
+   succeeded. `ctxr session submit` reads the remote branch and the forge's pull requests for it before it
+   pushes or opens anything, so running the same submit again is the retry, and it publishes once.
+   Submitting a session again after requested changes works the same way: a further commit on the same
+   branch, and the same pull request updated — keep `--branch` as it was.
+9. Hand off. Report each pull request's number and its url. Name what lands it: `ctxr-land`, with that
+   number, or with the session when the session has a part in more than one store. Why: the next step is
+   then one word away, not something to reconstruct later. When this store declares `change_approval`,
+   also give the approval page address that the command reports.
+   It is `serve.base_url`, then `/approve/`, then the session worktree's directory name and a `/`.
+   For a session with parts in several stores, give one address only: the session's page in the store
+   where it started. Every part's submit reports that same address. Why: a person without a forge account
+   approves the change there. One decision covers every part, and the change then lands without further
+   steps. Landing stays a separate decision, made on the approval page or by an explicit go.
+   Never run it from here.