@jaimevalasek/aioson 1.6.0 → 1.7.0

package/src/squad/verify-gate.js

@@ -0,0 +1,303 @@
+'use strict';
+
+/**
+ * Squad 4-tier verification gate
+ *
+ * Verifies task deliverables beyond pass/fail:
+ *
+ *   Tier 1 — Exists:       File/path exists on disk
+ *   Tier 2 — Substantive:  Not a stub/placeholder (min lines + anti-pattern scan)
+ *   Tier 3 — Wired:        Referenced/imported in expected target location
+ *   Tier 4 — Functional:   Smoke command returns expected output (opt-in, expensive)
+ *
+ * Used by reflection.js when a task has a `must_haves` contract.
+ */
+
+const fs = require('node:fs/promises');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execFileAsync = promisify(execFile);
+
+// Patterns that indicate a file is a stub, not real implementation
+const ANTI_PATTERNS = [
+  { pattern: /\bTODO\b/,                              label: 'TODO marker'           },
+  { pattern: /\bFIXME\b/,                             label: 'FIXME marker'          },
+  { pattern: /\bplaceholder\b/i,                      label: 'placeholder text'      },
+  { pattern: /not\s+implemented/i,                    label: '"not implemented"'     },
+  { pattern: /return\s+null;\s*\n?\s*\}/m,            label: 'empty return null'     },
+  { pattern: /throw\s+new\s+Error\s*\(['"]not\s+impl/i, label: 'NotImplemented throw' },
+  { pattern: /^\s*pass\s*$/m,                         label: 'Python stub (pass)'    },
+  { pattern: /^\s*\.\.\.\s*$/m,                       label: 'ellipsis stub'         }
+];
+
+// ─── Artifact string parser ───────────────────────────────────────────────────
+
+/**
+ * Parse an artifact descriptor string into structured fields.
+ *
+ * Examples:
+ *   "src/routes/auth.ts"
+ *   "src/routes/auth.ts (>50 lines)"
+ *   "src/routes/auth.ts (>50 lines, exports router)"
+ *
+ * Returns: { filePath, minLines, wiredPattern }
+ */
+function parseArtifact(str, projectDir) {
+  const s = String(str).trim();
+
+  // Extract optional annotations in parentheses
+  const parenMatch = s.match(/^(.+?)\s*\(([^)]*)\)\s*$/);
+  const rawPath = parenMatch ? parenMatch[1].trim() : s;
+  const annotations = parenMatch ? parenMatch[2] : '';
+
+  // Build absolute path (relative to projectDir if given)
+  const filePath = projectDir
+    ? require('node:path').resolve(projectDir, rawPath)
+    : rawPath;
+
+  // Parse min lines: ">50 lines" or "50 lines"
+  const linesMatch = annotations.match(/>?\s*(\d+)\s+lines?/i);
+  const minLines = linesMatch ? parseInt(linesMatch[1], 10) : 5;
+
+  // Parse wired pattern: any text after "exports" or "imports" or "registers"
+  const wiredMatch = annotations.match(/(?:exports?|imports?|registers?)\s+(.+)/i);
+  const wiredPattern = wiredMatch ? wiredMatch[1].trim() : null;
+
+  return { filePath, rawPath, minLines, wiredPattern };
+}
+
+/**
+ * Parse a key_link descriptor string.
+ *
+ * Example: "auth router registered in src/app.ts"
+ * Returns: { pattern, inFile }
+ *
+ * Pattern is extracted heuristically from the string.
+ */
+function parseKeyLink(str, projectDir) {
+  const path = require('node:path');
+  const s = String(str).trim();
+
+  // Pattern: "<thing> in <filepath>" or "<thing> registered/imported/used in <filepath>"
+  const inMatch = s.match(/^(.+?)\s+(?:in|from|inside)\s+(\S+\.(?:ts|js|tsx|jsx|py|rb|go|java|php|vue|svelte))\s*$/i);
+  if (inMatch) {
+    const rawFile = inMatch[2].trim();
+    const inFile = projectDir ? path.resolve(projectDir, rawFile) : rawFile;
+
+    // Extract meaningful keywords from the pattern part (first 3 significant words)
+    const patternWords = inMatch[1]
+      .replace(/\b(?:registered|imported|used|exported|referenced|wired|connected|added)\b/gi, '')
+      .trim()
+      .split(/\s+/)
+      .filter((w) => w.length > 2)
+      .slice(0, 3);
+
+    return { pattern: patternWords.join('|'), inFile, rawFile };
+  }
+
+  return null;
+}
+
+// ─── Tier implementations ─────────────────────────────────────────────────────
+
+/** Tier 1: file exists on disk */
+async function verifyExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return { passed: true, tier: 1, file: filePath };
+  } catch {
+    return { passed: false, tier: 1, file: filePath, reason: 'file does not exist' };
+  }
+}
+
+/** Tier 2: file is substantive (not a stub) */
+async function verifySubstantive(filePath, minLines = 5) {
+  let content;
+  try {
+    content = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return { passed: false, tier: 2, file: filePath, reason: 'cannot read file' };
+  }
+
+  const nonEmptyLines = content.split('\n').filter((l) => l.trim().length > 0).length;
+  if (nonEmptyLines < minLines) {
+    return {
+      passed: false, tier: 2, file: filePath,
+      reason: `only ${nonEmptyLines} non-empty lines (min: ${minLines})`
+    };
+  }
+
+  for (const { pattern, label } of ANTI_PATTERNS) {
+    if (pattern.test(content)) {
+      return { passed: false, tier: 2, file: filePath, reason: `contains ${label}` };
+    }
+  }
+
+  return { passed: true, tier: 2, file: filePath, lines: nonEmptyLines };
+}
+
+/** Tier 3: pattern found in a target file (wired/imported/registered) */
+async function verifyWired(pattern, inFile) {
+  if (!pattern || !inFile) {
+    return { passed: true, tier: 3, skipped: true, reason: 'no wired constraint to check' };
+  }
+
+  let content;
+  try {
+    content = await fs.readFile(inFile, 'utf8');
+  } catch {
+    return { passed: false, tier: 3, file: inFile, reason: `cannot read target file: ${inFile}` };
+  }
+
+  const regex = typeof pattern === 'string'
+    ? new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')
+    : pattern;
+
+  if (regex.test(content)) {
+    return { passed: true, tier: 3, pattern, inFile };
+  }
+
+  return {
+    passed: false, tier: 3, pattern, inFile,
+    reason: `pattern "${pattern}" not found in ${inFile}`
+  };
+}
+
+/** Tier 4: smoke command returns expected output (optional, expensive) */
+async function verifyFunctional(command, args = [], expectedPattern = null, timeoutMs = 10_000) {
+  try {
+    const { stdout, stderr } = await execFileAsync(command, args, {
+      timeout: timeoutMs,
+      shell: false
+    });
+    const output = stdout + stderr;
+
+    if (expectedPattern) {
+      const regex = typeof expectedPattern === 'string'
+        ? new RegExp(expectedPattern, 'i')
+        : expectedPattern;
+      if (!regex.test(output)) {
+        return {
+          passed: false, tier: 4, command,
+          reason: `expected pattern "${expectedPattern}" not found in command output`
+        };
+      }
+    }
+
+    return { passed: true, tier: 4, command, output: output.slice(0, 300) };
+  } catch (err) {
+    return { passed: false, tier: 4, command, reason: err.message.slice(0, 200) };
+  }
+}
+
+// ─── must_haves checker ───────────────────────────────────────────────────────
+
+/**
+ * Run must_haves verification against a task's contract.
+ *
+ * @param {object} mustHaves   — { truths?, artifacts?, key_links? }
+ * @param {string} output      — Task output text (used for truths checks)
+ * @param {string} projectDir
+ * @returns {Promise<MustHavesResult>}
+ *
+ * MustHavesResult:
+ *   {
+ *     passed: boolean,
+ *     failures: string[],
+ *     warnings: string[],
+ *     details: object[]
+ *   }
+ */
+async function checkMustHaves(mustHaves, output, projectDir) {
+  if (!mustHaves) return { passed: true, failures: [], warnings: [], details: [] };
+
+  const failures = [];
+  const warnings = [];
+  const details = [];
+  const outputText = String(output || '').toLowerCase();
+
+  // ── Truths: heuristic — check if output mentions the expected state ──────
+  for (const truth of (mustHaves.truths || [])) {
+    // Extract key nouns/verbs from truth statement and check they appear in output
+    const keywords = String(truth)
+      .replace(/\b(?:the|a|an|is|are|can|will|should|must|to|of|in|and|or|that)\b/gi, '')
+      .split(/\s+/)
+      .filter((w) => w.length > 3)
+      .slice(0, 4);
+
+    const found = keywords.some((kw) => outputText.includes(kw.toLowerCase()));
+    const result = { type: 'truth', statement: truth, passed: found };
+    details.push(result);
+
+    if (!found) {
+      warnings.push(`Truth not evident in output: "${truth.slice(0, 80)}"`);
+    }
+  }
+
+  // ── Artifacts: Tier 1 + Tier 2 checks ────────────────────────────────────
+  for (const artifactStr of (mustHaves.artifacts || [])) {
+    const { filePath, rawPath, minLines, wiredPattern } = parseArtifact(artifactStr, projectDir);
+
+    const t1 = await verifyExists(filePath);
+    details.push({ type: 'artifact', descriptor: artifactStr, ...t1 });
+
+    if (!t1.passed) {
+      failures.push(`Artifact missing: ${rawPath}`);
+      continue;
+    }
+
+    const t2 = await verifySubstantive(filePath, minLines);
+    details.push({ type: 'artifact_substantive', descriptor: artifactStr, ...t2 });
+
+    if (!t2.passed) {
+      failures.push(`Artifact is a stub: ${rawPath} — ${t2.reason}`);
+      continue;
+    }
+
+    // If wired pattern specified, verify it exists in the same file
+    if (wiredPattern) {
+      const t3 = await verifyWired(wiredPattern, filePath);
+      details.push({ type: 'artifact_wired', descriptor: artifactStr, ...t3 });
+      if (!t3.passed) {
+        warnings.push(`Artifact wiring issue: ${rawPath} — ${t3.reason}`);
+      }
+    }
+  }
+
+  // ── Key links: Tier 3 checks ──────────────────────────────────────────────
+  for (const keyLink of (mustHaves.key_links || [])) {
+    const parsed = parseKeyLink(keyLink, projectDir);
+
+    if (!parsed) {
+      // Cannot parse — skip silently (heuristic limitation)
+      details.push({ type: 'key_link', descriptor: keyLink, passed: true, skipped: true });
+      continue;
+    }
+
+    const t3 = await verifyWired(parsed.pattern, parsed.inFile);
+    details.push({ type: 'key_link', descriptor: keyLink, ...t3 });
+
+    if (!t3.passed) {
+      warnings.push(`Key link not wired: "${keyLink.slice(0, 80)}" — ${t3.reason}`);
+    }
+  }
+
+  return {
+    passed: failures.length === 0,
+    failures,
+    warnings,
+    details
+  };
+}
+
+module.exports = {
+  verifyExists,
+  verifySubstantive,
+  verifyWired,
+  verifyFunctional,
+  checkMustHaves,
+  parseArtifact,
+  parseKeyLink,
+  ANTI_PATTERNS
+};

