@skitterbyte/skitterspec-linear 15.0.0 → 17.0.0

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.