agentic-workflow-manager 8.2.1 → 8.4.0

package/dist/src/commands/doctor.js

@@ -15,6 +15,10 @@ const paths_1 = require("../core/paths");
 // read-only y el segundo auto-vivifica el archivo. Ver la nota en config.ts.
 const config_1 = require("../utils/config");
 const agent_targets_1 = require("../core/agent-targets");
+const collect_1 = require("../core/dashboard/collect");
+const render_html_1 = require("../core/dashboard/render-html");
+const render_terminal_1 = require("../core/dashboard/render-terminal");
+const write_html_1 = require("../core/dashboard/write-html");
 function glyph(status) {
     if (status === 'ok')
         return picocolors_1.default.green('✔');
@@ -123,6 +127,38 @@ function renderProviderReport(report) {
 }
 function runDoctor(opts = {}) {
     const resolveTargets = opts.resolveTargets ?? agent_targets_1.resolveAgentTargets;
+    const invalid = (message) => { process.stderr.write(`awm doctor: ${message}\n`); return 2; };
+    const htmlRequested = opts.html !== undefined;
+    if (opts.json && opts.full)
+        return invalid('--json cannot be combined with --full');
+    if (opts.json && htmlRequested)
+        return invalid('--json cannot be combined with --html');
+    if (opts.full && htmlRequested)
+        return invalid('--full cannot be combined with --html');
+    if (opts.force && !htmlRequested)
+        return invalid('--force requires --html');
+    if (opts.full || htmlRequested) {
+        try {
+            const cwd = opts.cwd ?? process.cwd();
+            const target = htmlRequested ? (0, write_html_1.resolveHtmlTarget)({ cwd, target: opts.html, force: opts.force }) : undefined;
+            const targets = resolveTargets({ prefs: (0, config_1.readPreferences)(), explicit: opts.agent });
+            const collectSnapshot = opts.collectSnapshot ?? collect_1.collectDashboardSnapshot;
+            const context = (0, context_1.gatherContext)({ cwd, agents: targets });
+            const snapshot = collectSnapshot({ cwd, now: new Date().toISOString(), adapters: {
+                    ...(0, collect_1.productionDashboardAdapters)(context),
+                } });
+            if (opts.full)
+                process.stdout.write((0, render_terminal_1.renderFullTerminal)(snapshot) + '\n');
+            if (htmlRequested) {
+                (0, write_html_1.writeHtmlAtomically)({ cwd, target: target, html: (0, render_html_1.renderDashboardHtml)(snapshot), force: opts.force });
+                process.stdout.write(`${target}\n`);
+            }
+            return snapshot.overall === 'healthy' ? 0 : 1;
+        }
+        catch (error) {
+            return invalid(error.message);
+        }
+    }
     // Validates --agent separately from the general diagnostic gathering below:
     // an unknown or disabled agent is a normal input-validation failure (the
     // user typo'd or forgot `awm init --agent <x>`), not an "internal error" —
@@ -159,8 +195,11 @@ function registerDoctorCommand(program) {
     program.command('doctor')
         .description('Read-only dashboard of the AWM harness state, per provider')
         .option('--json', 'Emit the diagnostic report as JSON')
+        .option('--full', 'Emit the full dashboard snapshot')
+        .option('--html [file]', 'Write the dashboard snapshot as HTML')
+        .option('--force', 'Allow replacing an existing HTML file')
         .option('-a, --agent <agent>', 'Target agent subset (comma-separated); defaults to every enabled agent')
         .action((options) => {
-        process.exitCode = runDoctor({ json: options.json, agent: options.agent });
+        process.exitCode = runDoctor({ json: options.json, full: options.full, html: typeof options.html === 'string' ? options.html : options.html === true ? '' : undefined, force: options.force, agent: options.agent });
     });
 }

package/dist/src/commands/hooks/claude.js

@@ -19,6 +19,43 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const providers_1 = require("../../providers");
 const shared_1 = require("./shared");
+const provider_1 = require("../../core/context/provider");
+const orchestrators_1 = require("../../core/orchestrators");
+/**
+ * Materializa el payload compuesto (using-awm + orquestadores declarados) en `skillDest`.
+ *
+ * Antes `using-awm.md` era un symlink al SKILL.md crudo del registry: todo lo que
+ * `buildContext` compone (declared orchestrators — Tasks 1-4) nunca llegaba a Claude
+ * Code, el proveedor PRINCIPAL que este framework existe para servir. Se escribe el
+ * archivo en vez de enlazarlo porque el contenido ya no es un archivo del registry sino
+ * un derivado suyo — igual que `materialize()` hace para los demas proveedores
+ * (core/context/materializer.ts), solo que aca el destino es el propio scriptsDir del
+ * hook en vez del awm-context.md generico.
+ *
+ * Usada por `installClaudeHook` Y por `resyncClaudeHookFiles` — con proposito: si solo
+ * una de las dos escribiera el payload materializado, la otra seguiria symlinkeando al
+ * SKILL.md crudo y el siguiente `awm update` reabriria el mismo bypass que esto cierra.
+ *
+ * Escritura atomica via write-then-rename (post-implementation-qa Finding 1, TOCTOU):
+ * el patron previo (`unlinkSync` seguido de `writeFileSync`) dejaba una ventana entre
+ * ambas llamadas donde un symlink recreado en `skillDest` seria seguido por
+ * `writeFileSync` (que no usa `O_EXCL`), escribiendo a traves de el sobre lo que sea
+ * que apunte. Escribir a un temporal unico en el MISMO directorio (para que el rename
+ * quede en el mismo filesystem y sea atomico) y luego `renameSync` al destino evita eso
+ * por completo: el rename reemplaza la entrada de directorio de forma atomica sin
+ * dereferenciar un symlink preexistente en el destino, y sin ventana entre borrar y
+ * escribir — no hace falta unlink previo, el rename ya sobrescribe en un solo paso.
+ */
+function writeMaterializedSkill(skillDest, registryRoot) {
+    const ctx = (0, provider_1.buildContext)({
+        registryRoot,
+        profileExtensions: [],
+        declaredOrchestrators: (0, orchestrators_1.collectAndWarn)(),
+    });
+    const tmpPath = path_1.default.join(path_1.default.dirname(skillDest), `.using-awm.md.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fs_1.default.writeFileSync(tmpPath, ctx.markdown, 'utf-8');
+    fs_1.default.renameSync(tmpPath, skillDest);
+}
 function isAwmEntry(entry, scriptsDir, matcher) {
     return (entry?.matcher === matcher &&
         Array.isArray(entry?.hooks) &&
@@ -39,19 +76,10 @@ function installClaudeHook(options) {
     fs_1.default.mkdirSync(config.scriptsDir, { recursive: true });
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'session-start'), path_1.default.join(config.scriptsDir, 'session-start'), options.installMethod);
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'run-hook.cmd'), path_1.default.join(config.scriptsDir, 'run-hook.cmd'), options.installMethod);
-    // 3. Link the skill (default: symlink so 'awm update' propagates; fall back to copy if symlink is unavailable, e.g. Windows without Developer Mode)
+    // 3. Materializar el payload compuesto (using-awm + orquestadores declarados) — ver
+    //    writeMaterializedSkill arriba para por que esto ya no es un symlink al SKILL.md crudo.
     const skillDest = path_1.default.join(config.scriptsDir, 'using-awm.md');
-    try {
-        fs_1.default.unlinkSync(skillDest);
-    }
-    catch { /* not exists */ }
-    try {
-        fs_1.default.symlinkSync(sourceSkill, skillDest, 'file'); // ver shared.ts: el tipo no se infiere
-    }
-    catch {
-        // best-effort: copy the single skill file; 'awm update' will not auto-propagate
-        fs_1.default.copyFileSync(sourceSkill, skillDest);
-    }
+    writeMaterializedSkill(skillDest, options.registryRoot);
     // 4. Backup settings if it exists
     const backupPath = (0, shared_1.backupManagedFile)(config.settingsPath);
     // 5. Read or initialize settings
@@ -178,29 +206,17 @@ function uninstallClaudeHook(agent) {
 /** Refresh the Claude hook's script/skill files in place (used by resync). Assumes the caller has verified the settings entry is already present. */
 function resyncClaudeHookFiles(config, registryRoot, method) {
     const sourceHooks = path_1.default.join(registryRoot, 'hooks');
-    const sourceSkill = path_1.default.join(registryRoot, 'skills/using-awm/SKILL.md');
     fs_1.default.mkdirSync(config.scriptsDir, { recursive: true });
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'session-start'), path_1.default.join(config.scriptsDir, 'session-start'), method);
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'run-hook.cmd'), path_1.default.join(config.scriptsDir, 'run-hook.cmd'), method);
+    // Re-materializar el payload compuesto igual que `installClaudeHook` (arriba) — NO
+    // volver a symlinkear al SKILL.md crudo. Antes este era el segundo escritor del mismo
+    // archivo con el symlink-con-fallback-a-copia; si solo `installClaudeHook` se hubiera
+    // arreglado y este no, el primer `awm update` posterior a un install correcto habria
+    // sobreescrito el payload materializado con un symlink crudo de nuevo — reabriendo el
+    // bypass que esto existe para cerrar.
     const skillDest = path_1.default.join(config.scriptsDir, 'using-awm.md');
-    try {
-        fs_1.default.unlinkSync(skillDest);
-    }
-    catch { /* not exists */ }
-    // Mismo fallback a copia que `installClaudeHook` (arriba). Sin el, en
-    // Windows sin Developer Mode este symlink tira EPERM, `resyncInstalledHooks`
-    // propaga el throw y `awm update` devuelve 1 — PARA SIEMPRE: el install
-    // funcionaba (tenia el fallback) y el update no, en una plataforma que la
-    // matriz de soporte declara verificada en CI. Dos escritores del mismo
-    // archivo, solo uno endurecido.
-    try {
-        fs_1.default.symlinkSync(sourceSkill, skillDest, 'file'); // ver shared.ts: el tipo no se infiere
-    }
-    catch {
-        // best-effort: `awm update` no auto-propagara cambios de esta skill,
-        // pero el hook queda funcional en vez de dejar el comando inservible.
-        fs_1.default.copyFileSync(sourceSkill, skillDest);
-    }
+    writeMaterializedSkill(skillDest, registryRoot);
 }
 /** True when the registry has everything needed to resync the Claude hook files. */
 function claudeResyncSourcesExist(registryRoot) {

package/dist/src/commands/hooks/index.js

@@ -58,7 +58,7 @@ function registerHooksCommand(program) {
             console.log(`  Scripts:        ${result.scriptsDir}/session-start`);
             if (agent === 'claude-code') {
                 console.log(`                  ${result.scriptsDir}/run-hook.cmd`);
-                console.log(`                  ${result.scriptsDir}/using-awm.md → ~/.awm/registries/baseline/skills/using-awm/SKILL.md`);
+                console.log(`                  ${result.scriptsDir}/using-awm.md (composed context, written)`);
             }
             console.log('');
             console.log(`  Settings file:  ${result.settingsPath}`);

package/dist/src/commands/hooks/shared.js

@@ -108,7 +108,7 @@ function checkFile(file) {
         return { ok: true, detail: file };
     }
     catch {
-        return { ok: false, detail: `broken link: ${file}` };
+        return { ok: false, detail: `cannot read file: ${file}` };
     }
 }
 /**

package/dist/src/commands/registry/add.js

@@ -12,6 +12,7 @@ const simple_git_1 = __importDefault(require("simple-git"));
 const registries_1 = require("../../core/registries");
 const discovery_1 = require("../../core/discovery");
 const bundles_1 = require("../../core/bundles");
+const orchestrators_1 = require("../../core/orchestrators");
 function deriveRegistryName(remote) {
     // Split on '/', '\' and ':' — not just '/' and ':'. A git remote URL
     // (https://…/repo.git, git@host:org/repo.git) only ever uses the first
@@ -66,6 +67,10 @@ async function addRegistry(remote, nameOverride) {
         fs_1.default.rmSync(dest, { recursive: true, force: true });
         return { ok: false, name, error: e instanceof Error ? e.message : String(e) };
     }
+    // Una declaracion de orquestador malformada se REPORTA, no aborta: el
+    // registry puede aportar skills utiles aunque su declaracion este rota,
+    // y abortar por eso invalidaria contenido sano (R1.2).
+    const { diagnostics: orchestratorDiagnostics } = (0, orchestrators_1.readDeclaredOrchestrators)(dest);
     (0, registries_1.writeRegistriesConfig)([...existing, { name, remote }]);
-    return { ok: true, name, contentRoot: dest };
+    return { ok: true, name, contentRoot: dest, orchestratorDiagnostics };
 }

package/dist/src/commands/registry/index.js

@@ -38,6 +38,9 @@ function registerRegistryCommand(program) {
             process.exit(1);
         }
         s.stop(`Registry ${picocolors_1.default.cyan(result.name)} added at ${result.contentRoot}`);
+        for (const d of result.orchestratorDiagnostics) {
+            console.warn(picocolors_1.default.yellow(`  ⚠  ${d}`));
+        }
         try {
             (0, regenerate_1.regenerateGlobalContext)();
         }

package/dist/src/core/context/orchestrator.js

@@ -8,6 +8,7 @@ const config_instructions_1 = require("./strategies/config-instructions");
 const codex_agents_1 = require("./strategies/codex-agents");
 const provider_1 = require("./provider");
 const materializer_1 = require("./materializer");
+const orchestrators_1 = require("../orchestrators");
 class InjectionOrchestrator {
     overrides;
     constructor(overrides = {}) {
@@ -41,7 +42,11 @@ class InjectionOrchestrator {
     }
     /** Full input: builds context from registry and materializes to disk. Used by installContext only. */
     inputFor(op) {
-        const ctx = (0, provider_1.buildContext)({ registryRoot: op.registryRoot, profileExtensions: op.profileExtensions });
+        const ctx = (0, provider_1.buildContext)({
+            registryRoot: op.registryRoot,
+            profileExtensions: op.profileExtensions,
+            declaredOrchestrators: (0, orchestrators_1.collectAndWarn)(),
+        });
         const absPath = this.contextPathFor(op);
         const ref = (0, materializer_1.materialize)(ctx, absPath, op.scope);
         return {
@@ -66,7 +71,15 @@ class InjectionOrchestrator {
         const absPath = this.contextPathFor(op);
         let contentHash = '';
         try {
-            const ctx = (0, provider_1.buildContext)({ registryRoot: op.registryRoot, profileExtensions: op.profileExtensions });
+            // Debe recolectar declarados igual que inputFor: si no, el hash "esperado" aqui
+            // diverge del hash realmente materializado por installContext en cuanto algun
+            // registry instalado declare un orquestador, y contextStatus reportaria 'stale'
+            // de forma permanente incluso justo despues de un install correcto.
+            const ctx = (0, provider_1.buildContext)({
+                registryRoot: op.registryRoot,
+                profileExtensions: op.profileExtensions,
+                declaredOrchestrators: (0, orchestrators_1.collectAndWarn)(),
+            });
             contentHash = ctx.contentHash;
         }
         catch (err) {

package/dist/src/core/context/provider.js

@@ -16,6 +16,33 @@ function parseVersion(skill) {
     const m = skill.match(/^version:\s*["']?([^"'\n]+)["']?\s*$/m);
     return m ? m[1].trim() : '0.0.0';
 }
+/**
+ * Neutraliza contenido no confiable proveniente de registries declarados
+ * (name/appliesWhen/terminatesTo) antes de interpolarlo en markdown.
+ * Sin esto, un registry malicioso/comprometido podria inyectar saltos de
+ * linea, marcadores markdown (##, `, *, _) o pseudo-tags XML/HTML (<, >)
+ * para forjar una seccion nueva o un bloque instruccional dentro del
+ * payload de contexto que consume el proveedor de IA — un vector de
+ * prompt-injection. `readDeclaredOrchestrators` solo valida que los
+ * campos sean strings no vacios; el saneo pertenece a esta frontera de
+ * render, no a la validacion de lectura.
+ */
+function sanitizeForMarkdown(s) {
+    return s.replace(/\r?\n/g, ' ').replace(/[`*_#<>]/g, '');
+}
+function renderDeclared(list) {
+    if (list.length === 0)
+        return '';
+    const rows = list
+        .map(o => {
+        const name = sanitizeForMarkdown(o.name);
+        const appliesWhen = sanitizeForMarkdown(o.appliesWhen);
+        const terminatesTo = sanitizeForMarkdown(o.terminatesTo);
+        return `- **${name}** — applies when: ${appliesWhen}. Terminates to: \`${terminatesTo}\`.`;
+    })
+        .join('\n');
+    return `## Declared orchestrators\n\nConsider these before the built-in pair:\n\n${rows}\n\n`;
+}
 function buildContext(input) {
     const skillPath = path_1.default.join(input.registryRoot, 'skills/using-awm/SKILL.md');
     if (!fs_1.default.existsSync(skillPath)) {
@@ -24,6 +51,7 @@ function buildContext(input) {
     const skill = fs_1.default.readFileSync(skillPath, 'utf-8');
     const exts = input.profileExtensions.length ? input.profileExtensions.join(', ') : 'none';
     const header = `<!-- AWM context (generated) -->\n# AWM\n\nActive extensions: ${exts}\n\n`;
-    const markdown = header + skill;
+    const declared = renderDeclared(input.declaredOrchestrators ?? []);
+    const markdown = header + declared + skill;
     return { markdown, sourceVersion: parseVersion(skill), contentHash: sha256(markdown) };
 }

package/dist/src/core/context/regenerate.js

@@ -13,11 +13,28 @@ exports.regenerateGlobalContext = regenerateGlobalContext;
 const fs_1 = __importDefault(require("fs"));
 const providers_1 = require("../../providers");
 const registries_1 = require("../registries");
+const orchestrators_1 = require("../orchestrators");
 const orchestrator_1 = require("./orchestrator");
 function regenerateGlobalContext(targets = [...providers_1.AGENT_TARGETS], orch = new orchestrator_1.InjectionOrchestrator()) {
     const skillsRoot = (0, registries_1.capabilityRoot)('skills');
     if (!skillsRoot)
         return [];
+    // Print each declared-orchestrator diagnostic ONCE up front, rather than letting
+    // every agent's contextStatus/installContext call independently re-collect and
+    // re-warn via InjectionOrchestrator.inputFor/statusInputFor (both call
+    // orchestrators.ts's collectAndWarn() internally, unaware of this outer loop). A
+    // single `awm update` touching N agents (e.g. opencode + codex) would otherwise
+    // print the same diagnostic up to 2x per agent (once from statusInputFor, once
+    // from inputFor when stale) — noisy but not incorrect, since no data is lost or
+    // wrong. This only reduces the printing done BY THIS FUNCTION to one line per
+    // diagnostic; inputFor/statusInputFor still call collectAndWarn() internally per
+    // op (they need the declared list to build/hash context), so a per-agent
+    // duplicate can still print alongside this upfront one. Deeper dedup would mean
+    // threading a pre-collected list through ContextOp/InjectionOrchestrator, which
+    // touches shared collection-scope logic other callers (hooks/claude.ts) rely on —
+    // out of proportion for this minor finding.
+    for (const d of (0, orchestrators_1.collectDeclaredOrchestrators)().diagnostics)
+        console.warn(`warning: ${d}`);
     const out = [];
     for (const agent of targets) {
         const inj = (0, providers_1.providerFor)(agent).injection;
@@ -42,6 +59,18 @@ function regenerateGlobalContext(targets = [...providers_1.AGENT_TARGETS], orch
             if (inj.globalPath === null)
                 continue;
         }
+        else if (inj.type === 'cc-settings-merge') {
+            // Claude Code no pasa por este dispatcher generico: su contexto se
+            // materializa via el hook dedicado (hooks/claude.ts's installClaudeHook/
+            // resyncClaudeHookFiles), invocado por `awm update` a traves de un path
+            // separado (hooks/resync.ts's resyncInstalledHooks). Mismo salteo que
+            // stepContextInjection (init/steps.ts) y contextGlobalCheck
+            // (diagnostics/provider-checks.ts) — "covered by hook". Sin este
+            // continue, orch.contextStatus/installContext corrian igual para
+            // claude-code y escribian un ~/.awm/context/awm-context.md huerfano que
+            // nadie lee (el archivo real vive en el scriptsDir del hook).
+            continue;
+        }
         const op = {
             agent,
             scope: 'global',

package/dist/src/core/dashboard/collect.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REMEDIATION_BY_FINDING_ID = void 0;
+exports.productionDashboardAdapters = productionDashboardAdapters;
+exports.collectDashboardSnapshot = collectDashboardSnapshot;
+const profile_1 = require("../profile");
+const sanitize_1 = require("./sanitize");
+const validate_1 = require("./validate");
+const plan_state_1 = require("./plan-state");
+exports.REMEDIATION_BY_FINDING_ID = {
+    'machine.preferences.missing': 'awm init',
+    'machine.registries.stale': 'awm update',
+    'project.profile.missing': 'awm init',
+    'project.sensors.unavailable': 'awm sensors status',
+    'project.preflight.degraded': 'awm preflight',
+    'planning.source.unavailable': 'awm preflight',
+    'execution.source.unavailable': 'awm sensors status',
+};
+const EMPTY_ADAPTERS = {
+    machine: () => ({ findings: [] }), project: () => ({ findings: [] }), plans: () => [], execution: () => undefined,
+};
+const SAFE_REMEDIATIONS = new Set(['awm init', 'awm update', 'awm sync', 'awm sensors status', 'awm preflight']);
+const HEALTHY_PROVIDER_STATES = new Set(['supported', 'healthy', 'shared', 'delivered']);
+const INAPPLICABLE_PROVIDER_STATES = new Set(['unsupported']);
+function providerState(state) {
+    if (HEALTHY_PROVIDER_STATES.has(state))
+        return 'ok';
+    if (INAPPLICABLE_PROVIDER_STATES.has(state))
+        return 'not_applicable';
+    return 'attention';
+}
+/**
+ * Maps the already-gathered diagnostics matrix into the snapshot's read-only
+ * source seam. It deliberately does not re-read providers, execute sensors, or
+ * relay provider detail/remediation prose: those values can contain local paths,
+ * command output, or credentials. The fixed IDs are derived solely from the
+ * provider/check enums and therefore remain stable across runs.
+ */
+function productionDashboardAdapters(context) {
+    if (!context || typeof context !== 'object' || !Array.isArray(context.providers))
+        throw new Error('productionDashboardAdapters requires gathered provider diagnostics');
+    const machineFindings = context.providers.flatMap((provider) => provider.checks.flatMap((check) => {
+        const finding = {
+            id: `machine.provider.${provider.id}.${check.id}`,
+            // Provider labels are configuration prose. The provider id and check id
+            // are enum-controlled and sufficient for a stable public observation.
+            label: `Provider ${provider.id}: ${check.id}`,
+            state: providerState(check.state),
+            // Provider remediation is intentionally not forwarded. It is free-form
+            // diagnostics text, not a dashboard-approved canonical command.
+            remediationVerified: false,
+        };
+        // These two legacy diagnosis states are the only provider observations
+        // with a pre-existing, exact dashboard command mapping.
+        if (check.id === 'skills.global' && check.state === 'absent') {
+            return [finding, { id: 'machine.preferences.missing', label: 'Preferences', state: 'missing', remediationVerified: true }];
+        }
+        if (check.id === 'skills.global' && check.state === 'stale') {
+            return [finding, { id: 'machine.registries.stale', label: 'Registries', state: 'attention', remediationVerified: true }];
+        }
+        return [finding];
+    }));
+    const project = context.project;
+    const projectFindings = !project ? [] : [
+        { id: project.profile.present ? 'project.profile.present' : 'project.profile.missing', label: 'Profile', state: project.profile.present ? 'ok' : 'missing', remediation: 'awm init', remediationVerified: true },
+        { id: 'project.extensions.configured', label: 'Extensions', state: project.profile.extensions.length > 0 ? 'ok' : 'not_applicable' },
+        { id: 'project.registry-pins.present', label: 'Registry pins', state: project.profile.registries && Object.keys(project.profile.registries).length > 0 ? 'ok' : 'not_applicable' },
+        { id: 'project.bundles.coherent', label: 'Active bundles', state: project.activeBundles.broken.length === 0 ? 'ok' : 'attention', remediation: 'awm sync', remediationVerified: true },
+        { id: 'project.context.present', label: 'Project context', state: project.context.present ? 'ok' : 'missing', remediation: 'awm init', remediationVerified: true },
+        { id: 'project.constitution.present', label: 'Constitution', state: project.constitution.present ? 'ok' : 'missing' },
+        { id: project.sensors.present ? 'project.sensors.present' : 'project.sensors.unavailable', label: 'Sensors', state: project.sensors.present ? 'ok' : 'unavailable', remediation: 'awm sensors status', remediationVerified: true },
+        // `preflight()` is async because static tool inspection is async. Doctor's
+        // synchronous legacy API must not dispatch it here; make the absence of that
+        // observation explicit rather than inventing a readiness verdict.
+        { id: 'project.preflight.not_collected', label: 'Static preflight', state: 'not_applicable' },
+    ];
+    return {
+        machine: () => ({ findings: machineFindings }),
+        project: () => ({ label: 'Project detected', findings: projectFindings }),
+        plans: () => [],
+        execution: () => undefined,
+    };
+}
+function findings(items, optional = false) {
+    if (optional && items === undefined)
+        return [];
+    if (!Array.isArray(items))
+        throw new Error('Dashboard findings must be an array');
+    return items.flatMap((item) => {
+        if (!item || typeof item !== 'object' || typeof item.id !== 'string' || item.id.trim() === '' || typeof item.label !== 'string' || item.label.trim() === '')
+            throw new Error('Dashboard finding is invalid');
+        if (!['ok', 'attention', 'missing', 'unavailable', 'not_applicable'].includes(item.state))
+            throw new Error('Dashboard finding state is invalid');
+        const remediation = exports.REMEDIATION_BY_FINDING_ID[item.id]
+            ?? (item.remediationVerified === true && typeof item.remediation === 'string' && SAFE_REMEDIATIONS.has(item.remediation) ? item.remediation : undefined);
+        if (item.state !== 'ok' && item.state !== 'not_applicable' && !remediation)
+            return [];
+        return [{ id: item.id, label: item.label, state: item.state, ...(item.detail ? { detail: item.detail } : {}), ...(remediation ? { remediation } : {}) }];
+    }).sort((left, right) => left.id.localeCompare(right.id));
+}
+function section(id, availability, items = []) {
+    return { id, availability, items };
+}
+function optional(source) {
+    try {
+        return { value: source(), failed: false, failure: {} };
+    }
+    catch (error) {
+        const findingId = error && typeof error === 'object' && typeof error.findingId === 'string'
+            ? error.findingId : undefined;
+        const remediationVerified = error !== null && typeof error === 'object'
+            ? error.remediationVerified === true : false;
+        return { failed: true, failure: { findingId, remediationVerified } };
+    }
+}
+function canonicalOptionalFailure(failure) {
+    if (!failure.remediationVerified || !failure.findingId || !Object.hasOwn(exports.REMEDIATION_BY_FINDING_ID, failure.findingId))
+        return [];
+    return [{ id: failure.findingId, label: 'Optional source unavailable', state: 'unavailable', remediation: exports.REMEDIATION_BY_FINDING_ID[failure.findingId] }];
+}
+function isolatedFindings(items) {
+    return optional(() => findings(items, true));
+}
+/** Pure read-only aggregation over injected source adapters. */
+function collectDashboardSnapshot(options) {
+    if (!options || typeof options.cwd !== 'string' || options.cwd.length === 0 || typeof options.now !== 'string' || Number.isNaN(Date.parse(options.now)))
+        throw new Error('collectDashboardSnapshot requires cwd and valid now');
+    const adapters = { ...EMPTY_ADAPTERS, ...(options.adapters ?? {}) };
+    const machine = adapters.machine({ cwd: options.cwd });
+    if (!Array.isArray(machine?.findings))
+        throw new Error('Dashboard findings must be an array');
+    const root = (0, profile_1.findProjectRoot)(options.cwd);
+    const machineItems = findings((0, sanitize_1.sanitizeDashboardSource)(machine).findings);
+    const machineSection = section('machine', 'available', machineItems);
+    if (!root) {
+        const degraded = machineSection.items.some((item) => item.state !== 'ok' && item.state !== 'not_applicable');
+        return (0, validate_1.validateDashboardSnapshotV1)({ schema: 1, generatedAt: options.now, overall: degraded ? 'degraded' : 'healthy', project: { detected: false, label: 'No project detected' }, confidence: 'none', sections: [machineSection] });
+    }
+    const projectResult = optional(() => (0, sanitize_1.sanitizeDashboardSource)(adapters.project({ root })));
+    const plansResult = optional(() => (0, sanitize_1.sanitizeDashboardSource)(adapters.plans({ root })));
+    const executionResult = optional(() => {
+        const source = adapters.execution({ root });
+        return source === undefined ? undefined : (0, sanitize_1.sanitizeDashboardSource)(source);
+    });
+    const projectSource = projectResult.value;
+    const execution = executionResult.value;
+    const projectItemsResult = projectSource ? isolatedFindings(projectSource.findings) : { value: [], failed: false, failure: {} };
+    const planItemsResult = plansResult.value ? optional(() => findings(plansResult.value.map((plan) => plan.lifecycle
+        ? { ...plan, detail: (0, plan_state_1.classifyPlanState)(plan.lifecycle) } : plan))) : { value: [], failed: false, failure: {} };
+    const executionItems = isolatedFindings(execution?.execution);
+    const qaItems = isolatedFindings(execution?.qa);
+    const retroItems = isolatedFindings(execution?.retro);
+    const historyItems = isolatedFindings(execution?.history);
+    const executionUnavailable = !executionResult.failed && execution === undefined;
+    const sections = [
+        machineSection,
+        section('project', projectResult.failed || projectItemsResult.failed ? 'unavailable' : 'available', projectResult.failed
+            ? canonicalOptionalFailure(projectResult.failure) : projectItemsResult.failed ? [] : projectItemsResult.value),
+        section('planning', plansResult.failed || planItemsResult.failed ? 'unavailable' : 'available', plansResult.failed
+            ? canonicalOptionalFailure(plansResult.failure) : planItemsResult.failed ? [] : planItemsResult.value),
+        section('execution', executionResult.failed || executionUnavailable || executionItems.failed ? 'unavailable' : 'available', executionResult.failed ? canonicalOptionalFailure(executionResult.failure) : executionUnavailable ? canonicalOptionalFailure({ findingId: 'execution.source.unavailable', remediationVerified: true }) : executionItems.value),
+        // There is no read-only QA, retro, or history adapter in Release A. An
+        // absent execution source is not evidence of a successful empty cycle.
+        section('qa', executionResult.failed || executionUnavailable || qaItems.failed ? 'unavailable' : 'available', qaItems.value),
+        section('retro', executionResult.failed || executionUnavailable || retroItems.failed ? 'unavailable' : 'available', retroItems.value),
+        section('history', executionResult.failed || executionUnavailable || historyItems.failed ? 'unavailable' : 'available', historyItems.value),
+    ];
+    const degraded = sections.some((entry) => entry.availability === 'unavailable' || entry.items.some((item) => item.state !== 'ok' && item.state !== 'not_applicable'));
+    return (0, validate_1.validateDashboardSnapshotV1)({ schema: 1, generatedAt: options.now, overall: degraded ? 'degraded' : 'healthy', project: { detected: true, label: projectSource?.label || 'Project detected' }, confidence: 'provisional', sections });
+}

package/dist/src/core/dashboard/plan-state.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyPlanState = classifyPlanState;
+function assertRecord(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Plan ${label} must be an object`);
+}
+function assertKeys(value, label, keys) {
+    if (Object.keys(value).some((key) => !keys.includes(key)))
+        throw new Error(`Plan ${label} has unsupported fields`);
+}
+function classifyPlanState(input) {
+    assertRecord(input, 'state input');
+    assertKeys(input, 'state input', ['journal', 'markers', 'tasks']);
+    assertRecord(input.markers, 'markers');
+    assertKeys(input.markers, 'markers', ['qaComplete', 'retroComplete']);
+    assertRecord(input.tasks, 'tasks');
+    assertKeys(input.tasks, 'tasks', ['total', 'completed']);
+    const markers = input.markers;
+    const tasks = input.tasks;
+    if (typeof markers.qaComplete !== 'boolean' || typeof markers.retroComplete !== 'boolean')
+        throw new Error('Plan markers must be boolean');
+    if (typeof tasks.total !== 'number' || typeof tasks.completed !== 'number' || !Number.isInteger(tasks.total) || !Number.isInteger(tasks.completed) || tasks.total < 0 || tasks.completed < 0 || tasks.completed > tasks.total)
+        throw new Error('Plan task counts are invalid');
+    let journalState;
+    if (input.journal !== undefined) {
+        assertRecord(input.journal, 'journal');
+        assertKeys(input.journal, 'journal', ['state']);
+        if (input.journal.state !== 'active' && input.journal.state !== 'blocked')
+            throw new Error('Plan journal state is invalid');
+        journalState = input.journal.state;
+    }
+    if (journalState === 'blocked')
+        return 'blocked';
+    if (journalState === 'active')
+        return 'active';
+    if (markers.retroComplete)
+        return 'executed';
+    if (markers.qaComplete)
+        return 'retro_pending';
+    if (tasks.total > 0 && tasks.completed === tasks.total)
+        return 'qa_pending';
+    return 'legacy_unverifiable';
+}