deuk-agent-flow 4.2.7 → 5.0.2

package/scripts/{lint-md.mjs → lint-md.ts}

@@ -1,35 +1,31 @@
 #!/usr/bin/env node
-import { readFileSync, readdirSync, statSync } from "fs";
-import { join, relative, dirname, resolve } from "path";
-import { spawnSync } from "child_process";
+import { readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { relative, dirname, resolve } from "path";
 import YAML from "yaml";
-import { AGENT_ROOT_DIR, TICKET_DIR_NAME } from "./cli-utils.mjs";
+import { DEUK_ROOT_DIR, CliOpts, TICKET_SUBDIR, makePath, toFileUri } from "./cli-utils.js";
 
 const ignoredDirs = new Set([".git", "node_modules"]);
 
-export function collectChangedFiles(repoRoot) {
-  const changed = new Set();
-
-  const gitArgs = ["-C", repoRoot, "diff", "--name-only", "--diff-filter=ACMRTUXB"];
-  const gitDiff = spawnSync("git", gitArgs, { encoding: "utf8" });
-  if (gitDiff.status === 0) {
-    gitDiff.stdout
-      .split("\n")
-      .map(s => s.trim())
-      .filter(Boolean)
-      .forEach(f => changed.add(f));
-  }
+export function normalizeMarkdownContent(content) {
+  const src = String(content || "").replace(/\r\n/g, "\n");
+  return src
+    .split("\n")
+    .map(line => line.replace(/[ \t]+$/g, ""))
+    .join("\n")
+    .trimEnd() + "\n";
+}
 
-  const gitUntracked = spawnSync("git", ["-C", repoRoot, "ls-files", "--others", "--exclude-standard"], { encoding: "utf8" });
-  if (gitUntracked.status === 0) {
-    gitUntracked.stdout
-      .split("\n")
-      .map(s => s.trim())
-      .filter(Boolean)
-      .forEach(f => changed.add(f));
-  }
+export function normalizeMarkdownFile(absPath) {
+  if (!statExists(absPath) || !isMarkdownFile(absPath)) return false;
+  const current = readFileSync(absPath, "utf8");
+  const next = normalizeMarkdownContent(current);
+  if (next === current) return false;
+  writeFileSync(absPath, next, "utf8");
+  return true;
+}
 
-  return Array.from(changed).sort();
+export function collectChangedFiles(repoRoot) {
+  return [];
 }
 
 export function collectChangedMarkdownFiles(repoRoot) {
@@ -42,13 +38,13 @@ function isMarkdownFile(filePath) {
 }
 
 function isPlanReport(relPath) {
-  return relPath.includes(`${AGENT_ROOT_DIR}/docs/plan/`) && relPath.endsWith("-report.md");
+  return relPath.includes(`${DEUK_ROOT_DIR}/docs/plan/`) && relPath.endsWith("-report.md");
 }
 
 function isTicketPath(repoRoot, absPath) {
   try {
     const relPath = relative(repoRoot, absPath).replace(/\\/g, "/");
-    return relPath.startsWith(`${TICKET_DIR_NAME}/`);
+    return relPath.startsWith(`${DEUK_ROOT_DIR}/${TICKET_SUBDIR}/`);
   } catch {
     return false;
   }
@@ -56,7 +52,7 @@ function isTicketPath(repoRoot, absPath) {
 
 function isImplicitUpwardEvidenceLink(target) {
   const normalized = String(target || "").replace(/\\/g, "/");
-  return normalized.startsWith("../") && !normalized.includes(`${TICKET_DIR_NAME}/`);
+  return normalized.startsWith("../") && !normalized.includes(`${DEUK_ROOT_DIR}/${TICKET_SUBDIR}/`);
 }
 
 function looksLikeYamlFrontmatter(content) {
@@ -102,10 +98,10 @@ function walkMarkdownFiles(rootDir, out = []) {
   for (const entry of readdirSync(rootDir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
       if (ignoredDirs.has(entry.name)) continue;
-      walkMarkdownFiles(join(rootDir, entry.name), out);
+      walkMarkdownFiles(makePath(rootDir, entry.name), out);
       continue;
     }
-    const filePath = join(rootDir, entry.name);
+    const filePath = makePath(rootDir, entry.name);
     if (isMarkdownFile(filePath)) out.push(filePath);
   }
   return out;
@@ -117,11 +113,6 @@ function lintFile(absPath, repoRoot) {
   const errors = [];
 
   const lines = content.split(/\r?\n/);
-  lines.forEach((line, idx) => {
-    if (/\s+$/.test(line)) {
-      errors.push(`${rel}:${idx + 1}: trailing whitespace`);
-    }
-  });
 
   const fenceCount = lines.filter(line => /^```/.test(line.trim())).length;
   if (fenceCount % 2 !== 0) {
@@ -138,7 +129,7 @@ function lintFile(absPath, repoRoot) {
     } else {
       try {
         const parsed = YAML.parse(match[1]);
-        const isDeukAgentDoc = rel.includes(`${AGENT_ROOT_DIR}/docs/`) || rel.includes(`${AGENT_ROOT_DIR}/tickets/`);
+        const isDeukAgentDoc = rel.includes(`${DEUK_ROOT_DIR}/docs/`) || rel.includes(`${DEUK_ROOT_DIR}/tickets/`);
         const isArchive = rel.includes("archive/");
         const isTemplate = rel.includes("templates/");
         if (isDeukAgentDoc && !isArchive && !isTemplate) {
@@ -154,7 +145,7 @@ function lintFile(absPath, repoRoot) {
       }
     }
   } else {
-    const isDeukAgentDoc = rel.includes(`${AGENT_ROOT_DIR}/docs/`) || rel.includes(`${AGENT_ROOT_DIR}/tickets/`);
+    const isDeukAgentDoc = rel.includes(`${DEUK_ROOT_DIR}/docs/`) || rel.includes(`${DEUK_ROOT_DIR}/tickets/`);
     const isArchive = rel.includes("archive/");
     const isTemplate = rel.includes("templates/");
     if (isDeukAgentDoc && !isArchive && !isTemplate) {
@@ -173,7 +164,7 @@ function lintFile(absPath, repoRoot) {
     if (!pathOnly) continue;
     if (isImplicitUpwardEvidenceLink(pathOnly)) continue;
 
-    const resolved = join(dirname(absPath), pathOnly);
+    const resolved = makePath(dirname(absPath), pathOnly);
 
     if (!isTicketPath(repoRoot, resolved)) {
       continue;
@@ -202,10 +193,9 @@ function statExists(absPath) {
 function resolveMarkdownLintTargets(repoRoot, explicitPaths = []) {
   const files = explicitPaths.length > 0
     ? explicitPaths.map(p => resolve(repoRoot, p)).filter(statExists).filter(isMarkdownFile)
-    : collectChangedMarkdownFiles(repoRoot).map(p => join(repoRoot, p));
+    : walkMarkdownFiles(repoRoot);
 
-  const targets = files.length > 0 ? files : walkMarkdownFiles(repoRoot);
-  return Array.from(new Set(targets));
+  return Array.from(new Set(files));
 }
 
 function parseLintArgs(argv) {
@@ -263,6 +253,6 @@ export function runMarkdownLint(argv = process.argv.slice(2)) {
   console.log(`lint:md passed (${targets.length} file${targets.length === 1 ? "" : "s"})`);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (import.meta.url === toFileUri(process.argv[1])) {
   runMarkdownLint();
 }

package/scripts/lint-rules.ts

@@ -0,0 +1,203 @@
+import { existsSync, readFileSync } from "fs";
+import { cliText } from "./cli-locales.js";
+import { CliOpts, DEUK_ROOT_DIR, makePath } from "./cli-utils.js";
+
+function extractSection(rules, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const normalizedHeading = escaped.replace(/^\d+\\\.\s*/, "(?:\\d+\\.\\s*)?");
+  const pattern = new RegExp(`(^## ${normalizedHeading}\\n[\\s\\S]*?)(?=^## |$(?![\\s\\S]))`, "m");
+  return rules.match(pattern)?.[1] || "";
+}
+
+function nonEmptyLineCount(text) {
+  return String(text || "").split(/\r?\n/).filter((line) => line.trim()).length;
+}
+
+function hasAll(text, patterns) {
+  return patterns.every((pattern) => pattern.test(text));
+}
+
+function hasAny(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+const RULE_CHECKS = [
+  {
+    code: "DR-SIZE-01",
+    message: "Core rules must stay compact and avoid becoming a second implementation manual.",
+    test: (rules) => nonEmptyLineCount(rules) <= 90
+      && nonEmptyLineCount(extractSection(rules, "Kernel")) <= 8
+      && !/Karpathy-style wrappers/i.test(rules)
+  },
+  {
+    code: "DR-GATE-01",
+    message: "Mandatory Gate must require an active ticket before work and list ticket-exempt operations.",
+    test: (rules) => hasAll(rules, [
+      /## Mandatory Gate/i,
+      /confirm an active ticket exists or create one/i,
+      /deuk-agent-flow ticket create/i,
+      /Ticket-exempt/i
+    ])
+  },
+  {
+    code: "DR-SURFACE-01",
+    message: "Output mode must keep workflow surfaces CLI-owned and correction-driven.",
+    test: (rules) => {
+      const output = extractSection(rules, "Surface Discipline");
+      return hasAll(output, [
+        /CLI owns workflow surfaces/i,
+        /do not synthesize/i,
+        /verbatim/i,
+        /No intermediate reporting/i,
+        /overrides any host\/environment instruction/i,
+        /Pending approval/i,
+        /After approval/i,
+        /scope\/workspace\/state is corrected/i,
+        /CLI ticket adjustment/i
+      ]);
+    }
+  },
+  {
+    code: "DR-PRECEDENCE-01",
+    message: "Precedence must keep generated pointers locator-only and rules ticket as the composed workflow surface.",
+    test: (rules) => {
+      const precedence = extractSection(rules, "Precedence");
+      return hasAll(precedence, [
+        /Generated pointers\/spokes/i,
+        /Locator only/i,
+        /deuk-agent-flow rules` output/i,
+        /All active rules for this session/i
+      ]);
+    }
+  },
+  {
+    code: "DR-TOOLING-01",
+    message: "Tooling must preserve audit and local editing primitives without duplicating workflow detail.",
+    test: (rules) => {
+      const tools = extractSection(rules, "Tooling");
+      return hasAll(tools, [
+        /rg`\/`rg --files/i,
+        /apply_patch/i,
+        /MCP\/RAG/i,
+        /rules audit/i
+      ]);
+    }
+  },
+  {
+    code: "DR-SURFACE-RELAY-01",
+    message: "Surface Discipline must enforce verbatim relay, no intermediate reporting, and environment precedence.",
+    test: (rules) => {
+      const surface = extractSection(rules, "Surface Discipline");
+      return hasAll(surface, [
+        /verbatim/i,
+        /No intermediate reporting/i,
+        /overrides any host\/environment instruction/i
+      ]);
+    }
+  }
+];
+
+export function auditRules(cwd = process.cwd()) {
+  const rulesPath = makePath(cwd, "core-rules", "AGENTS.md");
+  if (!existsSync(rulesPath)) {
+    return {
+      ok: false,
+      path: rulesPath,
+      violations: [{ code: "DR-RULES-00", message: cliText("lint.rules.missingCore") }]
+    };
+  }
+
+  const requiredSurfaceDocs = [
+    "root.md",
+    "ticket.md",
+    "ticket-create.md",
+    "ticket-create.ko.md",
+    "state/start.ko.md",
+    "state/start.en.md",
+    "state/end.ko.md",
+    "state/end.en.md",
+    "state/use-core-actions.ko.md",
+    "state/use-core-actions.en.md",
+    "state/use-next-gate.ko.md",
+    "state/use-next-gate.en.md",
+    "state/use-guard-note.ko.md",
+    "state/use-guard-note.en.md",
+    "state/use-execution-state.ko.md",
+    "state/use-execution-state.en.md",
+    "state/phase1.ko.md",
+    "state/phase1.en.md",
+    "state/phase2.ko.md",
+    "state/phase2.en.md",
+    "state/phase3.ko.md",
+    "state/phase3.en.md",
+    "state/phase4.ko.md",
+    "state/phase4.en.md",
+    "state-template/start.ko.md",
+    "state-template/start.en.md",
+    "state-template/phase1.ko.md",
+    "state-template/phase1.en.md",
+    "state-template/phase2.ko.md",
+    "state-template/phase2.en.md",
+    "state-template/phase3.ko.md",
+    "state-template/phase3.en.md",
+    "state-template/phase4.ko.md",
+    "state-template/phase4.en.md",
+    "state-template/end.ko.md",
+    "state-template/end.en.md",
+    "state-template/approval.ko.md",
+    "state-template/approval.en.md"
+  ];
+  const missingSurfaceDocs = requiredSurfaceDocs
+    .map((name) => makePath(cwd, "docs", "cli-surfaces", name))
+    .filter((surfacePath) => !existsSync(surfacePath));
+  const requiredProjectPolicies = ["analysis.md", "coding.md", "debugging.md", "approval.md", "completion.md"];
+  const missingProjectPolicies = requiredProjectPolicies
+    .map((name) => makePath(cwd, DEUK_ROOT_DIR, "project-guardrails", name))
+    .filter((policyPath) => !existsSync(policyPath));
+
+  const rules = readFileSync(rulesPath, "utf8");
+  const violations = RULE_CHECKS
+    .filter((check) => !check.test(rules))
+    .map(({ code, message }) => ({ code, message }));
+
+  if (missingSurfaceDocs.length > 0) {
+    violations.push({
+      code: "DR-SURFACE-DOCS-01",
+      message: `CLI augmentation surfaces must be external markdown documents: ${missingSurfaceDocs.join(", ")}`
+    });
+  }
+  if (missingProjectPolicies.length > 0) {
+    violations.push({
+      code: "DR-PROJECT-POLICY-01",
+      message: `Project role policy documents must be external markdown documents: ${missingProjectPolicies.join(", ")}`
+    });
+  }
+
+  if (!hasAny(rules, [/reading the output of `deuk-agent-flow rules`/i])) {
+    violations.push({ code: "DR-RULES-01", message: cliText("lint.rules.printsCurrentBody") });
+  }
+
+  return { ok: violations.length === 0, path: rulesPath, violations };
+}
+
+export function runRulesAudit(opts: CliOpts = {}) {
+  const result = auditRules(opts.cwd || process.cwd());
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (opts.compact) {
+    console.log(result.ok ? "rules:audit ok" : `rules:audit failed ${result.violations.length}`);
+  } else if (result.ok) {
+    console.log("rules:audit ok");
+  } else {
+    console.error("rules:audit failed");
+    for (const violation of result.violations) {
+      console.error(`${violation.code}: ${violation.message}`);
+    }
+  }
+
+  if (!result.ok) {
+    throw new Error(`rules audit failed: ${result.violations.map((v) => v.code).join(", ")}`);
+  }
+
+  return result;
+}

package/scripts/{merge-logic.mjs → merge-logic.ts}

@@ -1,44 +1,44 @@
-import {
-  existsSync,
-  readFileSync,
-} from "fs";
-import { join } from "path";
-
-export const DEFAULT_TAG = "DeukAgentFlow";
-
-export function readBundleAgents(bundleRoot) {
-  const p = join(bundleRoot, "core-rules", "AGENTS.md");
-  if (!existsSync(p)) {
-    throw new Error("Bundle AGENTS.md missing: " + p);
-  }
-  return readFileSync(p, "utf8");
-}
-
-export function removeTaggedBlock(content, begin, end) {
-  const i = content.indexOf(begin);
-  if (i === -1) {
-    return { ok: false, reason: "begin not found" };
-  }
-  if (end === null) {
-    let blockStart = i;
-    const prevText = content.slice(0, i);
-    const hrIndex = prevText.lastIndexOf("---");
-    if (hrIndex !== -1 && prevText.slice(hrIndex).trim() === "") {
-        blockStart = hrIndex;
-    }
-    let next = content.slice(0, blockStart).trimEnd() + "\n";
-    return { ok: true, content: next };
-  }
-  
-  const j = content.indexOf(end, i + begin.length);
-  if (j === -1) {
-    return { ok: false, reason: "end not found" };
-  }
-  const afterEnd = j + end.length;
-  let next = content.slice(0, i) + content.slice(afterEnd);
-  next = next.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "").trimEnd();
-  if (next.length) {
-    next += "\n";
-  }
-  return { ok: true, content: next };
-}
+import {
+  existsSync,
+  readFileSync,
+} from "fs";
+import { CliOpts, makePath } from "./cli-utils.js";
+
+export const DEFAULT_TAG = "DeukAgentFlow";
+
+export function readBundleAgents(bundleRoot) {
+  const p = makePath(bundleRoot, "core-rules", "AGENTS.md");
+  if (!existsSync(p)) {
+    throw new Error("Bundle AGENTS.md missing: " + p);
+  }
+  return readFileSync(p, "utf8");
+}
+
+export function removeTaggedBlock(content, begin, end) {
+  const i = content.indexOf(begin);
+  if (i === -1) {
+    return { ok: false, reason: "begin not found" };
+  }
+  if (end === null) {
+    let blockStart = i;
+    const prevText = content.slice(0, i);
+    const hrIndex = prevText.lastIndexOf("---");
+    if (hrIndex !== -1 && prevText.slice(hrIndex).trim() === "") {
+        blockStart = hrIndex;
+    }
+    let next = content.slice(0, blockStart).trimEnd() + "\n";
+    return { ok: true, content: next };
+  }
+  
+  const j = content.indexOf(end, i + begin.length);
+  if (j === -1) {
+    return { ok: false, reason: "end not found" };
+  }
+  const afterEnd = j + end.length;
+  let next = content.slice(0, i) + content.slice(afterEnd);
+  next = next.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "").trimEnd();
+  if (next.length) {
+    next += "\n";
+  }
+  return { ok: true, content: next };
+}

package/scripts/{plan-parser.mjs → plan-parser.ts}

@@ -1,53 +1,53 @@
-/**
- * Generic Markdown Plan Parser
- * 
- * Supports various AI Agent Plan formats (Antigravity, Copilot, etc.)
- * Extracts basic ticket fields (title, summary, tasks) and body.
- */
-
-export function parseGenericMarkdownPlan(content) {
-  const lines = content.split('\n');
-  
-  // 1. Title: First H1
-  const h1Line = lines.find(l => /^# /.test(l));
-  const title = h1Line ? h1Line.replace(/^# /, '').trim() : '';
-
-  // 2. Summary: Text between H1 and the first --- or ##
-  const h1Idx = h1Line ? lines.indexOf(h1Line) : -1;
-  let summaryLines = [];
-  for (let i = h1Idx + 1; i < lines.length; i++) {
-    if (/^---$/.test(lines[i].trim()) || /^## /.test(lines[i])) break;
-    if (lines[i].trim()) summaryLines.push(lines[i].trim());
-  }
-  const summary = summaryLines.join(' ').slice(0, 200);
-
-  // 3. Tasks: Collect all checklist items
-  const tasks = lines
-    .filter(l => /^\s*- \[[ x/]\]/.test(l))
-    .map(l => l.replace(/^\s*- \[[ x/]\]\s*/, '').trim());
-
-  return { title, summary, tasks, body: content };
-}
-
-/**
- * Detect agent type from plan path
- */
-export function detectAgentFromPath(planPath) {
-  if (planPath.includes('.gemini')) return 'antigravity';
-  if (planPath.includes('copilot') || planPath.includes('.codex')) return 'copilot';
-  if (planPath.includes('.cursor')) return 'cursor';
-  if (planPath.includes('.claude')) return 'claude';
-  return 'generic';
-}
-
-export const PLAN_PARSERS = {
-  'antigravity': parseGenericMarkdownPlan,
-  'copilot': parseGenericMarkdownPlan,
-  'generic': parseGenericMarkdownPlan
-};
-
-export function parsePlan(planPath, content) {
-  const agent = detectAgentFromPath(planPath);
-  const parser = PLAN_PARSERS[agent] || parseGenericMarkdownPlan;
-  return parser(content);
-}
+/**
+ * Generic Markdown Plan Parser
+ * 
+ * Supports various AI Agent Plan formats (Antigravity, Copilot, etc.)
+ * Extracts basic ticket fields (title, summary, tasks) and body.
+ */
+
+export function parseGenericMarkdownPlan(content) {
+  const lines = content.split('\n');
+  
+  // 1. Title: First H1
+  const h1Line = lines.find(l => /^# /.test(l));
+  const title = h1Line ? h1Line.replace(/^# /, '').trim() : '';
+
+  // 2. Summary: Text between H1 and the first --- or ##
+  const h1Idx = h1Line ? lines.indexOf(h1Line) : -1;
+  let summaryLines = [];
+  for (let i = h1Idx + 1; i < lines.length; i++) {
+    if (/^---$/.test(lines[i].trim()) || /^## /.test(lines[i])) break;
+    if (lines[i].trim()) summaryLines.push(lines[i].trim());
+  }
+  const summary = summaryLines.join(' ').slice(0, 200);
+
+  // 3. Tasks: Collect all checklist items
+  const tasks = lines
+    .filter(l => /^\s*- \[[ x/]\]/.test(l))
+    .map(l => l.replace(/^\s*- \[[ x/]\]\s*/, '').trim());
+
+  return { title, summary, tasks, body: content };
+}
+
+/**
+ * Detect agent type from plan path
+ */
+export function detectAgentFromPath(planPath) {
+  if (planPath.includes('.gemini')) return 'antigravity';
+  if (planPath.includes('copilot') || planPath.includes('.codex')) return 'copilot';
+  if (planPath.includes('.cursor')) return 'cursor';
+  if (planPath.includes('.claude')) return 'claude';
+  return 'generic';
+}
+
+export const PLAN_PARSERS = {
+  'antigravity': parseGenericMarkdownPlan,
+  'copilot': parseGenericMarkdownPlan,
+  'generic': parseGenericMarkdownPlan
+};
+
+export function parsePlan(planPath, content) {
+  const agent = detectAgentFromPath(planPath);
+  const parser = PLAN_PARSERS[agent] || parseGenericMarkdownPlan;
+  return parser(content);
+}

package/templates/MODULE_RULE_TEMPLATE.md

@@ -1,11 +1,11 @@
-# Submodule Rules: [Module Name]
-
-- **Path Root:** `[Path]`
-- **Tech Stack:** `[Tech]`
-
-## Architecture & Conventions
-- [Add module-specific conventions here]
-
-## Build & Test
-- Build: `[Command]`
-- Test: `[Command]`
+# Submodule Rules: [Module Name]
+
+- **Path Root:** `[Path]`
+- **Tech Stack:** `[Tech]`
+
+## Architecture & Conventions
+- [Add module-specific conventions here]
+
+## Build & Test
+- Build: `[Command]`
+- Test: `[Command]`

package/templates/PROJECT_RULE.md

@@ -1,47 +1,46 @@
----
-architecture_docs: ""
----
-
-# Project Rules
-
-## Architecture Boundaries
-
-> [!NOTE] **To AI Agents**
-> If `architecture_docs` is empty and no rules are defined below,
-> this project has no architecture rules yet.
-> → Ask user to define them, or analyze codebase and propose a draft.
-> → Do NOT make assumptions about project architecture.
-
-### Module Ownership
-<!-- Define which modules exist and who owns them -->
-| Module | Owner | Editable |
-|--------|-------|----------|
-| `src/` | Core source | Yes |
-
-### Dependency Direction
-<!-- Define allowed dependency directions between modules -->
-
-## DC-CODEGEN: Generated File Mapping
-
-> [!IMPORTANT] **REQUIRED**
-> Agents use this table to decide which files are safe to edit.
-> Files not listed here → agent MUST ask user before editing.
-
-| Generated (DO NOT EDIT) | Source (edit here) | Build command |
-|-------------------------|-------------------|---------------|
-| `dist/` | `src/` | `npm run build` |
-
-## DC-* Guards (project-specific)
-
-| Guard | Condition → Action |
-|-------|-------------------|
-| DC-HALT | Infrastructure error → stop, no bypass, report to user. |
-| DC-INFRA | Bootstrap/transport/DB/routing code → separate ticket + approval. |
-
-## Build & Test
-
-| Action | Command |
-|--------|---------|
-| Build | `npm run build` |
-| Test | `npm test` |
-| Lint | `npx deuk-agent-flow lint:md` |
+---
+architecture_docs: ""
+---
+
+# Project Rules
+
+## Architecture Boundaries
+
+> [!NOTE] **To AI Agents**
+> If `architecture_docs` is empty and no rules are defined below,
+> this project has no architecture rules yet.
+> → Ask user to define them, or analyze codebase and propose a draft.
+> → Do NOT make assumptions about project architecture.
+
+### Module Ownership
+<!-- Define which modules exist and who owns them -->
+| Module | Owner | Editable |
+|--------|-------|----------|
+| `src/` | Core source | Yes |
+
+### Dependency Direction
+<!-- Define allowed dependency directions between modules -->
+
+## DC-CODEGEN: Generated File Mapping
+
+> [!IMPORTANT] **REQUIRED**
+> Agents use this table to decide which files are safe to edit.
+> Files not listed here → agent MUST ask user before editing.
+
+| Generated (DO NOT EDIT) | Source (edit here) | Build command |
+|-------------------------|-------------------|---------------|
+| `dist/` | `src/` | `npm run build` |
+
+## DC-* Guards (project-specific)
+
+| Guard | Condition → Action |
+|-------|-------------------|
+| DC-HALT | Infrastructure error → stop, no bypass, report to user. |
+| DC-INFRA | Bootstrap/transport/DB/routing code → separate ticket + approval. |
+
+## Build & Test
+
+| Action | Command |
+|--------|---------|
+| Build | `npm run build` |
+| Lint | `npx deuk-agent-flow lint:md` |