@skitterbyte/skitterspec-linear 11.0.0 → 13.0.0

package/assets/core/env.config.md

@@ -1,18 +1,19 @@
 # `env.config.json` — per-spec isolation config
 
 Opt-in config for per-spec isolation (git worktree + optional namespaced Docker
-stack + host dev servers + a front-door proxy + an optional opener per
-in-progress spec). Provisioning is folded into `/spec-start`, teardown into
-`/spec-complete` · `/spec-cancel`, and traffic diversion is `/spec-connect`; the
-`skitterspec spec-env <up|down|prune|dev|connect|integrate>` CLI is the engine
-beneath them.
+stack + host dev servers + a front-door proxy per in-progress spec).
+Provisioning is folded into `/spec-start`, teardown into `/spec-complete` ·
+`/spec-cancel`, traffic diversion is `/spec-connect`, and reading a spec's diff
+is `/spec-diff`; the `skitterspec spec-env
+<up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` CLI is
+the engine beneath them.
 
 **Once this file is present, isolation is the default policy:** `/spec-start` gives
-**every** in-progress spec its own git worktree automatically. Docker is a **per-
-spec escalation** — a spec brings up a stack only when its `> **Stack:**` header
-is `worktree + docker` (set at `/spec` when it touches the DB / stateful
-services). A `worktree`-only spec takes no registry slot, no port block, and no
-`.env`.
+**every** in-progress spec its own git worktree automatically. Docker is a
+**per- spec escalation** — a spec brings up a stack only when its
+`> **Stack:**` header is `worktree + docker` (set at `/spec` when it touches
+the DB / stateful services). A `worktree`-only spec takes no registry slot, no
+port block, and no `.env`.
 
 **Adopt it** with `skitterspec init --isolation` (or copy
 `env.config.json.example` → `env.config.json` here) and edit the values. While
@@ -31,11 +32,12 @@ no live `env.config.json` was found.
   // Where a spec's branch gets built.
   //
   //   "worktree"  (default) — every spec gets its own git worktree. Several
-  //               specs run side by side and `main` stays free, at the cost of
-  //               one terminal session per spec (`/spec-start` sets it up for you).
+  //               specs run side by side and `main` stays free. `/spec-start`
+  //               moves your session into the spec's worktree with a `cd`, so
+  //               the terminal you are already in follows the work.
   //   "checkout"  — the branch is built in the primary checkout instead. One
-  //               spec at a time, but no second session and no hand-off: the
-  //               terminal you are already in follows the work.
+  //               spec at a time, and nowhere else to stand: the work comes to
+  //               your terminal rather than your terminal going to it.
   //
   // Pick it for how you work, not for what this repo contains — a project with
   // no dev servers may still want several specs in flight. An unrecognised
@@ -124,19 +126,6 @@ no live `env.config.json` was found.
     "host": "127.0.0.1"     // bind host for the canonical ports
   },
 
-  // Optional, editor/terminal-agnostic opener. `/spec-start` RUNS it when it hands
-  // you into a new worktree — after provisioning and bootstrap, so the session
-  // opens onto a tree that is ready to work in. The template is expanded with
-  // {worktreePath}, {slug}, {branch}, {projectName}, {portOffset}.
-  // Empty = nothing is opened (the path is just printed), which is how you turn
-  // the auto-open off. A non-interactive run skips it either way — an opened
-  // window nobody is sitting at helps no one.
-  // Examples: "code {worktreePath}", "tmux new-window -c {worktreePath}",
-  // or a "warp://..." deeplink for Warp users.
-  "open": {
-    "command": ""
-  },
-
   // Machine-local slot registry (spec → slot index). Resolved against the
   // primary checkout root, shared by all worktrees, gitignored.
   "registry": ".spec-env/registry.json",
@@ -153,6 +142,26 @@ no live `env.config.json` was found.
     "identifierField": ""
   },
 
