@sallmarta/eye-hate-agent 1.0.2 → 1.0.4

package/bin/eha.js

@@ -1,163 +1,248 @@
 #!/usr/bin/env node
 
+'use strict';
+
 const { program } = require('commander');
 const chalk = require('chalk');
+const readline = require('node:readline/promises');
 const {
-  DEFAULT_RUNTIME_IDS,
+  SUPPORTED_AGENT_IDS,
   doctor,
   findRepoRoot,
-  getWorkflow,
-  installRuntimes,
+  initProject,
   listSupportedRuntimes,
-  prepareWorkflowRun,
-  uninstallRuntimes,
+  listWorkflows,
+  readConfig,
+  readProjectManifest,
+  removeProject,
 } = require('../src/engine');
 
-function formatRuntimeList(runtimes) {
-  return runtimes.map((runtime) => `${runtime.id} (${runtime.supportTier})`).join(', ');
+const pkg = require('../package.json');
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function promptAgentChoice(currentAgent) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const defaultLabel = currentAgent || SUPPORTED_AGENT_IDS[0];
+    const answer = await rl.question(
+      `Which agent? [${SUPPORTED_AGENT_IDS.join('/')}] (default: ${defaultLabel}): `,
+    );
+    const normalized = answer.trim().toLowerCase();
+    return normalized || defaultLabel;
+  } finally {
+    rl.close();
+  }
 }
 
-function printDoctorSummary(result) {
-  console.log(chalk.blue('EHA doctor'));
-  console.log(`Repo root: ${result.rootDir}`);
-  console.log(`Engine state: ${result.paths.stateDir}`);
-  console.log(`Install manifest: ${result.paths.manifestPath}`);
-  console.log(`Supported runtimes: ${formatRuntimeList(result.supportedRuntimes)}`);
-  console.log(`Generated outputs live inside repo: ${result.generatedOutputsInsideRepo ? 'yes' : 'no'}`);
-
-  if (result.installedRuntimes.length === 0) {
-    console.log(chalk.yellow('No runtimes are currently installed.'));
-    return;
+async function promptOverwriteOrDiscard(message) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`${message} [O]verwrite / [D]iscard (default: D): `);
+    return answer.trim().toLowerCase() === 'o';
+  } finally {
+    rl.close();
   }
+}
 
-  console.log(chalk.green('Installed runtimes:'));
-  for (const runtime of result.installedRuntimes) {
-    console.log(`- ${runtime.id}: ${runtime.fileCount} generated file(s), support tier ${runtime.supportTier}`);
+async function promptConfirm(message, defaultYes = false) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const hint = defaultYes ? '[Y/n]' : '[y/N]';
+    const answer = await rl.question(`${message} ${hint}: `);
+    const normalized = answer.trim().toLowerCase();
+    if (!normalized) return defaultYes;
+    return normalized === 'y';
+  } finally {
+    rl.close();
   }
 }
 
