@skitterbyte/skitterspec-linear 15.0.0 → 17.0.0

package/src/vendor/linear/config.js

@@ -11,13 +11,13 @@
  *
  * Mirrors the shape/idiom of `src/env/config.js` (frozen defaults, merge known
  * keys only, forward-compatible on unknown keys). Zero-dependency. The one place
- * it is stricter: a `sync.fieldOwnership` value outside `both|pull|push` is a
- * hard error — the engine's whole safety model rests on those enums.
+ * it is stricter: a `sync.fieldOwnership` value outside `both|pull|push|none` is
+ * a hard error — the engine's whole safety model rests on those enums.
  *
  * Shape (see assets/core/linear.config.md for field docs):
  *   {
  *     linear:   { teamKey, teamId, projectId },
- *     intake:   { label, bugLabels, hotfixLabels },
+ *     intake:   { label, bugLabels, hotfixLabels, preserveOriginal },
  *     mapping:  { specFolder, phases, tasks },
  *     states:   { backlog, "in-progress", complete, cancelled },
  *     release:  { stages: [{ key, state }] },
@@ -25,7 +25,7 @@
  *     branch:   { pattern },
  *     sync: {
  *       baseDir, backupDir,
- *       fieldOwnership: { <field>: "both" | "pull" | "push" },
+ *       fieldOwnership: { <field>: "both" | "pull" | "push" | "none" },
  *       localOnlySections: string[]
  *     }
  *   }
@@ -36,7 +36,14 @@ const { join } = require('node:path')
 
 const CONFIG_FILE = join('specs', '.core', 'linear.config.json')
 
-const OWNERSHIP = Object.freeze(['both', 'pull', 'push'])
+// `none` is how a repo DECLINES a field the defaults own. It has to be a
+// value rather than an omitted key, because an omitted key cannot override a
+// default that is present — and `mergeFieldOwnership` merges per key onto the
+// defaults, so there is no way to subtract one. Every reader asks `ownsField`
+// rather than testing for the key, which is what keeps the two indistinguishable
+// downstream: a declined field and an unlisted one both leave the projection
+// without that key at all.
+const OWNERSHIP = Object.freeze(['both', 'pull', 'push', 'none'])
 
 // How a phase's task list is projected into its sub-issue description.
 //   checklist — mirror the tasks as a read-only markdown checklist (default)