+  // Paths that belong to a spec ALONGSIDE its own `specs/<bucket>/<name>/`
+  // folder. `/spec-start` uses this to tell "the spec you just wrote, not yet
+  // committed" apart from someone else's uncommitted work: if every dirty path
+  // belongs to the spec being started it is committed for you, and if a single
+  // path does not, the start is refused as before.
+  //
+  // Provider-neutral by design — the base engine must not know that any
+  // particular tracker exists — so you declare the shape here. `{slug}` and
+  // `{identifier}` expand exactly as in `branch.pattern` above, `{identifier}`
+  // via `branch.identifierField`.
+  //
+  // A pattern using {identifier} matches NOTHING when no identifier resolves
+  // (no `identifierField` set, or a spec never pushed to a tracker). That is
+  // deliberate: the file it names then belongs to some other spec, and the safe
+  // failure is a refusal you clear with /commit, not a stranger's file swept
+  // into your commit. Default: none — a spec owns only its own folder.
+  "spec": {
+    "companionPaths": []
+  },
+
   // Integration base branch — the branch specs fork from and land back onto
   // (used by the teardown "merged?" guard and, later, the integrate step).
   // Empty = auto-detect: origin/HEAD → main → master. Set it when your default
@@ -168,9 +177,10 @@ no live `env.config.json` was found.
     "refuseTeardownIfUnpushed": true
   },
 
-  // What teardown cleans up beyond this machine. `/spec-start` pushes the spec
-  // branch when it provisions, so without this a completed spec leaves a merged
-  // branch on the remote forever. `deleteRemoteBranch`:
+  // What teardown cleans up beyond this machine. Nothing publishes a spec
+  // branch for you, so a remote copy exists only because you pushed it by hand —
+  // and without this a completed spec leaves that merged branch on the remote
+  // forever. `deleteRemoteBranch`:
   //   "prompt"  (default) — plan `git push <remote> --delete <branch>` in its own
   //             "confirm with the user first" section; /spec-complete and
   //             /spec-cancel ask before running it.
@@ -207,6 +217,68 @@ no live `env.config.json` was found.
     "bump": "patch",
     "cherryPickMain": true,
     "targets": []
