create-pathfinder 1.7.0 → 1.8.0

package/CLAUDE.md

@@ -76,3 +76,5 @@ An adapter carries the canonical skill's frontmatter and a pointer to it, and no
 - `reflect` — review completed work, and the reflection itself, and propose reusable workflow improvements for human approval
 - `handoff` — preserve useful state between sessions or tools
 - `skillsmith` — teach and create small local skills
+- `setup-tracker` — configure an optional external work tracker
+- `sync-tracker` — publish approved feature specs to the configured tracker, one-way and idempotently

package/README.md

@@ -27,7 +27,7 @@ The installer copies five things into your repository and nothing else:
 | --- | --- |
 | `AGENTS.md`, `CLAUDE.md` | Entry files that tell an agent how to work in the project |
 | `context/` | Project truth — overview, standards, interaction rules, current feature |
-| `skills/` | Twenty skills covering discovery, specs, delivery, debugging, review, and learning |
+| `skills/` | Skills covering discovery, specs, delivery, debugging, review, learning, and optional work tracking |
 | `templates/` | Starting points the project copies when it needs them |
 
 On request it also writes one thing it does not copy:

package/context/ai-interaction.md

@@ -20,6 +20,7 @@ Follow the project's documented policy. Unless explicitly pre-approved, ask befo
 - Git history rewriting
 - commits, merges, releases, or deployments
 - adopting prototype code into production
+- writes that leave this repository, such as creating or editing items on a shared work tracker — writing files inside the repository is an ordinary file edit and is not covered
 
 ## Git and Delivery
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pathfinder",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",

package/skills/complete-feature/SKILL.md

@@ -11,7 +11,8 @@ description: Close an accepted feature through final verification, records, deli
 4. Follow the approved commit, PR, merge, changelog, versioning, release, and deployment policy—requesting approval where required. After the merge, verify the merged mainline and clean up the merged branch as that policy requires.
 5. Append the durable outcome to `context/history.md` while completing the feature, not afterwards. If the feature was merged without this skill running, still write the entry and record that it was written after the fact.
 6. Mark/reset `context/current-feature.md` and identify the next action.
-7. Offer or invoke `learn-feature` when learning is enabled.
-8. Produce a compact completion summary.
+7. If `context/tracker.md` exists, reconcile this feature's tracked item with `sync-tracker` after the merge.
+8. Offer or invoke `learn-feature` when learning is enabled.
+9. Produce a compact completion summary.
 
 Do not claim completion when checks failed, evidence is missing, or the feature remains unaccepted.

package/skills/load-feature/SKILL.md

@@ -12,6 +12,7 @@ description: Prepare one feature for implementation by checking readiness, conte
 5. Assess whether the feature fits a focused LLM context window.
 6. Split or revise it before implementation if the context is too broad.
 7. Populate `context/current-feature.md` with the feature, first delivery chunk, context boundary, assumptions, Git state, definition of done, and out-of-scope work.
-8. Present a short readiness summary.
+8. If `context/tracker.md` exists, note this feature's tracked item, or that it has none yet. The lookup is best-effort: an unreachable tracker is reported and never blocks loading.
+9. Present a short readiness summary.
 
 Do not implement, create Git history, or resolve `TBD` decisions silently.

