@skitterbyte/skitterspec-linear 14.0.0 → 17.0.0

package/assets/core/env.config.md

@@ -21,8 +21,27 @@ port block, and no `.env`.
 exactly as it does today.
 
 The loader (`src/env/config.js` → `loadEnvConfig`) merges your file over the
-frozen defaults below and returns `{ config, present }`; `present:false` means
-no live `env.config.json` was found.
+frozen defaults below and returns `{ config, present, unknown }`;
+`present:false` means no live `env.config.json` was found.
+
+**A key not listed below is ignored — and says so.** Every `spec-env` command
+prints one advisory line per unrecognised key, top-level or nested:
+
+```
+spec-env: env.config.json — unknown key "docker.portbase" is ignored.
+```
+
+It is advisory in the strongest sense: the key is dropped exactly as it always
+was, nothing refuses, and the exit status is unchanged. It exists because the
+two things an unknown key can be — a deliberate forward-compat entry and a typo
+— are indistinguishable from here, and only one of them is a mistake you would
+want to hear about. A mis-typed `review.required` leaves the commit gate on and
+a mis-typed `teardown.deleteRemoteBranch` reverts to `prompt`; before this, the
+only signal either gave was that nothing happened.
+
+A **known** key whose value is rejected — `mode: "Checkout"`,
+`teardown.deleteRemoteBranch: "yes"` — is not reported here. Each of those falls
+through to a documented conservative default; see the field notes below.
 
 ## Fields
 
@@ -74,8 +93,9 @@ no live `env.config.json` was found.
   // `spec-env up`, right after `git worktree add` and BEFORE `setup` runs — so a
   // fresh linked worktree (which starts with none of the repo's gitignored files)
   // has the .env / local secret overrides / local config that setup steps and
-  // git hooks depend on. Without this a step like `prisma generate` hard-fails in
-  // the new worktree because .env (its datasource URL) isn't there.
+  // git hooks depend on. Without this any setup step that reads .env — a schema
+  // or client generator, a codegen pass — hard-fails in the new worktree
+  // because the file it expects isn't there.
   //   mode   "symlink" (default) points the worktree file at the main file, so it
   //          stays in sync; "copy" makes an independent copy.
   //   files  repo-relative paths to seed. A source absent in main is a printed
@@ -221,13 +241,15 @@ no live `env.config.json` was found.
 
   // 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).
+  // `reader` decides how the page's LOCATION IS WORDED. It no longer decides
+  // the bind — `allowNetwork` does, see below — and it no longer decides which
+  // tiers are offered, because every tier is now listed whatever it says.
+  // WHAT THE SERVER
+  // BINDS TO — and nothing else. It never decides whether to serve (`serve`
+  // does) and never decides to PUBLISH. Three values:
+  //   "local"  — you are at the machine holding the page; it binds 127.0.0.1.
+  //   "remote" — you are not; it binds every interface so the page opens.
+  //   "detect" — work it out (the default); cannot-tell binds 127.0.0.1.
   // 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
@@ -237,25 +259,81 @@ no live `env.config.json` was found.
   // 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.
+  // `servePort` is the port for `spec-env review serve`, which renders every
+  // spec's diff per request on one local server. Two forms:
+  //
+  //   "auto" (the default) — derive it from this repo's path, as
+  //     7700 + hash(realpath(repoRoot)) % 100. Two repos on one machine stop
+  //     competing for one shared port without anyone configuring anything, and
+  //     — the part that matters — THE SAME REPO GETS THE SAME PORT EVERY TIME.
+  //     The derivation reads nothing on disk, so the port survives a restart, a
+  //     reboot and a `--stop`, which is what lets a link handed out yesterday
+  //     still resolve. A symlinked spelling of the tree resolves first, so one
+  //     repo never lands on two ports.
+  //   <a number> — pin it. An explicit number always wins, and pinning is what
+  //     you do when you want a port you can memorise, or when two repos derive
+  //     the same one.
   //
