@polymorphism-tech/morph-spec 4.10.5 → 4.10.7

package/src/lib/tasks/task-parser.js

@@ -1,13 +1,104 @@
 /**
- * Task Parser — Shared utilities for reading and syncing task state.
+ * Task Parser — Shared utilities for reading, parsing, and grouping tasks.
  *
- * Extracted from bin/task-manager.cjs so both the task-manager and any
- * future consumers can share the same parsing logic without duplication.
+ * Extracted from bin/task-manager.cjs and dispatch-agents.js so all
+ * consumers share the same parsing logic without duplication.
  */
 
 import { readFile } from 'fs/promises';
+import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 
+// ============================================================================
+// TASK_CATEGORY_TO_GROUP — maps task categories to parallel groups
+// ============================================================================
+
+const TASK_CATEGORY_TO_GROUP = {
+  'domain': 'backend',
+  'domain-bc': 'backend',
+  'infrastructure': 'backend',
+  'application': 'backend',
+  'presentation': 'frontend',
+  'tests': 'tests',
+  'infra': 'infra',
+  'docs': 'docs',
+};
+
+// ============================================================================
+// parseTaskList — structured task parsing with error reporting
+// ============================================================================
+
+/**
+ * Parse tasks.md content into structured task objects with error reporting.
+ *
+ * @param {string} content - Raw tasks.md content
+ * @returns {{ tasks: ParsedTask[], errors: TaskParseError[], groups: Object<string, string[]> }}
+ */
+export function parseTaskList(content) {
+  const tasks = [];
+  const errors = [];
+  const groups = {};
+
+  const taskHeadingRe = /^###\s+(T\d{3,})\s*[—–:\-]\s*(.+)$/gm;
+  const groupRe = /(?:\*\*Group\*\*\s*:\s*`?([a-z-]+)`?|- \*\*Group:\*\*\s*`?([a-z-]+)`?)/i;
+  const categoryRe = /(?:\*\*category\*\*\s*:\s*`?([a-z-]+)`?|category:\s*([a-z-]+))/i;
+
+  let headingMatch;
+  const taskPositions = [];
+
+  while ((headingMatch = taskHeadingRe.exec(content)) !== null) {
+    taskPositions.push({ id: headingMatch[1], title: headingMatch[2].trim(), pos: headingMatch.index });
+  }
+
+  for (let i = 0; i < taskPositions.length; i++) {
+    const { id, title, pos } = taskPositions[i];
+    const end = i + 1 < taskPositions.length ? taskPositions[i + 1].pos : content.length;
+    const block = content.slice(pos, end);
+
+    // Try group field first (v4), fall back to category field (v3)
+    const grpMatch = groupRe.exec(block);
+    const catMatch = categoryRe.exec(block);
+    let group;
+    if (grpMatch) {
+      group = (grpMatch[1] || grpMatch[2]).toLowerCase();
+    } else if (catMatch) {
+      const category = (catMatch[1] || catMatch[2]).toLowerCase();
+      group = TASK_CATEGORY_TO_GROUP[category] || 'backend';
+    } else {
+      group = 'backend';
+    }
+
+    tasks.push({ id, title, group });
+
+    if (!groups[group]) groups[group] = [];
+    groups[group].push(id);
+  }
+
+  return { tasks, errors, groups };
+}
+
+// ============================================================================
+// parseAndGroupTasks — drop-in replacement for dispatch-agents.js
+// ============================================================================
+
+/**
+ * Parse tasks.md and return a map of { parallelGroup -> taskId[] }.
+ * Gracefully returns {} if the file doesn't exist or is unparseable.
+ *
+ * @param {string} tasksPath - Absolute path to tasks.md
+ * @returns {Object<string, string[]>}
+ */
+export function parseAndGroupTasks(tasksPath) {
+  if (!existsSync(tasksPath)) return {};
+
+  try {
+    const content = readFileSync(tasksPath, 'utf8');
+    return parseTaskList(content).groups;
+  } catch {
+    return {};
+  }
+}
+
 // ============================================================================
 // parseTasksMd
 // ============================================================================

package/src/lib/validators/checkpoint-persistence.js