package/skills/setup-tracker/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: setup-tracker
+description: Configure an optional external work tracker by interviewing the human and writing context/tracker.md from the shipped template.
+---
+
+# Setup Tracker
+
+Use this skill to describe, in prose, which tracker a project uses and how
+Pathfinder's work items project onto it. The result is `context/tracker.md`.
+
+Work Tracking is **optional**. A project that never runs this skill is
+unaffected: no file, no prompt, no behaviour change anywhere. Do not run this
+skill unasked, and do not propose it as a missing step.
+
+This skill configures. It never contacts a tracker.
+
+## Rules
+
+- Do not write `context/tracker.md` without human approval.
+- Do not add code, dependencies, or an adapter for any tracker.
+- Do not invent a taxonomy the team did not ask for.
+- Keep the model section backend-neutral; vendor vocabulary belongs only under
+  the projection heading.
+- Never remove the work-item marker block. It is the one machine-stable token in
+  a prose contract, and identity depends on it.
+
+## Interview
+
+Ask progressively, in small groups. Ask only what the config cannot be written
+without:
+
+1. Which tracker, and where it lives.
+2. How an agent reaches it — a CLI, a path, or a described manual step.
+3. Which tag namespaces the project actually uses. `area`, `type`, `priority`,
+   and `agent` are available; a project needing none of them says so.
+4. What the tracker already carries. **List its existing labels, fields, or
+   conventions before proposing any tag value.** If something already means the
+   same thing, reuse it and record the mapping rather than creating a
+   near-duplicate.
+5. Anything about the projection that the shipped starting points do not cover.
+
+## Process
+
+1. Check whether `context/tracker.md` already exists. If it does, read it, and
+   treat this run as a revision — show what would change and change nothing
+   else. Never overwrite a working config wholesale.
+2. Read `templates/tracker.template.md`.
+3. Run the interview.
+4. Choose the projection:
+   - **GitHub Issues via `gh`** and **local Markdown files** ship as starting
+     points, both proven.
+   - Any other tracker is supported by the human describing it in prose, using a
+     shipped projection as the shape to follow. **That is the mechanism, not a
+     gap** — do not report an unsupported tracker as a blocker.
+5. Fill the placeholders and keep **one** projection block. Delete, in the
+   written config:
+   - the template's guidance blockquote at the top;
+   - the projection block you did not keep;
+   - the `pathfinder:model-start` and `pathfinder:projection-boundary` markers;
+   - the italic *"Keep this block for…"* line under the projection you kept — it
+     is an instruction to you, not content for the project to read.
+
+   **The model — everything between the two markers — is kept byte-for-byte.**
+   The tracker-identity paragraph above it is the one part you rewrite, because
+   it names the tracker and how to reach it.
+6. Present the proposed file and request approval.
+7. Write `context/tracker.md` only after the human approves.
+8. Report what was configured, and say plainly that nothing has been published.
+
+## Stop Condition
+
+Stop once the config is written. Publishing to a tracker is `sync-tracker`, not
+this skill. If `sync-tracker` is not installed, say so rather than publishing by
+hand.

package/skills/start-feature/SKILL.md

@@ -23,3 +23,4 @@ Restate goal, chunk, files/areas, context, risks, assumptions, verification, exc
 - Stop on conflicts between spec, durable context, and repository reality.
 - Do not add dependencies, expand scope, adopt prototype code, commit, merge, or deploy without the documented approval.
 - Do not hide multiple features inside one delivery chunk.
+- Do not publish to a work tracker, even when `context/tracker.md` exists — the repository is canonical and a chunk boundary is not a tracker event.

