@skitterbyte/skitterspec-linear 19.15.0 → 19.17.0

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.
Files changed (45) hide show
  1. package/MIGRATION.md +27 -0
  2. package/README.md +2 -1
  3. package/assets/claude-md-section.md +18 -9
  4. package/assets/commands/allow-main.md +1 -2
  5. package/assets/core/env.config.json.example +0 -1
  6. package/assets/core/env.config.md +28 -26
  7. package/assets/hooks/main-guard.cjs +73 -6
  8. package/assets/hooks/project-guard.cjs +80 -6
  9. package/assets/hooks/review-gate.cjs +73 -6
  10. package/assets/review/page.html +10 -83
  11. package/assets/rules/commit-trailers.md +2 -2
  12. package/assets/rules/spec-planning.md +26 -22
  13. package/assets/rules/spec-reports.md +52 -52
  14. package/assets/skills/no-spec/SKILL.md +2 -2
  15. package/assets/skills/spec/SKILL.md +22 -5
  16. package/assets/skills/spec-bug/SKILL.md +18 -15
  17. package/assets/skills/spec-complete/SKILL.md +23 -1
  18. package/assets/skills/spec-diff/SKILL.md +47 -115
  19. package/assets/skills/spec-hotfix/SKILL.md +18 -15
  20. package/assets/skills/spec-init/SKILL.md +4 -2
  21. package/assets/skills/spec-next/SKILL.md +66 -41
  22. package/assets/skills/spec-park/SKILL.md +92 -0
  23. package/assets/skills/spec-resume/SKILL.md +153 -0
  24. package/assets/skills/spec-review/SKILL.md +2 -2
  25. package/assets/skills/spec-reviewed/SKILL.md +1 -8
  26. package/assets/skills/spec-status/SKILL.md +1 -1
  27. package/assets/skills/spec-sync/SKILL.md +12 -12
  28. package/assets/skills/spec-todo/SKILL.md +5 -2
  29. package/package.json +1 -1
  30. package/src/cli.js +361 -208
  31. package/src/env/bootstrap.js +3 -1
  32. package/src/env/checks.js +49 -0
  33. package/src/env/config.js +27 -7
  34. package/src/env/hooks.js +53 -4
  35. package/src/env/live.js +48 -0
  36. package/src/env/provision.js +10 -2
  37. package/src/env/resume.js +234 -0
  38. package/src/env/review.js +71 -173
  39. package/src/env/serve.js +3 -7
  40. package/src/init.js +383 -50
  41. package/src/tada/todo.js +19 -4
  42. package/src/vendor/linear/cli-sync.js +3 -3
  43. package/src/vendor/provider-kit/src/specs.js +46 -1
  44. package/src/vendor/sync-core/src/summary.js +10 -1
  45. package/assets/commands/spec-remote-review.md +0 -37
package/src/env/review.js CHANGED
@@ -630,21 +630,20 @@ const DEFAULT_VERDICT = 'discuss'
630
630
  * pass would need a rule about which wins, and any such rule would sometimes
631
631
  * act on the half the reader did not mean.
632
632
  *
633
- * `allow-network`/`allow-remote` turn a review TIER on, and they exist here
634
- * because the page can now act — which is the premise
635
- * `feat-three-review-links` decision 5 rejected a page toggle on, having
636
- * recorded it as open to reopening. Two things replace the limit it rested on.
637
- * **Only a reader who can already reach the page can press one**, so widening
633
+ * `allow-network` turns the served tiers on, and it exists here because the
634
+ * page can now act — which is the premise `feat-three-review-links` decision 5
635
+ * rejected a page toggle on, having recorded it as open to reopening.
636
+ * **Only a reader who can already reach the page can press it**, so widening
638
637
  * loopback→network can only be pressed from the machine itself, where the
639
638
  * command was available anyway, and the serve token still decides who reaches
640
- * the page at all. And `allow-remote` **permits publishing without
641
- * publishing** — the permanent claude.ai page still takes an explicit ask.
639
+ * the page at all. `allow-remote` went with the published tier
640
+ * (feat-tailnet-remote-tier): `remote` is the tailnet now, on `network`'s switch.
642
641
  *
643
642
  * There is no disable direction, and `tierAction` is where that is enforced:
