@descix/cli 1.0.7 → 1.0.9

package/agent-assets/rules/descix_mcp.template.mdc

@@ -1,243 +0,0 @@
----
-alwaysApply: true
----
-
-# DeSciX SDK Agent Instructions
-
-You have SDK agent assets available locally at `{{SDK_ASSETS_PATH}}/`.
-
-## Key Architecture Concepts
-
-### Configuration: workspace.json is the Config File
-
-- **`workspace.json`** at `.descix/workspace.json` is the configuration file
-- **Context auto-detection** - CLI commands detect community/app from current working directory
-
-### CLI = Git Mode ONLY
-
-- The CLI only supports **git-mode** operations (local processing with Git version control)
-- **Drive-mode** apps are managed via PWA only (server-side processing)
-- All content starts on Drive - developers pull it locally, then manage with Git
-
-### App Folder Structure (Convention-Based)
-
-```
-my-app/
-├── assets/          # App metadata (icon.png, app_description.md, system_instructions.md)
-├── kb/              # Knowledge base
-│   ├── staging/     # Files to push TO Drive
-│   ├── General/     # Text files pulled FROM Drive
-│   └── chunks/      # Generated JSON chunks (Git-tracked)
-├── site/            # CodeSite static files (optional)
-└── microservice/    # Backend service code (optional)
-```
-
-## Post-Setup Initialization
-
-**IMPORTANT**: Check `.descix/workspace.json` for `_needsAgentSetup: true`.
-
-When this flag is set, the user has just completed `descix mcp quickstart` and needs your help configuring their workspace:
-
-1. **Greet the user** and confirm MCP is working: "I can see your DeSciX setup is complete. Let me help you configure your workspace."
-2. **Show their entitlements** from the cached JSON below (communities and apps they own)
-3. **Ask**: "Which app would you like to configure first?" or "Would you like me to scan your folders and suggest mappings?"
-4. **For each app folder**:
-   - Analyze the folder structure using heuristics from `{{SDK_ASSETS_PATH}}/instructions/folder-analysis.md`
-   - Recommend a packaging type using the decision tree from `{{SDK_ASSETS_PATH}}/instructions/packaging-types.md`
-   - Register the app in `workspace.json` with its localPath and absolutePath
-5. **When done**, set `_needsAgentSetup: false` in workspace.json
-
-If user asks "Help me configure my workspace" or similar, follow this flow.
-
-## Entitlements-First Principle
-
-**CRITICAL**: Users purchase apps/communities in the PWA first. Your role is to help configure local folders for apps they already own.
-
-### On First Interaction
-
-1. Check `.descix/workspace.json` for existing configuration
-2. If `_needsAgentSetup: true`, follow the Post-Setup Initialization flow above
-3. If unconfigured, read `{{SDK_ASSETS_PATH}}/instructions/onboarding-flow.md`
-4. For fresh entitlements: `execute_remote_command({ command: "fetch_my_purchases" })`
-5. Guide user through folder-to-app mapping in `workspace.json`
-
-## Local Asset References
-
-For quick decisions, read these local files (no network required):
-
-| File | Purpose |
-|------|---------|
-| `{{SDK_ASSETS_PATH}}/instructions/packaging-types.md` | App type taxonomy and decision tree |
-| `{{SDK_ASSETS_PATH}}/instructions/folder-analysis.md` | Detect project type from files |
-| `{{SDK_ASSETS_PATH}}/instructions/conversation-guides.md` | Dialogue templates |
-| `{{SDK_ASSETS_PATH}}/instructions/onboarding-flow.md` | Full onboarding workflow |
-
-## Template Usage
-
-When scaffolding apps, use templates from `{{SDK_ASSETS_PATH}}/templates/`:
-
-| Packaging Type | Templates Available |
-|----------------|---------------------|
-| `knowledge-only` | Assets folder only |
-| `static-site` | Site folder scaffold |
-| `microservice` | `manifest.json.template`, `SERVICE_README.template` |
-| `dynamic-site` | Site + microservice scaffolds |
-
-Replace `{{PLACEHOLDER}}` values with actual data from user input.
-
-## User Entitlements (Cached at Setup)
-
-```json
-{{ENTITLEMENTS_JSON}}
-```
-
-**Primary Community**: {{PRIMARY_COMMUNITY}}
-
-Use this cached data for quick checks. For fresh data, call `fetch_my_purchases`.
-
-## Tiered Access Pattern
-
-Use the appropriate tier based on what you need:
-
-### Tier 1: Local Files (Instant)
-```javascript
-// Read instructions directly
-Read("{{SDK_ASSETS_PATH}}/instructions/packaging-types.md")
-```
-**Use for**: Quick lookups, decision trees, templates
-
-### Tier 2: tell_me_how (Semantic Discovery)
-```javascript
-tell_me_how({ 
-  question: "How do I scaffold a microservice?",
-  scope: "entitlements"
-})
-```
-**Use for**: Finding the right tool for a task
-
-### Tier 3: chat_with_kb (Rich Context)
-```javascript
-chat_with_kb({
-  communityId: "daita",
-  appId: "docs",
-  kbId: "sdk",
-  message: "Explain the deployment workflow for dynamic sites"
-})
-```
-**Use for**: Complex questions requiring reasoning
-
-### Tier 4: execute_remote_command (Action)
-```javascript
-execute_remote_command({
-  command: "scaffold_app_type",
-  params: { type: "microservice", app_id: "myapp", ... }
-})
-```
-**Use for**: Actually creating/modifying things
-
-## Tool Discovery
-
-Use `tell_me_how` to discover platform capabilities:
-
-```javascript
-// Discover tools for a task
-tell_me_how({ question: "How do I deploy my app?", scope: "entitlements" })
-
-// Then execute the recommended command
-execute_remote_command({ command: "discovered_command", params: {...} })
-```
-
-**Scope Options**:
-- `project`: Only tools for apps in workspace.json
-- `entitlements`: Tools for all apps user owns (default)
-- `discovery`: All platform tools (may show purchasable)
-
-## App Configuration Workflow
-
-When user wants to configure a folder:
-
-1. **Analyze folder** using heuristics from `folder-analysis.md`
-2. **Recommend packaging type** using decision tree from `packaging-types.md`
-3. **Present options** using dialogue from `conversation-guides.md`
-4. **Register app** in `workspace.json` with localPath and absolutePath
-5. **Guide CLI commands** based on packaging type
-
-## Primary CLI Commands
-
-Guide users to these git-mode commands:
-
-### Knowledge Base Commands
-| Command | Purpose |
-|---------|---------|
-| `descix drive pull` | Pull text-converted content from Drive |
-| `descix drive push` | Push staging files to Drive |
-| `descix kb corpus sync` | Generate JSON chunks from text files |
-| `descix kb corpus sync` | Push chunks to Pinecone |
-| `descix kb corpus sync` | Full pipeline: pull → chunk → sync |
-| `descix kb corpus status` | Show local vs Pinecone sync status |
-
-### Site Commands
-| Command | Purpose |
-|---------|---------|
-| `descix site init` | Copy site scaffold to app |
-| `descix site upload` | Deploy CodeSite to GCS |
-| `descix site servelocal [port]` | Register local dev server port |
-| `descix site list` | List deployed site files |
-| `descix site status` | Get deployment status |
-
-### Microservice Commands
-| Command | Purpose |
-|---------|---------|
-| `descix microservice init` | Copy microservice scaffold to app |
-| `descix microservice register` | Register microservice with gateway |
-| `descix microservice vectorize` | Vectorize README for discovery |
-| `descix microservice list` | List registered microservices |
-| `descix microservice health <name>` | Check microservice health |
-| `descix microservice reload` | Reload manifests (admin) |
-
-**Context Auto-Detection**: When run from within an app directory, these commands auto-detect community/app from `workspace.json`. Otherwise use `-c` and `-a` flags.
-
-## SDK Tools Available (Remote)
-
-These tools are auto-registered and discoverable via `tell_me_how`:
-
-| Tool | Purpose |
-|------|---------|
-| `scaffold_app_type` | Create boilerplate for chosen packaging type |
-| `analyze_folder_structure` | Detect project type from folder contents |
-| `get_app_sync_status` | Check what's synced (KB, site, service) |
-| `fetch_my_purchases` | Get user's entitlements |
-| `register_service` | Register microservice with gateway |
-| `vectorize_service_readme` | Enable tell_me_how discovery |
-
-## Key Principles
-
-1. **Never assume** - Always ask before creating mappings
-2. **Entitlements are truth** - Can't configure apps user doesn't own
-3. **Local first** - Read local assets before making network calls
-4. **Guide, don't dictate** - Present options, let user choose
-5. **workspace.json is truth** - All configuration goes here
-
-## Error Recovery
-
-If commands fail:
-1. Check authentication: Is `wallet.json` valid?
-2. Check entitlements: Does user own the app?
-3. Check configuration: Is app registered in `workspace.json`?
-4. Check location: Are you in the app directory or using `-c/-a` flags?
-5. Use `tell_me_how` to find alternative approaches
-
-### Common Errors
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| "Workspace not configured" | No workspace.json | Run `descix init` |
-| "Could not determine app context" | Not in app directory | `cd` to app or use `-c/-a` flags |
-| "ADC not configured" | Missing Google auth | Run `gcloud auth application-default login` |
-| "App not found in workspace" | App not registered | Run `descix mcp quickstart` or add to workspace.json |
-
----
-
-*Generated by DeSciX SDK Setup*
-*SDK Version: {{SDK_VERSION}}*
-*Workspace: {{WORKSPACE_PATH}}*