@@ -0,0 +1,39 @@
+/**
+ * Checkpoint Validation Persistence
+ *
+ * Persists checkpoint validation results to disk for traceability.
+ * Each checkpoint writes a JSON file to:
+ *   .morph/features/{feature}/5-implement/validations/checkpoint-{N}.json
+ */
+
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Persist a checkpoint validation result to disk.
+ *
+ * @param {string} projectPath - Project root
+ * @param {string} featureName - Feature name
+ * @param {{ checkpointNum: number, timestamp: string, passed: boolean, validators: Object, summary: string, feature?: string, phase?: string }} result - Validation result
+ * @returns {string} Path to the saved JSON file
+ */
+export function persistCheckpointValidation(projectPath, featureName, result) {
+  const dir = join(projectPath, `.morph/features/${featureName}/5-implement/validations`);
+  mkdirSync(dir, { recursive: true });
+
+  const filename = `checkpoint-${result.checkpointNum}.json`;
+  const filePath = join(dir, filename);
+
+  const output = {
+    checkpointNum: result.checkpointNum,
+    timestamp: result.timestamp || new Date().toISOString(),
+    passed: result.passed,
+    validators: result.validators || {},
+    summary: result.summary || '',
+    feature: result.feature || featureName,
+    phase: result.phase || 'implement',
+  };
+
+  writeFileSync(filePath, JSON.stringify(output, null, 2), 'utf8');
+  return filePath;
+}

package/src/lib/validators/content/content-validator.js