+  },
+
+  // Reading a spec's diff (`spec-env review`, `/spec-diff`).
+  //
+  // `reader` decides how the page's LOCATION IS WORDED, and — through
+  // `serveOnRemote` below — whether the engine stands its local server up so a
+  // remote reader gets a link that opens. It never decides to PUBLISH. Three
+  // values:
+  //   "local"  — you are at the machine holding the page; a file:// URL opens.
+  //   "remote" — you are not; it does not, so the page is served instead.
+  //   "detect" — work it out (the default).
+  // An explicit "local"/"remote" is BELIEVED WITHOUT SNIFFING: you know where
+  // you are reading, and no signal outranks being told. Detection is only the
+  // default, and it has three outcomes rather than two — local, remote, and
+  // unknown. Unknown behaves exactly as the tool did before any of this existed
+  // (the file:// URL, no warning), because a wrong "local" prints a dead link
+  // and a wrong "remote" warns at someone whose link works fine. An
+  // unrecognised value falls through to "detect", so a typo cannot become a
+  // confident answer. Default: detect.
+  //
+  // `servePort` is the default port for `spec-env review serve`, which renders
+  // every spec's diff per request on one local server. `--port` overrides it per
+  // run. The server binds 127.0.0.1 unless `--host 0.0.0.0` is passed, which
+  // mints an unguessable path token and prints the LAN URL including it —
+  // anyone holding that URL can read every spec's diff while it runs.
+  // Default: 7777.
+  //
+  // `serveOnRemote` is whether a "remote" reader may have that server started
+  // FOR them. On (the default) the engine brings it up, binds 0.0.0.0, and puts
+  // the served URL on the `open:` line — best-guess network address first, the
+  // rest listed under it, because the guess reads interface names and a VPN or
+  // an unusual adapter will fool it. Off, you get the file:// URL with its
+  // "will not open where you are reading" marker and the command to type.
+  // Either way NOTHING IS PUBLISHED on a detection: a server is one process
+  // ended by one flag, while a published page is one this tooling cannot
+  // remove, so that half stays an explicit ask. Teardown names a server that
+  // served the last spec, and `spec-env prune` reaps a pidfile whose process is
+  // gone. Default: true.
+  //
+  // `commitWith` names the skill a COMMITTING verdict hands off to. A review
+  // page ends in a verdict — commit, commit & continue, request changes,
+  // discuss — and the point of the first two is that the commit follows from
+  // the reading rather than costing a separate decision. Skitterspec never
+  // commits through a skill it vendored: `/commit` ships with skittership, a
+  // different package, and a copy living here would fork it. Two shapes:
+  //   "/commit"  — the default; hand off to skittership's commit skill.
+  //   "<name>"   — any other skill your project installs.
+  // With the named skill unavailable, the committing branch commits directly —
+  // stage, typecheck, test, conventional message — and SAYS it took that path,
+  // because a commit made under rules nobody configured must not read as one
+  // made under /commit.
+  //
+  // THERE IS NO OFF SWITCH. `"none"` existed and was removed: it produced a
+  // verdict that records itself and does nothing, which is the one thing a
+  // review page must not offer — a review is the guard in front of an action.
+  // Recording an approval for SOMEONE ELSE to act on is a separate mechanism,
+  // not a value of this key. Default: "/commit".
+  "review": {
+    "reader": "detect",
+    "servePort": 7777,
+    "serveOnRemote": true,
+    "commitWith": "/commit"
   }
 }
 ```

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

@@ -0,0 +1,4 @@
+{
+  "guidance": "",
+  "default": "none: <reason>"
+}

package/assets/core/gating.config.md

@@ -0,0 +1,81 @@
+# `gating.config.json` — release-gating config
+
+Opt-in config for **release gating**: whether each spec records a decision about
+shipping behind a feature flag.
+
+The problem it solves is not "we forgot to use a flag" — it is that
+**nobody can tell whether the question was asked**. A spec can go from `/spec`
+through
+implementation to `/spec-complete` with no flag and no mention of one, and that
+is indistinguishable from "we considered it and decided against". Prose guidance
+in a project rule has already been shown not to close that gap; a required header
+does, because its absence is visible.
+
+**Skitterspec bakes in the offer, never the mechanism.** How your project does
+flags — a resolver, an admin toggle, env precedence, a vendor SDK — is none of
+its business, and it never reads your flag code. It asks the question, cites your
+own documentation, and records the answer.
+
+**Adopt it** by copying `gating.config.json.example` → `gating.config.json` here
+(or `skitterspec init --gating`). While this file is absent the feature is
+entirely unused: no grill question, no header, nothing to check — which is read
+as "this project does not use feature flags".
+
+## Fields
+
+```jsonc
+{
+  // Where THIS project documents how its flags work — a repo-relative path,
+  // cited when the question is asked so the answer is an informed one.
+  // Skitterspec never reads the file; it only names it. Empty = say nothing.
+  "guidance": ".claude/rules/feature-flags.md",
+
+  // The value written when the user declines a flag, so a project can
+  // standardise its wording. Must keep the `none: <reason>` shape — the reason
+  // half is the whole point (see below). Empty falls back to `none: <reason>`.
+  "default": "none: <reason>"
+}
+```
+
+## The header it drives
+
+With this file present, every spec `/spec`, `/spec-bug` and `/spec-hotfix` write
+carries a `Gating:` field beside `Stack:` in `00-overview.md`:
+
+```
+> **Gating:** search-ranking-v2
+> **Gating:** none: additive, nothing to revert
+```
+
+Two valid shapes, and one that is not:
+
+| Value | Meaning |
+|-------|---------|
+| a flag name | ships behind that flag |
+| `none: <reason>` | deliberately not flagged, and why |
+| *missing, empty, or a bare `none`* | **not a decision** — nobody answered |
+
+The reason half is load-bearing. `none: additive, nothing to revert` is a
+decision a reviewer can disagree with; a bare `none` is a shrug, and a missing
+line is an oversight. Distinguishing those three is the entire feature.
+
+## What it never does
+
+- **It never blocks.** `skitterspec gating check` reports and exits 0;
+  `/spec-start` and `/spec-complete` mention a missing header and carry on.
+  Nothing here can stop a spec being started, completed or landed.
+- **It never accuses an old spec.** Only `specs/backlog/` and
+  `specs/in-progress/` are read. Specs finished or abandoned before you adopted
+  gating are out of range by construction, not by a filter someone has to
+  remember.
+- **It never learns your flag system.** `guidance` is a path it prints, nothing
+  more.
+
+## Checking
+
+```
+skitterspec gating check              # the spec in flight here
+skitterspec gating check <spec>       # one named spec
+skitterspec gating check --all        # every active spec
+skitterspec gating check --json       # for tooling
+```

package/assets/core/linear.config.md

@@ -133,6 +133,64 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
 }
 ```
 
