mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/orchestration/story-progress/story-run-progress-writer.js

@@ -1,400 +0,0 @@
-/**
- * story-run-progress-writer — render the per-story progress snapshot.
- *
- * Story #3909 — this module no longer **posts** a `story-run-progress`
- * structured comment. That per-Story comment was the redundant mid-flight
- * progress surface: an Epic run already keeps the operator-facing
- * `epic-run-progress` rollup (one comment on the Epic) plus the
- * `epic-run-state` checkpoint and the lifecycle ledger, and the rollup is
- * rendered from the checkpoint `waves[]` — it never read the per-Story
- * comment. The per-Story comment fired at five phase transitions each and
- * duplicated state already on the labels + ledger, so the comment write was
- * removed.
- *
- * The renderer survives because its `{ body, payload }` output still feeds
- * two non-comment contracts: the `renderedBody` markdown the `/deliver`
- * workflow (`helpers/deliver-story.md`, `story-phase.js`) relays to chat so
- * the operator sees the phase table inline, and the snapshot payload returned
- * in those CLIs' JSON envelopes. `upsertStoryRunProgress`
- * therefore renders-only: it computes the body/payload and (optionally) mirrors
- * a low-severity webhook event, but writes no GitHub comment.
- *
- * Payload shape — per tech spec #902 (kept stable; the CLI envelopes carry it
- * verbatim):
- *
- *   {
- *     "kind": "story-run-progress",
- *     "storyId": <number>,
- *     "branch": "story-<id>",
- *     "phase": "init|implementing|closing|blocked|done",
- *     "tasks": [
- *       { "id": <n>, "title": "...", "state": "done", "commitSha": "abc1234" },
- *       { "id": <n>, "title": "...", "state": "executing" },
- *       { "id": <n>, "title": "...", "state": "pending" }
- *     ],
- *     "updatedAt": "<iso8601>"
- *   }
- */
-
-export const STORY_RUN_PROGRESS_TYPE = 'story-run-progress';
-
-const VALID_TASK_STATES = new Set([
-  'pending',
-  'executing',
-  'done',
-  'blocked',
-  'failed',
-]);
-
-const VALID_PHASES = new Set([
-  'init',
-  'implementing',
-  'closing',
-  'blocked',
-  'done',
-]);
-
-const TASK_STATE_EMOJI = {
-  pending: '⏳',
-  executing: '🔧',
-  done: '✅',
-  blocked: '🚧',
-  failed: '❌',
-};
-
-const PHASE_EMOJI = {
-  init: '🌱',
-  implementing: '🔧',
-  closing: '🔒',
-  blocked: '🚧',
-  done: '✅',
-};
-
-/**
- * Canonical 2-tier Story-phase order. The Story-phase snapshot replaces the
- * 4-tier per-Task list when the Story carries inline acceptance (no child
- * Tasks). Each entry tracks `status` + `startedAt` / `endedAt` so the parent
- * `/deliver` aggregator can render a coarse progress bar without
- * walking Task tickets.
- */
-export const STORY_PHASE_ORDER = ['init', 'implement', 'validate', 'close'];
-
-const VALID_STORY_PHASE_STATUS = new Set(['pending', 'in-progress', 'done']);
-
-const STORY_PHASE_STATUS_EMOJI = {
-  pending: '⏳',
-  'in-progress': '🔧',
-  done: '✅',
-};
-
-/**
- * Build the canonical default `phases[]` array for a freshly-initialized
- * 2-tier Story snapshot. All entries are `pending`; timestamps are null.
- * Exported so call sites (the story-init prepare step, story-phase) and
- * tests can build the same shape without re-implementing it.
- *
- * @returns {Array<{ name: string, status: 'pending', startedAt: null, endedAt: null }>}
- */
-export function defaultStoryPhases() {
-  return STORY_PHASE_ORDER.map((name) => ({
-    name,
-    status: 'pending',
-    startedAt: null,
-    endedAt: null,
-  }));
-}
-
-/**
- * Normalize one Story-phase row into the canonical schema. Timestamps may be
- * `null` (phase not yet started) or ISO-8601 strings; status is one of
- * pending | in-progress | done.
- *
- * @param {object} phase
- * @returns {object}
- */
-function normalizeStoryPhase(phase) {
-  if (!phase || typeof phase !== 'object') {
-    throw new TypeError('story-run-progress phase rows must be objects');
-  }
-  const name = String(phase.name ?? '');
-  if (!STORY_PHASE_ORDER.includes(name)) {
-    throw new RangeError(
-      `story-run-progress invalid phase name "${name}"; ` +
-        `expected one of: ${STORY_PHASE_ORDER.join(', ')}`,
-    );
-  }
-  const status = String(phase.status ?? 'pending');
-  if (!VALID_STORY_PHASE_STATUS.has(status)) {
-    throw new RangeError(
-      `story-run-progress invalid phase status "${status}" for "${name}"; ` +
-        `expected one of: ${[...VALID_STORY_PHASE_STATUS].join(', ')}`,
-    );
-  }
-  return {
-    name,
-    status,
-    startedAt: phase.startedAt == null ? null : String(phase.startedAt),
-    endedAt: phase.endedAt == null ? null : String(phase.endedAt),
-  };
-}
-
-/**
- * Normalize one Task row into the canonical schema. `commitSha` is only
- * carried on `done` rows (it has no meaning before the commit lands and is
- * cleared on rollback).
- *
- * @param {object} task
- * @returns {object}
- */
-function normalizeTask(task) {
-  if (!task || typeof task !== 'object') {
-    throw new TypeError('story-run-progress task rows must be objects');
-  }
-  const id = Number(task.id ?? task.taskId);
-  if (!Number.isInteger(id) || id <= 0) {
-    throw new TypeError(
-      `story-run-progress task row missing valid id: ${JSON.stringify(task)}`,
-    );
-  }
-  const state = String(task.state ?? 'pending');
-  if (!VALID_TASK_STATES.has(state)) {
-    throw new RangeError(
-      `story-run-progress invalid task state "${state}" for task #${id}; ` +
-        `expected one of: ${[...VALID_TASK_STATES].join(', ')}`,
-    );
-  }
-  const row = { id, title: String(task.title ?? ''), state };
-  if (state === 'done' && task.commitSha != null) {
-    row.commitSha = String(task.commitSha);
-  }
-  return row;
-}
-
-/**
- * Build the markdown body the writer upserts. Pure: no IO, no provider call.
- * Exported so tests can pin the rendered shape without going through the
- * upsert path.
- *
- * Two shapes are supported, selected by whether `input.phases` (2-tier
- * Story-phase snapshot) or `input.tasks` (legacy 4-tier per-Task list) is
- * provided. Callers MUST pass exactly one of the two — passing both is
- * rejected as a contract violation so a mistake at the call site fails
- * loudly rather than silently dropping one shape.
- *
- * @param {{
- *   storyId: number,
- *   branch: string,
- *   phase: string,
- *   tasks?: object[],
- *   phases?: object[],
- *   updatedAt?: string,
- * }} input
- * @returns {{ body: string, payload: object }}
- */
-export function renderStoryRunProgressBody(input) {
-  const storyId = Number(input?.storyId);
-  if (!Number.isInteger(storyId) || storyId <= 0) {
-    throw new TypeError(
-      'renderStoryRunProgressBody requires a numeric storyId',
-    );
-  }
-  const branch = String(input?.branch ?? '');
-  if (!branch) {
-    throw new TypeError(
-      'renderStoryRunProgressBody requires a non-empty branch',
-    );
-  }
-  const phase = String(input?.phase ?? '');
-  if (!VALID_PHASES.has(phase)) {
-    throw new RangeError(
-      `renderStoryRunProgressBody invalid phase "${phase}"; ` +
-        `expected one of: ${[...VALID_PHASES].join(', ')}`,
-    );
-  }
-
-  const hasPhases = Array.isArray(input.phases);
-  const hasTasks = Array.isArray(input.tasks);
-  if (hasPhases && hasTasks) {
-    throw new TypeError(
-      'renderStoryRunProgressBody: pass either `phases` (2-tier) or `tasks` ' +
-        '(4-tier), not both — the snapshot shape is mutually exclusive.',
-    );
-  }
-
-  const updatedAt = input.updatedAt ?? new Date().toISOString();
-
-  if (hasPhases) {
-    return renderPhasesBody({
-      storyId,
-      branch,
-      phase,
-      phases: input.phases,
-      updatedAt,
-    });
-  }
-  return renderTasksBody({
-    storyId,
-    branch,
-    phase,
-    tasks: input.tasks ?? [],
-    updatedAt,
-  });
-}
-
-/**
- * Render the 4-tier per-Task body. Pure helper for `renderStoryRunProgressBody`.
- */
-function renderTasksBody({
-  storyId,
-  branch,
-  phase,
-  tasks: rawTasks,
-  updatedAt,
-}) {
-  const tasks = rawTasks.map(normalizeTask);
-  const payload = {
-    kind: STORY_RUN_PROGRESS_TYPE,
-    storyId,
-    branch,
-    phase,
-    tasks,
-    updatedAt,
-  };
-
-  const done = tasks.filter((t) => t.state === 'done').length;
-  const total = tasks.length;
-  const phaseEmoji = PHASE_EMOJI[phase] ?? '';
-  const header = `### 📖 Story #${storyId} — ${phaseEmoji} ${phase} · ${done}/${total} tasks done`;
-  const tableRows = tasks.length
-    ? [
-        '| ID | State | Title | Commit |',
-        '| --- | --- | --- | --- |',
-        ...tasks.map((t) => {
-          const emoji = TASK_STATE_EMOJI[t.state] ?? '';
-          const commit = t.commitSha
-            ? `\`${String(t.commitSha).slice(0, 7)}\``
-            : '—';
-          const title = String(t.title).replace(/\|/g, '\\|');
-          return `| #${t.id} | ${emoji} ${t.state} | ${title} | ${commit} |`;
-        }),
-      ].join('\n')
-    : '_(no tasks recorded for this story)_';
-
-  const body = [
-    header,
-    '',
-    `Branch: \`${branch}\``,
-    '',
-    tableRows,
-    '',
-    '```json',
-    JSON.stringify(payload, null, 2),
-    '```',
-  ].join('\n');
-
-  return { body, payload };
-}
-
-/**
- * Render the 2-tier Story-phase body. Pure helper for
- * `renderStoryRunProgressBody`. Emits a `phases[]` payload whose entries
- * carry `{ name, status, startedAt, endedAt }` for init/implement/validate/close.
- */
-function renderPhasesBody({ storyId, branch, phase, phases: raw, updatedAt }) {
-  const phases = raw.map(normalizeStoryPhase);
-  const payload = {
-    kind: STORY_RUN_PROGRESS_TYPE,
-    storyId,
-    branch,
-    phase,
-    phases,
-    updatedAt,
-  };
-
-  const done = phases.filter((p) => p.status === 'done').length;
-  const total = phases.length;
-  const phaseEmoji = PHASE_EMOJI[phase] ?? '';
-  const header = `### 📖 Story #${storyId} — ${phaseEmoji} ${phase} · ${done}/${total} phases done`;
-  const tableRows = phases.length
-    ? [
-        '| Phase | Status | Started | Ended |',
-        '| --- | --- | --- | --- |',
-        ...phases.map((p) => {
-          const emoji = STORY_PHASE_STATUS_EMOJI[p.status] ?? '';
-          const started = p.startedAt ?? '—';
-          const ended = p.endedAt ?? '—';
-          return `| ${p.name} | ${emoji} ${p.status} | ${started} | ${ended} |`;
-        }),
-      ].join('\n')
-    : '_(no phases recorded for this story)_';
-
-  const body = [
-    header,
-    '',
-    `Branch: \`${branch}\``,
-    '',
-    tableRows,
-    '',
-    '```json',
-    JSON.stringify(payload, null, 2),
-    '```',
-  ].join('\n');
-
-  return { body, payload };
-}
-
-/**
- * Render the story-run-progress snapshot for one phase transition and return
- * `{ body, payload }` so callers can surface the markdown body to chat and
- * carry the payload in their JSON envelope. Story #3909 — this no longer posts
- * a GitHub comment (the redundant mid-flight progress surface was deleted); it
- * renders only and, when `notify` is supplied, mirrors a low-severity webhook
- * event for operators who wire one up.
- *
- * Two shapes are supported, selected by whether `args.phases` (2-tier
- * Story-phase snapshot) or `args.tasks` (legacy 4-tier per-Task list) is
- * provided. The webhook mirror's `done/total` count is computed from whichever
- * shape is active.
- *
- * @param {{
- *   provider?: import('../../ITicketingProvider.js').ITicketingProvider,
- *   storyId: number,
- *   branch: string,
- *   phase: string,
- *   tasks?: object[],
- *   phases?: object[],
- *   epicId?: number,
- *   updatedAt?: string,
- *   notify?: Function,
- * }} args
- * @returns {Promise<{ body: string, payload: object }>}
- */
-export async function upsertStoryRunProgress(args) {
-  const { notify, epicId, provider: _provider, ...rest } = args ?? {};
-  const { body, payload } = renderStoryRunProgressBody(rest);
-  if (typeof notify === 'function') {
-    const isPhases = Array.isArray(payload.phases);
-    const items = isPhases ? payload.phases : payload.tasks;
-    const done = isPhases
-      ? items.filter((p) => p.status === 'done').length
-      : items.filter((t) => t.state === 'done').length;
-    const total = items.length;
-    const unit = isPhases ? 'phases' : 'tasks';
-    const message = `Story #${payload.storyId} · ${payload.phase} · ${done}/${total} ${unit} done`;
-    await Promise.resolve(
-      notify(
-        payload.storyId,
-        {
-          severity: 'low',
-          message,
-          event: STORY_RUN_PROGRESS_TYPE,
-          level: 'story',
-          epicId,
-          phase: payload.phase,
-        },
-        { skipComment: true },
-      ),
-    ).catch(() => {});
-  }
-  return { body, payload };
-}