package/lib/commands/briefer/errors.js

@@ -1,88 +0,0 @@
-/**
- * BrieferExtractorError — canonical hard-fail surface for the `descix briefer` CLI.
- *
- * Per WS-DESCIX-BRIEFER-CLI scope doc §2.3 ("Hard-fail philosophy"), every data
- * source has exactly one extraction method and exactly one failure mode:
- * HARD-FAIL with an actionable error message.
- *
- * Per feedback_no-hardcoded-fallbacks: NO fallback values, NO best-effort prose,
- * NO try-catch-and-default. If a source moved or changed shape, the CLI exits
- * non-zero and the canonical briefer file remains untouched.
- *
- * Stable error codes (per scope doc §2.3) — grep-friendly for diagnostics:
- *   BRIEFER-SRC-NOT-FOUND   Source file missing / line range no longer matches
- *   BRIEFER-GCLOUD-AUTH     gcloud auth missing or insufficient scope
- *   BRIEFER-GCLOUD-FAIL     gcloud probe failed (auth/empty/timeout) when --env=demo|prod required it
- *   BRIEFER-PARSE-FAIL      Source file present but construct unparseable
- *   BRIEFER-DRIFT-DETECTED  --check diff against canonical briefer non-empty
- *   BRIEFER-NEGATIVE-CLAIM  Briefer claims X does not exist, but found at Y:Z
- *   BRIEFER-FIRESTORE       Firestore read via apifront failed
- *   BRIEFER-NOT-IMPLEMENTED M1 stub — extractor scaffold-only, real impl in later milestone
- *
- * Per scope doc §2.3, every error message must include:
- *   1. The exact source path + line range that was being read.
- *   2. The construct shape that was expected.
- *   3. What the operator should do to recover.
- *   4. A stable error code from the list above.
- */
-
-export const BRIEFER_ERROR_CODES = Object.freeze({
-  SRC_NOT_FOUND: 'BRIEFER-SRC-NOT-FOUND',
-  GCLOUD_AUTH: 'BRIEFER-GCLOUD-AUTH',
-  PARSE_FAIL: 'BRIEFER-PARSE-FAIL',
-  DRIFT_DETECTED: 'BRIEFER-DRIFT-DETECTED',
-  NEGATIVE_CLAIM: 'BRIEFER-NEGATIVE-CLAIM',
-  FIRESTORE: 'BRIEFER-FIRESTORE',
-  GCLOUD_FAIL: 'BRIEFER-GCLOUD-FAIL',
-  NOT_IMPLEMENTED: 'BRIEFER-NOT-IMPLEMENTED',
-  WORKSPACE_NOT_FOUND: 'BRIEFER-WORKSPACE-NOT-FOUND'
-});
-
-export class BrieferExtractorError extends Error {
-  /**
-   * @param {object} args
-   * @param {string} args.code       One of BRIEFER_ERROR_CODES (REQUIRED).
-   * @param {string} args.section    Briefer section being extracted (e.g., '§3 routing').
-   * @param {string} args.source     File path or 'gcloud' or 'firestore' (REQUIRED).
-   * @param {string} args.expected   Construct shape that was expected (REQUIRED).
-   * @param {string} args.recovery   Concrete next step for the operator (REQUIRED).
-   * @param {string} [args.detail]   Optional extra context (e.g., parser msg, exit code).
-   */
-  constructor({ code, section, source, expected, recovery, detail } = {}) {
-    if (!code || !Object.values(BRIEFER_ERROR_CODES).includes(code)) {
-      // Hard-fail loud on misuse — caller is constructing a bad error.
-      // We do NOT default the code; per feedback_no-hardcoded-fallbacks the
-      // absence of a code is itself a misconfiguration we want to surface.
-      throw new Error(
-        `BrieferExtractorError requires a valid 'code'. Got: ${JSON.stringify(code)}. ` +
-        `Valid codes: ${Object.values(BRIEFER_ERROR_CODES).join(', ')}.`
-      );
-    }
-    if (!source) {
-      throw new Error(`BrieferExtractorError requires a 'source' (file path / 'gcloud' / 'firestore').`);
-    }
-    if (!expected) {
-      throw new Error(`BrieferExtractorError requires an 'expected' construct shape description.`);
-    }
-    if (!recovery) {
-      throw new Error(`BrieferExtractorError requires a 'recovery' instruction for the operator.`);
-    }
-
-    const lines = [
-      `[${code}] ${section || '(section unspecified)'}`,
-      `  source:   ${source}`,
-      `  expected: ${expected}`,
-      `  recovery: ${recovery}`
-    ];
-    if (detail) lines.push(`  detail:   ${detail}`);
-
-    super(lines.join('\n'));
-    this.name = 'BrieferExtractorError';
-    this.code = code;
-    this.section = section || null;
-    this.source = source;
-    this.expected = expected;
-    this.recovery = recovery;
-    this.detail = detail || null;
-  }
-}