+## Assignment (`sync.fieldOwnership.assignee`)
+
+Off by default. Add one key and the spec issue is assigned to whoever is
+building it:
+
+```jsonc
+"fieldOwnership": {
+  "description": "push",
+  "subIssues": "push",
+  "workflowState": "push",
+  "assignee": "push"          // <- the whole opt-in
+}
+```
+
+It is deliberately **not** a config key of its own. `fieldOwnership` is already
+the documented extension point — "any key you add joins the pushed projection" —
+and assignment is exactly one more field the repo owns.
+
+- **Absent = inert.** No writes, no prompts, no drift line, and no assignee hash
+  in any snapshot. A project that never opts in cannot tell the feature exists,
+  which is why it is missing from `linear.config.json.example`: that file is
+  copied verbatim into new projects, and shipping the key there would opt
+  everyone in by default.
+- **The bucket decides.** The spec's `linear_assignee_id` is pushed while the
+  spec is live (`backlog`, `in-progress`) and cleared once it reaches `complete`
+  or `cancelled` — so finishing a spec hands the issue back with no unassign
+  step for anyone to remember. The stamp stays in the file, and so does
+  `> **Developer:**`: they record who *actioned* the work, which outlives who is
+  holding it.
+- **Unset means don't touch.** A spec that records nobody sends no assignee at
+  all, so an issue a PM assigned in Linear is never overwritten. Only an assignee
+  the repo itself pushed is ever cleared — and a snapshot written before you
+  opted in counts as "never pushed", not as "was nobody".
+- **Only the spec issue.** Phase sub-issues are never assigned: one person builds
+  a spec, and N assigned sub-issues is N notifications for one piece of work.
+  They stay independently assignable in Linear.
+
+**Who you are** is not configured here, and cannot be — this file is committed,
+so a user id in it would follow the repo to every teammate who clones it. It is
+derived from your own API key (`viewer`) and cached per machine in
+`~/.config/skitterspec/credentials.json` beside the key. `spec-sync whoami`
+shows it, `--set` overrides it when the key is shared or a bot's, and
+`spec-sync users` looks somebody up by name or email.
+
+Ownership moves with **`/spec-claim`** — take it, `--release` it, or `--to` a
+teammate.
+
+**Reading it back** is **`/spec-list`** (engine: `spec-sync list`), the one
+command that asks Linear what exists instead of the repo. It lists parentless
+issues — a phase sub-issue carries a parent, a spec issue does not — joined to
+the local spec folder that owns each one, so every row carries the name you
+paste into `/spec-start`. Scope is the live states by default
+(`--state`/`--all`/`--in-progress` to change it, `--next N` for the top of the
+backlog in Linear's own order), and `--mine`/`--by <user>` filter by assignee,
+reusing the identity above rather than a second copy of it. It writes nothing,
+and it says what it did not show — the count, the archived exclusion, and any
+cap — rather than implying a completeness it never checked.
+
 ## The deployment ladder (`release.stages`)
 
 A spec's lifecycle stops at `complete`. Where a ticket goes **after** that —
@@ -366,9 +424,10 @@ default for anyone who never sets one.
 - `"deferred"` — only once the work starts. A spec sitting in `specs/backlog/`
   mirrors as **the issue alone**; its sub-issues are created by the push that
   follows `/spec-start`.
-- `"inline"` — never. Each phase becomes a **section of the spec issue's own
-  description**, with its full task list, and the `## Phases` index stays as the
-  table of contents. One issue per spec, however many phases it has.
+- `"inline"` — never. Each phase becomes a
+  **section of the spec issue's own description**, with its full task list, and
+  the `## Phases` index stays as the table of contents. One issue per spec,
+  however many phases it has.
 
 ### One mode, or one per bucket
 
@@ -405,11 +464,11 @@ that made the choice worth it.
 
 ### Switching modes is non-destructive
 
-**A phase already carrying a `linear_issue_id` keeps its sub-issue in every
-mode**, and is never *also* inlined. One-way sync has no delete op, so
-withholding a live sub-issue would not remove it from Linear — it would freeze it
-there, never updated again. So changing `mapping.phases` only ever changes what
-has yet to be minted, and a spec part-way through keeps a coherent mirror.
+**A phase already carrying a `linear_issue_id` keeps its sub-issue in every mode**,
+and is never *also* inlined. One-way sync has no delete op, so withholding a
+live sub-issue would not remove it from Linear — it would freeze it there,
+never updated again. So changing `mapping.phases` only ever changes what has
+yet to be minted, and a spec part-way through keeps a coherent mirror.
 
 **Adopting on an established repo:** set `complete: "inline"` (and `"deferred"`
 or `"inline"` for `backlog`) **before** the first backfill push. Finished specs