sdd-agent-platform 0.4.0 → 0.4.2

package/node_modules/@sdd-agent-platform/core/src/execution/background-executor.ts

@@ -6,7 +6,7 @@ import { createDelegationRecord, isDelegationTerminal } from '../delegation/vali
 import { listDelegationQueueItems } from '../delegation/queue.js';
 import { persistDelegation } from '../delegation/run-state.js';
 import { evaluateGovernancePolicy } from '../governance/policy.js';
-import { getRunRelativeArtifactPath, toArtifactRootRelativePath } from '../runtime-paths.js';
+import { normalizeStageEvidenceOrLegacyArtifactRef, toBranchStageEvidenceRef } from '../runtime-paths.js';
 import { appendEvent } from '../run-state/events.js';
 import { createRun, readRunState, writeRunState } from '../run-state/run-state.js';
 import type { DelegationQueueItem } from '../run-state/run-index.js';
@@ -119,10 +119,10 @@ export async function runBackgroundExecutor(projectRoot: string, options: Backgr
   }
 
   const delegationId = options.delegationId ?? `B-${options.taskId}-${agent}-001`;
-  const expectedArtifact = options.artifactPath ? getRunRelativeArtifactPath(toArtifactRootRelativePath(options.artifactPath)) : `artifacts/${agent}-${options.taskId}.md`;
+  const expectedArtifact = options.artifactPath ? normalizeStageEvidenceOrLegacyArtifactRef(options.artifactPath) : toBranchStageEvidenceRef(branch, agent === 'validator' ? 'test' : 'do', `${agent}-${options.taskId}.md`);
   const existingDelegation = boundRunState.delegations[delegationId];