-  // `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.
+  // A derived port CAN still collide — a hundred slots is a small chance, not
+  // no chance — and the server refuses rather than moving itself aside. The fix
+  // it names is `servePort`, because that is what the next link is built from;
+  // `--port` moves one run and leaves every link already handed out pointing at
+  // the busy port. `spec-env review serve --status` prints the port and which
+  // of the three chose it.
+  //
+  // An unrecognised value falls through to "auto", like every other typed key
+  // here. Default: "auto".
+  //
+  // 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.
+  //
+  // `serve` is whether a render stands the local server up at all:
+  //   "always" — every render does (the default), so `local:` and `network:`
+  //              are both http URLs the page can POST a verdict back to. The
+  //              LAN address comes first with the rest listed under it, because
+  //              the guess reads interface names and a VPN or an unusual
+  //              adapter will fool it.
+  //   "never"  — `local:` is a file:// URL instead. Note what that costs: a
+  //              file:// page has no server to POST to, so its verdict buttons
+  //              copy a command for you to paste rather than sending anything.
+  // It replaced `serveOnRemote`, which gated serving on the reader — and so
+  // handed a local machine a page it could read and not answer. A legacy
+  // `serveOnRemote: false` is still read as `serve: "never"`.
   // 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.
   //
+  // `allowNetwork` and `allowRemote` decide WHICH TIERS a render offers, and
+  // they replaced the engine guessing where the reader was sitting. It guessed
+  // for a while and got it wrong three separate ways in one day: a file:// page
+  // on a session detected `unknown`, a LAN URL for a phone that had left the
+  // network, and an address that changed underneath a reader mid-session. So
+  // every tier is listed, labelled, and either a URL or the one command that
+  // turns it on — and you pick the one that reaches you.
+  //
+  //   `allowNetwork` — whether the review server binds EVERY INTERFACE, so the
+  //                    page opens on your phone, or loopback only. THIS IS WHAT
+  //                    CHOOSES THE BIND; `reader` no longer does. Default: true,
+  //                    which matches what the engine already did.
+  //   `allowRemote`  — whether PUBLISHING is permitted at all. It permits it; it
+  //                    publishes nothing. Default: FALSE, because a published
+  //                    page is one skitterspec cannot delete, so it must never
+  //                    happen unasked.
+  //
+  // `local` and `network` are two doors into ONE ROOM — the page POSTs to
+  // `location.pathname`, so both reach the same server and the same waiting
+  // verdict, and one wait covers both. `remote` is a second store: a verdict
+  // pressed on a published page needs `/spec-reviewed`, because nothing pushes
+  // from an artifact's store into a conversation.
+  //
+  // Both are toggled by `spec-env review allow <tier> --set [on|off]`, where an
+  // empty value toggles — which is what `/spec-remote-review` runs. It writes
+  // THIS FILE in the primary checkout, so it changes for everyone who pulls and
+  // leaves that tree dirty; the engine says so when it does.
+  //
   // `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
@@ -288,8 +366,8 @@ no live `env.config.json` was found.
   // place rather than quietly disabling it. Default: true.
   "review": {
     "reader": "detect",
-    "servePort": 7777,
-    "serveOnRemote": true,
+    "servePort": "auto",
+    "serve": "always",
     "commitWith": "/commit",
     "required": true
   }

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

@@ -41,7 +41,8 @@
     "fieldOwnership": {
       "description": "push",
       "subIssues": "push",
-      "workflowState": "push"
+      "workflowState": "push",
+      "assignee": "push"
     },
     "localOnlySections": ["State log", "Changelog", "Open questions"],
     "keyedFields": {}

package/assets/core/linear.config.md

