@skitterbyte/skitterspec-azure-boards 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @skitterbyte/skitterspec-azure-boards
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Spec-driven development for Claude Code, with **one-way Azure Boards sync** — a
+superset of [`@skitterbyte/skitterspec`](https://www.npmjs.com/package/@skitterbyte/skitterspec):
+the base filesystem workflow plus `/spec-push` · `/spec-status` · `/spec-claim`
+and the `spec-sync` CLI. The repo is canonical; Azure Boards is a generated
+mirror.
+
+Install exactly one distribution — this, the base, or one other superset —
+never two:
+
+```
+npx @skitterbyte/skitterspec-azure-boards init
+```
+
+## What the sync is
+
+- A spec is a **work item**; each phase a **child work item** under a
+  parent/child link; tasks ride along as a markdown checklist in the body
+  (still a read-only mirror — the repo wins on every push).
+- **Descriptions are markdown**, written verbatim with the format declared on
+  the field — checkboxes render natively, and a read-back is byte-comparable.
+- **Work item types and states are the project's own.** The process template
+  (Basic, Agile, custom) decides them, so the config names the types and the
+  bucket→state map, validated against the process at run time.
+- **One-way**: nothing is read back into the repo. A body edited in Boards is
+  reported and replaced on the next push, loudly.
+- **Releases**: CI runs `spec-sync release create <tag>` on a tag push. It
+  mints one work item of `releases.workItemType` per release, holding exactly
+  the tickets that tag contains by their `Refs: AB#n` trailers;
+  `release deployed <tag> <env>` moves that item's state through your envs.
+- **Assignment**: `/spec-start` assigns the work item to you; `/spec-claim`
+  hands it on. Identity derives from the PAT (`spec-sync whoami`).
+- **Intake**: adopt a PM-filed work item as a spec's own, routed to `/spec`,
+  `/spec-bug` or `/spec-hotfix` by its tags, the original description preserved
+  as a comment before the spec replaces it.
+
+## Setup
+
+You need a PAT with **Work Items (Read & Write)** — add **Identity (Read)** for
+user search. `/spec-azure-setup` interviews you and writes
+`specs/.core/azure-boards.config.json` (org URL, project, types, bucket→state
+map). Keep the token out of the repo — export `AZURE_DEVOPS_EXT_PAT`, or:
+
+```
+skitterspec-azure-boards spec-sync credentials set
+```
+
+`skitterspec-azure-boards spec-sync doctor --check-remote` reports readiness
+across every layer, the identity scope included.
+
+Not yet shipped for Azure Boards: `retarget`, `reattach`, `stage`,
+`spec-sanitise`.
+
+This package's `bin/`, `src/` and `assets/` are composed at build time from the
+skitterspec monorepo — see the repo for sources and development.

package/assets/claude-md-section.md

@@ -0,0 +1,85 @@
+## Spec workflow
+
+Spec-driven development runs through the lifecycle **skills** — use them so
+structure and lifecycle stay consistent. The everyday loop is
+**`spec → start → next → commit → complete`**, with **`/spec-diff`** to read what
+a phase changed and `/spec-connect` when you want to test the spec in a browser.
+
+**Skills vs commands.** The lifecycle skills are read by Claude, which exercises
+judgment. `/spec-connect` and `/spec-live` are **slash commands** instead — each
+pre-executes one `spec-env` verb and relays it, so only you can run them; a
+skill that wants one will tell you to type it.
+
+**Seeing the work.** A phase is built in its own worktree, so `git diff` in your
+terminal answers about the base branch. **`/spec-diff`** renders that worktree's
+diff as a self-contained HTML page you open locally — or publish, and read on a
+phone. The diff never passes through the model, so the page costs no context
+tokens however large it is; the optional written review is the part that costs,
+and it is offered rather than assumed. `/spec-next` writes the page at the end of
+every phase.
+
+**Handing the review back.** The page takes marks: tick `✓ accept` per file as
+you read, note anything against a line or a whole file, answer the questions a
+written review asked — then **end it in a decision**. At the end of a phase the
+buttons are `✓ Commit`, `✓ Commit & Continue` (commit, then build the next
+phase), `↺ Request changes` and `… Discuss first`. A spec that has just been
+written gets `✓ Commit & Start` instead — the `commit-start` verdict, which is
+the `commit && /spec-start` you would otherwise type. A **served** page hands
+the pass to the engine, which **holds** it and shows a six-digit code. Committing
+is unavailable while a note is open — you asked for something, so it cannot also
+be fine — and it hands off to your own commit skill (`review.commitWith`,
+`/commit` by default) rather than a copy living here. Fixes come back as
+resolutions, so the next render shows each note struck through with what changed.
+An accept remembers the file's content, so it lapses by itself when that file
+changes again. The marks are information — nothing gates on them; the verdict is
+the one thing you choose, once.
+
+**A second opinion, when you want one** (`review.reviewers`, empty by default).
+Point it at a code reviewer that runs from your terminal — CodeRabbit's CLI has
+a free tier and `{ "use": "coderabbit" }` is the whole setup; anything printing
+[rdjsonl](https://github.com/reviewdog/reviewdog) works too — and its findings
+land on the page beside your own notes, each badged with the tool that found it
+and linked to the line it is about. `/spec-next` runs them once per phase;
+`/spec-diff --reviewers` is the mid-phase ask. **They never block a commit** —
+reply to one and your reply does, because then a person has asked for something.
+A reviewer that could not run says `did not run — <why>` rather than passing as
+clean, because on the page you commit from those two must not look alike.
+Adding one sends your diff to whatever the command talks to, which is why the
+list starts empty and `init` never writes one.
+
+**Above the verdicts sits one line that is not a verdict.** `▶ Put it live`
+commits the phase, checks the branch out where your dev server can see it, and
+hands you back the same page with the same options — so you can judge the change
+by *using* it, not only by reading it. It clears no gate: you have looked at it
+running and concluded nothing, so the phase still owes an answer.
+
+**Every render lists where the page can be read**, labelled, in a fixed order —
+`local`, `network`, `remote` — each either a URL or the one command that turns it
+on, plus a `live:` line saying whether the change is also running. `local` and
+`network` are two doors into one room: the same server and the same waiting
+verdict, so one wait covers both. `remote` is a published page, a second store —
+a verdict there needs `/spec-reviewed`, and it stays off until someone types
+**`/spec-remote-review`**, which toggles it. Publishing is permitted by that
+command, never performed by it: a published page is one this tooling cannot
+remove.
+
+**One ending.** Every spec skill finishes with the same block — a verdict
+(`✅` · `⚠️` · `❌` · `⏸`), then a table of the fields that skill declares,
+ending on the one thing to do next. A refusal emits it too, so "nothing
+happened" is reported rather than absent, and `Follow-ups` is always there
+because a recorded `none` is a decision. Skills stay quiet while they run. The
+shape lives in **`.claude/rules/spec-reports.md`**.
+
+The skill table, the spec type/folder conventions and the per-spec isolation
+model all live in **`.claude/rules/spec-planning.md`**, the canonical reference
+every spec skill points at. Tailor its per-phase test commands to this stack.
+
+**Release gating** *(only when `specs/.core/gating.config.json` exists)* — each
+spec records whether it ships behind a feature flag, as
+`> **Gating:** <flag name>` or `> **Gating:** none: <one-line reason>`. `/spec`,
+`/spec-bug` and `/spec-hotfix` ask; `/spec-review`, `/spec-start` and
+`/spec-complete` report a spec that has no answer, and never block over it.
+`skitterspec gating check` lists them and always exits 0. The point is that the
+question is **on the record**: a missing line is an oversight, a reason is a
+decision. Skitterspec never reads your flag system — it asks and cites the doc
+you point it at. Without that config, none of this appears.

package/assets/commands/allow-main.md

@@ -0,0 +1,33 @@
+---
+description: Allow writes on the base branch for this session — bare allows it with no reason, a reason records why, `off` clears it
+argument-hint: "[<reason> | off]"
+allowed-tools: Bash({{exec}} skitterspec spec-env main allow:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env main allow $ARGUMENTS`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+**Only you can run this, and that is the whole guard.** The main-guard hook
+refuses an `Edit` or a `Write` in the primary checkout while it sits on the base
+branch, and it names two exits: move the work with `/no-spec` or `/spec-start`,
+or have you lift the guard. Claude can take the first exit on its own and can
+never take the second — a guard the model can lift is decoration, which is the
+same line `/spec-reviewed` draws.
+
+**Give it a reason.** `/allow-main fixing the lockfile by hand` records why; bare
+records `none given`. The reason is the part a reviewer can argue with, exactly
+as with a `Gating:` header — and it is what you will read when you wonder later
+why the base branch has an uncommitted file on it.
+
+**It lapses with the session where it can.** The allow is recorded against this
+session, so it ends when the session does. Where the harness exposes no session
+id it degrades to a repo-wide allow that outlives the session and is cleared only
+by `/allow-main off`; the engine says which kind you got, so do not read a bare
+"allowed" as temporary.
+
+**It is machine-local and gitignored.** Unlike `/spec-remote-review`, this writes
+nothing anyone else pulls: it is your decision about your checkout, not the
+project's policy. The project-wide switch is `guards.mainIsLandingZone` in
+`specs/.core/env.config.json`, and turning that off is a different, committed
+decision.

package/assets/commands/spec-connect.md

@@ -0,0 +1,13 @@
+---
+description: Expose one spec's dev servers on the canonical localhost ports — bare uses the spec you are on, `main` hands them back
+argument-hint: "[<spec> | main]"
+allowed-tools: Bash({{exec}} skitterspec spec-env connect:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env connect $ARGUMENTS`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+Only if it reports a **canonical port is in use**: say that the main checkout's
+dev server still holds that port, and that stopping it and re-running is the fix
+(the proxy cannot share a port main is bound to).

package/assets/commands/spec-live.md

@@ -0,0 +1,14 @@
+---
+description: Put one spec live on the already-running dev server — bare takes the spec you are on, `<spec>` takes that one, `main` hands the instance back
+argument-hint: "[<spec> | main | status | release | abort]"
+allowed-tools: Bash({{exec}} skitterspec spec-env live:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env live $ARGUMENTS`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+The engine enforces every refusal itself and prints why — a hotfix, a stateful
+spec (`Stack: worktree + docker`), a branch touching migrations, a dirty tree, a
+rebase conflict, or another spec already holding the instance. Do not re-explain
+or work around any of them.

package/assets/commands/spec-remote-review.md

@@ -0,0 +1,37 @@
+---
+description: Permit or forbid publishing this spec's review for a reader off your network — bare toggles it, `on`/`off` set it explicitly
+argument-hint: "[on | off]"
+allowed-tools: Bash({{exec}} skitterspec spec-env review allow remote:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env review allow remote --set "$ARGUMENTS"`
+
+Relay the engine output above verbatim. Add nothing to it.
+
+**Then one thing, and only when the engine asked for it.** Where the output
+carries a `review:` and a `publish:` line, typing this command **is** the ask
+to publish that page: the banner named this command beside a review the reader
+could not reach, so the link is what they are waiting for. Publish it exactly
+as `/spec-diff` §6 describes (run the `publish:` command, publish the copy it
+names with a store, write the URL file), then re-emit the review banner with
+all three tiers, `remote` now carrying the URL. A wait already running keeps
+running; do not restart it or the server. If the harness refuses the publish,
+say so in one line and keep the banner as it was, because local and network
+still work.
+
+With no `publish:` line, run nothing else. Nothing has a page to publish, or
+the tier was turned off.
+
+**Bare toggles.** That is the common case: you are looking at a render whose
+`remote:` line says which way it currently is, and what you want is the other
+one. `on` and `off` are there for when you are not looking at it.
+
+**It is per spec.** The engine resolves the spec from the worktree you are
+standing in and records the permission in the gitignored review store, so
+the base branch is untouched and no other spec may publish because of it.
+`skitterspec spec-env review allow remote --project` is the committed,
+every-spec form, for a team that wants it.
+
+**A published page is one skitterspec cannot delete**, and a verdict pressed
+on one needs `/spec-reviewed`, because nothing pushes from an artifact's store
+into a conversation.

package/assets/commands/spec-skip.md

@@ -0,0 +1,24 @@
+---
+description: Move on from a phase without a verdict, with the reason on the record — clears the review gate
+argument-hint: "\"<reason>\""
+allowed-tools: Bash({{exec}} skitterspec spec-env review skip:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env review skip "$ARGUMENTS"`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+**It refuses with no reason, and that refusal is the feature.** A skip with no
+reason is indistinguishable from nobody having looked — where
+`none: additive, nothing to revert` is a decision a reviewer can argue with. If
+the engine asked for a reason, relay that and stop; do not supply one on the
+operator's behalf.
+
+**It is one of exactly two exits**, and the other is a committing verdict on the
+page. Nothing else discharges a phase's obligation — not a mid-run `Continue`,
+not an action, not a render.
+
+**Only you can run it.** Like `/allow-main`, this lifts a guard aimed at Claude,
+so Claude must not be able to lift it. `/spec-connect` and `/spec-live` are
+user-only for the milder reason that there is no judgement to apply; this one is
+user-only because of who the guard is for.

package/assets/core/SETUP.md

@@ -0,0 +1,214 @@
+# Setting up Azure Boards sync (one-way)
+
+A start-to-finish guide to getting `/spec-status` and `/spec-push` working
+against a real Azure DevOps organization. Sync is **one-way**: the repo is the
+source of truth and the linked **work item** is a **generated mirror** —
+content is pushed up, never read back or merged. A spec is a work item and each
+phase a **child work item**, with the phase's tasks mirrored into that child's
+description as a markdown checklist (read-only — the repo wins). Covers the
+**Azure side** (credentials, finding your project) that the config reference
+(`azure-boards.config.md`) assumes you already have.
+
+> The whole feature is **opt-in**: until `specs/.core/azure-boards.config.json`
+> exists, everything below is inert and the package behaves exactly like the
+> base `@skitterbyte/skitterspec`.
+
+Two things about Azure Boards shape everything below:
+
+- **Descriptions are MARKDOWN**, written verbatim with the format declared
+  beside the field (`multilineFieldsFormat`) — so a read-back is normally the
+  pushed text byte for byte, and task checkboxes render natively. A field saved
+  as markdown cannot revert to HTML (Azure's rule; fine one-way). Items that
+  predate the link read back as HTML and are reduced to text for comparison.
+- **States are written directly** — there is no transition API — and a process
+  rule refuses an unknown name only **at write time**, after the description
+  has landed. The engine therefore validates every configured state up front
+  and refuses loudly (naming what the types DO have) before anything writes.
+
+---
+
+## 1. Install the package
+
+Install the Azure Boards superset (or, if you already run the base or another
+superset, switch — every distribution contains the entire base, so install
+exactly one):
+
+```sh
+npx @skitterbyte/skitterspec-azure-boards init
+```
+
+## 2. Credentials — a Personal Access Token
+
+Azure DevOps authenticates REST calls with basic auth: an empty username and a
+PAT as the password. Create the token in Azure DevOps under User settings →
+Personal access tokens, scoped **Work Items (Read & Write)** — add
+**Identity (Read)** if you want user search later (work item sync is whole
+without it).
+
+Store it in the user-level credentials store (outside every repo, `0600`),
+**in your own terminal — not through an assistant**:
+
+```sh
+pnpm exec skitterspec-azure-boards spec-sync credentials set --org-url https://dev.azure.com/<org>
+# Azure DevOps PAT for https://dev.azure.com/<org> (hidden): ●●●●●●●●
+```
+
+(`--org-url` keys the store entry before the repo has a config; once
+`azure-boards.config.json` exists it can be omitted.)
+
+Or export `AZURE_DEVOPS_EXT_PAT` — the official CLI's variable, so a machine
+set up for `az boards` needs nothing new. The environment wins over the store.
+
+> **MCP alternative:** with no credentials at all, the sync skills fall back to
+> Microsoft's official MCP server — remote at `https://mcp.dev.azure.com/{org}`,
+> or local via `@azure-devops/mcp` — authenticated with your Microsoft account.
+> The engine itself never calls MCP tools; the skills fetch and hand results to
+> the engine as files (`--workspace-states`, `--stored`, `--text`).
+
+## 3. Configure — run `/spec-azure-setup`
+
+With credentials in place, let the skill interview you:
+
+```
+/spec-azure-setup
+```
+
+It asks for the org URL, the project, the work item type names, and the four
+bucket→state names — validating them against the types' real states
+(`spec-sync states`) — then writes `specs/.core/azure-boards.config.json` via
+`spec-sync init-config`. By hand instead:
+
+```sh
+pnpm exec skitterspec-azure-boards spec-sync init-config \
+  --org-url https://dev.azure.com/<org> \
+  --project <project> \
+  --state complete=Done
+```
+
+**Commit the file it writes.** Spec worktrees fork from commits, so an
+uncommitted `azure-boards.config.json` is invisible inside every worktree —
+which is where the sync skills actually run — and sync reports itself off
+there.
+
+`azure-boards.config.md` (installed beside this file) is the full field
+reference. Two defaults worth knowing: the types are the **Basic** process's
+(`Issue`/`Task`) — an Agile project usually wants `User Story`/`Task`; and
+`cancelled` maps to `Done` because the Basic process carries no Cancelled
+state (Agile's `Removed` is an honest override).
+
+**Map buckets to work states, not deployment stages.** The buckets mirror the
+repo's work lifecycle, so To Do / Doing / Done translate honestly — On Test /
+On Live do not: a finished phase would show as deployed before anything was
+released. Deployment position belongs to the release carrier
+(`releases.series[].envs`, moving the release work item) —
+`azure-boards.config.md` → **Choosing your state map** carries the reasoning.
+
+## 4. Check — `spec-sync doctor`
+
+```sh
+pnpm exec skitterspec-azure-boards spec-sync doctor --check-remote
+```
+
+Every row reports `ok`, or names the exact command that fixes it. `missing`
+is an opt-in not taken (fine); `broken` is configured-but-wrong (exit 1).
+`--check-remote` additionally proves the PAT reaches the org, that every
+configured state exists on the types, and whether the PAT can search
+identities (a warn, never broken — only user search degrades without it).
+
+## 5. Push a spec
+
+`/spec-push <spec>` computes the plan, applies it, stamps the returned ids
+into the spec's frontmatter (`azure_identifier` / `azure_url` /
+`azure_item_id`), verifies the round-trip by words, and records the snapshot
+later drift is measured against. From then on the lifecycle skills keep the
+mirror fresh on their own.
+
+---
+
+## Release smoke checklist
+
+Re-runnable, against a real Azure DevOps org — a throwaway org/project is
+ideal (the free tier covers all of it). Run before cutting a release that
+touches the adapter, the dialect or the apply path. `states.json` below is the
+types' state names.
+
+1. **Doctor** — every row ok:
+
+   ```sh
+   pnpm exec skitterspec-azure-boards spec-sync doctor --check-remote
+   ```
+
+2. **States** — the types' state list:
+
+   ```sh
+   pnpm exec skitterspec-azure-boards spec-sync states --json > states.json
+   ```
+
+3. **Mint** — on a test spec with at least one phase and a task checklist:
+
+   ```sh
+   pnpm exec skitterspec-azure-boards spec-sync plan <spec> --workspace-states states.json --json > plan.json
+   pnpm exec skitterspec-azure-boards spec-sync apply <spec> --plan plan.json
+   ```
+
+   In Boards: the work item and its children exist, states match the buckets,
+   and the task checklist renders as markdown checkboxes.
+
+4. **Update** — edit the spec's prose and a phase's status, then plan + apply
+   again: the description is replaced and the child's state moves.
+
+5. **Adopt + preserve** — hand-create a work item with a description (in the
+   Boards UI, so it is HTML-era), stamp it onto a spec, and preserve before the
+   linking push:
+
+   ```sh
+   pnpm exec skitterspec-azure-boards spec-sync stamp <spec> --issue AB#123
+   pnpm exec skitterspec-azure-boards spec-sync preserve <spec>
+   ```
+
+   The original description appears as a comment headed **Original report**
+   (reduced to text from its HTML); a second `preserve` reports "already
+   preserved".
+
+6. **Verify** — save a read-back (`{ "issue": "<description text>",
+   "subIssues": { "<ref>": "<text>" } }`; a ref is the phase file's basename
+   without `.md`, e.g. `01-date-logic` — keyed with the extension it reports
+   every child as a stale ref) and:
+
+   ```sh
+   pnpm exec skitterspec-azure-boards spec-sync verify <spec> --stored readback.json
+   ```
+
+   "round-tripped intact", exit 0.
+
+7. **Released** — over a range with `Refs:` trailers:
+
+   ```sh
+   pnpm exec skitterspec-azure-boards spec-sync released <tag>..HEAD
+   ```
+
+   Tickets counted, unreferenced commits reported, an earlier tracker's
+   trailers counted as historical, bookkeeping ignored.
+
+8. **Release carrier** — with a `releases.series` configured and a tag pushed:
+
+   ```sh
+   pnpm exec skitterspec-azure-boards spec-sync release create <tag>
+   pnpm exec skitterspec-azure-boards spec-sync release create <tag> --apply
+   pnpm exec skitterspec-azure-boards spec-sync release deployed <tag> staged --apply
+   pnpm exec skitterspec-azure-boards spec-sync release complete <tag> --apply
+   ```
+
+   In Boards: one `releases.workItemType` item titled by the tag, the range's
+   tickets Related-linked with one comment each, the item's state moving
+   through the envs and closing on complete. A retry of `create --apply`
+   reports "unchanged", never a duplicate.
+
+9. **Drift** — edit the item's description **in Boards**, fetch the item JSON,
+   and:
+
+   ```sh
+   pnpm exec skitterspec-azure-boards spec-sync status <spec> --remote item.json
+   ```
+
+   The edit is reported; the next apply replaces it and says so loudly.

package/assets/core/azure-boards.config.json.example

@@ -0,0 +1,35 @@
+{
+  "azure": {
+    "orgUrl": "https://dev.azure.com/your-org",
+    "project": "your-project",
+    "workItemType": "Issue",
+    "childType": "Task",
+    "areaPath": ""
+  },
+  "states": {
+    "backlog": "To Do",
+    "in-progress": "Doing",
+    "complete": "Done",
+    "cancelled": "Done"
+  },
+  "intake": {
+    "tag": "",
+    "bugTags": ["bug"],
+    "hotfixTags": []
+  },
+  "auth": {
+    "tokenEnv": "AZURE_DEVOPS_EXT_PAT"
+  },
+  "refs": {
+    "foreignPatterns": []
+  },
+  "releases": {
+    "workItemType": "Release",
+    "series": [
+      {
+        "tagPrefix": "v",
+        "envs": { "staged": "Staged", "published": "Published" }
+      }
+    ]
+  }
+}

package/assets/core/azure-boards.config.md

@@ -0,0 +1,43 @@
+# `azure-boards.config.json` — field reference
+
+The committed, shareable half of Azure Boards sync. It holds ids, names and
+env-var NAMES — never a credential. Credentials live in the user-level store
+(`skitterspec-azure-boards spec-sync credentials set`) or the environment.
+
+| Key | Meaning | Default |
+|-----|---------|---------|
+| `azure.orgUrl` | The organization (`https://dev.azure.com/<org>`). Also keys the credentials-store entry. | `""` |
+| `azure.project` | The project spec work items land in. | `""` |
+| `azure.workItemType` | The work item type a spec mints as. Types are process-defined (Basic: `Issue`; Agile: `User Story`; custom anything), so this is config, not a constant. | `"Issue"` |
+| `azure.childType` | The type a phase mints as, linked parent/child under the spec's item. | `"Task"` |
+| `azure.areaPath` | Optional area path for minted items; empty means the project default. | `""` |
+| `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → work item, phase → child item, tasks → markdown checklist. Same modes as the other providers (`subissue` \| `deferred` \| `inline`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
+| `states.<bucket>` | The Boards STATE name for each lifecycle bucket, per the project's own process. Moves are direct `System.State` writes; a state the process refuses is a named refusal listing the states the type has. `cancelled` defaults to `Done` because the Basic process carries no Cancelled state. | see example |
+| `intake.tag` / `intake.bugTags` / `intake.hotfixTags` | Intake routes an adopted work item by its tags (Boards has tags, not labels): the inbox filter, and the routes to `/spec-bug` and `/spec-hotfix`. Empty lists route nothing. | `""` / `["bug"]` / `[]` |
+| `auth.tokenEnv` | The env-var NAME for the PAT — the official CLI's by default, so a machine set up for `az boards` needs nothing new. Work Items (Read & Write) covers everything but identity search, which wants Identity (Read). | `AZURE_DEVOPS_EXT_PAT` |
+| `refs.foreignPatterns` | Ref shapes that are KNOWN HISTORY rather than unreferenced commits — a repo migrating off another tracker lists its old key here (e.g. `"ERQ-\\d+"`). | `[]` |
+| `releases.workItemType` / `releases.series` | The release seam's carrier: one work item of this type per release, found by title, its state moved through each series' `envs` map by `release deployed`. | `"Release"` / `[]` |
+| `apply.transport` | `api` \| `mcp`, or empty for "api when credentials resolve, mcp when they don't". | `""` |
+| `sync.baseDir` | Where last-pushed snapshots live. | `specs/.core/azure-base` |
+| `sync.fieldOwnership` | Which projection fields push (`description`, `subIssues`, `workflowState`, `assignee`; `"none"` declines one). | all `push` |
+| `release.stages` / `release.ignorePaths` | The deployment ladder and bookkeeping path prefixes, exactly as the other providers define them. | `[]` / `specs/`, changelogs |
+
+Descriptions are stored as MARKDOWN: the adapter writes the projection's
+markdown verbatim and declares the format beside the field
+(`multilineFieldsFormat`), so a read-back is byte-comparable and task
+checkboxes render natively. A field saved as markdown cannot revert to HTML —
+Azure's rule, and fine one-way: this provider never writes HTML. Work items
+that predate the link (every intake-adopted item) come back as HTML and are
+reduced to text for comparison and preservation, never written back.
+
+A box ticked in Boards is still overwritten on the next push — the mirror is
+read-only, exactly as the other providers' are.
+
+## Choosing your state map
+
+Map the four buckets to **work** states, never to deployment stages — the
+same rule the Jira reference explains at length. The repo learns where work
+**is** as it happens, but what **shipped** only when a release is cut, so a
+pipeline state driven from the spec lifecycle is wrong the moment it moves.
+Deployment position belongs to the release seam (`releases.series[].envs`,
+moving the release work item), not to each ticket's state.

package/assets/core/env.config.json.example

@@ -0,0 +1,56 @@
+{
+  "mode": "worktree",
+  "worktree": {
+    "root": "../{repo}-wt",
+    "folderPattern": "{slug}"
+  },
+  "docker": {
+    "enabled": true,
+    "composeFile": "docker-compose.yml",
+    "projectNamePattern": "{repoSlug}_{slug}",
+    "portBase": 3000,
+    "portsPerSpec": 10,
+    "envFile": ".env",
+    "backupCommand": ""
+  },
+  "seedFiles": {
+    "mode": "symlink",
+    "files": [
+      ".env"
+    ]
+  },
+  "setup": [],
+  "dev": [],
+  "proxy": {
+    "enabled": true,
+    "host": "127.0.0.1"
+  },
+  "registry": ".spec-env/registry.json",
+  "branch": {
+    "pattern": "{type}/{slug}",
+    "identifierField": "azure_identifier"
+  },
+  "spec": {
+    "companionPaths": [
+      "specs/.core/azure-base/{identifier}.base.json"
+    ]
+  },
+  "baseBranch": "",
+  "guards": {
+    "refuseTeardownIfDirty": true,
+    "refuseTeardownIfUnpushed": true
+  },
+  "review": {
+    "reader": "detect",
+    "servePort": "auto",
+    "serve": "always",
+    "allowNetwork": true,
+    "allowRemote": false,
+    "commitWith": "/commit",
+    "required": true,
+    "reviewers": []
+  },
+  "live": {
+    "migrations": []
+  }
+}