package/lib/commands/briefer/index.js

@@ -1,322 +0,0 @@
-/**
- * `descix briefer` — main entry point.
- *
- * Per WS-DESCIX-BRIEFER-CLI scope doc §2 (Architecture / Option A):
- *
- *   descix briefer [--env=dev|demo|prod] [--out=PATH] [--check]
- *
- * Reads the per-section data sources defined in scope doc §2.2, dispatches to
- * the per-section extractors in ./sources/*.js, and emits a structured
- * BrieferDoc object. The stitcher composes the markdown; --check mode diffs
- * the regen against the canonical briefer file.
- *
- * HARD-FAIL philosophy (scope doc §2.3 + feedback_no-hardcoded-fallbacks):
- * every extractor that can't find its source data throws BrieferExtractorError
- * with a stable error code. No fallback strings. No try-catch-and-default.
- *
- * M1 SCOPE (this implementation):
- *   - CLI subcommand registration in bin/descix.js (separate edit).
- *   - This entry orchestrates 7 stub extractors.
- *   - Stitcher composes a real (non-empty) markdown with TODO placeholder bodies.
- *   - --check runs the full extraction, diffs against canonical, prints a
- *     unified-style diff, exits non-zero on drift (which is EXPECTED for M1 —
- *     stubs WILL differ from the manually-authored canonical briefer).
- *
- * M2+ SCOPE (NOT IMPLEMENTED HERE):
- *   - Real AST/regex parsing of source files.
- *   - Live gcloud probes.
- *   - Firestore Products counts via apifront.
- *   - MustKnow KB partition + auto-sync.
- *   - Bootstrap protocol edits (/cos skill, @bootstrap agent).
- *   - CI --check gate.
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import chalk from 'chalk';
-import { fileURLToPath } from 'url';
-
-import { BrieferExtractorError, BRIEFER_ERROR_CODES } from './errors.js';
-import { stitchBriefer, extractCitationTrail } from './stitcher.js';
-
-import * as identifiers from './sources/identifiers.js';
-import * as environments from './sources/environments.js';
-import * as routing from './sources/routing.js';
-import * as microserviceDeploy from './sources/microservice-deploy.js';
-import * as entitlements from './sources/entitlements.js';
-import * as whatIsNot from './sources/what-is-not.js';
-import * as canonicalSources from './sources/canonical-sources.js';
-
-import { WorkspaceConfig } from '../../workspace-config.js';
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Extractor dispatch table (scope doc §2.2 ordering)
-// ─────────────────────────────────────────────────────────────────────────────
-export const EXTRACTORS = Object.freeze([
-  identifiers,
-  environments,
-  routing,
-  microserviceDeploy,
-  entitlements,
-  whatIsNot,
-  canonicalSources
-]);
-
-export const VALID_ENVS = Object.freeze(['dev', 'demo', 'prod']);
-
-// Default output path (scope doc §2.1). Resolved relative to workspace root
-// via WorkspaceConfig.getWorkspaceRoot() — never a hardcoded absolute path.
-export const DEFAULT_OUT_RELATIVE = 'DeSciX/V2_docs/architecture/platform-must-know-briefer.md';
-
-const MECHANISM_TAG = 'descix briefer v1.0 (M2 — code-grounded extractors)';
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function resolveCliPaths() {
-  // Resolve the descix-cli root from this file's location, then walk up to
-  // DeSciX_Core and the parent repo. M2/M3 extractors that read source files
-  // will need these to anchor file reads.
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const descixCliRoot = path.resolve(here, '../../..');                // .../descix-cli
-  const descixCoreRoot = path.resolve(descixCliRoot, '..');             // .../DeSciX_Core
-  const desciXRoot = path.resolve(descixCoreRoot, '..');                // .../DeSciX
-  const repoRoot = path.resolve(desciXRoot, '..');                      // .../Unkamon
-  return { descixCliRoot, descixCoreRoot, desciXRoot, repoRoot };
-}
-
-export function resolveOutPath(cliOut, workspaceConfig, cliPaths, cwd) {
-  // Explicit override always wins.
-  if (cliOut) return path.resolve(cliOut);
-
-  // Default: workspace-root-relative path.
-  if (workspaceConfig) {
-    const wsRoot = workspaceConfig.getWorkspaceRoot();
-    return path.join(wsRoot, DEFAULT_OUT_RELATIVE);
-  }
-
-  // HARD-FAIL per feedback_no-hardcoded-fallbacks. The previous implementation
-  // derived a default from cliPaths.repoRoot (computed from the CLI file
-  // location), which silently produced a wrong path like
-  // "Unkamon/DeSciX/DeSciX/V2_docs/..." (double DeSciX/) when invoked from
-  // inside descix-cli/ with no workspace.json in cwd. No silent path-guessing.
-  throw new BrieferExtractorError({
-    code: BRIEFER_ERROR_CODES.WORKSPACE_NOT_FOUND,
-    section: 'briefer entry',
-    source: cwd || '(unknown cwd)',
-    expected: 'either .descix/workspace.json reachable by upward search, OR --out=<path>',
-    recovery: 'Run from your workspace root (where .descix/workspace.json lives), or pass --out=<path> explicitly.',
-    detail: `cliPaths.repoRoot was previously used as a silent fallback (resolved to ${cliPaths.repoRoot}); that fallback is removed.`
-  });
-}
-
-async function resolveRegenBy() {
-  // Best signal we have without forcing an auth round-trip in M1. M2 will
-  // require auth (for apifront/Firestore calls) and can use the wallet email
-  // from apiClient.loadCredentials() — at that point this changes to a hard
-  // requirement. For M1 scaffolding we just tag the system user.
-  return process.env.USER || process.env.USERNAME || 'unknown';
-}
-
-// Minimal unified-style diff (line-based). Avoids adding a new npm dependency
-// for the M1 scaffold; M2 may swap in the `diff` package if richer output is
-// needed (currently an unanswered question §9.1 in scope doc — Babel dep).
-function simpleLineDiff(a, b, { aLabel = 'canonical', bLabel = 'regen' } = {}) {
-  const aLines = (a || '').split(/\r?\n/);
-  const bLines = (b || '').split(/\r?\n/);
-  const out = [`--- ${aLabel}`, `+++ ${bLabel}`];
-  const max = Math.max(aLines.length, bLines.length);
-  let inHunk = false;
-  for (let i = 0; i < max; i++) {
-    const av = aLines[i];
-    const bv = bLines[i];
-    if (av === bv) {
-      if (inHunk) { out.push(' ' + (av ?? '')); inHunk = false; }
-      continue;
-    }
-    if (!inHunk) {
-      out.push(`@@ line ${i + 1} @@`);
-      inHunk = true;
-    }
-    if (av !== undefined) out.push(`-${av}`);
-    if (bv !== undefined) out.push(`+${bv}`);
-  }
-  return out.join('\n');
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// BrieferDoc — the structured object returned by buildBrieferDoc()
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * @typedef {object} BrieferSectionResult
- * @property {{number: number, heading: string, sourceFiles: string[]}} section
- * @property {{markdown: string, citations: object[]}} extract
- */
-
-/**
- * @typedef {object} BrieferDoc
- * @property {string} env
- * @property {string} mechanism
- * @property {string} regenBy
- * @property {BrieferSectionResult[]} sections
- * @property {string} markdown        Final stitched markdown.
- * @property {string[]} citationTrail Hidden HTML-comment trail (one per line).
- */
-
-/**
- * Run all extractors and return the BrieferDoc.
- *
- * @param {object} opts
- * @param {string} opts.env
- * @param {object} opts.cliPaths
- * @param {object|null} [opts.apiClient]  Optional in M1 (stubs don't need it).
- * @param {object|null} [opts.gcloud]     Optional in M1 (stubs don't need it).
- * @param {string}  opts.regenBy
- * @param {string} [opts.mechanism]
- * @returns {Promise<BrieferDoc>}
- */
-export async function buildBrieferDoc({ env, cliPaths, apiClient = null, gcloud = null, regenBy, mechanism = MECHANISM_TAG }) {
-  const sections = [];
-  for (const extractor of EXTRACTORS) {
-    const result = await extractor.extract({ env, cliPaths, gcloud, apiClient });
-    sections.push({ section: extractor.SECTION, extract: result });
-  }
-  const markdown = stitchBriefer({ env, mechanism, regenBy, sections });
-  const citationTrail = extractCitationTrail(markdown);
-  return { env, mechanism, regenBy, sections, markdown, citationTrail };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Public CLI entry — invoked by bin/descix.js `briefer` subcommand
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * @param {object} options Commander options object.
- * @param {string} [options.env]      dev|demo|prod (default: 'dev' for M1; M2 will hard-fail dev per scope doc §2.1).
- * @param {string} [options.out]      Output path override.
- * @param {boolean} [options.check]   Drift-detection mode: regen to memory, diff against canonical, exit non-zero on drift.
- * @param {boolean} [options.verbose] Print per-source timing + extractor names.
- */
-export async function runBriefer(options = {}) {
-  const env = (options.env || 'dev').toLowerCase();
-  if (!VALID_ENVS.includes(env)) {
-    console.error(chalk.red(`\n❌ Invalid --env=${options.env}. Must be one of: ${VALID_ENVS.join(', ')}\n`));
-    process.exit(1);
-  }
-
-  // Per scope §2.1: --env=dev is rejected by the routing extractor specifically
-  // (DEV has no LB URL map). Other extractors accept dev because they read
-  // only source files (no gcloud probe required). The rejection lives in
-  // sources/routing.js; this entry point passes env through unchanged.
-  if (options.verbose) {
-    console.log(chalk.gray(`[briefer] env=${env}`));
-  }
-
-  const cliPaths = resolveCliPaths();
-  const cwd = process.cwd();
-  let workspaceConfig = null;
-  try {
-    workspaceConfig = await WorkspaceConfig.tryLoad(cwd);
-  } catch (error) {
-    // tryLoad returns null on a MISSING workspace; it throws only when workspace.json EXISTS
-    // and cannot be read. Hard-fail per philosophy — do NOT proceed with a guessed default.
-    //
-    // The recovery text is the loader's own, not a second opinion invented here: it used to say
-    // "run `descix init` to regenerate", which prescribes overwriting the very file that could
-    // not be read, and which also contradicts the standing rule against hand-editing it.
-    throw new BrieferExtractorError({
-      code: BRIEFER_ERROR_CODES.PARSE_FAIL,
-      section: 'briefer entry',
-      source: '.descix/workspace.json',
-      expected: 'valid v2.1 workspace JSON',
-      recovery: error.message
-    });
-  }
-
-  const outPath = resolveOutPath(options.out, workspaceConfig, cliPaths, cwd);
-  const regenBy = await resolveRegenBy();
-
-  if (options.verbose) {
-    console.log(chalk.gray(`[briefer] outPath=${outPath}`));
-    console.log(chalk.gray(`[briefer] regenBy=${regenBy}`));
-    console.log(chalk.gray(`[briefer] extractors=${EXTRACTORS.length}`));
-  }
-
-  // Build the briefer doc. Each extractor is run sequentially; M2 can
-  // parallelize if hot-path latency matters (it likely won't for 7 sources).
-  let doc;
-  try {
-    doc = await buildBrieferDoc({ env, cliPaths, regenBy });
-  } catch (err) {
-    if (err instanceof BrieferExtractorError) {
-      console.error(chalk.red(`\n❌ Briefer extraction failed:\n`));
-      console.error(chalk.red(err.message));
-      console.error('');
-      process.exit(1);
-    }
-    throw err;
-  }
-
-  if (options.check) {
-    return runCheckMode({ doc, outPath, verbose: options.verbose });
-  }
-
-  // Write mode — overwrite the canonical briefer file.
-  await fs.mkdir(path.dirname(outPath), { recursive: true });
-  await fs.writeFile(outPath, doc.markdown, 'utf-8');
-
-  console.log(chalk.green(`\n✅ Briefer regenerated\n`));
-  console.log(chalk.cyan(`  Env:       ${env}`));
-  console.log(chalk.gray (`  Mechanism: ${doc.mechanism}`));
-  console.log(chalk.gray (`  By:        ${regenBy}`));
-  console.log(chalk.gray (`  Out:       ${outPath}`));
-  console.log(chalk.gray (`  Sections:  ${doc.sections.length}`));
-  console.log(chalk.gray (`  Citations: ${doc.citationTrail.length}\n`));
-  return doc;
-}
-
-export async function runCheckMode({ doc, outPath, verbose }) {
-  let canonical = null;
-  try {
-    canonical = await fs.readFile(outPath, 'utf-8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      console.error(chalk.red(`\n❌ --check failed: canonical briefer not found at ${outPath}\n`));
-      console.error(chalk.gray('   Run `descix briefer` (without --check) to create it.\n'));
-      process.exit(2);
-    }
-    throw err;
-  }
-
-  if (canonical === doc.markdown) {
-    console.log(chalk.green(`\n✅ Briefer is in sync — no drift detected.\n`));
-    return { drift: false, doc };
-  }
-
-  // Drift detected. Print a unified-style diff and exit non-zero.
-  // Per scope doc §2.2 §3, --check also compares the citation trail. For M1
-  // we report both prose-drift and citation-drift counts.
-  const canonicalTrail = extractCitationTrail(canonical);
-  const regenTrail = doc.citationTrail;
-  const trailChanged = (canonicalTrail.length !== regenTrail.length) ||
-    canonicalTrail.some((c, i) => c !== regenTrail[i]);
-
-  console.error(chalk.yellow(`\n⚠ [${BRIEFER_ERROR_CODES.DRIFT_DETECTED}] Briefer drift detected.\n`));
-  console.error(chalk.gray(`  Canonical:    ${outPath}`));
-  console.error(chalk.gray(`  Regen length: ${doc.markdown.length} bytes`));
-  console.error(chalk.gray(`  Canon length: ${canonical.length} bytes`));
-  console.error(chalk.gray(`  Citation trail drift: ${trailChanged ? 'YES' : 'no'}\n`));
-
-  if (verbose) {
-    console.error(simpleLineDiff(canonical, doc.markdown, { aLabel: outPath, bLabel: 'regen (in-memory)' }));
-    console.error('');
-  } else {
-    console.error(chalk.gray('  (Run with --verbose for the full diff.)\n'));
-  }
-
-  // M2: drift means a source-of-truth file changed shape since last regen.
-  // Caller should regenerate (run `descix briefer` without --check) and commit
-  // the updated canonical briefer.
-  process.exit(1);
-}