ghostrail 0.15.2 → 0.17.0

package/skill/ghostrail/SKILL.md

@@ -5,7 +5,7 @@ user-invocable: true
 argument-hint: "[customize | init | update | doctor | status | run | respond | triage]"
 license: Apache-2.0
 metadata:
-  version: 0.4.0
+  version: 0.7.0
 allowed-tools:
   - Read
   - Write
@@ -66,9 +66,24 @@ this tailors them to *this* repo. Never guess: read before proposing.
    - `[gate].commands` — mirroring CI exactly.
    - `[source]` — the team/project/label/assignee filters, if you can tell what
      they should be. Ask rather than invent tracker identifiers.
-4. **Do not touch** `[output].auto_merge` (it must stay `false`) or invent
+4. **Managed regions are structural. Never edit inside one.** A scaffolded
+   prompt marks the parts ghostrail owns:
+
+   ```markdown
+   <!-- ghostrail:managed id="result-contract" -->
+   ...ghostrail's text...
+   <!-- /ghostrail:managed -->
+   ```
+
+   Rewrite anything *outside* those markers freely: that is the whole point of
+   customize. Inside one, change nothing, and never move, rename, reorder, or
+   delete a marker. Those regions are how `<GR> init --update` carries a later
+   template fix into this repo without touching your wording; editing one turns
+   a silent merge into a conflict you have to port by hand forever after. If a
+   managed region genuinely blocks this repo, say so rather than editing it.
+5. **Do not touch** `[output].auto_merge` (it must stay `false`) or invent
    credentials.
-5. **Never run `<GR> run`, `<GR> triage`, or `<GR> respond` to check your edits.**
+6. **Never run `<GR> run`, `<GR> triage`, or `<GR> respond` to check your edits.**
    Those act on real tracker items, per the confirm-first rule under **run ·
    respond · triage** below, and that rule has no "just checking" exception:
    zero eligible items still means the command executed for real. If you want
@@ -112,18 +127,69 @@ Carry a template improvement into a repo that has customized its prompts. Run:
 <GR> init <template> --update
 ```
 
-It writes only files this repo never edited (proved by the baseline in
-`ghostrail.template.json`), and it never touches a customized file. For those it
-prints **signals**: what the template gained that the repo's copy lacks.
+It does as much as it can prove, in three steps.
+
+**Files this repo never edited** (proved by the baseline in
+`ghostrail.template.json`) are taken whole.
+
+**Managed regions inside a customized file are merged in place.** A region the
+repo never edited is rewritten from the template, and a region the template
+added is inserted. The file's editable text is never touched, and the file's own
+baseline is deliberately not re-recorded, so the customization stays protected.
+
+**Everything left over is reported**, as before: the placeholders and result
+fields the template gained that the repo's copy still lacks.
 
 ```
   ghostrail/prompts/resolve-issue.md
-    customized, and the template gained:
-      placeholder   {{description}}
-      result field  "testPlan"
+    customized:
+      updated         result-contract
+      inserted        prior-discussion
+      edited locally  item  (left alone; port it by hand)
+      placeholder     {{description}}
 ```
 
-Placing those is your job, and it is not a text merge. A customized prompt can
+The first two lines already happened; you do not need to do anything about them
+beyond telling the user. The rest is your job, and it is not a text merge.
+
+`edited locally` means someone edited inside a region ghostrail owns, so it was
+left alone rather than overwritten. Port the template's version of that region
+into the repo's copy by hand, keeping any local change that was deliberate. It
+keeps being reported until the region matches the template exactly.
+
+`unplaceable` means the template added a region and this file shares no managed
+region to anchor it against.
+
+`adopting regions: N/M` means the file has markers but no recorded baselines
+yet, so nothing could be merged. See **adopting regions** below.
+
+### Adopting regions in a repo that predates them
+
+A prompt scaffolded before regions existed has no markers, so `--update` says
+nothing about them and behaves exactly as it always did. Getting such a repo
+onto regions is a one-time guided pass, and it is incremental: you do not have
+to finish it in one go.
+
+1. **Add the markers**, around the text in the repo's copy that already
+   corresponds to each region. Read the template's copy to see the region ids
+   and what each one covers, then wrap the repo's own equivalent text. Do not
+   reword anything while doing this; you are only marking boundaries.
+2. **Bring each managed region to the template's current text.** This is the
+   same hand port the signal report has always asked for, done once. Keep the
+   repo's wording *outside* the markers; inside them, the template's text wins,
+   because that is what ghostrail is taking ownership of.
+3. **Re-run `<GR> init <template> --update`.** Every region that now matches the
+   template is recorded, and the report says how many. Regions you have not
+   ported yet are simply reported again.
+
+The useful part is that step 3 does not need step 2 to be complete. As soon as
+*one* region matches, that file has baselines, so a region the template added
+gets inserted automatically on the next run and only the regions you actually
+still differ on keep asking for attention. Repeat until the file reports
+`customized, nothing to take`.
+
+Never do this by taking the template's whole file. That throws away the
+customization, which is the thing the whole design exists to protect. A customized prompt can
 be a near-total rewrite that still needs the same one-line addition, so port the
 **intent**, not the template's wording:
 
@@ -139,6 +205,10 @@ be a near-total rewrite that still needs the same one-line addition, so port the
 5. Re-run `<GR> init <template> --update` and confirm it now reports
    `customized, nothing to take`.
 
+Never place a signal by editing inside a managed region, and never delete a
+marker to make a report go away. The markers are what make the next update a
+merge instead of another hand port.
+
 Verify a placeholder actually renders before anyone spends a run on it:
 
 ```
