ai-spec-dev 0.30.1 → 0.33.0

package/.claude/settings.local.json

@@ -4,7 +4,11 @@
       "Bash(npm run:*)",
       "Bash(python3 -c \":*)",
       "Bash(grep -E \"^./\\\\w+/|^./\\\\w+\\\\.ts$\")",
-      "Bash(wc -l core/*.ts prompts/*.ts)"
+      "Bash(wc -l core/*.ts prompts/*.ts)",
+      "Bash(npx tsc:*)",
+      "Bash(npm install:*)",
+      "Bash(npx vitest:*)",
+      "Bash(npm test:*)"
     ]
   }
 }

package/README.md

@@ -93,7 +93,7 @@ ai-spec create "给用户模块增加登录功能"
         [cycle 2/2] Running tests: npm test
         ✔ Tests passed.
         ✔ All checks passed after 2 cycle(s).
-[9/9]   Automated code review (3-pass: architecture + implementation + impact/complexity)...
+[9/10]  Automated code review (3-pass: architecture + implementation + impact/complexity)...
         Pass 1/3: Architecture review...
         Pass 2/3: Implementation review...
         Pass 3/3: Impact & complexity assessment...
@@ -1259,6 +1259,32 @@ Attempting auto-fix (3 error(s))...
 
 ---
 
+### Step 10 — Harness Self-Eval
+
+代码审查完成后自动执行，**零 AI 调用**，纯确定性评分：
+
+| 维度 | 评分逻辑 |
+|------|---------|
+| DSL Coverage (0-10) | 生成文件是否覆盖 DSL 声明的 endpoint 层和 model 层 |
+| Compile Score (0-10) | error feedback 全通过 → 10；未通过 / 跳过 → 5 |
+| Review Score (0-10) | 从 3-pass review 文本提取 `Score: X/10` |
+
+**Harness Score** = 加权平均（DSL 40% + Compile 30% + Review 30%）
+
+```
+─── Harness Self-Eval ───────────────────────────
+  Score  : [████████░░] 7.8/10
+  DSL    : 8/10  Compile: pass  Review: 7.2/10
+  Prompt : a3f2c1d8
+─────────────────────────────────────────────────
+```
+
+- `harnessScore` 和 `promptHash` 写入 RunLog（`.ai-spec-logs/<runId>.json`）
+- 每次改动 prompt 文件后，`promptHash` 自动变化，结合 `harnessScore` 可量化 prompt 改动的效果
+- 后续可通过脚本聚合多个 RunLog，绘制 harnessScore × promptHash 的趋势图
+
+---
+
 ## 多 Repo 工作区模式
 
 当父目录中存在 `.ai-spec-workspace.json` 时，`ai-spec create` 自动切换为**多 Repo 联动模式**，一句需求驱动前后端全链路实现。
@@ -1525,6 +1551,8 @@ ai-spec-dev-poc/
 │   ├── reviewer.ts                 # AI 代码审查（git diff / 文件内容双模式）
 │   ├── test-generator.ts           # 测试骨架生成器（DSL → Jest/Vitest 骨架）
 │   ├── error-feedback.ts           # 错误反馈自动修复（测试+lint检测 · 依赖图排序修复 · AI修复循环）
+│   ├── prompt-hasher.ts            # [v0.31.0] Prompt Hash：6 个核心 prompt 的 SHA-256 短 hash
+│   ├── self-evaluator.ts           # [v0.31.0] Harness Self-Eval：零 AI 调用，DSL覆盖+编译+review加权评分
 │   ├── knowledge-memory.ts         # 经验积累：审查 issue → 宪法§9
 │   ├── workspace-loader.ts         # [Phase 4] 工作区配置加载 + repo 类型自动检测
 │   ├── requirement-decomposer.ts   # [Phase 4] 需求跨 repo 拆分 + UX 决策生成

package/RELEASE_LOG.md

@@ -2,6 +2,194 @@
 
 ---
 
