@deksden-com/dd-flow-cli 0.3.1 → 0.4.1

package/dist/domain/validation.js

@@ -73,10 +73,44 @@ function validatePlanItem(input, index) {
         owner: requireString(item.owner, `items[${index}].owner`),
         summary: typeof item.summary === "string" ? item.summary : "",
         evidence: item.evidence,
+        ...(item.semantic_spine ? { semantic_spine: validateSemanticSpine(item.semantic_spine, id) } : {}),
+        ...(item.execution_context ? { execution_context: validateExecutionContext(item.execution_context, id) } : {}),
         ...(typeof item.block_reason === "string" ? { block_reason: item.block_reason } : {}),
         ...(typeof item.user_required === "boolean" ? { user_required: item.user_required } : {})
     };
 }
+function validateExecutionContext(input, itemId) {
+    const context = requireRecord(input, `Plan item ${itemId} execution_context`);
+    return {
+        prompt_profile: requireString(context.prompt_profile, `Plan item ${itemId} execution_context.prompt_profile`),
+        required_read: requireStringArray(context.required_read, `Plan item ${itemId} execution_context.required_read`),
+        discovery_boundary: requireStringArray(context.discovery_boundary, `Plan item ${itemId} execution_context.discovery_boundary`),
+        write_scope: requireStringArray(context.write_scope, `Plan item ${itemId} execution_context.write_scope`),
+        checks: requireStringArray(context.checks, `Plan item ${itemId} execution_context.checks`)
+    };
+}
+function validateSemanticSpine(input, itemId) {
+    const spine = requireRecord(input, `Plan item ${itemId} semantic_spine`);
+    return {
+        user_outcome: requireString(spine.user_outcome, `Plan item ${itemId} semantic_spine.user_outcome`),
+        component_responsibility: requireString(spine.component_responsibility, `Plan item ${itemId} semantic_spine.component_responsibility`),
+        must_preserve: requireStringArray(spine.must_preserve, `Plan item ${itemId} semantic_spine.must_preserve`),
+        non_goals: requireStringArray(spine.non_goals, `Plan item ${itemId} semantic_spine.non_goals`),
+        acceptance_contribution: requireString(spine.acceptance_contribution, `Plan item ${itemId} semantic_spine.acceptance_contribution`)
+    };
+}
+function requireRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("validation", `${label} must be an object`, 2);
+    }
+    return value;
+}
+function requireStringArray(value, label) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.length === 0)) {
+        throw new AppError("validation", `${label} must be a string array`, 2);
+    }
+    return value;
+}
 function requireString(value, label) {
     if (typeof value !== "string" || value.length === 0) {
         throw new AppError("validation", `${label} must be a non-empty string`, 2);

package/dist/protocol/local-files.js

@@ -6,6 +6,10 @@ import { ensureDir, planJsonPath, protocolDir, stateJsonPath } from "../storage/
 export function ensureProtocolFiles(input) {
     const storageRoot = input.storageRoot ?? input.projectRoot;
     const dir = protocolDir(storageRoot, input.protocolId);
+    const currentFlowContract = loadProjectFlowContract(input.projectRoot);
+    const statePath = stateJsonPath(storageRoot, input.protocolId);
+    const existing = readStateIfExists(statePath);
+    const flowContract = existing?.flow_contract ?? currentFlowContract;
     ensureDir(dir);
     const summaryPath = path.join(dir, "summary.md");
     if (!fs.existsSync(summaryPath)) {
@@ -25,9 +29,6 @@ export function ensureProtocolFiles(input) {
             ""
         ].join("\n"));
     }
-    const statePath = stateJsonPath(storageRoot, input.protocolId);
-    const existing = readStateIfExists(statePath);
-    const flowContract = existing?.flow_contract ?? loadProjectFlowContract(input.projectRoot);
     const state = existing ??
         {
             schema_version: schemaVersion,
@@ -62,14 +63,15 @@ export function ensureProtocolFiles(input) {
     return { ...state, flow_contract: flowContract, updated_at: input.now };
 }
 export function ensureRuntimeProtocolFiles(input) {
+    const currentFlowContract = loadProjectFlowContract(input.projectRoot);
+    const statePath = path.join(input.runtimeDir, "state.json");
+    const existing = readStateIfExists(statePath);
+    const flowContract = existing?.flow_contract ?? currentFlowContract;
     ensureDir(input.runtimeDir);
     const metadataPath = path.join(input.runtimeDir, "metadata.json");
     if (!fs.existsSync(metadataPath)) {
         fs.writeFileSync(metadataPath, `${JSON.stringify({ protocol_id: input.protocolId, handshake_id: input.handshakeId, project_root: input.projectRoot }, null, 2)}\n`);
     }
-    const statePath = path.join(input.runtimeDir, "state.json");
-    const existing = readStateIfExists(statePath);
-    const flowContract = existing?.flow_contract ?? loadProjectFlowContract(input.projectRoot);
     const state = existing ??
         {
             schema_version: schemaVersion,

package/dist/schemas/code-stage-report.schema.json

@@ -1,9 +1,18 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "dd-flow/code-stage-report@1",
+  "$id": "dd-flow/code-stage-report@2",
   "title": "Code stage report data",
   "type": "object",
   "additionalProperties": true,
+  "allOf": [
+    {
+      "if": {
+        "properties": { "schema_id": { "const": "dd-flow/code-stage-report@2" } },
+        "required": ["schema_id"]
+      },
+      "then": { "required": ["flow_flags"] }
+    }
+  ],
   "required": [
     "schema_id",
     "run",
@@ -20,11 +29,12 @@
     "defs"
   ],
   "properties": {
-    "schema_id": { "const": "dd-flow/code-stage-report@1" },
+    "schema_id": { "enum": ["dd-flow/code-stage-report@1", "dd-flow/code-stage-report@2"] },
     "run": { "$ref": "#/definitions/run" },
     "stage": { "$ref": "#/definitions/stage" },
     "project": { "$ref": "#/definitions/namedEntity" },
     "subject": { "$ref": "#/definitions/namedEntity" },
+    "flow_flags": { "$ref": "#/definitions/flowFlags" },
     "overall": { "$ref": "#/definitions/overall" },
     "breadcrumbs": {
       "type": "array",
@@ -42,6 +52,24 @@
       "type": "array",
       "items": { "$ref": "#/definitions/fileRef" }
     },
+    "policy_context": { "$ref": "#/definitions/policyContext" },
+    "sdlc_contours": { "$ref": "#/definitions/sdlcContours" },
+    "knowledge_candidates": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "source_candidates": { "type": "string" },
+        "total": { "type": "integer", "minimum": 0 },
+        "implemented": { "type": "integer", "minimum": 0 },
+        "documented_during_code": { "type": "integer", "minimum": 0 },
+        "already_documented": { "type": "integer", "minimum": 0 },
+        "task_local_only": { "type": "integer", "minimum": 0 },
+        "deferred_as_DEF": { "type": "integer", "minimum": 0 },
+        "needs_user_confirmation": { "type": "integer", "minimum": 0 },
+        "not_applicable": { "type": "integer", "minimum": 0 },
+        "summary": { "type": "string" }
+      }
+    },
     "checks": {
       "type": "array",
       "items": { "$ref": "#/definitions/check" }
@@ -58,6 +86,35 @@
         }
       }
     },
+    "review_gates": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/reviewGate" }
+    },
+    "design_aspect_traceability": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "source": { "type": "string" },
+        "verdict": { "type": "string" },
+        "summary": { "type": "string" },
+        "implemented_seeds": { "type": "array" },
+        "deviations": { "type": "array" },
+        "gaps": { "type": "array" }
+      }
+    },
+    "testing_system": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "source": { "type": "string" },
+        "verdict": { "type": "string" },
+        "summary": { "type": "string" },
+        "commands": { "type": "array" },
+        "datasets": { "type": "array" },
+        "gaps": { "type": "array" }
+      }
+    },
+    "aspect_coverage": { "$ref": "#/definitions/aspectCoverage" },
     "defs": {
       "type": "array",
       "items": { "$ref": "#/definitions/deferral" }
@@ -176,6 +233,144 @@
         "status": { "type": "string", "minLength": 1 },
         "summary": { "type": "string", "minLength": 1 }
       }
