chati-dev 4.2.2 → 4.3.0

package/src/orchestrator/session-manager.js

@@ -14,7 +14,7 @@ const SESSION_FILE = '.chati/session.yaml';
 /**
  * Default session template.
  */
-const CURRENT_SCHEMA_VERSION = '1.0';
+const CURRENT_SCHEMA_VERSION = '1.2';
 
 const DEFAULT_SESSION = {
   schema_version: CURRENT_SCHEMA_VERSION,
@@ -35,6 +35,31 @@ const DEFAULT_SESSION = {
   agent_results: {},
   mode_transitions: [],
   deviations: [],
+  // Scaffold Premium (Article XXI / Fase 10) — auto-gate wiring.
+  // scaffold_candidates: presets eligible for this project (e.g. ['motion-premium'])
+  //   written by greenfield-wu when stack answer signals a match.
+  // scaffold_signals: per-preset confidence/evidence map, written by
+  //   ux-brand-architect when reference analysis detects premium patterns.
+  // scaffold_applied: presets already applied by the decision dispatcher
+  //   (prevents double-apply when advance is re-run).
+  scaffold_candidates: [],
+  scaffold_signals: {},
+  scaffold_applied: [],
+  // Context Window Detection (Article XII v2) — model-aware brackets.
+  // active_model: normalized key from parseClaudeModelId() (e.g. 'opus[1m]'),
+  //   written by /chati boot; drives context limit resolution.
+  // active_provider: redundant with providers_enabled[0] but flat for hooks.
+  // context_tokens_used: rolling cumulative estimate (char-based); written
+  //   by prism-engine on every UserPromptSubmit. Replaces turn-count as the
+  //   primary metric for bracket determination.
+  // context_window_tokens: cached limit resolved from active_model+provider
+  //   so hooks avoid re-loading model-limits.json every fire.
+  // context_last_bracket: last computed bracket — telemetry + /chati status.
+  active_model: null,
+  active_provider: null,
+  context_tokens_used: 0,
+  context_window_tokens: null,
+  context_last_bracket: null,
   agents: {
     'greenfield-wu': { status: 'pending', score: 0, criteria_count: 0, completed_at: null },
     'brownfield-wu': { status: 'pending', score: 0, criteria_count: 0, completed_at: null },
@@ -47,10 +72,32 @@ const DEFAULT_SESSION = {
     'qa-planning': { status: 'pending', score: 0, criteria_count: 0, completed_at: null },
     'dev': { status: 'pending', score: 0, criteria_count: 0, completed_at: null },
     'qa-implementation': { status: 'pending', score: 0, criteria_count: 0, completed_at: null },
+    'qa-visual': { status: 'pending', score: 0, criteria_count: 0, completed_at: null },
     'devops': { status: 'pending', score: 0, criteria_count: 0, completed_at: null },
   },
   backlog: [],
   last_handoff: '',
+  // Fault Vector Protocol (Article XXII) — append-only known-bad state log.
+  // Consumed by agents before iterating so the same defect is not re-introduced.
+  decision_trail: [],
+  // Agent Teams (Article XXI) — empty until spawn-team is called.
+  teams: [],
+  team_events: [],
+  // Execution Mode (Article XVII) — canonical. Article XVIII was deprecated
+  // 2026-04-18: execution_profile + profile_transitions were folded into
+  // execution_mode (set in DEFAULT_SESSION above as 'interactive'/'autonomous').
+  providers_enabled: ['claude'],
+  // BUILD → DEPLOY preview state (user approves before devops ships).
+  preview: {
+    status: 'inactive',
+    url: null,
+    port: null,
+    framework: null,
+    logs_captured: 0,
+    adjustment_count: 0,
+  },
+  // Model Governance (Article XVI) — per-agent model selection log.
+  model_selections: [],
 };
 
 /**
@@ -120,7 +167,7 @@ export function migrateSession(session) {
     return { migrated: false, fromVersion: session.schema_version, toVersion: CURRENT_SCHEMA_VERSION };
   }
 
-  // v0 (no schema_version) → v1.0
+  // v0 (no schema_version) → v1.0 → v1.1 → v1.2
   const fromVersion = session.schema_version || null;
   session.schema_version = CURRENT_SCHEMA_VERSION;
 
@@ -130,6 +177,53 @@ export function migrateSession(session) {
   if (!session.deviations) session.deviations = [];
   if (!session.mode_transitions) session.mode_transitions = [];
 
+  // v1.1 — scaffold auto-gate fields (Fase 10).
+  if (!Array.isArray(session.scaffold_candidates)) session.scaffold_candidates = [];
+  if (!session.scaffold_signals || typeof session.scaffold_signals !== 'object') {
+    session.scaffold_signals = {};
+  }
+  if (!Array.isArray(session.scaffold_applied)) session.scaffold_applied = [];
+
+  // v1.2 — context window detection fields (Article XII v2).
+  // Defaults null/0 — /chati boot or prism-engine will populate on first hook.
+  if (!('active_model' in session))          session.active_model = null;
+  if (!('active_provider' in session))       session.active_provider = null;
+  if (typeof session.context_tokens_used !== 'number') session.context_tokens_used = 0;
+  if (!('context_window_tokens' in session)) session.context_window_tokens = null;
+  if (!('context_last_bracket' in session))  session.context_last_bracket = null;
+
+  // Schema parity catch-up (audit-fixes-v1 P4, additive). These fields live in
+  // session.schema.json but were not seeded into DEFAULT_SESSION historically.
+  // Runtime guards (`|| []`, `|| {}`) elsewhere kept things safe, but older
+  // sessions re-loaded here now get proper defaults without those guards.
+  if (!Array.isArray(session.decision_trail))       session.decision_trail = [];
+  if (!Array.isArray(session.teams))                session.teams = [];
+  if (!Array.isArray(session.team_events))          session.team_events = [];
+  if (!Array.isArray(session.providers_enabled))    session.providers_enabled = ['claude'];
+  if (!Array.isArray(session.model_selections))     session.model_selections = [];
+  if (!session.preview || typeof session.preview !== 'object') {
+    session.preview = {
+      status: 'inactive', url: null, port: null, framework: null,
+      logs_captured: 0, adjustment_count: 0,
+    };
+  }
+
+  // Article XVIII deprecation (2026-04-18): collapse execution_profile into
+  // execution_mode per the migration table. Runs LAST so it overrides any
+  // default seeded above. See constitution Article XVIII for rationale.
+  if (typeof session.execution_profile === 'string') {
+    const map = { explore: 'interactive', guided: 'interactive', autonomous: 'autonomous' };
+    const mapped = map[session.execution_profile.toLowerCase()];
+    if (mapped && session.execution_mode !== 'autonomous') {
+      // Only downgrade if current execution_mode is not already autonomous.
+      session.execution_mode = mapped;
+    }
+    delete session.execution_profile;
+  }
+  if (Array.isArray(session.profile_transitions)) {
+    delete session.profile_transitions;
+  }
+
   return { migrated: true, fromVersion, toVersion: CURRENT_SCHEMA_VERSION };
 }
 
@@ -275,13 +369,35 @@ export function recordModeTransition(projectDir, transition) {
     session.project.state = transition.to;
   }
 
-  return updateSession(projectDir, session);
+  return writeSessionToDisk(projectDir, session);
+}
+
+/**
+ * Persist the full session object to disk. Avoids routing through updateSession's
+ * spread+deep-merge logic (which can corrupt list fields like `completed_agents`
+ * when the full session is passed as the updates arg).
+ * @param {string} projectDir
+ * @param {object} session
+ * @returns {{ saved: boolean, session?: object, error?: string }}
+ */
+function writeSessionToDisk(projectDir, session) {
+  const sessionPath = join(projectDir, SESSION_FILE);
+  try {
+    const yamlContent = yaml.dump(session, { lineWidth: -1, noRefs: true });
+    writeFileSync(sessionPath, yamlContent, 'utf-8');
+    return { saved: true, session };
+  } catch (err) {
+    return { saved: false, error: `Failed to write session: ${err.message}` };
+  }
 }
 
 /**
  * Record an agent completion in session.
  * @param {string} projectDir
- * @param {object} completion - { agent, status, score, outputs }
+ * @param {object} completion - { agent, status, score, outputs, handoffData }
+ *   handoffData may include:
+ *     - decision_trail_entries: array of new Decision Trail objects to append
+ *     - resolved_decision_trail: array of DT entry IDs to mark resolved: true
  * @returns {{ saved: boolean }}
  */
 export function recordAgentCompletion(projectDir, completion) {
@@ -295,7 +411,7 @@ export function recordAgentCompletion(projectDir, completion) {
   }
 
   const session = loadResult.session;
-  const { agent, status, score, outputs = [] } = completion;
+  const { agent, status, score, outputs = [], handoffData = {} } = completion;
 
   // Update agent data
   if (!session.agents[agent]) {
@@ -329,7 +445,216 @@ export function recordAgentCompletion(projectDir, completion) {
   // Update last handoff
   session.last_handoff = agent;
 
-  return updateSession(projectDir, session);
+  // Merge Decision Trail entries from agent handoff document.
+  // Agents (e.g. qa-implementation) write Decision Trail entries to their handoff
+  // document instead of directly editing session.yaml (which is blocked by the
+  // mode-governance hook). The CLI reads them here and merges into session.yaml.
+  if (Array.isArray(handoffData.decision_trail_entries) && handoffData.decision_trail_entries.length > 0) {
+    session.decision_trail = [
+      ...(session.decision_trail || []),
+      ...handoffData.decision_trail_entries,
+    ];
+  }
+
+  // Mark resolved Decision Trail entries from agent handoff document.
+  if (Array.isArray(handoffData.resolved_decision_trail) && handoffData.resolved_decision_trail.length > 0) {
+    const trail = session.decision_trail || [];
+    for (const resolvedId of handoffData.resolved_decision_trail) {
+      const entry = trail.find(e => e.id === resolvedId);
+      if (entry) {
+        entry.resolved = true;
+      }
+    }
+    session.decision_trail = trail;
+  }
+
+  // Merge scaffold candidates/signals from handoff (Fase 10 auto-gate).
+  // - candidates: union into session.scaffold_candidates (dedup).
+  // - signals: overwrite session.scaffold_signals[key] (later signal wins)
+  //   and stamp source_agent + updated_at.
+  if (Array.isArray(handoffData.scaffold_candidates) && handoffData.scaffold_candidates.length > 0) {
+    session.scaffold_candidates = session.scaffold_candidates || [];
+    for (const preset of handoffData.scaffold_candidates) {
+      if (!session.scaffold_candidates.includes(preset)) {
+        session.scaffold_candidates.push(preset);
+      }
+    }
+  }
+  if (handoffData.scaffold_signals && typeof handoffData.scaffold_signals === 'object') {
+    session.scaffold_signals = session.scaffold_signals || {};
+    for (const [key, signal] of Object.entries(handoffData.scaffold_signals)) {
+      session.scaffold_signals[key] = {
+        ...signal,
+        source_agent: agent,
+        updated_at: new Date().toISOString(),
+      };
+    }
+  }
+
+  return writeSessionToDisk(projectDir, session);
+}
+
+/**
+ * Parse Decision Trail entries from an agent's handoff markdown document.
+ *
+ * The agent writes Decision Trail entries under a "## Decision Trail" heading
+ * and resolved IDs under "## Resolved Decision Trail". This function extracts
+ * both so they can be passed to recordAgentCompletion() as handoffData.
+ *
+ * @param {string} handoffMarkdown - Full text of the handoff .md file
+ * @returns {{ decision_trail_entries: object[], resolved_decision_trail: string[] }}
+ */
+export function parseHandoffDecisionTrail(handoffMarkdown) {
+  const decision_trail_entries = [];
+  const resolved_decision_trail = [];
+
+  if (!handoffMarkdown || typeof handoffMarkdown !== 'string') {
+    return { decision_trail_entries, resolved_decision_trail };
+  }
+
+  // Extract ## Decision Trail section (stop at next ## heading or end of input).
+  // Note: JS regex does not support \z (end-of-input anchor). Using $(?![\s\S])
+  // — an $ followed by negative lookahead "no more chars" — gives the same
+  // semantics. The previous \z was treated as literal 'z', silently truncating
+  // content at the first 'z' character in the Decision Trail block.
+  const dtMatch = handoffMarkdown.match(
+    /^## Decision Trail\s*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m,
+  );
+  if (dtMatch) {
+    const block = dtMatch[1];
+    // Parse YAML-like bullet blocks: lines starting with "  id: DT-"
+    // Split on entries that start a new id: field
+    const entryBlocks = block.split(/(?=^\s*-?\s*id:\s*DT-)/m).filter(Boolean);
+    for (const entryBlock of entryBlocks) {
+      try {
+        // Build a minimal object from key: value lines
+        const entry = {};
+        for (const line of entryBlock.split('\n')) {
+          const kv = line.match(/^\s*-?\s*(\w+(?:_\w+)*):\s*(.+)$/);
+          if (kv) {
+            const [, key, value] = kv;
+            // Coerce resolved field to boolean
+            if (key === 'resolved') {
+              entry[key] = value.trim() === 'true';
+            } else {
+              entry[key] = value.trim().replace(/^["']|["']$/g, '');
+            }
+          }
+        }
+        if (entry.id && entry.id.startsWith('DT-')) {
+          decision_trail_entries.push(entry);
+        }
+      } catch {
+        // Malformed entry — skip silently
+      }
+    }
+  }
+
+  // Extract ## Resolved Decision Trail section (same \z → $(?![\s\S]) fix)
+  const resolvedMatch = handoffMarkdown.match(
+    /^## Resolved Decision Trail\s*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m,
+  );
+  if (resolvedMatch) {
+    const block = resolvedMatch[1];
+    // Each line may be "- DT-001" or just "DT-001"
+    for (const line of block.split('\n')) {
+      const idMatch = line.match(/\bDT-\d+\b/);
+      if (idMatch) {
+        resolved_decision_trail.push(idMatch[0]);
+      }
+    }
+  }
+
+  return { decision_trail_entries, resolved_decision_trail };
+}
+
+/**
+ * Parse scaffold-auto-gate metadata from an agent's handoff markdown.
+ *
+ * Two sections are recognized (both optional):
+ *
+ *   ## Scaffold Candidates
+ *     - <preset-id>
+ *     - <preset-id>
+ *
+ *   ## Scaffold Signals
+ *     - preset: <preset-id>
+ *       candidate: true
+ *       confidence: 0.0–1.0
+ *       evidence:
+ *         - "<short match string>"
+ *
+ * Returns arrays/objects the CLI merges into session via recordAgentCompletion.
+ *
+ * @param {string} handoffMarkdown
+ * @returns {{ scaffold_candidates: string[], scaffold_signals: object }}
+ */
+export function parseHandoffScaffoldSignals(handoffMarkdown) {
+  const scaffold_candidates = [];
+  const scaffold_signals = {};
+
+  if (!handoffMarkdown || typeof handoffMarkdown !== 'string') {
+    return { scaffold_candidates, scaffold_signals };
+  }
+
+  // ## Scaffold Candidates — bullet list of preset ids.
+  const candidatesMatch = handoffMarkdown.match(
+    /^## Scaffold Candidates\s*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m,
+  );
+  if (candidatesMatch) {
+    const block = candidatesMatch[1];
+    for (const line of block.split('\n')) {
+      const m = line.match(/^\s*[-*]\s+([a-z][a-z0-9-]*)\s*$/);
+      if (m && !scaffold_candidates.includes(m[1])) {
+        scaffold_candidates.push(m[1]);
+      }
+    }
+  }
+
+  // ## Scaffold Signals — one YAML-ish entry per preset.
+  const signalsMatch = handoffMarkdown.match(
+    /^## Scaffold Signals\s*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m,
+  );
+  if (signalsMatch) {
+    const block = signalsMatch[1];
+    // Split on lines that start a new "- preset:" entry.
+    const entries = block.split(/(?=^\s*-\s*preset:\s*)/m).filter(Boolean);
+    for (const entry of entries) {
+      const presetMatch = entry.match(/preset:\s*([a-z][a-z0-9-]*)/);
+      if (!presetMatch) continue;
+      const preset = presetMatch[1];
+      // Normalize for YAML keys (underscore, safer than dash for downstream).
+      const key = preset.replace(/-/g, '_');
+
+      const confMatch = entry.match(/confidence:\s*([\d.]+)/);
+      const confidence = confMatch ? Math.max(0, Math.min(1, parseFloat(confMatch[1]))) : 0;
+
+      const candidateMatch = entry.match(/candidate:\s*(true|false)/);
+      const isCandidate = candidateMatch ? candidateMatch[1] === 'true' : confidence > 0;
+      if (!isCandidate) continue;
+
+      const evidence = [];
+      const evidenceSection = entry.match(/evidence:\s*\n([\s\S]*?)(?=\n\s*[-*]\s*preset:|$)/);
+      if (evidenceSection) {
+        for (const line of evidenceSection[1].split('\n')) {
+          const em = line.match(/^\s*[-*]\s+"?(.+?)"?\s*$/);
+          if (em && em[1].trim()) evidence.push(em[1].trim());
+        }
+      }
+
+      scaffold_signals[key] = {
+        confidence,
+        evidence,
+        source_agent: null, // filled in by recordAgentCompletion
+        updated_at: null,
+      };
+
+      // If the signal is emitted, the preset is an implicit candidate too.
+      if (!scaffold_candidates.includes(preset)) scaffold_candidates.push(preset);
+    }
+  }
+
+  return { scaffold_candidates, scaffold_signals };
 }
 
 /**

package/src/tasks/handoff.js

@@ -8,6 +8,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
 /**
  * Build a handoff document from task execution results.
@@ -123,7 +124,7 @@ export function formatHandoff(handoff) {
  */
 export function saveHandoff(projectDir, handoff) {
   try {
-    const handoffsDir = join(projectDir, 'chati.dev', 'artifacts', 'handoffs');
+    const handoffsDir = join(projectDir, resolveFrameworkDir(projectDir), 'artifacts', 'handoffs');
     if (!existsSync(handoffsDir)) {
       mkdirSync(handoffsDir, { recursive: true });
     }
@@ -147,7 +148,7 @@ export function saveHandoff(projectDir, handoff) {
  * @returns {{ loaded: boolean, handoff: object|null, error: string|null }}
  */
 export function loadHandoff(projectDir, agentName) {
-  const filePath = join(projectDir, 'chati.dev', 'artifacts', 'handoffs', `${agentName}-handoff.md`);
+  const filePath = join(projectDir, resolveFrameworkDir(projectDir), 'artifacts', 'handoffs', `${agentName}-handoff.md`);
 
   if (!existsSync(filePath)) {
     return { loaded: false, handoff: null, error: `No handoff found from agent '${agentName}'.` };

package/src/telemetry/config.js

@@ -7,6 +7,7 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 import { randomUUID } from 'crypto';
 import yaml from 'js-yaml';
 
@@ -21,7 +22,7 @@ import yaml from 'js-yaml';
  * @returns {{ enabled: boolean, anonymousId: string | null, endpoint: string }}
  */
 export function getTelemetryConfig(targetDir) {
-  const configPath = join(targetDir, 'chati.dev', 'config.yaml');
+  const configPath = join(targetDir, resolveFrameworkDir(targetDir), 'config.yaml');
 
   const defaults = {
     enabled: true,
@@ -64,7 +65,7 @@ export function isEnabled(targetDir) {
  * @param {boolean} enabled
  */
 export function setEnabled(targetDir, enabled) {
-  const configPath = join(targetDir, 'chati.dev', 'config.yaml');
+  const configPath = join(targetDir, resolveFrameworkDir(targetDir), 'config.yaml');
 
   if (!existsSync(configPath)) return;
 
@@ -99,7 +100,7 @@ export function getAnonymousId(targetDir) {
 
   // Generate and persist
   const id = randomUUID();
-  const configPath = join(targetDir, 'chati.dev', 'config.yaml');
+  const configPath = join(targetDir, resolveFrameworkDir(targetDir), 'config.yaml');
 
   if (existsSync(configPath)) {
     try {

package/src/telemetry/schema.js

@@ -19,6 +19,7 @@ export const TELEMETRY_EVENTS = [
   'session_started',
   'session_completed',
   'token_usage',
+  'rate_limit_wait',
 ];
 
 // ---------------------------------------------------------------------------

package/src/terminal/collector.js

@@ -59,9 +59,10 @@ export function collectResults(groupId, terminals) {
  *   { agent, outputs[], decisions{}, blockers[], summary }
  *
  * @param {object[]} results - Per-terminal result objects (from collectResults)
+ * @param {string} [projectDir] - Project root directory (used for write scope resolution)
  * @returns {{ merged: boolean, outputs: string[], decisions: Record<string,string>, blockers: string[], summary: string }}
  */
-export function mergeHandoffs(results) {
+export function mergeHandoffs(results, projectDir) {
   if (!Array.isArray(results) || results.length === 0) {
     return {
       merged: false,
@@ -82,7 +83,7 @@ export function mergeHandoffs(results) {
     if (Array.isArray(result.outputs)) {
       outputs.push(...result.outputs);
     } else {
-      const scope = getWriteScope(result.agent);
+      const scope = getWriteScope(result.agent, projectDir);
       if (scope.length > 0) {
         outputs.push(...scope.map(s => `${result.agent}: ${s}`));
       }

package/src/terminal/index.js

@@ -22,7 +22,6 @@ export {
 } from './collector.js';
 
 export {
-  WRITE_SCOPES,
   getWriteScope,
   validateWriteScopes,
   isPathAllowed,
@@ -32,7 +31,7 @@ export {
 
 export {
   buildAgentPrompt,
-  AGENT_FILE_MAP,
+  getAgentFile,
 } from './prompt-builder.js';
 
 export {

package/src/terminal/isolation.js

@@ -1,4 +1,5 @@
 import { posix } from 'path';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
 /**
  * @fileoverview Write scope isolation for multi-terminal execution.
@@ -12,38 +13,71 @@ import { posix } from 'path';
 
 /**
  * Default write scope mapping per agent.
- * Each key is an agent name; each value is an array of path prefixes
- * (relative to the project root) the agent is allowed to write.
+ * Paths are relative to the framework directory (e.g. 'artifacts/0-WU/').
+ * Non-framework paths (src/, test/, etc.) are stored as-is.
+ *
+ * Use getWriteScope(agent, projectDir) to get resolved paths.
  *
  * @type {Record<string, string[]>}
  */
-export const WRITE_SCOPES = {
-  'greenfield-wu': ['chati.dev/artifacts/0-WU/'],
-  'brownfield-wu': ['chati.dev/artifacts/0-WU/'],
-  'brief':         ['chati.dev/artifacts/1-Brief/'],
-  'detail':        ['chati.dev/artifacts/2-PRD/'],
-  'architect':     ['chati.dev/artifacts/3-Architecture/'],
-  'ux':            ['chati.dev/artifacts/4-UX/'],
-  'phases':        ['chati.dev/artifacts/5-Phases/'],
-  'tasks':         ['chati.dev/artifacts/6-Tasks/'],
-  'qa-planning':   ['chati.dev/artifacts/7-QA-Planning/'],
-  'dev':           ['src/', 'test/', 'package.json'],
-  'qa-implementation': ['test/', 'chati.dev/artifacts/8-QA-Impl/'],
-  'devops':        ['.github/', 'Dockerfile', 'docker-compose.yml', 'chati.dev/artifacts/9-Deploy/'],
+// IMPORTANT: artifacts/ lives at PROJECT ROOT (visible user output), NOT inside
+// the framework dir. All artifact paths use the :non-framework: prefix so they
+// resolve to <projectDir>/artifacts/, not <projectDir>/.chati.dev/artifacts/.
+const WRITE_SCOPE_TEMPLATES = {
+  'greenfield-wu': [':non-framework:artifacts/0-WU/', ':non-framework:artifacts/handoffs/greenfield-wu-handoff.md'],
+  'brownfield-wu': [':non-framework:artifacts/0-WU/', ':non-framework:artifacts/handoffs/brownfield-wu-handoff.md'],
+  'brief':         [':non-framework:artifacts/1-Brief/', ':non-framework:artifacts/handoffs/brief-handoff.md'],
+  'detail':        [':non-framework:artifacts/2-PRD/', ':non-framework:artifacts/handoffs/detail-handoff.md'],
+  'architect':     [':non-framework:artifacts/3-Architecture/', ':non-framework:artifacts/handoffs/architect-handoff.md'],
+  'ux':            [':non-framework:artifacts/4-UX/', ':non-framework:artifacts/handoffs/ux-handoff.md'],
+  'phases':        [':non-framework:artifacts/5-Phases/', ':non-framework:artifacts/handoffs/phases-handoff.md'],
+  'tasks':         [':non-framework:artifacts/6-Tasks/', ':non-framework:artifacts/handoffs/tasks-handoff.md'],
+  'qa-planning':   [':non-framework:artifacts/7-QA-Planning/', ':non-framework:artifacts/handoffs/qa-planning-handoff.md'],
+  'dev':           [':non-framework:src/', ':non-framework:test/', ':non-framework:package.json', ':non-framework:artifacts/8-Implementation/', ':non-framework:artifacts/handoffs/dev-handoff.md'],
+  'qa-implementation': [':non-framework:test/', ':non-framework:artifacts/9-QA-Implementation/', ':non-framework:artifacts/handoffs/qa-implementation-handoff.md'],
+  'qa-visual':     [':non-framework:artifacts/handoffs/qa-visual-handoff.md', ':non-framework:artifacts/9-QA-Implementation/qa-visual-report.md'],
+  'devops':        [':non-framework:.github/', ':non-framework:Dockerfile', ':non-framework:docker-compose.yml', ':non-framework:artifacts/10-Deploy/', ':non-framework:artifacts/handoffs/devops-handoff.md'],
 };
 
 /**
- * Return the write scope for a given agent.
+ * Resolved write scopes keyed as 'agent:fwDir' for memoization.
+ * @type {Map<string, string[]>}
+ */
+const _writeScopeCache = new Map();
+
+
+/**
+ * Return the write scope for a given agent, resolved against the project structure.
  *
  * @param {string} agent - Agent name (e.g. "architect")
+ * @param {string} [projectDir] - Project root directory. When provided, paths
+ *   are resolved using resolveFrameworkDir() so .chati.dev/ vs chati.dev/ is correct.
  * @returns {string[]} Array of path prefixes the agent may write to.
  *   Returns an empty array for unknown agents.
  */
-export function getWriteScope(agent) {
+export function getWriteScope(agent, projectDir) {
   if (!agent || typeof agent !== 'string') {
     return [];
   }
-  return WRITE_SCOPES[agent] || [];
+  const templates = WRITE_SCOPE_TEMPLATES[agent];
+  if (!templates) return [];
+
+  // Without projectDir, return legacy chati.dev/ paths (backward compat)
+  if (!projectDir) {
+    return templates.map(p => p.startsWith(':non-framework:') ? p.slice(':non-framework:'.length) : `chati.dev/${p}`);
+  }
+
+  const fwDir = resolveFrameworkDir(projectDir);
+  const cacheKey = `${agent}:${fwDir}`;
+  if (_writeScopeCache.has(cacheKey)) {
+    return _writeScopeCache.get(cacheKey);
+  }
+
+  const resolved = templates.map(p =>
+    p.startsWith(':non-framework:') ? p.slice(':non-framework:'.length) : `${fwDir}/${p}`
+  );
+  _writeScopeCache.set(cacheKey, resolved);
+  return resolved;
 }
 
 /**