package/skills/sync-tracker/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: sync-tracker
+description: Publish approved feature specs to the configured work tracker, one-way and idempotently, writing nothing when nothing has changed.
+---
+
+# Sync Tracker
+
+Use this skill to project the project's approved feature specs onto the tracker
+described in `context/tracker.md`.
+
+The repository is canonical. This is a **one-way projection** of work that
+already exists. Nothing here reads tracker state back into a spec,
+`context/current-feature.md`, or `context/history.md`.
+
+## The off switch comes first
+
+**If `context/tracker.md` does not exist, do nothing at all.** Report that work
+tracking is not configured for this project, and stop.
+
+Do not create the config, do not propose configuring one, and do not describe
+its absence as a gap. Work Tracking is optional, and a project without it is
+behaving correctly.
+
+## The config is the contract
+
+Read `context/tracker.md` in full and follow its prose. It states the model, the
+projection, and the publishing rules for this project.
+
+There is **no adapter code, no vendor branch, and no required tool** beyond what
+the config itself names. If the config describes a tracker this skill has never
+heard of, that is the design working, not a blocker.
+
+Where the config is silent on something a run needs, **ask the human**. Do not
+fill the gap with a convention of your own — the next run would fill it
+differently, and every item would look modified.
+
+## What gets published
+
+**Approved feature specs only**, from `to-specs` onward — one work item per spec.
+Never debate notes, kickstart output, or prototypes. The one exception is a
+prototype that gates a decision, published as a single item phrased as the
+decision it resolves, never as a deliverable.
+
+**Do not decompose a feature.** Choosing units of execution inside a feature is a
+judgement about how work will be shared out, and it belongs to a human or to a
+skill written for it. Publish the feature.
+
+## Process
+
+1. Check for `context/tracker.md`. If it is absent, report and stop.
+2. Read the config. Read the approved specs. Read nothing else.
+3. Build the work items: key, kind, title, body, blocked-by edges, tags, and
+   chunks, derived and composed exactly as the config's model section says. Every
+   field comes from the spec — **tags only from its optional `## Tags` section,
+   never inferred.** A spec without one has no tags, which is correct and common.
+4. Order them by dependency, blockers first. If the edges contain a cycle,
+   report it and publish nothing — a guessed order is a wrong order that looks
+   fine.
+5. **Ask the human before the first write that leaves this repository.** See
+   below.
+6. Publish, following the config's *Publishing, and re-publishing* section
+   exactly: index existing items by key, create what is missing, compare
+   normalized, and leave an unchanged item completely alone.
+7. Report what was created, what was edited, and what was left alone.
+
+## The approval gate
+
+**Ask before the first write to a tracker outside this repository in a session.**
+Creating items on a shared board is outward-facing and is not covered by ordinary
+file-edit approval. One approval covers the run; do not ask per item.
+
+**A projection onto files inside this repository is not gated.** It is an
+ordinary file edit and reaches nothing outside the repository. The gate is about
+leaving the repository, not about writing.
+
+## Idempotency is the whole feature
+
+A second run over unchanged specs must **create nothing, change nothing, and
+issue zero writes**. Not writes that happen to be no-ops — no writes.
+
+- **Compare normalized, never raw bytes.** A tracker is not obliged to hand a
+  body back exactly as it was sent, and APIs differ in whether they adjust
+  trailing whitespace. Where that happens, a naive byte comparison reports every
+  item as changed on every run and rewrites all of them forever, which looks like
+  working sync and is not. Strip trailing whitespace from each line and collapse
+  trailing blank lines at the end, **on both sides**, before comparing. It costs
+  nothing when the round-trip is exact.
+- **Compare tag sets as sets**, not as ordered lists. Application order is not
+  preserved.
+- Never close, reopen, delete, or recreate an item. Edit in place.
+- Never touch an item whose key is absent from the current set. It belongs to
+  work outside this run.
+- Match on the key alone, never on the title.
+
+**Report writes, not final state.** "The tracker looks right" is satisfied by a
+run that rewrote every item, which is the specific failure this skill exists to
+avoid. `3 items, 0 changes` is the expected result of a second run and the most
+important line of output.
+
+## Rules
+
+- Do not add code, dependencies, or an adapter for any tracker.
+- Do not branch on `kind`.
+- Do not infer tags, and do not apply a value the config's mapping table does not
+  carry. A spec naming an unmapped tag is a question for the human, not a
+  judgement call.
+- Do not drop an edge that resolves outside the published set, and do not invent
+  an item for it. Resolve it against the tracker as a whole: render the item's
+  identifier if the key already has one, and name the key as untracked only when
+  it genuinely has none.
+- Do not read anything back. A ticked checkbox means nothing to Pathfinder and
+  never advances any state.
+- Do not close, reopen, or delete anything, ever.
+- Stop and report when the config, the specs, and the tracker disagree.
+
+## Stop Condition
+
+Stop once the run is reported. Configuring a tracker is `setup-tracker`, not this
+skill. If a spec set is not ready to publish, say so rather than publishing part
+of it.

package/skills/to-specs/SKILL.md

@@ -36,8 +36,12 @@ Create only the coherent MVP roadmap in `context/features/`, using `templates/fe
 
 Each spec must include Context Boundary, Delivery Chunks, and Learning Targets.
 
+Write a `## Tags` section only when the project has configured work tracking and its `context/tracker.md` defines tag namespaces. Use the values that config already lists, never invented ones. No tags is a valid and common answer — omit the section rather than guessing.
+
 After creation, summarize file, outcome, dependency, visible/verifiable win, context risk, and recommended first feature.
 
+If `context/tracker.md` exists, offer to publish the new specs with `sync-tracker`. If it does not, say nothing about tracking.
+
 ## Rules
 
 - Do not implement or install packages.

package/src/detect.mjs

