ghostrail 0.7.3 → 0.8.0

package/skill/ghostrail/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ghostrail
-description: Drive ghostrail (the software factory) from inside this repo. Use when the user types /ghostrail, or asks to set up, customize, check, or run a ghostrail factory — scaffolding ghostrail.toml and prompts, tailoring the scaffolded prompts and gate commands to this codebase, diagnosing a broken setup, or kicking off a run/respond/triage tick.
+description: Drive ghostrail (the software factory) from inside this repo. Use when the user types /ghostrail, or asks to set up, customize, check, or run a ghostrail factory — scaffolding ghostrail.toml and prompts, tailoring the scaffolded prompts and gate commands to this codebase, carrying a later template improvement into prompts you have customized, diagnosing a broken setup, or kicking off a run/respond/triage tick.
 user-invocable: true
-argument-hint: "[customize | init | doctor | status | run | respond | triage]"
+argument-hint: "[customize | init | update | doctor | status | run | respond | triage]"
 license: Apache-2.0
 metadata:
-  version: 0.2.0
+  version: 0.3.0
 allowed-tools:
   - Read
   - Write
@@ -87,25 +87,71 @@ Scaffold the factory into this repo, then hand off to **customize**.
 
 ### Already initialized? Check for template drift
 
-If the repo already has `ghostrail.toml` and `prompts/`, do not re-run a bare
-`init` and report "0 files written" as if nothing were wrong. Run:
+If the repo already has `ghostrail.toml` and prompts, do not re-run a bare
+`init` and report "0 files written" as if nothing were wrong. See **update**
+below.
+
+Never suggest `--force` as the way to take a template update: it overwrites
+every file, destroying the gate commands, tracker filters, and prompt edits that
+**customize** wrote.
+
+---
+
+## update
+
+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.
 
 ```
-<GR> init <template> --diff
+  ghostrail/prompts/resolve-issue.md
+    customized, and the template gained:
+      placeholder   {{description}}
+      result field  "testPlan"
 ```
 
