ai-engineering-loop 1.0.11 → 1.0.12

package/bin/ai-engineering-loop.js

@@ -14,8 +14,14 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
-
-const VERSION = '1.0.11';
+const {
+  homeDir,
+  applyHostSync,
+  planHostSync,
+  formatHostSyncReport
+} = require('../lib/sync-hosts.js');
+
+const VERSION = '1.0.12';
 const CWD = process.cwd();
 const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
 
@@ -26,9 +32,20 @@ const REQUIRED_FILES = [
   'architecture.md',
   'conventions.md',
   'verification.md',
-  'adapter.md'
+  'adapter.md',
+  'glossary.md',
+  'adrs/README.md'
 ];
 
+function writeContextFile(filePath, content, { overwrite = true } = {}) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  if (!overwrite && fs.existsSync(filePath) && fs.statSync(filePath).size > 0) {
+    return false;
+  }
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
 /**
  * Colorized console helpers
  */
@@ -249,7 +266,8 @@ function analyzeRepository(rootDir) {
 /**
  * Generate Context Files (Including metadata.json Baseline)
  */
-function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'INITIAL_BOOTSTRAP') {
+function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'INITIAL_BOOTSTRAP', options = {}) {
+  const overwriteCore = options.overwriteCore !== false;
   const targetDir = path.join(rootDir, '.ai-engineering-loop');
   fs.mkdirSync(targetDir, { recursive: true });
 
@@ -257,7 +275,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
 
   // 0. metadata.json (Baseline)
   const metadataJson = {
-    contextVersion: '1.0.0',
+    contextVersion: '1.0.12',
     generatedAt: new Date().toISOString(),
     repositoryRevision: currentRevision,
     projectProfile: discovery.profile,
@@ -268,7 +286,11 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
       impact
     }
   };
-  fs.writeFileSync(path.join(targetDir, 'metadata.json'), JSON.stringify(metadataJson, null, 2) + '\n');
+  writeContextFile(
+    path.join(targetDir, 'metadata.json'),
+    JSON.stringify(metadataJson, null, 2) + '\n',
+    { overwrite: overwriteCore }
+  );
 
   // 1. config.md
   const configMd = `# Project Configuration
@@ -286,7 +308,7 @@ ${discovery.frameworks.map((f) => `  - ${f}`).join('\n') || '  - Standard'}
 ## Observed Evidence
 ${discovery.evidence.map((e) => `- ${e}`).join('\n')}
 `;
-  fs.writeFileSync(path.join(targetDir, 'config.md'), configMd);
+  writeContextFile(path.join(targetDir, 'config.md'), configMd, { overwrite: overwriteCore });
 
   // 2. architecture.md
   const archMd = `# Project Architecture
@@ -306,7 +328,7 @@ ${discovery.topLevelDirs.map((d) => `- \`${d}/\``).join('\n') || '- Flat directo
 - Observed from: Directory scan, package manifests
 - Confidence: HIGH
 `;
-  fs.writeFileSync(path.join(targetDir, 'architecture.md'), archMd);
+  writeContextFile(path.join(targetDir, 'architecture.md'), archMd, { overwrite: overwriteCore });
 
   // 3. conventions.md
   const convMd = `# Project Conventions