-function printInstallSummary(action, result) {
-  console.log(chalk.blue(`EHA ${action}`));
-  console.log(`Repo root: ${result.rootDir}`);
-  console.log(`Runtimes: ${result.runtimes.join(', ')}`);
-  console.log(`Manifest: ${result.manifestPath}`);
-  for (const runtime of result.runtimeSummaries) {
-    console.log(`- ${runtime.id}: ${runtime.fileCount} file(s), support tier ${runtime.supportTier}`);
+function resolveRootDir() {
+  try {
+    return findRepoRoot(process.cwd());
+  } catch {
+    console.error(
+      chalk.red('No project root found.') +
+        ' Run ' +
+        chalk.cyan('npm init -y') +
+        ' or ' +
+        chalk.cyan('git init') +
+        ' first.',
+    );
+    process.exit(1);
   }
 }
 
-function printWorkflowSummary(result) {
-  console.log(chalk.blue(`EHA workflow: ${result.workflow.id}`));
-  console.log(`Source workflow: ${result.workflow.repoRelativePath}`);
-  console.log(`Prepared prompt: ${result.promptPath}`);
-  if (result.workflow.capabilityNote) {
-    console.log(chalk.yellow(`Note: ${result.workflow.capabilityNote}`));
+function printInitSummary(result) {
+  console.log('');
+  console.log(chalk.green('✓ EHA is ready.'));
+  console.log(`  Agent : ${chalk.cyan(result.agentId)}`);
+  console.log(`  Files : ${result.fileCount} file(s) generated`);
+  for (const f of result.files) {
+    console.log(`    ${chalk.gray(f)}`);
   }
-  if (result.contextText) {
-    console.log(chalk.gray(`Additional context captured in ${result.promptPath}`));
+  console.log('');
+
+  if (result.agentId === 'claude') {
+    console.log('Open Claude in this project and run ' + chalk.cyan('/eha-bootstrap') + ' to get started.');
+  } else if (result.agentId === 'copilot') {
+    console.log(
+      'Open GitHub Copilot agent mode and attach ' +
+        chalk.cyan('#eha-bootstrap.prompt.md') +
+        ' to get started.',
+    );
   }
+  console.log('');
 }
 
-function installWorkflowCommand(workflowId) {
-  const workflow = getWorkflow(workflowId);
-
-  program
-    .command(`${workflow.id} [context...]`)
-    .description(workflow.description)
-    .option('--print', 'Print the assembled prompt instead of the summary')
-    .action((contextParts, options) => {
-      const rootDir = findRepoRoot(process.cwd());
-      const contextText = (contextParts || []).join(' ').trim();
-      const result = prepareWorkflowRun({
-        rootDir,
-        workflowId: workflow.id,
-        contextText,
-      });
-
-      if (options.print) {
-        process.stdout.write(result.promptContent);
+function printDoctorSummary(result) {
+  console.log('');
+  console.log(chalk.blue('EHA doctor'));
+  console.log(`  Root   : ${result.rootDir}`);
+  console.log(`  Config : ${result.paths.configPath}`);
+  console.log(`  Agent  : ${result.agentId ? chalk.cyan(result.agentId) : chalk.yellow('not set — run eha init')}`);
+  console.log('');
+
+  if (!result.isInitialized) {
+    console.log(chalk.yellow('EHA is not initialized in this project. Run eha init to set it up.'));
+    console.log('');
+    return;
+  }
+
+  const allPresent = result.generatedFiles.every((f) => f.exists);
+  if (allPresent) {
+    console.log(chalk.green('All generated files are present:'));
+  } else {
+    console.log(chalk.yellow('Some generated files are missing (re-run eha init to restore):'));
+  }
+  for (const f of result.generatedFiles) {
+    const icon = f.exists ? chalk.green('✓') : chalk.red('✗');
+    console.log(`  ${icon} ${f.relativePath}`);
+  }
+  console.log('');
+}
+
+// ─── Wizard (shared by bare invocation and `eha init`) ────────────────────────
+
+async function runInitWizard(agentIdArg) {
+  const rootDir = resolveRootDir();
+  const config = readConfig(rootDir);
+
+  let agentId = agentIdArg ? String(agentIdArg).trim().toLowerCase() : null;
+
+  if (!agentId) {
+    if (config.agent) {
+      const manifest = readProjectManifest(rootDir);
+      if (manifest.packageVersion !== pkg.version && process.stdin.isTTY && process.stdout.isTTY) {
+        const regenerate = await promptConfirm(
+          `EHA files were generated by v${manifest.packageVersion ?? 'unknown'}, current is v${pkg.version}. Regenerate?`,
+          true,
+        );
+        if (!regenerate) {
+          console.log('Skipped.');
+          return;
+        }
+        const result = initProject({ rootDir, agentId: config.agent });
+        printInitSummary(result);
+        return;
+      }
+      if (process.stdin.isTTY && process.stdout.isTTY) {
+        const overwrite = await promptOverwriteOrDiscard(
+          `EHA already set up (agent: ${chalk.cyan(config.agent)}).`,
+        );
+        if (!overwrite) {
+          console.log('Discarded.');
+          return;
+        }
+      }
+    }
+
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      agentId = await promptAgentChoice(config.agent);
+    } else {
+      agentId = config.agent || SUPPORTED_AGENT_IDS[0];
+    }
+  } else if (config.agent && config.agent !== agentId) {
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      const overwrite = await promptOverwriteOrDiscard(
+        `EHA already set up (agent: ${chalk.cyan(config.agent)}). Switch to ${chalk.cyan(agentId)}?`,
+      );
+      if (!overwrite) {
+        console.log('Discarded.');
         return;
       }
+    }
+  }
+
+  if (!SUPPORTED_AGENT_IDS.includes(agentId)) {
+    console.error(
+      chalk.red(`Unsupported agent: ${agentId}.`) +
+        ` Choose one of: ${SUPPORTED_AGENT_IDS.join(', ')}.`,
+    );
+    process.exit(1);
+  }
 
-      printWorkflowSummary(result);
-    });
+  const result = initProject({ rootDir, agentId });
+  printInitSummary(result);
 }
 
-program
-  .name('eha')
-  .description('Eye Hate Agent (EHA) engine and installer')
-  .version('1.0.0');
+// ─── CLI definition ────────────────────────────────────────────────────────────
 
-program
-  .command('install [runtimes...]')
-  .description('Generate repo-local runtime surfaces for EHA')
-  .action((runtimes) => {
-    const rootDir = findRepoRoot(process.cwd());
-    const result = installRuntimes({
-      rootDir,
-      runtimes: runtimes && runtimes.length > 0 ? runtimes : DEFAULT_RUNTIME_IDS,
-    });
-    printInstallSummary('install', result);
-  });
+program.name('eha').description('Eye Hate Agent (EHA) — AI workflow toolkit').version(pkg.version);
 
-program
-  .command('uninstall [runtimes...]')
-  .description('Remove generated repo-local runtime surfaces for EHA')
-  .action((runtimes) => {
-    const rootDir = findRepoRoot(process.cwd());
-    const result = uninstallRuntimes({
-      rootDir,
-      runtimes: runtimes && runtimes.length > 0 ? runtimes : DEFAULT_RUNTIME_IDS,
-    });
-    printInstallSummary('uninstall', result);
-  });
+// Bare `eha` / `eyehateagent` with no subcommand runs the init wizard.
+program.action(async () => {
+  await runInitWizard(null);
+});
 
 program
-  .command('doctor')
-  .description('Inspect EHA engine state, supported runtimes, and installed outputs')
-  .action(() => {
-    const rootDir = findRepoRoot(process.cwd());
-    printDoctorSummary(doctor({ rootDir }));
+  .command('init [agent]')
+  .description(`Set up EHA in this project. Agent: ${SUPPORTED_AGENT_IDS.join(' | ')}`)
+  .action(async (agentArg) => {
+    await runInitWizard(agentArg || null);
   });
 
-installWorkflowCommand('bootstrap');
-installWorkflowCommand('refresh');
-installWorkflowCommand('parity');
-installWorkflowCommand('discuss');
-installWorkflowCommand('execute');
-installWorkflowCommand('verify');
-
 program
-  .command('init [context...]')
-  .description('Alias for bootstrap')
-  .option('--print', 'Print the assembled prompt instead of the summary')
-  .action((contextParts, options) => {
-    const rootDir = findRepoRoot(process.cwd());
-    const contextText = (contextParts || []).join(' ').trim();
-    const result = prepareWorkflowRun({
-      rootDir,
-      workflowId: 'bootstrap',
-      contextText,
-      invokedAs: 'init',
-    });
-
-    if (options.print) {
-      process.stdout.write(result.promptContent);
+  .command('remove')
+  .description('Remove EHA-generated files and config from this project')
+  .action(async () => {
+    const rootDir = resolveRootDir();
+    const config = readConfig(rootDir);
+
+    if (!config.agent) {
+      console.log(chalk.yellow('EHA is not initialized here. Nothing to remove.'));
       return;
     }
 
-    printWorkflowSummary(result);
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      const confirmed = await promptConfirm(
+        `Remove EHA (agent: ${chalk.cyan(config.agent)}) from this project?`,
+      );
+      if (!confirmed) {
+        console.log('Aborted.');
+        return;
+      }
+    }
+
+    const result = removeProject({ rootDir });
+    console.log('');
+    console.log(chalk.green('✓ EHA removed.'));
+    for (const f of result.removedFiles) {
+      console.log(`  ${chalk.gray(f)}`);
+    }
+    console.log('');
   });
 
 program
-  .command('runtimes')
-  .description('List supported runtimes and support tiers')
+  .command('doctor')
+  .description('Show EHA status: config, agent, and generated files')
   .action(() => {
-    const runtimes = listSupportedRuntimes();
-    console.log(chalk.blue('Supported runtimes'));
-    for (const runtime of runtimes) {
-      console.log(`- ${runtime.id}: ${runtime.supportTier} - ${runtime.description}`);
-    }
+    const rootDir = resolveRootDir();
+    printDoctorSummary(doctor({ rootDir }));
   });
 
-program.parse(process.argv);
+program.parseAsync(process.argv).catch((error) => {
+  console.error(chalk.red(error.message));
+  process.exitCode = 1;
+});

package/docs/templates/project-docs-template/index.md

@@ -0,0 +1,208 @@
+# Project Docs Registry
+
+Last update: 2026-06-01
+
+Status: Live
+
+---
+
+## 1. Description
+This index is the master registry and layout definition for all Spec-Driven Development (SDD) documentation within EHA-adopting repositories. It defines the universal stable headings schema and active document types.
+
+## 2. Important
+All documentation generated under `docs/project-docs/` (except `index.md`, `getting-started.md`, and guideline registries) must strictly implement the Universal Stable Headings schema and incorporate the unique domain-specific headings defined below.
+
+## 3. Table of Contents
+- [1. Description](#1-description)
+- [2. Important](#2-important)
+- [3. Table of Contents](#3-table-of-contents)
+- [4. Scope](#4-scope)
+- [5. Goals](#5-goals)
+- [6. Non Goals](#6-non-goals)
+- [7. Universal Stable Headings](#7-universal-stable-headings)
+- [8. Active Doc Type Registry](#8-active-doc-type-registry)
+- [9. Domain-Specific Headings Catalog](#9-domain-specific-headings-catalog)
+
+## 4. Scope
+Covers the structural headings, layers (`foundation/`, `development/`, `operations/`), and domain headings for EHA-governed repositories.
+
+## 5. Goals
+Eliminate template boilerplate redundancy, prevent cross-document drift, and lower agent context consumption.
+
+## 6. Non Goals
+Does not define technical guidelines rules (refer to `technical-guidelines/index.md`).
+
+## 7. Universal Stable Headings
+Every project document must include these numbered headings in this exact order. Domain-specific headings go after § 6 and before the closing set. Feel free to add extra domain-specific headings if needed to capture important project context.
+
+### Opening Set:
+1. Description
+2. Important
+3. Table of Contents
+4. Scope
+5. Goals
+6. Non Goals
+
+### Closing Set (always last, in this order):
+- Success Metrics
+- Related Documents
+- Open Questions
+
+## 8. Active Doc Type Registry
+
+| Doc Type | Layer | Tier | Description |
+| :--- | :--- | :--- | :--- |
+| `getting-started.md` | Root | 1 | Orientation and local setup instructions. |
+| `foundation/prd.md` | foundation | 1 | Vision statement, target personas, user journeys, features. |
+| `foundation/architecture.md` | foundation | 1 | System architecture, tech stack, data flow, system flows, ADRs. |
+| `foundation/status.md` | foundation | 1 | High-level status, recent wins, roadmap. |
+| `foundation/workflow.md` | foundation | 1 | Branching, local development loop, PRs, code reviews. |
+| `foundation/phases.md` | foundation | 3 | Overall timelines, features, sub-functions, sprints. (Merged phases + feature inventory) |
+| `foundation/changelog.md` | foundation | 3 | Historical releases log. |
+| `development/testing.md` | development | 2 | QA policy, matrices, environments, gates, naming standards. |
+| `development/api-contract.md` | development | 2 | API authentication, endpoints, payloads, webhooks, rate limits. |
+| `development/database.md` | development | 2 | Schema, entity models, indexes, migrations, data dictionary. |
+| `development/ui-ux.md` | development | 2 | Design rules, wireframes, screen layouts, design tokens, responsive, a11y. |
+| `development/internationalization.md` | development | 3 | Languages support, translations flow, currency, dates. |
+| `operations/ci-cd.md` | operations | 2 | CI/CD pipelines, test gates, secrets handling, deploys. |
+| `operations/production-runbook.md` | operations | 3 | Release procedures, rollback, environment config, smoke checks. |
+| `operations/governance.md` | operations | 3 | Versioning policy, release cadence, code ownership rules. |
+| `operations/security-compliance.md` | operations | 3 | Threat mitigation, RBAC, encryption, data privacy/retention, audit logging. (Merged security + compliance) |
+| `operations/observability-error-handling.md` | operations | 3 | Log levels, error payloads, server fallbacks, alerts, dashboard metrics. (Merged observability + error handling) |
+| `[custom-path].md` | [layer] | [tier] | [Add custom document templates here as needed to activate additional files] |
+
+## 9. Domain-Specific Headings Catalog
+
+This catalog defines the baseline required domain-specific headings for each document type. When documenting a repository, both developers and AI agents are **NOT** limited to this baseline catalog; they must actively append additional, custom domain-specific headings to capture the unique features, patterns, and architectural realities discovered in the codebase.
+
+### `getting-started.md`
+- Prerequisites
+- First Steps
+- Local Setup
+- Verification
+- Troubleshooting
+
+### `foundation/prd.md`
+- Vision Statement
+- Target Personas
+- Core Business Value
+- User Journeys & App Flow
+- Feature Workflows
+- Functional Requirements
+- Non-Functional Requirements
+- Acceptance Criteria
+- External Dependencies & Partners
+
+### `foundation/architecture.md`
+- Tech Stack Overview
+- Architecture Pattern
+- System Flow
+- Data Flow
+- Tools Integration
+- Global Parameters and Constraints
+- Architecture Decision Records
+
+### `foundation/status.md`
+- Current State
+- Recent Accomplishments
+- Upcoming Focus
+- Key Metrics
+- Roadmap
+- Epics
+- Risks/Blockers
+
+### `foundation/workflow.md`
+- Local Dev Loop
+- Branching Strategy
+- PR & Code Review
+- Issue Tracking
+
+### `foundation/phases.md`
+- Overall Timeline
+- Feature Summary & Core Functions
+- Sub-Functions
+- Deprecated Features
+- Phase Registry
+- Sprint Tracker
+
+### `foundation/changelog.md`
+- [Unreleased] (Added/Changed/Deprecated/Removed/Fixed/Security entries)
+
+### `development/testing.md`
+- Verification Policy & Objectives
+- Verification Matrix & Coverage
+- Test Layers & Environments
+- Commands & CI Gates
+- Naming & File Conventions
+- Manual Checks & Fallbacks
+
+### `development/api-contract.md`
+- Base URL & Auth
+- Request/Response Format
+- Endpoints
+- Webhooks
+- Rate Limiting
+
+### `development/database.md`
+- DB Architecture
+- Schema Definitions
+- Indexes
+- Migration Strategy
+- Data Dictionary
+
+### `development/ui-ux.md`
+- Design Philosophy
+- Design System
+- Wireframing
+- Screen Layouts
+- Component Library
+- Responsive
+- Accessibility (A11y)
+- Design Handoff
+
+### `development/internationalization.md`
+- Supported Languages
+- Translation Workflow
+- Fallback Locales
+- Date & Currency
+
+### `operations/ci-cd.md`
+- Pipeline Architecture
+- Build Steps
+- Testing & Quality Gates
+- Deployment Environments
+- Secrets
+
+### `operations/production-runbook.md`
+- Environment Overview
+- Prerequisites & Access
+- Release Procedure
+- Smoke Checks
+- Rollback
+- Operational Notes
+
+### `operations/governance.md`
+- Versioning Policy
+- Release Cadence
+- Code Ownership
+- Contribution Guidelines
+
+### `operations/security-compliance.md`
+- Security Objectives & Threats
+- Access Control & RBAC
+- Data Encryption & Privacy
+- Data Retention
+- Audit Logging
+- Compliance Audits & Legal Disclaimers
+
+### `operations/observability-error-handling.md`
+- Logging Strategy
+- Standard Error Payloads
+- Global Error Codes
+- Client-Side Rules & Server Fallbacks
+- Metrics & Dashboards
+- Alerting Rules
+- Distributed Tracing
+
+### `[custom-path].md`
+- [Add the custom document's unique domain headings here, e.g., "Caching Strategy" or "Performance Budgets"]

package/docs/templates/project-docs-template/technical-guidelines/index.md

@@ -0,0 +1,81 @@
+# Guidelines Registry
+
+Last update: 2026-06-01
+
+Status: Live
+
+---
+
+## 1. Description
+This registry is the authoritative catalog and schema definition for all active technical guideline documents inside the repository. While core project documents explain the repository generally, technical guidelines document the durable, cross-cutting coding and design conventions that developers and AI agents must follow during implementation.
+
+## 2. Important
+Guidelines are durable, codebase-level rulebooks. They must never be created as simple placeholders. A guideline is officially activated in bootstrap, refresh, and parity loops only when it has an active row registered in the Active Guidelines table below.
+
+## 3. Table of Contents
+- [1. Description](#1-description)
+- [2. Important](#2-important)
+- [3. Table of Contents](#3-table-of-contents)
+- [4. Scope](#4-scope)
+- [5. Goals](#5-goals)
+- [6. Non Goals](#6-non-goals)
+- [7. Active Guidelines Registry](#7-active-guidelines-registry)
+- [8. Registry Rules & Ownership](#8-registry-rules--ownership)
+- [9. Guideline Stable Headings](#9-guideline-stable-headings)
+- [10. Success Metrics](#10-success-metrics)
+- [11. Related Documents](#11-related-documents)
+- [12. Open Questions](#12-open-questions)
+
+## 4. Scope
+Covers the active guideline categories, ownership tracking, review triggers, and standard heading rules for technical guidelines.
+
+## 5. Goals
+Standardize the coding and architectural rules across the codebase, preventing design-pattern divergence and ensuring high code quality.
+
+## 6. Non Goals
+Does not document general project setup, business logic, or operational procedures (refer to the master project docs registry `index.md`).
+
+## 7. Active Guidelines Registry
+
+| Guideline | Domain | Purpose | Owner | Review Trigger |
+| :--- | :--- | :--- | :--- | :--- |
+| `technical-guidelines/api.md` | API | Request or response contracts, versioning rules, and integration boundaries | TBD | API contract or integration changes |
+| `technical-guidelines/database.md` | Database | Schema, migration, naming, and persistence rules | TBD | Schema or storage changes |
+| `technical-guidelines/logging.md` | Logging | Event naming, log levels, redaction, and correlation rules | TBD | Logging policy or observability changes |
+| `technical-guidelines/error-handling.md` | Error handling | Error taxonomy, propagation, user-safe messages, and fallback rules | TBD | Error model or operational changes |
+| `technical-guidelines/json.md` | JSON | Serialization, naming, nullability, and payload-shape rules | TBD | Payload or contract changes |
+| `technical-guidelines/code-style.md` | Code style | Repo-specific style rules beyond formatter and linter defaults | TBD | Tooling or style-policy changes |
+| `technical-guidelines/design-patterns.md` | Design patterns | Preferred design patterns, boundary patterns, and forbidden coupling | TBD | Architecture or module-boundary changes |
+| `technical-guidelines/internationalization.md` | i18n/l10n | Rules for i18n keys, fallbacks, and adding new languages | TBD | i18n tooling or language changes |
+| `technical-guidelines/testing.md` | Testing | Rules for writing tests, naming conventions, mocking, and coverage | TBD | Testing framework or coverage changes |
+| `technical-guidelines/ui-ux.md` | UI/UX | Rules for UI components, accessibility standards, and design system usage | TBD | Design system or component library changes |
+| `technical-guidelines/[custom-guideline].md` | [Domain] | [Durable technical rules and conventions for custom domain] | TBD | [Review trigger, e.g. "API or schema changes"] |
+
+Remove rows for inactive domains and add a new row in the `## 7. Active Guidelines Registry` table above for any other active guideline files.
+
+## 8. Registry Rules & Ownership
+- Keep this index aligned with the files that actually exist under `technical-guidelines/`.
+- A row in this index activates a known guideline type for bootstrap, refresh, and parity behavior.
+- If no starter template file exists for a listed guideline type, use the Stable Headings schema defined below.
+- Update the relevant row whenever a guideline changes owner, scope, or review trigger.
+- Cross-reference owning project docs such as `architecture.md` or `testing.md` when a guideline depends on them.
+
+## 9. Guideline Stable Headings
+New guideline files must include the standard numbered headings below to keep all rulebooks consistent. When documenting a guideline, both developers and AI agents are **NOT** limited to this baseline schema; they must actively append additional, custom domain-specific headings (for example, under Section 3 or as subheadings) to capture the unique technical standards, tooling, and constraints of the codebase.
+
+1. **`## 1. Summary`**: A brief overview of what rules this guideline documents.
+2. **`## 2. Scope`**: The explicit boundaries of what these rules cover (and don't cover).
+3. **`## 3. Rules`**: The hard rules that must be followed.
+4. **`## 4. Preferred Patterns`**: Examples or guidelines of the *best* way to do something.
+5. **`## 5. Anti-Patterns`**: Examples of what *not* to do.
+6. **`## 6. Related Docs`**: Links to active core project documents or other guidelines.
+7. **`## 7. Open Questions`**: Any unresolved rules or edge cases.
+
+## 10. Success Metrics
+AI agents and developers can easily reference, follow, and validate cross-cutting code standard compliance during changes.
+
+## 11. Related Documents
+- [Master Project Registry](../index.md) - The active document catalog.
+
+## 12. Open Questions
+None.