@topogram/cli 0.3.72 → 0.3.74

package/README.md

@@ -1,223 +1,52 @@
-# Topogram Engine
+# Topogram CLI Package
 
-This folder contains the Topogram implementation: parser, validator, resolver, generators, runtime bundle emitters, and CLI.
+This directory is the npm package for `@topogram/cli`. It exposes the
+`topogram` executable.
 
-The active product workflow is authoring-to-generated-app. Engine development should stay separate from user-facing demos.
+The repo root owns product docs. Start with:
 
-## Package Shape
+- [README](../README.md)
+- [Docs map](../docs/README.md)
+- [CLI Reference](../docs/reference/cli.md)
+- [Engine Development](../docs/maintainers/engine-development.md)
 
-The engine is the publishable CLI package:
+## Package shape
 
 ```json
 {
   "name": "@topogram/cli",
   "bin": {
-    "topogram": "./src/cli.js"
+    "topogram": "src/cli.js"
   }
 }
 ```
 
-This lets source checkouts and package consumers call:
+## Local development
 
-```bash
-topogram new ../my-app
-topogram version
-topogram version --json
-topogram doctor
-topogram check
-topogram generate
-topogram catalog list
-topogram catalog show todo
-topogram catalog check topograms.catalog.json
-topogram catalog copy hello ../hello-topogram
-topogram import ../existing-app --out ../imported-topogram
-topogram import check ../imported-topogram
-topogram release status
-topogram package update-cli --latest
-topogram source status ../hello-topogram --local
-topogram source status ../hello-topogram --remote
-topogram template list
-topogram template explain
-topogram template status
-topogram template policy check
-topogram template policy pin @scope/template@0.2.0
-topogram template check ../my-template
-topogram template update --plan
-topogram trust template
-```
-
-Publishing is manual through the repo-level `Publish CLI Package` workflow. Create generated projects outside `engine/`; this directory is source and test code.
-
-From the repo root, prefer:
-
-```bash
-npm run smoke:test-app
-npm run cli:check
-npm run new -- ./my-topogram-app
-```
-
-## Layout
-
-- `src/` - engine source
-- `tests/active/` - retained active engine tests
-- `tests/fixtures/templates/` - local template fixtures used by engine tests
-- `tests/fixtures/workspaces/` - engine-owned Topogram workspaces
-- `tests/fixtures/expected/` - engine-owned golden outputs
-- `tests/fixtures/invalid/` - invalid model cases
-
-The generated Todo demo and Todo starter template live outside this repo in `topogram-demo-todo` and `topogram-template-todo`.
-
-## Active Fixture
-
-The current generated-app regression fixture is:
-
-```text
-tests/fixtures/workspaces/app-basic/
-tests/fixtures/expected/app-basic/
-```
-
-It is a fixture, not a user example.
-
-## Commands
-
-Run the engine gate:
-
-```bash
-npm run check
-```
-
-Create a starter project from the catalog-backed default `hello-web` alias:
+From the repo root:
 
 ```bash
-topogram new ../my-topogram-app --template hello-web
-cd ../my-topogram-app
 npm install
-npm run doctor
-npm run check
-```
-
-Choose another catalog starter with the template commands:
-
-```bash
-topogram template list
-topogram template show web-api
-topogram new ../web-api-demo --template web-api
-```
-
-Create a starter project from a shared template package:
-
-```bash
-topogram new ../todo-demo --template @topogram/template-todo
-topogram new ../todo-demo --template todo
-```
-
-Catalog aliases resolve through the public catalog index at
-`github:attebury/topograms/topograms.catalog.json`. The catalog is package
-backed; executable starter content still lives in template packages. Use
-`topogram catalog show <id>` to inspect an entry and get the correct `new` or
-`copy` command for that kind. Use `topogram template show <id>` when the entry
-is known to be a starter template and you want the direct `topogram new` flow.
-Pure
-topogram catalog entries can be copied for editing with
-`topogram catalog copy <id> <target>`. Copied topogram projects record
-`.topogram-source.json`; inspect local drift from that import baseline with
-`topogram source status <target> --local`. This metadata is provenance only and does not
-block local edits, checks, or generation. Template baseline divergence means the
-local project owns those edits; executable implementation trust is the separate
-state that can block generation until reviewed.
-Run `topogram template detach <target>` when the project should stop tracking
-template update metadata while keeping normal check/generate behavior.
-
-Do not create generated projects under `engine/`. The CLI refuses paths inside the engine directory.
-
-Template pack authoring and trust policy are documented in `../docs/template-authoring.md`.
-Catalog layout and optional private-source access are documented in `../docs/catalog.md`.
-Projects created from executable templates include `.topogram-template-trust.json`;
-regenerate it with `topogram trust template` after reviewing copied
-`implementation/` code. Use `topogram template status` for the lifecycle
-summary, then `topogram trust status` and `topogram trust diff` to inspect
-changed files before refreshing trust.
-
-Projects also include `topogram.template-policy.json`, the allow policy used by
-template update and template check commands. It can restrict candidate template
-sources, template ids, package scopes, executable-template behavior, and pinned
-template versions:
-
-```bash
-topogram template policy check
-topogram template policy explain
-topogram template policy init
-topogram template policy pin @scope/template@0.2.0
-```
-
-Use `topogram template policy explain` for a rule-by-rule view of the current
-project template, package scope, catalog provenance, executable implementation
-setting, and pinned version state.
-
-Use `topogram template status --latest` and `topogram template update --latest`
-only for package-backed templates when an explicit registry lookup is desired.
-Plain status and update commands do not query the registry.
-
-Use `topogram template update --status [--template <spec>]` to inspect current
-template adoption state with baseline and conflict analysis. Use
-`topogram template update --recommend [--template <spec>]` for a concise
-human/agent next-step summary before applying, adopting, or deleting files. Use
-`topogram template update --plan [--template <spec>]` to compare the current
-project with a candidate template without writing files. Use
-`topogram template update --check [--template <spec>]` as the no-write CI guard;
-it exits nonzero when the project is not aligned with the recorded or supplied
-template. Any update mode can write a machine-readable review report with
-`--out <path>`. After review, `topogram template update --apply [--template
-<spec>]` writes added/changed template-owned files, records a new
-`.topogram-template-files.json` baseline, skips deletes, and refuses local
-conflicts. Existing projects can run `topogram trust template` after review to
-record the first template-owned file baseline. JSON output includes structured
-diagnostics with codes, paths, suggested fixes, and workflow steps.
-
-Single-file adoption actions are explicit and baseline-aware:
-`--accept-current <file>` records the current file as the trusted baseline,
-`--accept-candidate <file>` applies one candidate file after baseline checks,
-and `--delete-current <file>` deletes one current-only file only when it still
-matches the trusted baseline.
-
-Template authors can run `topogram template check <template-spec-or-path>` to
-validate manifest/layout, temporary starter creation, starter checks, trust
-metadata, and no-write update planning. The JSON form reports structured
-diagnostics with codes, paths, and suggested fixes for authoring feedback.
-
-Run the same gate directly:
-
-```bash
 npm test
+bash ./scripts/verify-engine.sh
+bash ./scripts/verify-cli-package.sh
 ```
 
