@jaimevalasek/aioson 1.36.0 → 1.37.0

package/src/commands/agents.js

@@ -12,7 +12,8 @@ const {
 const { normalizeInteractionLanguage } = require('../locales');
 const { validateProjectContextFile, getInteractionLanguage } = require('../context');
 const { exists } = require('../utils');
-const { loadOrCreateState, runWorkflowNext } = require('./workflow-next');
+const { AUTOPILOT_HANDOFF_STAGES, loadOrCreateState, runWorkflowNext } = require('./workflow-next');
+const { resolveAutopilotSignal } = require('../autopilot-signal');
 const {
   bootstrapDirectAgentPrompt,
   classifyDirectAgentRuntime
@@ -278,12 +279,27 @@ async function runAgentPrompt({ args, options, logger, t }) {
       manifest,
       requestedMode: promptAgent.id === 'scope-check' && getScopeCheckModeOption(options) ? null : options.mode || null
     });
+    // Direct handoffs carry the autopilot exception too — without it the
+    // injected scope boundary instructs a manual stop and overrides the agent
+    // .md's autopilot section even when the flag/scheme says to chain.
+    let autoHandoff = false;
+    if (AUTOPILOT_HANDOFF_STAGES.has(promptAgent.id)) {
+      try {
+        const signal = await resolveAutopilotSignal(targetDir, {
+          slug: options.feature ? String(options.feature).trim() : null
+        });
+        autoHandoff = signal.enabled;
+      } catch {
+        autoHandoff = false;
+      }
+    }
     prompt = buildAgentPrompt(promptAgent, tool, {
       instructionPath,
       interactionLanguage: locale,
       autonomyMode: effectiveMode,
       capabilitySummary: buildAgentCapabilitySummary(manifest, tool),
-      activationContext
+      activationContext,
+      autoHandoff
     });
     const runtimeClass = classifyDirectAgentRuntime(promptAgent.id);
     const handoffLabel = runtimeClass.source === 'squad_session'

package/src/commands/briefing.js

@@ -14,13 +14,20 @@
  * Format: YAML frontmatter (briefings: array) + Markdown table
  */
 
+const fsp = require('node:fs/promises');
 const path = require('node:path');
 const readline = require('node:readline');
 const {
   configPath: registryConfigPath,
+  markRefinementState,
   readBriefingRegistry,
   writeBriefingRegistry
 } = require('../lib/briefing-refiner/briefing-registry');
+const { hashText, parseBriefingSections } = require('../lib/briefing-refiner/briefing-sections');
+const { assertFeedbackPath, validateFeedback, validateFindingsInput } = require('../lib/briefing-refiner/feedback-schema');
+const { resolveBriefingPath } = require('../lib/briefing-refiner/briefing-paths');
+const { writeReviewArtifacts } = require('../lib/briefing-refiner/review-html');
+const { applyConfirmedFeedback, applyDeclinedFeedback } = require('../lib/briefing-refiner/apply-feedback');
 
 // ─── Interactive prompt helpers ───────────────────────────────────────────────
 
@@ -219,4 +226,333 @@ async function runBriefingUnapprove({ args, options = {}, logger }) {
   return { ok: true, unapproved: names };
 }
 
-module.exports = { runBriefingApprove, runBriefingUnapprove };
+// ─── briefing:review / briefing:apply-feedback ────────────────────────────────
+//
+// The deterministic half of @briefing-refiner: the agent does the intelligent
+// audit (findings), the CLI owns the surface — parse briefings.md, render
+// review.html + refinement-feedback.json + refinement-report.md, and later
+// validate + apply the exported feedback. This kills the per-run hand-written
+// HTML (token cost + schema drift) that used to stand in for these commands.
+
+const USER_EXPORT_METHODS = new Set(['download', 'copy-paste', 'file-system-access']);
+
+/**
+ * Resolve which briefing a refinement command targets. Refinable = `draft`, or
+ * `approved` with no PRD yet (same rule as the @briefing-refiner contract).
+ * Unambiguous cases resolve without --slug; ambiguity is an error (these
+ * commands are agent-driven, so no interactive prompt).
+ */
+async function resolveRefinableSlug(projectDir, slugOpt) {
+  let data;
+  try {
+    data = await readBriefingRegistry(projectDir);
+  } catch (error) {
+    return { ok: false, error: error && error.code === 'invalid_frontmatter' ? 'invalid_frontmatter' : 'no_config' };
+  }
+
+  const refinable = data.briefings.filter(
+    (b) => b.status === 'draft' || (b.status === 'approved' && !b.prd_generated)
+  );
+  const slug = String(slugOpt || '').trim() || null;
+
+  if (slug) {
+    if (!refinable.some((b) => b.slug === slug)) {
+      return { ok: false, error: 'slug_not_refinable', slug, candidates: refinable.map((b) => b.slug) };
+    }
+    return { ok: true, slug };
+  }
+  if (refinable.length === 1) return { ok: true, slug: refinable[0].slug };
+  if (refinable.length === 0) return { ok: false, error: 'no_refinable' };
+  return { ok: false, error: 'ambiguous_slug', candidates: refinable.map((b) => b.slug) };
+}
+
+function logSlugResolutionError(resolved, logger) {
+  if (resolved.error === 'no_config') {
+    logger.error('No briefing registry found. Activate @briefing to create the first briefing.');
+  } else if (resolved.error === 'invalid_frontmatter') {
+    logger.error('briefings/config.md has invalid frontmatter. Fix it manually.');
+  } else if (resolved.error === 'no_refinable') {
+    logger.error('No refinable briefing (draft, or approved without a PRD).');
+  } else if (resolved.error === 'ambiguous_slug') {
+    logger.error(`Multiple refinable briefings — pass --slug=<slug>. Candidates: ${resolved.candidates.join(', ')}`);
+  } else if (resolved.error === 'slug_not_refinable') {
+    logger.error(`Briefing "${resolved.slug}" is not refinable. Candidates: ${(resolved.candidates || []).join(', ') || 'none'}`);
+  }
+}
+
+async function readOptionalJson(filePath) {
+  let raw;
+  try {
+    raw = await fsp.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return { exists: false, value: null };
+    return { exists: true, error: error.message, value: null };
+  }
+  try {
+    return { exists: true, value: JSON.parse(raw) };
+  } catch (error) {
+    return { exists: true, error: `invalid JSON: ${error.message}`, value: null };
+  }
+}
+
+async function runBriefingReview({ args, options = {}, logger }) {
+  const projectDir = path.resolve(process.cwd(), args[0] || '.');
+  const resolved = await resolveRefinableSlug(projectDir, options.slug);
+  if (!resolved.ok) {
+    logSlugResolutionError(resolved, logger);
+    return resolved;
+  }
+  const slug = resolved.slug;
+
+  let markdown;
+  try {
+    markdown = await fsp.readFile(resolveBriefingPath(projectDir, slug, 'briefings.md'), 'utf8');
+  } catch {
+    logger.error(`briefings.md not found for "${slug}".`);
+    return { ok: false, error: 'briefing_not_found', slug };
+  }
+
+  const parsed = parseBriefingSections(markdown, `.aioson/briefings/${slug}/briefings.md`);
+  if (parsed.missing.length > 0) {
+    logger.error(`briefings.md is missing mandatory sections: ${parsed.missing.join(', ')}`);
+    return { ok: false, error: 'missing_sections', slug, missing: parsed.missing };
+  }
+
+  // Findings: --findings=<path>, else the canonical drop path the agent writes.
+  const findingsExplicit = Boolean(options.findings);
+  const findingsPath = findingsExplicit
+    ? path.resolve(projectDir, String(options.findings))
+    : resolveBriefingPath(projectDir, slug, 'refinement-findings.json');
+  const findingsRead = await readOptionalJson(findingsPath);
+  if (findingsRead.error) {
+    logger.error(`cannot read findings file (${findingsPath}): ${findingsRead.error}`);
+    return { ok: false, error: 'invalid_findings', slug };
+  }
+  if (findingsExplicit && !findingsRead.exists) {
+    logger.error(`findings file not found: ${findingsPath}`);
+    return { ok: false, error: 'invalid_findings', slug };
+  }
+  let findings = [];
+  if (findingsRead.exists) {
+    const value = findingsRead.value;
+    findings = Array.isArray(value) ? value : (value && Array.isArray(value.findings) ? value.findings : null);
+    if (!findings) {
+      logger.error('findings file must be a JSON array or { "findings": [...] }');
+      return { ok: false, error: 'invalid_findings', slug };
+    }
+    const check = validateFindingsInput(findings, { sectionIds: parsed.sections.map((s) => s.id) });
+    if (!check.ok) {
+      for (const err of check.errors) logger.error(`findings: ${err}`);
+      return { ok: false, error: 'invalid_findings', slug, errors: check.errors };
+    }
+  }
+
+  // Round counter + pending-feedback protection: never silently clobber
+  // feedback the user already exported for the CURRENT briefing text. The
+  // round survives apply (which archives the canonical feedback) by also
+  // counting the applied-round archives.
+  const feedbackPath = resolveBriefingPath(projectDir, slug, 'refinement-feedback.json');
+  let lastRound = 0;
+  const prior = await readOptionalJson(feedbackPath);
+  if (prior.exists && prior.value && typeof prior.value === 'object') {
+    lastRound = Number.isInteger(prior.value.round) ? prior.value.round : 0;
+    const userExported = USER_EXPORT_METHODS.has(prior.value.export_method);
+    const fresh = prior.value.source_hash === parsed.source_hash;
+    if (userExported && fresh && !options.force) {
+      logger.error('refinement-feedback.json holds user-exported feedback for the current briefing text.');
+      logger.error('Apply it first (aioson briefing:apply-feedback) or pass --force to overwrite it.');
+      return { ok: false, error: 'pending_feedback', slug };
+    }
+  }
+  try {
+    const entries = await fsp.readdir(resolveBriefingPath(projectDir, slug));
+    for (const entry of entries) {
+      const match = entry.match(/^refinement-feedback\.(?:applied|declined)-round(\d+)/);
+      if (match) lastRound = Math.max(lastRound, Number(match[1]));
+    }
+  } catch { /* directory listing is best-effort */ }
+  const round = lastRound + 1;
+
+  const locale = String(options.locale || process.env.AIOS_LITE_LOCALE || 'en');
+  await writeReviewArtifacts(projectDir, {
+    slug,
+    sourceMarkdown: markdown,
+    sections: parsed.sections,
+    sourceHash: parsed.source_hash,
+    findings,
+    round,
+    locale
+  });
+
+  // Best-effort registry pointer so the dashboard/agents see the active review.
+  try {
+    const registry = await readBriefingRegistry(projectDir);
+    markRefinementState(registry, slug, {
+      refinement_status: 'review_generated',
+      review_html: `.aioson/briefings/${slug}/review.html`,
+      refinement_report: `.aioson/briefings/${slug}/refinement-report.md`
+    });
+    await writeBriefingRegistry(projectDir, registry);
+  } catch { /* registry pointer is advisory */ }
+
+  const reviewRel = `.aioson/briefings/${slug}/review.html`;
+  logger.log(`✓ Review generated for "${slug}" (round ${round}): ${parsed.sections.length} sections, ${findings.length} findings.`);
+  logger.log(`  Open ${reviewRel} in a real browser (not an editor preview), review, then export the JSON.`);
+  if (!findingsRead.exists) {
+    logger.log('  No findings file was provided — the review carries sections only.');
+  }
+  return {
+    ok: true,
+    slug,
+    round,
+    sections: parsed.sections.length,
+    findings: findings.length,
+    source_hash: parsed.source_hash,
+    review: reviewRel,
+    feedback: `.aioson/briefings/${slug}/refinement-feedback.json`,
+    report: `.aioson/briefings/${slug}/refinement-report.md`
+  };
+}
+
+function summarizeFeedback(feedback) {
+  const sections = feedback.sections || [];
+  const findings = feedback.findings || [];
+  const changed = sections.filter((s) => s.status !== 'unchanged' || s.current_text !== s.original_text);
+  const findingsByStatus = {};
+  for (const finding of findings) {
+    findingsByStatus[finding.status] = (findingsByStatus[finding.status] || 0) + 1;
+  }
+  return {
+    changed_sections: changed.map((s) => ({ id: s.id, status: s.status, text_changed: s.current_text !== s.original_text })),
+    blocked_sections: sections.filter((s) => s.status === 'blocked').map((s) => s.id),
+    comments: (feedback.comments || []).length,
+    findings_total: findings.length,
+    findings_by_status: findingsByStatus,
+    pending_blocking_findings: findings.filter((f) => f.blocking && f.status === 'pending').map((f) => f.id),
+    blocking_items: (feedback.blocking_items || []).length
+  };
+}
+
+async function runBriefingApplyFeedback({ args, options = {}, logger }) {
+  const projectDir = path.resolve(process.cwd(), args[0] || '.');
+  const resolved = await resolveRefinableSlug(projectDir, options.slug);
+  if (!resolved.ok) {
+    logSlugResolutionError(resolved, logger);
+    return resolved;
+  }
+  const slug = resolved.slug;
+  const allowStale = Boolean(options['allow-stale'] || options.allowStale);
+
+  const feedbackRel = options.feedback
+    ? String(options.feedback)
+    : `.aioson/briefings/${slug}/refinement-feedback.json`;
+  try {
+    assertFeedbackPath(projectDir, slug, feedbackRel);
+  } catch (error) {
+    logger.error(error.message);
+    return { ok: false, error: 'invalid_feedback_path', slug };
+  }
+  const feedbackPath = path.resolve(projectDir, feedbackRel);
+  const feedbackRead = await readOptionalJson(feedbackPath);
+  if (!feedbackRead.exists || feedbackRead.error) {
+    logger.error(`cannot read feedback (${feedbackRel}): ${feedbackRead.error || 'file not found'}`);
+    return { ok: false, error: 'feedback_not_found', slug };
+  }
+  const feedback = feedbackRead.value;
+
+  if (options.declined) {
+    const result = await applyDeclinedFeedback(projectDir, slug, feedback, { allowStale: true });
+    if (!result.ok) {
+      for (const err of (result.validation && result.validation.errors) || []) logger.error(`feedback: ${err}`);
+      return { ...result, slug, mode: 'declined' };
+    }
+    // Archive the declined feedback so "file present = pending" stays true and
+    // the next briefing:review does not dead-end on pending_feedback. Findings
+    // are NOT archived: the briefing text is unchanged, so they stay valid.
+    const canonicalPath = resolveBriefingPath(projectDir, slug, 'refinement-feedback.json');
+    if (feedbackPath === canonicalPath) {
+      const round = feedback.round || 1;
+      let archiveName = `refinement-feedback.declined-round${round}.json`;
+      try {
+        await fsp.access(resolveBriefingPath(projectDir, slug, archiveName));
+        archiveName = `refinement-feedback.declined-round${round}-${Date.now()}.json`;
+      } catch { /* target free */ }
+      try {
+        await fsp.rename(canonicalPath, resolveBriefingPath(projectDir, slug, archiveName));
+        result.archived = `.aioson/briefings/${slug}/${archiveName}`;
+      } catch { /* archive is best-effort */ }
+    }
+    logger.log(`✓ Feedback declined for "${slug}" — briefings.md unchanged, ${result.skippedChanges.length} change(s) recorded as skipped.`);
+    return { ...result, slug, mode: 'declined' };
+  }
+
+  if (!options.confirm) {
+    // Dry-run: validate + summarize so the agent can present the plan and ask
+    // for the human go-ahead. Never touches briefings.md.
+    let current;
+    try {
+      current = await fsp.readFile(resolveBriefingPath(projectDir, slug, 'briefings.md'), 'utf8');
+    } catch {
+      logger.error(`briefings.md not found for "${slug}".`);
+      return { ok: false, error: 'briefing_not_found', slug };
+    }
+    const validation = validateFeedback(feedback, { slug, currentSourceHash: hashText(current), allowStale });
+    const summary = summarizeFeedback(feedback);
+    if (!validation.ok) {
+      for (const err of validation.errors) logger.error(`feedback: ${err}`);
+      return { ok: false, error: 'invalid_feedback', slug, mode: 'dry-run', validation, summary };
+    }
+    logger.log(`Dry-run for "${slug}" (feedback round ${feedback.round || 1}):`);
+    logger.log(`  changed sections: ${summary.changed_sections.map((c) => c.id).join(', ') || 'none'}`);
+    logger.log(`  blocked sections: ${summary.blocked_sections.join(', ') || 'none'}`);
+    logger.log(`  findings: ${summary.findings_total} (${Object.entries(summary.findings_by_status).map(([k, v]) => `${k}: ${v}`).join(', ') || '-'})`);
+    logger.log(`  pending blocking findings: ${summary.pending_blocking_findings.join(', ') || 'none'}`);
+    for (const warning of validation.warnings) logger.log(`  warning: ${warning}`);
+    logger.log('Re-run with --confirm to apply.');
+    return { ok: true, slug, mode: 'dry-run', pending_confirmation: true, validation, summary };
+  }
+
+  const result = await applyConfirmedFeedback(projectDir, slug, feedback, { confirmed: true, allowStale });
+  if (!result.ok) {
+    for (const err of (result.validation && result.validation.errors) || []) logger.error(`feedback: ${err}`);
+    if (result.error === 'invalid_feedback' && result.validation && result.validation.stale && !allowStale) {
+      logger.error('Feedback is stale (briefings.md changed since the review). Regenerate the review or pass --allow-stale.');
+    }
+    return { ...result, slug, mode: 'apply' };
+  }
+
+  // Archive the consumed canonical feedback so "pending feedback" stays a
+  // deterministic signal (file present = not yet applied).
+  const canonicalPath = resolveBriefingPath(projectDir, slug, 'refinement-feedback.json');
+  if (feedbackPath === canonicalPath) {
+    const round = feedback.round || 1;
+    let archiveName = `refinement-feedback.applied-round${round}.json`;
+    try {
+      await fsp.access(resolveBriefingPath(projectDir, slug, archiveName));
+      archiveName = `refinement-feedback.applied-round${round}-${Date.now()}.json`;
+    } catch { /* target free */ }
+    try {
+      await fsp.rename(canonicalPath, resolveBriefingPath(projectDir, slug, archiveName));
+      result.archived = `.aioson/briefings/${slug}/${archiveName}`;
+    } catch { /* archive is best-effort */ }
+    // Retire the consumed findings too — the next round must audit the UPDATED
+    // briefing, not silently reuse last round's findings.
+    try {
+      await fsp.rename(
+        resolveBriefingPath(projectDir, slug, 'refinement-findings.json'),
+        resolveBriefingPath(projectDir, slug, `refinement-findings.applied-round${round}.json`)
+      );
+    } catch { /* no findings file, or archive failed — best-effort */ }
+  }
+
+  logger.log(`✓ Applied ${result.appliedChanges.length} change(s) to "${slug}".`);
+  if (result.returnedToDraft) logger.log('  Briefing returned from approved to draft.');
+  if (result.nextAction === 'resolve_blockers') {
+    logger.log('  Blockers remain — resolve them and regenerate the review (aioson briefing:review).');
+  } else {
+    logger.log('  No blockers — approve with `aioson briefing:approve` and hand off to @product, or regenerate the review for another round.');
+  }
+  return { ...result, slug, mode: 'apply' };
+}
+
+module.exports = { runBriefingApprove, runBriefingUnapprove, runBriefingReview, runBriefingApplyFeedback };

package/src/commands/feature-close.js

@@ -16,20 +16,21 @@ const fs = require('node:fs/promises');
 const path = require('node:path');
 const { contextDir, readFileSafe, parseFrontmatter } = require('../preflight-engine');
 const { runFeatureArchive } = require('./feature-archive');
+const { runStateReset } = require('./state-save');
 const dossierBootstrap = require('../dossier/dossier-bootstrap');
 const dossierStore = require('../dossier/store');
 const { emitDossierEvent } = require('../lib/dossier-telemetry');
 const { appendScoutToFeatureDossier } = require('../dossier/scout-section');
 const { emitSubTaskEvent } = require('../sub-task-telemetry');
 const { loadConfig } = require('../sub-task-engine');
-const { runDistillation, readFeatureClassification } = require('../learning-loop-engine');
-const { openRuntimeDb } = require('../runtime-store');
-const { runNotify } = require('./notify');
-const { splitCurrentState, buildArchiveContent, parseActiveSlugs } = require('../current-state-trim');
-const {
-  evaluateContractIntegrityGate,
-  formatContractIntegrityGateError
-} = require('../harness/contract-integrity-gate');
+const { runDistillation, readFeatureClassification } = require('../learning-loop-engine');
+const { openRuntimeDb } = require('../runtime-store');
+const { runNotify } = require('./notify');
+const { splitCurrentState, buildArchiveContent, parseActiveSlugs } = require('../current-state-trim');
+const {
+  evaluateContractIntegrityGate,
+  formatContractIntegrityGateError
+} = require('../harness/contract-integrity-gate');
 
 // P0 agent-loading-contract: a feature closing is the natural cadence to roll
 // aged-out current-state.md entries into the cold archive. Conservative window
@@ -302,6 +303,72 @@ async function archiveScoutsForFeature(targetDir, slug) {
   return result;
 }
 
+// retireDevStateForClosedFeature — clear the @dev cold-start pointer when it
+// still points at the feature being closed. @dev reads dev-state.md DIRECTLY on
+// cold start (its session-start protocol "starts on next_step immediately"),
+// bypassing the dev:resume-data guard that already checks features.md status —
+// so a stale pointer to a done feature would make a future @dev session try to
+// "resume" work that is already closed (e.g. next_step: aioson feature:close).
+// Only retires when active_feature matches this slug; a pointer to a DIFFERENT
+// active feature is left untouched. Archived (not blind-deleted) for audit via
+// the existing state:reset --archive path. Idempotent and best-effort.
+async function retireDevStateForClosedFeature(targetDir, ctxDir, slug) {
+  const statePath = path.join(ctxDir, 'dev-state.md');
+  const content = await readFileSafe(statePath);
+  if (!content) return { retired: false, reason: 'no_dev_state' };
+  const fm = parseFrontmatter(content);
+  const active = String(fm.active_feature || '').trim();
+  if (active !== slug) {
+    return { retired: false, reason: 'points_to_other', active_feature: active || null };
+  }
+  const reset = await runStateReset({
+    args: [targetDir],
+    options: { archive: true, json: true },
+    logger: { log() {} }
+  });
+  return {
+    retired: Boolean(reset && reset.removed),
+    archived: reset && reset.archived ? reset.archived : null
+  };
+}
+
+// retireWorkflowStateForClosedFeature — clear the per-feature workflow runtime
+// state when it still references the feature being closed. Both files live in
+// .aioson/context/, are not slug-named, and are excluded from feature:archive —
+// so without this they linger and break the NEXT feature:
+//   - workflow.state.json: seedFeatureWorkflowState refuses to seed a new slug
+//     while a stale feature state is present ("different_active_feature").
+//   - workflow-execute.json: its enabled agentic_policy is the autopilot signal
+//     downstream agents read — a stale one would auto-run the next feature.
+// Only clears when the file references THIS slug (feature mode); a project-mode
+// state or a pointer to another feature is left untouched. Best-effort.
+async function retireWorkflowStateForClosedFeature(ctxDir, slug) {
+  const retired = [];
+  const statePath = path.join(ctxDir, 'workflow.state.json');
+  const stateRaw = await readFileSafe(statePath);
+  if (stateRaw) {
+    try {
+      const st = JSON.parse(stateRaw);
+      if (st && st.mode === 'feature' && st.featureSlug === slug) {
+        await fs.unlink(statePath);
+        retired.push('workflow.state.json');
+      }
+    } catch { /* malformed — leave it for manual inspection */ }
+  }
+  const execPath = path.join(ctxDir, 'workflow-execute.json');
+  const execRaw = await readFileSafe(execPath);
+  if (execRaw) {
+    try {
+      const ex = JSON.parse(execRaw);
+      if (ex && ex.feature === slug) {
+        await fs.unlink(execPath);
+        retired.push('workflow-execute.json');
+      }
+    } catch { /* malformed — leave it */ }
+  }
+  return retired;
+}
+
 async function runFeatureClose({ args, options = {}, logger }) {
   const targetDir = path.resolve(process.cwd(), args[0] || '.');
   const slug = options.feature ? String(options.feature) : null;
@@ -326,40 +393,40 @@ async function runFeatureClose({ args, options = {}, logger }) {
   const updates = [];
 
   // 0a. Harness Done Gate (AC-HD-11 refined)
-  // Only enforced on PASS — FAIL means QA already rejected and we want the
-  // closure to record that. Runtime features the CLI can detect (prototype or
-  // migration/Prisma evidence) must have a valid contract even on MICRO/SMALL;
-  // non-runtime features without a contract keep the historical lightweight path.
+  // Only enforced on PASS — FAIL means QA already rejected and we want the
+  // closure to record that. Runtime features the CLI can detect (prototype or
+  // migration/Prisma evidence) must have a valid contract even on MICRO/SMALL;
+  // non-runtime features without a contract keep the historical lightweight path.
   if (verdict === 'PASS') {
     const planDir = path.join(targetDir, '.aioson', 'plans', slug);
-    const contractPath = path.join(planDir, 'harness-contract.json');
-    const progressPath = path.join(planDir, 'progress.json');
-    const contractContent = await readFileSafe(contractPath);
-    const progressContent = await readFileSafe(progressPath);
-    const force = options.force === true;
-
-    const integrityGate = await evaluateContractIntegrityGate(targetDir, slug, {
-      runChecks: Boolean(contractContent)
-    });
-    if (!integrityGate.ok) {
-      if (!force) {
-        const errMsg = formatContractIntegrityGateError(integrityGate);
-        if (options.json) {
-          return {
-            ok: false,
-            reason: 'harness_contract_gate_blocked',
-            feature: slug,
-            error: errMsg,
-            errors: integrityGate.errors
-          };
-        }
-        logger.log(errMsg);
-        return { ok: false, reason: 'harness_contract_gate_blocked' };
-      }
-      updates.push('harness contract gate: BYPASSED via --force');
-    }
-
-    // REQ-13 (loop-guardrails): tema `publish` é gate de COMANDO — intercepta
+    const contractPath = path.join(planDir, 'harness-contract.json');
+    const progressPath = path.join(planDir, 'progress.json');
+    const contractContent = await readFileSafe(contractPath);
+    const progressContent = await readFileSafe(progressPath);
+    const force = options.force === true;
+
+    const integrityGate = await evaluateContractIntegrityGate(targetDir, slug, {
+      runChecks: Boolean(contractContent)
+    });
+    if (!integrityGate.ok) {
+      if (!force) {
+        const errMsg = formatContractIntegrityGateError(integrityGate);
+        if (options.json) {
+          return {
+            ok: false,
+            reason: 'harness_contract_gate_blocked',
+            feature: slug,
+            error: errMsg,
+            errors: integrityGate.errors
+          };
+        }
+        logger.log(errMsg);
+        return { ok: false, reason: 'harness_contract_gate_blocked' };
+      }
+      updates.push('harness contract gate: BYPASSED via --force');
+    }
+
+    // REQ-13 (loop-guardrails): tema `publish` é gate de COMANDO — intercepta
     // o feature:close quando o contrato ativo o exige e não há gate publish
     // aprovado. Nunca detectado por diff. `--force` NÃO bypassa: a aprovação
     // humana é o propósito do gate (decisão registrada no spec da feature).
@@ -398,9 +465,9 @@ async function runFeatureClose({ args, options = {}, logger }) {
         }
       } catch { /* contrato ilegível — o done gate abaixo lida com o estado */ }
     }
-
-    if (contractContent && progressContent) {
-      let progress = null;
+
+    if (contractContent && progressContent) {
+      let progress = null;
       try {
         progress = JSON.parse(progressContent);
       } catch (err) {
@@ -471,6 +538,32 @@ async function runFeatureClose({ args, options = {}, logger }) {
     updates.push('features.md: not found (skipped)');
   }
 
+  // 2.5. Retire the @dev cold-start pointer if it still points at this feature.
+  // On PASS the feature is done; a lingering dev-state.md would make a future
+  // @dev cold-start try to resume it (it reads the file directly). FAIL leaves
+  // it — @dev keeps working the qa_failed feature. Never touches a pointer to a
+  // different active feature. Best-effort; never blocks the close.
+  if (verdict === 'PASS') {
+    try {
+      const ds = await retireDevStateForClosedFeature(targetDir, dir, slug);
+      if (ds.retired) {
+        updates.push(`dev-state.md: retired closed-feature pointer${ds.archived ? ` (archived to ${ds.archived})` : ''}`);
+      } else if (ds.reason === 'points_to_other') {
+        updates.push(`dev-state.md: left intact (points at ${ds.active_feature}, not ${slug})`);
+      }
+    } catch (err) {
+      updates.push(`dev-state.md: retire hook error (${(err && err.message) || err})`);
+    }
+    try {
+      const wf = await retireWorkflowStateForClosedFeature(dir, slug);
+      if (wf.length > 0) {
+        updates.push(`workflow state: retired ${wf.join(', ')} (closed-feature runtime state)`);
+      }
+    } catch (err) {
+      updates.push(`workflow state: retire hook error (${(err && err.message) || err})`);
+    }
+  }
+
   // 3. Update project-pulse.md
   const pulsePath = path.join(dir, 'project-pulse.md');
   const pulseUpdated = await updateProjectPulseFile(