@@ -19,7 +19,9 @@ your team ID (and an optional grouping project).
 The loader (`src/sync/config.js` → `loadLinearConfig`) merges your file over the
 frozen defaults below and returns `{ config, present }`; `present:false` means no
 live `linear.config.json` was found (the opt-in gate — it never throws on
-absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error.
+absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard error.
+`none` is how a repo **declines** a field the defaults own — see
+**Assignment** below, which is the field that needs it.
 
 ## Fields
 
@@ -40,7 +42,10 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   "intake": {
     "label": "",          // inbox filter — the label the web app files under
     "bugLabels": [],      // e.g. ["bug"] — these route to /spec-bug instead
-    "hotfixLabels": []    // e.g. ["production"] — these route to /spec-hotfix
+    "hotfixLabels": [],   // e.g. ["production"] — these route to /spec-hotfix
+    "preserveOriginal": true  // keep the reporter's description as a comment
+                              // before the linking push replaces it. ON by
+                              // default; false declines.
   },
 
   // How a spec's parts map onto Linear objects: a spec is an Issue, each phase a
@@ -119,7 +124,8 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
     "fieldOwnership": {
       "description": "push",
       "subIssues": "push",
-      "workflowState": "push"
+      "workflowState": "push",
+      "assignee": "push"
     },
 
     // Markdown sections of 00-overview.md that are local-only scaffolding and
@@ -135,37 +141,41 @@ 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:
+**On by default since v16.** The spec issue is assigned to whoever is building
+it: `/spec-start` records them, and the issue is released when the spec
+completes. To decline it, say so:
 
 ```jsonc
 "fieldOwnership": {
-  "description": "push",
-  "subIssues": "push",
-  "workflowState": "push",
-  "assignee": "push"          // <- the whole opt-in
+  "assignee": "none"          // <- the whole opt-out
 }
 ```
 
 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.
+and assignment is exactly one more field the repo owns. `none` is a value rather
+than an omitted key because the map merges **per key** onto the defaults: once a
+field is owned by default there is nothing an absent key can subtract.
+
+- **`none` = inert.** No writes, no prompts, no drift line, and no assignee hash
+  in any snapshot — identical in every respect to a field the config never
+  listed. A repo that declines cannot tell the feature exists.
+- **It was opt-in until v16**, and the cost of that was silent in the wrong
+  direction: a repo that never added the line looked exactly like one that had
+  decided against it, so the only signal was noticing an unassigned issue weeks
+  later. Declining is now a decision on the record; forgetting is not a state.
 - **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".
+- **Unset means don't touch, and this is what makes on-by-default safe.** 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 the field was owned counts as "never
+  pushed", not as "was nobody". Turning the default on widens who gets
+  **assigned**; it cannot widen who gets **unassigned**.
 - **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.
@@ -605,8 +615,25 @@ The issue **becomes** the spec's issue: its identifier is stamped as
 `linear_identifier`, phases become its sub-issues, and the **linking push**
 — which runs as the spec is created — replaces its description with the spec. The
 reporter's comments, links and subscribers stay on the one issue everyone is
-already watching; their original words are carried into the spec's **Problem**
-(or **Symptom**) section, and Linear keeps the original in the issue's history.
+already watching.
+
+**What happens to what they wrote.** Two things, and neither is the issue's
+history:
+
+- **Adoption posts it back as a comment**, verbatim, before the push replaces
+  the description (`skitterspec spec-sync preserve <spec>`, which the adoption
+  skills run for you). A comment is outside `sync.fieldOwnership` by design —
+  Linear-native triage that one-way sync never touches — which is exactly what
+  makes it safe: no later push can clobber it. It carries a marker so a second
+  run posts nothing, and it never fails the adoption: an unreachable Linear, an
+  issue with no description or `intake.preserveOriginal: false` all exit 0 and
+  say so. Set that key to `false` to turn the whole thing off.
+- **The spec quotes them** in its **Problem** (or **Symptom**) section, which
+  *is* pushed as part of the generated description — so the reporter's words are
+  in the description too, and they round-trip like everything else.
+
+The issue's history does technically hold the pre-adoption text, and it is not
+the answer: a diff viewer is not quotable and nobody opens one.
 
 An issue already stamped on a spec can't be adopted twice — `skitterspec spec-sync
 linked` is the list that's checked.