+## [0.33.0] 2026-03-30 — Pipeline 反馈环：DSL Gap Loop + Review→DSL Loop
+
+### 新增内容
+
+**Feature — 两条 Pipeline 反馈环（`core/dsl-feedback.ts`、`cli/index.ts`）**
+
+原有流水线是严格单向的——每一步的输出只能向前传递，review 发现的问题只能写入 §9，DSL 提取稀疏也只能硬着头皮继续。v0.33.0 在两个关键位置插入局部反馈环，让 pipeline 在保持可测量性的前提下具备弹性。
+
+---
+
+**Loop 1 — DSL Gap Feedback（DSL 提取完成 → Worktree 之前）**
+
+- 新增 `assessDslRichness(dsl)` — 纯启发式检查，零 AI 调用，检测四类常见 DSL 缺口：
+
+  | 缺口类型 | 检测逻辑 |
+  |----------|---------|
+  | `no_models_no_endpoints` | DSL 完全为空——spec 可能太抽象 |
+  | `generic_endpoint_desc`  | endpoint description < 15 字符或以模糊动词开头（handles/管理/处理…）|
+  | `missing_errors`         | ≥2 个 endpoint 且全部无 errors 定义 |
+  | `sparse_model`           | model 字段数 < 2 |
+
+- 发现缺口时，交互模式下展示具体缺口列表并提供选择：
+  - `🔧 Refine spec` — AI 执行定向 spec 补全（`buildDslGapRefinementPrompt`），不改变功能范围，只填充缺失细节 → 自动重新提取 DSL
+  - `⏭ Skip` — 继续用当前 DSL
+
+- `--auto` / `--fast` / `--skip-dsl` 模式下完全跳过此 Loop
+- 结果写入 RunLog `dsl_gap_feedback` 阶段（action: `refined` / `skipped` / `refinement_error`）
+
+---
+
+**Loop 2 — Review → DSL Structural Feedback（§9 知识积累 → Self-Eval 之前）**
+
+- 新增 `extractStructuralFindings(reviewText)` — 解析 Pass 1（架构审查）文本，识别设计层问题（而非实现层问题）：
+
+  | 类别 | 触发模式 |
+  |------|---------|
+  | `auth_design`      | 缺少认证 / missing auth / 鉴权缺 |
+  | `api_contract`     | 接口设计问题 / API design / 接口缺少 |
+  | `model_design`     | 模型缺少字段 / model missing field / schema incomplete |
+  | `layer_violation`  | 层级违反 / layer violation / 分层问题 |
+
+  Pass 1 得分 ≥ 8 时认为架构没问题，自动跳过分类
+
+- 发现结构性问题时展示区别于 §9 的"设计层警告"，并提供三种选择：
+  - `🔧 Amend spec + update DSL` — AI 根据结构性发现定向修订 spec → 重新提取 DSL → 覆盖保存 spec 文件和 DSL 文件 → 提示 `ai-spec update --codegen` 重新生成受影响文件
+  - `📝 Note in §9 only` — §9 已由 knowledge accumulation 写入，DSL 不变
+  - `⏭ Skip`
+
+- 关键设计决策：Loop 2 **不自动触发 codegen**。DSL 修正后提示用户主动运行 `update --codegen`，保持人在决策节点的控制权
+- `--auto` 模式下完全跳过此 Loop（不增加 CI 耗时）
+- 结果写入 RunLog `review_dsl_feedback` 阶段
+
+---
+
+**新流水线结构：**
+
+```
+Spec → DSL 提取
+         ↓
+    [Loop 1] DSL Gap 检测
+         ↓ (不满足 → 定向 spec 补全 → 重新提取 DSL)
+    Approval Gate → Worktree → Codegen → ErrorFix → Review
+                                                        ↓
+                                                   §9 知识积累
+                                                        ↓
+                                               [Loop 2] 结构性问题检测
+                                                        ↓ (发现 → spec 修订 → DSL 更新)
+                                                   Self-Eval → Done
+```
+
+---
+
+## [0.32.0] 2026-03-30 — Harness 数据闭环：`trend` / `logs` 命令 + DSL Coverage 细化评分
+
+### 新增内容
+
+**Feature #1 — `ai-spec trend` 跨运行趋势命令（`core/run-trend.ts`、`cli/index.ts`）**
+
+- 新增 `core/run-trend.ts` — 趋势分析模块：
+  - `loadRunLogs(workingDir)` — 扫描 `.ai-spec-logs/*.json`，按运行时间倒序排列，静默跳过损坏文件
+  - `buildTrendReport(logs, opts)` — 从 RunLog 数组生成趋势报告：按 `promptHash` 分组，统计 avg / best / worst；支持 `last` 和 `promptFilter` 选项
+  - `printTrendReport(report, workingDir)` — 彩色表格输出，分为「Prompt 版本摘要」和「运行历史」两区，当前 prompt 版本用 `◀ current` 标记
+- 新增 CLI 命令 `ai-spec trend`：
+  ```bash
+  ai-spec trend              # 最近 15 次有评分的运行，按 promptHash 分组
+  ai-spec trend --last 30    # 最近 30 次
+  ai-spec trend --prompt a3f # 只看 hash 以 a3f 开头的 prompt 版本
+  ai-spec trend --json       # 输出原始 JSON，适合脚本聚合分析
+  ```
+  输出示例：
+  ```
+  ─── Harness Trend ───────────────────────────────────────────────
+    Prompt Versions:
+    Hash        Runs   Avg  Best Worst  Last seen
+    ─────────────────────────────────────────────────────────
+    a3f2c1d8       3   7.6   8.2   6.9  2026-03-30 ◀ current
+    b1e4a2f0       5   6.8   7.4   5.5  2026-03-29
+
+    Run History:
+    2026-03-30  [████████░░] 7.8  a3f2c1d8  1m24s  feature-login-v1.md
+    2026-03-30  [████████░░] 8.2  a3f2c1d8  1m18s  feature-user-v1.md
+    ...
+  ```
+
+**Feature #2 — `ai-spec logs` 运行日志列表命令（`cli/index.ts`）**
+
+- 新增 CLI 命令 `ai-spec logs`：
+  ```bash
+  ai-spec logs               # 列出最近 10 次运行（runId、日期、score、文件数、耗时）
+  ai-spec logs --last 20     # 列出最近 20 次
+  ai-spec logs <runId>       # 展示该次运行的完整阶段耗时表格
+  ```
+  单次运行详情示例：
+  ```
+  ─── Run: 20260330-143022-a7f2 ─────────────────────────────────
+    Started : 2026-03-30T14:30:22.000Z
+    Provider: gemini / gemini-2.5-pro
+    Prompt  : a3f2c1d8
+    Score   : 7.8/10
+    Stages:
+      ✔  context_load            0.3s
+      ✔  spec_gen                18.4s
+      ✔  dsl_extract             6.1s
+      ✔  codegen                 51.2s
+      ✔  review                  14.8s
+      ✔  self_eval               0.0s
+  ```
+- 结尾提示 `ai-spec logs <runId>` 和 `ai-spec trend`，引导用户进入分析工作流
+
+### 功能增强
+
+**Enhancement — DSL Coverage Score 三层细化评分（`core/self-evaluator.ts`）**
+
+原有评分只做二元判断（endpoint 层有无、model 层有无），无法反映实际覆盖深度。新增两个 Tier：
+
+| Tier | 检查项 | 扣分规则 |
+|------|--------|--------|
+| Tier 1（原有）| endpoint 层存在 / model 层存在 | -4 / -3（同前）|
+| **Tier 2（新增）** | Model name 覆盖率：对每个 DSL 声明的 model，检查其名称（含 camelCase → snake_case 规范化）是否出现在任何生成文件路径中 | coverage < 50% → -2；50-79% → -1；≥80% → 0 |
+| **Tier 3（新增）** | Endpoint 文件充足性：≥5 个端点但 endpoint 层文件 < 2 个 | -1 |
+
+- 新增 `modelNameTokens(name)` — 将 PascalCase 模型名规范化为多种路径匹配 token（`OrderItem` → `orderitem` / `order-item` / `order_item`）
+- `SelfEvalResult.detail` 新增 `endpointLayerFiles`、`modelNameCoverage`、`modelNameMatched` 字段，写入 RunLog 供后续分析
+- `printSelfEval()` 当存在 DSL model 时新增 Detail 行：
+  ```
+  ─── Harness Self-Eval ───────────────────────────
+    Score  : [████████░░] 7.8/10
+    DSL    : 8/10  Compile: pass  Review: 7.2/10
+    Detail : Models: 3/4 (75%)  Endpoints: 5  Files: 9
+    Prompt : a3f2c1d8
+  ─────────────────────────────────────────────────
+  ```
+
+---
+
+## [0.31.0] 2026-03-29 — Harness Engineer：Prompt Hash + Create 内联 Self-Eval
+
+### 新增内容
+
+**Feature #1 — Prompt Hash 关联（`core/prompt-hasher.ts`、`core/run-logger.ts`）**
+
+- 新增 `computePromptHash()` — 对 6 个核心 prompt 字符串（codegen、DSL extractor、spec generator、review 三 pass）计算 SHA-256 并取前 8 位，返回形如 `a3f2c1d8` 的短 hex 字符串
+- `RunLog` 新增 `promptHash?: string` 字段；`RunLogger` 新增 `setPromptHash()` + `setHarnessScore()` 方法
+- `ai-spec create` 运行开始时立即调用 `computePromptHash()` 写入 RunLog，任何 prompt 文件改动都会产生不同的 hash
+- **目的**：跨多次运行对比 `harnessScore` 时，可以精确知道「这两次用的 prompt 版本是否相同」，将 prompt 改动的效果从模型随机性中解耦
+
+**Feature #2 — Create 内联 Harness Self-Eval（`core/self-evaluator.ts`、`cli/index.ts`）**
+
+- 新增 `core/self-evaluator.ts` — 零 AI 调用的确定性评分模块：
+  - **DSL Coverage Score (0-10)**：检查 `generatedFiles` 中是否存在 endpoint 层文件（`src/api*`、`src/routes*`、`src/controller*`…）和 model 层文件（`src/model*`、`prisma/`、`src/db*`…），与 DSL 中声明的 endpoint / model 数量对照
+  - **Compile Score (0-10)**：`runErrorFeedback()` 返回 `true` → 10，未通过 / 跳过 → 5
+  - **Review Score (0-10)**：从 3-pass review 文本中提取 `Score: X/10`（与 `reviewer.ts` 同规则），review 跳过时为 null
+  - **Harness Score**：加权平均（有 review：DSL×40% + Compile×30% + Review×30%；无 review：DSL×55% + Compile×45%）
+- `runErrorFeedback()` 的返回值（`boolean`）现在被接住赋给 `compilePassed`，传入 self-eval
+- `ai-spec create` Step 9（code review）之后新增 **Step 10: Harness Self-Eval**，完成后打印：
+
+  ```
+  ─── Harness Self-Eval ───────────────────────────
+    Score  : [████████░░] 7.8/10
+    DSL    : 8/10  Compile: pass  Review: 7.2/10
+    Prompt : a3f2c1d8
+  ─────────────────────────────────────────────────
+  ```
+
+- `harnessScore` 和所有维度分数写入 RunLog 的 `self_eval:done` 事件 + 根级 `harnessScore` 字段，便于后续脚本聚合分析
+
+---
+
 ## [0.30.0] 2026-03-29 — 错误修复依赖图排序 + 前端 Import 多行感知解析
 
 ### 改进内容