@@ -164,39 +234,20 @@ Two things to tell the user plainly:
 
 ## doctor
 
-Diagnose a setup without changing anything. Check and report each, with the fix:
-
-- **CLI** — which form resolved, and its `<GR> version`.
-- **Config** — `ghostrail.toml` present, and it parses. Read it yourself first:
-  most syntax and shape problems (bad TOML, a misnamed table, a wrong type) are
-  visible without running anything. Only `<GR> run`, `<GR> triage`, and
-  `<GR> respond` surface the dotted-path parse error the CLI produces, and they
-  execute for real even with zero eligible items, so getting that message is
-  not a free action — treat it exactly like the "run · respond · triage"
-  section requires: state what you're about to do and get confirmation first,
-  never run one silently "just to check parsing."
-- **Prompts** — every path referenced by `[agent].prompt`, `[respond].prompt`,
-  and `[triage].prompt` exists.
-- **Gate** — `[gate].commands` is non-empty for a code factory, and the commands
-  actually exist in the project's scripts.
-- **Credentials** — report which of `LINEAR_API_KEY`, `GH_TOKEN`/`GITHUB_TOKEN`,
-  and `ANTHROPIC_API_KEY` **or** `CLAUDE_CODE_OAUTH_TOKEN` are set. Report only
-  set/unset, **never print a value**. Note that `ANTHROPIC_API_KEY` wins over the
-  OAuth token, so it must be unset to bill a Pro/Max subscription. Remember they
-  can come from a file as well as the environment: `~/.config/ghostrail/secrets.env`
-  and a repo's `.ghostrail.env`, which beat an exported variable of the same name.
-  When something is missing, the fix to suggest is `ghostrail secrets-setup --write`,
-  which scaffolds that file and opens it in the user's editor. Never offer to fill
-  in a value yourself.
-- **GitHub** — `gh auth status` succeeds.
-- **Container backend**, if `[backend].kind = "container"` — the configured
-  `image` exists locally (`docker images`). If not, the fix is
-  `ghostrail image build` (add `--tag` when the config names something other
-  than `ghostrail-factory:local`). No repo checkout is needed; the Dockerfile
-  ships in the package. A `local-worktree` factory needs no image at all, so do
-  not report a missing one as a problem.
-
-Finish with a short ordered list of what to fix first.
+Run `<GR> doctor` and relay its output. It probes the setup itself — including a
+real `claude -p` call inside the configured backend and a cheap Linear query, not
+just presence checks — so describe what it actually did rather than re-deriving
+checks here (that would drift from what the command does). It never prints a
+credential value, only names and outcomes. Add `--quick` when the operator wants
+a fast, no-network answer instead (it will say plainly which checks it skipped).
+Add `--json` when the output needs to be machine-parsed (e.g. for the board).
+
+`doctor` reports whether `ghostrail.toml` parses, so there is never a reason to
+run `<GR> run`, `<GR> triage`, or `<GR> respond` just to surface a parse error;
+those execute for real even with zero eligible items.
+
+`doctor` exits non-zero when any check fails, and prints an ordered "fix first"
+list; lead with that list, then offer to walk through it one item at a time.
 
 ---
 

package/templates/code/prompts/resolve-issue.md

