@structured-vibe-coding/core 0.7.0 → 0.9.0

package/defaults/memory/constitution.md

@@ -0,0 +1,23 @@
+# Constitution
+
+<!-- Non-negotiables agents must not violate. Broader style lives in conventions.md. -->
+
+## Principles
+
+-
+
+## Stack & tooling
+
+-
+
+## Testing
+
+-
+
+## Security
+
+-
+
+## Process
+
+-

package/defaults/memory/index.md

@@ -6,7 +6,7 @@ Parent page for **stable** project docs. Humans and coding agents: start here, t
 |------|--------|----------|
 | **This map + memory** | `memory/*.md` | Long-lived |
 | **Active change** | `changes/<id>/` (see `.sdd/active-context.md`) | Until complete |
-| **Finished work** | `archive/<id>/` | History |
+| **Finished work** | `changes/<id>/` with `status: completed` | History (pack stays in place; archive is opt-in) |
 | **Optional domains** | `domains/` | Long-lived by area |
 
 ## Stable docs
@@ -14,6 +14,7 @@ Parent page for **stable** project docs. Humans and coding agents: start here, t
 | Topic | File |
 |-------|------|
 | Product / vision | [product.md](product.md) |
+| Constitution (non-negotiables) | [constitution.md](constitution.md) |
 | Architecture | [architecture.md](architecture.md) |
 | Coding & process conventions | [conventions.md](conventions.md) |
 

package/defaults/templates/brainstorm.md

@@ -0,0 +1,67 @@
+# Brainstorm
+
+> **{{title}}** · `{{id}}` · stage `{{stage}}`  
+> **Optional stage** — skip if one approach is obvious:  
+> `sdd skip brainstorm -r "single approach is clear"`
+
+## Goal of exploration
+
+-
+
+## Approach A
+
+### Idea
+
+-
+
+### Pros
+
+-
+
+### Cons / risks
+
+-
+
+## Approach B
+
+### Idea
+
+-
+
+### Pros
+
+-
+
+### Cons / risks
+
+-
+
+## Approach C (optional)
+
+### Idea
+
+-
+
+### Pros
+
+-
+
+### Cons / risks
+
+-
+
+## Comparison
+
+| Criterion | A | B | C |
+|-----------|---|---|---|
+| Complexity | | | |
+| Risk | | | |
+| Fit to constraints | | | |
+
+## Recommendation for design stage
+
+-
+
+## Open questions (feed clarify / design)
+
+-

package/defaults/templates/clarify.md

@@ -0,0 +1,30 @@
+# Clarify
+
+> **{{title}}** · `{{id}}` · stage `{{stage}}`  
+> **Optional stage** — skip if nothing is ambiguous:  
+> `sdd skip {{stage}} -r "no open questions"`
+
+## Context
+
+What just finished? What is about to start?
+
+-
+
+## Clarifying questions
+
+1. **Q:**  
+   **A:**  
+
+2. **Q:**  
+   **A:**  
+
+3. **Q:**  
+   **A:**  
+
+## Decisions / constraints captured
+
+-
+
+## Ready for next stage?
+
+- [ ] No blocking unknowns remain (or explicitly accepted risks)

package/defaults/workflows/enterprise-feature.yaml

@@ -114,10 +114,7 @@ stages:
     title: Implementation
     summary: Execute tasks; respect ARB conditions
     skippable: false
-    artifacts:
-      - id: evidence
-        path: evidence/
-        required: false
+    artifacts: []
     gate:
       type: soft
       checklist:
@@ -142,9 +139,6 @@ stages:
         path: local-test-results.md
         template: local-test-results.md
         required: true
-      - id: evidence
-        path: evidence/local/
-        required: false
     gate:
       type: hard
       overridable: true
@@ -154,8 +148,7 @@ stages:
         - "Failures fixed or filed before complete"
     verify:
       commands: []
-      evidence_dir: evidence/local
 
 on_complete:
-  archive: true
+  archive: false
   domain_sync: recommend

package/defaults/workflows/feature.yaml

@@ -1,6 +1,6 @@
 name: feature
-description: Standard feature — intent, design, tasks, implement, local verify
-version: 1
+description: "Feature — intent, optional clarify/brainstorm, design, tasks, implement, verify"
+version: 2
 recommendation:
   priority: 30
   when:
@@ -10,6 +10,7 @@ stages:
   - id: intent
     title: Feature intent
     summary: Problem, users, scope, non-goals, success
+    kind: standard
     skippable: false
     artifacts:
       - id: feature
@@ -20,10 +21,55 @@ stages:
       type: soft
       checklist:
         - "Scope and non-goals are explicit"
+
+  # Optional: clarifying questions after intent
+  - id: clarify_intent
+    title: Clarify intent
+    summary: Ask clarifying questions before brainstorm/design (optional)
+    kind: clarify
+    optional: true
+    skippable: true
+    artifacts:
+      - id: clarify-intent
+        path: clarify-intent.md
+        template: clarify.md
+        required: false
+    gate:
+      type: soft
+    agent_context:
+      instructions: |
+        OPTIONAL clarify stage. If scope is already clear, tell the human to run:
+          sdd skip clarify_intent -r "intent is clear"
+        Otherwise ask focused clarifying questions (ambiguities, constraints, success metrics).
+        Write Q&A into clarify-intent.md. Do not design or implement yet.
+
+  # Optional: parallel approaches before design
+  - id: brainstorm
+    title: Brainstorm approaches
+    summary: Explore multiple approaches in parallel (optional)
+    kind: brainstorm
+    optional: true
+    skippable: true
+    artifacts:
+      - id: brainstorm
+        path: brainstorm.md
+        template: brainstorm.md
+        required: false
+    gate:
+      type: soft
+    agent_context:
+      instructions: |
+        OPTIONAL brainstorm stage. If a single approach is obvious, human may:
+          sdd skip brainstorm -r "single approach is clear"
+        Otherwise produce 2–4 approaches in brainstorm.md (trade-offs, risks).
+        Prefer parallel exploration: outline each approach independently, then compare.
+        Do not pick a final design until design stage. Do not implement code yet.
+
   - id: design
     title: Design
-    summary: Approach, components, risks (keep short)
-    skippable: true
+    summary: Chosen approach, components, risks (required for features)
+    kind: standard
+    skippable: false
     artifacts:
       - id: design
         path: design.md
@@ -31,9 +77,37 @@ stages:
         required: true
     gate:
       type: soft
+      checklist:
+        - "Approach chosen and risks noted"
+    agent_context:
+      instructions: |
+        Produce a concrete design in design.md based on feature.md and brainstorm.md (if any).
+        Do not leave template stubs empty — substantive content is required before sdd next.
+        Do not implement product code yet.
+
+  - id: clarify_design
+    title: Clarify design
+    summary: Clarifying questions after design (optional)
+    kind: clarify
+    optional: true
+    skippable: true
+    artifacts:
+      - id: clarify-design
+        path: clarify-design.md
+        template: clarify.md
+        required: false
+    gate:
+      type: soft
+    agent_context:
+      instructions: |
+        OPTIONAL. Skip if design is clear:
+          sdd skip clarify_design -r "design is clear"
+        Otherwise ask questions that unblock tasks/implement. Write answers to clarify-design.md.
+
   - id: tasks
     title: Tasks
     summary: Break work into implementable tasks
