chati-dev 4.5.28 → 4.5.29

package/bin/chati.js

@@ -2,7 +2,7 @@
 
 import { resolve } from 'path';
 import { randomUUID } from 'crypto';
-import { readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 
@@ -10,7 +10,6 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 
 import { logBanner } from '../src/utils/logger.js';
-import { resolveFrameworkDir } from '../src/utils/framework-dir.js';
 
 function showBanner() {
   let logoText;
@@ -27,6 +26,8 @@ const command = args[0] || 'init';
 // Known subcommands and agent names that should NOT be mistaken for targetDir paths.
 // Without this, `chati orchestrate advance --agent detail` resolves targetDir to `<cwd>/detail/`.
 const KNOWN_SUBCOMMANDS = new Set([
+  'rail-authority-enroll', 'rail-authority-request', 'rail-verify', 'rail-effort',
+  'rail-browser-artifact', 'rail-browser-prune',
   // CLI subcommands
   'next', 'advance', 'init', 'status', 'validate-handoff', 'deviation', 'exit', 'activate-harness',
   'install-v2', 'migrate-v2', 'rail-import', 'rail-next', 'rail-dispatch', 'rail-review-run', 'rail-rework', 'rail-adjudicate', 'rail-release-ready', 'rail-recover', 'rail-complete', 'rail-tracking-reconcile', 'rail-tracking-pending', 'rail-tracking-ack', 'rail-tracking-lookup',
@@ -56,6 +57,22 @@ const targetDir = resolve(
 );
 
 async function main() {
+  // v2 mutators acquire maintenance only after authorization in their common
+  // API. Migration previews must not create maintenance bookkeeping at all.
+  const projectCommand = command.startsWith('rail-') || ['init', 'install',
+    'status', 'check-update', 'memory', 'context', 'registry', 'health', 'telemetry', 'scaffold', '--reconfigure'].includes(command);
+  // `init <new-project>` scaffolds a directory that does not exist yet; the
+  // installer bootstraps its own lease once it creates `.chati`. Maintenance
+  // can only wrap commands whose project root already exists.
+  const scaffoldingNewDirectory = ['init', 'install'].includes(command) && !existsSync(targetDir);
+  if (projectCommand && !scaffoldingNewDirectory) {
+    const { withUpgradeMaintenance } = await import('../src/upgrade/maintenance.js');
+    return withUpgradeMaintenance(targetDir, executeCommand);
+  }
+  return executeCommand();
+}
+
+async function executeCommand() {
   switch (command) {
     case 'init':
     case 'install': {
@@ -80,7 +97,7 @@ async function main() {
       }
       const { installV2 } = await import('../src/installer-v2/index.js');
       try {
-        const result = installV2(input, { projectDir: targetDir });
+        const result = await installV2(input, { projectDir: targetDir });
         console.log(JSON.stringify(result, null, 2));
       } catch (error) {
         console.error(`Error: ${error.code || 'INSTALL_V2_FAILED'}: ${error.message}`);
@@ -105,7 +122,7 @@ async function main() {
       }
       try {
         const { migrateV2 } = await import('../src/installer-v2/index.js');
-        const result = migrateV2(input, { projectDir: targetDir, authorize: args.includes('--apply') });
+        const result = await migrateV2(input, { projectDir: targetDir, authorize: args.includes('--apply') });
         console.log(JSON.stringify(result, null, 2));
       } catch (error) {
         console.error(`Error: ${error.code || 'MIGRATE_V2_FAILED'}: ${error.message}`);
@@ -262,23 +279,20 @@ async function main() {
       }
       const attemptId = value('--attempt-id');
       try {
-        const { resolveRailAttemptContext } = await import('../src/orchestrator/rail-runtime.js');
-        const { executeReadyRailTask } = await import('../src/terminal/run-rail-task.js');
-        const context = resolveRailAttemptContext({
-          projectDir: targetDir,
-          handoff_id: value('--handoff-id'),
-          attempt_id: attemptId,
-        });
-        const result = await executeReadyRailTask({
+        const { recoverAndResumeRailTask } = await import('../src/terminal/run-rail-recovery.js');
+        const result = await recoverAndResumeRailTask({
           projectDir: targetDir,
           handoff_id: value('--handoff-id'),
-          task_id: context.task.task_id,
           attempt_id: attemptId,
           operator_id: value('--operator-id'),
           git_dir: value('--git-dir') || targetDir,
-          recover_expired: true,
           ...(value('--timeout') ? { timeout: Number(value('--timeout')) } : {}),
           ...(value('--browser-request-json') ? { browser_request: JSON.parse(value('--browser-request-json')) } : {}),
+          // macOS only: the operator explicitly attests that no process of the
+          // interrupted launch remains, instead of waiting for a reboot.
+          ...(args.includes('--attest-terminated') ? { termination_attestation: {
+            operator_id: value('--operator-id'), attested_at: new Date().toISOString(), statement: 'no-launch-processes-remain',
+          } } : {}),
         });
         console.log(JSON.stringify(result, null, 2));
         if (!result.ok) process.exitCode = 1;
@@ -286,13 +300,104 @@ async function main() {
         console.error(JSON.stringify({
           ok: false, action: 'error', error: error.code || 'RAIL_RECOVERY_FAILED',
           detail: error.message, attempt_id: error.details?.attempt_id || attemptId,
-          next_required_action: 'rail_recover_and_dispatch_same_attempt',
+          next_required_action: error.details?.next_required_action || 'rail_recover_and_dispatch_same_attempt',
+          ...(error.details?.interruption_event_id ? { interruption_event_id: error.details.interruption_event_id } : {}),
+          ...(error.details?.checkpoint_event_id ? { checkpoint_event_id: error.details.checkpoint_event_id } : {}),
         }));
         process.exitCode = 1;
       }
       break;
     }
 
+    case 'rail-effort':
+    case 'rail-verify': {
+      try {
+        const values = new Map();
+        for (let index = 1; index < args.length; index += 2) {
+          const flag = args[index];
+          const value = args[index + 1];
+          if (!['--project-dir', '--handoff-id', '--attempt-id'].includes(flag)
+            || values.has(flag) || !value || value.startsWith('-')) {
+            throw Object.assign(new Error(`${command} accepts --project-dir, --handoff-id and --attempt-id only`), {
+              code: command === 'rail-effort' ? 'HUMAN_EFFORT_INPUT_INVALID' : 'RAIL_VERIFICATION_INPUT_INVALID' });
+          }
+          values.set(flag, value);
+        }
+        const run = command === 'rail-effort'
+          ? (await import('../src/orchestrator/rail-human-effort.js')).runHumanEffortTerminal
+          : (await import('../src/orchestrator/rail-verification.js')).observeRailVerification;
+        const result = await run({ projectDir: targetDir,
+          handoff_id: values.get('--handoff-id'), attempt_id: values.get('--attempt-id') });
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.ok) process.exitCode = 1;
+      } catch (error) {
+        console.error(`Error: ${error.code || 'RAIL_VERIFICATION_FAILED'}: ${error.message}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+
+    case 'rail-browser-artifact':
+    case 'rail-browser-prune': {
+      try {
+        const values = new Map();
+        const allowed = command === 'rail-browser-artifact' ? ['--project-dir', '--ref'] : ['--project-dir'];
+        for (let index = 1; index < args.length; index += 2) {
+          const flag = args[index]; const value = args[index + 1];
+          if (!allowed.includes(flag) || values.has(flag) || !value || value.startsWith('-')) {
+            throw Object.assign(new Error(`${command} accepts ${allowed.join(', ')} only`), { code: 'BROWSER_ARTIFACT_INPUT_INVALID' });
+          }
+          values.set(flag, value);
+        }
+        const { loadRuntimeInstallationV2 } = await import('../src/orchestrator/runtime-installation-v2.js');
+        const installation = loadRuntimeInstallationV2(targetDir);
+        if (!installation) throw Object.assign(new Error('browser artifact access requires a verified installation'), { code: 'V2_INSTALLATION_REQUIRED' });
+        const store = await import('../src/orchestrator/browser-artifact-store.js');
+        const options = { projectDir: targetDir, projectId: installation.project_id };
+        const result = command === 'rail-browser-artifact'
+          ? store.readBrowserArtifact({ ...options, ref: values.get('--ref') }) : store.pruneBrowserArtifacts(options);
+        console.log(JSON.stringify(result, null, 2));
+        if (result.ok === false) process.exitCode = 1;
+      } catch (error) {
+        console.error(`Error: ${error.code || 'BROWSER_ARTIFACT_FAILED'}: ${error.message}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+
+    case 'rail-authority-request': {
+      const kindIndex = args.indexOf('--kind');
+      const kind = kindIndex === -1 ? null : args[kindIndex + 1];
+      try {
+        const { createEvidenceAuthorityRequest } = await import('../src/orchestrator/evidence-authority-request.js');
+        console.log(JSON.stringify(createEvidenceAuthorityRequest({ projectDir: targetDir, kind }), null, 2));
+      } catch (error) {
+        console.error(`Error: ${error.code || 'AUTHORITY_REQUEST_FAILED'}: ${error.message}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+
+    case 'rail-authority-enroll': {
+      const certificateIndex = args.indexOf('--certificate');
+      const certificatePath = certificateIndex === -1 ? null : args[certificateIndex + 1];
+      if (!certificatePath || certificatePath.startsWith('--')) {
+        console.error('Error: rail-authority-enroll requires --certificate <CHATI-signed-public-certificate.json>');
+        process.exitCode = 1;
+        break;
+      }
+      try {
+        const { enrollProjectEvidenceAuthorityFile } = await import('../src/orchestrator/evidence-authority-enrollment.js');
+        console.log(JSON.stringify(enrollProjectEvidenceAuthorityFile({
+          projectDir: targetDir, certificatePath: resolve(certificatePath), replace: args.includes('--replace'),
+        }), null, 2));
+      } catch (error) {
+        console.error(`Error: ${error.code || 'AUTHORITY_ENROLLMENT_FAILED'}: ${error.message}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+
     case 'rail-complete': {
       const value = (flag) => { const index = args.indexOf(flag); return index === -1 ? null : args[index + 1]; };
       if (!value('--handoff-id') || !value('--completion')) {
@@ -303,10 +408,11 @@ async function main() {
       try {
         const completion = JSON.parse(readFileSync(resolve(value('--completion')), 'utf8'));
         const { completeRailTask } = await import('../src/orchestrator/rail-runtime.js');
-        const { completion_id, attempt_id, claim_id, operator_id, state, git, ci, reviews, acceptance_evidence_refs, acceptance_authority_receipt, completed_at, metrics } = completion;
+        const { completion_id, attempt_id, claim_id, operator_id, state, git, ci, reviews, acceptance_evidence_refs, acceptance_authority_receipt, browser_evidence, completed_at, metrics } = completion;
         console.log(JSON.stringify(completeRailTask({
           projectDir: targetDir, handoff_id: value('--handoff-id'), completion_id, attempt_id, claim_id, operator_id, state, git, ci,
-          reviews, acceptance_evidence_refs, acceptance_authority_receipt, ...(completed_at === undefined ? {} : { completed_at }), ...(metrics === undefined ? {} : { metrics }),
+          reviews, acceptance_evidence_refs, acceptance_authority_receipt, ...(browser_evidence === undefined ? {} : { browser_evidence }),
+          ...(completed_at === undefined ? {} : { completed_at }), ...(metrics === undefined ? {} : { metrics }),
         }), null, 2));
       } catch (error) {
         console.error(`Error: ${error.code || 'RAIL_COMPLETION_FAILED'}: ${error.message}`);
@@ -423,112 +529,21 @@ async function main() {
     case 'upgrade': {
       const versionFlag = args.indexOf('--version');
       const targetVersion = versionFlag !== -1 ? args[versionFlag + 1] : pkg.version;
-
-      const { getCurrentVersion, updateConfigVersion } = await import('../src/upgrade/checker.js');
-      const { createBackup, restoreFromBackup } = await import('../src/upgrade/backup.js');
-      const { runMigrations } = await import('../src/upgrade/migrator.js');
-      const { validateInstallation } = await import('../src/installer/validator.js');
-
-      const currentVersion = getCurrentVersion(targetDir);
-      if (!currentVersion) {
-        console.error('No Chati.dev installation found. Run `npx chati-dev init` first.');
-        process.exit(1);
-      }
-
-      console.log(`Upgrading Chati.dev v${currentVersion} -> v${targetVersion}...`);
-
-      // 1. Create backup
-      console.log('  Creating backup...');
-      const backupDir = createBackup(targetDir, currentVersion);
-      console.log(`  Backup created at: ${backupDir}`);
-
-      // 2. Run migrations
-      console.log('  Running migrations...');
-      const migrationResult = await runMigrations(targetDir, currentVersion, targetVersion);
-
-      if (!migrationResult.success) {
-        console.error(`  Migration failed at: ${migrationResult.failedAt}`);
-        console.error(`  Error: ${migrationResult.error}`);
-        console.log('  Rolling back...');
-        restoreFromBackup(targetDir, currentVersion);
-        console.log('  Rollback complete.');
-        process.exit(1);
-      }
-
-      console.log(`  ${migrationResult.migrationsRun} migration(s) applied.`);
-
-      // 2.5. Sync framework files (copy new/updated agents, templates, hooks, etc.)
-      console.log('  Syncing framework files...');
-      try {
-        const { copyFrameworkFiles } = await import('../src/installer/core.js');
-        copyFrameworkFiles(join(targetDir, resolveFrameworkDir(targetDir)));
-        console.log('  Framework files synced.');
-      } catch (err) {
-        console.log(`  Framework sync skipped: ${err.message}`);
-      }
-
-      // 2.55. Refresh .claude/settings.json (merge-safe) so hook registrations
-      // added in newer versions reach existing installs. Without this, projects
-      // installed before a hook was added to the generator never receive it
-      // (reasoning-escalator and git-push-authority were missing for everyone).
-      try {
-        const { writeClaudeSettingsWithMerge } = await import('../src/installer/core.js');
-        const { existsSync: ex } = await import('fs');
-        const settingsPath = join(targetDir, '.claude', 'settings.json');
-        if (ex(join(targetDir, '.claude'))) {
-          writeClaudeSettingsWithMerge(settingsPath);
-          console.log('  Claude settings refreshed (hooks re-registered).');
-        }
-      } catch (err) {
-        console.log(`  Settings refresh skipped: ${err.message}`);
+      if (targetVersion !== pkg.version) {
+        console.error(`UPGRADE_PACKAGE_VERSION_MISMATCH: this command contains v${pkg.version}; --version cannot fetch or relabel another package.`);
+        process.exitCode = 1;
+        break;
       }
-
-      // 2.6. Re-bundle CLI (Bug 4 part 3, v4.3.1+) — refreshes .chati.dev/_cli/
-      // and writes version.json so chati-router.js mismatch detection clears
-      // on the next invocation.
-      console.log('  Re-bundling CLI...');
       try {
-        const { copyCliSource, copyCliDependencies } = await import('../src/installer/core.js');
-        const { writeFileSync } = await import('fs');
-        const fwDir = resolveFrameworkDir(targetDir);
-        const frameworkDir = join(targetDir, fwDir);
-        copyCliSource(join(__dirname, '..', 'src'), join(frameworkDir, '_cli'));
-        copyCliDependencies(join(__dirname, '..'), join(frameworkDir, '_cli', 'node_modules'));
-        writeFileSync(
-          join(frameworkDir, '_cli', 'version.json'),
-          JSON.stringify({ version: pkg.version, bundled_at: new Date().toISOString() }, null, 2),
-        );
-        console.log('  CLI re-bundled.');
-      } catch (err) {
-        console.log(`  CLI rebundle skipped: ${err.message}`);
-      }
-
-      // 2.6. Detect tracked framework files and warn user (non-blocking)
-      try {
-        const { detectTrackedFrameworkFiles } = await import('../src/upgrade/tracked-files-detector.js');
-        const { renderTrackedFilesWarning } = await import('../src/upgrade/user-messages.js');
-        const trackedFiles = detectTrackedFrameworkFiles(targetDir);
-        if (trackedFiles.length > 0) {
-          process.stdout.write(renderTrackedFilesWarning(trackedFiles));
-        }
-      } catch {
-        // Non-critical — skip silently if git is unavailable
-      }
-
-      // 3. Validate
-      console.log('  Validating...');
-      const validation = await validateInstallation(targetDir);
-      console.log(`  Validation: ${validation.passed}/${validation.total} checks passed.`);
-
-      if (validation.passed < validation.total) {
-        console.log('  Some validation checks failed. Installation may need manual review.');
+        const { upgradeProject } = await import('../src/upgrade/upgrade.js');
+        const result = await upgradeProject(targetDir, { targetVersion, offline: args.includes('--offline') });
+        console.log(`Validation: ${result.validation.passed}/${result.validation.total} checks passed.`);
+        console.log(`Previous generation retained at: ${result.backupDir}`);
+        console.log(`Chati.dev upgraded to v${result.version} successfully.`);
+      } catch (error) {
+        console.error(`${error.code || 'UPGRADE_FAILED'}: ${error.message}`);
+        process.exitCode = 1;
       }
-
-      // 4. Update config.yaml with new version
-      updateConfigVersion(targetDir, targetVersion);
-
-      console.log();
-      console.log(`Chati.dev upgraded to v${targetVersion} successfully.`);
       break;
     }
 
@@ -751,6 +766,19 @@ Orchestration:
   npx chati-dev orchestrate deviation --type rollback --target X  Analyze deviation
   npx chati-dev orchestrate exit                   Save and exit session
 
+RAIL evidence authority:
+  npx chati-dev rail-verify --handoff-id ID --attempt-id ID [--project-dir PATH]
+  npx chati-dev rail-effort --handoff-id ID --attempt-id ID [--project-dir PATH]
+  npx chati-dev rail-browser-artifact --ref REF [--project-dir PATH]
+  npx chati-dev rail-browser-prune [--project-dir PATH]
+                                                    Observe approved checks on the canonical result
+  npx chati-dev rail-authority-request --kind rail-evidence|clickup-mcp [--project-dir PATH]
+                                                    Create a public certification request
+  npx chati-dev rail-authority-enroll --certificate FILE [--project-dir PATH]
+                                                    Enroll a CHATI-signed public certificate
+  npx chati-dev rail-authority-enroll --certificate FILE --replace
+                                                    Explicitly rotate the enrolled certificate
+
 Intelligence:
   npx chati-dev memory [stats|list|search|clean]  Memory management
   npx chati-dev context                            Context bracket status
@@ -918,9 +946,9 @@ Telemetry:
         console.error('orchestrate subcommands accept only --flag arguments. To set the project name, use --name "<name>".');
         process.exit(1);
       }
-      // targetDir for orchestrate is ALWAYS cwd (or auto-resolved by handleInit)
+      // Honor the same explicit project directory as the other public commands.
       const { runOrchestrate } = await import('../src/orchestrator/cli.js');
-      await runOrchestrate(subCommand, args.slice(1), process.cwd());
+      await runOrchestrate(subCommand, args.slice(1), targetDir);
       break;
     }
 
@@ -933,6 +961,6 @@ Telemetry:
 }
 
 main().catch(err => {
-  console.error('Fatal error:', err.message);
+  console.error('Fatal error:', err.code ? `${err.code}: ${err.message}` : err.message);
   process.exit(1);
 });

package/framework/agents/build/dev.md

@@ -892,7 +892,7 @@ and proceed directly to handoff.
 ---
 
 ### Handoff (Protocol 5.5)
-Save to: `artifacts/handoffs/dev-handoff.md`
+Save to: `artifacts/handoffs/dev/dev-handoff.md`
 
 When ALL tasks in current phase are complete AND user confirmed preview:
 - Transition to QA-Implementation
@@ -1002,13 +1002,13 @@ This agent supports TASK-LEVEL parallelization (all modes):
 ### Receives
 - **From**: QA-Planning agent (BUILD phase transition)
 - **Artifact**: `artifacts/7-QA-Planning/qa-planning-report.md` (APPROVED status required)
-- **Handoff file**: `artifacts/handoffs/qa-planning-handoff.md`
+- **Handoff file**: `artifacts/handoffs/qa-planning/qa-planning-handoff.md`
 - **Expected content**: Validation result (APPROVED), traceability summary, adversarial review findings, state transition to BUILD
 
 ### Sends
 - **To**: QA-Implementation agent
 - **Artifact**: Implementation code + `artifacts/8-Implementation/dev-summary.md`
-- **Handoff file**: `artifacts/handoffs/dev-handoff.md`
+- **Handoff file**: `artifacts/handoffs/dev/dev-handoff.md`
 - **Handoff content**: Implementation summary, per-task completion status, per-task scores, commit hashes, blocker resolutions, self-critique findings, duration per task, total tasks completed vs planned
 
 ---
@@ -1149,7 +1149,7 @@ The dev preview step still runs after ALL tasks complete. QA-Implementation's fi
 **Mandatory Handoff:**
 
 When you receive a CLEANUP WAVE or when the orchestrator tells you this is the LAST wave:
-you MUST write your handoff to `artifacts/handoffs/dev-handoff.md` before returning.
+you MUST write your handoff to `artifacts/handoffs/dev/dev-handoff.md` before returning.
 
 The handoff must include:
 - All tasks completed with scores

package/framework/agents/deploy/devops.md

@@ -140,7 +140,7 @@ Validation:
 
 ### Step 5: Finalize
 ```
-1. Complete your handoff document (artifacts/handoffs/devops-handoff.md) with final state.
+1. Complete your handoff document (artifacts/handoffs/devops/devops-handoff.md) with final state.
    Do NOT edit session.yaml directly — the mode-governance hook blocks this.
    The CLI records completion in canonical state when you run:
      node chati.dev/orchestrator/chati-router.js advance --agent devops --score <N>
@@ -362,13 +362,13 @@ Rules:
 ### Receives
 - **From**: QA-Implementation agent (DEPLOY phase transition)
 - **Artifact**: `artifacts/9-QA-Implementation/qa-implementation-report.md` (APPROVED status required)
-- **Handoff file**: `artifacts/handoffs/qa-implementation-handoff.md`
+- **Handoff file**: `artifacts/handoffs/qa-implementation/qa-implementation-handoff.md`
 - **Expected content**: Validation result (APPROVED), weighted score, test results, security scan summary, code review findings, state transition to DEPLOY
 
 ### Sends
 - **To**: None (final agent in pipeline)
 - **Artifact**: `artifacts/10-Deploy/deploy-report.md`
-- **Handoff file**: `artifacts/handoffs/devops-handoff.md`
+- **Handoff file**: `artifacts/handoffs/devops/devops-handoff.md`
 - **Handoff content**: Deployment result (DEPLOYED/FAILED/ROLLED BACK), deployment URL, git summary (branch, commits, PR URL), build results, security pre-deploy check results, documentation generated, session finalization status
 
 ---

package/framework/agents/discover/brief.md

@@ -129,6 +129,16 @@ Output: Raw, unfiltered user input captured (initial_context + any follow-up ans
 
 ### Visual Quality Signal (MANDATORY - ask in Phase 1)
 
+First establish whether the product has a user-facing visual/rendering surface.
+For an explicitly confirmed library/service-only scope with no visual surface,
+do not invent a visual preference: record `visual_quality: not_applicable` in
+the canonical `## Visual Quality` YAML block and `visual_references: []` in
+`## Visual References`, with the no-visual-surface rationale in
+`reference_synthesis`. Keep exactly one declaration of each field. This is an
+upstream scope decision for council review, not a UX self-exemption or a passed
+browser gate. Missing or ambiguous scope is not N/A. Visual requirements,
+premium references or non-empty visual references conflict with N/A.
+
 Ask the user: "What level of visual experience are you looking for?"
 
 1. **Functional** - Clean, professional, focus on usability. Minimal animations.
@@ -140,7 +150,9 @@ Record the answer in the Brief output under a new `visual_quality` field:
 visual_quality: premium  # functional | premium | showcase
 ```
 
-If the user doesn't express a preference, DEFAULT to **premium**.
+For a product with a visual surface, if the user doesn't express a preference,
+DEFAULT to **premium**. This default never creates a visual surface in an
+explicitly non-visual product.
 This field flows downstream to Architect (animation tech stack), UX (motion system scope), and QA-Planning (validation).
 
 ### Visual Reference Analysis (MANDATORY when user provides reference URLs)
@@ -441,7 +453,7 @@ If no visual_references exist in the brief: skip all 3 steps, proceed to handoff
 **IMPORTANT:** Do NOT present completion options before the Visualizer returns. The user must see the complete brief (text + visual analysis) before approving.
 
 ### Handoff (Protocol 5.5)
-Save to: `artifacts/handoffs/brief-handoff.md`
+Save to: `artifacts/handoffs/brief/brief-handoff.md`
 
 - **Layer 1**: Problem summary, key decisions, artifacts, critical context for Detail/Architect
 - **Layer 2**: Only if conflicting stakeholder needs or complex problem landscape discovered
@@ -455,7 +467,7 @@ agents:
     criteria_count: 9
     completed_at: "{timestamp}"
 next_parallel_group: [detail, architect, ux, qa-planning]  # PARALLEL GROUP - see Transition Logic 4.5
-last_handoff: artifacts/handoffs/brief-handoff.md
+last_handoff: artifacts/handoffs/brief/brief-handoff.md
 ```
 
 ---
@@ -561,7 +573,7 @@ domains:
     - global.yaml
     - rules/human-writing-style.md
     - agents/brief.yaml
-    - artifacts/handoffs/greenfield-wu-handoff.md  # or brownfield-wu-handoff.md
+    - artifacts/handoffs/greenfield-wu/greenfield-wu-handoff.md  # or brownfield-wu-handoff.md
 ```
 
 ---
@@ -588,7 +600,7 @@ Input data:
 
 ### Sending (to Detail agent or Architect agent)
 ```
-Handoff file: artifacts/handoffs/brief-handoff.md
+Handoff file: artifacts/handoffs/brief/brief-handoff.md
 Contents:
   - brief.yaml with 5 requirement categories:
     1. Functional requirements (features, capabilities)
@@ -652,7 +664,7 @@ On failure:
 2. Functional and non-functional requirements must be clearly separated
 3. Never assume requirements - always validate with user
 4. Contradictions between categories must be resolved before compilation
-5. User brain dump must be preserved verbatim for traceability
+5. Brain Dump (Raw) is clearly identified quoted original input: preserve it verbatim in its source language for traceability; do not translate or rewrite the original input. All authored summaries and analysis remain English. Both handoff layers, including Summary and Deep Context, must be English. A quote label does not exempt newly authored prose, and the localized terminal envelope is not the Markdown handoff file.
 6. Negative scope is mandatory - explicitly document what will NOT be built
 7. Adapt question depth to user level (vibecoder = guided, power user = direct)
 8. Maximum 5 interaction rounds before compiling brief draft

package/framework/agents/discover/brownfield-wu.md

@@ -262,7 +262,7 @@ These rules are passed to Dev agent via handoff to prevent convention violations
 ```
 
 ### Handoff (Protocol 5.5)
-Save to: `artifacts/handoffs/brownfield-wu-handoff.md`
+Save to: `artifacts/handoffs/brownfield-wu/brownfield-wu-handoff.md`
 
 - **Layer 1 (Summary)**: Mission completed, key findings, tech stack, critical debt items
 - **Layer 2 (Deep Context)**: Full scout findings, detailed debt inventory, integration complexity
@@ -276,7 +276,7 @@ agents:
     criteria_count: 8
     completed_at: "{timestamp}"
 current_agent: brief
-last_handoff: artifacts/handoffs/brownfield-wu-handoff.md
+last_handoff: artifacts/handoffs/brownfield-wu/brownfield-wu-handoff.md
 ```
 
 ---
@@ -400,7 +400,7 @@ Input data:
 
 ### Sending (to Brief agent)
 ```
-Handoff file: artifacts/handoffs/brownfield-wu-handoff.md
+Handoff file: artifacts/handoffs/brownfield-wu/brownfield-wu-handoff.md
 Contents:
   Layer 1 (Summary):
     - Codebase map (folder structure, file counts, patterns)

package/framework/agents/discover/greenfield-wu.md

@@ -157,7 +157,7 @@ Save to: `artifacts/0-WU/wu-operational-report.md`
 ```
 
 ### Handoff (Protocol 5.5)
-Save to: `artifacts/handoffs/greenfield-wu-handoff.md`
+Save to: `artifacts/handoffs/greenfield-wu/greenfield-wu-handoff.md`
 
 Follow Two-Layer Handoff structure:
 - **Layer 1 (Summary)**: Mission completed, key findings, artifacts, critical context for Brief agent
@@ -177,7 +177,7 @@ agents:
     criteria_count: 7
     completed_at: "{timestamp}"
 current_agent: brief
-last_handoff: artifacts/handoffs/greenfield-wu-handoff.md
+last_handoff: artifacts/handoffs/greenfield-wu/greenfield-wu-handoff.md
 ```
 
 ### Project Context Update
@@ -353,7 +353,7 @@ brand-architect agent confirms the intent via Signal 2.
 
 ### How to write the signal
 Append a `## Scaffold Candidates` section to your handoff file
-(`artifacts/handoffs/greenfield-wu-handoff.md`). The CLI parser
+(`artifacts/handoffs/greenfield-wu/greenfield-wu-handoff.md`). The CLI parser
 (`parseHandoffScaffoldCandidates` in `src/orchestrator/session-manager.js`)
 reads this block on `advance greenfield-wu` and merges the preset ids into
 `session.scaffold_candidates` (idempotent — no duplicate push).
@@ -398,7 +398,7 @@ Input data:
 
 ### Sending (to Brief agent)
 ```
-Handoff file: artifacts/handoffs/greenfield-wu-handoff.md
+Handoff file: artifacts/handoffs/greenfield-wu/greenfield-wu-handoff.md
 Contents:
   - Project type confirmation
   - Tech stack assessment (frameworks, languages, tools)

package/framework/agents/plan/architect.md

@@ -180,12 +180,12 @@ Score = criteria met / 10. Threshold: >= 90% (9/10 minimum).
 ### Receives
 - **From**: Detail agent (greenfield) or Brief agent (brownfield parallel)
 - **Artifacts**: `prd.md`, `brief-report.md`
-- **Handoff**: `artifacts/handoffs/detail-handoff.md` or `brief-handoff.md`
+- **Handoff**: `artifacts/handoffs/detail/detail-handoff.md` or `artifacts/handoffs/brief/brief-handoff.md`
 
 ### Sends
 - **To**: UX agent
 - **Artifacts**: `architecture.md` (10 sections)
-- **Handoff**: `artifacts/handoffs/architect-handoff.md`
+- **Handoff**: `artifacts/handoffs/architect/architect-handoff.md`
 - **Content**: Architecture summary, tech stack overview, API contract summary, data model summary, security posture, self-validation score
 
 ---

package/framework/agents/plan/detail.md

@@ -230,7 +230,7 @@ Use template: `chati.dev/templates/prd-tmpl.yaml` (or brownfield-prd-tmpl.yaml)
 ```
 
 ### Handoff (Protocol 5.5)
-Save to: `artifacts/handoffs/detail-handoff.md`
+Save to: `artifacts/handoffs/detail/detail-handoff.md`
 
 ### Session Update
 ```yaml
@@ -327,7 +327,7 @@ Rules:
 | L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules |
 | L1.5 | `chati.dev/rules/human-writing-style.md` | Anti-AI prose rules for human-facing PRD sections |
 | L2 | `artifacts/1-Brief/brief-report.md` | Problems, desired outcomes, constraints, target users |
-| L3 | `artifacts/handoffs/brief-handoff.md` | Brief agent handoff with decisions and open questions |
+| L3 | `artifacts/handoffs/brief/brief-handoff.md` | Brief agent handoff with decisions and open questions |
 
 **Workflow Awareness**: Use the validated session context in the activation prompt to understand pipeline position and whether the flow is greenfield or brownfield. If that context is missing, return `needs_input`; never inspect the session file directly.
 
@@ -338,13 +338,13 @@ Rules:
 ### Receives
 - **From**: Brief agent
 - **Artifact**: `artifacts/1-Brief/brief-report.md` (brief.yaml format)
-- **Handoff file**: `artifacts/handoffs/brief-handoff.md`
+- **Handoff file**: `artifacts/handoffs/brief/brief-handoff.md`
 - **Expected content**: Validated problem statements, target users, constraints, desired outcomes
 
 ### Sends
 - **To**: Architect agent (greenfield) or UX agent (brownfield)
 - **Artifact**: `artifacts/2-PRD/prd.md`
-- **Handoff file**: `artifacts/handoffs/detail-handoff.md`
+- **Handoff file**: `artifacts/handoffs/detail/detail-handoff.md`
 - **Handoff content**: PRD summary, key decisions made, open questions, self-validation score, traceability matrix summary
 
 ---

package/framework/agents/plan/phases.md

@@ -212,7 +212,7 @@ Save to: `artifacts/5-Phases/phases.md`
 ```
 
 ### Handoff (Protocol 5.5)
-Save to: `artifacts/handoffs/phases-handoff.md`
+Save to: `artifacts/handoffs/phases/phases-handoff.md`
 
 ### Session Update
 ```yaml
@@ -309,13 +309,13 @@ Rules:
 ### Receives
 - **From**: UX agent
 - **Artifact**: `artifacts/4-UX/ux-specification.md` (screen inventory, component complexity)
-- **Handoff file**: `artifacts/handoffs/ux-handoff.md`
+- **Handoff file**: `artifacts/handoffs/ux/ux-handoff.md`
 - **Expected content**: UX specification summary, Design System token overview, screen inventory, accessibility compliance status
 
 ### Sends
 - **To**: Tasks agent
 - **Artifact**: `artifacts/5-Phases/phases.md`
-- **Handoff file**: `artifacts/handoffs/phases-handoff.md`
+- **Handoff file**: `artifacts/handoffs/phases/phases-handoff.md`
 - **Handoff content**: Phase breakdown summary, MVP scope, dependency map, wave structure, timeline estimates, traceability matrix (PRD to Phases), self-validation score
 
 ---