@@ -8,6 +8,7 @@ and PRs.
 
 Match the surrounding code: its style, patterns, and test conventions.
 
+<!-- ghostrail:managed id="item" -->
 ## The issue
 - ID: {{id}}
 - Title: {{title}}
@@ -16,6 +17,16 @@ Match the surrounding code: its style, patterns, and test conventions.
 ### Description
 
 {{description}}
+<!-- /ghostrail:managed -->
+
+<!-- ghostrail:managed id="prior-discussion" -->
+## Prior discussion
+
+If `.ghostrail/comments.md` exists, read it. It holds the comment thread on
+this issue, oldest first, and it can include a question a previous run of the
+factory asked and a human's reply. Treat an already-answered question as
+settled and act on the answer; do not ask it again.
+<!-- /ghostrail:managed -->
 
 ## What to do
 1. Locate the relevant code and understand how it is structured.
@@ -23,6 +34,7 @@ Match the surrounding code: its style, patterns, and test conventions.
 3. Add or update tests (author them from the intent, not the implementation).
 4. Run the project's lint, typecheck, and unit-test commands and fix what you touched.
 
+<!-- ghostrail:managed id="result-contract" -->
 ## Reporting your result (required, do this last)
 Write a JSON file at `.ghostrail/result.json` with exactly one of:
 
@@ -31,15 +43,19 @@ Write a JSON file at `.ghostrail/result.json` with exactly one of:
 - `{"status":"failed","error":"<why>"}`
 - `{"status":"noop","reason":"<why nothing needed changing>"}`
 
-`type` is the conventional-commit type for the change; it sets the commit and PR
-title. If you omit it, the factory's configured default is used.
+`type` is the conventional-commit type for the change (pick the one that fits:
+`feat` for a feature, `fix` for a bug, `docs`, `refactor`, ...); it sets the
+commit and PR title. If you omit it, the factory's configured default is used.
+
+`summary` and `testPlan` are rendered into the pull request body under headings
+the factory supplies, so do not add headings of your own.
+<!-- /ghostrail:managed -->
 
 `summary` and `testPlan` are the pull request a human reads, so write them for
 that reader rather than as a log of what you did:
 
 - **`summary`**: one or two sentences on what changed and why, then markdown
-  bullets for the specifics. Do not write a single long paragraph, and do not
-  add headings; the factory supplies its own.
+  bullets for the specifics. Do not write a single long paragraph.
 - **`testPlan`**: the steps someone runs to check this by hand. Concrete
   commands, what to look at, and what they should see. The gate has already run
   lint, typecheck, and the unit suite, so do not just repeat those: give the

package/templates/code/prompts/respond.md

@@ -5,9 +5,11 @@ of an open pull request. New human feedback has been left on the PR or its track
 issue. Address it. You may only read and write files and run shell commands in
 this workspace. Do not use git: the factory owns commits and pushes.
 
+<!-- ghostrail:managed id="feedback" -->
 ## The feedback
 Read `.ghostrail/feedback.md`. It contains the new comments (author and time),
 newest work last. Treat it as the review to act on.
+<!-- /ghostrail:managed -->
 
 ## What to do
 1. Read the feedback and the current state of the branch.
@@ -16,6 +18,7 @@ newest work last. Treat it as the review to act on.
 4. If a comment is a question rather than a change request, answer it in your result
    (see `blocked`) instead of guessing.
 
+<!-- ghostrail:managed id="result-contract" -->
 ## Reporting your result (required, do this last)
 Write a JSON file at `.ghostrail/result.json` with exactly one of:
 
@@ -23,5 +26,6 @@ Write a JSON file at `.ghostrail/result.json` with exactly one of:
 - `{"status":"blocked","questions":"<what you need answered>"}`
 - `{"status":"failed","error":"<why>"}`
 - `{"status":"noop","reason":"<why nothing needed changing>"}`
+<!-- /ghostrail:managed -->
 
 On `done` the factory commits and pushes to the PR branch and posts a summary.

package/templates/code/prompts/triage.md

@@ -5,6 +5,7 @@ NOT to fix it: it is to decide whether the issue is too large to fix in one pass
 and, if so, propose how to break it into smaller, ordered sub-issues. Do not use
 git and do not change any source files except the two output files below.
 
+<!-- ghostrail:managed id="item" -->
 ## The issue
 - ID: {{id}}
 - Title: {{title}}