package/cli/commands/config.ts

@@ -0,0 +1,93 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { CodeGenMode } from "../../core/code-generator";
+import { clearAllKeys, clearKey, getSavedKey, KEY_STORE_FILE } from "../../core/key-store";
+import { AiSpecConfig, CONFIG_FILE, loadConfig } from "../utils";
+
+export function registerConfig(program: Command): void {
+  program
+    .command("config")
+    .description(`Set default configuration for this project (saved to ${CONFIG_FILE})`)
+    .option("--provider <name>", "Default AI provider for spec generation")
+    .option("--model <name>", "Default model for spec generation")
+    .option("--codegen <mode>", "Default code generation mode (claude-code|api|plan)")
+    .option("--codegen-provider <name>", "Default provider for code generation")
+    .option("--codegen-model <name>", "Default model for code generation")
+    .option("--min-spec-score <score>", "Minimum overall spec score (1-10) to pass Approval Gate (0 = disabled)")
+    .option("--show", "Print current configuration")
+    .option("--reset", "Reset configuration to empty")
+    .option("--clear-keys", "Delete all saved API keys from ~/.ai-spec-keys.json")
+    .option("--clear-key <provider>", "Delete saved API key for a specific provider")
+    .option("--list-keys", "Show which providers have a saved key")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+      const configPath = path.join(currentDir, CONFIG_FILE);
+
+      if (opts.clearKeys) {
+        await clearAllKeys();
+        console.log(chalk.green(`✔ All saved API keys cleared.`));
+        return;
+      }
+
+      if (opts.clearKey) {
+        await clearKey(opts.clearKey);
+        console.log(chalk.green(`✔ Saved key for "${opts.clearKey}" removed.`));
+        return;
+      }
+
+      if (opts.listKeys) {
+        const store: Record<string, string> = await fs.readJson(KEY_STORE_FILE).catch(() => ({}));
+        const providers = Object.keys(store);
+        if (providers.length === 0) {
+          console.log(chalk.gray("No saved API keys."));
+        } else {
+          console.log(chalk.bold("Saved API keys:"));
+          for (const p of providers) {
+            const k = store[p];
+            console.log(chalk.gray(`  ${p}: ${k.slice(0, 6)}...${k.slice(-4)}`));
+          }
+          console.log(chalk.gray(`\nFile: ${KEY_STORE_FILE}`));
+        }
+        return;
+      }
+
+      if (opts.reset) {
+        await fs.writeJson(configPath, {}, { spaces: 2 });
+        console.log(chalk.green(`✔ Config reset: ${configPath}`));
+        return;
+      }
+
+      const existing: AiSpecConfig = await loadConfig(currentDir);
+
+      if (opts.show) {
+        if (Object.keys(existing).length === 0) {
+          console.log(chalk.gray("No config file found. Using built-in defaults."));
+        } else {
+          console.log(chalk.bold(`${configPath}:`));
+          console.log(JSON.stringify(existing, null, 2));
+        }
+        return;
+      }
+
+      const updated: AiSpecConfig = { ...existing };
+      if (opts.provider) updated.provider = opts.provider;
+      if (opts.model) updated.model = opts.model;
+      if (opts.codegen) updated.codegen = opts.codegen as CodeGenMode;
+      if (opts.codegenProvider) updated.codegenProvider = opts.codegenProvider;
+      if (opts.codegenModel) updated.codegenModel = opts.codegenModel;
+      if (opts.minSpecScore !== undefined) {
+        const score = parseInt(opts.minSpecScore, 10);
+        if (isNaN(score) || score < 0 || score > 10) {
+          console.error(chalk.red("  --min-spec-score must be a number between 0 and 10"));
+          process.exit(1);
+        }
+        updated.minSpecScore = score;
+      }
+
+      await fs.writeJson(configPath, updated, { spaces: 2 });
+      console.log(chalk.green(`✔ Config saved to ${configPath}`));
+      console.log(JSON.stringify(updated, null, 2));
+    });
+}

