mandrel 2.76.0 → 2.77.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.
@@ -17,8 +17,14 @@ import { upsertStructuredComment } from '../ticketing.js';
17
17
 
18
18
  const SUPERSEDED_BY_COMMENT_TYPE = 'superseded-by';
19
19
 
20
- /** Nothing has shipped at persist time, so `not_planned`, not `completed`. */
21
- export const SUPERSEDE_CLOSE_REASON = 'not_planned';
20
+ /**
21
+ * The claiming Story carries the work, so `duplicate`: nothing has shipped
22
+ * (not `completed`), but the ticket is not abandoned either.
23
+ */
24
+ export const SUPERSEDE_CLOSE_REASON = 'duplicate';
25
+
26
+ /** Retried once when the provider refuses `duplicate`. */
27
+ const SUPERSEDE_FALLBACK_CLOSE_REASON = 'not_planned';
22
28
 
23
29
  /**
24
30
  * Stripped, not rewritten to `agent::done`: a retired ticket has no agent
@@ -33,8 +39,8 @@ const AGENT_STATE_LABELS = Object.freeze(Object.values(AGENT_LABELS));
33
39
  * @param {{ labels?: unknown }} ticket The probe's fresh copy.
34
40
  * @returns {object} Mutations for `provider.updateTicket`.
35
41
  */
36
- function supersedeCloseMutations(ticket) {
37
- const close = { state: 'closed', state_reason: SUPERSEDE_CLOSE_REASON };
42
+ function supersedeCloseMutations(ticket, reason = SUPERSEDE_CLOSE_REASON) {
43
+ const close = { state: 'closed', state_reason: reason };
38
44
  const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
39
45
  const remove = AGENT_STATE_LABELS.filter((label) => labels.includes(label));
40
46
  if (remove.length === 0) return close;
@@ -288,6 +294,28 @@ export function buildSupersedeCommentBody({
288
294
  return lines.join('\n');
289
295
  }
290
296
 
297
+ /**
298
+ * Close as `duplicate`; on refusal, retry once as `not_planned` so a
299
+ * supersede never fails on the reason alone.
300
+ *
301
+ * @returns {Promise<void>}
302
+ */
303
+ async function closeSupersededSource(provider, id, ticket) {
304
+ try {
305
+ await provider.updateTicket(id, supersedeCloseMutations(ticket));
306
+ } catch (err) {
307
+ Logger.warn(
308
+ `[plan-persist] closing #${id} as ${SUPERSEDE_CLOSE_REASON} was ` +
309
+ `refused (${err.message}) — retrying as ` +
310
+ `${SUPERSEDE_FALLBACK_CLOSE_REASON}.`,
311
+ );
312
+ await provider.updateTicket(
313
+ id,
314
+ supersedeCloseMutations(ticket, SUPERSEDE_FALLBACK_CLOSE_REASON),
315
+ );
316
+ }
317
+ }
318
+
291
319
  /**
292
320
  * The ticket rides along so the close needs no second read.
293
321
  *
@@ -335,8 +363,9 @@ async function closeOneSupersededTicket({
335
363
  note,
336
364
  sourceTicketIds,
337
365
  }),
366
+ { story: story.id },
338
367
  );
339
- await provider.updateTicket(id, supersedeCloseMutations(probe.ticket));
368
+ await closeSupersededSource(provider, id, probe.ticket);
340
369
  return { outcome: 'closed' };
341
370
  } catch (err) {
342
371
  return { outcome: 'failed', reason: err.message };
@@ -148,10 +148,14 @@ function noopResult(storyId, reason) {
148
148
  return { storyId, standalone: true, action: 'noop', reason };
149
149
  }
150
150
 
151
+ /** Close reasons meaning nothing merged — superseded or abandoned. */
152
+ const UNLANDED_CLOSE_REASONS = new Set(['not_planned', 'duplicate']);
153
+
151
154
  /**
152
- * Terminal for an already-closed Story. `not_planned` means nothing merged,
153
- * so it fails rather than reporting `landed` (which would also unblock
154
- * dependents); `completed` or null (GitHub's default) reads as landed.
155
+ * Terminal for an already-closed Story. `not_planned` / `duplicate` mean
156
+ * nothing merged, so it fails rather than reporting `landed` (which would
157
+ * also unblock dependents); `completed` or null (GitHub's default) reads as
158
+ * landed.
155
159
  */
156
160
  async function alreadyClosedResult(
157
161
  storyId,
@@ -159,7 +163,7 @@ async function alreadyClosedResult(
159
163
  config,
160
164
  worker = NO_WORKER,
161
165
  ) {
162
- if (stateReason === 'not_planned') {
166
+ if (UNLANDED_CLOSE_REASONS.has(stateReason)) {
163
167
  progress(
164
168
  'NOOP',
165
169
  `Story #${storyId} is closed as not planned — nothing to land.`,
@@ -550,9 +550,16 @@ fail-closes: a `--tickets` run whose Stories forgot `supersedes[]` is
550
550
 
551
551
  **Default on.** After the Stories exist, persist comments on each source
552
552
  issue naming the specific Story that claims it — plus that Story's optional
553
- per-supersede `note` — and closes it with reason **`not_planned`**
554
- (`state_reason`) — nothing has shipped at persist time, so `completed` would
555
- be a lie.
553
+ per-supersede `note` — and closes it with reason **`duplicate`**
554
+ (`state_reason`): the claiming Story carries the work, and nothing has
555
+ shipped at persist time, so `completed` would be a lie. A provider that
556
+ refuses `duplicate` gets one logged retry as `not_planned`.
557
+
558
+ The comment opens with
559
+ `<!-- ap:structured-comment type="superseded-by" story="<id>" -->`, `<id>`
560
+ the claiming Story's issue number. That marker is a **stable consumer
561
+ contract** — tooling mirroring issue state may follow it to the successor —
562
+ and will not change shape without a CHANGELOG `BREAKING CHANGE`.
556
563
 
557
564
  The default also **clears the source's `agent::*` label** in the same write — a
558
565
  retired ticket has no agent state. Pass **`--no-close-superseded`** for a
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.77.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.76.0...mandrel-v2.77.0) (2026-10-08)
19
+
20
+
21
+ ### Added
22
+
23
+ * plan-persist: name the claiming Story in the superseded-by marker and close superseded tickets as duplicate ([#5565](https://github.com/dsj1984/mandrel/issues/5565)) ([#5566](https://github.com/dsj1984/mandrel/issues/5566)) ([941fc0a](https://github.com/dsj1984/mandrel/commit/941fc0a340d7ffa5b605db48ba6a60a8172c0b5e))
24
+
18
25
  ## [2.76.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.75.0...mandrel-v2.76.0) (2026-10-07)
19
26
 
20
27
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.76.0",
3
+ "version": "2.77.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",