@@ -125,7 +132,19 @@ const DEFAULT_CONFIG = Object.freeze({
   // and no routing. `hotfixLabels` wins over `bugLabels` on an issue carrying
   // both: production is the more specific destination, and the cost of getting it
   // wrong is asymmetric — a fix that lands only on main never reaches prod.
-  intake: Object.freeze({ label: '', bugLabels: Object.freeze([]), hotfixLabels: Object.freeze([]) }),
+  // `preserveOriginal` is the other half of intake, and it is about what
+  // adoption COSTS rather than where it routes. Adopting an existing issue
+  // replaces the reporter's description with the generated spec, so
+  // `spec-sync preserve` first posts that description as a comment — the one
+  // surface on the issue that sync never touches.
+  //
+  // ON BY DEFAULT, and `false` is how a project declines. Opt-in was rejected
+  // for the reason `sync.fieldOwnership.assignee` records below: a repo that
+  // never added the line would look identical to one that did not want the
+  // feature, and the only signal would be noticing a lost report weeks later.
+  // Being wrong in this direction costs a comment nobody needed; the other
+  // direction costs someone their words.
+  intake: Object.freeze({ label: '', bugLabels: Object.freeze([]), hotfixLabels: Object.freeze([]), preserveOriginal: true }),
   // A spec is a Linear ISSUE; each phase is a SUB-ISSUE of it; tasks are not
   // synced (they live only in the repo phase files).
   // A spec is an ISSUE; each phase a SUB-ISSUE of it. `tasks` selects how the
@@ -165,17 +184,22 @@ const DEFAULT_CONFIG = Object.freeze({
     // the set, so the PM's triage is never touched. The `push` marker is retained
     // for shape; any key you add joins the pushed projection.
     //
-    // `assignee` is the one field that OPTS IN this way rather than shipping on:
-    // add `"assignee": "push"` and the issue is assigned to whoever is building
-    // the spec, and released when it completes. Left out (the default) the whole
-    // feature is inert — nothing is written, no hash is recorded in a snapshot,
-    // and `status` prints no assignee line. It is deliberately not a new config
-    // key: this map is already the documented extension point, and assignment is
-    // exactly "one more field the repo owns".
+    // `assignee` ships ON, and the opt-out is `"assignee": "none"`. It was
+    // opt-in until v16, and the cost of that was silent in exactly the wrong
+    // direction: a repo that never added the line looked identical to one that
+    // did not want the feature, so the only signal was noticing an unassigned
+    // issue weeks later.
+    //
+    // WHAT MAKES ON-BY-DEFAULT SAFE, and it is not this line: a spec that
+    // records no assignee sends none (so a PM's triage survives), and a snapshot
+    // with no assignee key means "never pushed" rather than "was null" (so no
+    // upgrade emits a clear). Flipping the default widens who gets assigned; it
+    // cannot widen who gets UNassigned. See `compare.js` `issueChanges`.
     fieldOwnership: Object.freeze({
       description: 'push',
       subIssues: 'push',
       workflowState: 'push',
+      assignee: 'push',
     }),
     localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
     // Fields that are keyed collections (arrays of objects with a stable id),
@@ -203,6 +227,7 @@ function defaults() {
       label: DEFAULT_CONFIG.intake.label,
       bugLabels: [...DEFAULT_CONFIG.intake.bugLabels],
       hotfixLabels: [...DEFAULT_CONFIG.intake.hotfixLabels],
+      preserveOriginal: DEFAULT_CONFIG.intake.preserveOriginal,
     },
     mapping: { ...DEFAULT_CONFIG.mapping },
     states: { ...DEFAULT_CONFIG.states },
@@ -412,6 +437,9 @@ function mergeConfig(base, parsed) {
     if (Array.isArray(parsed.intake.hotfixLabels)) {
       base.intake.hotfixLabels = stringList(parsed.intake.hotfixLabels)
     }
+    // `'boolean'`, so only a real `false` turns this off. A string, a null or a
+    // typo leaves the default standing rather than reading as a decline.
+    assign(base.intake, parsed.intake, 'preserveOriginal', 'boolean')
   }
 
   if (isObject(parsed.mapping)) {

package/src/vendor/linear/doctor.js

@@ -261,10 +261,11 @@ function keyCheck(s = {}, tracker = {}) {
  *
  * WHAT WOULD MAKE THIS CHECK ACCUSE THE INNOCENT, and why it does not:
  *
- *   - **A project that never opted in.** Assignment is opt-in through
- *     `sync.fieldOwnership.assignee`; without it nothing reads an identity, so
- *     reporting one as missing would tell a healthy project to fix something it
- *     deliberately does not use. That is `skipped`, and it is the common case.
+ *   - **A project that does not own the field.** `sync.fieldOwnership.assignee`
+ *     decides, and `"none"` declines it as surely as omitting it does; without
+ *     ownership nothing reads an identity, so reporting one as missing would
+ *     tell a healthy project to fix something it deliberately does not use.
+ *     That is `skipped`.
  *   - **An identity that is merely underivable.** No key, offline, a shared
  *     credential — all ordinary, all `missing` rather than `broken`, because the
  *     lifecycle skills skip assignment and carry on. Nothing here fails a run.
@@ -276,7 +277,7 @@ function keyCheck(s = {}, tracker = {}) {
 function identityCheck(s = {}, tracker = {}) {
   if (!tracker.present) return row('identity', 'identity', 'skipped', 'no tracker configured')
   if (!s.owned) {
-    return row('identity', 'identity', 'skipped', 'assignment not enabled (sync.fieldOwnership.assignee)')
+    return row('identity', 'identity', 'skipped', 'assignment not owned here (sync.fieldOwnership.assignee)')
   }
   if (!s.ok) {
     return row(

package/src/vendor/sync-core/index.js

@@ -13,18 +13,19 @@
  * stored matches what was sent — it merges nothing (see `src/verify.js`).
  */
 
-const { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
-const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify } = require('./src/compare.js')
+const { ownsField, normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
+const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited } = require('./src/compare.js')
 const { readBase, writeBase } = require('./src/base.js')
 const { push, recordPush, projectionOf } = require('./src/push.js')
 const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
 const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
 const { detectLegacyMirror } = require('./src/legacy.js')
-const { compareStored } = require('./src/verify.js')
+const { compareStored, stream } = require('./src/verify.js')
 const { flattenNestedTables } = require('./src/tables.js')
 const { planRetarget, applyRetarget, deriveRecordedKey, isEmptyRetarget, dirtyPaths } = require('./src/retarget.js')
 
 module.exports = {
+  ownsField,
   normalizeLocal,
   // Exported for `spec-sync list`: an `inline`-mode spec has no phase sub-issues
   // to read, so the listing must resolve the mode rather than assume `subissue`.
@@ -58,6 +59,13 @@ module.exports = {
   sanitizeSpecMarkdown,
   detectLegacyMirror,
   compareStored,
+  // The tolerant reduction behind both `compareStored` and the snapshot's
+  // `descriptionStream` hash — exported so a provider can reduce a read-back the
+  // same way rather than writing a second one that disagrees.
+  stream,
+  // Did someone else edit the tracker's description since the last push?
+  // Three-valued; `null` is cannot-tell and must never be reported as drift.
+  remoteDescriptionEdited,
   flattenNestedTables,
   planRetarget,
   applyRetarget,

package/src/vendor/sync-core/src/compare.js

@@ -19,6 +19,10 @@
  */
 
 const { createHash } = require('node:crypto')
+// The tolerant reduction `verify.js` already uses to tell Linear's own
+// reserialisation apart from a real edit. Imported rather than reimplemented:
+// two reductions that disagree would be two different answers to one question.
+const { stream } = require('./verify.js')
 
 // Deterministic JSON: object keys sorted recursively; array order preserved.
 // undefined normalises to null.
@@ -69,8 +73,68 @@ function specIssueFieldHashes(p) {
   // "the feature is inert" has to include the files it writes, or opting in later
   // would find a history of hashes it never agreed to.
   if (p.assignee !== undefined) hashes.assignee = hashField(p.assignee ?? null)
+
+  // A SECOND HASH OF THE SAME TEXT, answering a different question.
+  //
+  // `description` above decides what to PUSH: it is exact, because any
+  // difference between the repo and what the repo last sent is a difference the
+  // repo should send again. This one decides whether SOMEBODY ELSE has been
+  // here, and for that exactness is precisely wrong — Linear reserialises
+  // markdown on save (bullets rewritten, ordered lists renumbered, table
+  // separators collapsed), so comparing the exact hash against a read-back would
+  // report a human edit on every intact mirror in the workspace.
+  //
+  // So it hashes the `stream` reduction instead: word characters only, which is
+  // what `compareStored` already compares and what makes every benign transform
+  // invisible. The cost is the mirror image — an edit consisting ONLY of
+  // punctuation or formatting is invisible here too — and that is the right way
+  // round: the unknown case goes to the branch that says nothing rather than the
+  // one that accuses (`.claude/rules/negative-checks.md` rule 4).
+  //
+  // It is recorded and never planned on. `issueChanges` reads `description`,
+  // `state` and `assignee` by name and never iterates this object, so adding a
+  // key here cannot make a push pending — there is a test for exactly that.
+  hashes.descriptionStream = hashField(stream(p.description ?? ''))
   return hashes
 }
+
+/**
+ * Has the tracker's copy of the description been edited by someone other than
+ * this repo, since the last push?
+ *
+ * THREE ANSWERS, and the third is the point: `true`, `false`, and `null` for
+ * cannot-tell. Only `true` may be reported to a user, because only `true` is
+ * evidence. The three cannot-tells, each an absence that proves nothing:
+ *
+ *   - no `issueFields.descriptionStream` in the snapshot. EVERY snapshot written
+ *     before this function existed lacks it, so reading that absence as evidence
+ *     would accuse every spec in every repo on the first run after an upgrade.
+ *     This is the blind spot that matters most here.
+ *   - no `description` key on the remote object. The caller did not ask the
+ *     tracker for it, or could not.
+ *   - a `description` that is not a string. The same blind spot `compareStored`
+ *     documents: a value the caller never fetched is indistinguishable from one
+ *     the tracker really holds empty.
+ *
+ * Pure: no I/O, no clock, no randomness.
+ *
+ * @param {object|null} snapshot  the committed last-pushed snapshot
+ * @param {object|null} remote    what the tracker currently holds for the issue
+ * @returns {boolean|null}
+ */
+function remoteDescriptionEdited(snapshot, remote) {
+  const fields = snapshot && snapshot.issueFields
+  if (!fields || typeof fields !== 'object' || Array.isArray(fields)) return null
+  const recorded = fields.descriptionStream
+  if (typeof recorded !== 'string' || !recorded) return null
+
+  if (!remote || typeof remote !== 'object') return null
+  if (!('description' in remote)) return null
+  const text = remote.description
+  if (typeof text !== 'string') return null
+
+  return hashField(stream(text)) !== recorded
+}
 // A phase SUB-ISSUE: its name, goal and state (all repo-owned).
 const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? null, state: s.state ?? null })
 
@@ -228,6 +292,7 @@ function isEmptyPlan(plan) {
 
 module.exports = {
   planChanges,
+  remoteDescriptionEdited,
   issueChanges,
   specIssueFieldHashes,
   snapshotOf,

package/src/vendor/sync-core/src/normalize.js

@@ -488,11 +488,36 @@ function lintPhases(snapshotDir, config) {
 
 // --- ownership-driven field set ---------------------------------------------
 
+/**
+ * Does this repo own `field` — i.e. does the projection carry it at all?
+ *
+ * THE VALUE DECIDES, NEVER THE KEY'S PRESENCE. A field configured `none` is
+ * declared not-ours, and it must be indistinguishable from one the config never
+ * listed: both produce a projection with no such key, which is the single
+ * vocabulary every downstream reader already speaks for "not in play"
+ * (`compare.js` hashes it only when defined; the status report prints an
+ * assignee line only when defined).
+ *
+ * Asked in one place so the two cannot drift. Testing `field in fieldOwnership`
+ * at a call site reads correct and is not: once a field is owned by DEFAULT the
+ * key is always present, and the test silently becomes "always true".
+ */
+function ownsField(config, field) {
+  const owned = config && config.sync && config.sync.fieldOwnership
+  return !!owned && field in owned && owned[field] !== 'none'
+}
+
 // Reduce an `extracted` map to exactly the configured field keys, defaulting a
 // missing field to `null` so local and remote always share an identical set.
+//
+// A declined field is OMITTED, not set null. The two are not interchangeable
+// here: `null` is a value this projection asserts — it is how a finished spec
+// hands its issue back — so writing it for a field the repo does not own would
+// clear in Linear exactly what declining ownership promised not to touch.
 function toFieldSet(extracted, config) {
   const out = {}
   for (const field of Object.keys(config.sync.fieldOwnership)) {
+    if (!ownsField(config, field)) continue
     out[field] = field in extracted ? extracted[field] : null
   }
   return out
@@ -1065,6 +1090,7 @@ function stateSuggestions(config, workspaceStates) {
 }
 
 module.exports = {
+  ownsField,
   stateSuggestions,
   configuredStateNames,
   normalizeLocal,