+    },
+    "reviewGate": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "label", "stage", "applicability", "verdict", "summary"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "label": { "type": "string", "minLength": 1 },
+        "stage": { "type": "string", "minLength": 1 },
+        "applicability": { "type": "string", "minLength": 1 },
+        "verdict": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 },
+        "evidence": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "aspectCoverage": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["source", "verdict", "summary"],
+      "properties": {
+        "source": { "type": "string", "minLength": 1 },
+        "verdict": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 },
+        "counts": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "applicable": { "type": "integer", "minimum": 0 },
+            "not_applicable": { "type": "integer", "minimum": 0 },
+            "unknown": { "type": "integer", "minimum": 0 },
+            "covered": { "type": "integer", "minimum": 0 },
+            "blocked": { "type": "integer", "minimum": 0 },
+            "deferred": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "sdlcContours": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "summary": { "type": "string" },
+        "contours": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/sdlcContour" }
+        },
+        "policy_migration": { "type": "string" },
+        "next_delivery_action": { "type": "string" }
+      }
+    },
+    "sdlcContour": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["name", "applicability_status", "gate_status", "summary"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "applicability_status": { "type": "string", "minLength": 1 },
+        "verification_state": { "type": "string" },
+        "closure_state": { "type": "string" },
+        "gate_status": { "type": "string", "minLength": 1 },
+        "target_stage": { "type": "string" },
+        "delivery_target": { "type": "string" },
+        "summary": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string" },
+        "evidence": { "type": "string" },
+        "next_action": { "type": "string" }
+      }
+    },
+    "policyContext": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["sources", "git", "checks", "delivery", "gaps"],
+      "properties": {
+        "sources": { "type": "object", "additionalProperties": true },
+        "git": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "workspace_route": { "type": "string" },
+            "delivery_strategy": {
+              "type": "string",
+              "enum": ["direct_commit", "direct_commit_push", "feature_merge", "pull_request", "merge_queue", "squash_merge", "rebase_ff", "release_branch", "external_handoff", "local_only", "no_git"]
+            },
+            "fixation_required": { "type": "boolean" },
+            "result_evidence_required": { "type": "array", "items": { "type": "string" } },
+            "actual_workspace_route": { "type": "string" },
+            "route_match": { "type": "boolean" }
+          }
+        },
+        "checks": { "type": "object", "additionalProperties": true },
+        "delivery": { "type": "object", "additionalProperties": true },
+        "gaps": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "flowFlags": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["flow_kind", "snapshot_revision", "resolution_status", "values", "snapshot_checksum"],
+      "properties": {
+        "contract": { "type": "object", "additionalProperties": true },
+        "flow_kind": { "type": "string", "minLength": 1 },
+        "preset": { "type": "object", "additionalProperties": true },
+        "snapshot_revision": { "type": "integer", "minimum": 1 },
+        "resolution_status": { "type": "string", "enum": ["valid", "legacy_incomplete", "reconciliation_required"] },
+        "values": { "type": "object", "additionalProperties": { "$ref": "#/definitions/flagValue" } },
+        "snapshot_checksum": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "floors_applied": { "type": "array", "items": { "type": "string" } },
+        "resolved_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "flagValue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value", "value_type", "owner", "source", "rationale", "resolved_at"],
+      "properties": {
+        "value": {},
+        "value_type": { "type": "string", "minLength": 1 },
+        "owner": { "type": "string", "minLength": 1 },
+        "source": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "ref"],
+          "properties": {
+            "kind": { "type": "string", "minLength": 1 },
+            "ref": { "type": "string", "minLength": 1 },
+            "revision": { "type": ["integer", "null"] }
+          }
+        },
+        "rationale": { "type": "string", "minLength": 1 },
+        "resolved_at": { "type": "string", "format": "date-time" }
+      }
     }
   }
 }