@@ -41,6 +41,14 @@ export function validateSpecContent(specPath) {
   const errors = [];
   const warnings = [];
 
+  // Missing sections are warnings, not errors — not every spec needs all sections
+  // (e.g., frontend-only features may not have Data Model, CLI tools may not have Technical Architecture)
+  if (missing.length > 0) {
+    missing.forEach(section => {
+      warnings.push(`Missing recommended section: ${section}`);
+    });
+  }
+
   // Check minimum content length
   if (content.length < 500) {
     warnings.push('Spec seems very short (< 500 characters). Consider adding more detail.');
@@ -70,7 +78,7 @@ export function validateSpecContent(specPath) {
   }
 
   return {
-    valid: missing.length === 0 && errors.length === 0,
+    valid: errors.length === 0,
     missing,
     errors,
     warnings,

package/src/lib/validators/spec-validator.js

@@ -75,9 +75,9 @@ function validateSpecMd(content) {
   for (const section of requiredSections) {
     if (!section.pattern.test(content)) {
       issues.push({
-        level: 'error',
+        level: 'warning',
         type: 'spec',
-        message: `Missing required section: "${section.name}"`,
+        message: `Missing recommended section: "${section.name}"`,
         solution: `Add ## ${section.name} section to spec.md`
       });
     }

package/src/lib/validators/validation-runner.js

@@ -20,6 +20,15 @@ const DOTNET_ONLY_VALIDATORS = new Set([
   'blazor-state', 'contract-compliance'
 ]);
 
+/**
+ * Heavy validators skipped in 'light' mode (checkpoint-only).
+ * Light mode runs only spec, content, and stack-specific lightweight validators.
+ */
+const HEAVY_VALIDATORS = new Set([
+  'architecture', 'packages', 'contract-compliance',
+  'blazor-concurrency', 'css', 'design-system'
+]);
+
 /**
  * Load agent → validators map from agents.json (data-driven)
  * @param {string} projectPath - Root path of the project
@@ -74,6 +83,17 @@ export async function runValidation(projectPath, featureName, options = {}) {
   // Determine which validators to run
   const validatorIds = options.validators || detectValidators(featureName, projectPath);
 
+  // Filter by mode: 'light' skips heavy validators, 'full' (default) runs all
+  const mode = options.mode || 'full';
+  if (mode === 'light') {
+    const beforeCount = validatorIds.length;
+    for (let i = validatorIds.length - 1; i >= 0; i--) {
+      if (HEAVY_VALIDATORS.has(validatorIds[i])) {
+        validatorIds.splice(i, 1);
+      }
+    }
+  }
+
   // Merge constraint-enabled validators
   validatorIds.push(...constraints.enabledValidators);
 

package/src/scripts/setup-infra.js

@@ -27,7 +27,7 @@ import {
 import { parseStacks, getProjectTags, shouldInstall } from '../lib/stack-filter.js';
 import { injectMorphImport } from '../utils/claude-md-injector.js';
 import { saveProjectMorphVersion, getInstalledCLIVersion } from '../utils/version-checker.js';
-import { installClaudeHooks, installGlobalStatusline, installVSCodeTerminalSettings, installShellIntegration } from '../utils/claude-settings-manager.js';
+import { installClaudeHooks, installGlobalStatusline } from '../utils/claude-settings-manager.js';
 import { installSkills } from '../utils/skills-installer.js';
 import { installAgents, installDomainAgents } from '../utils/agents-installer.js';
 
@@ -238,22 +238,6 @@ export async function setupInfra(targetPath, { _exec = execSync } = {}) {
   log('Step 16: Installing Claude Code hooks...');
   await installClaudeHooks(targetPath);
 
-  // --- 16a. installShellIntegration (non-critical) ---
-  log('Step 16a: Installing shell integration...');
-  try {
-    await installShellIntegration();
-  } catch {
-    // Non-critical — shell profile may not be writable
-  }
-
-  // --- 16b. installVSCodeTerminalSettings (non-critical) ---
-  log('Step 16b: Configuring VS Code terminal settings...');
-  try {
-    await installVSCodeTerminalSettings();
-  } catch {
-    // Non-critical — VS Code settings may not be present
-  }
-
   // --- 17. saveProjectMorphVersion ---
   log('Step 17: Saving version info...');
   const cliVersion = getInstalledCLIVersion();

package/src/utils/agent-id-mapper.js

@@ -0,0 +1,11 @@
+/**
+ * Map an agents.json ID to the Claude Code subagent_type.
+ *
+ * @param {string} id - Agent ID from agents.json (e.g., "nextjs-expert")
+ * @param {number} [tier] - Agent tier (1-4). Defaults to non-validator.
+ * @returns {string} subagent_type matching .claude/agents/ filename stem
+ */
+export function agentIdToSubagentType(id, tier) {
+  const prefix = tier === 4 ? 'morph-validator-' : 'morph-';
+  return `${prefix}${id}`;
+}

package/src/utils/agents-installer.js

@@ -8,7 +8,7 @@
  * maxTurns, skills, memory) followed by the agent's spawn prompt as the body.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from 'node:fs';
 import { join } from 'path';
 import { parseStacks, shouldInstall } from '../lib/stack-filter.js';
 
@@ -88,6 +88,13 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     if (allPossible.has(file) && !installed.has(file)) {
       unlinkSync(join(targetDir, file));
     }
+    // Remove morph-domain-{name}.md when morph-{name}.md was installed from agents.json
+    if (file.startsWith('morph-domain-')) {
+      const suffix = file.slice('morph-domain-'.length);
+      if (installed.has(`morph-${suffix}`)) {
+        unlinkSync(join(targetDir, file));
+      }
+    }
   }
 
   return { tier1, tier2, tier3, tier4 };
@@ -170,6 +177,19 @@ function buildDescription(agent) {
   return base.length > 200 ? base.slice(0, 197) + '...' : base;
 }
 
+/**
+ * Serialize an AgentStandard to a readable markdown line.
+ *
+ * @param {string|{id: string, scope?: string, priority?: string}} standard
+ * @returns {string} e.g., "- core-coding (all, required)" or "- core-coding"
+ */
+export function formatStandardRef(standard) {
+  if (typeof standard === 'string') return `- ${standard}`;
+  const id = standard.id || String(standard);
+  const parts = [standard.scope, standard.priority].filter(Boolean);
+  return parts.length > 0 ? `- ${id} (${parts.join(', ')})` : `- ${id}`;
+}
+
 function buildBody(agent) {
   const lines = [];
   if (agent.teammate?.spawn_prompt) {
@@ -181,7 +201,7 @@ function buildBody(agent) {
     }
   }
   if (agent.standards?.length) {
-    lines.push(`\n## Standards to Reference\n${agent.standards.map(s => `- ${s}`).join('\n')}`);
+    lines.push(`\n## Standards to Reference\n${agent.standards.map(formatStandardRef).join('\n')}`);
   }
   return lines.join('\n');
 }
@@ -270,11 +290,19 @@ export async function installDomainAgents(projectDir, frameworkDir = 'framework'
       '',
     ].join('\n');
 
-    const filename = `morph-domain-${name}.md`;
-    const targetPath = join(targetDir, filename);
-    writeFileSync(targetPath, `---\n${frontmatter}---\n\n${body.trimStart()}`, 'utf-8');
-    installed.add(filename);
-    specialists++;
+    // If agents.json already generated morph-{name}.md, append domain content there
+    const agentsJsonFile = `morph-${name}.md`;
+    const agentsJsonPath = join(targetDir, agentsJsonFile);
+    if (existsSync(agentsJsonPath)) {
+      appendFileSync(agentsJsonPath, `\n\n---\n\n## Domain Knowledge\n\n${body.trimStart()}`, 'utf-8');
+      specialists++;
+    } else {
+      const filename = `morph-domain-${name}.md`;
+      const targetPath = join(targetDir, filename);
+      writeFileSync(targetPath, `---\n${frontmatter}---\n\n${body.trimStart()}`, 'utf-8');
+      installed.add(filename);
+      specialists++;
+    }
   }
 
   // Cleanup orphan morph-domain-* files
@@ -333,7 +361,7 @@ export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
     }
   }
 
