@smartmemory/compose 0.1.5-beta → 0.1.7-beta

package/bin/compose.js

@@ -994,6 +994,416 @@ if (cmd === 'roadmap') {
   process.exit(0)
 }
 
+if (cmd === 'record-completion') {
+  // compose record-completion <feature_code> --commit-sha=<full-40-hex> [options]
+  //
+  // Flags:
+  //   --commit-sha=<sha>          required; full 40-char hex SHA (Decision 9)
+  //   --tests-pass=<bool>         default true
+  //   --notes=<string>            optional
+  //   --files-changed-from-stdin  read newline-separated paths from stdin
+  //   --no-status                 set_status: false (don't flip status to COMPLETE)
+  //   --force                     force-replace an existing same-(code,sha) record
+  //   --idempotency-key=<key>     caller-supplied idempotency key
+  //
+  // Positional: <feature_code> is the first non-flag argument.
+
+  // Tiny flag parser: handles --key=value, --key value, --no-key
+  function parseFlags(rawArgs) {
+    const flags = {}
+    const positionals = []
+    let i = 0
+    while (i < rawArgs.length) {
+      const a = rawArgs[i]
+      if (a.startsWith('--')) {
+        const stripped = a.slice(2)
+        if (stripped.startsWith('no-')) {
+          flags[stripped.slice(3)] = false
+          i++
+        } else if (stripped.includes('=')) {
+          const eq = stripped.indexOf('=')
+          flags[stripped.slice(0, eq)] = stripped.slice(eq + 1)
+          i++
+        } else if (i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('--')) {
+          flags[stripped] = rawArgs[i + 1]
+          i += 2
+        } else {
+          flags[stripped] = true
+          i++
+        }
+      } else {
+        positionals.push(a)
+        i++
+      }
+    }
+    return { flags, positionals }
+  }
+
+  if (args[0] === '--help' || args[0] === '-h') {
+    console.log('Usage: compose record-completion <feature_code> --commit-sha=<full-40-hex> [options]')
+    console.log('')
+    console.log('Options:')
+    console.log('  --commit-sha=<sha>          Full 40-char hex SHA (required)')
+    console.log('  --tests-pass=<bool>         Whether tests passed (default: true)')
+    console.log('  --notes=<string>            Optional provenance notes')
+    console.log('  --files-changed-from-stdin  Read newline-separated repo-relative paths from stdin')
+    console.log('  --no-status                 Do not flip feature status to COMPLETE')
+    console.log('  --force                     Replace existing record with same (feature_code, commit_sha)')
+    console.log('  --idempotency-key=<key>     Caller-supplied idempotency key')
+    process.exit(0)
+  }
+
+  const { flags, positionals } = parseFlags(args)
+  const featureCode = positionals[0]
+  if (!featureCode) {
+    console.error('Error: feature_code is required as the first positional argument')
+    console.error('Usage: compose record-completion <feature_code> --commit-sha=<sha>')
+    process.exit(1)
+  }
+
+  const commitSha = flags['commit-sha']
+  if (!commitSha) {
+    console.error('Error: --commit-sha is required (full 40-char hex SHA)')
+    process.exit(1)
+  }
+
+  // Parse tests-pass: default true
+  let testsPass = true
+  if (flags['tests-pass'] !== undefined) {
+    const tp = flags['tests-pass']
+    if (tp === 'false' || tp === false) testsPass = false
+    else if (tp === 'true' || tp === true) testsPass = true
+    else {
+      console.error(`Error: --tests-pass must be true or false, got "${tp}"`)
+      process.exit(1)
+    }
+  }
+
+  // Read files_changed from stdin if flag set
+  let filesChanged = []
+  if (flags['files-changed-from-stdin'] === true) {
+    const { createReadStream } = await import('fs')
+    const { createInterface } = await import('readline')
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity })
+    for await (const line of rl) {
+      const trimmed = line.trim()
+      if (trimmed) filesChanged.push(trimmed)
+    }
+  }
+
+  const completionArgs = {
+    feature_code: featureCode,
+    commit_sha: commitSha,
+    tests_pass: testsPass,
+    files_changed: filesChanged,
+  }
+  if (flags['notes']) completionArgs.notes = flags['notes']
+  if (flags['status'] === false) completionArgs.set_status = false  // --no-status
+  if (flags['force'] === true) completionArgs.force = true
+  if (flags['idempotency-key']) completionArgs.idempotency_key = flags['idempotency-key']
+
+  const cwd = findProjectRoot(process.cwd())
+  const { recordCompletion } = await import('../lib/completion-writer.js')
+  try {
+    const result = await recordCompletion(cwd, completionArgs)
+    console.log(JSON.stringify({
+      completion_id:  result.completion_id,
+      idempotent:     result.idempotent,
+      status_changed: result.status_changed,
+    }, null, 2))
+    process.exit(0)
+  } catch (err) {
+    let msg = err && err.code ? `[${err.code}]: ${err.message}` : err.message
+    if (err && err.cause && typeof err.cause.message === 'string') {
+      msg += err.cause.code
+        ? `\n  Caused by [${err.cause.code}]: ${err.cause.message}`
+        : `\n  Caused by: ${err.cause.message}`
+    }
+    console.error(msg)
+    process.exit(1)
+  }
+}
+
+if (cmd === 'hooks') {
+  // compose hooks {install,uninstall,status}
+  const sub = args[0]
+
+  // Tiny flag parser reused here
+  function parseHookFlags(rawArgs) {
+    const flags = {}
+    let i = 0
+    while (i < rawArgs.length) {
+      const a = rawArgs[i]
+      if (a.startsWith('--')) {
+        const stripped = a.slice(2)
+        if (stripped.includes('=')) {
+          const eq = stripped.indexOf('=')
+          flags[stripped.slice(0, eq)] = stripped.slice(eq + 1)
+          i++
+        } else {
+          flags[stripped] = true
+          i++
+        }
+      }
+      i = i < rawArgs.length && !rawArgs[i].startsWith('--') ? i + 1 : i
+    }
+    return flags
+  }
+
+  // Fix: simpler flag parsing
+  const hookFlags = {}
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--force') hookFlags.force = true
+    else if (a.startsWith('--')) {
+      const stripped = a.slice(2)
+      if (stripped.includes('=')) {
+        const eq = stripped.indexOf('=')
+        hookFlags[stripped.slice(0, eq)] = stripped.slice(eq + 1)
+      } else {
+        hookFlags[stripped] = true
+      }
+    }
+  }
+
+  const { readFileSync: rfSync, writeFileSync: wfSync, existsSync: exSync, chmodSync } = await import('fs')
+  const { join: pjoin, resolve: presolve } = await import('path')
+  const { fileURLToPath: futp } = await import('url')
+
+  const projectRoot = findProjectRoot(process.cwd())
+  const gitDir = pjoin(projectRoot, '.git')
+  if (!exSync(gitDir)) {
+    console.error('Error: not a git repository (no .git directory found)')
+    process.exit(1)
+  }
+
+  const hooksDir = pjoin(gitDir, 'hooks')
+  const { mkdirSync: mSync } = await import('fs')
+  mSync(hooksDir, { recursive: true })
+
+  // Resolve absolute paths for substitution
+  const composeBin = presolve(presolve(futp(import.meta.url), '..'), 'compose.js')
+  const composeNode = process.execPath
+
+  // Hook-type table. Each entry knows its template, marker, and destination.
+  const HOOK_TYPES = {
+    'post-commit': {
+      template: pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'post-commit.template'),
+      marker:   '# Compose post-commit hook —',
+      dest:     pjoin(hooksDir, 'post-commit'),
+    },
+    'pre-push': {
+      template: pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'pre-push.template'),
+      marker:   '# Compose pre-push hook —',
+      dest:     pjoin(hooksDir, 'pre-push'),
+    },
+  }
+
+  // Determine which hook types this invocation operates on.
+  // Flags: --pre-push, --post-commit, or none (default = post-commit, back-compat).
+  const selectedTypes = []
+  if (hookFlags['pre-push']) selectedTypes.push('pre-push')
+  if (hookFlags['post-commit']) selectedTypes.push('post-commit')
+  if (selectedTypes.length === 0) selectedTypes.push('post-commit') // default = back-compat
+
+  function installOne(type) {
+    const { template: tplPath, marker, dest } = HOOK_TYPES[type]
+    let template
+    try {
+      template = rfSync(tplPath, 'utf-8')
+    } catch (err) {
+      console.error(`Error: could not read ${type} template: ${err.message}`)
+      return 1
+    }
+    if (exSync(dest)) {
+      const existing = rfSync(dest, 'utf-8')
+      const isOurs = existing.includes(marker)
+      if (!isOurs && !hookFlags.force) {
+        console.error(`Error: a foreign ${type} hook already exists at ${dest}`)
+        console.error('')
+        console.error(`Run \`compose hooks install --${type} --force\` to overwrite.`)
+        return 1
+      }
+    }
+    const substituted = template
+      .replace(/__COMPOSE_NODE__/g, composeNode)
+      .replace(/__COMPOSE_BIN__/g, composeBin)
+    wfSync(dest, substituted)
+    chmodSync(dest, 0o755)
+    console.log(`Installed ${type} hook at ${dest}`)
+    console.log(`  COMPOSE_NODE=${composeNode}`)
+    console.log(`  COMPOSE_BIN=${composeBin}`)
+    return 0
+  }
+
+  function uninstallOne(type) {
+    const { marker, dest } = HOOK_TYPES[type]
+    if (!exSync(dest)) {
+      console.log(`No ${type} hook installed.`)
+      return 0
+    }
+    const content = rfSync(dest, 'utf-8')
+    if (!content.includes(marker)) {
+      console.warn(`Warning: ${type} hook exists but does not appear to be a Compose hook (marker not found). Leaving alone.`)
+      return 0
+    }
+    const { rmSync: rmS } = require('fs')
+    rmS(dest)
+    console.log(`Removed ${type} hook at ${dest}`)
+    return 0
+  }
+
+  function statusOne(type) {
+    const { marker, dest } = HOOK_TYPES[type]
+    if (!exSync(dest)) {
+      console.log(`${type}: absent — no hook installed`)
+      return
+    }
+    const content = rfSync(dest, 'utf-8')
+    if (!content.includes(marker)) {
+      console.log(`${type}: foreign — hook exists but is not a Compose hook`)
+      return
+    }
+    const nodeMatch = content.includes(`COMPOSE_NODE="${composeNode}"`)
+    const binMatch  = content.includes(`COMPOSE_BIN="${composeBin}"`)
+    if (nodeMatch && binMatch) {
+      console.log(`${type}: installed (current)`)
+    } else {
+      console.log(`${type}: installed (stale paths — re-run install)`)
+      if (!nodeMatch) console.log(`  expected COMPOSE_NODE="${composeNode}"`)
+      if (!binMatch)  console.log(`  expected COMPOSE_BIN="${composeBin}"`)
+    }
+  }
+
+  if (sub === 'install') {
+    let exitCode = 0
+    for (const t of selectedTypes) exitCode = installOne(t) || exitCode
+    process.exit(exitCode)
+  }
+
+  if (sub === 'uninstall') {
+    const { rmSync: _rmS } = await import('fs') // ensure fs.rmSync is available
+    // uninstallOne calls require('fs') but we're ESM — replace with import-based deletion
+    for (const t of selectedTypes) {
+      const { marker, dest } = HOOK_TYPES[t]
+      if (!exSync(dest)) { console.log(`No ${t} hook installed.`); continue }
+      const content = rfSync(dest, 'utf-8')
+      if (!content.includes(marker)) {
+        console.warn(`Warning: ${t} hook exists but does not appear to be a Compose hook (marker not found). Leaving alone.`)
+        continue
+      }
+      _rmS(dest)
+      console.log(`Removed ${t} hook at ${dest}`)
+    }
+    process.exit(0)
+  }
+
+  // status (default)
+  if (!sub || sub === 'status') {
+    // Status reports on ALL known hook types (selection flags ignored), so users
+    // see the full picture. Selection only affects install/uninstall.
+    for (const t of Object.keys(HOOK_TYPES)) statusOne(t)
+    process.exit(0)
+  }
+
+  console.error(`Unknown hooks subcommand: "${sub}". Use: install | uninstall | status`)
+  process.exit(1)
+}
+
+if (cmd === 'validate') {
+  // compose validate [--scope=feature|project] [--code=CODE] [--block-on=error|warning|info] [--json]
+  let scope = 'project'
+  let code = null
+  let blockOn = 'error'
+  let asJson = false
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--help' || a === '-h') {
+      console.log(`Usage: compose validate [options]
+
+Options:
+  --scope=feature|project     Scope (default: project)
+  --code=CODE                 Feature code (required when scope=feature)
+  --block-on=LEVEL            Exit non-zero if any finding >= LEVEL (default: error)
+                              LEVEL: error | warning | info
+  --json                      Emit findings as JSON (default: human-readable)
+
+Exit codes:
+  0   no findings >= block-on threshold
+  1   findings >= block-on threshold present
+  2   usage error`)
+      process.exit(0)
+    }
+    if (a === '--json') { asJson = true; continue }
+    if (a.startsWith('--scope=')) scope = a.slice('--scope='.length)
+    else if (a === '--scope') scope = args[++i]
+    else if (a.startsWith('--code=')) code = a.slice('--code='.length)
+    else if (a === '--code') code = args[++i]
+    else if (a.startsWith('--block-on=')) blockOn = a.slice('--block-on='.length)
+    else if (a === '--block-on') blockOn = args[++i]
+    else if (a.startsWith('--')) {
+      console.error(`Unknown flag: ${a}`)
+      process.exit(2)
+    }
+  }
+  if (!['feature', 'project'].includes(scope)) {
+    console.error(`Invalid --scope=${scope}; expected feature or project`)
+    process.exit(2)
+  }
+  if (scope === 'feature' && !code) {
+    console.error(`--scope=feature requires --code=<CODE>`)
+    process.exit(2)
+  }
+  if (!['error', 'warning', 'info'].includes(blockOn)) {
+    console.error(`Invalid --block-on=${blockOn}; expected error, warning, or info`)
+    process.exit(2)
+  }
+
+  const { validateFeature, validateProject } = await import('../lib/feature-validator.js')
+  let result
+  try {
+    result = scope === 'feature'
+      ? await validateFeature(process.cwd(), code)
+      : await validateProject(process.cwd())
+  } catch (err) {
+    if (err.code === 'INVALID_INPUT') {
+      console.error(`Error [INVALID_INPUT]: ${err.message}`)
+      process.exit(2)
+    }
+    console.error(`Error: ${err.message}`)
+    process.exit(2)
+  }
+
+  // Threshold: findings at or above this severity block the exit code
+  const SEV_RANK = { error: 3, warning: 2, info: 1 }
+  const threshold = SEV_RANK[blockOn]
+  const blocking = result.findings.filter((f) => SEV_RANK[f.severity] >= threshold)
+
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    const byKind = {}
+    for (const f of result.findings) {
+      const sev = f.severity.toUpperCase()
+      const tag = `[${sev}] ${f.kind}${f.feature_code ? ' ' + f.feature_code : ''}`
+      if (!byKind[tag]) byKind[tag] = []
+      byKind[tag].push(f.detail)
+    }
+    if (result.findings.length === 0) {
+      console.log(`compose validate: no findings (scope=${scope}${code ? ' code=' + code : ''})`)
+    } else {
+      console.log(`compose validate findings (scope=${scope}${code ? ' code=' + code : ''}):`)
+      for (const tag of Object.keys(byKind).sort()) {
+        console.log(`  ${tag}`)
+        for (const detail of byKind[tag]) console.log(`    - ${detail}`)
+      }
+      console.log(`\n${result.findings.length} finding(s); ${blocking.length} at or above --block-on=${blockOn}`)
+    }
+  }
+
+  process.exit(blocking.length > 0 ? 1 : 0)
+}
+
 if (cmd === 'pipeline') {
   const { runPipelineCli } = await import('../lib/pipeline-cli.js')
   try {

package/bin/git-hooks/post-commit.template

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Compose post-commit hook — auto-records completions from `Records-completion:` trailers.
+# Installed by `compose hooks install`; placeholders below are substituted at install time.
+# Failures are logged and non-blocking.
+
+set -u
+COMPOSE_NODE="__COMPOSE_NODE__"
+COMPOSE_BIN="__COMPOSE_BIN__"
+LOG="${COMPOSE_HOOK_LOG:-.compose/data/post-commit.log}"
+mkdir -p "$(dirname "$LOG")"
+
+trailers=$(git log -1 --pretty=%B | git interpret-trailers --parse 2>/dev/null || true)
+if [[ -z "$trailers" ]]; then exit 0; fi
+
+sha=$(git rev-parse HEAD)
+files=$(git diff-tree --no-commit-id --name-only -r HEAD)
+subject=$(git log -1 --pretty=%s)
+
+echo "$trailers" | while IFS= read -r line; do
+  header=$(echo "$line" | awk -F': ' 'NR==1{print tolower($1)}')
+  if [[ "$header" != "records-completion" ]]; then continue; fi
+  value=$(echo "$line" | awk -F': ' '{ for (i=2; i<=NF; i++) printf "%s%s", $i, (i==NF?"":": ") }')
+  code=$(echo "$value" | awk '{print $1}')
+  rest=$(echo "$value" | awk '{$1=""; sub(/^ /, ""); print}')
+
+  tp="true"
+  notes="$subject"
+
+  # Extract notes="..." first (greedy quoted-string), then strip it from rest
+  # so its content can't pollute key=value token scanning.
+  if [[ "$rest" =~ notes=\"([^\"]*)\" ]]; then
+    notes="${BASH_REMATCH[1]}"
+    rest="${rest/notes=\"${BASH_REMATCH[1]}\"/}"
+  fi
+
+  # Tokenize remaining rest on whitespace; parse known key=value pairs.
+  for token in $rest; do
+    key="${token%%=*}"
+    val="${token#*=}"
+    case "$key" in
+      tests_pass)
+        if [[ "$val" == "true" ]];  then tp="true";  fi
+        if [[ "$val" == "false" ]]; then tp="false"; fi
+        ;;
+      "")
+        # empty token after stripping notes="...", skip silently
+        ;;
+      *)
+        echo "[$(date -Iseconds)] hook: unknown qualifier \"$token\" for $code" | tee -a "$LOG" >&2
+        ;;
+    esac
+  done
+
+  if ! echo "$files" | "$COMPOSE_NODE" "$COMPOSE_BIN" record-completion "$code" \
+    --commit-sha="$sha" --tests-pass="$tp" --notes="$notes" \
+    --files-changed-from-stdin >> "$LOG" 2>&1; then
+    echo "[$(date -Iseconds)] hook: record_completion failed for $code (sha=$sha) — see above" >> "$LOG"
+  fi
+done
+
+exit 0

package/bin/git-hooks/pre-push.template

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Compose pre-push hook — runs `compose validate` and blocks the push on
+# any error-severity drift finding. Installed by `compose hooks install --pre-push`;
+# placeholders below are substituted at install time.
+
+set -u
+COMPOSE_NODE="__COMPOSE_NODE__"
+COMPOSE_BIN="__COMPOSE_BIN__"
+LOG="${COMPOSE_HOOK_LOG:-.compose/data/pre-push.log}"
+mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
+
+OUTPUT=$("$COMPOSE_NODE" "$COMPOSE_BIN" validate --scope=project --block-on=error 2>&1)
+EXIT_CODE=$?
+
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "$OUTPUT" | tee -a "$LOG" >&2
+  echo "" >&2
+  echo "compose validate found error-severity drift. Push aborted." >&2
+  echo "Run \`compose validate\` to see findings, then fix and retry." >&2
+  echo "Bypass at your own risk: git push --no-verify" >&2
+  exit "$EXIT_CODE"
+fi
+
+# Below-threshold findings (warnings/info) are still printed for visibility.
+echo "$OUTPUT"
+exit 0

package/contracts/feature-json.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://compose.smartmemory.dev/contracts/feature-json.schema.json",
+  "title": "feature.json",
+  "description": "Per-feature state record at docs/features/<CODE>/feature.json. Codifies the de facto union of fields produced today by typed writers and runtime code. Intentionally permissive (additionalProperties: true) until COMP-MCP-VALIDATE-SCHEMA-TIGHTEN follow-up.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["code"],
+  "properties": {
+    "code": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9-]*[A-Z0-9]$",
+      "description": "Strict feature code. Matches FEATURE_CODE_RE_STRICT."
+    },
+    "description": { "type": "string" },
+    "name": {
+      "type": "string",
+      "description": "Legacy alternative to description (de facto). Prefer description on new files."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["PLANNED", "IN_PROGRESS", "PARTIAL", "COMPLETE", "SUPERSEDED", "PARKED", "BLOCKED", "KILLED"]
+    },
+    "phase": { "type": ["string", "null"] },
+    "complexity": {
+      "oneOf": [
+        { "type": "string", "enum": ["S", "M", "L", "XL"] },
+        { "type": "number" }
+      ],
+      "description": "S/M/L/XL on new files; numeric on legacy files (e.g. COMP-DEBUG-1). Convergence deferred to COMP-MCP-VALIDATE-SCHEMA-TIGHTEN."
+    },
+    "position": { "type": ["integer", "string"] },
+    "parent": { "type": "string" },
+    "depends_on": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "De facto field on legacy files. Cross-feature dependency codes."
+    },
+    "source": {
+      "type": "string",
+      "description": "De facto field on legacy files."
+    },
+    "profile": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object", "additionalProperties": true }
+      ],
+      "description": "Either a string identifier or an inline profile object (de facto on COMP-DEBUG-1 etc.)."
+    },
+    "created": { "type": "string", "format": "date" },
+    "updated": { "type": "string", "format": "date" },
+    "commit_sha": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "artifacts": {
+      "type": "array",
+      "description": "Linked non-canonical artifacts (journal/snapshot pointers, external docs). Canonical artifacts (design.md, plan.md, etc.) under the feature folder are auto-discovered and explicitly NOT registered here.",
+      "items": {
+        "type": "object",
+        "required": ["type", "path"],
+        "properties": {
+          "type": { "type": "string", "enum": ["design", "prd", "architecture", "blueprint", "plan", "report", "journal", "snapshot"] },
+          "path": { "type": "string" },
+          "status": { "type": "string" }
+        }
+      }
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "to_code"],
+        "properties": {
+          "kind": { "type": "string", "enum": ["surfaced_by", "blocks", "depends_on", "follow_up", "supersedes", "related"] },
+          "to_code": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]*[A-Z0-9]$" },
+          "note": { "type": "string" }
+        }
+      }
+    },
+    "completions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["completion_id", "feature_code", "commit_sha"],
+        "properties": {
+          "completion_id": { "type": "string" },
+          "feature_code": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]*[A-Z0-9]$" },
+          "commit_sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+          "commit_sha_short": { "type": "string" },
+          "tests_pass": { "type": "boolean" },
+          "files_changed": { "type": "array", "items": { "type": "string" } },
+          "recorded_at": { "type": "string" },
+          "recorded_by": { "type": "string" },
+          "notes": { "type": "string" }
+        }
+      }
+    },
+    "lifecycle": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "currentPhase": { "type": "string" },
+        "phaseHistory": { "type": "array" }
+      }
+    },
+    "phaseHistory": {
+      "type": "array",
+      "description": "Empty array on every existing file today. Validator does not flag empty."
+    },
+    "filesChanged": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Written by runBuild() on completion. De facto field; not tightened in v1."
+    }
+  }
+}

package/contracts/roadmap-row.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://compose.smartmemory.dev/contracts/roadmap-row.schema.json",
+  "title": "Roadmap Row",
+  "description": "Single parsed ROADMAP.md row, mirroring lib/roadmap-parser.js FeatureEntry typedef. Validator filters out _anon_* sentinel codes (parser emits these for unrecognized rows) before applying this schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["code", "description", "status", "phaseId", "position"],
+  "properties": {
+    "code": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9-]*[A-Z0-9]$",
+      "description": "Strict feature code. Anonymous _anon_<n> sentinel codes from the parser are filtered before this schema runs."
+    },
+    "description": { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["PLANNED", "IN_PROGRESS", "PARTIAL", "COMPLETE", "SUPERSEDED", "PARKED", "BLOCKED", "KILLED"]
+    },
+    "phaseId": { "type": "string" },
+    "position": { "type": "integer", "minimum": 1 }
+  }
+}