package/dist/schemas/flow-contract.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/flow-contract@3",
+  "title": "dd-flow canonical flow contract",
+  "description": "Structural contract for the complete flow-contract.json catalog. Dynamic cross-key relationships are validated by the shared CLI normalizer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "version", "capabilities", "stages", "transitions", "readiness", "merge_queue", "defaults", "legacy_aliases", "flow_flags"],
+  "properties": {
+    "id": {"type":"string","pattern":"^dd-flow-canonical-[0-9]{4}-[0-9]{2}$"},
+    "version": {"const":3},
+    "capabilities": {"type":"array","uniqueItems":true,"items":{"type":"string","minLength":1}},
+    "stages": {"type":"object","minProperties":1,"additionalProperties":{"$ref":"#/definitions/stage"}},
+    "transitions": {"type":"object","minProperties":1,"additionalProperties":{"$ref":"#/definitions/stringArray"}},
+    "entrypoints": {"type":"object","additionalProperties":{"$ref":"#/definitions/entrypoint"}},
+    "readiness": {"$ref":"#/definitions/readiness"},
+    "merge_queue": {"$ref":"#/definitions/mergeQueue"},
+    "defaults": {"$ref":"#/definitions/defaults"},
+    "auto_policy": {"$ref":"#/definitions/autoPolicy"},
+    "legacy_aliases": {"$ref":"#/definitions/stringMap"},
+    "route_aliases": {"$ref":"#/definitions/stringMap"},
+    "flow_flags": {"$ref":"#/definitions/flowFlags"}
+  },
+  "definitions": {
+    "nonEmptyString": {"type":"string","minLength":1},
+    "stringArray": {"type":"array","uniqueItems":true,"items":{"$ref":"#/definitions/nonEmptyString"}},
+    "stringMap": {"type":"object","additionalProperties":{"$ref":"#/definitions/nonEmptyString"}},
+    "flagScalar": {"type":["string","number","boolean","null"]},
+    "flagMap": {"type":"object","additionalProperties":{"$ref":"#/definitions/flagScalar"}},
+    "stage": {
+      "type":"object","additionalProperties":false,"required":["terminal"],
+      "properties":{"terminal":{"type":"boolean"},"report_enabled":{"type":"boolean"}}
+    },
+    "entrypoint": {
+      "type":"object","additionalProperties":false,
+      "properties": {
+        "stage":{"$ref":"#/definitions/nonEmptyString"},
+        "logical_stages":{"$ref":"#/definitions/stringArray"},
+        "creates_protocol":{"type":"boolean"},
+        "purpose":{"$ref":"#/definitions/nonEmptyString"},
+        "mode":{"$ref":"#/definitions/nonEmptyString"}
+      },
+      "anyOf":[{"required":["stage"]},{"required":["logical_stages"]}]
+    },
+    "readiness": {
+      "type":"object","additionalProperties":false,"required":["command","allowed_from","target_stage"],
+      "properties":{"command":{"const":"ready-for-merge"},"allowed_from":{"$ref":"#/definitions/stringArray"},"target_stage":{"$ref":"#/definitions/nonEmptyString"}}
+    },
+    "mergeQueue": {
+      "type":"object","additionalProperties":false,"required":["complete"],
+      "properties":{"complete":{"type":"object","additionalProperties":false,"required":["target_stage","next_action"],"properties":{"target_stage":{"$ref":"#/definitions/nonEmptyString"},"next_action":{"$ref":"#/definitions/nonEmptyString"}}}}
+    },
+    "defaults": {
+      "type":"object","additionalProperties":false,"required":["registered_next_action"],
+      "properties": {
+        "registered_next_action":{"$ref":"#/definitions/nonEmptyString"},
+        "ordinary_protocol_flow_kind":{"$ref":"#/definitions/nonEmptyString"},
+        "normal_stage_layout":{"$ref":"#/definitions/stringArray"},
+        "legacy_coding_stage_layout":{"$ref":"#/definitions/stringArray"}
+      }
+    },
+    "autoPolicy": {
+      "type":"object","additionalProperties":false,
+      "properties": {
+        "ready_for_code_auto":{"$ref":"#/definitions/nonEmptyString"},
+        "ready_for_code_after_user_review":{"$ref":"#/definitions/nonEmptyString"},
+        "home_config_path":{"$ref":"#/definitions/nonEmptyString"},
+        "snapshot_authority":{"$ref":"#/definitions/nonEmptyString"},
+        "legacy_profile_projection":{"$ref":"#/definitions/nonEmptyString"}
+      }
+    },
+    "flowFlags": {
+      "type":"object","additionalProperties":false,
+      "required":["source_precedence","definitions","presets","flows","mandatory_floors"],
+      "properties": {
+        "source_precedence": {
+          "type":"array","minItems":1,"uniqueItems":true,
+          "items":{"enum":["flow_default","preset","task_profile","protocol_override","run_override","escalation","compatibility_alias"]}
+        },
+        "definitions": {"type":"object","minProperties":1,"additionalProperties":{"$ref":"#/definitions/flagDefinition"}},
+        "presets": {"type":"object","minProperties":1,"additionalProperties":{"$ref":"#/definitions/flagMap"}},
+        "flows": {"type":"object","minProperties":1,"additionalProperties":{"$ref":"#/definitions/flowFlagConsumer"}},
+        "mandatory_floors": {"type":"array","items":{"$ref":"#/definitions/mandatoryFloor"}},
+        "reduction_matrix": {"type":"object","additionalProperties":{"$ref":"#/definitions/reductionEntry"}},
+        "consumer_matrix": {"type":"object","additionalProperties":{"$ref":"#/definitions/stringArray"}}
+      }
+    },
+    "flagDefinition": {
+      "type":"object","additionalProperties":false,"required":["type","owner","description"],
+      "properties": {
+        "type":{"enum":["boolean","enum","number","string"]},
+        "values":{"type":"array","minItems":1,"uniqueItems":true,"items":{"$ref":"#/definitions/flagScalar"}},
+        "owner":{"$ref":"#/definitions/nonEmptyString"},
+        "description":{"$ref":"#/definitions/nonEmptyString"}
+      },
+      "allOf":[
+        {"if":{"properties":{"type":{"const":"enum"}},"required":["type"]},"then":{"required":["values"]}},
+        {"if":{"properties":{"type":{"enum":["boolean","number","string"]}},"required":["type"]},"then":{"not":{"required":["values"]}}}
+      ]
+    },
+    "flowFlagConsumer": {
+      "type":"object","additionalProperties":false,"required":["default_preset","supported","defaults"],
+      "properties": {
+        "default_preset":{"$ref":"#/definitions/nonEmptyString"},
+        "supported":{"type":"array","minItems":1,"uniqueItems":true,"items":{"$ref":"#/definitions/nonEmptyString"}},
+        "defaults":{"type":"object","additionalProperties":false,"required":["preset"],"properties":{"preset":{"$ref":"#/definitions/nonEmptyString"}}}
+      }
+    },
+    "mandatoryFloor": {
+      "type":"object","additionalProperties":false,"required":["when","values","reason"],
+      "properties": {
+        "when":{"type":"object","minProperties":1,"additionalProperties":{"$ref":"#/definitions/stringArray"}},
+        "values":{"$ref":"#/definitions/flagMap"},
+        "reason":{"$ref":"#/definitions/nonEmptyString"}
+      }
+    },
+    "reductionEntry": {
+      "type":"object","additionalProperties":false,"required":["skips","keeps","reduced_artifact_status"],
+      "properties": {
+        "skips":{"$ref":"#/definitions/stringArray"},
+        "keeps":{"$ref":"#/definitions/stringArray"},
+        "reduced_artifact_status":{"$ref":"#/definitions/nonEmptyString"}
+      }
+    }
+  }
+}