@@ -321,7 +343,7 @@ ${discovery.topLevelDirs.map((d) => `- \`${d}/\``).join('\n') || '- Flat directo
 - Never commit private secrets, passwords, or API keys.
 - Do not make unsolicited renovations outside the active Goal Contract scope.
 `;
-  fs.writeFileSync(path.join(targetDir, 'conventions.md'), convMd);
+  writeContextFile(path.join(targetDir, 'conventions.md'), convMd, { overwrite: overwriteCore });
 
   // 4. verification.md
   const verifyMd = `# Project Verification Commands
@@ -337,7 +359,7 @@ ${discovery.scripts.e2e ? `- **e2e**: \`${discovery.scripts.e2e}\`` : ''}
 - 100% deterministic checks must pass before Devil's Advocate review.
 - Unit tests must cover boundary cases, null safety, and error paths.
 `;
-  fs.writeFileSync(path.join(targetDir, 'verification.md'), verifyMd);
+  writeContextFile(path.join(targetDir, 'verification.md'), verifyMd, { overwrite: overwriteCore });
 
   // 5. adapter.md
   const adapterMd = `# Project Delivery Adapter Configuration
@@ -348,7 +370,48 @@ ${discovery.adapter.repoSlug ? `- **remote_repository**: "${discovery.adapter.re
 - **default_target_branch**: "${discovery.adapter.defaultBranch}"
 - **ci_provider**: "${discovery.adapter.ciProvider}"
 `;
-  fs.writeFileSync(path.join(targetDir, 'adapter.md'), adapterMd);
+  writeContextFile(path.join(targetDir, 'adapter.md'), adapterMd, { overwrite: overwriteCore });
+
+  const glossaryMd = `# Ubiquitous Language
+
+One term per concept. Agents and humans use these words in Goal Contracts, tests, code names, and review.
+
+## Terms
+
+| Term | Meaning | Do not say |
+|---|---|---|
+| Goal Contract | Frozen Stage 1 acceptance document | "the prompt" |
+| Seam | Public interface under test | "the internals" |
+
+Update this file during Stage 1 grill when a term is coined or corrected.
+`;
+  writeContextFile(path.join(targetDir, 'glossary.md'), glossaryMd, { overwrite: false });
+
+  const adrReadme = `# Architecture Decision Records
+
+Hard decisions that would otherwise live only in chat. Write one ADR when Stage 1 grill settles a choice that future agents must not re-litigate.
+
+File name: \`NNN-short-kebab-title.md\`
+
+## Template
+
+\`\`\`markdown
+# ADR NNN: <title>
+
+## Status
+Accepted
+
+## Context
+What forced a choice.
+
+## Decision
+What we chose, in glossary terms.
+
+## Consequences
+What becomes easier, harder, or forbidden.
+\`\`\`
+`;
+  writeContextFile(path.join(targetDir, 'adrs', 'README.md'), adrReadme, { overwrite: false });
 }
 
 /**
@@ -460,6 +523,10 @@ function handleInit() {
   log.info('AI Engineering Loop — Project Context Bootstrap (init)');
   log.dim(`Target directory: ${CWD}`);
 
+  let overwriteCore = true;
+  let trigger = 'init';
+  let impact = 'INITIAL_BOOTSTRAP';
+
   if (fs.existsSync(CONTEXT_DIR)) {
     const validation = validateContext(CONTEXT_DIR);
     if (validation.valid) {
@@ -470,6 +537,9 @@ function handleInit() {
       process.exit(0);
     } else {
       log.warn(`! Existing .ai-engineering-loop/ found but incomplete: ${validation.reason}. Repairing...`);
+      overwriteCore = false;
+      trigger = 'repair';
+      impact = 'REPAIR_MISSING';
     }
   }
 
@@ -481,7 +551,7 @@ function handleInit() {
   log.dim(`> Package Manager: ${discovery.packageManager}`);
   log.dim(`> Unit Test Command: ${discovery.scripts.testUnit}`);
 
-  generateContextFiles(CWD, discovery, 'init', 'INITIAL_BOOTSTRAP');
+  generateContextFiles(CWD, discovery, trigger, impact, { overwriteCore });
 
   const validation = validateContext(CONTEXT_DIR);
   if (validation.valid) {
@@ -523,7 +593,17 @@ function handleStatus() {
   console.log(`- Project Profile: ${metadata.projectProfile || 'unspecified'}`);
   console.log(`- Context Baseline Git: ${metadata.repositoryRevision ? metadata.repositoryRevision.slice(0, 8) : 'unknown'}`);
   console.log(`- Living Freshness: \x1b[32m${drift.status}\x1b[0m (${drift.reason})`);
-  console.log('- Context Files: 6/6 verified (including metadata.json)');
+  console.log(`- Context Files: ${REQUIRED_FILES.length}/${REQUIRED_FILES.length} verified (including metadata.json, glossary.md, adrs/)`);
+
+  const hostPlan = planHostSync({ home: homeDir() });
+  const hostCopy = hostPlan.filter((item) => item.action === 'copy').length;
+  if (hostCopy > 0) {
+    log.warn(`- Host skills: STALE (${hostCopy} file(s) behind package v${VERSION})`);
+    log.dim('  Run "npx ai-engineering-loop sync-hosts" then start a new session.');
+  } else {
+    const hostCurrent = hostPlan.filter((item) => item.action === 'current').length;
+    console.log(`- Host skills: CURRENT (${hostCurrent} managed file(s) match v${VERSION})`);
+  }
 }
 
 // Command: refresh
@@ -537,8 +617,15 @@ function handleRefresh() {
     return;
   }
 
+  const validation = validateContext(CONTEXT_DIR);
+  if (!validation.valid) {
+    log.info(`Incomplete context: ${validation.reason}. Filling missing files without overwriting filled ones...`);
+    const discovery = analyzeRepository(CWD);
+    generateContextFiles(CWD, discovery, 'refresh', 'REPAIR_MISSING', { overwriteCore: false });
+  }
+
   const drift = evaluateDrift(CWD, CONTEXT_DIR);
-  if (drift.status === 'CURRENT') {
+  if (drift.status === 'CURRENT' && validateContext(CONTEXT_DIR).valid) {
     log.success('✓ Context is already CURRENT. No changes required.');
     log.dim(`Reason: ${drift.reason}`);
     process.exit(0);
@@ -547,12 +634,26 @@ function handleRefresh() {
   log.info(`Drift detected: ${drift.reason}. Reconciling context...`);
   const discovery = analyzeRepository(CWD);
 
-  generateContextFiles(CWD, discovery, 'refresh', 'DRIFT_RECONCILIATION');
+  generateContextFiles(CWD, discovery, 'refresh', 'DRIFT_RECONCILIATION', { overwriteCore: true });
 
   log.success('✓ Context reconciled non-destructively.');
   handleStatus();
 }
 
+function syncHostsQuiet() {
+  const results = applyHostSync({ home: homeDir(), dryRun: false });
+  const copied = results.filter((item) => item.action === 'copy').length;
+  if (copied === 0) return;
+  console.log(formatHostSyncReport(results, { version: VERSION }));
+}
+
+function handleSyncHosts() {
+  const dryRun = process.argv.includes('--dry-run');
+  log.info(`AI Engineering Loop — Sync host skills (sync-hosts)${dryRun ? ' [dry-run]' : ''}`);
+  const results = applyHostSync({ home: homeDir(), dryRun });
+  console.log(formatHostSyncReport(results, { version: VERSION, dryRun }));
+}
+
 function detectGrokHost() {
   try {
     const { detectGrokRuntime } = require('../lib/orchestration.js');
@@ -573,13 +674,15 @@ function handleRun() {
     handleStatus();
   }
 
+  syncHostsQuiet();
+
   const grok = detectGrokHost();
 
   console.log('\n------------------------------------------------------------');
   log.bold('AI Agent Ready:');
-  console.log('1. Formulate Goal Contract (core/goal-contract.md)');
-  console.log('2. Execute Root Cause Analysis & Plan');
-  console.log('3. Maker Agent implements surgical code and tests');
+  console.log('1. Grill if needed, then freeze Goal Contract (core/grill-policy.md, core/goal-contract.md)');
+  console.log('2. Root Cause Analysis (core/root-cause-analysis.md) & Plan');
+  console.log('3. Maker TDD at named seams (policies/tdd-policy.md)');
   console.log('4. Run Deterministic Verification');
   console.log('5. Execute Devil\'s Advocate Adversarial Review');
   console.log('6. Judge Agent evaluates DoD and issues PASS verdict');
@@ -636,10 +739,13 @@ Usage:
   npx ai-engineering-loop <command>
 
 Commands:
-  init      Bootstrap .ai-engineering-loop/ context from repository discovery
-  status    Check the validity, readiness, and baseline freshness of context
-  refresh   Reconcile drifted context against repository non-destructively
-  run       Verify context readiness and instruct AI agent to begin loop
+  init         Bootstrap .ai-engineering-loop/ context from repository discovery
+  status       Check the validity, readiness, and baseline freshness of context
+  refresh      Reconcile drifted context against repository non-destructively
+  run          Verify context readiness, sync host skills, and instruct the agent
+  sync-hosts   Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
+               (only hosts that already exist; DOT skills only if already installed)
+               --dry-run  print the plan without writing
 
 Options:
   -h, --help     Show this help menu
@@ -667,6 +773,9 @@ switch (command) {
   case 'run':
     handleRun();
     break;
+  case 'sync-hosts':
+    handleSyncHosts();
+    break;
   case '-v':
   case '--version':
     console.log(`ai-engineering-loop v${VERSION}`);

package/core/context-impact-assessment.md

@@ -69,6 +69,8 @@ flowchart TD
 | `package.json` / `go.mod` scripts modified | `verification.md`, `config.md` | Update test/build/lint command entries |
 | New folder in `src/modules/` or `apps/` | `architecture.md` | Add module summary and boundary notes |
 | New global error class or lint rule added | `conventions.md` | Document new pattern or forbidden rule |
+| New or corrected domain term | `glossary.md` | Add or fix one glossary row |
+| Load-bearing design choice settled | `adrs/NNN-*.md` | Write an ADR; do not bury it in chat |
 | `.gitlab-ci.yml` / `.github/workflows` edited | `adapter.md` | Update CI/CD workflow references |
 
 - **Action**: Reconcile *only* the affected markdown file(s) and update `metadata.json` baseline.

package/core/definition-of-done.md

@@ -39,6 +39,8 @@ flowchart LR
 ### Pillar 3: Code & Diff Quality
 - **Surgical Diff**: Smallest coherent diff that completely resolves the issue.
 - **Architecture Preservation**: Adheres to existing repository patterns, naming conventions, and layer boundaries.
+- **Seams & TDD**: Tests sit at Goal Contract seams; red then green (`policies/tdd-policy.md`).
+- **Glossary**: New names match `.ai-engineering-loop/glossary.md`.
 - **Zero Placeholders**: No stubbed functions, empty `catch` blocks, speculative `TODO` comments, or orphaned dead code.
 - **Null & Boundary Safety**: Explicit handling of `null`, `undefined`, empty collections, and error paths.
 

package/core/goal-contract.md

@@ -11,6 +11,8 @@ The Goal Contract establishes:
 - **Where** the boundaries are set (preventing scope creep).
 - **When** the work is strictly considered complete.
 
+Alignment before freeze follows [Grill Policy](file:///Users/egagofur/Development/work/ai-engineering-loop/core/grill-policy.md). Terms come from `.ai-engineering-loop/glossary.md`.
+
 ---
 
 ## 2. Mandatory Contract Schema
@@ -40,13 +42,22 @@ Every Goal Contract MUST adhere to the following schema in Markdown or structure
 ## 5. Out of Scope
 - [Explicitly list what the agent MUST NOT touch or refactor during this task]
 
-## 6. Verification Requirements
+## 6. Ubiquitous Language
+- Terms used in this contract (must match `.ai-engineering-loop/glossary.md`): [term, ...]
+- New terms coined in Stage 1 grill: [add to glossary before freeze]
+
+## 7. Test Seams
+- [Public interface under test. Prefer existing seams. No test at an unconfirmed seam.]
+- [What a passing test at this seam proves for AC-1..N]
+
+## 8. Verification Requirements
 - **Unit Tests**: [Target files, boundary cases, and minimum expected coverage]
 - **Static Analysis**: [Typecheck command, linter command, schema validation command]
 - **Build / Packaging**: [Build command or bundling check]
 - **Runtime / Integration**: [Manual smoke test steps or integration test command]
+- **TDD**: Red then green at the seams above (`policies/tdd-policy.md`)
 
-## 7. Definition of Done (DoD)
+## 9. Definition of Done (DoD)
 - [ ] All Acceptance Criteria (AC-1 through AC-N) verified with automated tests.
 - [ ] 100% pass on all deterministic verification commands (0 errors, 0 warnings where enforced).
 - [ ] Independent Devil's Advocate review completed with 0 unresolved blocking findings (SEV-1 / SEV-2).
@@ -60,7 +71,8 @@ Every Goal Contract MUST adhere to the following schema in Markdown or structure
 
 1. **Pre-Implementation Freezing**:
    - The Goal Contract is authored and frozen *before* any production code edits.
-   - If the task is ambiguous, the agent must refine the contract with the user before touching code.
+   - If the task is ambiguous and a human is present, run the [Grill Policy](file:///Users/egagofur/Development/work/ai-engineering-loop/core/grill-policy.md) until the design-tree frontier is empty, then freeze.
+   - If the task is unambiguous, waived, or headless with testable AC, skip grill and freeze immediately.
 2. **Immutability During Iteration**:
    - Neither the Maker Agent nor the Devil's Advocate Agent may alter Acceptance Criteria during an iteration loop to make tests pass or bypass critique.
 3. **Contract Amendments**:
@@ -83,6 +95,8 @@ Every single item listed under `Acceptance Criteria` must map to at least one co
 
 ## 5. Anti-Patterns to Avoid
 
-- **The Vague Contract**: "Make authentication work better." (Invalid: lacks testable acceptance criteria).
+- **The Vague Contract**: "Make authentication work better." (Invalid: lacks testable acceptance criteria). Grill or refuse to freeze.
+- **The Missing Seam**: Acceptance criteria with no public interface to test against.
+- **The Parallel Glossary**: Using 20 words for a concept that already has a term in `glossary.md`.
 - **The Missing Constraint**: Failing to declare out-of-scope files, leading to arbitrary refactoring of adjacent legacy modules.
 - **The Self-Serving Goal**: Modifying acceptance criteria post-hoc when tests fail rather than fixing the underlying implementation.

package/core/grill-policy.md

@@ -0,0 +1,70 @@
+# Grill Policy (Stage 1 Alignment)
+
+The Goal Contract is frozen only after alignment is real. When the task is ambiguous and a human can answer, the orchestrator **grills** before any production edit. This is Stage 1, not a separate product.
+
+## When to grill
+
+Grill when **all** of these are true:
+
+1. No frozen Goal Contract exists for this task.
+2. The request is ambiguous, multi-way, or missing acceptance criteria, seams, or out-of-scope.
+3. A human is present in this session (interactive TUI / chat).
+
+## When to skip
+
+Skip grill (write the Goal Contract from what is already known) when any of these is true:
+
+1. The user waived it ("just do it", "skip grill", contract already pasted).
+2. A Goal Contract for this task is already frozen on disk.
+3. The session is headless / autonomous and the prompt already has testable AC-1..N.
+4. The change is a one-line mechanical fix with an obvious AC (typo, lint, version bump).
+
+Do not interview the user for **facts** you can look up (files, scripts, types, git). Look them up. Grill only **decisions**.
+
+## DOT adapter (`adapter_type: dot`)
+
+On DOT repositories, grill is **one** session that includes the four-pillar blast radius from Antigravity skill `task-impact-inquiry` (`~/.gemini/config/skills/task-impact-inquiry/SKILL.md`). Do not run that skill as a second interview after grill.
+
+The four pillars must appear in the grill (and then in the Goal Contract) whenever the change can touch:
+
+1. State and condition permutations (status, overtime vs normal hours, locked vs open periods)
+2. Sibling / historical isolation (other entities in the same parent, period, or cart)
+3. Actor and approval authority (who edits, when an existing approval is void vs kept)
+4. Downstream jobs and queues (BullMQ, cron, payroll/aggregates)
+
+**Do not skip grill** for those four cases, even if AC look obvious or the user said "just do it". Typo, lint, and version-bump skips still apply.
+
+If the skill file is missing on this host, still ask the four pillars from this section. Do not claim the Gemini skill ran.
+
+Present the impact matrix and 2–3 probing questions in the same grill round as other Stage 1 decisions. Recommended answers required. After the frontier is empty, freeze the Goal Contract once.
+
+## Design tree
+
+Map the work as a design tree. The **frontier** is every undecided question whose prerequisites are settled.
+
+Work in **rounds**. Each round asks the whole current frontier. Number the questions. Give a recommended answer for each. Wait for the user's answers before the next round.
+
+```text
+Q1 - <title>: <body, including choices>
+Recommended: <your answer>
+```
+
+A question that depends on an unanswered question in this round belongs to a later round.
+
+The grill is done when the frontier is empty: every branch visited, nothing silently assumed. Confirm shared understanding, then freeze the Goal Contract (`core/goal-contract.md`).
+
+## What the grill must settle
+
+- Objective and business outcome
+- Acceptance criteria that can fail a test
+- Out of scope
+- Test **seams** (public interfaces to observe; prefer existing seams; fewer is better)
+- Glossary terms to use (read and update `.ai-engineering-loop/glossary.md`)
+- Hard decisions that belong in an ADR under `.ai-engineering-loop/adrs/`
+
+## Invariants
+
+- No production code edits during grill.
+- Neither Maker nor Devil's Advocate may amend AC after freeze. Only a human amends the contract (`core/goal-contract.md`).
+- Use glossary terms in the contract, ticket, and later code names.
+- Do not own the user's process outside this loop. Grill exists to freeze Stage 1, then the 8-stage OS continues.

package/core/handoff-policy.md

@@ -0,0 +1,44 @@
+# Handoff Artifact
+
+When a session stops mid-loop (context limit, user switch, detach), the orchestrator writes a handoff so the next agent continues the same 8-stage run. This is not a new stage.
+
+## Path
+
+`.ai-engineering-loop/tasks/handoff.md`
+
+Overwrite the previous handoff for the active task. Do not commit unless the user asks.
+
+## Required sections
+
+```markdown
+# Handoff: <short task title>
+
+## Stage
+<0-8 plus grill / iterate-N>
+
+## Goal Contract
+<path, frozen or not>
+
+## Seams
+- <public interface under test>
+
+## Verification
+- last command, exit code, log path (or NOT RUN)
+
+## Review
+- DA ledger path (or NOT RUN)
+- Judge verdict (or NOT RUN)
+- open VALID BLOCKER/HIGH ids
+
+## Glossary / ADRs touched
+- <paths>
+
+## Next action
+One sentence the next agent must do first. No recap of chat.
+```
+
+## Rules
+
+- Facts only: paths, commands, ids. No Maker optimism.
+- The next session reads this file, the Goal Contract, and `.ai-engineering-loop/glossary.md` before grilling again.
+- Do not restart Stage 1 if the contract is already frozen.

package/core/judge-policy.md

@@ -30,12 +30,13 @@ flowchart TD
 
 ## 2. Evidence-Based Decision Matrix
 
-The Judge renders decisions based strictly on **Validity + Severity**. The reviewer's subjective disposition (`STRONG`, `ACCEPTABLE`, `WEAK`) **never overrides factual evidence**:
+The Judge renders decisions based strictly on **Validity + Severity**, then **review axis**. The reviewer's subjective disposition (`STRONG`, `ACCEPTABLE`, `WEAK`) **never overrides factual evidence**. Do not merge Spec and Standards into one ranking:
 
 | Finding Validity | Finding Severity | Disposition | Judge Action | Impact on Final Verdict |
 |---|---|---|---|---|
-| **`VALID`** | **`BLOCKER`** | Any | **UPHELD (Blocking)** | **`ITERATE`** — Maker must apply alternative diff & tests. |
-| **`VALID`** | **`HIGH`** | Any | **UPHELD (Blocking)** | **`ITERATE`** — Maker must apply alternative diff & tests. |
+| **`VALID`** | **`BLOCKER`** | Any | **UPHELD (Blocking)** if `axis` is `spec` (or omitted), or `standards` with `hardConvention: true` | **`ITERATE`** — Maker must apply alternative diff & tests. |
+| **`VALID`** | **`HIGH`** | Any | **UPHELD (Blocking)** under the same axis rule | **`ITERATE`** — Maker must apply alternative diff & tests. |
+| **`VALID`** | **`BLOCKER` / `HIGH`** | Any | **TRADEOFF** if `axis` is `standards` and `hardConvention` is not true | **`PASS`** (if ACs met) — smell/convention judgement, not an AC breach. |
 | **`VALID`** | **`MEDIUM`** | `ACCEPTABLE` | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
 | **`VALID`** | **`LOW`** | `ACCEPTABLE` | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
 | **`INVALID`** | Any | `WEAK` | **DISMISSED (Hallucination)** | **`PASS`** (if ACs met) — Discarded with evidence proof. |

package/core/project-initialization.md

@@ -81,7 +81,8 @@ Inspect Topology ──▶ Manifests/Commands ──▶ Inferred Profile ──
    - Cross-checks existing docs (`README.md`, `CONTRIBUTING.md`, `CLAUDE.md`, `AGENTS.md`) without blindly trusting contradictions.
 5. **Pass 5 (Safety Audit & File Generation)**:
    - Strictly ignores private credentials (`.env`, `.env.local`, `.pem`, tokens, API keys).
-   - Generates `.ai-engineering-loop/` (`config.md`, `architecture.md`, `conventions.md`, `verification.md`, `adapter.md`).
+   - Generates `.ai-engineering-loop/` (`config.md`, `architecture.md`, `conventions.md`, `verification.md`, `adapter.md`, `glossary.md`, `adrs/README.md`).
+   - Repair of a valid-but-incomplete directory fills missing files only. Filled `glossary.md` and ADRs are never overwritten.
 
 ---
 

package/core/repo-config-schema.md

@@ -12,7 +12,11 @@ The `.ai-engineering-loop/` directory serves as the **Living Project Context** f
     ├── architecture.md     # System architecture, layers, & boundaries
     ├── conventions.md      # Code standards, patterns, & forbidden practices
     ├── verification.md     # Exact CLI verification commands
-    └── adapter.md          # Configured delivery pipeline & CI/CD tools
+    ├── adapter.md          # Configured delivery pipeline & CI/CD tools
+    ├── glossary.md         # Ubiquitous language (one term per concept)
+    ├── adrs/               # Architecture Decision Records from Stage 1 grill
+    │   └── README.md
+    └── tasks/              # Ephemeral: current.diff, handoff.md, verification logs
 ```
 
 ---
@@ -65,6 +69,16 @@ Maintains lightweight state for instant drift detection:
 - `default_target_branch`: Base target branch.
 - `ci_provider`: Detected CI engine (GitHub Actions, GitLab CI).
 
+### 7. `glossary.md` — Ubiquitous Language
+- One term per domain concept. Goal Contracts, tests, and code names must use these words.
+- Updated during Stage 1 grill when a term is coined or corrected. Never overwritten by `refresh` if already filled.
+
+### 8. `adrs/` — Architecture Decision Records
+- Durable why for load-bearing choices settled in grill. `refresh` does not overwrite existing ADRs.
+
+### 9. `tasks/` — Run artifacts (optional)
+- `current.diff`, verification logs, `handoff.md`. Not required for `init` validity.
+
 ---
 
 ## 3. Version Control Recommendation

package/core/root-cause-analysis.md

@@ -0,0 +1,30 @@
+# Root Cause Analysis (Stage 2)
+
+Stage 2 is diagnosis, not coding. The Maker must not start a production diff until the failure (or the missing capability) is named with evidence.
+
+## Feature work
+
+For a new capability with a frozen Goal Contract:
+
+1. Trace the data path (ingress → domain → data → side effects).
+2. Name the existing module and **seam** that will carry the change.
+3. List edge cases the AC already require.
+4. Stop. Stage 3 is the plan; Stage 4 is the diff.
+
+## Bug and regression work
+
+Use a gated diagnosis loop. Do not skip a gate.
+
+1. **Red repro.** Build or run a feedback loop that fails on this bug (test, log, metric, or script). If you cannot turn it red, you do not understand it yet.
+2. **Minimise.** Shrink input, surface, and time window until one causal slice remains.
+3. **Hypothesise.** Write 1–3 falsifiable causes. Do not "try things".
+4. **Instrument.** Add the smallest probe that distinguishes those causes. Remove the probe if it is not a product requirement.
+5. **Fix.** Only after one hypothesis is confirmed. The fix is Stage 4, still test-first at the agreed seam (`policies/tdd-policy.md`).
+6. **Regression test.** The red repro becomes a kept test mapped to an AC.
+
+## Anti-patterns
+
+- Guessing a fix from stack-trace vibe without a red repro
+- Horizontal exploration of the whole repo "in case"
+- Editing production code in Stage 2
+- Asking the user for facts that exist in git, logs, or `.ai-engineering-loop/verification.md`

package/core/verification-loop.md

@@ -6,6 +6,8 @@ The Verification Loop is the deterministic machine gate of the AI Engineering Lo
 
 > **"Code cannot enter Devil's Advocate review until it achieves 100% green machine verification backed by explicit, verifiable execution evidence."**
 
+Maker reaches that green via [TDD Policy](file:///Users/egagofur/Development/work/ai-engineering-loop/policies/tdd-policy.md): red at a named seam, then green. "We did TDD" without logs is not a PASS.
+
 ---
 
 ## 2. Verification Evidence Contract
@@ -20,7 +22,7 @@ A verification `PASS` is **strictly invalid** without concrete execution evidenc
 5. **`stdout` & `stderr`**: Raw machine logs captured from execution.
 6. **`timeoutStatus`**: Must be `"COMPLETED"` (not timed out or backgrounded without completion).
 7. **`testCounts`**: Explicit counts of passed, failed, and skipped tests.
-8. **`assertionEvidence`**: Specific assertion proof matching the active Goal Contract's Acceptance Criteria.
+8. **`assertionEvidence`**: Specific assertion proof matching the active Goal Contract's Acceptance Criteria, observed at a named test seam.
 
 ```json
 {

package/examples/initialization/discovery-trace.md

@@ -57,7 +57,7 @@
 ## 3. Completion & Hand-off
 
 ```text
-[ENGINE] Generated .ai-engineering-loop/ (config.md, architecture.md, conventions.md, verification.md, adapter.md)
+[ENGINE] Generated .ai-engineering-loop/ (config.md, architecture.md, conventions.md, verification.md, adapter.md, glossary.md, adrs/README.md)
 [ENGINE] Project Context successfully initialized!
 [ENGINE] Proceeding to Goal Contract formulation...
 ```

package/examples/initialization/generated-context.md

@@ -1,6 +1,6 @@
 # Generated Context Artifacts: `acme-platform`
 
-Below are the exact 5 files generated automatically inside `/workspaces/acme-platform/.ai-engineering-loop/`:
+Below are the files generated automatically inside `/workspaces/acme-platform/.ai-engineering-loop/` (including `glossary.md` and `adrs/README.md`):
 
 ---