@skitterbyte/skitterspec-linear 17.3.0 → 17.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -28,10 +28,12 @@
28
28
  "registry": ".spec-env/registry.json",
29
29
  "branch": {
30
30
  "pattern": "{type}/{slug}",
31
- "identifierField": ""
31
+ "identifierField": "linear_identifier"
32
32
  },
33
33
  "spec": {
34
- "companionPaths": []
34
+ "companionPaths": [
35
+ "specs/.core/linear-base/{identifier}.base.json"
36
+ ]
35
37
  },
36
38
  "baseBranch": "",
37
39
  "guards": {
@@ -188,6 +188,16 @@ through to a documented conservative default; see the field notes below.
188
188
  // deliberate: the file it names then belongs to some other spec, and the safe
189
189
  // failure is a refusal you clear with /commit, not a stranger's file swept
190
190
  // into your commit. Default: none — a spec owns only its own folder.
191
+ //
192
+ // THIS DISTRIBUTION SEEDS BOTH KEYS. `skitterspec init --isolation` writes an
193
+ // `env.config.json` already carrying
194
+ // `"companionPaths": ["specs/.core/linear-base/{identifier}.base.json"]` and
195
+ // `"identifierField": "linear_identifier"`, because the Linear snapshot is
196
+ // written by this package, and only this package knows where. What follows is
197
+ // the base engine's default — what you get if you clear them.
198
+ //
199
+ // Both or neither: `{identifier}` resolves through `branch.identifierField`,
200
+ // so `companionPaths` on its own expands to nothing and owns nothing.
191
201
  "spec": {
192
202
  "companionPaths": []
193
203
  },
@@ -242,6 +242,12 @@ paraphrase it into "done".
242
242
  **Only when `specs/.core/env.config.json` exists** (per-spec isolation is on). If
243
243
  it is absent, skip this — there is nothing to configure.
244
244
 
245
+ **Check before you write — a fresh install already has this.** Since 17.4.0 the
246
+ superset seeds both keys into the `env.config.json` that `init --isolation`
247
+ writes, so the common case here is reading the file and finding it done. This
248
+ step is the **retrofit**: a project that adopted isolation before that, or ran
249
+ `/spec-linear-setup` before adopting it, still has the empty defaults.
250
+
245
251
  `/spec-start` commits an uncommitted spec for you, but only the paths it can
246
252
  prove belong to that spec. Its own folder always does; this repo's per-spec
247
253
  Linear snapshot (`sync.baseDir`, `specs/.core/linear-base/<ID>.base.json`) does
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "17.3.0",
3
+ "version": "17.3.1",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -2576,18 +2576,58 @@ function specEnvReviewAllow(dir, config, tier, flags) {
2576
2576
  }
2577
2577
 
2578
2578
  // `review skip` — move on without a verdict, on the record.
2579
- function specEnvReviewSkip(dir, config, reason, flags) {
2579
+ /**
2580
+ * Split `skip`'s positionals into a spec and a reason.
2581
+ *
2582
+ * WHY IT IS NOT SIMPLY `positional[1]`. It was, and it made the gate's own
2583
+ * documented exit unreachable: a spec whose worktree is gone resolves neither
2584
+ * from the cwd nor from a sole provisioned spec, so the refusal told the
2585
+ * operator to "name the one you mean" — a thing the command could not accept —
2586
+ * while its worktree, the other half of that advice, no longer existed. The
2587
+ * gate was then permanent, and clearing it meant hand-editing a gitignored
2588
+ * sidecar. `review gate <spec>` and `review <spec> --claim-since` both take a
2589
+ * name; this was the one that did not.
2590
+ *
2591
+ * TWO POSITIONALS are unambiguous: spec, then reason.
2592
+ *
2593
+ * ONE IS DECIDED BY A POSITIVE SIGNAL (`.claude/rules/negative-checks.md`
2594
+ * rule 1) — it is a spec only where it RESOLVES to one. `findSpecFolder`
2595
+ * matches a bucket folder by exact basename, so nothing fuzzy gets in: a reason
2596
+ * has to be spelled exactly like a spec folder to be read as one, and a reason
2597
+ * that is spelled exactly like a spec folder is a person naming a spec. Every
2598
+ * cannot-tell — an unknown name, an unresolvable repo, a thrown resolver —
2599
+ * falls to the reason, which is the behaviour this command has always had and
2600
+ * the harmless branch.
2601
+ *
2602
+ * THE PROBE NEVER DECIDES THE OUTCOME, only which slot the word fills. What
2603
+ * happens next is the ordinary resolution, refusal text and all.
2604
+ */
2605
+ function splitSkipArgs(dir, config, rest) {
2606
+ const args = (rest || []).filter((a) => a !== undefined && a !== null)
2607
+ if (args.length >= 2) return { specArg: args[0], reason: args[1] }
2608
+ if (args.length === 1) {
2609
+ return gateTarget(dir, config, args[0]).spec
2610
+ ? { specArg: args[0], reason: null }
2611
+ : { specArg: null, reason: args[0] }
2612
+ }
2613
+ return { specArg: null, reason: null }
2614
+ }
2615
+
2616
+ function specEnvReviewSkip(dir, config, rest, flags) {
2617
+ const { specArg, reason } = splitSkipArgs(dir, config, rest)
2580
2618
  const said = String(reason || '').trim()
2581
2619
  if (!said) {
2582
2620
  // The reason IS the feature. A skip with no reason is the silence this
2583
- // whole gate exists to replace, so it is refused rather than defaulted.
2621
+ // whole gate exists to replace, so it is refused rather than defaulted —
2622
+ // and naming the spec is not giving one, which is why the probe above puts
2623
+ // a lone spec name in the spec slot and leaves this empty.
2584
2624
  process.stdout.write(
2585
- 'spec-env review skip: needs a reason — skitterspec spec-env review skip "<why>"\n',
2625
+ 'spec-env review skip: needs a reason — skitterspec spec-env review skip [<spec>] "<why>"\n',
2586
2626
  )
2587
2627
  process.exitCode = 1
2588
2628
  return
2589
2629
  }
2590
- const target = gateTarget(dir, config, null)
2630
+ const target = gateTarget(dir, config, specArg)
2591
2631
  if (!target.spec) {
2592
2632
  process.stdout.write(`spec-env review skip: cannot tell which spec — ${target.reason}\n`)
2593
2633
  process.exitCode = 1
@@ -5114,10 +5154,10 @@ async function specEnv(rest) {
5114
5154
  break
5115
5155
  }
5116
5156
  if (positional[0] === 'skip') {
5117
- // The one positional is the REASON, not a spec: the two are
5118
- // indistinguishable as free text, and the spec is the one thing this
5119
- // engine can already resolve from where you are standing.
5120
- specEnvReviewSkip(dir, config, positional[1], flags)
5157
+ // `skip [<spec>] "<why>"`. The spec is usually resolvable from where you
5158
+ // are standing, which is why it stays optional — but not always, and
5159
+ // `splitSkipArgs` carries why that mattered enough to change.
5160
+ specEnvReviewSkip(dir, config, positional.slice(1), flags)
5121
5161
  break
5122
5162
  }
5123
5163
  await specEnvReview(dir, config, positional[0], flags, invokedFrom)
@@ -5134,7 +5174,7 @@ async function specEnv(rest) {
5134
5174
  ' review arm [spec] [--phase <n>] a phase ended — its diff now owes a verdict\n' +
5135
5175
  ' review gate [spec] [--check] [--json] is one owed? --check exits non-zero if so\n' +
5136
5176
  ' [--for-command <cmdline>] ...but only when that command is a git commit\n' +
5137
- ' review skip "<reason>" move on without one, on the record\n' +
5177
+ ' review skip [spec] "<reason>" move on without one, on the record\n' +
5138
5178
  ' review gate [spec] --offered record that the bypass was offered (spends it)\n' +
5139
5179
  ' review wait [spec] --heartbeat <secs> proof-of-life cadence on stderr; 0 disables\n' +
5140
5180
  ' review wait [spec] --since <iso> block until a verdict arrives ([--timeout <s>])\n' +
@@ -210,6 +210,50 @@ const DEFAULT_CONFIG = Object.freeze({
210
210
  }),
211
211
  })
212
212
 
213
+ // The frontmatter field `spec-sync apply` stamps a spec's issue identifier into.
214
+ // Named once, because three things have to agree on it: the stamp itself, the
215
+ // snapshot filename derived from it, and the `branch.identifierField` below that
216
+ // tells the base engine where to read it back from.
217
+ const IDENTIFIER_FIELD = 'linear_identifier'
218
+
219
+ /**
220
+ * The per-spec-isolation keys THIS PROVIDER needs a project to declare, merged
221
+ * into the superset's shipped `env.config.json.example` by `build-dist`.
222
+ *
223
+ * WHY IT LIVES HERE. `env.config.json` belongs to the base engine, which is
224
+ * tracker-free by design and must keep shipping these two empty — a base that
225
+ * named Linear's snapshot would point every install at a directory nothing
226
+ * writes. The superset is the component that WRITES that snapshot, and it is
227
+ * therefore the only one that can declare it.
228
+ *
229
+ * WHAT GOES WRONG WITHOUT IT. `spec-env stage` splits a dirty tree by exact
230
+ * membership, so an undeclared `linear-base/<ID>.base.json` is FOREIGN — to the
231
+ * very `/spec-complete` skill that asserts it is declared and commits it by
232
+ * name. The snapshot is then left uncommitted and `spec-env integrate` refuses
233
+ * to land the branch over it, which is the failure that assertion exists to
234
+ * prevent.
235
+ *
236
+ * BOTH KEYS OR NEITHER, and this is the half that hides. `expandCompanion`
237
+ * (`common/src/env/classify.js`) expands `{identifier}` only when
238
+ * `branch.identifierField` names a frontmatter field to read it from, so a
239
+ * config carrying `companionPaths` alone expands to nothing, matches nothing,
240
+ * and looks applied while changing no behaviour.
241
+ *
242
+ * SETTING `identifierField` DOES NOT CHANGE BRANCH NAMES. `branchFor`
243
+ * (`common/src/env/resolve.js`) consults it only when `branch.pattern` contains
244
+ * `{identifier}`, and the shipped pattern is `{type}/{slug}`.
245
+ *
246
+ * The pattern is DERIVED from `sync.baseDir` rather than typed out beside it: a
247
+ * second copy of that path would stay valid while owning nothing the day the
248
+ * snapshot directory moved.
249
+ */
250
+ const ENV_CONFIG_DEFAULTS = Object.freeze({
251
+ branch: Object.freeze({ identifierField: IDENTIFIER_FIELD }),
252
+ spec: Object.freeze({
253
+ companionPaths: Object.freeze([`${DEFAULT_CONFIG.sync.baseDir}/{identifier}.base.json`]),
254
+ }),
255
+ })
256
+
213
257
  // The lifecycle buckets a per-bucket `mapping.phases` map may key on. Derived
214
258
  // from `states` rather than restated: both maps key on the spec's folder bucket,
215
259
  // so they cannot drift apart.
@@ -579,4 +623,6 @@ module.exports = {
579
623
  TRANSPORTS,
580
624
  DEFAULT_KEY_ENV,
581
625
  DEFAULT_RELEASE_IGNORE_PATHS,
626
+ ENV_CONFIG_DEFAULTS,
627
+ IDENTIFIER_FIELD,
582
628
  }