-  if (existingDelegation && isDelegationTerminal(existingDelegation.status)) {
-    issues.push(contractIssue('delegationId', `Delegation ${delegationId} is already terminal.`, 'Create a new delegation id for retry instead of reopening a terminal delegation.'));
+  if (existingDelegation && isDelegationTerminal(existingDelegation.status) && !options.artifactPath) {
+    issues.push(contractIssue('delegationId', `Delegation ${delegationId} is already terminal.`, 'Rerun with an artifact path to idempotently reingest the same digest or allocate a retry attempt for changed evidence.'));
   }
 
   const governance = await evaluateGovernancePolicy(projectRoot, {

package/node_modules/@sdd-agent-platform/core/src/execution/foreground-subagents.test.ts

@@ -8,6 +8,8 @@ import { initProject } from '../config/init-project.js';
 import { readRunState } from '../run-state/run-state.js';
 import { listRuntimeProjections } from '../storage/runtime-store.js';
 import { validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { evaluateLifecycleRiskDecisionForModel, recordLifecycleRiskDecisionProjection } from '../risk.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
 import { runForegroundSubagents } from './foreground-subagents.js';
 
 const hostCommand = [
@@ -20,11 +22,17 @@ const hostCommand = [
   "process.stdout.write(result + evidence);"
 ].join('\n');
 
-test('runForegroundSubagents collects all foreground subagent artifacts without lifecycle authority', async () => {
+async function seedLifecycleRiskDecision(root: string, branch: string): Promise<void> {
+  const model = await parseSddBranch(root, branch);
+  await recordLifecycleRiskDecisionProjection(root, evaluateLifecycleRiskDecisionForModel(branch, model));
+}
+
+test('runForegroundSubagents collects non-authoritative foreground artifacts after lifecycle decision', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-foreground-subagents-'));
   try {
     await initProject(root);
     await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []).replace('packages/core/src/index.ts', 'docs/t1.md'));
+    await seedLifecycleRiskDecision(root, 'feature');
 
     const result = await runForegroundSubagents(root, {
       branch: 'feature',
@@ -35,7 +43,7 @@ test('runForegroundSubagents collects all foreground subagent artifacts without
 
     assert.equal(result.status, 'completed');
     assert.deepEqual(result.agents.map((agent) => `${agent.agent}:${agent.status}`), ['reviewer:completed', 'validator:completed']);
-    assert.equal(result.agents.every((agent) => agent.artifactPath?.startsWith('artifacts/')), true);
+    assert.equal(result.agents.every((agent) => agent.artifactPath?.startsWith('.sdd/runs/feature/do/')), true);
     assert.equal(result.agents.every((agent) => agent.ingestion?.status === 'accepted'), true);
 
     const state = await readRunState(root, result.runId);
@@ -74,6 +82,7 @@ test('runForegroundSubagents blocks before host invocation when dependencies are
   try {
     await initProject(root);
     await writeBranchDocs(root, 'feature', `# Tasks\n\n${validTaskMarkdown('DEP1', [])}\n${validTaskMarkdown('DEP2', ['DEP1']).replace('packages/core/src/index.ts', 'docs/dep2.md')}`);
+    await seedLifecycleRiskDecision(root, 'feature');
 
     const result = await runForegroundSubagents(root, {
       branch: 'feature',

package/node_modules/@sdd-agent-platform/core/src/execution/foreground-subagents.ts

@@ -13,7 +13,7 @@ import { parseSddBranch } from '../sdd-docs/task-parser.js';
 import { routeSddTask } from '../router/route-sdd-task.js';
 import { buildAgentExecutionRecord, writeAgentExecutionRecord } from './agent-execution-records.js';
 import { invokeClaudeCodeSubagentHost, type HostInvocationCommandOptions, type HostInvocationResult } from './host-invocation.js';
-import { getRunRelativeArtifactPath, toArtifactRootRelativePath } from '../runtime-paths.js';
+import { toBranchStageEvidenceRef, toEvidencePayloadFileName } from '../runtime-paths.js';
 import { recordRuntimeProjection } from '../storage/runtime-store.js';
 import { recordSubagentDispatchProjection, recordSubagentResultProjection } from '../subagents/runtime.js';
 import type { SubagentDispatch, SubagentResult } from '../subagents/contracts.js';
@@ -122,7 +122,7 @@ export async function runForegroundSubagents(projectRoot: string, options: Foreg
 
   const slots = agents.map((agent, index) => {
     const delegationId = `F-${options.taskId}-${safeToken(agent)}-${String(index + 1).padStart(3, '0')}`;
-    const expectedArtifact = getRunRelativeArtifactPath(toArtifactRootRelativePath(`artifacts/${safeToken(agent)}-${options.taskId}-${String(index + 1).padStart(3, '0')}.md`));
+    const expectedArtifact = toBranchStageEvidenceRef(branch, 'do', `${safeToken(agent)}-${options.taskId}-${String(index + 1).padStart(3, '0')}.md`);
     return { agent, delegationId, expectedArtifact };
   });
 
@@ -342,7 +342,7 @@ function buildHostFailureDigest(taskId: string, agent: string, delegationId: str
 
 async function readArtifactText(projectRoot: string, runId: string, artifactPath: string): Promise<string> {
   try {
-    return await readArtifact(projectRoot, runId, toArtifactRootRelativePath(artifactPath));
+    return await readArtifact(projectRoot, runId, toEvidencePayloadFileName(artifactPath));
   } catch {
     return '';
   }

package/node_modules/@sdd-agent-platform/core/src/execution/host-invocation.ts

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 
 import { SDD_RESULT_CONTRACT, SDD_RESULT_VERSION } from '../contracts.js';
 import { writeArtifact } from '../run-state/artifacts.js';
+import { toEvidencePayloadFileName } from '../runtime-paths.js';
 
 export interface HostInvocationCommandOptions {
   command?: string;
@@ -41,7 +42,7 @@ export async function invokeClaudeCodeSubagentHost(input: HostInvocationInput):
   const args = resolveHostArgs(input.commandOptions?.args, prompt);
   const processResult = await runHostProcess(command, args, input.projectRoot, input.timeoutSeconds ?? 900);
   const artifactContent = buildHostArtifactContent(input, processResult.stdout, processResult.stderr, processResult.exitCode, processResult.signal, processResult.timedOut);
-  const written = await writeArtifact(input.projectRoot, input.runId, toArtifactRootRelativePath(input.expectedArtifact), artifactContent);
+  await writeArtifact(input.projectRoot, input.runId, toEvidencePayloadFileName(input.expectedArtifact), artifactContent);
 
   return {
     command,
@@ -49,7 +50,7 @@ export async function invokeClaudeCodeSubagentHost(input: HostInvocationInput):
     exitCode: processResult.exitCode,
     signal: processResult.signal,
     timedOut: processResult.timedOut,
-    artifactPath: written.runRelativePath,
+    artifactPath: input.expectedArtifact,
     stdoutBytes: Buffer.byteLength(processResult.stdout, 'utf8'),
     stderrBytes: Buffer.byteLength(processResult.stderr, 'utf8')
   };
@@ -68,8 +69,8 @@ Expected result artifact: ${input.expectedArtifact}
 
 Rules:
 - Work only on this one delegation.
-- Do not run sync-back, ship, or workflow transition commands.
-- Do not claim approval, sync-back readiness, ship readiness, lifecycle completion, or authoritative PASS unless backed by valid evidence policy.
+- Do not run ship or workflow transition commands.
+- Do not claim approval, truth-alignment readiness, ship readiness, lifecycle completion, or authoritative PASS unless backed by valid evidence policy.
 - Treat your summary as non-authoritative guidance for the parent main agent.
 - Do not bypass Claude Code permission prompts.
 - Never create, edit, delete, move, or rewrite production/source files.

package/node_modules/@sdd-agent-platform/core/src/execution/resident-worker.test.ts

@@ -11,6 +11,9 @@ import { writeArtifact } from '../run-state/artifacts.js';
 import { inspectRun } from '../run-state/inspect-run.js';
 import { readRunState } from '../run-state/run-state.js';
 import { validResultArtifact, validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { writeVerifyContract } from '../verification/verify-contract.js';
+import { evaluateLifecycleRiskDecisionForModel, recordLifecycleRiskDecisionProjection } from '../risk.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
 import { runBackgroundExecutor } from './background-executor.js';
 import {
   claimResidentWorkerRuntime,
@@ -21,11 +24,18 @@ import {
   writeResidentWorkerRuntimeRecord
 } from './resident-worker.js';
 
+async function seedLifecycleRiskDecision(root: string, branch: string): Promise<void> {
+  const model = await parseSddBranch(root, branch);
+  await recordLifecycleRiskDecisionProjection(root, evaluateLifecycleRiskDecisionForModel(branch, model));
+}
+
 test('resident worker runtime claim persists run-bound runtime evidence', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-resident-worker-claim-'));
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const result = await claimResidentWorkerRuntime(root, { taskId: 'B1', runtimeId: 'R-B1-implementer-test', leaseSeconds: 60 });
     const runtime = await readResidentWorkerRuntimeRecord(root, result.runId, 'R-B1-implementer-test');
@@ -36,7 +46,7 @@ test('resident worker runtime claim persists run-bound runtime evidence', async
     assert.equal(result.status, 'claimed');
     assert.equal(result.delegationId, 'B-B1-implementer-001');
     assert.equal(runtime.runtimeId, 'R-B1-implementer-test');
-    assert.equal(runtime.expectedArtifact, 'artifacts/implementer-B1.md');
+    assert.equal(runtime.expectedArtifact, '.sdd/runs/master/do/implementer-B1.md');
     assert.equal(list.runtimes.length, 1);
     assert.equal(list.activeRuntimes, 1);
     assert.equal(inspection.workerRuntimes.length, 1);
@@ -51,6 +61,8 @@ test('resident worker runtime heartbeat renews lease without completing task', a
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const claimed = await claimResidentWorkerRuntime(root, { taskId: 'B1', runtimeId: 'R-B1-heartbeat', leaseSeconds: 60 });
     const before = claimed.runtime?.leaseExpiresAt;
@@ -74,6 +86,8 @@ test('resident worker runtime stale lease is visible to status and doctor', asyn
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const claimed = await claimResidentWorkerRuntime(root, { taskId: 'B1', runtimeId: 'R-B1-stale', leaseSeconds: 60 });
     assert.ok(claimed.runtime);
@@ -104,6 +118,8 @@ test('resident worker runtime heartbeat does not reopen terminal delegations', a
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+    await seedLifecycleRiskDecision(root, 'master');
 
     const claimed = await claimResidentWorkerRuntime(root, { taskId: 'B1', runtimeId: 'R-B1-terminal', leaseSeconds: 60 });
     await writeArtifact(root, claimed.runId, 'implementer-B1.md', validResultArtifact('implementer', 'B1', 'PASS', 'artifacts/implementer-B1.md'));

package/node_modules/@sdd-agent-platform/core/src/execution/resident-worker.ts

@@ -1,13 +1,14 @@
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
 import { contractIssue, messageFromError, type ContractValidationIssue } from '../contracts/issues.js';
 import { listDelegationQueueItems } from '../delegation/queue.js';
 import { isDelegationTerminal } from '../delegation/validation.js';
-import { getWorkerRuntimeRecordPath, getWorkerRuntimesDir } from '../runtime-paths.js';
+import { getLegacyWorkerRuntimeRecordPath, getLegacyWorkerRuntimesDir, toBranchStageEvidenceRef } from '../runtime-paths.js';
 import { appendEvent } from '../run-state/events.js';
 import { readRunState, writeRunState } from '../run-state/run-state.js';
 import { exists } from '../storage/json-io.js';
+import { listRuntimeWorkerRuntimes, readRuntimeWorkerRuntime, recordRuntimeWorkerRuntime } from '../storage/runtime-store.js';
 import type { DelegationQueueItem } from '../run-state/run-index.js';
 import { inspectWorkerAdapterContract, type WorkerAdapterContract } from '../registries/worker-adapters.js';
 import { toSafeRecordId } from './agent-execution-records.js';
@@ -108,18 +109,25 @@ export interface ResidentWorkerRuntimeList {
 }
 
 export async function writeResidentWorkerRuntimeRecord(projectRoot: string, record: ResidentWorkerRuntimeRecord): Promise<ResidentWorkerRuntimeRecord> {
-  await mkdir(getWorkerRuntimesDir(projectRoot, record.runId), { recursive: true });
-  await writeFile(getWorkerRuntimeRecordPath(projectRoot, record.runId, record.runtimeId), `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+  await recordRuntimeWorkerRuntime(projectRoot, record);
   return record;
 }
 
 export async function readResidentWorkerRuntimeRecord(projectRoot: string, runId: string, runtimeId: string): Promise<ResidentWorkerRuntimeRecord> {
-  const raw = await readFile(getWorkerRuntimeRecordPath(projectRoot, runId, runtimeId), 'utf8');
+  const runtimeRecord = await readRuntimeWorkerRuntime(projectRoot, runId, runtimeId);
+  if (runtimeRecord) {
+    return runtimeRecord;
+  }
+  const raw = await readFile(getLegacyWorkerRuntimeRecordPath(projectRoot, runId, runtimeId), 'utf8');
   return JSON.parse(raw) as ResidentWorkerRuntimeRecord;
 }
 
 export async function listResidentWorkerRuntimeRecords(projectRoot: string, runId: string): Promise<ResidentWorkerRuntimeRecord[]> {
-  const recordsDir = getWorkerRuntimesDir(projectRoot, runId);
+  const runtimeRecords = await listRuntimeWorkerRuntimes(projectRoot, runId);
+  if (runtimeRecords.length > 0) {
+    return runtimeRecords;
+  }
+  const recordsDir = getLegacyWorkerRuntimesDir(projectRoot, runId);
   if (!await exists(recordsDir)) {
     return [];
   }
@@ -173,6 +181,7 @@ export async function claimResidentWorkerRuntime(projectRoot: string, options: R
   const state = await readRunState(projectRoot, backgroundResult.runId);
   const delegation = state.delegations[backgroundResult.delegationId];
   const now = new Date().toISOString();
+  const branch = state.gitBranch ?? state.partition ?? 'unscoped';
   const runtime: ResidentWorkerRuntimeRecord = {
     version: RESIDENT_WORKER_RUNTIME_CONTRACT_VERSION,
     runtimeId,
@@ -182,7 +191,7 @@ export async function claimResidentWorkerRuntime(projectRoot: string, options: R
     workerAdapterId,
     delegationId: backgroundResult.delegationId,
     queueItemId: backgroundResult.queueItemId,
-    expectedArtifact: delegation?.expectedArtifact ?? `artifacts/${agent}-${options.taskId}.md`,
+    expectedArtifact: delegation?.expectedArtifact ?? toBranchStageEvidenceRef(branch, agent === 'validator' ? 'test' : 'do', `${agent}-${options.taskId}.md`),
     status: 'claimed',
     claimedAt: now,
     lastHeartbeatAt: null,

package/node_modules/@sdd-agent-platform/core/src/execution/stage-team-runtime.test.ts

@@ -0,0 +1,102 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { STAGE_TEAM_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+import { assertAdvisoryAssessment, assertValidFanInEvidenceSet, assertValidStageRoleResult, buildFanInEvidenceSet, describeStageTeamActivation, type FanInEvidenceSetRecord, type LlmAdvisorAssessmentRecord, type StageRoleResultRecord } from './stage-team-runtime.js';
+
+test('stage role results reject lifecycle transition authority fields', () => {
+  const result = roleResult({ payload: { final_pass: true } });
+
+  assert.throws(() => assertValidStageRoleResult(result), /final_pass/);
+  assert.throws(() => assertValidStageRoleResult({ ...roleResult(), truthAlignmentApproved: true }), /truthAlignmentApproved/);
+  assert.doesNotThrow(() => assertValidStageRoleResult(roleResult()));
+});
+
+test('advisor assessments are advisory-only and cannot carry lifecycle transitions', () => {
+  assert.throws(() => assertAdvisoryAssessment(advisor({ advisoryOnly: false } as unknown as Partial<LlmAdvisorAssessmentRecord>)), /advisoryOnly=true/);
+  assert.throws(() => assertAdvisoryAssessment(advisor({ payload: { ship_ready: true } })), /ship_ready/);
+  assert.doesNotThrow(() => assertAdvisoryAssessment(advisor()));
+  assert.throws(() => assertAdvisoryAssessment(advisor({ validity: 'unknown' } as unknown as Partial<LlmAdvisorAssessmentRecord>)), /validity/);
+  assert.throws(() => assertAdvisoryAssessment(advisor({ confidence: 'none' } as unknown as Partial<LlmAdvisorAssessmentRecord>)), /confidence/);
+});
+
+test('fan-in evidence set is gate input only and deduplicates referenced inputs', () => {
+  const fanIn = buildFanInEvidenceSet({
+    fanInId: 'fanin-001',
+    partition: 'feature',
+    runId: 'run-001',
+    taskId: 'T1',
+    stage: 'test',
+    roleResultIds: ['role-result-2', 'role-result-1', 'role-result-1'],
+    durableGapIds: ['gap-1'],
+    proposalRefs: ['proposal.md'],
+    advisorAssessmentIds: ['advisor-1'],
+    evidenceRefs: ['artifacts/validation-T1.md'],
+    canonicalEvidenceRefs: ['payload-1'],
+    createdAt: '2026-01-01T00:00:00.000Z',
+    payload: { note: 'input only' }
+  });
+
+  assert.equal(fanIn.gateInputOnly, true);
+  assert.deepEqual(fanIn.roleResultIds, ['role-result-1', 'role-result-2']);
+  assert.throws(() => buildFanInEvidenceSet({ ...fanIn, payload: { stagePassed: true } }), /stagePassed/);
+  assert.throws(() => assertValidFanInEvidenceSet({ ...fanIn, gateInputOnly: false } as unknown as FanInEvidenceSetRecord), /gateInputOnly=true/);
+});
+
+test('lifecycle profiles explain team activation without requiring direct team mode', () => {
+  const direct = describeStageTeamActivation('direct');
+  const recover = describeStageTeamActivation('recover');
+
+  assert.equal(direct.requiredTeam, false);
+  assert.equal(direct.roles.length, 0);
+  assert.equal(recover.requiredTeam, true);
+  assert.equal(recover.roles.some((role) => role.roleId === 'role.sync-risk-reviewer' && role.required), true);
+});
+
+function roleResult(overrides: Partial<StageRoleResultRecord> & Record<string, unknown> = {}): StageRoleResultRecord & Record<string, unknown> {
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    resultId: 'role-result-001',
+    sessionId: 'session-001',
+    assignmentId: 'assignment-001',
+    partition: 'feature',
+    runId: 'run-001',
+    taskId: 'T1',
+    roleId: 'role.evidence-runner',
+    agentId: 'validator',
+    outputKind: 'evidence',
+    authorityCeiling: 'gate_input',
+    status: 'accepted',
+    summary: 'Collected validation evidence.',
+    evidenceRefs: ['artifacts/validation-T1.md'],
+    durableGapIds: [],
+    proposalRefs: [],
+    advisorAssessmentIds: [],
+    createdAt: '2026-01-01T00:00:00.000Z',
+    payload: {},
+    ...overrides
+  };
+}
+
+function advisor(overrides: Partial<LlmAdvisorAssessmentRecord> & Record<string, unknown> = {}): LlmAdvisorAssessmentRecord & Record<string, unknown> {
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    assessmentId: 'advisor-001',
+    sessionId: 'session-001',
+    partition: 'feature',
+    runId: 'run-001',
+    taskId: 'T1',
+    kind: 'evidence_sufficiency',
+    concern: 'medium',
+    validity: 'valid',
+    confidence: 'high',
+    advisoryOnly: true,
+    summary: 'Evidence is sufficient for gate input, pending deterministic checks.',
+    evidenceRefs: ['artifacts/validation-T1.md'],
+    durableGapIds: [],
+    proposalRefs: [],
+    createdAt: '2026-01-01T00:00:00.000Z',
+    payload: {},
+    ...overrides
+  };
+}

package/node_modules/@sdd-agent-platform/core/src/execution/stage-team-runtime.ts

@@ -0,0 +1,271 @@
+import { STAGE_TEAM_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+
+export type StageTeamLifecycleProfile = 'direct' | 'compact' | 'full' | 'research' | 'recover';
+export type StageTeamStage = 'spec' | 'plan' | 'tasks' | 'verifies' | 'do' | 'test' | 'review' | 'ship' | 'recover';
+export type StageTeamSessionStatus = 'planned' | 'running' | 'completed' | 'blocked' | 'cancelled';
+export type StageRoleAssignmentStatus = 'assigned' | 'running' | 'completed' | 'blocked' | 'skipped';
+export type StageRoleResultStatus = 'accepted' | 'candidate' | 'rejected' | 'superseded';
+export type StageRoleResultKind = 'evidence' | 'review' | 'gap' | 'proposal' | 'diagnostic' | 'gate_assessment';
+export type StageRoleAuthorityCeiling = 'advisory_only' | 'evidence_input' | 'proposal_input' | 'gate_input';
+export type LlmAdvisorAssessmentKind = 'evidence_sufficiency' | 'gap_classification' | 'semantic_drift' | 'writeback_classification' | 'risk_escalation' | 'recovery_suggestion';
+export type LlmAdvisorConcern = 'none' | 'low' | 'medium' | 'high';
+export type LlmAdvisorValidity = 'valid' | 'invalid';
+export type LlmAdvisorConfidence = 'low' | 'medium' | 'high';
+
+export interface StageRoleProfileActivation {
+  roleId: string;
+  required: boolean;
+  advisory: boolean;
+  reason: string;
+}
+
+export interface StageTeamActivationProfile {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  profile: StageTeamLifecycleProfile;
+  requiredTeam: boolean;
+  roles: StageRoleProfileActivation[];
+  reason: string;
+}
+
+export interface StageTeamSessionRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  sessionId: string;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  stage: StageTeamStage;
+  lifecycleProfile: StageTeamLifecycleProfile;
+  status: StageTeamSessionStatus;
+  createdAt: string;
+  updatedAt: string;
+  assignments: StageRoleAssignment[];
+  payload: unknown;
+}
+
+export interface StageRoleAssignment {
+  assignmentId: string;
+  roleId: string;
+  agentId: string | null;
+  status: StageRoleAssignmentStatus;
+  required: boolean;
+  authorityCeiling: StageRoleAuthorityCeiling;
+  materialRefs: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface StageRoleResultRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  resultId: string;
+  sessionId: string;
+  assignmentId: string;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  roleId: string;
+  agentId: string | null;
+  outputKind: StageRoleResultKind;
+  authorityCeiling: StageRoleAuthorityCeiling;
+  status: StageRoleResultStatus;
+  summary: string;
+  evidenceRefs: string[];
+  durableGapIds: string[];
+  proposalRefs: string[];
+  advisorAssessmentIds: string[];
+  createdAt: string;
+  payload: unknown;
+}
+
+export interface LlmAdvisorAssessmentRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  assessmentId: string;
+  sessionId: string | null;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  kind: LlmAdvisorAssessmentKind;
+  concern: LlmAdvisorConcern;
+  validity: LlmAdvisorValidity;
+  confidence: LlmAdvisorConfidence;
+  advisoryOnly: true;
+  summary: string;
+  evidenceRefs: string[];
+  durableGapIds: string[];
+  proposalRefs: string[];
+  createdAt: string;
+  payload: unknown;
+}
+
+export interface FanInEvidenceSetRecord {
+  contract: typeof STAGE_TEAM_RUNTIME_CONTRACT_VERSION;
+  fanInId: string;
+  partition: string;
+  runId: string | null;
+  taskId: string | null;
+  stage: StageTeamStage;
+  roleResultIds: string[];
+  durableGapIds: string[];
+  proposalRefs: string[];
+  advisorAssessmentIds: string[];
+  evidenceRefs: string[];
+  canonicalEvidenceRefs: string[];
+  gateInputOnly: true;
+  createdAt: string;
+  payload: unknown;
+}
+
+const FORBIDDEN_LIFECYCLE_FIELDS = new Set([
+  'stage_passed',
+  'stagePassed',
+  'task_completed',
+  'taskCompleted',
+  'truth_alignment_approved',
+  'truthAlignmentApproved',
+  'ship_ready',
+  'shipReady',
+  'final_pass',
+  'finalPass'
+]);
+
+export function assertValidStageRoleResult(value: StageRoleResultRecord | Record<string, unknown>): asserts value is StageRoleResultRecord {
+  const forbidden = firstForbiddenLifecycleField(value);
+  if (forbidden) {
+    throw new Error(`RoleResult cannot carry lifecycle transition field ${forbidden}.`);
+  }
+  const outputKind = (value as { outputKind?: unknown }).outputKind;
+  if (!isStageRoleResultKind(outputKind)) {
+    throw new Error(`RoleResult outputKind must be one of evidence, review, gap, proposal, diagnostic, gate_assessment.`);
+  }
+  const authorityCeiling = (value as { authorityCeiling?: unknown }).authorityCeiling;
+  if (!isStageRoleAuthorityCeiling(authorityCeiling)) {
+    throw new Error(`RoleResult authorityCeiling is invalid.`);
+  }
+}
+
+export function assertAdvisoryAssessment(value: LlmAdvisorAssessmentRecord | Record<string, unknown>): asserts value is LlmAdvisorAssessmentRecord {
+  const forbidden = firstForbiddenLifecycleField(value);
+  if (forbidden) {
+    throw new Error(`LLM advisor assessment cannot carry lifecycle transition field ${forbidden}.`);
+  }
+  if ((value as { advisoryOnly?: unknown }).advisoryOnly !== true) {
+    throw new Error('LLM advisor assessment must be advisoryOnly=true.');
+  }
+  const validity = (value as { validity?: unknown }).validity;
+  if (validity !== 'valid' && validity !== 'invalid') {
+    throw new Error('LLM advisor assessment validity must be valid or invalid.');
+  }
+  const confidence = (value as { confidence?: unknown }).confidence;
+  if (confidence !== 'low' && confidence !== 'medium' && confidence !== 'high') {
+    throw new Error('LLM advisor assessment confidence must be low, medium, or high.');
+  }
+}
+
+export function assertValidFanInEvidenceSet(value: FanInEvidenceSetRecord | Record<string, unknown>): asserts value is FanInEvidenceSetRecord {
+  const forbidden = firstForbiddenLifecycleField(value);
+  if (forbidden) {
+    throw new Error(`FanInEvidenceSet cannot carry lifecycle transition field ${forbidden}.`);
+  }
+  if ((value as { gateInputOnly?: unknown }).gateInputOnly !== true) {
+    throw new Error('FanInEvidenceSet must be gateInputOnly=true.');
+  }
+}
+
+export function buildFanInEvidenceSet(input: Omit<FanInEvidenceSetRecord, 'contract' | 'gateInputOnly'>): FanInEvidenceSetRecord {
+  assertValidFanInEvidenceSet({ ...input, gateInputOnly: true });
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    ...input,
+    roleResultIds: sortedUnique(input.roleResultIds),
+    durableGapIds: sortedUnique(input.durableGapIds),
+    proposalRefs: sortedUnique(input.proposalRefs),
+    advisorAssessmentIds: sortedUnique(input.advisorAssessmentIds),
+    evidenceRefs: sortedUnique(input.evidenceRefs),
+    canonicalEvidenceRefs: sortedUnique(input.canonicalEvidenceRefs),
+    gateInputOnly: true
+  };
+}
+
+export function describeStageTeamActivation(profile: StageTeamLifecycleProfile): StageTeamActivationProfile {
+  const roles = activationRoles(profile);
+  return {
+    contract: STAGE_TEAM_RUNTIME_CONTRACT_VERSION,
+    profile,
+    requiredTeam: profile !== 'direct',
+    roles,
+    reason: activationReason(profile)
+  };
+}
+
+function activationRoles(profile: StageTeamLifecycleProfile): StageRoleProfileActivation[] {
+  switch (profile) {
+    case 'direct':
+      return [];
+    case 'compact':
+      return [activationRole('role.implementation-reviewer', true, false, 'Compact profile adds one independent reviewer for bounded risk.')];
+    case 'full':
+      return [
+        activationRole('role.norm-scout', true, true, 'Full profile checks project norms before stage output.'),
+        activationRole('role.implementation-reviewer', true, false, 'Full profile requires implementation or contract review.'),
+        activationRole('role.evidence-runner', true, false, 'Full profile requires evidence collection as gate input.')
+      ];
+    case 'research':
+      return [
+        activationRole('role.norm-scout', true, true, 'Research profile gathers external and project norm context.'),
+        activationRole('role.uncertainty-reviewer', true, true, 'Research profile records unresolved ambiguity as advisory input.'),
+        activationRole('role.performance-planner', false, true, 'Research profile can add performance/token planning when relevant.')
+      ];
+    case 'recover':
+      return [
+        activationRole('role.context-curator', true, true, 'Recover profile reconstructs trusted context.'),
+        activationRole('role.sync-risk-reviewer', true, false, 'Recover profile reviews shared-state/writeback risk.'),
+        activationRole('role.verification-designer', true, false, 'Recover profile rebuilds validation needs before retry.')
+      ];
+  }
+}
+
+function activationRole(roleId: string, required: boolean, advisory: boolean, reason: string): StageRoleProfileActivation {
+  return { roleId, required, advisory, reason };
+}
+
+function activationReason(profile: StageTeamLifecycleProfile): string {
+  switch (profile) {
+    case 'direct':
+      return 'Direct profile does not require team activation; deterministic checks and explicit artifacts remain sufficient.';
+    case 'compact':
+      return 'Compact profile activates a minimal independent role for moderate risk without slowing simple flows.';
+    case 'full':
+      return 'Full profile activates norm, review, and evidence roles for high-risk implementation paths.';
+    case 'research':
+      return 'Research profile activates context and uncertainty roles for decisions that need broader evidence.';
+    case 'recover':
+      return 'Recover profile activates context, sync-risk, and verification roles because prior workflow evidence is blocked or stale.';
+  }
+}
+
+function isStageRoleResultKind(value: unknown): value is StageRoleResultKind {
+  return value === 'evidence' || value === 'review' || value === 'gap' || value === 'proposal' || value === 'diagnostic' || value === 'gate_assessment';
+}
+
+function isStageRoleAuthorityCeiling(value: unknown): value is StageRoleAuthorityCeiling {
+  return value === 'advisory_only' || value === 'evidence_input' || value === 'proposal_input' || value === 'gate_input';
+}
+
+function firstForbiddenLifecycleField(value: unknown): string | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    if (FORBIDDEN_LIFECYCLE_FIELDS.has(key)) {
+      return key;
+    }
+    const nested = firstForbiddenLifecycleField(child);
+    if (nested) {
+      return nested;
+    }
+  }
+  return null;
+}
+
+function sortedUnique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort();
+}