package/src/updater.js

@@ -15,17 +15,16 @@ async function updateInstallation(targetDir, options = {}) {
 
   const savedProfile = await readInstallProfile(targetDir);
 
-  // During update, pass null profile so ALL framework files are installed
-  // (not just those matching the saved profile).
-  // This ensures new framework files from the new version are always installed.
-  // Profile-based filtering only applies to init/install.
+  // Default: only update files already present in the target (selective update).
+  // With --all: install every file from the template, including new ones not yet installed.
   const result = await installTemplate(targetDir, {
     overwrite: true,
     dryRun: Boolean(options.dryRun),
     mode: 'update',
     backupOnOverwrite: true,
     frameworkDetection: options.frameworkDetection || null,
-    installProfile: null
+    installProfile: null,
+    selectiveUpdate: !options.all
   });
 
   return {

package/src/worker-runner.js

@@ -123,12 +123,188 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// ─── Research Worker ──────────────────────────────────────────────────────────
+
+/**
+ * Handle a `type: 'research'` worker.
+ *
+ * Checks the researchs/ cache first (7-day default TTL), falls back to
+ * scraping declared URLs or the topic keyword via web.js fetchPage.
+ *
+ * Cache location: researchs/{topic}/summary.md
+ */
+async function runResearchWorker(projectDir, config, inputPayload) {
+  const { fetchPage } = require('./web');
+  const research = config.research || {};
+  const topic = String(research.topic || inputPayload?.topic || 'general').replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+  const cacheHours = Number(research.cache_hours || 168); // 7 days default
+  const cacheDir = path.join(projectDir, research.cache_dir || 'researchs', topic);
+  const summaryPath = path.join(cacheDir, 'summary.md');
+
+  // ── Cache check ────────────────────────────────────────────────────────────
+  try {
+    const stat = await fs.stat(summaryPath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    const ageHours = ageMs / (1000 * 60 * 60);
+    if (ageHours < cacheHours) {
+      const cached = await fs.readFile(summaryPath, 'utf8');
+      return {
+        ok: true,
+        output: { topic, summary: cached, cached: true, cache_age_hours: Math.round(ageHours) },
+        attempt: 1
+      };
+    }
+  } catch { /* no cache yet */ }
+
+  // ── Scrape sources ─────────────────────────────────────────────────────────
+  const urls = research.urls || inputPayload?.urls || [];
+  const maxSources = Number(research.max_sources || 5);
+  const pages = [];
+
+  for (const url of urls.slice(0, maxSources)) {
+    try {
+      const result = await fetchPage(url, { timeoutMs: 15000, extractLinks: false });
+      if (result.ok && result.text) {
+        pages.push({ url, content: result.text.slice(0, 3000) });
+      }
+    } catch { /* skip unreachable sources */ }
+  }
+
+  if (pages.length === 0) {
+    return {
+      ok: false,
+      error: `Research worker "${topic}": no URLs declared and no cached summary. Add "research.urls" to worker.json or provide ?topic= with cached data.`,
+      attempts: 1
+    };
+  }
+
+  // ── Build summary ──────────────────────────────────────────────────────────
+  const ts = new Date().toISOString();
+  const summary = [
+    `# Research: ${topic}`,
+    `_Generated: ${ts} · Sources: ${pages.length}_`,
+    '',
+    ...pages.map((p, i) => [
+      `## Source ${i + 1}: ${p.url}`,
+      '',
+      p.content.slice(0, 2000),
+      ''
+    ].join('\n'))
+  ].join('\n');
+
+  await fs.mkdir(cacheDir, { recursive: true });
+  await fs.writeFile(summaryPath, summary, 'utf8');
+
+  return {
+    ok: true,
+    output: { topic, summary, cached: false, sources: pages.length, generated_at: ts },
+    attempt: 1
+  };
+}
+
+// ─── Skill Worker (Plan 81 §2.2) ─────────────────────────────────────────────
+
+/**
+ * Handle a `type: 'skill'` worker.
+ * Resolves an external Agent Skills Standard skill and executes it.
+ *
+ * Skill sources:
+ *   - Local path: ./skills/my-skill/ or .claude/skills/my-skill/
+ *   - NPM package: npm:@org/skill-name (resolved from node_modules)
+ */
+async function runSkillWorker(projectDir, config, inputPayload) {
+  const skillRef = config.skill || config.source || '';
+  let skillDir;
+
+  if (skillRef.startsWith('npm:')) {
+    // Resolve from node_modules
+    const pkgName = skillRef.slice(4);
+    skillDir = path.join(projectDir, 'node_modules', pkgName);
+  } else {
+    // Local path
+    skillDir = path.resolve(projectDir, skillRef);
+  }
+
+  // Check SKILL.md exists
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  if (!(await pathExists(skillMdPath))) {
+    return {
+      ok: false,
+      error: `Skill not found: ${skillRef} (expected SKILL.md at ${skillMdPath})`,
+      attempts: 0
+    };
+  }
+
+  // Check for executable scripts
+  const scriptsDir = path.join(skillDir, 'scripts');
+  const runScript = path.join(scriptsDir, 'run.js');
+  const runPyScript = path.join(scriptsDir, 'run.py');
+
+  if (await pathExists(runScript)) {
+    return spawnWorker(runScript, inputPayload || {}, {}, config.timeout_ms || DEFAULT_TIMEOUT);
+  }
+
+  if (await pathExists(runPyScript)) {
+    return spawnWorker(runPyScript, inputPayload || {}, {}, config.timeout_ms || DEFAULT_TIMEOUT);
+  }
+
+  // No executable script — return skill content for LLM-based execution
+  const skillContent = await fs.readFile(skillMdPath, 'utf8');
+  return {
+    ok: true,
+    output: {
+      type: 'skill-prompt',
+      skillPath: skillMdPath,
+      content: skillContent.slice(0, 4000),
+      message: `Skill "${skillRef}" loaded. No run script found — use skill content as agent instructions.`
+    },
+    attempt: 1
+  };
+}
+
+// ─── Agent Memory Loader (Plan 81 §Sprint 4) ────────────────────────────────
+
+/**
+ * Load per-agent persistent memory if it exists.
+ * Returns memory content or null.
+ */
+async function loadAgentMemory(projectDir, squadSlug, executorSlug) {
+  const memoryPath = path.join(
+    projectDir, SQUADS_DIR, squadSlug, 'agent-memory', `${executorSlug}.md`
+  );
+  try {
+    return await fs.readFile(memoryPath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
 async function runWorker(projectDir, squadSlug, workerSlug, inputPayload, options = {}) {
   const config = await loadWorkerConfig(projectDir, squadSlug, workerSlug);
   if (!config) {
     return { ok: false, error: `Worker config not found: ${workerSlug}`, attempts: 0 };
   }
 
+  // Skill worker — external skill execution (Plan 81 §2.2)
+  if (config.type === 'skill') {
+    return runSkillWorker(projectDir, config, inputPayload || {});
+  }
+
+  // Research worker — special handler (4.1)
+  if (config.type === 'research') {
+    return runResearchWorker(projectDir, config, inputPayload || {});
+  }
+
+  // Load per-agent persistent memory (Plan 81 §Sprint 4)
+  const agentMemory = await loadAgentMemory(projectDir, squadSlug, workerSlug);
+  if (agentMemory && inputPayload) {
+    // Inject into _agent_memory field (readable by Node.js workers via process.argv[2])
+    inputPayload._agent_memory = agentMemory;
+    // Prefix into context so LLM-based workers receive it as part of their task context
+    const existingContext = inputPayload.context || '';
+    inputPayload.context = `## Your accumulated knowledge:\n${agentMemory}\n\n---\n\n${existingContext}`.trimEnd();
+  }
+
   // Validate inputs
   const validation = validateInputs(inputPayload || {}, config.inputs);
   if (!validation.valid) {
@@ -149,6 +325,13 @@ async function runWorker(projectDir, squadSlug, workerSlug, inputPayload, option
   // Resolve env vars
   const env = resolveEnvVars(config.env);
 
+  // Expose agent memory path as env var so workers can read it directly
+  const memoryFilePath = path.join(projectDir, SQUADS_DIR, squadSlug, 'agent-memory', `${workerSlug}.md`);
+  try {
+    await fs.access(memoryFilePath);
+    env.AIOSON_AGENT_MEMORY_PATH = memoryFilePath;
+  } catch { /* no memory file yet — env var omitted */ }
+
   // Resolve MCP env vars if worker declares uses_mcp
   if (config.uses_mcp && config.uses_mcp.length > 0) {
     try {
@@ -335,5 +518,7 @@ module.exports = {
   generateRunJs,
   generateWorkerReadme,
   validateInputs,
-  resolveEnvVars
+  resolveEnvVars,
+  runSkillWorker,
+  loadAgentMemory
 };

package/template/.aioson/agents/analyst.md

@@ -39,6 +39,15 @@ Check the following before doing anything else:
 - `.aioson/context/prd-{slug}.md` (feature mode)
 - `.aioson/context/design-doc.md` + `readiness.md` (if present)
 - `.aioson/context/discovery.md` + `spec.md` (feature mode — project context, if present)
+- `.aioson/plans/{slug}/manifest.md` (if present — Sheldon phased plans; check subdirectories of `.aioson/plans/`)
+
+## Sheldon enrichment context (RDA-01)
+
+If `.aioson/context/sheldon-enrichment.md` (or `sheldon-enrichment-{slug}.md`) exists at session start:
+- Read it silently — do not display its contents to the user
+- Use the gaps identified and pre-made decisions as additional context for discovery
+- Do not re-ask questions that are already documented in the enrichment log
+- If `plan_path` is set in the frontmatter: read the manifest at that path and scope discovery to Phase 1 first
 
 ## Context loading policy
 
@@ -102,6 +111,10 @@ Stop here only when neither `discovery.md` nor local scan artifacts exist. Do no
 
 > **Rule:** whenever `discovery.md` is present, always read `spec.md` alongside it — never one without the other.
 
+## Web research cache
+
+Before running any web search, load `.aioson/skills/static/web-research-cache.md` and follow the protocol: check `researchs/{slug}/summary.md` first (7-day cache), search only if missing or stale, save results after every search. Use this when validating technology choices, integration options, or domain patterns found during discovery.
+
 ## Skills and docs on demand
 
 Before deepening discovery:
@@ -111,7 +124,7 @@ Before deepening discovery:
 - load only the docs that actually matter for this batch
 - consult local skills only when they improve domain mapping or flow clarity
 - check `.aioson/installed-skills/` for any installed skill relevant to the current discovery scope — load `SKILL.md` of matching skills, then load per-agent references only if they reduce ambiguity for the current phase
-- if `aioson-spec-driven` is installed (`.aioson/installed-skills/aioson-spec-driven/SKILL.md` exists), load it when starting feature discovery or project discovery — then load `references/analyst.md` from that skill
+- if `aioson-spec-driven` exists in `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OR in `.aioson/skills/process/aioson-spec-driven/SKILL.md`, load it when starting feature discovery or project discovery — then load `references/analyst.md` from that skill
 
 Do not inflate context without need.
 
@@ -213,6 +226,7 @@ For each new or modified entity, produce field-level detail (same format as Phas
 feature: {slug}
 status: in_progress
 started: {ISO-date}
+spec_version: 1
 phase_gates:
   requirements: approved      # approved | pending | needs_work
   design: pending             # approved | pending | skipped (MICRO/SMALL sem @architect)
@@ -255,6 +269,38 @@ AskUserQuestion:
     - label: "Todos aprovados"
 ```
 
+### Conformance contract (MEDIUM only)
+
+If classification is MEDIUM, also generate `.aioson/context/conformance-{slug}.yaml` — a YAML file that structures each AC into machine-readable format:
+
+```yaml
+# Conformance Contract — {feature}
+# Generated by: @analyst
+# Verified by: @qa
+
+feature: {slug}
+spec_version: 1
+generated_at: {ISO-date}
+
+acceptance_criteria:
+  - id: AC-{slug}-01
+    description: "..."
+    type: behavior    # behavior | data | security | performance
+    preconditions:
+      - "..."
+    action: "..."
+    expected:
+      - "..."
+    negative_cases:
+      - input: "..."
+        expected: "..."
+```
+
+Rules:
+- Only for MEDIUM classification — do not generate for MICRO or SMALL
+- @qa uses it as a structured verification checklist
+- @dev uses it to understand exact expected behavior for test writing
+
 Then tell the user: "Feature spec ready. Activate **@dev** to implement — it will read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`."
 
 ## MICRO shortcut
@@ -298,6 +344,7 @@ Generate `.aioson/context/discovery.md` with the following sections:
 - Do not finalize any output file with missing or assumed fields.
 - In feature mode: never duplicate content already in `discovery.md` — only document what is new or changed.
 - If `readiness.md` already says the context is sufficiently clear, do not reopen broad discovery without a good reason.
+- At session end, before registering, update the project pulse via CLI: `aioson pulse:update . --agent=analyst --feature={slug} --gate="Gate A: approved" --action="<discovery summary>" --next="<next agent recommendation>" 2>/dev/null || true`. If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually.
 - At session end, after writing the discovery file, register the session: `aioson agent:done . --agent=analyst --summary="<one-line summary of discovery produced>" 2>/dev/null || true`
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
 
@@ -309,3 +356,17 @@ Ative: `/architect` ou `/dev`
 
 Também disponível: `/sheldon` (enriquecimento adicional), `/qa` (revisão dos requisitos)
 ---
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Domain modeled: [scope]
+- Next step: `@architect` (technical decisions) or `@product` (PRD refinement) or `/sheldon` (enrichment)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---