-It is read-only. It reports each scaffolded file as up to date, locally
-customized, safe to take, a conflict, or missing, using the baseline recorded in
-`ghostrail.template.json`. Summarize the rows that are not up to date, show the
-`diff` command it printed, and offer to merge template changes in by hand.
+Placing those is your job, and it is not a text merge. 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:
+
+1. Read the template's copy of the file to see how it uses the signal. The path
+   is printed by `<GR> init <template> --diff`.
+2. Read the repo's copy and find where the same idea belongs *in its structure*.
+3. Add it in the repo's own voice. A placeholder goes where that content is
+   wanted (`{{description}}` under the issue's ID/title/link block). A result
+   field goes on the matching line of the result-document list, with a
+   description written to match the surrounding entries.
+4. Never reformat, reorder, or "tidy" the rest of the file. The customization is
+   deliberate. Your diff should be as small as the signal count implies.
+5. Re-run `<GR> init <template> --update` and confirm it now reports
+   `customized, nothing to take`.
+
+Verify a placeholder actually renders before anyone spends a run on it:
+
+```
+node -e 'import("URL_TO_PROMPT_JS").then(({renderPrompt})=>{
+  const t=require("fs").readFileSync("PATH/TO/PROMPT.md","utf8");
+  const o=renderPrompt(t,{id:"TJ-1",title:"t",url:"u",description:"BODY"});
+  console.log(o.match(/\{\{[a-z]+\}\}/g) ?? "no unrendered placeholders");
+})'
+```
 
-Never suggest `--force` as the way to take a template update: it overwrites every
-file, destroying the gate commands, tracker filters, and prompt edits that
-**customize** wrote. Merging by hand is the correct path.
+Two things to tell the user plainly:
 
-If it reports no recorded baseline, the repo predates provenance. Re-running a
-bare `<GR> init` once adopts a baseline for every file that still matches the
-template exactly, which is safe and improves later diffs.
+- **The installed template is the last published release.** A repo can be
+  current with it and still behind `main`. The `--update` header names the
+  version it compared against; repeat that in your summary.
+- **A repo with no baseline gets signals but no writes.** Without a recorded
+  baseline nothing can be *shown* to be untouched, so `--update` will not
+  overwrite anything. Re-running a bare `<GR> init` once adopts a baseline for
+  every file that still matches the template exactly, which is safe and makes
+  later updates able to write.
 
 ---
 

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

@@ -13,6 +13,10 @@ Match the surrounding code: its style, patterns, and test conventions.
 - Title: {{title}}
 - Link: {{url}}
 
+### Description
+
+{{description}}
+
 ## What to do
 1. Locate the relevant code and understand how it is structured.
 2. Make the smallest correct change that resolves the issue.
@@ -22,10 +26,24 @@ Match the surrounding code: its style, patterns, and test conventions.
 ## Reporting your result (required, do this last)
 Write a JSON file at `.ghostrail/result.json` with exactly one of:
 
-- `{"status":"done","summary":"<what you changed>","type":"<feat|fix|docs|refactor|chore|...>"}`
+- `{"status":"done","summary":"<what changed and why>","testPlan":"<how to check it by hand>","type":"<feat|fix|docs|refactor|chore|...>"}`
 - `{"status":"blocked","questions":"<a real product/design decision you need>"}`
 - `{"status":"failed","error":"<why>"}`
-- `{"status":"noop"}`
+- `{"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.
+
+`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.
+- **`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
+  commands that exercise what you actually changed. If the change is not
+  observable by hand (a refactor, a type fix), say what to run instead and what
+  a green result proves.
+

package/templates/code-local/prompts/respond.md

@@ -22,6 +22,6 @@ Write a JSON file at `.ghostrail/result.json` with exactly one of:
 - `{"status":"done","summary":"<what you changed in response>"}`
 - `{"status":"blocked","questions":"<what you need answered>"}`
 - `{"status":"failed","error":"<why>"}`
-- `{"status":"noop"}`
+- `{"status":"noop","reason":"<why nothing needed changing>"}`
 
 On `done` the factory commits and pushes to the PR branch and posts a summary.

package/templates/code-local/prompts/triage.md

@@ -10,6 +10,10 @@ git and do not change any source files except the two output files below.
 - Title: {{title}}
 - Link: {{url}}
 
+### Description
+
+{{description}}
+
 ## What to do
 1. Read the issue and enough of the codebase to judge its scope.
 2. Decide:

package/templates/content-loop/prompts/draft.md

@@ -9,6 +9,10 @@ git: the factory owns commits, branches, and PRs.
 - Title: {{title}}
 - Link: {{url}}
 
+### Description
+
+{{description}}
+
 ## Shared references
 Read any files under `.ghostrail/artifacts/` (voice and style, formats,
 strategy). Follow them closely: they define how this work should read.
@@ -21,9 +25,9 @@ strategy). Follow them closely: they define how this work should read.
 ## Reporting your result (required, do this last)
 Write `.ghostrail/result.json` with exactly one of:
 
-- `{"status":"done","summary":"<one-paragraph summary of the draft>"}`
+- `{"status":"done","summary":"<what you drafted and why>","testPlan":"<how to review it>"}`
 - `{"status":"blocked","questions":"<what you need decided>"}`
 - `{"status":"failed","error":"<why>"}`
-- `{"status":"noop"}`
+- `{"status":"noop","reason":"<why nothing needed changing>"}`
 
 The factory opens a draft pull request for a human to review.

package/templates/content-loop/prompts/respond.md

@@ -22,4 +22,4 @@ Write a JSON file at `.ghostrail/result.json` with exactly one of:
 - `{"status":"done","summary":"<what you revised>"}`
 - `{"status":"blocked","questions":"<what you need answered>"}`
 - `{"status":"failed","error":"<why>"}`
-- `{"status":"noop"}`
+- `{"status":"noop","reason":"<why nothing needed changing>"}`