644
643
  * turning `network` off from a page reached over the network kills the page
645
644
  * doing the turning.
646
645
  */
647
- const ACTIONS = ['live-on', 'allow-network', 'allow-remote']
646
+ const ACTIONS = ['live-on', 'allow-network']
648
647
 
649
648
  /**
650
649
  * The action a tier that is OFF offers, or null.
@@ -661,7 +660,6 @@ function tierAction(tier) {
661
660
  // command is named on the line; the page offers nothing.
662
661
  if (tier.bound === 'loopback') return null
663
662
  if (tier.tier === 'network') return 'allow-network'
664
- if (tier.tier === 'remote') return 'allow-remote'
665
663
  return null
666
664
  }
667
665
 
@@ -694,8 +692,7 @@ function surfacesFor({ live, tiers, buttons = null }) {
694
692
  // learns the surface exists and what to type, which is exactly the trade the
695
693
  // strip already makes on a `file://` page.
696
694
  //
697
- // ONLY `live-on`. `allow-network` and `allow-remote` write a config file
698
- // and commit nothing, so they are as valid mid-phase as at the end of one.
695
+ // ONLY `live-on`. `allow-network` writes a config file and commits nothing, so they are as valid mid-phase as at the end of one.
699
696
  const canCommit = buttons !== 'midrun'
700
697
  const rows = []
701
698
 
@@ -736,19 +733,11 @@ function surfacesFor({ live, tiers, buttons = null }) {
736
733
  // touches no tracked file, `allow` edits `specs/.core/env.config.json` in
737
734
  // the primary checkout — changing behaviour for everyone who pulls and
738
735
  // leaving that tree dirty. A setting change of that reach must not land
739
- // because someone tapped a button labelled only `Allow remote`.
740
- // `remote` is per spec now (bug-remote-review-toggle): a gitignored
741
- // sidecar, so the base branch is untouched and no other spec may publish.
742
- note:
743
- t.note ||
744
- (t.tier === 'remote'
745
- ? 'this spec only — nothing committed'
746
- : 'writes env.config.json — committed, and shared'),
747
- // The same thing from a terminal, for the reader who is nowhere near the
748
- // page. Only `remote` has a command of its own: `network` is ON by
749
- // default, so turning it off is a rare deliberate act and a slash command
750
- // per tier is clutter for the one nobody touches.
751
- command: t.tier === 'remote' ? '/spec-remote-review' : null,
736
+ // because someone tapped a button labelled only `Allow network`.
737
+ note: t.note || 'writes env.config.json — committed, and shared',
738
+ // No slash command: `network` is ON by default, so turning it on is a
739
+ // rare deliberate act and the press or the engine verb covers it.
740
+ command: null,
752
741
  action,
753
742
  })
754
743
  }
@@ -764,14 +753,19 @@ function surfacesFor({ live, tiers, buttons = null }) {
764
753
  * their phone opens should not have to re-read the labels every render, and a
765
754
  * stack that reordered itself by availability would make them.
766
755
  *
756
+ * LABELLED BY ADDRESS, never by where the reader sits: `local` is loopback,
757
+ * `network` the LAN, `remote` the tailnet. Relabelling the LAN `local` whenever
758
+ * loopback is hidden gave one URL two names depending on who looked, and a
759
+ * label that moves is one nobody learns (feat-tailnet-remote-tier decision 1).
760
+ *
767
761
  * WHY A STACK AT ALL, when the rule said exactly one link: the engine cannot
768
762
  * know where the reader is sitting, and every attempt to guess failed the
769
- * moment they moved. `local` and `network` are two doors into ONE room — the
770
- * page POSTs to `location.pathname`, so both reach the same server and the same
771
- * pending store, and one wait covers both. `remote` is a second store, which is
772
- * why it carries the line saying so.
763
+ * moment they moved. All three are doors into ONE room — the page POSTs to
764
+ * `location.pathname`, so each reaches the same server and the same pending
765
+ * store, and one wait covers them all. `remote` was once a published page with
766
+ * a store of its own; that tier is gone, and the tailnet took its name.
773
767
  */