package/cli/commands/export.ts

@@ -0,0 +1,66 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { SpecDSL } from "../../core/dsl-types";
+import { exportOpenApi } from "../../core/openapi-exporter";
+import { findLatestDslFile } from "../../core/mock-server-generator";
+
+export function registerExport(program: Command): void {
+  program
+    .command("export")
+    .description("Export the latest DSL to OpenAPI 3.1.0 (YAML or JSON)")
+    .option("--openapi", "Export as OpenAPI 3.1.0 (default behaviour)")
+    .option("--format <fmt>", "Output format: yaml | json (default: yaml)", "yaml")
+    .option("--output <path>", "Output file path (default: openapi.yaml)")
+    .option("--server <url>", "API server URL in the OpenAPI document (default: http://localhost:3000)")
+    .option("--dsl <path>", "Path to a specific .dsl.json file (auto-detected if omitted)")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+
+      // ── Find DSL ────────────────────────────────────────────────────────────
+      let dslPath: string | null = opts.dsl ?? null;
+      if (!dslPath) {
+        dslPath = await findLatestDslFile(currentDir);
+        if (!dslPath) {
+          console.error(chalk.red("  No .dsl.json file found. Run `ai-spec create` first or use --dsl <path>."));
+          process.exit(1);
+        }
+        console.log(chalk.gray(`  Using DSL: ${path.relative(currentDir, dslPath)}`));
+      }
+
+      let dsl: SpecDSL;
+      try {
+        dsl = await fs.readJson(dslPath);
+      } catch (err) {
+        console.error(chalk.red(`  Failed to read DSL: ${(err as Error).message}`));
+        process.exit(1);
+      }
+
+      // ── Export ──────────────────────────────────────────────────────────────
+      console.log(chalk.blue("\n─── ai-spec export ─────────────────────────────"));
+
+      const format = (opts.format === "json" ? "json" : "yaml") as "yaml" | "json";
+      const serverUrl = opts.server || "http://localhost:3000";
+
+      try {
+        const outputPath = await exportOpenApi(dsl, currentDir, {
+          format,
+          serverUrl,
+          outputPath: opts.output,
+        });
+        const rel = path.relative(currentDir, outputPath);
+        console.log(chalk.green(`  ✔ OpenAPI ${format.toUpperCase()} exported: ${rel}`));
+        console.log(chalk.gray(`  Feature  : ${dsl.feature.title}`));
+        console.log(chalk.gray(`  Endpoints: ${dsl.endpoints.length}`));
+        console.log(chalk.gray(`  Models   : ${dsl.models.length}`));
+        console.log(chalk.gray(`  Server   : ${serverUrl}`));
+        console.log(chalk.blue("\n  Next steps:"));
+        console.log(chalk.gray(`  • Import ${rel} into Postman / Insomnia / Swagger UI`));
+        console.log(chalk.gray(`  • Use openapi-generator to generate client SDKs`));
+      } catch (err) {
+        console.error(chalk.red(`  Export failed: ${(err as Error).message}`));
+        process.exit(1);
+      }
+    });
+}