+    kind: standard
     skippable: true
     artifacts:
       - id: tasks
@@ -42,9 +116,34 @@ stages:
         required: true
     gate:
       type: soft
+    agent_context:
+      instructions: |
+        Break design into concrete tasks in tasks.md. Design must already be substantive.
+        Do not implement large product code yet.
+
+  - id: clarify_tasks
+    title: Clarify tasks
+    summary: Clarifying questions after tasks (optional)
+    kind: clarify
+    optional: true
+    skippable: true
+    artifacts:
+      - id: clarify-tasks
+        path: clarify-tasks.md
+        template: clarify.md
+        required: false
+    gate:
+      type: soft
+    agent_context:
+      instructions: |
+        OPTIONAL. Skip if tasks are clear:
+          sdd skip clarify_tasks -r "tasks are clear"
+        Otherwise resolve ambiguities before implement.
+
   - id: implement
     title: Implement
     summary: Build the feature locally
+    kind: standard
     skippable: false
     artifacts: []
     gate:
@@ -52,10 +151,12 @@ stages:
     agent_context:
       instructions: |
         Implement tasks from tasks.md following design.md and feature.md.
-        Prefer incremental, testable steps.
+        Prefer incremental, testable steps. Honor memory/constitution.md if present.
+
   - id: local_verify
     title: Local verify
     summary: Verify the feature on this machine
+    kind: standard
     skippable: true
     artifacts:
       - id: local-test-plan
@@ -66,9 +167,6 @@ stages:
         path: local-test-results.md
         template: local-test-results.md
         required: true
-      - id: evidence
-        path: evidence/local/
-        required: false
     gate:
       type: soft
       checklist:
@@ -76,7 +174,7 @@ stages:
         - "Key edge cases covered or waived with notes"
     verify:
       commands: []
-      evidence_dir: evidence/local
+
 on_complete:
-  archive: true
+  archive: false
   domain_sync: recommend

package/defaults/workflows/hotfix.yaml

@@ -40,16 +40,12 @@ stages:
         path: local-test-results.md
         template: local-test-results.md
         required: false
-      - id: evidence
-        path: evidence/local/
-        required: false
     gate:
       type: soft
       checklist:
         - "Smoke-checked locally"
     verify:
       commands: []
-      evidence_dir: evidence/local
 on_complete:
-  archive: true
+  archive: false
   domain_sync: never

package/defaults/workflows/patch.yaml

@@ -55,9 +55,6 @@ stages:
         path: local-test-results.md
         template: local-test-results.md
         required: false
-      - id: evidence
-        path: evidence/local/
-        required: false
     gate:
       type: soft
       checklist:
@@ -65,7 +62,6 @@ stages:
         - "No obvious regressions on touched paths"
     verify:
       commands: []
-      evidence_dir: evidence/local
 on_complete:
-  archive: true
+  archive: false
   domain_sync: never

package/defaults/workflows/spike.yaml

@@ -46,5 +46,5 @@ stages:
       checklist:
         - "Clear recommendation recorded"
 on_complete:
-  archive: true
+  archive: false
   domain_sync: never

package/dist/{agents-TN7TOYF7.js → agents-BA7WVN35.js}

@@ -19,7 +19,7 @@ import {
   removeOtherAgentHosts,
   renderThinAgent,
   writeAgentHandoff
-} from "./chunk-4ZDPIYEB.js";
+} from "./chunk-M245MC6E.js";
 export {
   AGENT_INTEGRATIONS,
   AGENT_TARGET_OPTIONS,

package/dist/{chunk-4ZDPIYEB.js → chunk-M245MC6E.js}

@@ -60,6 +60,25 @@ async function copyDir(src, dest) {
     }
   }
 }
+async function copyDirSkipExisting(src, dest) {
+  await ensureDir(dest);
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = `${src}/${entry.name}`;
+    const to = `${dest}/${entry.name}`;
+    if (entry.isDirectory()) {
+      await copyDirSkipExisting(from, to);
+    } else if (!await pathExists(to)) {
+      await ensureDir(dirname(to));
+      await fs.copyFile(from, to);
+    }
+  }
+}
+async function writeTextIfMissing(path, content) {
+  if (await pathExists(path)) return false;
+  await writeText(path, content);
+  return true;
+}
 async function removePath(path) {
   await fs.rm(path, { recursive: true, force: true });
 }
@@ -87,6 +106,14 @@ var StageSchema = z.object({
   id: z.string(),
   title: z.string().optional(),
   summary: z.string().optional(),
+  /**
+   * standard — normal work stage
+   * brainstorm — optional multi-approach exploration (before design)
+   * clarify — optional Q&A before leaving a major stage
+   */
+  kind: z.enum(["standard", "brainstorm", "clarify"]).default("standard"),
+  /** When true, stage is optional (skippable); agents may skip if not needed */
+  optional: z.boolean().default(false),
   artifacts: z.array(ArtifactDefSchema).default([]),
   gate: GateSchema.default({}),
   skippable: z.boolean().default(true),
@@ -117,7 +144,7 @@ var WorkflowSchema = z.object({
     priority: z.number().default(0)
   }).optional(),
   on_complete: z.object({
-    archive: z.boolean().default(true),
+    archive: z.boolean().default(false),
     domain_sync: z.enum(["never", "recommend", "require"]).default("never")
   }).optional()
 });