package/.agents/scripts/lib/single-story/confirm-merge-follow-ups.js

@@ -1,36 +0,0 @@
-/**
- * confirm-merge-follow-ups.js — post-land follow-up capture seam for
- * `single-story-confirm-merge.js` (keeps the CLI entry under the MI ceiling).
- */
-
-import { captureFollowUpsAfterConfirm } from '../orchestration/story-follow-ups.js';
-
-/**
- * @param {object} args
- * @param {object} args.confirmation
- * @param {number} args.storyId
- * @param {number|null} args.prNumber
- * @param {object} args.provider
- * @param {object} [args.config]
- * @param {string} args.cwd
- * @param {(tag: string, msg: string) => void} [args.progress]
- * @returns {Promise<object>}
- */
-export async function withConfirmFollowUps({
-  confirmation,
-  storyId,
-  prNumber,
-  provider,
-  config,
-  cwd,
-  progress,
-}) {
-  const followUps = await captureFollowUpsAfterConfirm(confirmation, {
-    storyId,
-    provider,
-    config,
-    cwd,
-    progress,
-  });
-  return { standalone: true, prNumber, ...confirmation, followUps };
-}

package/.agents/scripts/resolve-plan-run.js

@@ -1,117 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * resolve-plan-run.js — resolve Stories labeled `plan-run::<id>` for
- * `/deliver --run <planRunId>` (v2 Stage 4).
- *
- * Thin CLI over `lib/orchestration/resolve-plan-run.js`.
- *
- * Usage:
- *   node .agents/scripts/resolve-plan-run.js --run <planRunId>
- *   node .agents/scripts/resolve-plan-run.js --run <planRunId> --state all
- *   node .agents/scripts/resolve-plan-run.js --run <planRunId> --pretty
- *
- * Exit codes: 0 ok, 1 usage/error, 2 no Stories found for the run.
- */
-
-import { parseArgs } from 'node:util';
-
-import { runAsCli } from './lib/cli-utils.js';
-import { resolveConfig } from './lib/config-resolver.js';
-import {
-  assertIssueState,
-  buildPlanRunEnvelope,
-  fetchPlanRunIssues,
-  normalizePlanRunLabel,
-  planRunIdFromLabel,
-  resolvePlanRunFromIssues,
-} from './lib/orchestration/resolve-plan-run.js';
-import { createProvider } from './lib/provider-factory.js';
-
-export {
-  buildPlanRunEnvelope,
-  fetchPlanRunIssues,
-  normalizePlanRunLabel,
-  planRunIdFromLabel,
-  resolvePlanRunFromIssues,
-};
-
-const HELP = `\
-Usage:
-  resolve-plan-run.js --run <planRunId> [--state open|all|closed] [--pretty]
-
-Resolve Stories labeled plan-run::<planRunId> for /deliver --run.
-
-Options:
-  --run <id>     Plan-run token (with or without the plan-run:: prefix).
-  --state <s>    Issue state filter (default: open).
-  --pretty       Pretty-print the JSON envelope.
-  --help         Show this help.
-`;
-
-function writeEnvelope(envelope, pretty) {
-  const text = pretty
-    ? `${JSON.stringify(envelope, null, 2)}\n`
-    : `${JSON.stringify(envelope)}\n`;
-  process.stdout.write(text);
-}
-
-/**
- * Resolve config once and pass it to the provider factory. Kept as an
- * injectable seam so the CLI contract is covered without network access.
- *
- * @param {object} [deps]
- * @param {Function} [deps.resolveConfigFn]
- * @param {Function} [deps.createProviderFn]
- * @returns {object}
- */
-export function resolvePlanRunProvider({
-  resolveConfigFn = resolveConfig,
-  createProviderFn = createProvider,
-} = {}) {
-  const config = resolveConfigFn();
-  return createProviderFn(config);
-}
-
-async function main() {
-  const { values } = parseArgs({
-    options: {
-      run: { type: 'string' },
-      state: { type: 'string', default: 'open' },
-      pretty: { type: 'boolean', default: false },
-      help: { type: 'boolean', default: false },
-    },
-    allowPositionals: false,
-  });
-
-  if (values.help) {
-    process.stdout.write(HELP);
-    return 0;
-  }
-  if (!values.run) {
-    process.stderr.write(HELP);
-    throw new Error('resolve-plan-run: --run <planRunId> is required');
-  }
-
-  const state = assertIssueState(values.state);
-  const planRunLabel = normalizePlanRunLabel(values.run);
-  const planRunId = planRunIdFromLabel(planRunLabel);
-
-  const provider = resolvePlanRunProvider();
-  const issues = await fetchPlanRunIssues(provider, { planRunLabel, state });
-  const envelope = buildPlanRunEnvelope(issues, { planRunId, planRunLabel });
-  writeEnvelope(envelope, values.pretty);
-
-  if (envelope.stories.length === 0) {
-    process.stderr.write(
-      `resolve-plan-run: no type::story issues with label ${planRunLabel} (state=${state})\n`,
-    );
-    return 2;
-  }
-  return 0;
-}
-
-runAsCli(import.meta.url, main, {
-  source: 'resolve-plan-run',
-  propagateExitCode: true,
-});