package/cli/commands/init.ts

@@ -0,0 +1,153 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { createProvider, DEFAULT_MODELS, SUPPORTED_PROVIDERS } from "../../core/spec-generator";
+import { ContextLoader } from "../../core/context-loader";
+import { ConstitutionGenerator, CONSTITUTION_FILE } from "../../core/constitution-generator";
+import { ConstitutionConsolidator } from "../../core/constitution-consolidator";
+import {
+  loadGlobalConstitution,
+  saveGlobalConstitution,
+  GLOBAL_CONSTITUTION_FILE,
+} from "../../core/global-constitution";
+import {
+  globalConstitutionSystemPrompt,
+  buildGlobalConstitutionPrompt,
+} from "../../prompts/global-constitution.prompt";
+import { loadConfig, resolveApiKey } from "../utils";
+
+export function registerInit(program: Command): void {
+  program
+    .command("init")
+    .description(`Analyze codebase and generate Project Constitution (${CONSTITUTION_FILE})`)
+    .option(
+      "--provider <name>",
+      `AI provider (${SUPPORTED_PROVIDERS.join("|")})`,
+      undefined
+    )
+    .option("--model <name>", "Model name")
+    .option("-k, --key <apiKey>", "API key")
+    .option("--force", "Overwrite existing constitution")
+    .option(
+      "--global",
+      `Generate a Global Constitution (~/${GLOBAL_CONSTITUTION_FILE}) instead of a project-level one`
+    )
+    .option("--consolidate", "Consolidate §9 accumulated lessons into §1–§8 core rules (prune & rebase)")
+    .option("--dry-run", "Preview consolidation result without writing (use with --consolidate)")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+      const config = await loadConfig(currentDir);
+
+      const providerName = opts.provider || config.provider || "gemini";
+      const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
+      const apiKey = await resolveApiKey(providerName, opts.key);
+      const provider = createProvider(providerName, apiKey, modelName);
+
+      // ── Consolidate mode ───────────────────────────────────────────────────
+      if (opts.consolidate) {
+        const consolidator = new ConstitutionConsolidator(provider);
+        try {
+          const result = await consolidator.consolidate(currentDir, {
+            dryRun: opts.dryRun,
+            auto: opts.auto,
+          });
+          if (result.written) {
+            console.log(chalk.blue("\n  Summary:"));
+            console.log(chalk.gray(`  Lines : ${result.before.totalLines} → ${result.after.totalLines} (${result.before.totalLines - result.after.totalLines > 0 ? "-" : "+"}${Math.abs(result.before.totalLines - result.after.totalLines)})`));
+            console.log(chalk.gray(`  §9    : ${result.before.lessonCount} → ${result.after.lessonCount} lessons remaining`));
+            if (result.backupPath) {
+              console.log(chalk.gray(`  Backup: ${path.basename(result.backupPath)}`));
+            }
+          }
+        } catch (err) {
+          console.error(chalk.red(`  ✘ Consolidation failed: ${(err as Error).message}`));
+          process.exit(1);
+        }
+        return;
+      }
+
+      // ── Global constitution mode ───────────────────────────────────────────
+      if (opts.global) {
+        const existing = await loadGlobalConstitution([currentDir]);
+        if (existing && !opts.force) {
+          console.log(chalk.yellow(`\n  Global constitution already exists at: ${existing.source}`));
+          console.log(chalk.gray("  Use --force to overwrite it."));
+          return;
+        }
+
+        console.log(chalk.blue("\n─── Generating Global Constitution ──────────────"));
+        console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
+        console.log(chalk.gray("  Scanning repos in workspace..."));
+
+        const loader = new ContextLoader(currentDir);
+        const ctx = await loader.loadProjectContext();
+        const summary = [
+          `Tech stack: ${ctx.techStack.join(", ") || "unknown"}`,
+          `Dependencies: ${ctx.dependencies.slice(0, 20).join(", ")}`,
+        ].join("\n");
+
+        const prompt = buildGlobalConstitutionPrompt([{ name: path.basename(currentDir), summary }]);
+        let globalConstitution: string;
+        try {
+          globalConstitution = await provider.generate(prompt, globalConstitutionSystemPrompt);
+        } catch (err) {
+          console.error(chalk.red("  ✘ Failed to generate global constitution:"), err);
+          process.exit(1);
+        }
+
+        const saved = await saveGlobalConstitution(globalConstitution, currentDir);
+        console.log(chalk.green(`\n  ✔ Global constitution saved: ${saved}`));
+        console.log(chalk.gray("  This will be automatically merged into all project constitutions in this workspace."));
+        console.log(chalk.gray("  Project-level rules always override global rules.\n"));
+        console.log(chalk.bold("  Preview:"));
+        console.log(chalk.gray(globalConstitution.split("\n").slice(0, 12).join("\n")));
+        if (globalConstitution.split("\n").length > 12) {
+          console.log(chalk.gray(`  ... (${globalConstitution.split("\n").length} lines total)`));
+        }
+        return;
+      }
+
+      // ── Project constitution mode (default) ───────────────────────────────
+      const constitutionPath = path.join(currentDir, CONSTITUTION_FILE);
+
+      if (!opts.force && (await fs.pathExists(constitutionPath))) {
+        console.log(chalk.yellow(`\n  ${CONSTITUTION_FILE} already exists.`));
+        console.log(chalk.gray("  Use --force to overwrite it."));
+        console.log(chalk.gray(`  Or edit it directly: ${constitutionPath}`));
+        return;
+      }
+
+      console.log(chalk.blue("\n─── Generating Project Constitution ─────────────"));
+      console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
+      console.log(chalk.gray("  Analyzing codebase..."));
+
+      const generator = new ConstitutionGenerator(provider);
+
+      let constitution: string;
+      try {
+        constitution = await generator.generate(currentDir);
+      } catch (err) {
+        console.error(chalk.red("  ✘ Failed to generate constitution:"), err);
+        process.exit(1);
+      }
+
+      const saved = await generator.saveConstitution(currentDir, constitution);
+
+      const globalResult = await loadGlobalConstitution([path.dirname(currentDir)]);
+      if (globalResult) {
+        console.log(chalk.cyan(`\n  ℹ Global constitution detected: ${globalResult.source}`));
+        console.log(chalk.gray("    It will be merged with this project constitution at runtime."));
+        console.log(chalk.gray("    Project rules take priority over global rules."));
+      }
+
+      console.log(chalk.green(`\n  ✔ Constitution saved: ${saved}`));
+      console.log(chalk.gray("  This file will be automatically used in all future `ai-spec create` runs."));
+      console.log(chalk.gray("  Edit it to add custom rules or red lines for your project.\n"));
+      console.log(chalk.bold("  Preview:"));
+      console.log(chalk.gray(constitution.split("\n").slice(0, 15).join("\n")));
+      if (constitution.split("\n").length > 15) {
+        console.log(chalk.gray(`  ... (${constitution.split("\n").length} lines total)`));
+      }
+    });
+}

package/cli/commands/learn.ts

@@ -0,0 +1,30 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { input } from "@inquirer/prompts";
+import { appendDirectLesson } from "../../core/knowledge-memory";
+
+export function registerLearn(program: Command): void {
+  program
+    .command("learn")
+    .description("Append a lesson or engineering decision directly to constitution §9")
+    .argument("[lesson]", "The lesson or decision to record (prompted if omitted)")
+    .action(async (lesson: string | undefined) => {
+      const currentDir = process.cwd();
+
+      if (!lesson) {
+        lesson = await input({
+          message: "What lesson or engineering decision should be recorded?",
+          validate: (v) => v.trim().length > 0 || "Please enter a lesson",
+        });
+      }
+
+      const result = await appendDirectLesson(currentDir, lesson.trim());
+
+      if (result.appended) {
+        console.log(chalk.green(`\n  ✔ Lesson appended to constitution §9`));
+        console.log(chalk.gray(`  File: .ai-spec-constitution.md`));
+      } else {
+        console.log(chalk.yellow(`\n  ⚠ Not appended: ${result.reason}`));
+      }
+    });
+}