-Run only the active fixture validity check:
+From `engine/`:
 
 ```bash
+npm test
 npm run fixture:check
-```
-
-Inspect the active fixture topology as JSON:
-
-```bash
-npm run fixture:check:json
-```
-
-Generate the active fixture app bundle:
-
-```bash
 npm run fixture:generate
 ```
 
-Run the app-generation workflow test:
+## What belongs here
 
-```bash
-node --test ./tests/active/generated-app-workflow.test.js
-```
+- parser, validator, resolver;
+- CLI command dispatch;
+- import, reconcile, and adoption workflows;
+- context/query/agent packets;
+- generator dispatch and bundled fallback adapters;
+- engine fixtures and active tests.
 
-Validate or generate through the public CLI shape:
-
-```bash
-node ./src/cli.js check ./tests/fixtures/workspaces/app-basic
-node ./src/cli.js generate ./tests/fixtures/workspaces/app-basic --out /tmp/topogram-app
-```
+Generated projects should live outside `engine/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.72",
+  "version": "0.3.74",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/adoption/plan/index.js

@@ -6,7 +6,7 @@ import {
   reviewBoundaryForImportProposal
 } from "../../policy/review-boundaries.js";
 
-const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "widgets", "docs", "journeys", "workflows", "verification", "ui"]);
+const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "widgets", "docs", "journeys", "workflows", "verification", "cli", "ui"]);
 
 function stableSortedStrings(values) {
   return [...new Set((values || []).filter(Boolean))].sort();
@@ -360,6 +360,7 @@ export function selectorMatchesItem(selector, item) {
   if (selector === "journeys") return item.track === "docs" && String(item.canonical_rel_path || "").startsWith("docs/journeys/");
   if (selector === "workflows") return item.track === "workflows" || item.kind === "decision";
   if (selector === "verification") return item.kind === "verification";
+  if (selector === "cli") return item.bundle === "cli" || item.track === "cli" || item.suggested_action === "promote_cli_surface";
   if (selector === "ui") return item.track === "ui" || item.kind === "widget" || item.source_kind === "ui_widget_event";
   if (selector.startsWith("bundle:")) return item.bundle === selector.slice("bundle:".length);
   return false;

package/src/agent-brief.js

@@ -20,6 +20,10 @@ import {
   getTemplateTrustStatus,
   TEMPLATE_TRUST_FILE
 } from "./template-trust.js";
+import {
+  loadSdlcPolicy,
+  SDLC_POLICY_FILE
+} from "./sdlc/policy.js";
 import { DEFAULT_TOPO_FOLDER_NAME, resolveTopoRoot, resolveWorkspaceContext } from "./workspace-paths.js";
 
 /**
@@ -164,6 +168,17 @@ function readImportSummary(projectRoot) {
  */
 function buildWorkflows(config, hasImportRecord) {
   const workflows = [
+    {
+      id: "sdlc-task-plan",
+      title: "SDLC task and plan loop",
+      commands: [
+        "topogram sdlc explain <task-or-bug-id> --json",
+        "topogram query slice ./topo --task <task-id> --json",
+        "topogram sdlc plan explain <plan-id> --json",
+        "topogram sdlc plan step complete <plan-id> <step-id> --actor <actor> --write"
+      ],
+      rule: "Plans are optional; edit plan text directly, but use CLI for status, history, step progress, and archive state."
+    },
     {
       id: "greenfield-generated",
       title: "Generated project loop",
@@ -235,9 +250,10 @@ function buildWorkflows(config, hasImportRecord) {
  * @param {Record<string, any>} trust
  * @param {Record<string, any>|null} importSummary
  * @param {Record<string, any>} generatorPolicy
+ * @param {Record<string, any>} sdlcPolicy
  * @returns {string[]}
  */
-function buildWarnings(projectRoot, config, trust, importSummary, generatorPolicy) {
+function buildWarnings(projectRoot, config, trust, importSummary, generatorPolicy, sdlcPolicy) {
   /** @type {string[]} */
   const warnings = [];
   if (config?.implementation) {
@@ -249,6 +265,9 @@ function buildWarnings(projectRoot, config, trust, importSummary, generatorPolic
   if (generatorPolicy?.diagnostics?.errors > 0) {
     warnings.push(`${GENERATOR_POLICY_FILE} has generator policy errors. Fix policy before generating.`);
   }
+  if (sdlcPolicy?.status === "adopted" && sdlcPolicy?.mode === "enforced") {
+    warnings.push("SDLC is enforced. Protected changes need a valid SDLC item, a topo/sdlc/*.tg record update, or an explicit allowed exemption.");
+  }
   if (summarizeOutputBoundaries(config).some((output) => output.ownership === "generated")) {
     warnings.push("Generated-owned outputs are replaceable by Topogram; do not make lasting edits under generated output paths.");
   }
@@ -312,12 +331,25 @@ export function buildAgentBrief(inputPath, workspaceAst) {
   const generatorBindings = packageBackedGeneratorBindings(config);
   const generatorDiagnostics = generatorPolicyDiagnosticsForBindings(generatorPolicyInfo, generatorBindings, "agent-brief");
   const importSummary = readImportSummary(configDir);
+  const sdlcPolicyInfo = loadSdlcPolicy(configDir);
+  const sdlcPolicy = {
+    exists: sdlcPolicyInfo.exists,
+    path: relativeProjectPath(projectRoot, sdlcPolicyInfo.path),
+    status: sdlcPolicyInfo.status,
+    mode: sdlcPolicyInfo.mode,
+    protectedPaths: sdlcPolicyInfo.policy?.protectedPaths || [],
+    requiredItemKinds: sdlcPolicyInfo.policy?.requiredItemKinds || [],
+    allowExemptions: sdlcPolicyInfo.policy?.allowExemptions ?? false,
+    gateCommand: "topogram sdlc gate . --require-adopted",
+    diagnostics: sdlcPolicyInfo.diagnostics
+  };
 
   const topogramReadPath = path.resolve(topogramRoot) === path.resolve(projectRoot) ? "." : `${DEFAULT_TOPO_FOLDER_NAME}/`;
   const readOrder = [
     readItem(projectRoot, "AGENTS.md", "Human-readable first-run guidance generated with this project.", false),
     readItem(projectRoot, "README.md", "Project workflow and template provenance summary.", true),
     readItem(projectRoot, "topogram.project.json", "Topology, outputs, template metadata, generator bindings, and implementation provider settings.", true),
+    readItem(projectRoot, SDLC_POLICY_FILE, "SDLC adoption, enforcement mode, protected paths, required item kinds, and exemption policy.", false),
     readItem(projectRoot, "topogram.template-policy.json", "Template trust/update policy for attached templates.", false),
     readItem(projectRoot, GENERATOR_POLICY_FILE, "Package-backed generator policy and allowed scopes.", false),
     readItem(projectRoot, TEMPLATE_TRUST_FILE, "Executable implementation trust record, if the template copied implementation code.", Boolean(config.implementation)),
@@ -331,6 +363,11 @@ export function buildAgentBrief(inputPath, workspaceAst) {
     commandItem("npm run source:status", "See whether template-derived files diverged locally."),
     commandItem("npm run template:explain", "Understand whether the project is template-attached or detached."),
     commandItem("npm run generator:policy:check", "Validate package-backed generator policy before generation."),
+    ...(sdlcPolicy.status === "adopted" ? [
+      commandItem("topogram sdlc policy explain --json", "Read current SDLC enforcement mode and protected paths.", "sdlc"),
+      commandItem("topogram sdlc gate . --require-adopted --json", "Verify protected work has SDLC linkage before PR/CI.", "sdlc"),
+      commandItem("topogram sdlc explain <task-or-bug-id> --json", "Start SDLC-backed implementation from the current task or bug.", "sdlc")
+    ] : []),
     ...(config.implementation ? [
       commandItem("npm run trust:status", "Check executable implementation trust before generation.", "trust")
     ] : []),
@@ -385,6 +422,7 @@ export function buildAgentBrief(inputPath, workspaceAst) {
       safe_paths: [
         `${DEFAULT_TOPO_FOLDER_NAME}/**`,
         "topogram.project.json",
+        SDLC_POLICY_FILE,
         "topogram.template-policy.json",
         GENERATOR_POLICY_FILE,
         ...(config.implementation ? ["implementation/** after review and trust status"] : [])
@@ -396,8 +434,10 @@ export function buildAgentBrief(inputPath, workspaceAst) {
     file_organization: {
       small: [`${DEFAULT_TOPO_FOLDER_NAME}/actors`, `${DEFAULT_TOPO_FOLDER_NAME}/entities`, `${DEFAULT_TOPO_FOLDER_NAME}/shapes`, `${DEFAULT_TOPO_FOLDER_NAME}/capabilities`, `${DEFAULT_TOPO_FOLDER_NAME}/widgets`, `${DEFAULT_TOPO_FOLDER_NAME}/projections`, `${DEFAULT_TOPO_FOLDER_NAME}/verifications`],
       large: [`${DEFAULT_TOPO_FOLDER_NAME}/domains/<domain>`, `${DEFAULT_TOPO_FOLDER_NAME}/shared`, `${DEFAULT_TOPO_FOLDER_NAME}/domains/<domain>/widgets`, `${DEFAULT_TOPO_FOLDER_NAME}/domains/<domain>/projections`],
+      sdlc: [`${DEFAULT_TOPO_FOLDER_NAME}/sdlc/pitches`, `${DEFAULT_TOPO_FOLDER_NAME}/sdlc/requirements`, `${DEFAULT_TOPO_FOLDER_NAME}/sdlc/acceptance_criteria`, `${DEFAULT_TOPO_FOLDER_NAME}/sdlc/tasks`, `${DEFAULT_TOPO_FOLDER_NAME}/sdlc/plans`, `${DEFAULT_TOPO_FOLDER_NAME}/sdlc/bugs`, `${DEFAULT_TOPO_FOLDER_NAME}/sdlc/decisions`],
       parserRule: "Folder layout is for humans and agents; Topogram flattens statements into one graph."
     },
+    sdlc_policy: sdlcPolicy,
     topology: {
       runtimes: summarizeRuntimes(config),
       outputs: summarizeOutputBoundaries(config)
@@ -415,7 +455,7 @@ export function buildAgentBrief(inputPath, workspaceAst) {
     import: importSummary,
     warnings: []
   };
-  payload.warnings = buildWarnings(projectRoot, config, payload.trust, importSummary, generatorPolicy);
+  payload.warnings = buildWarnings(projectRoot, config, payload.trust, importSummary, generatorPolicy, sdlcPolicy);
   return { ok: true, payload };
 }
 
@@ -430,6 +470,7 @@ export function formatAgentBrief(brief) {
   lines.push(`Topogram: ${brief.project?.topogram || "unknown"}`);
   lines.push(`Template: ${brief.template?.id || "none"}${brief.template?.version ? `@${brief.template.version}` : ""}`);
   lines.push(`Implementation trust: ${brief.trust?.requiresTrust ? (brief.trust.ok ? "trusted" : "review required") : "not required"}`);
+  lines.push(`SDLC policy: ${brief.sdlc_policy?.status || "not_adopted"}${brief.sdlc_policy?.mode ? `/${brief.sdlc_policy.mode}` : ""}`);
   lines.push(`Package-backed generators: ${brief.generator_policy?.packageBackedGenerators || 0}`);
   lines.push("");
   lines.push("Read order:");
@@ -473,6 +514,9 @@ export function formatAgentBrief(brief) {
   lines.push("");
   lines.push("Verification gates:");
   lines.push("  - npm run check");
+  if (brief.sdlc_policy?.status === "adopted") {
+    lines.push(`  - ${brief.sdlc_policy.gateCommand || "topogram sdlc gate . --require-adopted"}`);
+  }
   lines.push("  - topogram widget check --json when UI/widget contracts change");
   lines.push("  - topogram widget behavior --json when widget behavior changes");
   lines.push("  - npm run generate");

package/src/archive/archive.js

@@ -4,7 +4,7 @@
 // Strategy:
 //   1. Validate the statement is in a status eligible for archiving.
 //   2. Build the archive entry (frozen snapshot + transitions).
-//   3. Append to `_archive/{kind}s-{year}.jsonl`.
+//   3. Append to `sdlc/_archive/{kind}s-{year}.jsonl`.
 //   4. Surgically remove the statement block from its source `.tg` file.
 //
 // `archiveBatch` is the bulk counterpart used by `release`.

package/src/archive/jsonl.js

@@ -1,7 +1,7 @@
 // Year-bucketed JSONL archive I/O.
 //
-// File layout: `<project-root>/topo/_archive/{kind}s-{year}.jsonl`
-// or `<workspace-root>/_archive/{kind}s-{year}.jsonl`
+// File layout: `<project-root>/topo/sdlc/_archive/{kind}s-{year}.jsonl`
+// or `<workspace-root>/sdlc/_archive/{kind}s-{year}.jsonl`
 // (e.g. `tasks-2026.jsonl`, `bugs-2026.jsonl`).
 //
 // Each line is a self-contained archived statement. The format is JSONL so
@@ -9,11 +9,15 @@
 
 import { existsSync, mkdirSync, readFileSync, appendFileSync, readdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { topogramRootForSdlc } from "../sdlc/paths.js";
+import { sdlcRootForSdlc, topogramRootForSdlc } from "../sdlc/paths.js";
 
 const ARCHIVE_DIR = "_archive";
 
 export function archiveDir(workspaceRoot) {
+  return path.join(sdlcRootForSdlc(workspaceRoot), ARCHIVE_DIR);
+}
+
+function legacyArchiveDir(workspaceRoot) {
   return path.join(topogramRootForSdlc(workspaceRoot), ARCHIVE_DIR);
 }
 
@@ -29,11 +33,17 @@ function ensureArchiveDir(workspaceRoot) {
 }
 
 export function listArchiveFiles(workspaceRoot) {
-  const dir = archiveDir(workspaceRoot);
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir)
-    .filter((name) => name.endsWith(".jsonl"))
-    .map((name) => path.join(dir, name));
+  const dirs = [archiveDir(workspaceRoot), legacyArchiveDir(workspaceRoot)];
+  const files = [];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    files.push(
+      ...readdirSync(dir)
+        .filter((name) => name.endsWith(".jsonl"))
+        .map((name) => path.join(dir, name))
+    );
+  }
+  return files;
 }
 
 export function parseArchiveFile(filePath) {

package/src/archive/resolver-bridge.js

@@ -1,7 +1,7 @@
 // Bridge between archived JSONL entries and the live resolver graph.
 //
 // At workspace load time the resolver bridge:
-//   1. Walks the workspace `_archive/*.jsonl`
+//   1. Walks the workspace `sdlc/_archive/*.jsonl`
 //   2. Builds a flat list of frozen entries (each with `archived: true`)
 //   3. Returns `{ entries, byId }` so the caller can merge them into the
 //      registry / graph
@@ -36,6 +36,11 @@ export function loadArchive(workspaceRoot) {
         errors.push(`${file}: entry id='${raw.id}' has kind '${raw.kind}', expected '${expectedKind}'`);
         continue;
       }
+      const schemaErrors = validateArchivedEntry(file, raw, expectedKind);
+      if (schemaErrors.length > 0) {
+        errors.push(...schemaErrors);
+        continue;
+      }
       entries.push(normalizeArchivedEntry(raw));
     }
   }
@@ -43,6 +48,34 @@ export function loadArchive(workspaceRoot) {
   return { entries, byId, errors };
 }
 
+function validateArchivedEntry(file, raw, expectedKind) {
+  const errors = [];
+  const label = `${file}: archive entry`;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return [`${label} must be an object`];
+  }
+  for (const key of ["id", "kind", "status"]) {
+    if (typeof raw[key] !== "string" || raw[key].trim() === "") {
+      errors.push(`${label} must include string '${key}'`);
+    }
+  }
+  if (expectedKind && typeof raw.kind === "string" && raw.kind !== expectedKind) {
+    errors.push(`${label} id='${raw.id}' has kind '${raw.kind}', expected '${expectedKind}'`);
+  }
+  if (raw.fields !== undefined && (!raw.fields || typeof raw.fields !== "object" || Array.isArray(raw.fields))) {
+    errors.push(`${label} id='${raw.id}' field 'fields' must be an object when present`);
+  }
+  if (!Array.isArray(raw.transitions)) {
+    errors.push(`${label} id='${raw.id}' must include transitions array`);
+  }
+  if (!raw.archived || typeof raw.archived !== "object" || Array.isArray(raw.archived)) {
+    errors.push(`${label} id='${raw.id}' must include archived metadata object`);
+  } else if (typeof raw.archived.at !== "string" || raw.archived.at.trim() === "") {
+    errors.push(`${label} id='${raw.id}' archived metadata must include string 'at'`);
+  }
+  return errors;
+}
+
 function normalizeArchivedEntry(raw) {
   const fields = raw.fields && typeof raw.fields === "object" && !Array.isArray(raw.fields) ? raw.fields : {};
   return {

package/src/archive/schema.js

@@ -8,7 +8,7 @@
 //
 // Documents archive includes the body verbatim.
 
-const ALLOWED_KINDS = new Set(["pitch", "task", "bug", "document"]);
+const ALLOWED_KINDS = new Set(["pitch", "task", "plan", "bug", "document"]);
 
 export function isArchivableKind(kind) {
   return ALLOWED_KINDS.has(kind);

package/src/archive/unarchive.js

@@ -8,6 +8,7 @@
 // Status is reset to a sensible "re-opened" value per kind:
 //   - bug: open
 //   - task: claimed (caller must set claimed_by)
+//   - plan: draft
 //   - pitch: draft
 //   - document: draft
 
@@ -24,6 +25,7 @@ import { resolveTopoRoot } from "../workspace-paths.js";
 const REOPEN_STATUSES = {
   bug: "open",
   task: "claimed",
+  plan: "draft",
   pitch: "draft",
   document: "draft"
 };
@@ -44,6 +46,30 @@ function renderStatement(entry, newStatus) {
   lines.push(`${entry.kind} ${entry.id} {`);
   if (entry.name) lines.push(`  name "${entry.name.replace(/"/g, "\\\"")}"`);
   if (entry.description) lines.push(`  description "${entry.description.replace(/"/g, "\\\"")}"`);
+  if (entry.kind === "plan") {
+    if (entry.fields?.task?.id) lines.push(`  task ${entry.fields.task.id}`);
+    if (entry.fields?.priority) lines.push(`  priority ${entry.fields.priority}`);
+    if (entry.fields?.notes) lines.push(`  notes "${String(entry.fields.notes).replace(/"/g, "\\\"")}"`);
+    if (entry.fields?.outcome) lines.push(`  outcome "${String(entry.fields.outcome).replace(/"/g, "\\\"")}"`);
+    lines.push("  steps {");
+    for (const step of entry.fields?.steps || []) {
+      const parts = [
+        "step",
+        step.id,
+        "status",
+        step.status,
+        "description",
+        `"${String(step.description || "").replace(/"/g, "\\\"")}"`
+      ];
+      if (step.notes) parts.push("notes", `"${String(step.notes).replace(/"/g, "\\\"")}"`);
+      if (step.outcome) parts.push("outcome", `"${String(step.outcome).replace(/"/g, "\\\"")}"`);
+      lines.push(`    ${parts.join(" ")}`);
+    }
+    lines.push("  }");
+    lines.push(`  status ${newStatus}`);
+    lines.push("}");
+    return lines.join("\n") + "\n";
+  }
   for (const [key, value] of Object.entries(entry.fields || {})) {
     if (value == null) continue;
     if (Array.isArray(value)) {

package/src/cli/command-parsers/sdlc.js

@@ -7,6 +7,72 @@ import { commandPath } from "./shared.js";
  * @returns {import("./shared.js").SplitCommandArgs|null}
  */
 export function parseSdlcCommandArgs(args) {
+  if (args[0] === "sdlc" && args[1] === "policy" && ["init", "check", "explain"].includes(args[2])) {
+    return {
+      sdlcCommand: `policy:${args[2]}`,
+      inputPath: commandPath(args, 3, ".")
+    };
+  }
+  if (args[0] === "sdlc" && args[1] === "gate") {
+    return { sdlcCommand: "gate", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "sdlc" && args[1] === "prep" && args[2] === "commit") {
+    return { sdlcCommand: "prep:commit", inputPath: commandPath(args, 3, ".") };
+  }
+  if (args[0] === "sdlc" && args[1] === "link") {
+    return {
+      sdlcCommand: "link",
+      sdlcFromId: args[2],
+      sdlcToId: args[3],
+      inputPath: commandPath(args, 4, ".")
+    };
+  }
+  if (args[0] === "sdlc" && args[1] === "complete") {
+    return {
+      sdlcCommand: "complete",
+      sdlcId: args[2],
+      inputPath: commandPath(args, 3, ".")
+    };
+  }
+  if (args[0] === "sdlc" && args[1] === "plan" && args[2] === "create") {
+    return {
+      sdlcCommand: "plan:create",
+      sdlcId: args[3],
+      sdlcSlug: args[4],
+      inputPath: commandPath(args, 5, ".")
+    };
+  }
+  if (args[0] === "sdlc" && args[1] === "plan" && args[2] === "explain") {
+    return {
+      sdlcCommand: "plan:explain",
+      sdlcId: args[3],
+      inputPath: commandPath(args, 4, ".")
+    };
+  }
+  if (args[0] === "sdlc" && args[1] === "plan" && args[2] === "step" && args[3] === "transition") {
+    return {
+      sdlcCommand: "plan:step:transition",
+      sdlcId: args[4],
+      sdlcStepId: args[5],
+      sdlcTargetStatus: args[6],
+      inputPath: commandPath(args, 7, ".")
+    };
+  }
+  if (args[0] === "sdlc" && args[1] === "plan" && args[2] === "step" && ["start", "complete", "skip"].includes(args[3])) {
+    /** @type {Record<string, string>} */
+    const statusByAction = {
+      start: "in-progress",
+      complete: "done",
+      skip: "skipped"
+    };
+    return {
+      sdlcCommand: `plan:step:${args[3]}`,
+      sdlcId: args[4],
+      sdlcStepId: args[5],
+      sdlcTargetStatus: statusByAction[args[3]],
+      inputPath: commandPath(args, 6, ".")
+    };
+  }
   if (args[0] === "sdlc" && args[1] === "transition") {
     return {
       sdlcCommand: "transition",

package/src/cli/commands/import/help.js

@@ -31,6 +31,7 @@ export function printImportHelp() {
   console.log("Examples:");
   console.log("  topogram import ./existing-app --out ./imported-topogram");
   console.log("  topogram import ./existing-app --out ./imported-topogram --from db,api,ui");
+  console.log("  topogram import ./existing-cli --out ./imported-topogram --from cli");
   console.log("  topogram import diff ./imported-topogram");
   console.log("  topogram import refresh ./imported-topogram --from ./existing-app --dry-run");
   console.log("  topogram import refresh ./imported-topogram --from ./existing-app");