@@ -137,7 +164,7 @@ var ConfigSchema = z.object({
   }).default({}),
   persistence: z.object({
     default: z.enum(["change_only", "domain_sync"]).default("change_only"),
-    archive_on_complete: z.boolean().default(true),
+    archive_on_complete: z.boolean().default(false),
     domain_sync: z.object({
       mode: z.enum(["never", "recommend", "require"]).default("never"),
       anchored_domains: z.array(z.string()).default([])
@@ -588,6 +615,7 @@ async function buildAgentPrompt(ctx, config, projectRoot) {
   }
   parts.push(`## Constraints`);
   parts.push(`- Follow artifacts in the change directory as source of truth.`);
+  parts.push(`- Honor \`memory/constitution.md\` when present (non-negotiables).`);
   parts.push(`- Do not skip ARB/decision constraints if present.`);
   parts.push(`- Local development only \u2014 verify on this machine.`);
   parts.push(`- Prefer small, reviewable commits.`);
@@ -884,7 +912,8 @@ ${role.roleLine}
 
 1. \`.sdd/active-context.md\` \u2014 current change and stage
 2. \`.sdd/protocol.md\` \u2014 SDD rules for this repo (single playbook)
-3. Active change files under \`changes/<id>/\` as listed in active-context
+3. \`memory/constitution.md\` if present \u2014 non-negotiables
+4. Active change files under \`changes/<id>/\` as listed in active-context
 
 ## Role rules
 
@@ -927,14 +956,15 @@ Also read: \`.sdd/active-context.md\`, \`.sdd/protocol.md\`, \`memory/constituti
   return outPath;
 }
 function agentKickoffMessage(opts) {
+  const event = opts.event ?? "context updated";
   return [
-    `SDD: new change started.`,
+    `SDD: ${event}.`,
     `Title: ${opts.title}`,
     `Change: ${opts.changeId}`,
     `Stage: ${opts.stage}`,
     `Read in order: .sdd/active-context.md, .sdd/handoff.md, .sdd/protocol.md, memory/constitution.md (if present).`,
-    `Fill/update current stage artifacts only under changes/${opts.changeId}/. Do not expand scope.`,
-    `When the stage is done, tell the human to run: sdd next`
+    `Do the work for the current stage only under changes/${opts.changeId}/. Do not expand scope.`,
+    `When the stage is done, tell the human to run: sdd next (or sdd verify / sdd complete as appropriate).`
   ].join(" ");
 }
 async function refreshActiveAgentContext(projectRoot) {
@@ -991,6 +1021,7 @@ This repo uses **Structured Vibe Coding** (\`sdd\`). Agents must follow this fil
 |------|--------|
 | Process state | \`changes/<id>/meta.yaml\` (workflow, stage, gates) |
 | Current task snapshot | \`.sdd/active-context.md\` |
+| Non-negotiables | \`memory/constitution.md\` if present |
 | Stable product/tech rules | \`memory/*.md\` (start at \`memory/index.md\` if present) |
 | Stage artifacts | files in \`changes/<id>/\` for the active change |
 
@@ -998,8 +1029,9 @@ This repo uses **Structured Vibe Coding** (\`sdd\`). Agents must follow this fil
 
 1. \`.sdd/active-context.md\`
 2. This file (\`.sdd/protocol.md\`)
-3. \`meta.yaml\` + artifacts for the **current stage** (and prior stages if needed)
-4. \`memory/index.md\` (documentation map) if present, then linked memory pages when architecture or conventions matter
+3. \`memory/constitution.md\` if present (non-negotiables agents must not violate)
+4. \`meta.yaml\` + artifacts for the **current stage** (and prior stages if needed)
+5. \`memory/index.md\` (documentation map) if present, then linked memory pages when architecture or conventions matter
 
 ## Stage behavior
 
@@ -1010,6 +1042,15 @@ This repo uses **Structured Vibe Coding** (\`sdd\`). Agents must follow this fil
 | tasks | Break work into implementable checklist |
 | implement | Code only for this change; follow tasks/acceptance |
 | local_verify | Check acceptance; fix only; prepare for complete |
+| brainstorm (optional) | Multiple approaches; parallel exploration; no final design yet |
+| clarify_* (optional) | Ask clarifying questions; write Q&A; or tell human to skip |
+
+## Optional stages
+
+- Stages marked **optional** / kind \`brainstorm\` or \`clarify\` may be skipped:  
+  \`sdd skip <stage_id> -r "not needed"\`
+- Do **not** invent a skip by jumping stages. \`sdd next\` blocks on empty required stubs (e.g. design.md).
+- If the tool falls back to an earlier stage, **complete that stage** before advancing again.
 
 ## Hard rules
 
@@ -1018,6 +1059,7 @@ This repo uses **Structured Vibe Coding** (\`sdd\`). Agents must follow this fil
 3. **Honor constraints** in \`arb-decision.md\`, design, and memory non-negotiables.
 4. **Local verify** is part of done when the workflow has a verify stage: \`sdd verify\`.
 5. Prefer small, reviewable diffs.
+6. **Required stage artifacts must be substantive** \u2014 not empty templates. Design cannot be skipped via empty design.md.
 
 ## Commands (human / shell)
 
@@ -1033,7 +1075,7 @@ sdd complete
 ## Out of scope for agents
 
 - Replacing CI/CD or team process tools
-- Deleting \`.sdd\` / archive history
+- Deleting \`.sdd\` / completed change history
 - Claiming complete without verify when required
 `;
 function renderAgentsMd(integ) {
@@ -1047,6 +1089,7 @@ AI coding agents are **not** the same as IDEs: VS Code, Cursor, and IntelliJ hos
 |------------|--|
 | Live task | \`.sdd/active-context.md\` |
 | Playbook | \`.sdd/protocol.md\` |
+| Constitution | \`memory/constitution.md\` if present |
 | Doc map (stable) | \`memory/index.md\` if present |
 
 | AI agent | Files |
@@ -1086,6 +1129,8 @@ export {
   listDirs,
   listFiles,
   copyDir,
+  copyDirSkipExisting,
+  writeTextIfMissing,
   removePath,
   isInitialized,
   loadConfig,

package/dist/index.d.ts

@@ -49,6 +49,14 @@ declare const StageSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
     summary: z.ZodOptional<z.ZodString>;
+    /**
+     * standard — normal work stage
+     * brainstorm — optional multi-approach exploration (before design)
+     * clarify — optional Q&A before leaving a major stage
+     */
+    kind: z.ZodDefault<z.ZodEnum<["standard", "brainstorm", "clarify"]>>;
+    /** When true, stage is optional (skippable); agents may skip if not needed */
+    optional: z.ZodDefault<z.ZodBoolean>;
     artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         path: z.ZodString;
@@ -131,6 +139,8 @@ declare const StageSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
+    kind: "standard" | "brainstorm" | "clarify";
+    optional: boolean;
     artifacts: {
         path: string;
         id: string;
@@ -165,6 +175,8 @@ declare const StageSchema: z.ZodObject<{
     id: string;
     title?: string | undefined;
     summary?: string | undefined;
+    kind?: "standard" | "brainstorm" | "clarify" | undefined;
+    optional?: boolean | undefined;
     artifacts?: {
         path: string;
         id: string;
@@ -202,6 +214,14 @@ declare const WorkflowSchema: z.ZodObject<{
         id: z.ZodString;
         title: z.ZodOptional<z.ZodString>;
         summary: z.ZodOptional<z.ZodString>;
+        /**
+         * standard — normal work stage
+         * brainstorm — optional multi-approach exploration (before design)
+         * clarify — optional Q&A before leaving a major stage
+         */
+        kind: z.ZodDefault<z.ZodEnum<["standard", "brainstorm", "clarify"]>>;
+        /** When true, stage is optional (skippable); agents may skip if not needed */
+        optional: z.ZodDefault<z.ZodBoolean>;
         artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             path: z.ZodString;
@@ -284,6 +304,8 @@ declare const WorkflowSchema: z.ZodObject<{
         }>>;
     }, "strip", z.ZodTypeAny, {
         id: string;
+        kind: "standard" | "brainstorm" | "clarify";
+        optional: boolean;
         artifacts: {
             path: string;
             id: string;
@@ -318,6 +340,8 @@ declare const WorkflowSchema: z.ZodObject<{
         id: string;
         title?: string | undefined;
         summary?: string | undefined;
+        kind?: "standard" | "brainstorm" | "clarify" | undefined;
+        optional?: boolean | undefined;
         artifacts?: {
             path: string;
             id: string;
@@ -397,6 +421,8 @@ declare const WorkflowSchema: z.ZodObject<{
     version: number;
     stages: {
         id: string;
+        kind: "standard" | "brainstorm" | "clarify";
+        optional: boolean;
         artifacts: {
             path: string;
             id: string;
@@ -448,6 +474,8 @@ declare const WorkflowSchema: z.ZodObject<{
         id: string;
         title?: string | undefined;
         summary?: string | undefined;
+        kind?: "standard" | "brainstorm" | "clarify" | undefined;
+        optional?: boolean | undefined;
         artifacts?: {
             path: string;
             id: string;
@@ -621,6 +649,14 @@ declare const ChangeMetaSchema: z.ZodObject<{
             id: z.ZodString;
             title: z.ZodOptional<z.ZodString>;
             summary: z.ZodOptional<z.ZodString>;
+            /**
+             * standard — normal work stage
+             * brainstorm — optional multi-approach exploration (before design)
+             * clarify — optional Q&A before leaving a major stage
+             */
+            kind: z.ZodDefault<z.ZodEnum<["standard", "brainstorm", "clarify"]>>;
+            /** When true, stage is optional (skippable); agents may skip if not needed */
+            optional: z.ZodDefault<z.ZodBoolean>;
             artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 id: z.ZodString;
                 path: z.ZodString;
@@ -703,6 +739,8 @@ declare const ChangeMetaSchema: z.ZodObject<{
             }>>;
         }, "strip", z.ZodTypeAny, {
             id: string;
+            kind: "standard" | "brainstorm" | "clarify";
+            optional: boolean;
             artifacts: {
                 path: string;
                 id: string;
@@ -737,6 +775,8 @@ declare const ChangeMetaSchema: z.ZodObject<{
             id: string;
             title?: string | undefined;
             summary?: string | undefined;
+            kind?: "standard" | "brainstorm" | "clarify" | undefined;
+            optional?: boolean | undefined;
             artifacts?: {
                 path: string;
                 id: string;
@@ -771,6 +811,8 @@ declare const ChangeMetaSchema: z.ZodObject<{
         skip_stages: string[];
         extra_stages: {
             id: string;
+            kind: "standard" | "brainstorm" | "clarify";
+            optional: boolean;
             artifacts: {
                 path: string;
                 id: string;
@@ -809,6 +851,8 @@ declare const ChangeMetaSchema: z.ZodObject<{
             id: string;
             title?: string | undefined;
             summary?: string | undefined;
+            kind?: "standard" | "brainstorm" | "clarify" | undefined;
+            optional?: boolean | undefined;
             artifacts?: {
                 path: string;
                 id: string;
@@ -923,6 +967,8 @@ declare const ChangeMetaSchema: z.ZodObject<{
         skip_stages: string[];
         extra_stages: {
             id: string;
+            kind: "standard" | "brainstorm" | "clarify";
+            optional: boolean;
             artifacts: {
                 path: string;
                 id: string;
@@ -999,6 +1045,8 @@ declare const ChangeMetaSchema: z.ZodObject<{
             id: string;
             title?: string | undefined;
             summary?: string | undefined;
+            kind?: "standard" | "brainstorm" | "clarify" | undefined;
+            optional?: boolean | undefined;
             artifacts?: {
                 path: string;
                 id: string;
@@ -1120,17 +1168,34 @@ declare function clearActiveIf(projectRoot: string, config: Config, changeId: st
 declare function setActiveChange(projectRoot: string, config: Config, changeId: string): Promise<void>;
 declare function resolveChangeId(projectRoot: string, config: Config, changeId?: string): Promise<string>;
 
+/**
+ * Prior non-skipped stages with required work must be complete before leaving
+ * the current stage (prevents jumping intent → tasks with empty design).
+ */
+declare function incompletePriorStageErrors(ctx: ChangeContext): Promise<string[]>;
 /** Artifact + gate + verify checks before leaving the current stage. */
 declare function canLeaveStage(ctx: ChangeContext, config: Config): Promise<{
     ok: boolean;
     errors: string[];
     warnings: string[];
 }>;
+/**
+ * If meta.stage points past incomplete required work, return the earliest
+ * incomplete stage id to fall back to (e.g. design).
+ */
+declare function fallbackIncompleteStageId(ctx: ChangeContext): Promise<string | null>;
 declare function approveGate(projectRoot: string, config: Config, changeId: string, stageId: string | undefined, note?: string, status?: "approved" | "waived" | "failed"): Promise<ChangeContext>;
 
 declare function formatStatus(ctx: ChangeContext): string;
 declare function buildAgentPrompt(ctx: ChangeContext, config: Config, projectRoot: string): Promise<string>;
 
+/**
+ * Artifact content quality — existence alone is not "stage complete"
+ * (templates are materialized on stage entry and would otherwise auto-pass).
+ */
+/** Strip comments/headings/empty bullets; require real prose. */
+declare function isSubstantiveArtifactContent(content: string): boolean;
+
 interface CreateChangeInput {
     projectRoot: string;
     config: Config;
@@ -1276,11 +1341,13 @@ declare function agentKickoffMessage(opts: {
     title: string;
     stage: string;
     changeId: string;
+    /** What just happened, e.g. "new change", "advanced to implement" */
+    event?: string;
 }): string;
 /** Write .sdd/active-context.md for the current change. */
 declare function refreshActiveAgentContext(projectRoot: string): Promise<string | null>;
 /** Single playbook — only long agent-facing content we author once. */
-declare const PROTOCOL_MD = "# SDD protocol\n\nThis repo uses **Structured Vibe Coding** (`sdd`). Agents must follow this file plus `.sdd/active-context.md`. Do not invent a parallel process.\n\n## Source of truth\n\n| What | Where |\n|------|--------|\n| Process state | `changes/<id>/meta.yaml` (workflow, stage, gates) |\n| Current task snapshot | `.sdd/active-context.md` |\n| Stable product/tech rules | `memory/*.md` (start at `memory/index.md` if present) |\n| Stage artifacts | files in `changes/<id>/` for the active change |\n\n## Required read order\n\n1. `.sdd/active-context.md`\n2. This file (`.sdd/protocol.md`)\n3. `meta.yaml` + artifacts for the **current stage** (and prior stages if needed)\n4. `memory/index.md` (documentation map) if present, then linked memory pages when architecture or conventions matter\n\n## Stage behavior\n\n| Stage kind | Agent focus |\n|------------|-------------|\n| intent / feature / stories | Clarify scope; write short artifacts |\n| design / lld / db / research / hl_arb | Specs and decisions; minimal product code |\n| tasks | Break work into implementable checklist |\n| implement | Code only for this change; follow tasks/acceptance |\n| local_verify | Check acceptance; fix only; prepare for complete |\n\n## Hard rules\n\n1. **Do not skip hard gates.** If blocked, tell the human to run `sdd gate approve` (or fix the gate).\n2. **Stay in scope** of the active change title/intent. No drive-by refactors or new features.\n3. **Honor constraints** in `arb-decision.md`, design, and memory non-negotiables.\n4. **Local verify** is part of done when the workflow has a verify stage: `sdd verify`.\n5. Prefer small, reviewable diffs.\n\n## Commands (human / shell)\n\n```bash\nsdd status\nsdd next\nsdd agent              # print handoff\nsdd agents refresh     # refresh active-context.md\nsdd verify\nsdd complete\n```\n\n## Out of scope for agents\n\n- Replacing CI/CD or team process tools\n- Deleting `.sdd` / archive history\n- Claiming complete without verify when required\n";
+declare const PROTOCOL_MD = "# SDD protocol\n\nThis repo uses **Structured Vibe Coding** (`sdd`). Agents must follow this file plus `.sdd/active-context.md`. Do not invent a parallel process.\n\n## Source of truth\n\n| What | Where |\n|------|--------|\n| Process state | `changes/<id>/meta.yaml` (workflow, stage, gates) |\n| Current task snapshot | `.sdd/active-context.md` |\n| Non-negotiables | `memory/constitution.md` if present |\n| Stable product/tech rules | `memory/*.md` (start at `memory/index.md` if present) |\n| Stage artifacts | files in `changes/<id>/` for the active change |\n\n## Required read order\n\n1. `.sdd/active-context.md`\n2. This file (`.sdd/protocol.md`)\n3. `memory/constitution.md` if present (non-negotiables agents must not violate)\n4. `meta.yaml` + artifacts for the **current stage** (and prior stages if needed)\n5. `memory/index.md` (documentation map) if present, then linked memory pages when architecture or conventions matter\n\n## Stage behavior\n\n| Stage kind | Agent focus |\n|------------|-------------|\n| intent / feature / stories | Clarify scope; write short artifacts |\n| design / lld / db / research / hl_arb | Specs and decisions; minimal product code |\n| tasks | Break work into implementable checklist |\n| implement | Code only for this change; follow tasks/acceptance |\n| local_verify | Check acceptance; fix only; prepare for complete |\n| brainstorm (optional) | Multiple approaches; parallel exploration; no final design yet |\n| clarify_* (optional) | Ask clarifying questions; write Q&A; or tell human to skip |\n\n## Optional stages\n\n- Stages marked **optional** / kind `brainstorm` or `clarify` may be skipped:  \n  `sdd skip <stage_id> -r \"not needed\"`\n- Do **not** invent a skip by jumping stages. `sdd next` blocks on empty required stubs (e.g. design.md).\n- If the tool falls back to an earlier stage, **complete that stage** before advancing again.\n\n## Hard rules\n\n1. **Do not skip hard gates.** If blocked, tell the human to run `sdd gate approve` (or fix the gate).\n2. **Stay in scope** of the active change title/intent. No drive-by refactors or new features.\n3. **Honor constraints** in `arb-decision.md`, design, and memory non-negotiables.\n4. **Local verify** is part of done when the workflow has a verify stage: `sdd verify`.\n5. Prefer small, reviewable diffs.\n6. **Required stage artifacts must be substantive** \u2014 not empty templates. Design cannot be skipped via empty design.md.\n\n## Commands (human / shell)\n\n```bash\nsdd status\nsdd next\nsdd agent              # print handoff\nsdd agents refresh     # refresh active-context.md\nsdd verify\nsdd complete\n```\n\n## Out of scope for agents\n\n- Replacing CI/CD or team process tools\n- Deleting `.sdd` / completed change history\n- Claiming complete without verify when required\n";
 
 interface InitOptions {
     projectRoot: string;
@@ -1311,7 +1378,8 @@ interface VerifyResult {
         output: string;
     }[];
     checklist: string[];
-    evidencePath: string;
+    /** Path to evidence dir when configured; null when no evidence_dir is set */
+    evidencePath: string | null;
     /** False if any required command failed or was not run when required */
     ok: boolean;
 }
@@ -1346,6 +1414,13 @@ declare function writeYaml(path: string, data: unknown): Promise<void>;
 declare function listDirs(path: string): Promise<string[]>;
 declare function listFiles(path: string): Promise<string[]>;
 declare function copyDir(src: string, dest: string): Promise<void>;
+/**
+ * Copy directory tree but never overwrite existing files (stable docs like
+ * memory/constitution.md survive `sdd init --force`).
+ */
+declare function copyDirSkipExisting(src: string, dest: string): Promise<void>;
+/** Write only when the path does not already exist. */
+declare function writeTextIfMissing(path: string, content: string): Promise<boolean>;
 declare function removePath(path: string): Promise<void>;
 
-export { AGENT_INTEGRATIONS, AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdvanceResult, type AgentIntegration, type AgentTarget, type AgentTargetOption, type ArtifactDef, ArtifactDefSchema, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_INIT_INTEGRATION, type Gate, GateSchema, type InitOptions, type InitResult, type InstallAgentOptions, type InstallAgentResult, type InstallAgentsOptions, type InstallAgentsResult, type InstalledAgentSnapshot, PROTOCOL_MD, SDD_AGENT_ROLES, SDD_DIR, type SddAgentRole, type SddAgentRoleId, type Stage, StageSchema, VerifyCommandSchema, type VerifyResult, type Workflow, WorkflowSchema, activePointerPath, activeStages, advanceStage, agentHostPaths, agentKickoffMessage, approveGate, archiveDir, buildAgentPrompt, buildContext, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, clearActiveIf, completeChange, configPath, copyDir, createChange, defaultConfig, defaultMemoryDir, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, domainsDir, ensureDir, firstActiveStageId, formatStatus, getActiveChangeId, getIntegration, getStage, inferComplexity, initProject, installAgentIntegration, installAgentIntegrations, integrationKeyFor, isInitialized, isStageSkipped, listChanges, listDirs, listFiles, listWorkflowNames, loadChangeMeta, loadConfig, loadInstalledAgent, loadWorkflow, memoryDir, nextStageId, nowIso, optionForTarget, parseAgentTargets, parseIntegration, pathExists, readText, readYaml, recommendWorkflow, refreshActiveAgentContext, removeOtherAgentHosts, removePath, renderThinAgent, resolveChangeId, resolveStages, runLocalVerify, saveChangeMeta, saveConfig, sddRoot, setActiveChange, shouldAutoSkip, skipStage, slugify, switchWorkflow, templatesDir, todayIsoDate, uniqueChangeDirName, workflowsDir, writeAgentHandoff, writeText, writeYaml };
+export { AGENT_INTEGRATIONS, AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdvanceResult, type AgentIntegration, type AgentTarget, type AgentTargetOption, type ArtifactDef, ArtifactDefSchema, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_INIT_INTEGRATION, type Gate, GateSchema, type InitOptions, type InitResult, type InstallAgentOptions, type InstallAgentResult, type InstallAgentsOptions, type InstallAgentsResult, type InstalledAgentSnapshot, PROTOCOL_MD, SDD_AGENT_ROLES, SDD_DIR, type SddAgentRole, type SddAgentRoleId, type Stage, StageSchema, VerifyCommandSchema, type VerifyResult, type Workflow, WorkflowSchema, activePointerPath, activeStages, advanceStage, agentHostPaths, agentKickoffMessage, approveGate, archiveDir, buildAgentPrompt, buildContext, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, clearActiveIf, completeChange, configPath, copyDir, copyDirSkipExisting, createChange, defaultConfig, defaultMemoryDir, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, domainsDir, ensureDir, fallbackIncompleteStageId, firstActiveStageId, formatStatus, getActiveChangeId, getIntegration, getStage, incompletePriorStageErrors, inferComplexity, initProject, installAgentIntegration, installAgentIntegrations, integrationKeyFor, isInitialized, isStageSkipped, isSubstantiveArtifactContent, listChanges, listDirs, listFiles, listWorkflowNames, loadChangeMeta, loadConfig, loadInstalledAgent, loadWorkflow, memoryDir, nextStageId, nowIso, optionForTarget, parseAgentTargets, parseIntegration, pathExists, readText, readYaml, recommendWorkflow, refreshActiveAgentContext, removeOtherAgentHosts, removePath, renderThinAgent, resolveChangeId, resolveStages, runLocalVerify, saveChangeMeta, saveConfig, sddRoot, setActiveChange, shouldAutoSkip, skipStage, slugify, switchWorkflow, templatesDir, todayIsoDate, uniqueChangeDirName, workflowsDir, writeAgentHandoff, writeText, writeTextIfMissing, writeYaml };

package/dist/index.js

@@ -27,6 +27,7 @@ import {
   clearActiveIf,
   configPath,
   copyDir,
+  copyDirSkipExisting,
   defaultConfig,
   domainsDir,
   ensureDir,
@@ -77,14 +78,84 @@ import {
   workflowsDir,
   writeAgentHandoff,
   writeText,
+  writeTextIfMissing,
   writeYaml
-} from "./chunk-4ZDPIYEB.js";
+} from "./chunk-M245MC6E.js";
 
 // src/change.ts
 import { join as join2 } from "pathe";
 
 // src/stage-gates.ts
 import { join } from "pathe";
+
+// src/artifacts.ts
+function isSubstantiveArtifactContent(content) {
+  const stripped = content.replace(/<!--[\s\S]*?-->/g, "").replace(/^#{1,6}\s+.*$/gm, "").replace(/^>\s.*$/gm, "").replace(/^\s*[-*+]\s*$/gm, "").replace(/^\s*[-*+]\s*\.\.\.\s*$/gm, "").replace(/^\s*[-*+]\s*TBD\s*$/gim, "").replace(/^\s*[-*+]\s*TODO\s*$/gim, "").replace(/^\s*\|.*\|\s*$/gm, "").replace(/`+/g, "").trim();
+  if (stripped.length < 48) return false;
+  const meaningful = stripped.replace(/[-–—_.\s]/g, "").replace(/\b(TBD|TODO|N\/A|none|n\/a)\b/gi, "");
+  return meaningful.length >= 32;
+}
+function incompleteArtifactReason(path, content) {
+  if (content == null) {
+    return `Missing required artifact: ${path}`;
+  }
+  if (!isSubstantiveArtifactContent(content)) {
+    return `Required artifact still incomplete (looks like empty template/stub): ${path}. Fill it with real content, or skip this stage with \`sdd skip <stage> -r "\u2026"\` if optional.`;
+  }
+  return null;
+}
+
+// src/stage-gates.ts
+async function checkRequiredArtifacts(changePath2, stageId, artifacts) {
+  const errors = [];
+  for (const artifact of artifacts) {
+    if (!artifact.required) continue;
+    if (artifact.path.endsWith("/")) {
+      const target2 = join(changePath2, artifact.path);
+      if (!await pathExists(target2)) {
+        errors.push(`Missing required directory: ${artifact.path} (stage ${stageId})`);
+      }
+      continue;
+    }
+    const target = join(changePath2, artifact.path);
+    if (!await pathExists(target)) {
+      errors.push(incompleteArtifactReason(artifact.path, null));
+      continue;
+    }
+    const content = await readText(target);
+    const reason = incompleteArtifactReason(artifact.path, content);
+    if (reason) {
+      errors.push(`${reason} (stage ${stageId})`);
+    }
+  }
+  return errors;
+}
+async function incompletePriorStageErrors(ctx) {
+  const errors = [];
+  const stages = activeStages(ctx.workflow, ctx.meta);
+  const currentIdx = stages.findIndex((s) => s.id === ctx.meta.stage);
+  if (currentIdx <= 0) return errors;
+  for (let i = 0; i < currentIdx; i++) {
+    const stage = stages[i];
+    if (isStageSkipped(ctx.meta, stage.id) || shouldAutoSkip(stage, ctx.meta)) {
+      continue;
+    }
+    const required = stage.artifacts.filter((a) => a.required);
+    if (!required.length && stage.optional) continue;
+    const stageErrors = await checkRequiredArtifacts(
+      ctx.path,
+      stage.id,
+      stage.artifacts
+    );
+    if (stageErrors.length) {
+      errors.push(
+        `Prior stage "${stage.id}" is not complete \u2014 finish it or \`sdd skip ${stage.id} -r "\u2026"\` if optional.`
+      );
+      errors.push(...stageErrors);
+    }
+  }
+  return errors;
+}
 async function canLeaveStage(ctx, config) {
   const stage = getStage(ctx.workflow, ctx.meta, ctx.meta.stage);
   const errors = [];
@@ -92,13 +163,10 @@ async function canLeaveStage(ctx, config) {
   if (!stage) {
     return { ok: false, errors: [`Unknown stage: ${ctx.meta.stage}`], warnings };
   }
-  for (const artifact of stage.artifacts) {
-    if (!artifact.required) continue;
-    const target = join(ctx.path, artifact.path);
-    if (!await pathExists(target)) {
-      errors.push(`Missing required artifact: ${artifact.path}`);
-    }
-  }
+  errors.push(...await incompletePriorStageErrors(ctx));
+  errors.push(
+    ...await checkRequiredArtifacts(ctx.path, stage.id, stage.artifacts)
+  );
   const declared = stage.gate?.type ?? "soft";
   let effectiveGate = declared;
   if (config.policy.gates === "hard" && declared === "soft") {
@@ -132,8 +200,27 @@ async function canLeaveStage(ctx, config) {
       );
     }
   }
+  if (stage.optional || stage.kind === "clarify" || stage.kind === "brainstorm") {
+    warnings.push(
+      `Stage "${stage.id}" is optional (${stage.kind ?? "optional"}). Skip with: sdd skip ${stage.id} -r "not needed"`
+    );
+  }
   return { ok: errors.length === 0, errors, warnings };
 }
+async function fallbackIncompleteStageId(ctx) {
+  const stages = activeStages(ctx.workflow, ctx.meta);
+  for (const stage of stages) {
+    if (stage.id === ctx.meta.stage) break;
+    if (isStageSkipped(ctx.meta, stage.id) || shouldAutoSkip(stage, ctx.meta)) {
+      continue;
+    }
+    const required = stage.artifacts.filter((a) => a.required);
+    if (!required.length && stage.optional) continue;
+    const errs = await checkRequiredArtifacts(ctx.path, stage.id, stage.artifacts);
+    if (errs.length) return stage.id;
+  }
+  return null;
+}
 async function approveGate(projectRoot, config, changeId, stageId, note, status = "approved") {
   const ctx = await buildContext(projectRoot, config, changeId);
   const id = stageId ?? ctx.meta.stage;
@@ -190,7 +277,7 @@ async function createChange(input) {
   await materializeStageArtifacts(projectRoot, config, id, workflow, meta, firstStage);
   await setActiveChange(projectRoot, config, id);
   try {
-    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-TN7TOYF7.js");
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-BA7WVN35.js");
     await refreshActiveAgentContext2(projectRoot);
   } catch {
   }
@@ -252,11 +339,45 @@ function defaultArtifactContent(artifactId, meta, stage, workflow) {
 `;
 }
 async function advanceStage(projectRoot, config, changeId, opts) {
-  const ctx = await buildContext(projectRoot, config, changeId);
+  let ctx = await buildContext(projectRoot, config, changeId);
   const warnings = [];
   if (ctx.meta.status === "completed") {
     throw new Error("Change is already completed.");
   }
+  if (!opts?.force) {
+    const fallback = await fallbackIncompleteStageId(ctx);
+    if (fallback && fallback !== ctx.meta.stage) {
+      const from2 = ctx.meta.stage;
+      ctx.meta.stage = fallback;
+      await saveChangeMeta(projectRoot, config, ctx.meta);
+      const stage2 = getStage(ctx.workflow, ctx.meta, fallback);
+      const artifactsCreated2 = await materializeStageArtifacts(
+        projectRoot,
+        config,
+        changeId,
+        ctx.workflow,
+        ctx.meta,
+        stage2
+      );
+      try {
+        const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-BA7WVN35.js");
+        await refreshActiveAgentContext2(projectRoot);
+      } catch {
+      }
+      const updated2 = await buildContext(projectRoot, config, changeId);
+      return {
+        ctx: updated2,
+        from: from2,
+        to: fallback,
+        completed: false,
+        artifactsCreated: artifactsCreated2,
+        warnings: [
+          ...warnings,
+          `Fell back to incomplete stage "${fallback}" (required work not done). Finish it before advancing.`
+        ]
+      };
+    }
+  }
   const check = await canLeaveStage(ctx, config);
   warnings.push(...check.warnings);
   if (!check.ok && !opts?.force) {
@@ -286,7 +407,7 @@ async function advanceStage(projectRoot, config, changeId, opts) {
     stage
   );
   try {
-    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-TN7TOYF7.js");
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-BA7WVN35.js");
     await refreshActiveAgentContext2(projectRoot);
   } catch {
   }
@@ -481,9 +602,9 @@ async function initProject(opts) {
   await ensureDir(mDest);
   const mSrc = defaultMemoryDir();
   if (await pathExists(mSrc)) {
-    await copyDir(mSrc, mDest);
+    await copyDirSkipExisting(mSrc, mDest);
   } else {
-    await writeText(
+    await writeTextIfMissing(
       join4(mDest, "index.md"),
       `# Documentation map
 
@@ -492,34 +613,93 @@ Parent page for **stable** project docs. Start here, then open only what you nee
 | Topic | File |
 |-------|------|
 | Product | [product.md](product.md) |
+| Constitution (non-negotiables) | [constitution.md](constitution.md) |
 | Architecture | [architecture.md](architecture.md) |
 | Conventions | [conventions.md](conventions.md) |
 
 Active work: \`.sdd/active-context.md\` and \`changes/<id>/\`.
 `
     );
-    await writeText(
+    await writeTextIfMissing(
       join4(mDest, "product.md"),
       "# Product\n\n<!-- What are you building? -->\n"
     );
-    await writeText(
+    await writeTextIfMissing(
+      join4(mDest, "constitution.md"),
+      `# Constitution
+
+<!-- Non-negotiables agents must not violate. Broader style lives in conventions.md. -->
+
+## Principles
+
+-
+
+## Stack & tooling
+
+-
+
+## Testing
+
+-
+
+## Security
+
+-
+
+## Process
+
+-
+`
+    );
+    await writeTextIfMissing(
       join4(mDest, "architecture.md"),
       "# Architecture\n\n<!-- High-level system shape -->\n"
     );
-    await writeText(
+    await writeTextIfMissing(
       join4(mDest, "conventions.md"),
       "# Conventions\n\n<!-- Coding and process conventions -->\n"
     );
   }
+  if (!await pathExists(join4(mDest, "constitution.md"))) {
+    const fromDefault = join4(mSrc, "constitution.md");
+    if (await pathExists(fromDefault)) {
+      await copyDirSkipExisting(mSrc, mDest);
+    } else {
+      await writeTextIfMissing(
+        join4(mDest, "constitution.md"),
+        `# Constitution
+
+<!-- Non-negotiables agents must not violate. Broader style lives in conventions.md. -->
+
+## Principles
+
+-
+
+## Stack & tooling
+
+-
+
+## Testing
+
+-
+
+## Security
+
+-
+
+## Process
+
+-
+`
+      );
+    }
+  }
   created.push(mDest);
   await ensureDir(changesDir(projectRoot, config));
-  await ensureDir(archiveDir(projectRoot, config));
   await ensureDir(domainsDir(projectRoot, config));
   created.push(changesDir(projectRoot, config));
-  created.push(archiveDir(projectRoot, config));
   created.push(domainsDir(projectRoot, config));
   await writeText(join4(changesDir(projectRoot, config), ".gitkeep"), "");
-  await writeText(join4(archiveDir(projectRoot, config), ".gitkeep"), "");
   await writeText(join4(domainsDir(projectRoot, config), ".gitkeep"), "");
   const sddReadme = join4(root, "README.md");
   if (!await pathExists(sddReadme) || force) {
@@ -534,7 +714,8 @@ This directory configures local Spec-Driven Development for this repo.
 - \`templates/\` \u2014 markdown templates for stage artifacts
 - \`protocol.md\` / \`active-context.md\` \u2014 agent playbook + live task (after agent install)
 
-Work lives in \`../changes/\` and completed work in \`../archive/\`.
+Work lives in \`../changes/<id>/\`. Completed packs stay there with \`status: completed\`.
+Promote lasting decisions into \`../memory/\`. (Archive-on-complete is opt-in.)
 
 **Documentation map (stable):** \`../memory/index.md\`  
 **Change-scoped docs:** \`../changes/<id>/\`
@@ -590,14 +771,59 @@ function runCommand(command, cwd) {
     });
   });
 }
+function isToolGeneratedResults(content) {
+  const trimmed = content.trim();
+  if (!trimmed) return true;
+  if (trimmed.includes("{{") || trimmed.includes("TODO")) return true;
+  if (trimmed.startsWith("# Local verify results")) return true;
+  return false;
+}
+function buildSummaryLines(title, stageId, ok, results, checklist) {
+  const lines = [
+    `# Local verify results`,
+    ``,
+    `> Change: ${title}`,
+    `> Stage: ${stageId}`,
+    `> At: ${nowIso()}`,
+    `> Overall: ${ok ? "PASS" : "FAIL"}`,
+    ``,
+    `## Commands`,
+    ``
+  ];
+  if (results.length === 0) {
+    lines.push(`_No commands configured for this stage. Complete the checklist manually._`);
+    lines.push("");
+  } else {
+    for (const r of results) {
+      lines.push(`### ${r.name}`);
+      lines.push(`- Command: \`${r.command}\``);
+      lines.push(`- Exit: ${r.exitCode}`);
+      lines.push("");
+    }
+  }
+  lines.push(`## Checklist`);
+  lines.push("");
+  for (const item of checklist) {
+    lines.push(`- [ ] ${item}`);
+  }
+  lines.push("");
+  lines.push(`## Notes`);
+  lines.push("");
+  lines.push(`-`);
+  lines.push("");
+  return lines;
+}
 async function runLocalVerify(projectRoot, config, changeId, opts) {
   const ctx = await buildContext(projectRoot, config, changeId);
   const stage = getStage(ctx.workflow, ctx.meta, ctx.meta.stage);
   if (!stage) {
     throw new Error(`Unknown stage: ${ctx.meta.stage}`);
   }
-  const evidenceDir = stage.verify?.evidence_dir != null ? join5(ctx.path, stage.verify.evidence_dir) : join5(ctx.path, "evidence", "local");
-  await ensureDir(evidenceDir);
+  const evidenceDirRaw = stage.verify?.evidence_dir?.trim();
+  const evidenceDir = evidenceDirRaw && evidenceDirRaw.length > 0 ? join5(ctx.path, evidenceDirRaw) : null;
+  if (evidenceDir) {
+    await ensureDir(evidenceDir);
+  }
   const results = [];
   const runCommands = opts?.runCommands !== false;
   const commands = stage.verify?.commands ?? [];
@@ -610,15 +836,17 @@ async function runLocalVerify(projectRoot, config, changeId, opts) {
         exitCode,
         output: output.slice(0, 5e4)
       });
-      const logPath = join5(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
-      await writeText(
-        logPath,
-        `# ${cmd.name}
+      if (evidenceDir) {
+        const logPath = join5(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
+        await writeText(
+          logPath,
+          `# ${cmd.name}
 $ ${cmd.run}
 exit: ${exitCode}
 
 ${output}`
-      );
+        );
+      }
     }
   }
   const required = commands.filter((c) => c.required);
@@ -637,46 +865,44 @@ ${output}`
   }
   const checklist = stage.gate?.checklist ?? [];
   const summaryPath = join5(ctx.path, "local-test-results.md");
-  const lines = [
-    `# Local verify results`,
-    ``,
-    `> Change: ${ctx.meta.title}`,
-    `> Stage: ${stage.id}`,
-    `> At: ${nowIso()}`,
-    `> Overall: ${ok ? "PASS" : "FAIL"}`,
-    ``,
-    `## Commands`,
-    ``
-  ];
-  if (results.length === 0) {
-    lines.push(`_No commands configured for this stage. Complete the checklist manually._`);
-    lines.push("");
-  } else {
-    for (const r of results) {
-      lines.push(`### ${r.name}`);
-      lines.push(`- Command: \`${r.command}\``);
-      lines.push(`- Exit: ${r.exitCode}`);
-      lines.push("");
-    }
-  }
-  lines.push(`## Checklist`);
-  lines.push("");
-  for (const item of checklist) {
-    lines.push(`- [ ] ${item}`);
-  }
-  lines.push("");
-  lines.push(`## Notes`);
-  lines.push("");
-  lines.push(`-`);
-  lines.push("");
+  const lines = buildSummaryLines(ctx.meta.title, stage.id, ok, results, checklist);
+  const summaryBody = lines.join("\n");
   if (await pathExists(summaryPath)) {
-    const stamp = nowIso();
-    await writeText(
-      join5(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`),
-      lines.join("\n")
-    );
+    const existing = await readText(summaryPath);
+    if (isToolGeneratedResults(existing)) {
+      await writeText(summaryPath, summaryBody);
+    } else {
+      const stamp = nowIso();
+      const append = [
+        ``,
+        `---`,
+        ``,
+        `## Latest run (${stamp})`,
+        ``,
+        `> Overall: ${ok ? "PASS" : "FAIL"}`,
+        `> Stage: ${stage.id}`,
+        ``
+      ];
+      if (results.length === 0) {
+        append.push(`_No commands configured for this stage._`);
+        append.push("");
+      } else {
+        for (const r of results) {
+          append.push(`- **${r.name}**: exit ${r.exitCode} (\`${r.command}\`)`);
+        }
+        append.push("");
+      }
+      await writeText(summaryPath, existing.trimEnd() + "\n" + append.join("\n"));
+    }
+    if (evidenceDir) {
+      const stamp = nowIso();
+      await writeText(
+        join5(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`),
+        summaryBody
+      );
+    }
   } else {
-    await writeText(summaryPath, lines.join("\n"));
+    await writeText(summaryPath, summaryBody);
   }
   ctx.meta.verify_results = {
     ...ctx.meta.verify_results,
@@ -728,6 +954,7 @@ export {
   completeChange,
   configPath,
   copyDir,
+  copyDirSkipExisting,
   createChange,
   defaultConfig,
   defaultMemoryDir,
@@ -736,11 +963,13 @@ export {
   defaultsRoot,
   domainsDir,
   ensureDir,
+  fallbackIncompleteStageId,
   firstActiveStageId,
   formatStatus,
   getActiveChangeId,
   getIntegration,
   getStage,
+  incompletePriorStageErrors,
   inferComplexity,
   initProject,
   installAgentIntegration,
@@ -748,6 +977,7 @@ export {
   integrationKeyFor,
   isInitialized,
   isStageSkipped,
+  isSubstantiveArtifactContent,
   listChanges,
   listDirs,
   listFiles,
@@ -787,5 +1017,6 @@ export {
   workflowsDir,
   writeAgentHandoff,
   writeText,
+  writeTextIfMissing,
   writeYaml
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-vibe-coding/core",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Core engine for structured vibe coding (local-first Spec-Driven Development)",
   "type": "module",
   "main": "./dist/index.js",