-  // Check domain agents
+  // Check domain agents (skip if merged into agents.json entry)
   const domainsDir = join(frameworkDir, 'agents');
   if (existsSync(domainsDir)) {
     for (const filePath of collectSkillFiles(domainsDir)) {
@@ -342,6 +370,10 @@ export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
       if (!name) continue;
       if (!shouldInstall(stacks, projectTags)) continue;
 
+      // If agents.json has morph-{name}.md, domain content is merged there
+      const agentsJsonFile = `morph-${name}.md`;
+      if (installedFiles.has(agentsJsonFile)) continue;
+
       expected++;
       const filename = `morph-domain-${name}.md`;
       if (!installedFiles.has(filename)) {

package/src/utils/claude-settings-manager.js

@@ -17,7 +17,7 @@ const MORPH_MANAGED_KEY = '_morph_managed';
 // Re-export from hooks-installer (v2 registry-based)
 // ============================================================================
 
-export { installClaudeHooks, installGlobalStatusline, installVSCodeTerminalSettings, installShellIntegration, getHooksVersion } from './hooks-installer.js';
+export { installClaudeHooks, installGlobalStatusline, getHooksVersion } from './hooks-installer.js';
 export { installAgents } from './agents-installer.js';
 
 // ============================================================================

package/src/utils/hooks-installer.js

@@ -79,10 +79,6 @@ const MORPH_HOOKS = [
         type: 'command',
         command: 'node framework/hooks/claude-code/user-prompt/enrich-prompt.js'
       },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/user-prompt/set-terminal-title.js'
-      }
     ]
   },
 
@@ -416,248 +412,7 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
   return { installed: true, globalDir };
 }
 