@@ -13,6 +14,16 @@ git and do not change any source files except the two output files below.
 ### Description
 
 {{description}}
+<!-- /ghostrail:managed -->
+
+<!-- ghostrail:managed id="prior-discussion" -->
+## Prior discussion
+
+If `.ghostrail/comments.md` exists, read it. It holds the comment thread on
+this issue, oldest first, and it can include a question a previous triage pass
+asked and a human's reply. Treat an already-answered question as settled and
+act on the answer; do not ask it again.
+<!-- /ghostrail:managed -->
 
 ## What to do
 1. Read the issue and enough of the codebase to judge its scope.
@@ -26,6 +37,7 @@ git and do not change any source files except the two output files below.
    when you produced a plan, or `{"status":"blocked","questions":"<what you need>"}`
    if you genuinely cannot decide without a human.
 
+<!-- ghostrail:managed id="triage-schema" -->
 ## `.ghostrail/triage.json` schema
 
 Atomic (no split):
@@ -50,6 +62,7 @@ Split into sub-issues:
 - `dependsOn` lists the indices of earlier sub-issues (0-based, all strictly
   less than the current one) that must be done first.
 - Keep titles imperative and specific. Each sub-issue should stand on its own.
+<!-- /ghostrail:managed -->
 
 The factory creates the sub-issues (unassigned) and a human assigns each to the
 bot to start work; the parent leaves the triage queue.

package/templates/content/prompts/draft.md

@@ -4,6 +4,7 @@ You are a writing agent working in an isolated checkout. Write the piece
 described below as a Markdown file. You may only read and write files. Do not use
 git: the factory owns commits, branches, and PRs.
 
+<!-- ghostrail:managed id="item" -->
 ## The brief
 - ID: {{id}}
 - Title: {{title}}
@@ -12,6 +13,16 @@ git: the factory owns commits, branches, and PRs.
 ### Description
 
 {{description}}
+<!-- /ghostrail:managed -->
+
+<!-- ghostrail:managed id="prior-discussion" -->
+## Prior discussion
+
+If `.ghostrail/comments.md` exists, read it. It holds the comment thread on
+this item, oldest first, and it can include a question a previous run of the
+factory asked and a human's reply. Treat an already-answered question as
+settled and act on the answer; do not ask it again.
+<!-- /ghostrail:managed -->
 
 ## Shared references
 Read any files under `.ghostrail/artifacts/` (voice and style, formats,
@@ -22,6 +33,7 @@ strategy). Follow them closely: they define how this work should read.
 2. Match the voice, structure, and formats in the shared references.
 3. Do not publish or post anything; produce a draft only.
 
+<!-- ghostrail:managed id="result-contract" -->
 ## Reporting your result (required, do this last)
 Write `.ghostrail/result.json` with exactly one of:
 
@@ -29,5 +41,6 @@ Write `.ghostrail/result.json` with exactly one of:
 - `{"status":"blocked","questions":"<what you need decided>"}`
 - `{"status":"failed","error":"<why>"}`
 - `{"status":"noop","reason":"<why nothing needed changing>"}`
+<!-- /ghostrail:managed -->
 
 The factory opens a draft pull request for a human to review.

package/templates/content/prompts/respond.md

@@ -6,9 +6,11 @@ tracker issue. Revise the draft to address it. You may only read and write files
 and run shell commands in this workspace. Do not use git: the factory owns commits
 and pushes.
 
+<!-- ghostrail:managed id="feedback" -->
 ## The feedback
 Read `.ghostrail/feedback.md`. It contains the new comments (author and time),
 newest work last. Treat it as the editorial review to act on.
+<!-- /ghostrail:managed -->
 
 ## What to do
 1. Read the feedback and the current draft on this branch.
@@ -16,6 +18,7 @@ newest work last. Treat it as the editorial review to act on.
 3. If a comment is a question rather than a change, answer it in your result
    (`blocked`) instead of guessing.
 
+<!-- ghostrail:managed id="result-contract" -->
 ## Reporting your result (required, do this last)
 Write a JSON file at `.ghostrail/result.json` with exactly one of:
 
@@ -23,3 +26,4 @@ Write a JSON file at `.ghostrail/result.json` with exactly one of:
 - `{"status":"blocked","questions":"<what you need answered>"}`
 - `{"status":"failed","error":"<why>"}`
 - `{"status":"noop","reason":"<why nothing needed changing>"}`
+<!-- /ghostrail:managed -->