package/.agents/skills/core/analyze-execution/SKILL.md

@@ -1,101 +0,0 @@
----
-name: analyze-execution
-description: >-
-  Aggregate per-Story or per-plan-run execution signals into a structured
-  perf-summary or perf-report and upsert it onto the corresponding GitHub
-  ticket. Use after a Story closes (Story mode) or during run closeout
-  (plan-run mode). Reads NDJSON via
-  `lib/signals/read` and writes a single structured comment.
-allowed_tools:
-  - Read
-  - Bash
----
-
-# analyze-execution
-
-## Policy Capsule
-
-- Invoke via the wrapping CLI `node .agents/scripts/analyze-execution.js`; do not duplicate the read/write logic from this Skill body.
-- Resolve mode strictly by flags: Story + run id → Story mode; run id alone → plan-run mode. The current CLI still spells the run-id flag as `--epic <id>`; treat that value as the run id and do not add a second executor path here.
-- Read NDJSON signals only through `lib/signals/read` (the async-iterator entry point). Never open `<tempRoot>/run-<id>/stories/story-<sid>/signals.ndjson` directly — the reader owns the warn-once malformed-JSON policy.
-- Emit a single structured GitHub comment per ticket (`<!-- structured:story-perf-summary -->` or `<!-- structured:epic-perf-report -->`); rely on `upsertStructuredComment` for idempotence — never post duplicates.
-- Never rename or alter the structured-marker IDs; the retro composer and run dashboard grep them verbatim.
-- Validate the structured payload against `docs/data-dictionary.md §StoryPerfSummary` or `§EpicPerfReport` before posting. Schema violations exit non-zero.
-- Soft-fail (exit 0 with a warning) when NDJSON is missing for a Story or a plan-run has no children — observability output MUST NOT block the close pipeline.
-- Do not write to disk. Persistence is GitHub; the Skill is read-NDJSON + post-comment only.
-
-## Role
-
-Observability writer. Composes the structured `story-perf-summary` /
-`epic-perf-report` comment bodies the retro composer downstream renders
-into the run dashboard.
-
-## When to use
-
-- **Story mode** — after `single-story-close.js` finishes, the close
-  pipeline dispatches this Skill (or the wrapping script) to roll up the
-  Story's NDJSON signals into a single `<!-- structured:story-perf-summary -->`
-  marker comment on the Story ticket.
-- **Plan-run mode** — during run closeout (or the retro
-  composer), the Skill fans out across every Story under the plan-run,
-  reads each Story's structured perf summary, and posts a single
-  `<!-- structured:epic-perf-report -->` marker on the run ticket.
-
-## Inputs
-
-The Skill reads (never writes) the NDJSON signal stream at:
-
-```text
-<tempRoot>/run-<id>/stories/story-<sid>/signals.ndjson
-```
-
-Use the `lib/signals/read` async-iterator entry point — never open the
-file directly. Story mode also reads `phase-timings.json` written by
-the close pipeline.
-
-## Outputs
-
-A single upserted GitHub comment per ticket. The Skill writes nothing to
-disk — the persist path is GitHub. Idempotence: the underlying script's
-`upsertStructuredComment` helper deletes any prior marker before posting
-the new one.
-
-## Procedure
-
-### Step 1 — Resolve mode
-
-If both Story id and run id are supplied → Story mode.
-If only run id is supplied → plan-run mode. The script
-`analyze-execution.js` is the dispatcher today; this Skill documents the
-contract the dispatcher implements.
-
-### Step 2 — Read signals via lib/signals/read
-
-```bash
-node .agents/scripts/analyze-execution.js --story <sid> --epic <eid>
-# or
-node .agents/scripts/analyze-execution.js --epic <eid>
-```
-
-`--epic <eid>` is the legacy spelling of the run-id flag in the current
-CLI; treat `<eid>` as the run id for path/layout purposes.
-
-### Step 3 — Validate the structured payload before posting
-
-The payload must conform to `docs/data-dictionary.md §StoryPerfSummary`
-or §EpicPerfReport. Schema violations exit non-zero — the close
-pipeline treats that as a non-fatal warning, but the smoke spec pins
-the contract so we never silently emit malformed comments.
-
-## Constraints
-
-- Do **not** open `signals.ndjson` outside `lib/signals/read` — the
-  reader handles the warn-once policy for malformed JSON lines and
-  the streaming-iteration contract.
-- Do **not** rename the structured-marker IDs
-  (`<!-- structured:story-perf-summary -->`,
-  `<!-- structured:epic-perf-report -->`); the retro composer and the
-  run dashboard both grep for them verbatim.
-- Soft-failure mode is intentional: missing NDJSON for a Story or no
-  children for a plan-run returns exit 0 with a warning so close pipelines
-  never block on observability output.