@zeyue0329/xiaoma-cli 1.13.0 → 1.15.0

package/tools/schema/step.js

@@ -0,0 +1,855 @@
+// Zod schema definition for step file frontmatter inside auto-* pipelines.
+//
+// Scope: this schema validates the YAML frontmatter of step files under the five
+// auto-* pipelines (auto-requirements-pipeline, auto-story-pipeline,
+// auto-prd-to-stories, auto-full-pipeline; auto-story-pipeline-batch has no step
+// files). E1 (run #3 in pipeline-optimization-report.md) cleaned these up so every
+// such step file carries only `name`, `description`, `nextStepFile`, and the
+// conditional `nextStepFile_*` / `altStepFile` variants. N1 ratifies that cleanup
+// as a strict machine-checkable lint.
+//
+// Out of scope: step files under src/core/tasks/xiaoma-create-prd/ and under
+// src/xmc/workflows/xiaoma-quick-flow/ carry many additional context-binding keys
+// (prdFile, validationReportPath, outputFile, wipFile, …). Those pipelines are not
+// of the auto-* family and intentionally use a richer (open) frontmatter shape.
+// Run the validator only against PIPELINE_ROOTS in tools/validate-step-schemas.js.
+//
+// P1 (run #14) — optional `kind` field: lets each step file self-describe its
+// role in the pipeline (`init` / `analysis` / `orchestrator` / `quality-gate` /
+// `finalize` / `terminal`). Strictly optional; absence means "unclassified".
+// Downstream consumers (future status-JSON aggregator, dashboards) can group
+// or filter by kind without re-parsing the file body. Adding a new kind value
+// requires editing both the KIND_VALUES list below and the matching
+// test/test-step-schema.js positive case so coverage stays aligned.
+//
+// R1 (run #16) — extended the enum with two structural values that were
+// previously rolled under `orchestrator`:
+//   * `loop`   — self-referencing iteration step that calls itself via
+//                `nextStepFile_loop` (e.g. step-07-fix-and-retest in
+//                auto-story-pipeline). Distinct from generic `orchestrator`
+//                because dashboards visualizing pipeline shape care about
+//                "this step can re-enter itself".
+//   * `bridge` — cross-phase glue step that runs an out-of-band workflow
+//                (sprint-planning) to wire one pipeline's output into the
+//                next pipeline's input (e.g. step-03-bridge-sprint-planning
+//                in auto-full-pipeline and auto-prd-to-stories). Distinct
+//                from `orchestrator` because bridge failures need
+//                bridge-failure.json handling and resume semantics that pure
+//                orchestrator steps don't.
+// Loop/bridge classification is purely opt-in; existing `orchestrator`
+// callers remain valid. The unit test's `for (const kindValue of KIND_VALUES)`
+// loop automatically gains positive coverage for the new values.
+//
+// S2 (run #17) — structural pipeline-shape invariant: a `bridge` step must
+// never be the first or last step in its pipeline. Rationale: a bridge step
+// by definition glues two phases together, so it must have at least one
+// pipeline step on each side (a producer feeding it, and a consumer reading
+// its output). The auto-full-pipeline and auto-prd-to-stories pipelines
+// both already satisfy this naturally (their bridge sits at position 3 of
+// 5). The invariant is enforced by `verifyPipelineKindInvariants` below
+// and run from the CI walker per pipeline.
+//
+// T1 (run #18) — three more structural rules added to
+// `verifyPipelineKindInvariants`, closing proposal S3 from run #17 §7:
+//
+//   * `init-position`        — a step whose `kind === 'init'` must be at
+//                              index 0 of its pipeline. An init step is the
+//                              entry point; placing it elsewhere is almost
+//                              always a typo (e.g. wrong kind tag) and
+//                              breaks the assumed pipeline shape.
+//   * `terminal-position`    — a step whose `kind === 'terminal'` must be at
+//                              the last index of its pipeline. Mirror of
+//                              init-position for the exit side.
+//   * `init-uniqueness`      — at most one step per pipeline may carry
+//                              `kind: 'init'`. A second init is reported
+//                              with its name + position so operators can
+//                              relabel the duplicate.
+//   * `terminal-uniqueness`  — at most one step per pipeline may carry
+//                              `kind: 'terminal'`. Mirror of init-uniqueness.
+//
+// Like the S2 bridge-position rule, all four rules silently skip steps
+// whose `kind` is absent (the unclassified bucket), so opt-out remains
+// safe. All four live auto-* pipelines already satisfy every rule (init at
+// index 0 / terminal at last index / exactly one of each), so adoption is
+// a no-op + pure regression defence.
+//
+// U1 / U2 (run #19) — two more structural rules added to
+// `verifyPipelineKindInvariants`, closing proposals T2 + T3 from run #18 §7:
+//
+//   * `loop-self-reference` (U1) — a step whose `kind === 'loop'` must
+//                                  declare `nextStepFile_loop` pointing at
+//                                  itself (`./<name>.md`). A loop step's
+//                                  defining property is the ability to
+//                                  re-enter itself; if the self-reference
+//                                  is missing or routes elsewhere, the
+//                                  `loop` annotation is a lie. The only
+//                                  live `loop` step (auto-story-pipeline /
+//                                  step-07-fix-and-retest) already satisfies
+//                                  this naturally. To enforce this rule the
+//                                  pipeline-shape descriptor was widened
+//                                  from `{ name, kind }` to also carry
+//                                  `nextStepFile_loop` — descriptors
+//                                  remain backward-compatible when the
+//                                  field is absent.
+//   * `analysis-position` (U2)  — every step whose `kind === 'analysis'`
+//                                  must appear at a strictly smaller index
+//                                  than every step whose `kind ===
+//                                  'orchestrator'` in the same pipeline.
+//                                  Rationale: the analysis phase produces
+//                                  the inputs that orchestrator steps
+//                                  consume; placing analysis after
+//                                  orchestrator leaves the latter running
+//                                  against incomplete state. Currently
+//                                  only `auto-requirements-pipeline` has
+//                                  any `analysis` steps; the other three
+//                                  auto-* pipelines have none, so the rule
+//                                  is a no-op for them.
+//
+// Both rules silently skip unclassified steps (mirror of S2 / T1
+// behaviour) so opt-out remains safe.
+//
+// V1 / V2 (run #20) — two more structural rules added to
+// `verifyPipelineKindInvariants`, closing proposal U3 from run #19 §7 and
+// adding the natural uniqueness companion for the `finalize` kind:
+//
+//   * `quality-gate-predecessor` (V1) — a step whose `kind === 'quality-gate'`
+//                                       must have an immediate predecessor
+//                                       whose `kind` (if classified) is one
+//                                       of {analysis, orchestrator, loop,
+//                                       bridge, quality-gate}. Equivalently:
+//                                       a quality-gate cannot be the first
+//                                       step in its pipeline, and its
+//                                       predecessor cannot be `init`,
+//                                       `finalize`, or `terminal`. Chaining
+//                                       quality-gates is explicitly allowed
+//                                       (mirrors auto-story-pipeline's
+//                                       code-review → test-story shape where
+//                                       step-06 follows step-05, both gates).
+//                                       Unclassified predecessors are
+//                                       treated as "non-violating" (the rule
+//                                       only fires against known-bad kinds)
+//                                       so opt-out adoption stays safe.
+//   * `finalize-uniqueness` (V2)        — at most one step per pipeline may
+//                                       carry `kind: 'finalize'`. Mirror of
+//                                       init-uniqueness / terminal-uniqueness
+//                                       from T1 (run #18). Only
+//                                       auto-story-pipeline has any
+//                                       `finalize` step today
+//                                       (step-08-complete-story); the rule
+//                                       is a no-op for the other three
+//                                       auto-* pipelines.
+//
+// Both rules silently skip unclassified steps to preserve P1's opt-in
+// adoption contract. All four live auto-* pipelines satisfy both rules
+// (every live quality-gate's predecessor is orchestrator or quality-gate;
+// the single live finalize step is unique).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { z } = require('zod');
+
+// nextStepFile (and its conditional variants) must point to a sibling step file
+// using a relative `./step-NN-<kebab>.md` form, or be `null` for the terminal
+// step in the pipeline. The `null` form is reserved for nextStepFile itself —
+// conditional variants either point to a sibling step or are absent.
+const STEP_REF_PATTERN = /^\.\/step-\d{2}[a-z]?-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/;
+const NAME_PATTERN = /^step-\d{2}[a-z]?-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+// nextStepFile: required, string matching STEP_REF_PATTERN or explicit null for
+// terminal steps. We accept null only for nextStepFile (not the variants).
+const nextStepFileSchema = z.union([
+  z.string().regex(STEP_REF_PATTERN, 'must be "./step-NN-<kebab>.md" or null for terminal steps'),
+  z.null(),
+]);
+
+// Conditional next-step variants — must be a string pointing to a sibling step
+// when present; cannot be null (null implies "terminate the pipeline", and
+// conditional branches that want to terminate should simply omit the key).
+const conditionalStepFileSchema = z
+  .string()
+  .regex(STEP_REF_PATTERN, 'must be "./step-NN-<kebab>.md" (null not allowed on conditional variants)');
+
+// P1 (run #14) / R1 (run #16) — enumerated values for the optional `kind`
+// field. Order is rough lifecycle order (init → analysis → orchestrator →
+// loop → bridge → quality-gate → finalize → terminal) but the schema only
+// validates set membership, not ordering. Each value is described in the
+// tools/schema/step.js header comment above.
+const KIND_VALUES = ['init', 'analysis', 'orchestrator', 'loop', 'bridge', 'quality-gate', 'finalize', 'terminal'];
+
+const stepFrontmatterSchema = z
+  .object({
+    name: z.string().regex(NAME_PATTERN, 'must be kebab-case "step-NN-<words>" (matching the file basename without .md)'),
+    description: z.string().min(1, 'description must be a non-empty string'),
+    nextStepFile: nextStepFileSchema,
+
+    // Conditional routing variants — all optional, all pointing at a sibling step.
+    // We enumerate the four currently-in-use variants and the generic altStepFile.
+    // New variants can be added here when introduced.
+    nextStepFile_loop: conditionalStepFileSchema.optional(),
+    nextStepFile_issues: conditionalStepFileSchema.optional(),
+    nextStepFile_fail: conditionalStepFileSchema.optional(),
+    nextStepFile_skip: conditionalStepFileSchema.optional(),
+    altStepFile: conditionalStepFileSchema.optional(),
+
+    // P1 (run #14) — optional step-role tag. Absence means "unclassified" and
+    // is backward-compatible with every existing step file (all 27 live files
+    // remain valid without modification). Adding a new permitted value here
+    // requires updating KIND_VALUES above and the matching unit-test case.
+    kind: z.enum(KIND_VALUES, { errorMap: () => ({ message: `kind must be one of: ${KIND_VALUES.join(', ')}` }) }).optional(),
+  })
+  .strict();
+
+/**
+ * Validate the YAML frontmatter object of an auto-* pipeline step file.
+ *
+ * Performs structural Zod validation plus one cross-check: the `name` field
+ * must equal the file basename (without the .md extension). This catches the
+ * common drift where a step is renamed on disk but the frontmatter `name`
+ * value is left stale.
+ *
+ * @param {string} filePath Absolute or relative path to the step .md file.
+ * @param {unknown} frontmatter Parsed YAML frontmatter object.
+ * @returns {import('zod').SafeParseReturnType<unknown, unknown>} SafeParse result.
+ */
+function validateStepFrontmatter(filePath, frontmatter) {
+  const baseName = path.basename(filePath, '.md');
+
+  // First pass: structural validation.
+  const structural = stepFrontmatterSchema.safeParse(frontmatter);
+  if (!structural.success) {
+    return structural;
+  }
+
+  // Second pass: name-vs-filename cross-check.
+  if (structural.data.name !== baseName) {
+    return {
+      success: false,
+      error: new z.ZodError([
+        {
+          code: 'custom',
+          path: ['name'],
+          message: `frontmatter name "${structural.data.name}" does not match file basename "${baseName}"`,
+        },
+      ]),
+    };
+  }
+
+  return structural;
+}
+
+/**
+ * Verify that every `nextStepFile*` / `altStepFile` reference in `frontmatter`
+ * points to a sibling step file that exists on disk.
+ *
+ * The Zod schema in this same module validates the *shape* of the reference
+ * (the STEP_REF_PATTERN regex); this routine validates that the target also
+ * exists on the filesystem. Splitting the two checks lets the schema stay a
+ * pure data validator while reference existence stays a filesystem concern
+ * shared by both the CI walker (tools/validate-step-schemas.js) and the unit
+ * tests (test/test-step-schema.js — O1).
+ *
+ * Keys checked: any key that starts with `nextStepFile` (covers `nextStepFile`
+ * itself plus `nextStepFile_loop` / `_issues` / `_fail` / `_skip` and any
+ * future variants without code changes), and `altStepFile`. Non-string values
+ * (e.g. `null` on the terminal step's `nextStepFile`) are skipped.
+ *
+ * @param {string} stepDirAbsolute Absolute path to the directory holding the
+ *   step file. The function resolves each reference as `path.join(stepDirAbsolute, value)`.
+ * @param {object} frontmatter Parsed YAML frontmatter (typically already
+ *   accepted by validateStepFrontmatter, but the function does not require it).
+ * @returns {{ key: string, value: string, targetAbsolute: string }[]} List of
+ *   broken references; empty array when all references resolve. Each entry
+ *   carries the original frontmatter key, the literal value, and the absolute
+ *   path that was looked up — callers can render relative paths against any
+ *   chosen project root.
+ */
+function verifyStepReferences(stepDirAbsolute, frontmatter) {
+  const issues = [];
+
+  if (frontmatter === null || typeof frontmatter !== 'object') {
+    return issues;
+  }
+
+  for (const [key, value] of Object.entries(frontmatter)) {
+    if (!key.startsWith('nextStepFile') && key !== 'altStepFile') continue;
+    if (value === null || value === undefined) continue;
+    if (typeof value !== 'string') continue;
+    if (!value.startsWith('./')) continue;
+
+    const targetAbsolute = path.join(stepDirAbsolute, value);
+    if (!fs.existsSync(targetAbsolute)) {
+      issues.push({ key, value, targetAbsolute });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Verify pipeline-shape invariants over an ordered list of step descriptors.
+ *
+ * Currently checks nine structural rules:
+ *
+ *   * `bridge-position` (S2, run #17) — a step whose `kind === 'bridge'`
+ *     must not be the first step (index 0) or the last step (index
+ *     length-1) in its pipeline. A bridge by definition needs at least one
+ *     producing step before it and at least one consuming step after it.
+ *   * `init-position` (T1, run #18) — a step whose `kind === 'init'` must
+ *     be at index 0. Init steps initialize state for the whole pipeline,
+ *     so placing one in the middle leaves earlier steps running against
+ *     uninitialized state.
+ *   * `terminal-position` (T1, run #18) — a step whose `kind === 'terminal'`
+ *     must be at the last index. Mirror of init-position for the exit side.
+ *   * `init-uniqueness` (T1, run #18) — at most one step per pipeline may
+ *     carry `kind: 'init'`. A duplicate is reported with its name + index
+ *     so the operator knows which one to relabel.
+ *   * `terminal-uniqueness` (T1, run #18) — at most one step per pipeline
+ *     may carry `kind: 'terminal'`. Mirror of init-uniqueness.
+ *   * `loop-self-reference` (U1, run #19) — a step whose `kind === 'loop'`
+ *     must declare `nextStepFile_loop` pointing at itself (canonical form
+ *     `./<name>.md`). A loop step's defining property is the ability to
+ *     re-enter itself via the `_loop` conditional branch; a missing or
+ *     foreign-target self-reference makes the `loop` annotation a lie.
+ *   * `analysis-position` (U2, run #19) — every step whose
+ *     `kind === 'analysis'` must appear at a strictly smaller index than
+ *     every step whose `kind === 'orchestrator'` in the same pipeline.
+ *     Equivalent statement: once a pipeline reaches its first orchestrator
+ *     step, no later analysis step may appear. The rule is reported
+ *     against the offending analysis step, with the position of the first
+ *     orchestrator in the message for context.
+ *   * `quality-gate-predecessor` (V1, run #20) — a step whose
+ *     `kind === 'quality-gate'` must have an immediate predecessor whose
+ *     `kind` (if classified) is one of {analysis, orchestrator, loop,
+ *     bridge, quality-gate}. A quality-gate validates productive work; it
+ *     makes no sense to gate the output of `init` (nothing produced yet),
+ *     `finalize` (the pipeline is wrapping up), or `terminal` (the next
+ *     index doesn't exist). Quality-gate at index 0 also fails (no
+ *     predecessor exists). Chaining quality-gates is allowed (mirrors
+ *     auto-story-pipeline's code-review → test-story shape). An
+ *     unclassified predecessor is treated as non-violating to preserve
+ *     opt-out adoption semantics.
+ *   * `finalize-uniqueness` (V2, run #20) — at most one step per pipeline
+ *     may carry `kind: 'finalize'`. Mirror of init-uniqueness /
+ *     terminal-uniqueness. A second finalize step is reported with its
+ *     name + index so the operator knows which one to relabel.
+ *
+ * The function is intentionally `kind`-aware but stays agnostic about which
+ * specific names (`step-NN-...`) carry which kinds — callers feed in an
+ * ordered list and the function reports issues by position + name. Steps
+ * without a `kind` field (the "unclassified" bucket in the walker histogram)
+ * are silently skipped, preserving backward compatibility with any future
+ * step file that opts out of the optional enum.
+ *
+ * Descriptor shape: each entry is `{ name, kind?, nextStepFile_loop? }`.
+ * The optional `nextStepFile_loop` is consulted only by the U1 rule; other
+ * rules ignore it. Walkers may pass the full frontmatter object — extra
+ * keys are simply ignored.
+ *
+ * Adding a new invariant: extend the issues array in this function and add
+ * a matching unit test in test/test-step-schema.js. Possible future
+ * candidates (not implemented):
+ *   * `bridge` step should declare a recovery branch (e.g. `nextStepFile_fail`
+ *     pointing at a finalize/error path). Deferred from U4 in run #19 §7
+ *     because the current live bridges (auto-full-pipeline /
+ *     auto-prd-to-stories step-03-bridge-sprint-planning) use a HALT +
+ *     bridge-failure.json marker pattern for recovery rather than
+ *     in-pipeline routing. Enforcing this rule would require a behavioural
+ *     change to the bridges, not just a documentation lint.
+ *   * `step_kind` field propagated into the per-pipeline status JSON so
+ *     downstream dashboards can render pipeline shape without re-parsing
+ *     step frontmatter. Deferred from U5 in run #19 §7 — needs producer +
+ *     consumer changes on both sides.
+ *
+ * @param {{ name: string, kind?: string, nextStepFile_loop?: string }[]}
+ *   pipelineSteps Ordered list of step descriptors (one pipeline at a time,
+ *   in file-name order).
+ * @returns {{ rule: string, name: string, index: number, message: string }[]}
+ *   List of invariant violations; empty array when the pipeline is clean.
+ */
+function verifyPipelineKindInvariants(pipelineSteps) {
+  const issues = [];
+
+  if (!Array.isArray(pipelineSteps) || pipelineSteps.length === 0) {
+    return issues;
+  }
+
+  const lastIndex = pipelineSteps.length - 1;
+
+  // T1 (run #18) — track first sightings so duplicates can be reported
+  // against the original step (helps operators identify which one is the
+  // newcomer / typo). V2 (run #20) extends the pattern to `finalize`.
+  let firstInit = null;
+  let firstTerminal = null;
+  let firstFinalize = null;
+
+  // V1 (run #20) — predecessor-kind allow-list for quality-gate steps.
+  // A quality-gate validates productive work, so its immediate predecessor
+  // must itself be productive (analysis / orchestrator / loop / bridge) or
+  // another quality-gate (allows chaining gates such as code-review →
+  // test-story in auto-story-pipeline). Predecessors with no classified
+  // `kind` are treated as non-violating to preserve P1's opt-out adoption.
+  const QUALITY_GATE_ALLOWED_PREDECESSORS = new Set(['analysis', 'orchestrator', 'loop', 'bridge', 'quality-gate']);
+
+  // U2 (run #19) — pre-pass: find the index of the first orchestrator step
+  // (if any) so the analysis-position rule below can compare against it in
+  // O(n) overall. Steps with no `kind` field never count as orchestrators.
+  let firstOrchestratorIndex = -1;
+  for (const [index, step] of pipelineSteps.entries()) {
+    if (step && typeof step === 'object' && step.kind === 'orchestrator') {
+      firstOrchestratorIndex = index;
+      break;
+    }
+  }
+
+  for (const [index, step] of pipelineSteps.entries()) {
+    if (!step || typeof step !== 'object') continue;
+
+    // S2 — bridge-position rule.
+    if (step.kind === 'bridge') {
+      if (index === 0) {
+        issues.push({
+          rule: 'bridge-position',
+          name: step.name,
+          index,
+          message: `bridge step "${step.name}" is at index 0 (first position); a bridge needs at least one producing step before it`,
+        });
+      } else if (index === lastIndex) {
+        issues.push({
+          rule: 'bridge-position',
+          name: step.name,
+          index,
+          message: `bridge step "${step.name}" is at the last index (${lastIndex}); a bridge needs at least one consuming step after it`,
+        });
+      }
+    }
+
+    // T1 — init-position + init-uniqueness rules.
+    if (step.kind === 'init') {
+      if (index !== 0) {
+        issues.push({
+          rule: 'init-position',
+          name: step.name,
+          index,
+          message: `init step "${step.name}" is at index ${index}; init steps must be at index 0 (pipeline entry point)`,
+        });
+      }
+      if (firstInit === null) {
+        firstInit = { name: step.name, index };
+      } else {
+        issues.push({
+          rule: 'init-uniqueness',
+          name: step.name,
+          index,
+          message: `duplicate init step "${step.name}" at index ${index}; first init was "${firstInit.name}" at index ${firstInit.index}`,
+        });
+      }
+    }
+
+    // T1 — terminal-position + terminal-uniqueness rules.
+    if (step.kind === 'terminal') {
+      if (index !== lastIndex) {
+        issues.push({
+          rule: 'terminal-position',
+          name: step.name,
+          index,
+          message: `terminal step "${step.name}" is at index ${index}; terminal steps must be at the last index (${lastIndex})`,
+        });
+      }
+      if (firstTerminal === null) {
+        firstTerminal = { name: step.name, index };
+      } else {
+        issues.push({
+          rule: 'terminal-uniqueness',
+          name: step.name,
+          index,
+          message: `duplicate terminal step "${step.name}" at index ${index}; first terminal was "${firstTerminal.name}" at index ${firstTerminal.index}`,
+        });
+      }
+    }
+
+    // U1 (run #19) — loop-self-reference rule. A `loop` step must declare
+    // `nextStepFile_loop` pointing at itself in canonical `./<name>.md` form.
+    // Missing self-reference, foreign-target self-reference, or non-string
+    // value all surface as a single rule violation against this step.
+    if (step.kind === 'loop') {
+      const expected = `./${step.name}.md`;
+      const actual = step.nextStepFile_loop;
+      if (actual !== expected) {
+        const detail = actual === undefined ? 'missing' : `"${actual}"`;
+        issues.push({
+          rule: 'loop-self-reference',
+          name: step.name,
+          index,
+          message: `loop step "${step.name}" must declare nextStepFile_loop: "${expected}" (got ${detail}); a loop step's defining property is the ability to re-enter itself`,
+        });
+      }
+    }
+
+    // U2 (run #19) — analysis-position rule. An `analysis` step that
+    // appears at a strictly larger index than the first `orchestrator`
+    // step in the same pipeline violates the "analysis precedes
+    // orchestration" contract. Skips silently when the pipeline contains
+    // no orchestrator step (e.g. an analysis-only pipeline).
+    if (step.kind === 'analysis' && firstOrchestratorIndex !== -1 && index > firstOrchestratorIndex) {
+      issues.push({
+        rule: 'analysis-position',
+        name: step.name,
+        index,
+        message: `analysis step "${step.name}" is at index ${index}; must precede the first orchestrator step at index ${firstOrchestratorIndex}`,
+      });
+    }
+
+    // V1 (run #20) — quality-gate-predecessor rule. A `quality-gate` step
+    // gates productive work, so it cannot be the first step (no predecessor
+    // to gate) and its immediate predecessor's classified kind must be in
+    // QUALITY_GATE_ALLOWED_PREDECESSORS. An unclassified predecessor (no
+    // `kind` field) is treated as non-violating to preserve P1's opt-out
+    // adoption semantics — the rule fires only against *known-bad* kinds.
+    if (step.kind === 'quality-gate') {
+      if (index === 0) {
+        issues.push({
+          rule: 'quality-gate-predecessor',
+          name: step.name,
+          index,
+          message: `quality-gate step "${step.name}" is at index 0 (no predecessor to gate); a quality-gate must follow a productive step`,
+        });
+      } else {
+        const predecessor = pipelineSteps[index - 1];
+        const predecessorKind = predecessor && typeof predecessor === 'object' ? predecessor.kind : undefined;
+        if (predecessorKind !== undefined && !QUALITY_GATE_ALLOWED_PREDECESSORS.has(predecessorKind)) {
+          const allowed = [...QUALITY_GATE_ALLOWED_PREDECESSORS].join(', ');
+          issues.push({
+            rule: 'quality-gate-predecessor',
+            name: step.name,
+            index,
+            message: `quality-gate step "${step.name}" at index ${index} follows "${predecessor.name}" (kind=${predecessorKind}); predecessor kind must be one of: ${allowed}`,
+          });
+        }
+      }
+    }
+
+    // V2 (run #20) — finalize-uniqueness rule. Mirror of init-uniqueness /
+    // terminal-uniqueness from T1. The duplicate is reported against the
+    // second sighting so operators can identify the newcomer to relabel.
+    // Note: there is intentionally no `finalize-position` rule — a
+    // `finalize` step's position is governed by pipeline-specific design
+    // (auto-story-pipeline places it at lastIndex-1, immediately before
+    // its `terminal` step), and over-constraining it would block future
+    // pipelines that legitimately want finalize at a different position.
+    if (step.kind === 'finalize') {
+      if (firstFinalize === null) {
+        firstFinalize = { name: step.name, index };
+      } else {
+        issues.push({
+          rule: 'finalize-uniqueness',
+          name: step.name,
+          index,
+          message: `duplicate finalize step "${step.name}" at index ${index}; first finalize was "${firstFinalize.name}" at index ${firstFinalize.index}`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Format a markdown reference document for the auto-* pipeline step kinds.
+ *
+ * Y1 (run #23) — closes proposal (t) in pipeline-optimization-report.md
+ * (`docs/step-kinds.md` auto-generation). Takes the same per-pipeline ordered
+ * step descriptors that `verifyPipelineKindInvariants` consumes, plus the
+ * pipeline display label and the optional `description` field of each step,
+ * and returns a single markdown string suitable for writing to
+ * `docs/step-kinds.md`. The output is deterministic given the same input so
+ * drift detection is a simple byte-equal comparison.
+ *
+ * The output shape:
+ *
+ *   # Auto Pipeline Step Kinds Reference
+ *
+ *   > **AUTO-GENERATED** ... (header preamble)
+ *
+ *   ## <pipeline-name>
+ *
+ *   **Shape:** `init` → `analysis` → ... → `terminal`
+ *
+ *   ```mermaid
+ *   flowchart TD
+ *       s1["step-NN-xxx<br/>kind-value"]
+ *       ...
+ *       s1 --> s2
+ *       s7 -. loop .-> s7
+ *   ```
+ *
+ *   | # | Step | Kind | Description |
+ *   |---|------|------|-------------|
+ *   | 01 | step-NN-xxx | kind-value | first-sentence-of-description |
+ *
+ *   ## Kind Distribution
+ *
+ *   | Kind | Count |
+ *   |------|-------|
+ *   | init | 4 |
+ *
+ * Z1 (run #24) — adds a one-line "Shape signature" between each `## <pipeline>`
+ * H2 and the per-pipeline detail table. The shape is a left-to-right arrow-
+ * connected sequence of each step's `kind` (or `unclassified` when absent),
+ * letting reviewers eyeball the pipeline silhouette without scanning N table
+ * rows. This is the natural reader-facing complement to the schema-level
+ * structural invariants enforced by verifyPipelineKindInvariants: the
+ * invariants catch shape violations programmatically; the Shape line lets a
+ * human reviewer spot intentional differences (e.g. auto-story-pipeline's
+ * 3-gate streak vs. auto-requirements-pipeline's single mid-pipeline gate) at
+ * a glance.
+ *
+ * AB1 (run #26) — closes proposal (dd) in pipeline-optimization-report.md
+ * (`docs/step-kinds.md` mermaid flowchart enrichment). For each non-empty
+ * pipeline, a fenced mermaid `flowchart TD` block is inserted between the
+ * Shape signature line and the per-step table. Nodes are labeled `step-name`
+ * over `kind` and edges are drawn from each step's `nextStepFile*` references:
+ *
+ *   * `nextStepFile`        → solid arrow `s1 --> s2` (main flow). The
+ *                             terminal step's `null` nextStepFile produces no
+ *                             outbound main-flow edge.
+ *   * `nextStepFile_loop`   → labeled dotted arrow `s7 -. loop .-> s7` (the
+ *                             only live use is auto-story-pipeline step-07's
+ *                             self-reference).
+ *   * `nextStepFile_issues` → labeled dotted arrow `s5 -. issues .-> s7`
+ *                             (e.g. auto-story-pipeline code-review fanning
+ *                             to fix-and-retest).
+ *   * `nextStepFile_fail`   → labeled dotted arrow `s6 -. fail .-> s7`
+ *                             (e.g. auto-story-pipeline test-story fanning
+ *                             to fix-and-retest).
+ *   * `nextStepFile_skip`   → labeled dotted arrow `sN -. skip .-> sM`.
+ *   * `altStepFile`         → labeled dotted arrow `sN -. alt .-> sM`.
+ *
+ * Edges with targets outside the pipeline are silently skipped (a validated
+ * tree never has these; the formatter stays safe for partial-pipeline test
+ * inputs). The diagram is the visual companion to the Shape signature: shape
+ * shows kind-sequence, the diagram shows reach-ability + conditional branches.
+ *
+ * Splitting this into a pure function keeps the markdown-formatting concern
+ * unit-testable independently of filesystem I/O — the CLI walker is the only
+ * caller that needs to read frontmatter and write to disk.
+ *
+ * @param {{ label: string, steps: { name: string, kind?: string, description?: string, nextStepFile?: string | null, nextStepFile_loop?: string, nextStepFile_issues?: string, nextStepFile_fail?: string, nextStepFile_skip?: string, altStepFile?: string }[] }[]} pipelines
+ *   Ordered list of pipelines. Each entry carries the human-readable pipeline
+ *   `label` (e.g. `auto-requirements-pipeline`) and the ordered step descriptors.
+ *   AB1 (run #26) widens the step descriptor with the main and conditional
+ *   `nextStepFile*` fields so the mermaid flowchart can render edges. All new
+ *   fields are optional — descriptors that only carry `{name, kind, description}`
+ *   (the Y1 / Z1 contract) still produce a node-only flowchart with no edges.
+ * @returns {string} Markdown document body, ending with exactly one trailing newline.
+ */
+function formatStepKindsDoc(pipelines) {
+  const lines = [];
+  lines.push(
+    '# Auto Pipeline Step Kinds Reference',
+    '',
+    '> **AUTO-GENERATED** by `tools/validate-step-schemas.js --emit-doc`. Do not edit by hand.',
+    '> Run `npm run validate:step-kinds-doc` to detect drift between this file and the live step tree.',
+    '',
+    'Each row shows a step file in the four `auto-*` pipelines along with its `kind` annotation from YAML frontmatter and a short description. Each pipeline section also renders a mermaid flowchart wired from the live `nextStepFile*` references.',
+    '',
+  );
+
+  // Aggregate counts as we walk the pipelines so the histogram below stays
+  // consistent with the per-pipeline tables without a second pass.
+  const totals = Object.fromEntries(KIND_VALUES.map((v) => [v, 0]));
+  totals.unclassified = 0;
+
+  for (const pipeline of pipelines) {
+    // Z1 (run #24) — Shape signature: a single arrow-connected line of the
+    // ordered step kinds, rendered between the H2 and the per-step table so
+    // reviewers can eyeball pipeline silhouettes without scanning the rows.
+    // Empty pipelines produce `**Shape:** _(empty)_` rather than a bare label
+    // so the line is still visually present and grep-able.
+    const shapeTokens = pipeline.steps.map((step) => `\`${step.kind || 'unclassified'}\``);
+    const shapeLine = shapeTokens.length > 0 ? shapeTokens.join(' → ') : '_(empty)_';
+    lines.push(`## ${pipeline.label}`, '', `**Shape:** ${shapeLine}`, '');
+
+    // AB1 (run #26) — Mermaid flowchart block sits between the Shape line and
+    // the per-step detail table. Empty pipelines are skipped (no useful graph
+    // to render); the `_(empty)_` Shape line already conveys the same fact.
+    if (pipeline.steps.length > 0) {
+      lines.push(...formatMermaidFlowchart(pipeline.steps), '');
+    }
+
+    lines.push('| # | Step | Kind | Description |', '|---|------|------|-------------|');
+    for (const [idx, step] of pipeline.steps.entries()) {
+      const num = String(idx + 1).padStart(2, '0');
+      const kind = step.kind || 'unclassified';
+      const description = firstSentence(step.description || '');
+      lines.push(`| ${num} | \`${step.name}\` | \`${kind}\` | ${description} |`);
+      if (Object.prototype.hasOwnProperty.call(totals, kind)) {
+        totals[kind]++;
+      } else {
+        totals.unclassified++;
+      }
+    }
+    lines.push('');
+  }
+
+  // Histogram — mirrors the walker's stdout output but persisted to disk so a
+  // dashboard or external consumer can `grep` it without invoking the validator.
+  lines.push('## Kind Distribution', '', '| Kind | Count |', '|------|-------|');
+  for (const kindValue of KIND_VALUES) {
+    lines.push(`| \`${kindValue}\` | ${totals[kindValue]} |`);
+  }
+  lines.push(`| \`unclassified\` | ${totals.unclassified} |`, '');
+
+  return lines.join('\n');
+}
+
+// AB1 (run #26) — conditional-edge variant descriptor used by
+// `formatMermaidFlowchart`. The order is the rendering order for conditional
+// edges so the generated flowchart stays deterministic: loop first (most
+// pipeline-shape-relevant — a loop edge usually re-enters the same node),
+// then issues / fail (the two routing variants used by live auto-story
+// pipeline gates), then the rarely-used skip / alt tails. Adding a new
+// conditional variant in `tools/schema/step.js` (and the matching strict
+// schema) requires appending to this list to surface the edge in the
+// flowchart; existing tests' variant-order assertions will fail until the
+// new entry is added consistently.
+const CONDITIONAL_EDGE_VARIANTS = Object.freeze([
+  { field: 'nextStepFile_loop', label: 'loop' },
+  { field: 'nextStepFile_issues', label: 'issues' },
+  { field: 'nextStepFile_fail', label: 'fail' },
+  { field: 'nextStepFile_skip', label: 'skip' },
+  { field: 'altStepFile', label: 'alt' },
+]);
+
+// AB1 (run #26) — STEP_REF_PATTERN-compatible target extractor. The mermaid
+// flowchart formatter resolves each `nextStepFile*` value (e.g.
+// `./step-02-create-story.md`) back to its source step name so it can look up
+// the target's node id within the same pipeline. The regex mirrors the schema
+// STEP_REF_PATTERN above so the two layers stay in sync; a non-matching value
+// (or one whose target isn't a sibling in the same pipeline) is silently
+// skipped — the formatter must remain safe for partial-pipeline test inputs.
+const STEP_REF_TARGET_PATTERN = /^\.\/(step-\d{2}[a-z]?-[a-z0-9]+(?:-[a-z0-9]+)*)\.md$/;
+
+/**
+ * Format one pipeline's mermaid `flowchart TD` block.
+ *
+ * Renders each step as a node `sN["step-name<br/>kind"]`, then draws:
+ *   * a solid main-flow arrow `sN --> sM` for each `nextStepFile`
+ *     (terminal steps with `null` or absent `nextStepFile` emit no arrow);
+ *   * a labeled dotted arrow `sN -. <variant> .-> sM` for each conditional
+ *     variant declared in CONDITIONAL_EDGE_VARIANTS that points at a sibling
+ *     in the same pipeline.
+ *
+ * Edges to targets outside the pipeline are silently skipped (a validated
+ * tree never has these; safety net for partial-pipeline unit-test inputs).
+ *
+ * Output is an array of lines (caller controls outer blank-line padding).
+ * The block always starts with `` ```mermaid `` and ends with `` ``` ``.
+ *
+ * Deterministic given the same input: nodes in pipeline order, main edges in
+ * pipeline order, conditional edges in pipeline order then variant order so
+ * the `validate:step-kinds-doc` drift check stays stable.
+ *
+ * @param {{ name: string, kind?: string, nextStepFile?: string | null,
+ *   nextStepFile_loop?: string, nextStepFile_issues?: string,
+ *   nextStepFile_fail?: string, nextStepFile_skip?: string,
+ *   altStepFile?: string }[]} steps Ordered list of step descriptors. Must be
+ *   non-empty; callers guard the empty case (the doc generator skips empty
+ *   pipelines entirely so they don't produce a stub flowchart).
+ * @returns {string[]} Lines forming a fenced mermaid block.
+ */
+function formatMermaidFlowchart(steps) {
+  const lines = ['```mermaid', 'flowchart TD'];
+
+  // Build the name → 1-based node id lookup once so edge resolution is O(1).
+  const nameToNodeId = new Map();
+  for (const [idx, step] of steps.entries()) {
+    nameToNodeId.set(step.name, `s${idx + 1}`);
+  }
+
+  function resolveTargetNodeId(value) {
+    if (typeof value !== 'string') return null;
+    const match = STEP_REF_TARGET_PATTERN.exec(value);
+    if (!match) return null;
+    return nameToNodeId.get(match[1]) || null;
+  }
+
+  // Node definitions.
+  for (const [idx, step] of steps.entries()) {
+    const nodeId = `s${idx + 1}`;
+    const kind = step.kind || 'unclassified';
+    lines.push(`    ${nodeId}["${step.name}<br/>${kind}"]`);
+  }
+
+  // Main-flow edges.
+  for (const [idx, step] of steps.entries()) {
+    const sourceId = `s${idx + 1}`;
+    const targetId = resolveTargetNodeId(step.nextStepFile);
+    if (targetId) {
+      lines.push(`    ${sourceId} --> ${targetId}`);
+    }
+  }
+
+  // Conditional edges (variant order matches CONDITIONAL_EDGE_VARIANTS).
+  for (const [idx, step] of steps.entries()) {
+    const sourceId = `s${idx + 1}`;
+    for (const { field, label } of CONDITIONAL_EDGE_VARIANTS) {
+      const targetId = resolveTargetNodeId(step[field]);
+      if (targetId) {
+        lines.push(`    ${sourceId} -. ${label} .-> ${targetId}`);
+      }
+    }
+  }
+
+  lines.push('```');
+  return lines;
+}
+
+// Trim a free-form description down to the first sentence so the generated
+// table stays readable. Falls back to the whole string when no terminator is
+// found. Markdown table cells need pipe characters escaped so the table
+// doesn't break.
+//
+// AA2 (run #25) — closes proposal (ee) in pipeline-optimization-report.md.
+// Two changes to the original Y1 (run #23) regex:
+//
+//   1. Extends the terminator set with Chinese full-width semicolon `；`
+//      and Chinese full-width colon `：` (in addition to the pre-existing
+//      `。`, `！`, `？`) so future Chinese-language descriptions can be
+//      truncated at natural clause boundaries. ASCII `;` / `:` are
+//      intentionally NOT terminators — existing English descriptions that
+//      use a colon mid-sentence (e.g. "Phase 2 bridge: auto-run sprint
+//      planning…") remain intact.
+//   2. Splits the trailing-context requirement by character class:
+//        * ASCII `.!?` still REQUIRE a following whitespace or end-of-string,
+//          so mid-token periods like `req.md` in English descriptions do
+//          not falsely terminate the sentence.
+//        * Chinese full-width terminators (`。！？；：`) DO NOT require
+//          trailing whitespace because Chinese prose runs words together
+//          without spaces — requiring whitespace would mean Chinese
+//          descriptions never truncate at the intended boundary.
+//
+// Adding more terminators requires updating both this regex and the matching
+// AA2 unit test cases.
+function firstSentence(text) {
+  if (!text) return '';
+  const trimmed = text.trim();
+  // Match the first sentence-terminating punctuation. ASCII `.!?` need a
+  // following whitespace or end-of-string (anti-`req.md` guard); Chinese
+  // full-width terminators stand alone (no whitespace requirement). Falls
+  // back to the entire trimmed text when no terminator matches.
+  const match = trimmed.match(/^(.*?(?:[.!?](?=\s|$)|[。！？；：]))/);
+  const sentence = match ? match[1] : trimmed;
+  return sentence.replaceAll('|', String.raw`\|`);
+}
+
+module.exports = {
+  validateStepFrontmatter,
+  verifyStepReferences,
+  verifyPipelineKindInvariants,
+  formatStepKindsDoc,
+  formatMermaidFlowchart,
+  STEP_REF_PATTERN,
+  NAME_PATTERN,
+  KIND_VALUES,
+  CONDITIONAL_EDGE_VARIANTS,
+};