@@ -119,7 +119,7 @@ function detectTool(tool, { cwd, home, env, platform }) {
  * Decided by counting skill directories rather than by testing for `CLAUDE.md`,
  * which any agent-assisted project may have written for its own reasons.
  * A `skills/<name>/SKILL.md` is a far more specific signature, and the count is
- * worth having on its own — it is what makes "already installed (20 skills)"
+ * worth having on its own — it is what makes "already installed (N skills)"
  * checkable by the person reading it.
  */
 function detectPathfinder(cwd) {

package/src/kickstart-prompt.mjs

@@ -4,7 +4,7 @@
  * This used to be one hardcoded string naming a file path, and that was right
  * for exactly as long as Pathfinder configured nothing. Once a run can generate
  * native adapters, the path form is no longer the best answer for someone who
- * just watched twenty skills be installed into their harness — it is the answer
+ * just watched the whole kit be installed into their harness — it is the answer
  * for someone whose tool cannot discover them.
  *
  * A pure function of the selection, deliberately: no filesystem, no detection,

package/templates/feature-spec.template.md

@@ -22,6 +22,12 @@ State one user-visible or system-verifiable outcome.
 
 - Earlier feature, system, decision, prototype, or `None`.
 
+## Tags
+
+- Optional. `namespace:value`, e.g. `area:cli`, `type:infra`, `agent:suitable`.
+- Omit this section entirely, or write `None`, when the project does not use tags. Most do not.
+- Only meaningful when the project has configured work tracking; nothing else reads them.
+
 ## Requirements
 
 - Requirement 1

package/templates/tracker.template.md

@@ -0,0 +1,359 @@
+# Tracker
+
+> Starting point for `context/tracker.md`. `setup-tracker` fills the placeholders
+> and keeps **one** projection block, then deletes this blockquote.
+>
+> **The file's absence is the off switch.** Work Tracking is optional. A project
+> with no `context/tracker.md` behaves exactly as it always has, and nothing in
+> Pathfinder prompts for one. Do not ship this template's output unconfigured.
+>
+> **The backend-neutral model is everything between the two markers below** —
+> from `pathfinder:model-start` down to `pathfinder:projection-boundary` — and it
+> **must be byte-identical whichever projection is chosen.** Choosing a backend
+> cuts below the projection boundary and nowhere else. Nothing inside the model
+> may be *defined* in a backend's terms — an "issue number", a "label", a file
+> path. Naming one in order to rule it out is not the same thing and is correct:
+> "edges name keys, never tracker issue numbers" is the neutrality rule being
+> stated, not a leak. The test is whether changing backend would change the
+> sentence.
+>
+> The two paragraphs above the model marker are this project's own — the tracker
+> it uses, and the rule that the repository wins. They are *not* claimed to be
+> byte-identical across backends: the first one names the tracker and how an
+> agent reaches it, so it necessarily differs.
+
+This project tracks work in `[tracker name]`, at `[where it lives]`, reached by
+`[how to reach it]`.
+
+The repository is canonical. This tracker is a **one-way projection** of work
+that already exists in `context/features/`. Never read status back out of the
+tracker and into a spec. If the two disagree, the repository is right and the
+tracker is stale.
+
+<!-- pathfinder:model-start
+Everything from here to the projection boundary is the backend-neutral model. It
+is byte-identical in every configured project, whichever backend is chosen.
+Nothing between the two markers may be defined in a backend's terms; naming one
+to exclude it is correct and is not a leak.
+-->
+
+## What gets tracked
+
+Only **approved feature specs**, from `to-specs` onward. Never track debate
+notes, kickstart output, or prototypes. The one exception is a prototype that
+gates a decision, which may be tracked as a single item phrased as the decision
+it resolves, never as a deliverable.
+
+## The work item
+
+Every tracked thing is a **work item**. A work item has:
+
+- a **key** — stable, assigned by Pathfinder, never by the tracker
+- a **kind** — what sort of thing it is
+- a **title** and a **body**
+- zero or more **blocked-by** edges, naming other work items by key
+- zero or more **tags**
+- an ordered list of **chunks** (features only)
+- a **parent** key (tickets only)
+
+### Keys
+
+A key looks like `pathfinder:<kind>/<id>`. For a feature spec, the id is the
+spec's number: `context/features/06-docs-site-scaffold.md` is
+`pathfinder:feature/06`.
+
+Keys are how a work item is recognised on a later run. Record the key inside the
+published item so it can be found again without keeping a local index. Put it in
+a marker block that the tracker will not render to a human:
+
+```text
+<!-- pathfinder:work-item
+key: pathfinder:feature/06
+kind: feature
+blocked-by: pathfinder:feature/03
+tags: area:site, type:infra, agent:suitable
+chunks-projection: checklist
+-->
+```
+
+Match on the key alone. Never match on the title — titles are edited by humans
+and a title match will create duplicates or overwrite the wrong item.
+
+**The title is written once, when the item is created, and is never reconciled
+afterwards.** It is human-owned from that point on. This is a decision, not an
+oversight, and it follows from the rule above: humans edit titles, so a
+projection that rewrote them would overwrite that edit on every run. Renaming
+the spec changes the pointer to it in the body, not the title.
+
+**Prose alone is not sufficient for identity.** This marker is the one
+machine-stable token in an otherwise prose contract. Everything else here can be
+reworded; this cannot be removed on the grounds that the config is "just prose".
+Without it there is no way to recognise an item on a second run, and publishing
+stops being idempotent.
+
+### Kinds
+
+Two kinds are defined.
+
+- `feature` — one approved feature spec. One branch, one review, one merge.
+- `ticket` — an independently assignable unit of execution inside a feature,
+  carrying its own blocked-by edges so that more than one agent can work a
+  feature at once. A ticket names its feature with `parent`.
+
+**A ticket is not a delivery chunk.** Chunks are a planning device inside a spec;
+tickets are units of execution. They may coincide, and they routinely will not: a
+ticket may span several chunks, and a ticket may exist that belongs to no chunk
+at all — a prefactor, or a decision that gates the rest. Nothing in this model
+derives one from the other, and a projection that assumed `ticket == chunk` would
+be wrong rather than simplified.
+
+**Do not treat a chunk as permanently equal to a checkbox either.** Chunk
+rendering is a *projection choice* named by `chunks-projection`, not a fact about
+the model.
+
+Feature and ticket are the **same work item**. They carry the same fields, the
+same marker, the same edge semantics, the same tag model, and the same
+idempotency rule. `chunks` is simply absent on a ticket, and `parent` is absent on
+a feature — optional fields, not different shapes. **No rule anywhere may branch
+on `kind`.**
+
+### Parent
+
+A ticket names the feature it belongs to with `parent`, a key. Parentage is
+**not** a blocking edge and must never be rendered as one: a ticket is not
+blocked by its feature. Rendering parentage as a blocker produces a graph that
+never unblocks.
+
+### Blocked-by edges
+
+Edges name **keys**, never tracker issue numbers. Resolving a key to an issue
+number is the projection's job, and the same edge must survive being pointed at a
+different tracker.
+
+An edge may name a work item that is **not in the set being published**. That is
+normal — a feature can depend on one that was tracked earlier or not at all. Do
+not drop such an edge and do not invent an item for it. Resolve it against the
+tracker as a whole rather than against this run:
+
+- if the key already has an item in the tracker, render that item's identifier,
+  exactly as an in-set edge is rendered;
+- otherwise render the key and say plainly that it has no item here.
+
+Being outside this run is not the same as being untracked, and an edge must not
+claim it is.
+
+Publish in dependency order, blockers first, so an edge can reference a real
+identifier by the time it is written.
+
+### Tags
+
+A tag is `namespace:value`. The namespace says what kind of statement the tag is
+making; the value is free text.
+
+Namespaces in use here:
+
+- `area` — the part of the system touched, e.g. `area:site`, `area:cli`
+- `type` — the nature of the work, e.g. `type:infra`, `type:content`
+- `priority` — only when the project actually uses one, e.g. `priority:now`
+- `agent` — suitability for autonomous work, e.g. `agent:suitable`,
+  `agent:needs-human`
+
+**Tags are backend-neutral.** The list above is the whole model. How a tag
+becomes a label, a field, or a line of text is a projection concern.
+
+**Respect what the tracker already has.** Before introducing any tag value,
+list the values the tracker already carries. If one already means the same
+thing, use it and record the mapping below rather than creating a
+near-duplicate. Never invent a taxonomy the team did not ask for, and never
+apply a tag that is not in the mapping table.
+
+### From spec to work item
+
+Every field above comes from the spec, and from nowhere else:
+
+- **key** — `pathfinder:feature/<NN>`, from the spec's number.
+- **kind** — `feature` for an approved feature spec.
+- **title** — the spec's own title.
+- **blocked-by** — the specs named under `## Dependencies`, each converted to
+  its key. A dependency that is not a feature spec — a decision, an external
+  system, `None` — produces no edge.
+- **chunks** — the entries under `## Delivery Chunks`, in spec order.
+- **tags** — **only** the values written in the spec's optional `## Tags`
+  section.
+
+**Tags are never inferred.** Not from the title, not from the paths a spec
+mentions, not from which part of the system it appears to touch. A spec with no
+`## Tags` section has no tags, and an item published with none is correct and
+expected — most projects never use them. Guessing a tag produces a taxonomy the
+team did not choose, applied to work they did not classify, and it will look
+authoritative on the board.
+
+If a spec names a tag that this config's mapping table does not carry, **stop and
+ask**. Do not apply it, and do not quietly drop it.
+
+### Body composition
+
+The body is a **pure function of the spec**. The same spec must produce the same
+body on every run. This is not tidiness: re-publishing decides what to do by
+comparing the body it would write now against the one already there, so a body
+that varies between runs rewrites every item forever while appearing to work.
+
+Compose it in this order, and **omit any section whose source is absent** rather
+than emitting it empty:
+
+1. a pointer to the spec this item projects
+2. the blocked-by edges
+3. the parent, on a ticket
+4. the delivery chunks
+5. the statement that the repository is canonical and that nothing here is read
+   back
+6. the marker block, last
+
+**Never include anything derived from the run rather than the spec** — no date,
+no timestamp, no run counter, no tally of what changed, no note of who published
+it. Each of those differs on the next run and each would make every item look
+modified. Never re-wrap or re-summarise text taken from the spec: copy it the
+same way every time, or the same spec produces two different bodies.
+
+How each of these elements *renders* is a projection concern. The order, the
+omission rule, and the absence of run-derived content are not.
+
+<!-- pathfinder:projection-boundary
+This marker closes the neutral model opened by `pathfinder:model-start`.
+Everything below is one projection. Keep exactly one of the two blocks that
+follow, and delete this marker, the model-start marker, and the block you did
+not keep.
+-->
+
+## Projection to GitHub
+
+*Keep this block for a GitHub Issues tracker; delete the local-files block below.*
+
+- One work item → one issue.
+- Title → the spec's title, prefixed with its number: `06 — Docs Site Scaffold`.
+- The **spec pointer** → the first line of the body, naming the spec's path.
+- The **repository-is-canonical statement** → a line near the end of the body,
+  before the marker, saying that nothing here is read back and that a ticked box
+  advances no state.
+- The marker block goes at the **end** of the issue body.
+- `blocked-by` → a `**Blocked by**` line naming each blocker as
+  `#<number> (<key>)`. A key with no issue in this repository renders as
+  `<key> — not tracked here`; a key that has one renders as `#<number> (<key>)`
+  whether or not it is part of the current run.
+- `parent` → a `**Parent**` line naming the feature as `#<number> (<key>)`.
+  Never render parentage as a blocking edge.
+- `chunks` under `chunks-projection: checklist` → a `## Delivery chunks` section
+  of `- [ ]` items in spec order. **A checked box means nothing to Pathfinder.**
+  The repository is canonical; a human ticking a box does not advance any state
+  and must never be read back.
+- Tags → labels, via this mapping. Create a label only if nothing equivalent
+  exists. Replace the rows below with this project's own tags and the labels the
+  repository already carries.
+
+  | Tag | GitHub label | Colour |
+  |---|---|---|
+  | `area:site` | `area:site` | `1d76db` |
+  | `area:cli` | `area:cli` | `1d76db` |
+  | `type:infra` | `type:infra` | `5319e7` |
+  | `type:content` | `documentation` *(pre-existing — reused, not duplicated)* | `0075ca` |
+  | `agent:suitable` | `agent:suitable` | `0e8a16` |
+  | `agent:needs-human` | `agent:needs-human` | `d93f0b` |
+
+### Publishing, and re-publishing
+
+**Ask the human before the first write to this tracker in a session.** Creating
+issues on a shared repository is outward-facing and is not covered by ordinary
+file-edit approval.
+
+Publishing is **idempotent**. Re-running must be safe and must be provably inert
+when nothing changed:
+
+1. Read every existing issue in the repository, open and closed, and index them
+   by the key in their marker block.
+2. For each work item, if no issue carries its key, create one.
+3. If an issue carries its key, compare the rendered body and the label set to
+   what would be published now. **If they are identical, do nothing at all** —
+   no edit, no comment, no label call. An unchanged item must produce zero
+   writes, not a write that happens to be a no-op.
+
+   **Compare normalized, never raw bytes.** A tracker is not obliged to hand a
+   body back exactly as it was sent, and APIs differ in whether they adjust
+   trailing whitespace. Where that happens, a naive byte comparison reports every
+   issue as changed on every run and rewrites all of them forever — which looks
+   like working sync and is not. Before comparing, strip trailing whitespace from
+   each line and collapse trailing blank lines at end of body, on **both** sides.
+   This costs nothing when the round-trip is exact, and is the difference between
+   inert and catastrophic when it is not. Compare label sets as sets, not as
+   ordered lists — the tracker does not preserve the order they were applied.
+4. If they differ, edit that issue in place. Never close and recreate.
+5. Never close an issue, never reopen one, and never touch an issue whose key is
+   absent from the current set — it belongs to work outside this run.
+
+Report what was created, what was edited, and what was left alone.
+
+## Projection to local files
+
+*Keep this block for a local Markdown tracker; delete the GitHub block above.*
+
+- One work item → one file, `.work/<NN>-<slug>.md`. On first publish the files
+  are numbered from `01` in dependency order, so blockers sort first.
+
+  **`<NN>` is presentation and ordering only. It is never identity** — a file is
+  recognised by the key inside it, and nothing may match on the prefix.
+
+  A new file takes the **next unused prefix**, not the position it would occupy
+  in dependency order. Existing files are **never renumbered**: renaming a file
+  is deleting one and creating another, and re-publishing must never do that —
+  it would rewrite unrelated files every time a blocker was inserted. So after a
+  dependency change the prefixes no longer sort into dependency order, and that
+  is expected. Read the current order from the `**Blocked by**` lines, which are
+  reconciled. The prefixes are not.
+- Title → an `# ` heading, prefixed with its number: `06 — Docs Site Scaffold`.
+- The **spec pointer** → the first line of the body, naming the spec's path.
+- The **repository-is-canonical statement** → a line near the end of the file,
+  before the marker, saying that nothing here is read back and that a ticked box
+  advances no state.
+- The marker block goes at the **end** of the file.
+- `blocked-by` → a `**Blocked by**` line naming each blocker as
+  `<file> (<key>)`. A key with no file under `.work/` renders as
+  `<key> — not tracked here`; a key that has one renders as `<file> (<key>)`
+  whether or not it is part of the current run.
+- `parent` → a `**Parent**` line naming the feature as `<file> (<key>)`.
+  Never render parentage as a blocking edge.
+- `chunks` under `chunks-projection: checklist` → a `## Delivery chunks` section
+  of `- [ ]` items in spec order. **A checked box means nothing to Pathfinder.**
+  The repository is canonical; a human ticking a box does not advance any state
+  and must never be read back.
+- Tags → a `**Tags**` line listing them verbatim, comma-separated, in the order
+  given. There is no label object to create, so the mapping is the identity
+  mapping and no colour applies. Replace the rows below with this project's own
+  tags.
+
+  | Tag | Local rendering |
+  |---|---|
+  | `area:site` | `area:site` |
+  | `area:cli` | `area:cli` |
+  | `type:infra` | `type:infra` |
+  | `type:content` | `type:content` |
+  | `agent:suitable` | `agent:suitable` |
+  | `agent:needs-human` | `agent:needs-human` |
+
+### Publishing, and re-publishing
+
+No approval is required to write under `.work/` — it is an ordinary file edit in
+this repository and reaches nothing outside it.
+
+Publishing is **idempotent**. Re-running must be safe and must be provably inert
+when nothing changed:
+
+1. Read every existing file under `.work/` and index them by the key in their
+   marker block.
+2. For each work item, if no file carries its key, create one.
+3. If a file carries its key, compare its full contents to what would be written
+   now. **If they are identical, do nothing at all** — do not rewrite the file
+   with the same bytes. An unchanged item must leave its mtime untouched.
+4. If they differ, rewrite that file in place. Never delete and recreate.
+5. Never delete a file, and never touch a file whose key is absent from the
+   current set — it belongs to work outside this run.
+
+Report what was created, what was edited, and what was left alone.