-/**
- * Install VS Code terminal settings to enable OSC title sequences.
- *
- * Sets `terminal.integrated.tabs.title` to include `${sequence}` so VS Code
- * renders OSC 0 escape sequences written by the set-terminal-title hook.
- *
- * Idempotent — only writes if the setting is missing or doesn't already
- * include `${sequence}`.
- *
- * @param {string} [homeDirOverride] - Override home directory (for testing)
- * @returns {Promise<{ updated: boolean, path: string|null, alreadySet: boolean }>}
- */
-export async function installVSCodeTerminalSettings(homeDirOverride = null) {
-  const home = homeDirOverride || homedir();
-
-  let settingsPath;
-  if (process.platform === 'win32') {
-    settingsPath = join(home, 'AppData', 'Roaming', 'Code', 'User', 'settings.json');
-  } else if (process.platform === 'darwin') {
-    settingsPath = join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json');
-  } else {
-    settingsPath = join(home, '.config', 'Code', 'User', 'settings.json');
-  }
-
-  if (!existsSync(settingsPath)) {
-    return { updated: false, path: settingsPath, alreadySet: false };
-  }
-
-  let settings;
-  try {
-    settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-  } catch {
-    settings = {};
-  }
-
-  const KEY = 'terminal.integrated.tabs.title';
-  const current = settings[KEY] || '';
-  if (current.includes('${sequence}')) {
-    return { updated: false, path: settingsPath, alreadySet: true };
-  }
 
-  settings[KEY] = '${sequence}${separator}${local}';
-  await writeFile(settingsPath, JSON.stringify(settings, null, 4) + '\n', 'utf-8');
-  return { updated: true, path: settingsPath, alreadySet: false };
-}
-
-/**
- * Install shell integration for Claude Code terminal title.
- *
- * Writes a wrapper function to the user's shell profile that:
- * 1. Starts a background job watching ~/.claude/terminal_title
- * 2. Updates the terminal tab title in real time via Console.Title (PS) / OSC 0 (bash)
- * 3. Resets the title when the `claude` command exits
- *
- * On Windows: installs to PowerShell 5.1 and/or PowerShell 7 profiles.
- * On Linux/macOS: installs to ~/.bashrc and/or ~/.zshrc (if they exist).
- *
- * Idempotent — skips if the integration block is already present.
- *
- * @param {string} [homeDirOverride] - Override home directory (for testing)
- * @returns {Promise<{ installed: string[], skipped: string[], errors: string[] }>}
- */
-export async function installShellIntegration(homeDirOverride = null) {
-  const home = homeDirOverride || homedir();
-  const installed = [];
-  const skipped = [];
-  const errors = [];
-
-  if (process.platform === 'win32') {
-    const profiles = [
-      join(home, 'Documents', 'WindowsPowerShell', 'Microsoft.PowerShell_profile.ps1'),
-      join(home, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1'),
-    ];
-    for (const profilePath of profiles) {
-      try {
-        const result = await _appendShellBlock(profilePath, _buildPowerShellBlock(), _psAlreadyInstalled);
-        if (result === 'installed') installed.push(profilePath);
-        else skipped.push(profilePath);
-      } catch (err) {
-        errors.push(profilePath + ': ' + err.message);
-      }
-    }
-  } else {
-    const bashBlock = _buildBashBlock();
-    for (const profilePath of [join(home, '.bashrc'), join(home, '.zshrc')]) {
-      if (!existsSync(profilePath)) continue;
-      try {
-        const result = await _appendShellBlock(profilePath, bashBlock, _bashAlreadyInstalled);
-        if (result === 'installed') installed.push(profilePath);
-        else skipped.push(profilePath);
-      } catch (err) {
-        errors.push(profilePath + ': ' + err.message);
-      }
-    }
-  }
-
-  return { installed, skipped, errors };
-}
-
-/** @returns {string} PowerShell integration block */
-function _buildPowerShellBlock() {
-  return [
-    '',
-    '# === Claude Code terminal title integration (morph-spec) ===',
-    '# Per-session title file prevents cross-session title contamination.',
-    '$script:_claudeExe = Get-Command claude -CommandType Application -ErrorAction SilentlyContinue |',
-    '    Select-Object -First 1 -ExpandProperty Source',
-    '',
-    'function _Start-ClaudeTitleWatcher {',
-    '    param([string]$TitleFile)',
-    '    $rs = [runspacefactory]::CreateRunspace()',
-    '    $rs.Open()',
-    '    $ps = [powershell]::Create()',
-    '    $ps.Runspace = $rs',
-    '    [void]$ps.AddScript({',
-    '        param($f)',
-    '        $last = ""',
-    '        while ($true) {',
-    '            if (Test-Path $f) {',
-    '                try {',
-    '                    $t = (Get-Content $f -Raw -ErrorAction Stop).Trim()',
-    '                    if ($t -and $t -ne $last) {',
-    '                        [Console]::Title = $t',
-    '                        $last = $t',
-    '                    }',
-    '                } catch {}',
-    '            }',
-    '            Start-Sleep -Milliseconds 500',
-    '        }',
-    '    }).AddArgument($TitleFile)',
-    '    $ps.BeginInvoke() | Out-Null',
-    '    return $ps',
-    '}',
-    '',
-    'function Invoke-Claude {',
-    '    [CmdletBinding()]',
-    '    param([Parameter(ValueFromRemainingArguments=$true)][string[]]$Arguments)',
-    '    if (-not $script:_claudeExe) { Write-Error "claude executable not found in PATH"; return }',
-    '    # Per-session file: each Invoke-Claude gets its own title file so multiple',
-    '    # open terminals don\'t overwrite each other\'s titles.',
-    '    $sessionTitleFile = Join-Path $HOME ".claude\\terminal_title_$(New-Guid)"',
-    '    $env:MORPH_TERMINAL_TITLE_FILE = $sessionTitleFile',
-    '    $watcher = _Start-ClaudeTitleWatcher -TitleFile $sessionTitleFile',
-    '    try {',
-    '        & $script:_claudeExe @Arguments',
-    '    } finally {',
-    '        try { $watcher.Stop(); $watcher.Dispose() } catch {}',
-    '        $env:MORPH_TERMINAL_TITLE_FILE = $null',
-    '        Remove-Item $sessionTitleFile -ErrorAction SilentlyContinue',
-    '        [Console]::Title = "PowerShell"',
-    '    }',
-    '}',
-    'Set-Alias -Name claude -Value Invoke-Claude -Force',
-    '# === End Claude Code terminal title integration (morph-spec) ===',
-  ].join('\n');
-}
-
-/** @returns {string} Bash/Zsh integration block */
-function _buildBashBlock() {
-  return [
-    '',
-    '# === Claude Code terminal title integration (morph-spec) ===',
-    '# Per-session title file prevents cross-session title contamination.',
-    '_claude_title_watcher() {',
-    '  local title_file="$1"',
-    '  local last_title=""',
-    '  while true; do',
-    '    if [ -f "$title_file" ]; then',
-    '      local current',
-    '      current=$(cat "$title_file" 2>/dev/null)',
-    '      if [ -n "$current" ] && [ "$current" != "$last_title" ]; then',
-    "        printf '\\e]0;%s\\a' \"$current\"",
-    '        last_title="$current"',
-    '      fi',
-    '    fi',
-    '    sleep 0.5',
-    '  done',
-    '}',
-    '',
-    'claude() {',
-    '  # Per-session file: each invocation gets its own title file so multiple',
-    '  # open terminals don\'t overwrite each other\'s titles.',
-    '  local SESSION_TITLE_FILE',
-    '  SESSION_TITLE_FILE="$HOME/.claude/terminal_title_$$_$RANDOM"',
-    '  export MORPH_TERMINAL_TITLE_FILE="$SESSION_TITLE_FILE"',
-    '  _claude_title_watcher "$SESSION_TITLE_FILE" &',
-    '  local WATCHER_PID=$!',
-    '  command claude "$@"',
-    '  local EXIT_CODE=$?',
-    '  kill "$WATCHER_PID" 2>/dev/null',
-    '  wait "$WATCHER_PID" 2>/dev/null',
-    '  unset MORPH_TERMINAL_TITLE_FILE',
-    '  rm -f "$SESSION_TITLE_FILE"',
-    "  printf '\\e]0;claude\\a'",
-    '  return $EXIT_CODE',
-    '}',
-    '# === End Claude Code terminal title integration (morph-spec) ===',
-  ].join('\n');
-}
-
-/** Check if PowerShell profile already has the integration */
-function _psAlreadyInstalled(content) {
-  return content.includes('Invoke-Claude') || content.includes('_Start-ClaudeTitleWatcher');
-}
-
-/** Check if bash/zsh profile already has the integration */
-function _bashAlreadyInstalled(content) {
-  return content.includes('_claude_title_watcher') || content.includes('command claude "$@"');
-}
-
-/**
- * Append a shell block to a profile file if not already present.
- * Creates the file (and parent dirs) if it doesn't exist.
- * @param {string} profilePath
- * @param {string} block
- * @param {(content: string) => boolean} isInstalled
- * @returns {Promise<'installed'|'skipped'>}
- */
-async function _appendShellBlock(profilePath, block, isInstalled) {
-  let existing = '';
-  let isUtf16le = false;
-
-  if (existsSync(profilePath)) {
-    const raw = await readFile(profilePath);
-    // Detect UTF-16LE: starts with FF FE BOM or has null bytes in the first bytes
-    isUtf16le = (raw[0] === 0xFF && raw[1] === 0xFE) ||
-                (raw.length >= 4 && raw[1] === 0 && raw[3] === 0);
-    existing = isUtf16le ? raw.toString('utf16le').replace(/^\uFEFF/, '') : raw.toString('utf-8');
-  }
-
-  if (isInstalled(existing)) return 'skipped';
-
-  const dir = dirname(profilePath);
-  if (!existsSync(dir)) {
-    await mkdir(dir, { recursive: true });
-  }
-
-  // Always write as UTF-8; trim trailing whitespace from UTF-16LE-decoded content
-  const base = isUtf16le ? existing.trimEnd() + '\n' : existing;
-  await writeFile(profilePath, base + block + '\n', 'utf-8');
-  return 'installed';
-}
 
 /**
  * Remove old v1 agent-teams/dispatch.js hook entries.

package/src/utils/tier-helpers.js

@@ -0,0 +1,24 @@
+/**
+ * Tier-to-role helpers for agents.json v4.0
+ *
+ * Derives role strings from tier numbers, eliminating the need
+ * for an explicit `role` field on each agent.
+ *
+ * @module tier-helpers
+ */
+
+const TIER_ROLES = {
+  1: 'orchestrator',
+  2: 'leader',
+  3: 'specialist',
+  4: 'validator',
+};
+
+/**
+ * Derive role string from agent tier number.
+ * @param {number} tier - Agent tier (1-4)
+ * @returns {string} Role name
+ */
+export function tierToRole(tier) {
+  return TIER_ROLES[tier] || 'specialist';
+}