@skitterbyte/skitterspec-jira 2.11.0 → 2.12.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.
@@ -12,6 +12,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
12
12
  | `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
13
13
  | `/spec-incident` | (Incident) Capture a live outage as a record written during it — grill, write in flight, fixes as separate linked specs | `In Progress` | `specs/in-progress/` |
14
14
  | `/no-spec` | Work that genuinely has no spec — its own branch, worktree, page and land. Writes no spec and moves nothing through the lifecycle | `—` | (none) |
15
+ | `/spec-idea` | Capture an idea without specing it — in the tracker when the provider holds ideas, else `specs/ideas.md` on the base branch; bare lists, `--drop` discards. `/spec idea:<id>` or `/spec #N` promotes one | `—` | (none) |
15
16
  | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
16
17
  | `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
17
18
  | `/spec-next` | Build the next phase of the spec this session is in (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
@@ -74,6 +75,17 @@ branch. Beneath it, `skitterspec spec-env nospec <name>` records the branch —
74
75
  and that record is what makes a name with nothing under `specs/**` resolvable by
75
76
  `review`, `integrate`, `down` and a bare `resolve`.
76
77
 
78
+ **`/spec-idea` is the door before `/spec`.** `/spec` grills until there is a
79
+ spec, which is right for work and wrong for a passing thought. This skill files
80
+ the thought as it stands, somewhere the team can see. An idea is not a spec,
81
+ so it has no folder, no status and no branch. It lives in the tracker when the
82
+ provider can hold ideas (an issue kept off the board, which `/spec #N` already
83
+ adopts), and otherwise in `specs/ideas.md`. That file is committed straight
84
+ onto the base branch by `skitterspec idea`, using plumbing, so no checkout is
85
+ switched or left dirty, and it is never pushed for you. A configured provider
86
+ that does not declare an idea store is cannot-tell: capture refuses and hands
87
+ the text back, rather than putting one idea in each store.
88
+
77
89
  **`/spec-tada` reads, and moves nothing.** It is in the table because it
78
90
  reports in the unit the table is about — a spec — but it changes no status,
79
91
  writes no file and commits nothing. `skitterspec tada` reads Claude Code's own
@@ -140,6 +140,36 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
140
140
  there somewhere". The comment is the answer, and the other half is the spec's
141
141
  own **Problem** (or **Symptom**) section quoting the reporter.
142
142
 
143
+ ## Phase 0b — start from an idea (only when asked)
144
+
145
+ **Only when the invocation names an idea** with `idea:<id>`, a handle that
146
+ `/spec-idea` lists for an idea kept in `specs/ideas.md`. An idea kept in the
147
+ tracker is an ordinary issue, so `/spec #N` adopts it through Phase 0 above,
148
+ and nothing here applies to it.
149
+
150
+ 1. **Read it.** Run `skitterspec idea list --json` and find the entry whose
151
+ `id` matches. If none does, **stop** and say so: an id that matches nothing
152
+ is never stood in for by the nearest one.
153
+ 2. **Seed, don't skip, the grill.** The idea's title becomes the working spec
154
+ title, and its body becomes the starting material for **Problem**. Quote it
155
+ rather than paraphrasing it away. An idea is a thought, not a groomed
156
+ requirement, so grill it as hard as anything else.
157
+ 3. **Retire it once the spec exists — never before.** The idea is dropped
158
+ after the spec reaches somewhere it can be found. With isolation, that is
159
+ once a committing verdict has committed it (and landed it, under
160
+ `"trunk"`). Without isolation, it is once the spec is written. Run:
161
+
162
+ ```
163
+ skitterspec idea drop <id> --reason "promoted to <spec-name>"
164
+ ```
165
+
166
+ It commits onto the base branch by itself, so it needs no pathspec and has
167
+ no part in the spec's own commit. A drop that is refused leaves the idea
168
+ listed. Say so in `Notes` and carry on: a stale idea is a nuisance, but a
169
+ lost one is the failure this exists to prevent.
170
+ **A run that writes no spec drops nothing** — a `⏸` grill and a
171
+ `discuss` verdict both leave the idea where it was.
172
+
143
173
  ## Phase A — reach a clear shared understanding (grill first)
144
174
 
145
175
  Interview the user until requirement AND proposed solution are unambiguous. Do
@@ -97,10 +97,20 @@ Jira credentials are set (see `apply.transport` in `jira.config.md`).
97
97
  complete/cancelled/reviewed in the repo regardless; the mirror is disposable
98
98
  and the next push repairs it. Do not roll anything back, and do not stop to
99
99
  ask.
100
- - **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
101
- a PR, and a ready PR is not a merged one — so skip it on run 1, even where
102
- the `branch` lane committed the move to ride the PR, and run it on run 2 once
103
- the host has merged. The tracker's Done lands when the work does.
100
+ - **In `/spec-complete`'s PR mode the Done waits for run 2.** Run 1 readies a
101
+ PR, and a ready PR is not a merged one. Which run pushes depends on the
102
+ `land.specDocs` lane:
103
+ - **`trunk`** — skip it on run 1. Run 2 moves the spec on base, so it pushes
104
+ there in this step's usual place, before its own commit.
105
+ - **`branch`** — run 1 commits the move to ride the PR, so push **here**,
106
+ holding the state: `spec-sync apply <spec> --plan <file> --hold-state`.
107
+ Everything but the Done goes now, and the snapshot is written as if the
108
+ Done had gone too, so it rides the PR. Run 2 sends it once the host has
109
+ merged: `spec-sync apply <spec> --send-held`, which needs no plan and
110
+ leaves the snapshot untouched. Over MCP, apply by hand and end run 1 with
111
+ `spec-sync record <spec> --held`.
112
+
113
+ The tracker's Done lands when the work does.
104
114
  - **Say what happened** in the skill's report: mirror updated, skipped as
105
115
  unlinked, or failed with the reason.
106
116
  - **There is no assignment to release here.** Assignment sync is not yet
@@ -119,6 +129,14 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
119
129
  snapshot under `specs/.core/`. Push after the commit instead and both are left
120
130
  uncommitted, which makes `spec-env integrate` refuse to land the branch.
121
131
 
132
+ **PR mode keeps both halves by splitting the push across the runs.** In the
133
+ `branch` lane the commit happens in run 1, and run 2 only has the base branch,
134
+ where nothing is left to commit a snapshot to. An unsplit push there left a
135
+ modified snapshot on base after every completion. `--hold-state` writes run 2's
136
+ snapshot in run 1, and `--send-held` then moves only the state. If it says
137
+ nothing was held (a run 1 from before this), it sends the whole plan and names
138
+ the snapshot it leaves modified. Relay that line.
139
+
122
140
  The snapshot is reached **by name**, not by breadth. It is a declared
123
141
  `spec.companionPaths` entry (`specs/.core/jira-base/{identifier}.base.json`),
124
142
  so `spec-env stage` returns it among this spec's owned paths and the commit below
@@ -178,10 +178,20 @@ Jira credentials are set (see `apply.transport` in `jira.config.md`).
178
178
  complete/cancelled/reviewed in the repo regardless; the mirror is disposable
179
179
  and the next push repairs it. Do not roll anything back, and do not stop to
180
180
  ask.
181
- - **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
182
- a PR, and a ready PR is not a merged one — so skip it on run 1, even where
183
- the `branch` lane committed the move to ride the PR, and run it on run 2 once
184
- the host has merged. The tracker's Done lands when the work does.
181
+ - **In `/spec-complete`'s PR mode the Done waits for run 2.** Run 1 readies a
182
+ PR, and a ready PR is not a merged one. Which run pushes depends on the
183
+ `land.specDocs` lane:
184
+ - **`trunk`** — skip it on run 1. Run 2 moves the spec on base, so it pushes
185
+ there in this step's usual place, before its own commit.
186
+ - **`branch`** — run 1 commits the move to ride the PR, so push **here**,
187
+ holding the state: `spec-sync apply <spec> --plan <file> --hold-state`.
188
+ Everything but the Done goes now, and the snapshot is written as if the
189
+ Done had gone too, so it rides the PR. Run 2 sends it once the host has
190
+ merged: `spec-sync apply <spec> --send-held`, which needs no plan and
191
+ leaves the snapshot untouched. Over MCP, apply by hand and end run 1 with
192
+ `spec-sync record <spec> --held`.
193
+
194
+ The tracker's Done lands when the work does.
185
195
  - **Say what happened** in the skill's report: mirror updated, skipped as
186
196
  unlinked, or failed with the reason.
187
197
  - **There is no assignment to release here.** Assignment sync is not yet
@@ -200,6 +210,14 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
200
210
  snapshot under `specs/.core/`. Push after the commit instead and both are left
201
211
  uncommitted, which makes `spec-env integrate` refuse to land the branch.
202
212
 
213
+ **PR mode keeps both halves by splitting the push across the runs.** In the
214
+ `branch` lane the commit happens in run 1, and run 2 only has the base branch,
215
+ where nothing is left to commit a snapshot to. An unsplit push there left a
216
+ modified snapshot on base after every completion. `--hold-state` writes run 2's
217
+ snapshot in run 1, and `--send-held` then moves only the state. If it says
218
+ nothing was held (a run 1 from before this), it sends the whole plan and names
219
+ the snapshot it leaves modified. Relay that line.
220
+
203
221
  The snapshot is reached **by name**, not by breadth. It is a declared
204
222
  `spec.companionPaths` entry (`specs/.core/jira-base/{identifier}.base.json`),
205
223
  so `spec-env stage` returns it among this spec's owned paths and the commit below
@@ -474,6 +492,10 @@ person happens before the ready, in this order:
474
492
  — run 2 moves it on base after the merge; under `branch` commit the move on
475
493
  the branch *before* step 3 so it rides the PR. Either way
476
494
  **the tracker's Done waits for run 2**: a ready PR is not a merged one.
495
+ Under `branch` the §4 tracker step still runs here, but holding the state
496
+ (`--hold-state`, as the step says), so the snapshot run 2 would write is in
497
+ the commit that rides the PR. Otherwise run 2 leaves it modified on the base
498
+ branch, where nothing is left to commit it to.
477
499
  5. **Stop, keeping the worktree.** Report
478
500
  `Landed: PR #N opened — finish after merge` (or `ready`), spec
479
501
  `In Progress`, worktree standing. No afterLand runs — the plan deferred it
@@ -483,13 +505,19 @@ person happens before the ready, in this order:
483
505
  **Run 2 — after the host merges.** `integrate` recognises the landed branch
484
506
  (ancestry or the host's answer) and prints the finish: catch local base up and
485
507
  the deferred `afterLand` with the land's own range. Run those, then do what run
486
- 1 deferred — the §4 move (trunk lane) with its State log row and commit, the
487
- §5 report — then **§7 teardown runs as normal**:
508
+ 1 deferred — the §4 move (trunk lane) with its State log row and commit, or
509
+ under `branch` the held state alone (`--send-held`, which writes nothing to the
510
+ tree), the §5 report — then **§7 teardown runs as normal**:
488
511
  a host-merged branch counts as landed (squash and rebase
489
512
  merges included), and a host that auto-deleted the branch makes the remote
490
513
  delete an already-gone no-op, never a failure. Re-test on base before calling
491
514
  it done, exactly as 6-feature/bug step 4.
492
515
 
516
+ Where `--send-held` reports that nothing was held — a run 1 from before the
517
+ hold existed — it has sent the whole plan, and its line names the snapshot it
518
+ left modified on base. Put that in the report's `Notes`: only the operator can
519
+ choose where that file goes.
520
+
493
521
  ## 7. Tear down the environment (opt-in, only if configured)
494
522
 
495
523
  **A hotfix is torn down later, by `hotfix finish`.**
@@ -0,0 +1,115 @@
1
+ ---
2
+ name: spec-idea
3
+ description: Capture an idea for a future spec without specing it — one step, no grilling — somewhere the team can see it (the tracker when a provider holds ideas, else specs/ideas.md on the base branch). Bare, it lists the ideas waiting; --drop discards one. Use when the user says "/spec-idea", "note this idea", "park this for later", "add to the ideas list", "what ideas do we have", or wants to get a thought down without writing a spec.
4
+ ---
5
+
6
+ # /spec-idea — capture now, spec later
7
+
8
+ > Stay silent while this runs — speak only to ask something you cannot answer
9
+ > yourself, or to report a failure at the moment it happens. Read
10
+ > `.claude/rules/spec-reports.md` before reporting; it defines the block this
11
+ > skill ends with.
12
+
13
+ `/spec` grills until there is a spec. That is right for work and wrong for a
14
+ passing thought, which then gets specced too early or not written down at all.
15
+ This skill is the other door: it files the thought as it stands, and the grill
16
+ happens later, when someone promotes it with `/spec`.
17
+
18
+ **The engine decides where an idea lives — never you.** `skitterspec idea`
19
+ uses the tracker when the installed provider holds ideas (an issue kept off the
20
+ board), and `specs/ideas.md` on the base branch when there is no provider or
21
+ the provider says it cannot. A configured provider that says nothing is
22
+ cannot-tell, and the engine refuses rather than splitting ideas across two
23
+ stores. Relay what it decided; do not second-guess it.
24
+
25
+ ## 1. Pick the mode from the arguments
26
+
27
+ | Invocation | Mode |
28
+ |------------|------|
29
+ | `/spec-idea <text>` | capture |
30
+ | `/spec-idea` (bare), "what ideas do we have" | list |
31
+ | `/spec-idea --drop <ref> [reason]` | drop |
32
+
33
+ ## 2. Capture
34
+
35
+ **Ask nothing by default.** Getting the thought out of someone's head is the
36
+ whole point, and every question is a reason not to bother.
37
+
38
+ **One judgement, made once.** Read the text. If it is asking for design rather
39
+ than recording a thought — questions addressed to you, "suggestions welcome",
40
+ several alternatives left open for someone to weigh — it wants the grill now.
41
+ Offer the choice once, with a picker:
42
+
43
+ - **Grill it now with `/spec`.** Invoke `/spec` and seed it with the text. The
44
+ idea is not filed, because the spec will record it.
45
+ - **File it as an idea.** File it exactly as typed.
46
+
47
+ A short or rough thought is not a design question. When in doubt, file it: an
48
+ idea can always be promoted, but a grill that nobody asked for is the cost this
49
+ skill exists to remove.
50
+
51
+ To file it, pass the text as **one argument**, newlines included. The first
52
+ line becomes the title and the rest becomes the body:
53
+
54
+ ```
55
+ skitterspec idea add "<text>" --json
56
+ ```
57
+
58
+ **Never push.** On the file store the engine commits onto the base branch and
59
+ prints the push instead of running it, because a push publishes the base
60
+ branch and that is always the operator's call.
61
+
62
+ **A refused capture loses nothing.** The engine prints the text back. Put it in
63
+ the `Why` row verbatim so the user can copy it.
64
+
65
+ ## 3. List
66
+
67
+ ```
68
+ skitterspec idea list
69
+ ```
70
+
71
+ Relay the ideas as a table in the body of the message, one row per idea:
72
+ title, date, and the handle that promotes it. That is `/spec idea:<id>` for a
73
+ file idea, and `/spec #N` (or the provider's own reference) for a tracker idea.
74
+ An empty list is an answer, so say it is empty.
75
+
76
+ ## 4. Drop
77
+
78
+ ```
79
+ skitterspec idea drop <ref> --reason "<reason>"
80
+ ```
81
+
82
+ Pass the reason when one was given. **Do not ask for one** — dropping a
83
+ thought should cost no more than having it. On the tracker the idea is closed
84
+ as not planned. In the file the entry is removed and the reason goes in the
85
+ commit, where git keeps it.
86
+
87
+ ## Promotion is `/spec`'s, not this skill's
88
+
89
+ `/spec idea:<id>` or `/spec #N` turns an idea into a spec. It seeds the grill
90
+ from the idea and retires the idea once the spec exists. This skill never
91
+ writes a spec.
92
+
93
+ ## Report
94
+
95
+ End with the block defined in `.claude/rules/spec-reports.md`. That file carries
96
+ the shape; this section carries only what is specific here. In list mode the
97
+ table of ideas is the body of the message, and the block follows it.
98
+
99
+ **Verdicts**
100
+
101
+ - `✅` — an idea was filed or dropped, or the list was read (an empty list
102
+ included).
103
+ - `⏸` — the engine refused, so nothing was written. Name the reason in `Why`,
104
+ with the text when it was a capture.
105
+ - Handing off to `/spec` emits no block here: that skill ends with its own.
106
+
107
+ **Fields:** `Tracker` · `Built` · `Landed` · `Follow-ups` · `Next`
108
+
109
+ `Tracker` is the idea's issue, when the provider holds it. `Built` is what
110
+ happened: the idea's id and title, where it went, or the count listed.
111
+ `Landed` covers the file store only: the commit on the base branch and
112
+ `not pushed · <the push it printed> publishes it`. `Next` is the handle that
113
+ promotes the idea (`/spec idea:<id>`, `/spec #N`), or `none` after a drop.
114
+
115
+ **`Follow-ups` is always `none` here.** An idea is the follow-up.
@@ -27,7 +27,7 @@ clobber customised content. Finish with a summary of created vs already-present.
27
27
  > **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
28
28
  > `--reset` (reset needs `--yes`) drive the stronger actions.
29
29
 
30
- The system is **seventeen skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
30
+ The system is **eighteen skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
31
31
  `spec-hotfix` (a bug fixed on a released tag),
32
32
  `spec-incident` (a live outage, recorded as it happens),
33
33
  `no-spec` (work that genuinely has none — off the base branch all the same),
@@ -36,7 +36,8 @@ The system is **seventeen skills**: `spec` (feature, chore or issue), `spec-bug`
36
36
  `spec-reviewed` (pick up a review you approved on that page),
37
37
  `spec-epic-next` (name the epic member that can start now), `spec-to-main`,
38
38
  `spec-complete`, `spec-cancel`, `spec-tada` (a ta-da list of what got done),
39
- `spec-todo` (where you left off, and what is ahead),
39
+ `spec-todo` (where you left off, and what is ahead), `spec-idea` (an idea
40
+ parked without a spec),
40
41
  and this `spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
41
42
  with `.core` holding always-apply project rules.
42
43
 
@@ -147,10 +147,20 @@ Jira credentials are set (see `apply.transport` in `jira.config.md`).
147
147
  complete/cancelled/reviewed in the repo regardless; the mirror is disposable
148
148
  and the next push repairs it. Do not roll anything back, and do not stop to
149
149
  ask.
150
- - **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
151
- a PR, and a ready PR is not a merged one — so skip it on run 1, even where
152
- the `branch` lane committed the move to ride the PR, and run it on run 2 once
153
- the host has merged. The tracker's Done lands when the work does.
150
+ - **In `/spec-complete`'s PR mode the Done waits for run 2.** Run 1 readies a
151
+ PR, and a ready PR is not a merged one. Which run pushes depends on the
152
+ `land.specDocs` lane:
153
+ - **`trunk`** — skip it on run 1. Run 2 moves the spec on base, so it pushes
154
+ there in this step's usual place, before its own commit.
155
+ - **`branch`** — run 1 commits the move to ride the PR, so push **here**,
156
+ holding the state: `spec-sync apply <spec> --plan <file> --hold-state`.
157
+ Everything but the Done goes now, and the snapshot is written as if the
158
+ Done had gone too, so it rides the PR. Run 2 sends it once the host has
159
+ merged: `spec-sync apply <spec> --send-held`, which needs no plan and
160
+ leaves the snapshot untouched. Over MCP, apply by hand and end run 1 with
161
+ `spec-sync record <spec> --held`.
162
+
163
+ The tracker's Done lands when the work does.
154
164
  - **Say what happened** in the skill's report: mirror updated, skipped as
155
165
  unlinked, or failed with the reason.
156
166
  - **There is no assignment to release here.** Assignment sync is not yet
@@ -169,6 +179,14 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
169
179
  snapshot under `specs/.core/`. Push after the commit instead and both are left
170
180
  uncommitted, which makes `spec-env integrate` refuse to land the branch.
171
181
 
182
+ **PR mode keeps both halves by splitting the push across the runs.** In the
183
+ `branch` lane the commit happens in run 1, and run 2 only has the base branch,
184
+ where nothing is left to commit a snapshot to. An unsplit push there left a
185
+ modified snapshot on base after every completion. `--hold-state` writes run 2's
186
+ snapshot in run 1, and `--send-held` then moves only the state. If it says
187
+ nothing was held (a run 1 from before this), it sends the whole plan and names
188
+ the snapshot it leaves modified. Relay that line.
189
+
172
190
  The snapshot is reached **by name**, not by breadth. It is a declared
173
191
  `spec.companionPaths` entry (`specs/.core/jira-base/{identifier}.base.json`),
174
192
  so `spec-env stage` returns it among this spec's owned paths and the commit below
@@ -46,6 +46,9 @@ What the lines mean:
46
46
  - `finished:` — the specs that day completed or cancelled, by name.
47
47
  - `blocked:` — a review verdict waiting, or a gate armed by a phase that ended
48
48
  and still owes an answer. Read only for specs in flight.
49
+ - `ideas:` — how many ideas are waiting for the `(here)` project. It is a count,
50
+ never the next action: `/spec-idea` lists them, and the line is absent when
51
+ there are none or the count could not be read.
49
52
  - `today:` — commits and moves since midnight, when there are any.
50
53
 
51
54
  ## 2. Write the recap
@@ -32,6 +32,10 @@ require('../src/env/config.js').setProviderEnvDefaults(
32
32
  require('../src/env/config.js').setProviderConfigFile(
33
33
  require('../src/vendor/jira/config.js').CONFIG_FILE,
34
34
  )
35
+ // Jira does not hold ideas yet, and SAYS so: `skitterspec idea` then uses
36
+ // specs/ideas.md. Registering nothing would read as cannot-tell and refuse
37
+ // every capture (see common src/idea.js, selectStore).
38
+ require('../src/idea.js').setProviderIdeaStore({ supports: false })
35
39
  const {
36
40
  PROVIDER_COMMANDS,
37
41
  providerHelpSection,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-jira",
3
- "version": "2.11.0",
3
+ "version": "2.12.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -377,6 +377,13 @@ Usage:
377
377
  waiting and gates armed, and today so far. Same
378
378
  scope as tada (--here, --all-projects), --json,
379
379
  --page [--summary <recap.md>].
380
+ skitterspec idea <cmd> Ideas not specced yet, where the team can see them:
381
+ in the tracker when the provider holds ideas, else
382
+ specs/ideas.md landed on the base branch (never
383
+ pushed — it prints the push). Subcommands:
384
+ add <text> capture one; first line is the title
385
+ list what is waiting (--count, --json)
386
+ drop <id> discard one (--reason <why>)
380
387
  skitterspec gating <cmd> Release-gating check (opt-in; needs
381
388
  specs/.core/gating.config.json). Subcommands:
382
389
  check [spec] report specs with no recorded gating
@@ -905,6 +912,26 @@ function repoBlockers(repo, specs) {
905
912
  return readBlockers(reviewsDirFor(repo, config), specs, config.review && config.review.required)
906
913
  }
907
914
 
915
+ /**
916
+ * The home project's waiting ideas, or null when that cannot be told. A
917
+ * provider store asks the network, so the answer is bounded: a slow, failed or
918
+ * refused count is null, and null prints nothing — an idea count is never a
919
+ * reason for the morning report to fail or stall.
920
+ */
921
+ async function ideaCount(repo) {
922
+ let text = ''
923
+ const sink = { write: (s) => (text += s) }
924
+ try {
925
+ const counted = require('./ideacmd.js').ideaCommand(['list', '--count', '--json'], { cwd: repo, out: sink })
926
+ const timeout = new Promise((resolve) => setTimeout(() => resolve('timeout'), 5000).unref())
927
+ if ((await Promise.race([counted, timeout])) !== 0) return null
928
+ const n = JSON.parse(text).count
929
+ return Number.isInteger(n) ? n : null
930
+ } catch {
931
+ return null
932
+ }
933
+ }
934
+
908
935
  /**
909
936
  * `skitterspec todo` — the morning half of the ta-da list: where each project
910
937
  * was left on the last day with any activity, what is ahead, and what is in
@@ -931,7 +958,7 @@ async function todoCommand(argv) {
931
958
  } catch {
932
959
  // the folder name stands in, as it does everywhere else
933
960
  }
934
- home = { repo: homeRepo, name, groups: openSpecsIn(homeRepo).map((row) => ({ spec: row.spec, inFlight: row })) }
961
+ home = { repo: homeRepo, name, groups: openSpecsIn(homeRepo).map((row) => ({ spec: row.spec, inFlight: row })), ideas: await ideaCount(homeRepo) }
935
962
  }
936
963
 
937
964
  const todo = buildTodo({ leftOff, leftOffDay: day, today: todaySoFar, home, blockersFor: repoBlockers })
@@ -8107,6 +8134,11 @@ async function run(argv) {
8107
8134
  return
8108
8135
  }
8109
8136
 
8137
+ if (cmd === 'idea') {
8138
+ process.exitCode = await require('./ideacmd.js').ideaCommand(rest)
8139
+ return
8140
+ }
8141
+
8110
8142
  if (cmd === 'epic') {
8111
8143
  const [sub, ...eArgs] = rest
8112
8144
  if (sub === 'status') epicStatusCommand(eArgs)
package/src/env/config.js CHANGED
@@ -927,6 +927,12 @@ function setProviderConfigFile(rel) {
927
927
  providerConfigFile = rel || null
928
928
  }
929
929
 
930
+ // Is a ticketing provider registered AND configured in this project? The same
931
+ // signal `land.specDocs` defaults on, so the two cannot disagree.
932
+ function providerConfigured(dir) {
933
+ return Boolean(providerConfigFile) && existsSync(join(dir, providerConfigFile))
934
+ }
935
+
930
936
  // An explicit `specDocs` in the file — any value, even one the merge rejected —
931
937
  // is the project's decision; a rejected typo stays on the conservative "trunk"
932
938
  // rather than being promoted to the provider default.
@@ -976,6 +982,7 @@ module.exports = {
976
982
  loadEnvConfig,
977
983
  setProviderEnvDefaults,
978
984
  setProviderConfigFile,
985
+ providerConfigured,
979
986
  resolveServePort,
980
987
  derivedServePort,
981
988
  servePortRoot,
@@ -52,7 +52,7 @@ const GIT_READS = new Set([
52
52
 
53
53
  // skitterspec verbs that only read, as `verb` or `verb sub`.
54
54
  const ENGINE_READS = new Set([
55
- 'tada', 'todo', 'status', 'help', '--help', '-h', '--version', '-v',
55
+ 'tada', 'todo', 'idea list', 'status', 'help', '--help', '-h', '--version', '-v',
56
56
  'spec-env status', 'spec-env resolve',
57
57
  'epic status', 'epic check', 'gating check', 'spec-sync ownership', 'spec-sync board',
58
58
  ])
package/src/idea.js ADDED
@@ -0,0 +1,190 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Ideas — the inbox for work that is not a spec yet.
5
+ *
6
+ * `/spec-idea` captures a thought without grilling it, somewhere the team can
7
+ * see. Where a ticketing provider can hold ideas, it does (an issue kept off
8
+ * the board); everywhere else they live in one file on the base branch,
9
+ * `specs/ideas.md`. This module is the pure half: the file's format, the id
10
+ * an entry is addressed by, the add/drop planners, and the choice of store.
11
+ * Every git call lives in the CLI.
12
+ */
13
+
14
+ const IDEAS_FILE = 'specs/ideas.md'
15
+
16
+ const PREAMBLE = [
17
+ '# Ideas',
18
+ '',
19
+ 'Captured with `/spec-idea`, not specced yet. Promote one with',
20
+ '`/spec idea:<id>`; discard one with `/spec-idea --drop <id>`.',
21
+ '',
22
+ ].join('\n')
23
+
24
+ // `## <id> · <YYYY-MM-DD> · <author>`
25
+ const HEADER = /^## ([a-z0-9][a-z0-9-]*) · (\d{4}-\d{2}-\d{2}) · (.+)$/
26
+
27
+ // The id is part of a commit subject (`docs(ideas): drop <id>`), and the
28
+ // subject line is held to 50 characters.
29
+ const MAX_ID = 30
30
+
31
+ /**
32
+ * Parse `specs/ideas.md`. Everything before the first `## ` line is the
33
+ * preamble and is kept verbatim. A `## ` line that is not an entry header is
34
+ * reported in `malformed` rather than guessed at, because rewriting the file
35
+ * around a hand edit we did not understand would lose it.
36
+ */
37
+ function parseIdeas(text) {
38
+ const lines = String(text || '').split('\n')
39
+ const first = lines.findIndex((line) => line.startsWith('## '))
40
+ const preamble = first === -1 ? lines.join('\n') : lines.slice(0, first).join('\n')
41
+ const entries = []
42
+ const malformed = []
43
+ if (first === -1) return { preamble, entries, malformed }
44
+
45
+ let current = null
46
+ for (const line of lines.slice(first)) {
47
+ if (line.startsWith('## ')) {
48
+ const m = HEADER.exec(line)
49
+ if (!m) {
50
+ malformed.push(line)
51
+ current = null
52
+ continue
53
+ }
54
+ current = { id: m[1], date: m[2], author: m[3].trim(), lines: [] }
55
+ entries.push(current)
56
+ } else if (current) {
57
+ current.lines.push(line)
58
+ }
59
+ }
60
+ return {
61
+ preamble,
62
+ entries: entries.map(({ lines: body, ...rest }) => ({ ...rest, ...splitText(body.join('\n')) })),
63
+ malformed,
64
+ }
65
+ }
66
+
67
+ /** First non-empty line is the title; whatever follows it is the body. */
68
+ function splitText(text) {
69
+ const lines = String(text || '').replace(/\r\n/g, '\n').split('\n')
70
+ const at = lines.findIndex((line) => line.trim())
71
+ if (at === -1) return { title: '', body: '' }
72
+ return { title: lines[at].trim(), body: lines.slice(at + 1).join('\n').trim() }
73
+ }
74
+
75
+ function formatIdeas({ preamble, entries }) {
76
+ const head = (preamble && preamble.trim() ? preamble : PREAMBLE).replace(/\s+$/, '')
77
+ const blocks = entries.map((e) =>
78
+ [`## ${e.id} · ${e.date} · ${e.author}`, e.title, ...(e.body ? [e.body] : [])].join('\n'),
79
+ )
80
+ return [head, ...blocks].join('\n\n') + '\n'
81
+ }
82
+
83
+ /** A short kebab id from the title, unique among `taken`. */
84
+ function ideaId(title, taken = []) {
85
+ const words = String(title || '')
86
+ .toLowerCase()
87
+ .replace(/[^a-z0-9]+/g, ' ')
88
+ .trim()
89
+ .split(/\s+/)
90
+ .filter(Boolean)
91
+ let stem = ''
92
+ for (const word of words) {
93
+ const next = stem ? `${stem}-${word}` : word
94
+ if (next.length > MAX_ID) break
95
+ stem = next
96
+ }
97
+ if (!stem) stem = words.length ? words[0].slice(0, MAX_ID) : 'idea'
98
+ const used = new Set(taken)
99
+ if (!used.has(stem)) return stem
100
+ for (let n = 2; ; n++) {
101
+ const suffix = `-${n}`
102
+ const candidate = `${stem.slice(0, MAX_ID - suffix.length)}${suffix}`
103
+ if (!used.has(candidate)) return candidate
104
+ }
105
+ }
106
+
107
+ function refuseMalformed(parsed) {
108
+ if (!parsed.malformed.length) return null
109
+ return (
110
+ `${IDEAS_FILE} has ${parsed.malformed.length} heading(s) that are not idea entries ` +
111
+ `(first: "${parsed.malformed[0]}") — fix them by hand; nothing was written`
112
+ )
113
+ }
114
+
115
+ /**
116
+ * Plan an add: `{ id, content, message }`, or `{ refused }`. `text` is what
117
+ * was typed — the first line becomes the title.
118
+ */
119
+ function planAdd(current, { text, author, date }) {
120
+ const { title, body } = splitText(text)
121
+ if (!title) return { refused: 'nothing to capture — give the idea some text' }
122
+ const parsed = parseIdeas(current)
123
+ const bad = refuseMalformed(parsed)
124
+ if (bad) return { refused: bad }
125
+ const id = ideaId(title, parsed.entries.map((e) => e.id))
126
+ // A body line that opens with `## ` would read back as an entry header.
127
+ const safe = body.replace(/^(#+ )/gm, '\\$1')
128
+ const entry = { id, date, author: author || 'unknown', title, body: safe }
129
+ return {
130
+ id,
131
+ entry,
132
+ content: formatIdeas({ preamble: parsed.preamble, entries: [...parsed.entries, entry] }),
133
+ message: `docs(ideas): add ${id}\n\n- Capture "${title}" in ${IDEAS_FILE}\n`,
134
+ }
135
+ }
136
+
137
+ /** Plan a drop: `{ id, content, message }`, or `{ refused }`. */
138
+ function planDrop(current, { id, reason }) {
139
+ const parsed = parseIdeas(current)
140
+ const bad = refuseMalformed(parsed)
141
+ if (bad) return { refused: bad }
142
+ const entry = parsed.entries.find((e) => e.id === id)
143
+ if (!entry) return { refused: `no idea "${id}" — \`skitterspec idea list\` shows them` }
144
+ const why = reason && reason.trim() ? reason.trim() : 'no reason given'
145
+ return {
146
+ id,
147
+ entry,
148
+ content: formatIdeas({ preamble: parsed.preamble, entries: parsed.entries.filter((e) => e !== entry) }),
149
+ message: `docs(ideas): drop ${id}\n\n- Discard "${entry.title}": ${why}\n`,
150
+ }
151
+ }
152
+
153
+ // A provider that can hold ideas registers its store here; one that cannot
154
+ // registers `{ supports: false }`. Left unregistered, the answer is unknown.
155
+ let providerIdeaStore
156
+ function setProviderIdeaStore(store) {
157
+ providerIdeaStore = store
158
+ }
159
+ function getProviderIdeaStore() {
160
+ return providerIdeaStore
161
+ }
162
+
163
+ /**
164
+ * Which store holds ideas: `file`, `provider`, or `unknown`.
165
+ *
166
+ * The file is chosen only on a POSITIVE answer — no provider configured, or a
167
+ * provider that registered `supports: false`. A configured provider that said
168
+ * nothing is unknown, and capture refuses instead of writing to the file:
169
+ * filing there while the team reads the tracker would put one idea in each
170
+ * store with nothing to say which is the real one.
171
+ */
172
+ function selectStore({ providerConfigured, store }) {
173
+ if (!providerConfigured) return 'file'
174
+ if (store && store.supports === true) return 'provider'
175
+ if (store && store.supports === false) return 'file'
176
+ return 'unknown'
177
+ }
178
+
179
+ module.exports = {
180
+ IDEAS_FILE,
181
+ parseIdeas,
182
+ formatIdeas,
183
+ splitText,
184
+ ideaId,
185
+ planAdd,
186
+ planDrop,
187
+ selectStore,
188
+ setProviderIdeaStore,
189
+ getProviderIdeaStore,
190
+ }
package/src/ideacmd.js ADDED
@@ -0,0 +1,242 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * `skitterspec idea <add|list|drop>` — the side-effecting half of `idea.js`.
5
+ *
6
+ * The file store writes `specs/ideas.md` straight onto the base branch with
7
+ * plumbing — a throwaway index, `commit-tree`, then a fast-forward — so no
8
+ * checkout is switched, no worktree is made, and the primary checkout is never
9
+ * left dirty. Where the base branch is checked out, the fast-forward runs
10
+ * there (`merge --ff-only`) so its working tree follows; elsewhere the ref
11
+ * moves by compare-and-swap. Either way a base that moved underneath us
12
+ * refuses rather than overwriting it.
13
+ *
14
+ * Nothing is pushed. The base branch is shared once it is pushed, and a push
15
+ * is always the operator's to make, so the command prints it instead.
16
+ */
17
+
18
+ const fs = require('node:fs')
19
+ const os = require('node:os')
20
+ const path = require('node:path')
21
+ const { execFileSync } = require('node:child_process')
22
+
23
+ const { IDEAS_FILE, parseIdeas, planAdd, planDrop, selectStore, getProviderIdeaStore } = require('./idea.js')
24
+ const { loadEnvConfig, providerConfigured } = require('./env/config.js')
25
+ const { describeBaseBranch, baseRemote } = require('./env/resolve.js')
26
+ const { primaryAnchor } = require('./env/project.js')
27
+
28
+ const USAGE =
29
+ 'Usage: skitterspec idea add <text> | list [--count] | drop <id> [--reason <why>] [--json] [--dir <path>]\n'
30
+
31
+ function reader(cwd) {
32
+ return (argv) => {
33
+ try {
34
+ return execFileSync('git', ['-C', cwd, ...argv], { stdio: ['ignore', 'pipe', 'ignore'] })
35
+ .toString()
36
+ .trim()
37
+ } catch {
38
+ return null
39
+ }
40
+ }
41
+ }
42
+
43
+ // A mutating call: throws with git's own stderr, which is what gets relayed.
44
+ function git(cwd, argv, { input, env } = {}) {
45
+ try {
46
+ return execFileSync('git', ['-C', cwd, ...argv], {
47
+ input,
48
+ env: env || process.env,
49
+ stdio: ['pipe', 'pipe', 'pipe'],
50
+ })
51
+ .toString()
52
+ .trim()
53
+ } catch (error) {
54
+ throw new Error((error.stderr && error.stderr.toString().trim()) || error.message)
55
+ }
56
+ }
57
+
58
+ function parseArgs(argv) {
59
+ const flags = { json: false, count: false, dir: null, reason: null }
60
+ const positional = []
61
+ for (let i = 0; i < argv.length; i++) {
62
+ const a = argv[i]
63
+ if (a === '--json') flags.json = true
64
+ else if (a === '--count') flags.count = true
65
+ else if (a === '--dir') flags.dir = argv[++i]
66
+ else if (a === '--reason') flags.reason = argv[++i]
67
+ else positional.push(a)
68
+ }
69
+ return { flags, positional }
70
+ }
71
+
72
+ function localDay(now) {
73
+ const pad = (n) => String(n).padStart(2, '0')
74
+ return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`
75
+ }
76
+
77
+ /** Where the file store lives: the primary checkout, its base branch, the path. */
78
+ function fileContext(from) {
79
+ const anchor = primaryAnchor(from, reader(from))
80
+ const read = reader(anchor.root)
81
+ let config = {}
82
+ try {
83
+ config = loadEnvConfig(anchor.dir).config
84
+ } catch {
85
+ // an unreadable config resolves the base the way a missing one does
86
+ }
87
+ const { base, refused } = describeBaseBranch(config, read)
88
+ return {
89
+ anchor,
90
+ read,
91
+ base,
92
+ refused,
93
+ remote: baseRemote(config),
94
+ rel: anchor.prefix ? `${anchor.prefix}/${IDEAS_FILE}` : IDEAS_FILE,
95
+ }
96
+ }
97
+
98
+ /** The file as the base branch holds it — `''` when it is not there yet. */
99
+ function readOnBase(ctx) {
100
+ const tip = ctx.read(['rev-parse', '--verify', '--quiet', `refs/heads/${ctx.base}^{commit}`])
101
+ if (!tip) return { tip: null, text: null }
102
+ return { tip, text: ctx.read(['show', `${tip}:${ctx.rel}`]) || '' }
103
+ }
104
+
105
+ /** The worktree that has `branch` checked out, else null. */
106
+ function checkedOutAt(ctx, branch) {
107
+ const out = ctx.read(['worktree', 'list', '--porcelain']) || ''
108
+ let at = null
109
+ for (const line of out.split('\n')) {
110
+ if (line.startsWith('worktree ')) at = line.slice('worktree '.length)
111
+ else if (line === `branch refs/heads/${branch}`) return at
112
+ }
113
+ return null
114
+ }
115
+
116
+ /** Commit `content` at `rel` on top of `tip`, then fast-forward the base to it. */
117
+ function landOnBase(ctx, tip, content, message) {
118
+ const root = ctx.anchor.root
119
+ const index = path.join(os.tmpdir(), `skitterspec-idea-${process.pid}-${Date.now()}.index`)
120
+ const env = { ...process.env, GIT_INDEX_FILE: index }
121
+ let commit
122
+ try {
123
+ git(root, ['read-tree', tip], { env })
124
+ const blob = git(root, ['hash-object', '-w', '--stdin'], { input: content })
125
+ git(root, ['update-index', '--add', '--cacheinfo', `100644,${blob},${ctx.rel}`], { env })
126
+ const tree = git(root, ['write-tree'], { env })
127
+ commit = git(root, ['commit-tree', tree, '-p', tip, '-F', '-'], { input: message })
128
+ } finally {
129
+ fs.rmSync(index, { force: true })
130
+ }
131
+
132
+ const at = checkedOutAt(ctx, ctx.base)
133
+ if (at) {
134
+ // Its working tree must follow the ref, so the move happens there — and a
135
+ // local edit to the file is someone's work, which a fast-forward would
136
+ // either refuse over or carry; refuse first, with the reason in words.
137
+ const dirty = reader(at)(['status', '--porcelain', '--', ctx.rel])
138
+ if (dirty) throw new Error(`${ctx.rel} has uncommitted changes in ${at} — commit or discard them first`)
139
+ git(at, ['merge', '--ff-only', '--quiet', commit])
140
+ } else {
141
+ git(root, ['update-ref', '-m', 'skitterspec idea', `refs/heads/${ctx.base}`, commit, tip])
142
+ }
143
+ return commit
144
+ }
145
+
146
+ function write(out, flags, json, lines) {
147
+ out.write(flags.json ? JSON.stringify(json, null, 2) + '\n' : lines.join('\n') + '\n')
148
+ }
149
+
150
+ function refuse(out, flags, reason, extra = {}) {
151
+ write(out, flags, { ok: false, refused: reason, ...extra }, [`idea: ${reason}`])
152
+ return 1
153
+ }
154
+
155
+ async function fileStore(sub, positional, flags, { cwd, now, out }) {
156
+ const ctx = fileContext(cwd)
157
+ if (!ctx.base) return refuse(out, flags, ctx.refused ? ctx.refused.message : 'cannot resolve the base branch')
158
+ const { tip, text } = readOnBase(ctx)
159
+
160
+ if (sub === 'list') {
161
+ const ideas = tip ? parseIdeas(text).entries : []
162
+ if (flags.count) {
163
+ write(out, flags, { store: 'file', count: ideas.length }, [String(ideas.length)])
164
+ return 0
165
+ }
166
+ const lines = ideas.length
167
+ ? [`ideas on ${ctx.base} (${ctx.rel}):`, ...ideas.map((e) => ` ${e.id.padEnd(30)} ${e.date} ${e.title}`)]
168
+ : [`idea: nothing waiting on ${ctx.base}`]
169
+ write(out, flags, { store: 'file', base: ctx.base, file: ctx.rel, ideas }, lines)
170
+ return 0
171
+ }
172
+
173
+ if (!tip) return refuse(out, flags, `the base branch ${ctx.base} has no commits here`)
174
+
175
+ const plan =
176
+ sub === 'add'
177
+ ? planAdd(text, {
178
+ text: positional.join(' '),
179
+ author: ctx.read(['config', 'user.name']),
180
+ date: localDay(now),
181
+ })
182
+ : planDrop(text, { id: positional[0], reason: flags.reason })
183
+ if (plan.refused) return refuse(out, flags, plan.refused, sub === 'add' ? { text: positional.join(' ') } : {})
184
+
185
+ let commit
186
+ try {
187
+ commit = landOnBase(ctx, tip, plan.content, plan.message)
188
+ } catch (error) {
189
+ return refuse(out, flags, `nothing landed — ${error.message}`, sub === 'add' ? { text: positional.join(' ') } : {})
190
+ }
191
+ const push = `git push ${ctx.remote} ${ctx.base}`
192
+ const verb = sub === 'add' ? 'added' : 'dropped'
193
+ write(
194
+ out,
195
+ flags,
196
+ { ok: true, store: 'file', action: sub, id: plan.id, title: plan.entry.title, base: ctx.base, commit, file: ctx.rel, push },
197
+ [
198
+ `idea: ${verb} "${plan.id}" ${sub === 'add' ? 'to' : 'from'} ${ctx.rel} on ${ctx.base} (${commit.slice(0, 7)})`,
199
+ ` title: ${plan.entry.title}`,
200
+ ` pushed: no — ${push} publishes it`,
201
+ ],
202
+ )
203
+ return 0
204
+ }
205
+
206
+ /**
207
+ * Entry point. Resolves to an exit code: 0 for an answer, 1 for a refusal —
208
+ * which for `add` carries the text back, so a refused capture loses nothing.
209
+ */
210
+ async function ideaCommand(argv, { cwd = process.cwd(), now = new Date(), out = process.stdout } = {}) {
211
+ const [sub, ...rest] = argv
212
+ const { flags, positional } = parseArgs(rest)
213
+ const from = path.resolve(flags.dir || cwd)
214
+ if (!['add', 'list', 'drop'].includes(sub)) {
215
+ out.write(USAGE)
216
+ return sub ? 1 : 0
217
+ }
218
+ if (sub === 'add' && !positional.join(' ').trim()) return refuse(out, flags, 'nothing to capture — give the idea some text')
219
+ if (sub === 'drop' && !positional[0]) return refuse(out, flags, 'name the idea to drop — `skitterspec idea list` shows them')
220
+
221
+ const anchor = primaryAnchor(from, reader(from))
222
+ const store = getProviderIdeaStore()
223
+ const where = selectStore({ providerConfigured: providerConfigured(anchor.dir), store })
224
+ if (where === 'provider') return store.run(sub, rest, { cwd: from, out })
225
+ if (where === 'unknown') {
226
+ if (sub === 'list') {
227
+ write(out, flags, { store: 'unknown', count: null }, ['idea: cannot tell where ideas live — the configured provider declares no idea store'])
228
+ return 0
229
+ }
230
+ const text = positional.join(' ')
231
+ return refuse(
232
+ out,
233
+ flags,
234
+ 'cannot tell where ideas live — the configured provider declares no idea store; nothing was written' +
235
+ (sub === 'add' ? `\n your idea, so nothing is lost:\n ${text.replace(/\n/g, '\n ')}` : ''),
236
+ sub === 'add' ? { text } : {},
237
+ )
238
+ }
239
+ return fileStore(sub, positional, flags, { cwd: from, now, out })
240
+ }
241
+
242
+ module.exports = { ideaCommand, USAGE }
package/src/tada/todo.js CHANGED
@@ -179,13 +179,17 @@ function buildTodo({ leftOff, leftOffDay, today, home = null, blockersFor = () =
179
179
  const e = entry({ ...home, here: true })
180
180
  for (const g of home.groups) if (g.inFlight) e.groups.push({ spec: g.spec, branch: null, left: null, prompt: null, inFlight: g.inFlight })
181
181
  }
182
+ // Ideas are counted for home only: the count is this project's to act on,
183
+ // and asking every project's tracker would turn a morning read into a crawl.
184
+ // Null — could not ask — and zero both print nothing.
185
+ if (home && home.ideas > 0) projects.get(keyOf(home)).ideas = home.ideas
182
186
 
183
187
  const list = [...projects.values()]
184
188
  .map((e) => {
185
189
  const specs = e.groups.filter((g) => g.spec && g.inFlight).map((g) => g.spec)
186
190
  return { ...e, blocked: e.repo && specs.length ? blockersFor(e.repo, specs) : [] }
187
191
  })
188
- .filter((e) => e.groups.length || e.finished.length || e.today.commits || e.today.moves)
192
+ .filter((e) => e.groups.length || e.finished.length || e.today.commits || e.today.moves || e.ideas)
189
193
  // The home project first: it is the one this session acts on.
190
194
  .sort((a, b) => (a.here !== b.here ? (a.here ? -1 : 1) : a.name.localeCompare(b.name)))
191
195
 
@@ -233,6 +237,7 @@ function formatTodo(todo, now = new Date()) {
233
237
  }
234
238
  if (p.finished.length) out.push(` finished: ${p.finished.join(', ')}`)
235
239
  for (const b of p.blocked) out.push(` blocked: ${blockedText(b, now)}`)
240
+ if (p.ideas) out.push(` ideas: ${p.ideas} waiting · /spec-idea lists them`)
236
241
  if (p.today.commits || p.today.moves) {
237
242
  const parts = [p.today.commits && `${p.today.commits} commit${p.today.commits === 1 ? '' : 's'}`, p.today.moves && `${p.today.moves} move${p.today.moves === 1 ? '' : 's'}`]
238
243
  out.push(` today: ${parts.filter(Boolean).join(', ')}`)
@@ -318,10 +318,15 @@ function specSyncPlan(dir, config, specArg, flags, out, err) {
318
318
  }
319
319
 
320
320
  async function specSyncApply(dir, config, specArg, flags, out, err) {
321
- if (!flags.plan && !flags.all) {
321
+ if (!flags.plan && !flags.all && !flags.sendHeld) {
322
322
  out.write(`${PROGRAM} apply: pass --plan <file> (from \`plan --json\`), or --all <bucket>\n`)
323
323
  return 1
324
324
  }
325
+ const held = kit.heldFlags(flags, PROGRAM)
326
+ if (held.error) {
327
+ out.write(held.error + '\n')
328
+ return 1
329
+ }
325
330
  const cred = apiAdapterFor(config, flags)
326
331
  const transport = kit.resolveTransport(flags, config, cred.ok)
327
332
  if (transport === 'mcp') {
@@ -335,6 +340,8 @@ async function specSyncApply(dir, config, specArg, flags, out, err) {
335
340
  ' editJiraIssue / transitionJiraIssue), then stamp the returned keys\n' +
336
341
  ' with `spec-sync stamp` and record with `spec-sync record`.\n',
337
342
  )
343
+ const heldNote = kit.heldOverMcp(held, PROGRAM)
344
+ if (heldNote) out.write(heldNote + '\n')
338
345
  return 0
339
346
  }
340
347
  if (!cred.ok) {
@@ -351,6 +358,8 @@ async function specSyncApply(dir, config, specArg, flags, out, err) {
351
358
  adapter: cred.adapter,
352
359
  ops: applyOps({ adapter: cred.adapter, config, kind: specKindOf(snapshotDir), snapshotDir, out }),
353
360
  forceNew: !!flags.forceNew,
361
+ holdState: held.holdState,
362
+ sendHeld: held.sendHeld,
354
363
  program: PROGRAM,
355
364
  })
356
365
 
@@ -386,13 +395,19 @@ async function specSyncApply(dir, config, specArg, flags, out, err) {
386
395
  const snapshotDir = resolveOrExit(specArg, dir, out)
387
396
  if (!snapshotDir) return 1
388
397
  let plan
389
- try {
390
- plan = JSON.parse(fs.readFileSync(flags.plan, 'utf-8'))
391
- } catch (error) {
392
- out.write(`${PROGRAM} apply: cannot read --plan: ${error.message}\n`)
393
- return 1
398
+ if (!flags.plan) {
399
+ // --send-held computes its own. After the merge it is normally empty, and
400
+ // that empty plan is what tells apply that run 1 held the state.
401
+ plan = push({ dir, snapshotDir, identifier: specIdentifier(snapshotDir, config), config }).plan
402
+ } else {
403
+ try {
404
+ plan = JSON.parse(fs.readFileSync(flags.plan, 'utf-8'))
405
+ } catch (error) {
406
+ out.write(`${PROGRAM} apply: cannot read --plan: ${error.message}\n`)
407
+ return 1
408
+ }
394
409
  }
395
- if (isEmptyPlan(plan)) {
410
+ if (!held.sendHeld && isEmptyPlan(plan)) {
396
411
  out.write(`${PROGRAM} apply: empty plan — nothing to do\n`)
397
412
  return 0
398
413
  }
@@ -477,10 +492,13 @@ async function specSyncStamp(dir, config, specArg, flags, out) {
477
492
  return 0
478
493
  }
479
494
 
480
- function specSyncRecord(dir, config, specArg, out) {
495
+ function specSyncRecord(dir, config, specArg, flags, out) {
481
496
  const snapshotDir = resolveOrExit(specArg, dir, out)
482
497
  if (!snapshotDir) return 1
483
- const file = recordPush({ dir, snapshotDir, identifier: specIdentifier(snapshotDir, config), config })
498
+ // --held: the hand-applied twin of `apply --hold-state` — the state was left
499
+ // out on purpose, and is recorded as sent so run 2 rewrites nothing.
500
+ const sent = flags && flags.held ? { issue: true, subIssues: new Set() } : null
501
+ const file = recordPush({ dir, snapshotDir, identifier: specIdentifier(snapshotDir, config), config, sent })
484
502
  out.write(`${PROGRAM} record: snapshot written — ${path.relative(dir, file).split(path.sep).join('/')}\n`)
485
503
  return 0
486
504
  }
@@ -1307,8 +1325,9 @@ const USAGE = `Usage: skitterspec-jira spec-sync <subcommand>
1307
1325
  normalize <spec> print the local projection as JSON
1308
1326
  plan <spec> --workspace-states <f> what a push would change (dry, JSON)
1309
1327
  apply <spec> --plan <f> | --all <b> apply a plan over the API
1328
+ apply <spec> --hold-state | --send-held PR-mode completion: hold Done for run 2, then send it
1310
1329
  stamp <spec> --issue KEY [--sub r=K] write returned keys into the spec
1311
- record <spec> write the last-pushed snapshot
1330
+ record <spec> [--held] write the last-pushed snapshot
1312
1331
  status <spec> [--remote <f>] read-only drift report
1313
1332
  verify <spec> --stored <f> compare a read-back against the repo
1314
1333
  splice <spec> --live <f> [--phase <ref>] the body to write over MCP (summary mode)
@@ -1382,7 +1401,7 @@ async function specSync(rest, io = {}) {
1382
1401
  case 'stamp':
1383
1402
  return specSyncStamp(dir, config, positional[0], flags, out)
1384
1403
  case 'record':
1385
- return specSyncRecord(dir, config, positional[0], out)
1404
+ return specSyncRecord(dir, config, positional[0], flags, out)
1386
1405
  case 'status':
1387
1406
  return specSyncStatus(dir, config, positional[0], flags, out, err)
1388
1407
  case 'splice': {
@@ -1447,6 +1466,9 @@ function parseArgs(args, sub) {
1447
1466
  '--via': { kind: 'string' },
1448
1467
  '--force': { kind: 'boolean' },
1449
1468
  '--force-new': { kind: 'boolean', name: 'forceNew' },
1469
+ '--hold-state': { kind: 'boolean', name: 'holdState' },
1470
+ '--send-held': { kind: 'boolean', name: 'sendHeld' },
1471
+ '--held': { kind: 'boolean' },
1450
1472
  '--issue': { kind: 'string' },
1451
1473
  '--url': { kind: 'value' },
1452
1474
  '--sub': { kind: 'list', name: 'subs' },
@@ -52,6 +52,7 @@ const path = require('node:path')
52
52
  const {
53
53
  readSnapshot,
54
54
  readBase,
55
+ isEmptyPlan,
55
56
  projectionOf,
56
57
  recordPush,
57
58
  writeFrontmatter,
@@ -85,16 +86,58 @@ async function applySpecPlan(args) {
85
86
  }
86
87
  }
87
88
 
88
- async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progress, forceNew = false, program = 'spec-sync' }) {
89
+ async function applyInner({
90
+ dir,
91
+ config,
92
+ snapshotDir,
93
+ plan,
94
+ adapter,
95
+ ops,
96
+ progress,
97
+ forceNew = false,
98
+ holdState = false,
99
+ sendHeld = false,
100
+ program = 'spec-sync',
101
+ }) {
89
102
  const fields = fieldsOf(config)
90
103
  const helpers = makeSpecHelpers({ program })
91
104
  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
92
105
  const identifier = helpers.linkedIdentifier(path.join(snapshotDir, overviewFile), config)
93
106
  const lines = []
94
107
  const result = { issue: null, subIssues: {} }
108
+
109
+ // PR-MODE COMPLETION, `branch` lane (spec bug-pr-complete-snapshot-on-base).
110
+ // Run 1 commits the move to ride the PR, but the Done waits for the merge —
111
+ // and run 2 sends it from the base branch, where no spec branch is left to
112
+ // commit a snapshot to. So run 1 HOLDS the state yet records it as sent, and
113
+ // run 2 SENDS only that state: the snapshot it records is byte-identical to
114
+ // the one the merge brought, and the base branch stays clean.
115
+ if (holdState && sendHeld) throw new Error(`${program} apply: --hold-state and --send-held are two runs, not one`)
116
+ if ((holdState || sendHeld) && !identifier) {
117
+ throw new Error(`${program} apply: an unlinked spec has no transition to hold — push it plainly`)
118
+ }
119
+ let heldState = false
120
+ let fellBack = false
121
+ if (holdState && plan.issue && plan.issue.state != null) {
122
+ const { state, stateResend, ...rest } = plan.issue
123
+ plan = { ...plan, issue: Object.keys(rest).length ? rest : undefined }
124
+ heldState = state
125
+ } else if (sendHeld) {
126
+ // A NON-EMPTY PLAN MEANS RUN 1 HELD NOTHING — it predates the hold, so the
127
+ // whole completion is still unsent. Sending the state alone would strand
128
+ // the rest; apply it all, as before, and say which file that leaves dirty.
129
+ if (isEmptyPlan(plan)) {
130
+ const status = projectionOf(snapshotDir, config).status
131
+ if (status != null) plan = { ...plan, issue: { state: status } }
132
+ } else {
133
+ fellBack = true
134
+ }
135
+ }
136
+
95
137
  // Which items this apply carried a state for — the snapshot records today's
96
- // state name for these and only these (`recordPush`).
97
- const sent = { issue: !!(plan.issue && plan.issue.state != null), subIssues: new Set() }
138
+ // state name for these and only these (`recordPush`). A held state counts:
139
+ // run 2 sends it, and what run 2 records has to match what run 1 committed.
140
+ const sent = { issue: !!heldState || !!(plan.issue && plan.issue.state != null), subIssues: new Set() }
98
141
  // Handed out immediately, so a throw from anywhere below still reports what
99
142
  // had been stamped by the time it happened.
100
143
  if (progress) progress.result = result
@@ -268,7 +311,12 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
268
311
  const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent, keepSubIssues })
269
312
  // A repo path, `/`-separated on every platform — the form every other
270
313
  // spec path in this output takes.
271
- lines.push(` snapshot: ${path.relative(dir, file).split(path.sep).join('/')}`)
314
+ const snapshotPath = path.relative(dir, file).split(path.sep).join('/')
315
+ lines.push(` snapshot: ${snapshotPath}`)
316
+ if (heldState) lines.push(` state held: ${identifier} → ${heldState} waits for the merge — run 2 sends it with --send-held`)
317
+ if (fellBack) {
318
+ lines.push(` !! nothing was held for ${identifier} — sent the whole plan; ${snapshotPath} now differs from the merged copy`)
319
+ }
272
320
  return { result, lines, lost }
273
321
  }
274
322
 
@@ -304,4 +352,41 @@ function resolvePhaseFileIn(snapshotDir, ref) {
304
352
  return listPhaseFiles(snapshotDir).find((f) => f.replace(/\.md$/, '') === want) || null
305
353
  }
306
354
 
307
- module.exports = { applySpecPlan }
355
+ /**
356
+ * `--hold-state` / `--send-held` as every provider's `apply` reads them: one
357
+ * spec, one of the two, never both. Returns `{ holdState, sendHeld }`, or
358
+ * `{ error }` for the provider to print and exit 1 on.
359
+ */
360
+ function heldFlags(flags, program) {
361
+ const holdState = !!(flags && flags.holdState)
362
+ const sendHeld = !!(flags && flags.sendHeld)
363
+ if (holdState && sendHeld) return { error: `${program} apply: --hold-state and --send-held are two runs, not one` }
364
+ if ((holdState || sendHeld) && flags.all != null) {
365
+ return { error: `${program} apply --all: --hold-state and --send-held act on one spec at a time` }
366
+ }
367
+ return { holdState, sendHeld }
368
+ }
369
+
370
+ /**
371
+ * What the MCP transport adds to its "nothing written" note, so the hand-applied
372
+ * push ends with the same snapshot the API path would record. Null when neither
373
+ * flag is set.
374
+ */
375
+ function heldOverMcp({ holdState, sendHeld }, program) {
376
+ if (holdState) {
377
+ return (
378
+ " --hold-state: apply the plan WITHOUT the spec issue's state, then record with\n" +
379
+ ` \`${program} record <spec> --held\` — run 2 sends the state after the merge.`
380
+ )
381
+ }
382
+ if (sendHeld) {
383
+ return (
384
+ " --send-held: if `plan` is empty, send the spec issue's state alone and record\n" +
385
+ ' nothing — the merged snapshot already says it. If it is not, run 1 held\n' +
386
+ ' nothing: apply it whole and record as usual.'
387
+ )
388
+ }
389
+ return null
390
+ }
391
+
392
+ module.exports = { applySpecPlan, heldFlags, heldOverMcp }