774
- function reviewTierStack({ served, fileUrl, publishedUrl, config, reader = null }) {
768
+ function reviewTierStack({ served, fileUrl, config, reader = null }) {
775
769
  const tiers = []
776
770
  const loopbackUrl = served && served.loopbackUrl ? served.loopbackUrl : null
777
771
 
@@ -781,45 +775,45 @@ function reviewTierStack({ served, fileUrl, publishedUrl, config, reader = null
781
775
  : { tier: 'local', url: fileUrl, note: 'a file:// page cannot send a verdict' },
782
776
  )
783
777
 
778
+ // The served alternates, split by what they are. A tailnet address is its
779
+ // own tier; anything else (a second LAN interface) stays an `also:` under
780
+ // `network`, because that is still what it is.
781
+ const alternates = served && !served.loopback && served.url ? served.alternates || [] : []
782
+ const tailnet = alternates.filter((u) => isTailnetAddress(hostOf(u)))
783
+ const lan = alternates.filter((u) => !isTailnetAddress(hostOf(u)))
784
+
784
785
  if (!config.review.allowNetwork) {
785
- tiers.push({ tier: 'network', off: true, enable: 'skitterspec spec-env review allow network' })
786
+ const enable = 'skitterspec spec-env review allow network'
787
+ tiers.push({ tier: 'network', off: true, enable })
788
+ // THE SAME SERVER ON ANOTHER INTERFACE, so it follows the same switch — a
789
+ // separate key would be a setting for a distinction nobody has asked for.
790
+ tiers.push({ tier: 'remote', off: true, enable })
786
791
  } else if (served && !served.loopback && served.url) {
787
- // LABELLED HERE, not by the renderer: `--json`'s `tiers` is the stack a
788
- // skill copies, and an unlabelled alternate made the `(tailnet)` suffix a
789
- // fact only the text render knew — so the one link a reader off the wifi
790
- // could open reached the JSON indistinguishable from a second LAN address.
791
- tiers.push({
792
- tier: 'network',
793
- url: served.url,
794
- alternates: (served.alternates || []).map((u) => {
795
- let host = ''
796
- try {
797
- host = new URL(u).hostname
798
- } catch {}
799
- return isTailnetAddress(host) ? { url: u, label: 'tailnet' } : { url: u }
800
- }),
801
- })
792
+ tiers.push({ tier: 'network', url: served.url, alternates: lan.map((u) => ({ url: u })) })
793
+ tiers.push(
794
+ tailnet.length
795
+ ? {
796
+ tier: 'remote',
797
+ url: tailnet[0],
798
+ label: 'tailnet',
799
+ alternates: tailnet.slice(1).map((u) => ({ url: u, label: 'tailnet' })),
800
+ }
801
+ : // KEPT, AND SAYS WHY. A line that vanished whenever Tailscale was down
802
+ // would leave a reader off the wifi unable to tell "not offered" from
803
+ // "not possible". No command is named: none of ours turns it on.
804
+ { tier: 'remote', unavailable: true, note: 'no tailnet address on this machine' },
805
+ )
802
806
  } else if (served && served.loopback && served.widen) {
803
807
  // Permitted, and the machine has addresses — but the running server is
804
808
  // bound to loopback. "No network address" here sent readers looking for a
805
809
  // network problem; the fix is one command, so the line names it.
806
810
  tiers.push({ tier: 'network', off: true, bound: 'loopback', enable: served.widen })
811
+ tiers.push({ tier: 'remote', off: true, bound: 'loopback', enable: served.widen })
807
812
  } else {
808
813
  // Permitted, but there is no address to offer — a machine with no network,
809
814
  // or a server that could not take one. Not a problem to report as an error.
810
815
  tiers.push({ tier: 'network', unavailable: true, note: 'no network address on this machine' })
811
- }
812
-
813
- if (!config.review.allowRemote) {
814
- // THE COMMAND A PERSON TYPES. `/spec-remote-review` toggles, so the same
815
- // line works whichever way the tier currently is — and nobody has to
816
- // reconstruct `spec-env review allow remote` from a render they are reading
817
- // on a phone.
818
- tiers.push({ tier: 'remote', off: true, enable: '/spec-remote-review' })
819
- } else if (publishedUrl) {
820
- tiers.push({ tier: 'remote', url: publishedUrl, note: 'a verdict here needs /spec-reviewed' })
821
- } else {
822
- tiers.push({ tier: 'remote', unavailable: true, note: 'publishing is an ask — nothing published yet' })
816
+ tiers.push({ tier: 'remote', unavailable: true, note: 'no tailnet address on this machine' })
823
817
  }
824
818
 
825
819
  // A READER ON ANOTHER MACHINE gets no `local` door: it points at this
@@ -853,25 +847,25 @@ function reviewStackText(tiers) {
853
847
  }
854
848
 
855
849
  /**
856
- * The served tiers one wait covers, as the stack shows them. `local` and
857
- * `network` are two doors into one room; with `local` hidden there is one door,
858
- * and the line must not name one the reader was never shown.
850
+ * The served tiers one wait covers, as the stack shows them: every door shown
851
+ * that has a served URL. They are all one room, so the line names exactly the
852
+ * doors the reader was shown — never a hidden one, never a `file://` page.
859
853
  */
860
854
  function waitCovers(tiers) {
861
- const local = tiers.find((t) => t.tier === 'local')
862
- return local && local.hidden ? ['network'] : ['local', 'network']
855
+ return tiers
856
+ .filter((t) => !t.hidden && t.url && !String(t.url).startsWith('file:'))
857
+ .map((t) => t.tier)
863
858
  }
864
859
 
865
860
  // One tier as a line, padded so the labels form a column the eye can run down.
866
861
  // A tier with alternates renders them as indented `also:` lines of its own —
867
- // they are PART of the tier, which is what puts them under `network:` rather
868
- // than dangling after the stack (they used to print below `remote:`, against
869
- // the comment that placed them).
862
+ // they are PART of the tier, which is what puts them under it rather than
863
+ // dangling after the stack.
870
864
  function reviewTierLine(t) {
871
865
  const label = ` ${t.tier}:`.padEnd(11)
872
866
  if (t.url) {
873
867
  return [
874
- `${label}${t.url}${t.note ? ` (${t.note})` : ''}`,
868
+ `${label}${t.url}${t.label ? ` (${t.label})` : ''}${t.note ? ` (${t.note})` : ''}`,
875
869
  ...(t.alternates || []).map((a) => ` also: ${a.url}${a.label ? ` (${a.label})` : ''}`),
876
870
  ].join('\n')
877
871
  }
@@ -879,6 +873,15 @@ function reviewTierLine(t) {
879
873
  return `${label}— (${t.note})`
880
874
  }
881
875
 
876
+ // The hostname of a URL, or '' for anything that does not parse.
877
+ function hostOf(url) {
878
+ try {
879
+ return new URL(url).hostname
880
+ } catch {
881
+ return ''
882
+ }
883
+ }
884
+
882
885
  // 100.64.0.0/10 — the CGNAT range Tailscale assigns from.
883
886
  //
884
887
  // WHAT WOULD FOOL THIS: a carrier-grade NAT or another overlay network using
@@ -1843,8 +1846,8 @@ function markGateOffered(gate, { at }) {
1843
1846
  * The actions whose handling REQUIRES a commit in the spec's own worktree.
1844
1847
  *
1845
1848
  * One, and the list exists so the answer is looked up rather than remembered.
1846
- * `allow-network` and `allow-remote` write a config key and commit nothing, so
1847
- * neither has a precondition to permit — and a permit granted for an action
1849
+ * `allow-network` writes a config key and commits nothing, so it has no
1850
+ * precondition to permit — and a permit granted for an action
1848
1851
  * that never commits is a hole with no commit to close it.
1849
1852
  */
1850
1853
  const PERMITTED_ACTIONS = ['live-on']
@@ -2364,57 +2367,6 @@ function escapeHtml(s) {
2364
2367
  * The data goes in as JSON, never as generated markup — that is the property the
2365
2368
  * whole design rests on.
2366
2369
  */
2367
- /**
2368
- * The fragment form of the template: what an artifact host can accept.
2369
- *
2370
- * A published page is wrapped in the host's own `<!doctype>`/`<head>`/`<body>`
2371
- * skeleton, so handing it a complete document nests two of them. The fragment
2372
- * carries the `<title>` (hosts read it for the tab name), every `<style>` and
2373
- * `<script>` block out of `<head>`, then the body contents — and no wrapper.
2374
- *
2375
- * IT SPLITS THE TEMPLATE, NEVER THE RENDERED PAGE, and that is the whole
2376
- * correctness argument. The template contains exactly one of each boundary tag
2377
- * and nothing but placeholders where content goes. A rendered page contains the
2378
- * diff, and this feature reviews its own source — so `<!doctype html>`,
2379
- * `<html>` and `<body>` appear inside it as ordinary patch text. A regex over
2380
- * the rendered page finds those and cuts in the wrong place; the first hand
2381
- * publish of `feat-review-offer-lands` hit exactly that, with four
2382
- * wrapper-looking tags in the output that were all patch content.
2383
- */
2384
- function fragmentTemplate(template = null) {
2385
- const t = template || loadTemplate()
2386
-
2387
- const headStart = t.indexOf('<head>')
2388
- const headEnd = t.indexOf('</head>')
2389
- const bodyOpen = t.indexOf('<body')
2390
- const bodyStart = t.indexOf('>', bodyOpen) + 1
2391
- const bodyEnd = t.lastIndexOf('</body>')
2392
- if (headStart < 0 || headEnd < 0 || bodyOpen < 0 || bodyEnd < 0) {
2393
- throw new Error('review template has no <head>/<body> to split — cannot build a fragment')
2394
- }
2395
-
2396
- const head = t.slice(headStart, headEnd)
2397
- const title = /<title>[\s\S]*?<\/title>/.exec(head)
2398
- const carried = head.match(/<(style|script)\b[\s\S]*?<\/\1>/g) || []
2399
-
2400
- return [title ? title[0] : '', ...carried, t.slice(bodyStart, bodyEnd).trim()]
2401
- .filter(Boolean)
2402
- .join('\n')
2403
- }
2404
-
2405
- /**
2406
- * The same data, spliced into the fragment instead of the whole document. One
2407
- * pass over the placeholders, for the same reason `renderReviewPage` uses one.
2408
- */
2409
- function renderReviewFragment(data, { template = null, reviewHtml = '' } = {}) {
2410
- const values = {
2411
- [TITLE_PLACEHOLDER]: escapeHtml(tabTitle(data)),
2412
- [REVIEW_PLACEHOLDER]: reviewHtml,
2413
- [DATA_PLACEHOLDER]: escapeIsland(JSON.stringify(data)),
2414
- }
2415
- return fragmentTemplate(template).replace(PLACEHOLDER_RE, (m) => values[m])
2416
- }
2417
-
2418
2370
  // The tab name: `<project> · <spec>`, so pages from two projects open side by
2419
2371
  // side can be told apart from the tab alone — all a phone shows.
2420
2372
  function tabTitle(data) {
@@ -2617,13 +2569,6 @@ function reviewServerNotice({ running, othersServed }) {
2617
2569
  ]
2618
2570
  }
2619
2571
 
2620
- // The publish-ready copy, beside the page it came from. Same stem, so every
2621
- // sidecar (`.notes.json`, `.url`, `.publish.html`, `.render.json`) reads as one
2622
- // spec's set.
2623
- function reviewPublishPath(outPath) {
2624
- return outPath.replace(/\.html$/, '') + '.publish.html'
2625
- }
2626
-
2627
2572
  function readReviewUrl(outPath) {
2628
2573
  try {
2629
2574
  return fs.readFileSync(reviewUrlPath(outPath), 'utf8').trim() || null
@@ -2632,46 +2577,6 @@ function readReviewUrl(outPath) {
2632
2577
  }
2633
2578
  }
2634
2579
 
2635
- /**
2636
- * Whether ONE SPEC may publish, beside its page in the gitignored store.
2637
- *
2638
- * WHY PER SPEC. `review.allowRemote` in the committed config permits every
2639
- * spec in the repo at once, and writing it from a worktree dirtied the base
2640
- * branch (bug-remote-review-toggle). Publishing sends a diff to a third party,
2641
- * so what may generate an artifact is decided per worktree; the committed key
2642
- * stays as the project default beneath it.
2643
- */
2644
- function reviewRemotePath(outPath) {
2645
- return outPath.replace(/\.html$/, '') + '.remote.json'
2646
- }
2647
-
2648
- // true / false when the sidecar says so, null for every cannot-tell — absent,
2649
- // unreadable, a non-boolean — so the committed default stands
2650
- // (`.claude/rules/negative-checks.md` rule 4: a typo must not permit a publish).
2651
- function readRemoteAllow(outPath) {
2652
- try {
2653
- const v = JSON.parse(fs.readFileSync(reviewRemotePath(outPath), 'utf8')).allowRemote
2654
- return typeof v === 'boolean' ? v : null
2655
- } catch {
2656
- return null
2657
- }
2658
- }
2659
-
2660
- function writeRemoteAllow(outPath, on, at = new Date().toISOString()) {
2661
- const file = reviewRemotePath(outPath)
2662
- fs.mkdirSync(path.dirname(file), { recursive: true })
2663
- fs.writeFileSync(file, JSON.stringify({ allowRemote: on, at }, null, 2) + '\n')
2664
- return file
2665
- }
2666
-
2667
- // The config one spec's render reads: the project's, with this spec's own
2668
- // remote permission over it. A new object — the caller's config is shared.
2669
- function withSpecRemote(config, outPath) {
2670
- const own = readRemoteAllow(outPath)
2671
- if (own === null) return config
2672
- return { ...config, review: { ...config.review, allowRemote: own } }
2673
- }
2674
-
2675
2580
  // Default output path for a spec's page, under the gitignored `.spec-env/`.
2676
2581
  function reviewOutPath(dir, specFolder, out) {
2677
2582
  if (out) return path.resolve(dir, out)
@@ -2801,16 +2706,9 @@ module.exports = {
2801
2706
  renderReviewerStrip,
2802
2707
  reviewerSaid,
2803
2708
  reviewUrlPath,
2804
- reviewPublishPath,
2805
2709
  readReviewUrl,
2806
- reviewRemotePath,
2807
- readRemoteAllow,
2808
- writeRemoteAllow,
2809
- withSpecRemote,
2810
2710
  publishedPageNotice,
2811
2711
  reviewServerNotice,
2812
- fragmentTemplate,
2813
- renderReviewFragment,
2814
2712
  detectReader,
2815
2713
  resolveReader,
2816
2714
  readerOffMachine,
package/src/env/serve.js CHANGED
@@ -54,7 +54,6 @@ const {
54
54
  renderReviewPage,
55
55
  renderReviewBlock,
56
56
  reviewOutPath,
57
- withSpecRemote,
58
57
  validateNotesBlob,
59
58
  readPending,
60
59
  passState: readPassState,
@@ -367,8 +366,7 @@ function committedDocsFor(root, config, spec) {
367
366
  * The tier rows the PAGE needs, from config alone.
368
367
  *
369
368
  * DELIBERATELY NOT `reviewTierStack`. That stack answers "where can this be
370
- * read", which needs the server's bind, the machine's addresses and any
371
- * published URL. The page needs only the half it can act on: which tiers are
369
+ * read", which needs the server's bind and the machine's addresses. The page needs only the half it can act on: which tiers are
372
370
  * OFF, so it can offer the press that turns one on. An `off` tier has no URL by
373
371
  * definition, so none of that machinery is required — and an `on` tier
374
372
  * contributes nothing here, because the reader is standing on one of them.
@@ -376,8 +374,8 @@ function committedDocsFor(root, config, spec) {
376
374
  function pageTiers(config) {
377
375
  const r = (config && config.review) || {}
378
376
  return [
377
+ // `remote` is the tailnet on this same switch, so `network` speaks for it.
379
378
  { tier: 'network', off: !r.allowNetwork },
380
- { tier: 'remote', off: !r.allowRemote },
381
379
  ]
382
380
  }
383
381
 
@@ -632,9 +630,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
632
630
  receipt: null,
633
631
  worktreeExists: Boolean(spec.worktreePath && fs.existsSync(spec.worktreePath)),
634
632
  })
635
- // This spec's own remote permission, read per request so a toggle shows on
636
- // the next refresh without restarting the server.
637
- const tiers = pageTiers(withSpecRemote(config, out))
633
+ const tiers = pageTiers(config)
638
634
 
639
635
  let data = collectReview({
640
636
  spec,