sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,352 @@
+import { createHash } from 'node:crypto';
+
+import type { RuntimeProjectionEnvelope, RuntimeRef, RuntimeScope, RuntimeProjectionStaleness, SddStage } from '../contracts.js';
+import { readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, runtimeProjectionStaleness, listRuntimeProjections, type RuntimeProjectionEnvelopeWriteResult } from '../storage/runtime-store.js';
+import type { LifecycleRiskDecision } from '../risk/contracts.js';
+import type { StageRun, StageRunStatus, WorkflowHandoff, WorkflowHandoffStatus } from './contracts.js';
+
+export const STAGE_RUNTIME_PRODUCER_VERSION = 'phase8-stage-runtime-v1';
+export const STAGE_RUN_PROJECTION_TYPE = 'phase8_stage_run';
+export const WORKFLOW_HANDOFF_PROJECTION_TYPE = 'phase8_workflow_handoff';
+
+const STAGE_RUN_TRANSITIONS: Record<StageRunStatus, readonly StageRunStatus[]> = {
+  pending: ['active', 'blocked', 'skipped'],
+  active: ['completed', 'blocked', 'failed'],
+  blocked: ['active', 'skipped', 'failed'],
+  completed: [],
+  skipped: [],
+  failed: []
+};
+
+const WORKFLOW_HANDOFF_TRANSITIONS: Record<WorkflowHandoffStatus, readonly WorkflowHandoffStatus[]> = {
+  proposed: ['accepted', 'rejected', 'blocked'],
+  blocked: ['proposed', 'rejected'],
+  accepted: [],
+  rejected: []
+};
+
+export interface StageRuntimeValidationResult {
+  valid: boolean;
+  issues: string[];
+}
+
+export interface StageRunTransitionResult extends StageRuntimeValidationResult {
+  stageRun: StageRun;
+}
+
+export interface WorkflowHandoffTransitionResult extends StageRuntimeValidationResult {
+  handoff: WorkflowHandoff;
+}
+
+export interface WorkflowHandoffValidationInput {
+  handoff: WorkflowHandoff;
+  sourceStageRun?: StageRun | null;
+  lifecycleRiskDecision?: LifecycleRiskDecision | null;
+}
+
+export interface WorkflowHandoffValidationResult extends StageRuntimeValidationResult {
+  recommendedStatus: WorkflowHandoffStatus;
+  considered: {
+    sourceStageStatus: StageRunStatus | null;
+    lifecycleRiskProfile: LifecycleRiskDecision['profile'] | null;
+    lifecycleApprovalPolicy: LifecycleRiskDecision['approvalPolicy'] | null;
+    requiredInputRefs: number;
+    outputRefs: number;
+    evidenceRefs: number;
+    openQuestions: number;
+    blockingGaps: number;
+  };
+}
+
+export type WorkflowStageHandoffDiagnosticStatus = 'missing' | 'fresh' | 'stale' | 'blocked' | 'rejected' | 'incompatible';
+
+export interface WorkflowStageHandoffDiagnostic {
+  status: WorkflowStageHandoffDiagnosticStatus;
+  branch: string;
+  activeStage: StageRun | null;
+  latestStageRun: StageRun | null;
+  latestHandoff: WorkflowHandoff | null;
+  latestStageStaleness: RuntimeProjectionStaleness;
+  latestHandoffStaleness: RuntimeProjectionStaleness;
+  projectionCounts: {
+    stageRuns: number;
+    handoffs: number;
+  };
+  reasons: string[];
+}
+
+export function canTransitionStageRun(from: StageRunStatus, to: StageRunStatus): boolean {
+  return STAGE_RUN_TRANSITIONS[from].includes(to);
+}
+
+export function transitionStageRun(stageRun: StageRun, status: StageRunStatus, options: { updatedAt?: string; outputRefs?: RuntimeRef[]; blockingReasons?: string[] } = {}): StageRunTransitionResult {
+  if (!canTransitionStageRun(stageRun.status, status)) {
+    return {
+      valid: false,
+      issues: [`Illegal stage transition ${stageRun.status} -> ${status} for ${stageRun.stage}.`],
+      stageRun
+    };
+  }
+  const next: StageRun = {
+    ...stageRun,
+    status,
+    outputRefs: options.outputRefs ?? stageRun.outputRefs,
+    blockingReasons: options.blockingReasons ?? stageRun.blockingReasons,
+    updatedAt: options.updatedAt ?? new Date().toISOString()
+  };
+  return { valid: true, issues: validateStageRun(next).issues, stageRun: next };
+}
+
+export function canTransitionWorkflowHandoff(from: WorkflowHandoffStatus, to: WorkflowHandoffStatus): boolean {
+  return WORKFLOW_HANDOFF_TRANSITIONS[from].includes(to);
+}
+
+export function transitionWorkflowHandoff(handoff: WorkflowHandoff, status: WorkflowHandoffStatus, options: { decidedAt?: string; blockingGaps?: string[]; openQuestions?: string[] } = {}): WorkflowHandoffTransitionResult {
+  if (!canTransitionWorkflowHandoff(handoff.status, status)) {
+    return {
+      valid: false,
+      issues: [`Illegal handoff transition ${handoff.status} -> ${status} for ${handoff.fromStage} -> ${handoff.toStage}.`],
+      handoff
+    };
+  }
+  const next: WorkflowHandoff = {
+    ...handoff,
+    status,
+    blockingGaps: options.blockingGaps ?? handoff.blockingGaps,
+    openQuestions: options.openQuestions ?? handoff.openQuestions,
+    decidedAt: options.decidedAt ?? new Date().toISOString()
+  };
+  return { valid: true, issues: [], handoff: next };
+}
+
+export function validateStageRun(stageRun: StageRun): StageRuntimeValidationResult {
+  const issues: string[] = [];
+  if (isSubagentRole(stageRun.ownerAgent)) {
+    issues.push(`Stage owner ${stageRun.ownerAgent} is a subagent; subagents cannot own lifecycle stages.`);
+  }
+  if ((stageRun.status === 'blocked' || stageRun.status === 'failed') && stageRun.blockingReasons.length === 0) {
+    issues.push(`Stage ${stageRun.stage} is ${stageRun.status} but has no blocking reason.`);
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+export function validateWorkflowHandoff(input: WorkflowHandoffValidationInput): WorkflowHandoffValidationResult {
+  const issues: string[] = [];
+  const { handoff, sourceStageRun, lifecycleRiskDecision } = input;
+  if (!sourceStageRun) {
+    issues.push('Handoff source stage run is missing.');
+  } else if (sourceStageRun.stage !== handoff.fromStage) {
+    issues.push(`Handoff source stage ${handoff.fromStage} does not match stage run ${sourceStageRun.stage}.`);
+  } else if (!['completed', 'skipped'].includes(sourceStageRun.status)) {
+    issues.push(`Handoff source stage ${handoff.fromStage} is ${sourceStageRun.status}; only completed or skipped stages can hand off control.`);
+  }
+  if (!lifecycleRiskDecision) {
+    issues.push('Lifecycle risk decision is missing for handoff validation.');
+  } else if (lifecycleRiskDecision.profile === 'blocked' || lifecycleRiskDecision.approvalPolicy === 'blocked') {
+    issues.push('Lifecycle risk decision blocks workflow handoff.');
+  }
+  if (handoff.requiredInputRefs.length === 0) {
+    issues.push('Handoff has no required input refs.');
+  }
+  if (handoff.outputRefs.length === 0) {
+    issues.push('Handoff has no source output refs.');
+  }
+  if (requiresEvidenceForHandoff(handoff.toStage) && handoff.evidenceRefs.length === 0) {
+    issues.push(`Handoff to ${handoff.toStage} has no evidence refs.`);
+  }
+  if (handoff.openQuestions.length > 0) {
+    issues.push(`Handoff has open questions: ${handoff.openQuestions.join(' ')}`);
+  }
+  if (handoff.blockingGaps.length > 0) {
+    issues.push(`Handoff has blocking gaps: ${handoff.blockingGaps.join(' ')}`);
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+    recommendedStatus: issues.length === 0 ? 'proposed' : 'blocked',
+    considered: {
+      sourceStageStatus: sourceStageRun?.status ?? null,
+      lifecycleRiskProfile: lifecycleRiskDecision?.profile ?? null,
+      lifecycleApprovalPolicy: lifecycleRiskDecision?.approvalPolicy ?? null,
+      requiredInputRefs: handoff.requiredInputRefs.length,
+      outputRefs: handoff.outputRefs.length,
+      evidenceRefs: handoff.evidenceRefs.length,
+      openQuestions: handoff.openQuestions.length,
+      blockingGaps: handoff.blockingGaps.length
+    }
+  };
+}
+
+export function stageRunScopeKey(scope: RuntimeScope, stage: SddStage): string {
+  return [scope.branch, scope.taskId ?? 'all', scope.runId ?? 'none', scope.changeRef ?? 'none', stage].join(':');
+}
+
+export function workflowHandoffScopeKey(scope: RuntimeScope, fromStage: SddStage, toStage: SddStage): string {
+  return [scope.branch, scope.taskId ?? 'all', scope.runId ?? 'none', scope.changeRef ?? 'none', fromStage, toStage].join(':');
+}
+
+export async function recordStageRunProjection(projectRoot: string, stageRun: StageRun): Promise<RuntimeProjectionEnvelopeWriteResult<StageRun>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: STAGE_RUN_PROJECTION_TYPE,
+    scopeKey: stageRunScopeKey(stageRun.scope, stageRun.stage),
+    inputHash: stageRunInputHash(stageRun),
+    producer: 'phase8-stage-runtime',
+    producerVersion: STAGE_RUNTIME_PRODUCER_VERSION,
+    generatedAt: stageRun.updatedAt,
+    payload: stageRun
+  });
+}
+
+export async function readStageRunProjection(projectRoot: string, scope: RuntimeScope, stage: SddStage): Promise<RuntimeProjectionEnvelope<StageRun> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, STAGE_RUN_PROJECTION_TYPE, stageRunScopeKey(scope, stage));
+}
+
+export async function recordWorkflowHandoffProjection(projectRoot: string, handoff: WorkflowHandoff): Promise<RuntimeProjectionEnvelopeWriteResult<WorkflowHandoff>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: WORKFLOW_HANDOFF_PROJECTION_TYPE,
+    scopeKey: workflowHandoffScopeKey(handoff.scope, handoff.fromStage, handoff.toStage),
+    inputHash: workflowHandoffInputHash(handoff),
+    producer: 'phase8-stage-runtime',
+    producerVersion: STAGE_RUNTIME_PRODUCER_VERSION,
+    generatedAt: handoff.decidedAt ?? handoff.createdAt,
+    payload: handoff
+  });
+}
+
+export async function readWorkflowHandoffProjection(projectRoot: string, scope: RuntimeScope, fromStage: SddStage, toStage: SddStage): Promise<RuntimeProjectionEnvelope<WorkflowHandoff> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, WORKFLOW_HANDOFF_PROJECTION_TYPE, workflowHandoffScopeKey(scope, fromStage, toStage));
+}
+
+export async function inspectWorkflowStageHandoff(projectRoot: string, branch: string): Promise<WorkflowStageHandoffDiagnostic> {
+  const projections = await listRuntimeProjections(projectRoot, [STAGE_RUN_PROJECTION_TYPE, WORKFLOW_HANDOFF_PROJECTION_TYPE]);
+  const stageEnvelopes = projections
+    .filter((projection) => projection.projectionType === STAGE_RUN_PROJECTION_TYPE)
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<StageRun>)
+    .filter((envelope) => envelope?.payload?.scope?.branch === branch);
+  const handoffEnvelopes = projections
+    .filter((projection) => projection.projectionType === WORKFLOW_HANDOFF_PROJECTION_TYPE)
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<WorkflowHandoff>)
+    .filter((envelope) => envelope?.payload?.scope?.branch === branch);
+  const latestStageEnvelope = latestEnvelope(stageEnvelopes);
+  const latestHandoffEnvelope = latestEnvelope(handoffEnvelopes);
+  const activeStage = latestEnvelope(stageEnvelopes.filter((envelope) => envelope.payload.status === 'active'))?.payload ?? null;
+  const latestStageStaleness = stageEnvelopeStaleness(latestStageEnvelope);
+  const latestHandoffStaleness = handoffEnvelopeStaleness(latestHandoffEnvelope);
+  const latestHandoff = latestHandoffEnvelope?.payload ?? null;
+  const status: WorkflowStageHandoffDiagnosticStatus = !latestHandoffEnvelope
+    ? 'missing'
+    : latestStageStaleness === 'incompatible' || latestHandoffStaleness === 'incompatible'
+      ? 'incompatible'
+      : latestStageStaleness === 'stale' || latestHandoffStaleness === 'stale'
+        ? 'stale'
+        : latestHandoff?.status === 'blocked'
+          ? 'blocked'
+          : latestHandoff?.status === 'rejected'
+            ? 'rejected'
+            : 'fresh';
+
+  return {
+    status,
+    branch,
+    activeStage,
+    latestStageRun: latestStageEnvelope?.payload ?? null,
+    latestHandoff,
+    latestStageStaleness,
+    latestHandoffStaleness,
+    projectionCounts: {
+      stageRuns: stageEnvelopes.length,
+      handoffs: handoffEnvelopes.length
+    },
+    reasons: workflowStageHandoffReasons(status, latestStageEnvelope?.payload ?? null, latestHandoff)
+  };
+}
+
+function stageEnvelopeStaleness(envelope: RuntimeProjectionEnvelope<StageRun> | null): RuntimeProjectionStaleness {
+  return runtimeProjectionStaleness(envelope, {
+    inputHash: envelope ? stageRunInputHash(envelope.payload) : 'missing',
+    producerVersion: STAGE_RUNTIME_PRODUCER_VERSION
+  });
+}
+
+function handoffEnvelopeStaleness(envelope: RuntimeProjectionEnvelope<WorkflowHandoff> | null): RuntimeProjectionStaleness {
+  return runtimeProjectionStaleness(envelope, {
+    inputHash: envelope ? workflowHandoffInputHash(envelope.payload) : 'missing',
+    producerVersion: STAGE_RUNTIME_PRODUCER_VERSION
+  });
+}
+
+function workflowStageHandoffReasons(status: WorkflowStageHandoffDiagnosticStatus, latestStageRun: StageRun | null, latestHandoff: WorkflowHandoff | null): string[] {
+  if (status === 'missing') {
+    return ['Workflow handoff projection is missing; legacy next-command behavior remains authoritative.'];
+  }
+  if (status === 'stale') {
+    return ['Workflow handoff projection is stale against its current payload.'];
+  }
+  if (status === 'incompatible') {
+    return [`Workflow handoff projection producer is incompatible with ${STAGE_RUNTIME_PRODUCER_VERSION}.`];
+  }
+  if (status === 'blocked') {
+    return [`Workflow handoff is blocked: ${latestHandoff?.blockingGaps.join(' ') || latestStageRun?.blockingReasons.join(' ') || 'no blocking detail recorded'}.`];
+  }
+  if (status === 'rejected') {
+    return [`Workflow handoff ${latestHandoff?.fromStage ?? 'unknown'} -> ${latestHandoff?.toStage ?? 'unknown'} was rejected.`];
+  }
+  return [`Workflow handoff is fresh: ${latestHandoff?.fromStage ?? 'unknown'} -> ${latestHandoff?.toStage ?? 'unknown'} status=${latestHandoff?.status ?? 'none'}.`];
+}
+
+function latestEnvelope<TPayload>(envelopes: Array<RuntimeProjectionEnvelope<TPayload>>): RuntimeProjectionEnvelope<TPayload> | null {
+  return [...envelopes].sort((left, right) => right.generatedAt.localeCompare(left.generatedAt))[0] ?? null;
+}
+
+function stageRunInputHash(stageRun: StageRun): string {
+  return stableHash(JSON.stringify({
+    contract: stageRun.contract,
+    id: stageRun.id,
+    scope: stageRun.scope,
+    stage: stageRun.stage,
+    ownerAgent: stageRun.ownerAgent,
+    coMainAgents: stageRun.coMainAgents,
+    status: stageRun.status,
+    inputRefs: stageRun.inputRefs,
+    outputRefs: stageRun.outputRefs,
+    decisionRefs: stageRun.decisionRefs,
+    blockingReasons: stageRun.blockingReasons,
+    createdAt: stageRun.createdAt,
+    updatedAt: stageRun.updatedAt
+  }));
+}
+
+function workflowHandoffInputHash(handoff: WorkflowHandoff): string {
+  return stableHash(JSON.stringify({
+    contract: handoff.contract,
+    id: handoff.id,
+    scope: handoff.scope,
+    fromStage: handoff.fromStage,
+    toStage: handoff.toStage,
+    fromAgent: handoff.fromAgent,
+    toAgent: handoff.toAgent,
+    status: handoff.status,
+    outputRefs: handoff.outputRefs,
+    requiredInputRefs: handoff.requiredInputRefs,
+    riskDecisionRef: handoff.riskDecisionRef,
+    evidenceRefs: handoff.evidenceRefs,
+    openQuestions: handoff.openQuestions,
+    blockingGaps: handoff.blockingGaps,
+    createdAt: handoff.createdAt,
+    decidedAt: handoff.decidedAt ?? null
+  }));
+}
+
+function requiresEvidenceForHandoff(toStage: SddStage): boolean {
+  return toStage === 'test' || toStage === 'goal-verify' || toStage === 'sync-back' || toStage === 'ship';
+}
+
+function isSubagentRole(role: string): boolean {
+  const normalized = role.toLowerCase();
+  return normalized === 'subagent' || normalized.startsWith('subagent:') || normalized.endsWith('-subagent');
+}
+
+function stableHash(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}

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

@@ -0,0 +1,2 @@
+export * from './stage-runtime/contracts.js';
+export * from './stage-runtime/runtime.js';

package/node_modules/@sdd-agent-platform/core/src/status/project-status.test.ts

@@ -0,0 +1,288 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { setTimeout } from 'node:timers/promises';
+
+import { contextBuildTaskMarkdown, validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { getProjectStatus, getStatuslineProjection } from './project-status.js';
+import { initProject } from '../config/init-project.js';
+import { readAgentRuntimeProjectConfig as readProjectConfig } from '../router/agent-runtime-config.js';
+import { buildContextBuildPackage } from '../context/build-package.js';
+import { decideCommandTeamRuntime } from '../registries/command-team-runtime.js';
+import { STAGE_RUN_CONTRACT_VERSION, SUBAGENT_DISPATCH_CONTRACT_VERSION, WORKFLOW_HANDOFF_CONTRACT_VERSION } from '../contracts.js';
+import { recordStageRunProjection, recordWorkflowHandoffProjection, type StageRun, type WorkflowHandoff } from '../stage-runtime.js';
+import { decideContextOffload, evaluateContextLoadSignal, recordContextLoadSignalProjection, recordContextOffloadDecisionProjection } from '../context-offload.js';
+import { recordSubagentDispatchProjection, type SubagentDispatch } from '../subagents.js';
+
+const execFileAsync = promisify(execFile);
+
+async function removeTempRoot(root: string): Promise<void> {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      await rm(root, { recursive: true, force: true });
+      return;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EBUSY' || attempt === 4) {
+        throw error;
+      }
+      await setTimeout(100);
+    }
+  }
+}
+
+
+test('getProjectStatus resolves configured default SDD branch without silent master fallback', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-context-resolver-'));
+  try {
+    await initProject(root, { branch: 'feature-x' });
+    const config = await readProjectConfig(root);
+    const defaultStatus = await getProjectStatus(root);
+    const explicitStatus = await getProjectStatus(root, { branch: 'feature-x' });
+
+    assert.equal(config.sdd.default_branch, 'feature-x');
+    assert.equal(defaultStatus.context.branch, 'feature-x');
+    assert.equal(defaultStatus.context.branchSource, 'project_config');
+    assert.equal(defaultStatus.context.specDir, 'specs/feature-x');
+    assert.equal(explicitStatus.context.branch, 'feature-x');
+    assert.equal(explicitStatus.context.branchSource, 'explicit_option');
+    assert.equal(explicitStatus.context.specDir, 'specs/feature-x');
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+test('getProjectStatus resolves concrete project config branch when no default branch is set', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-context-config-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'config-branch', '# Tasks\n');
+    const configPath = path.join(root, '.sdd', 'project.yml');
+    const config = await readFile(configPath, 'utf8');
+    await writeFile(configPath, config.replace(/  default_branch: master\n/, '').replace('spec_dir: specs/<branch>', 'spec_dir: specs/config-branch'), 'utf8');
+
+    const status = await getProjectStatus(root);
+
+    assert.equal(status.context.branch, 'config-branch');
+    assert.equal(status.context.branchSource, 'project_config');
+    assert.equal(status.context.specDir, 'specs/config-branch');
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+test('Phase 6.4 getProjectStatus resolves current Git branch before project config default', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-context-git-'));
+  try {
+    await execFileAsync('git', ['init'], { cwd: root });
+    await execFileAsync('git', ['checkout', '-b', 'git-branch'], { cwd: root });
+    await initProject(root);
+    await writeBranchDocs(root, 'git-branch', '# Tasks\n');
+
+    const status = await getProjectStatus(root);
+
+    assert.equal(status.context.rawBranch, 'git-branch');
+    assert.equal(status.context.branch, 'git-branch');
+    assert.equal(status.context.partition, 'git-branch');
+    assert.equal(status.context.branchSource, 'git_branch');
+    assert.equal(status.context.specDir, 'specs/git-branch');
+    assert.equal(status.workflowStatus, 'active');
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+test('Phase 6.4 maps slash Git branch names to stable safe partitions', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-context-git-slash-'));
+  const rawBranch = 'feature/login';
+  const partition = `feature-login-${createHash('sha256').update(rawBranch).digest('hex').slice(0, 8)}`;
+  try {
+    await execFileAsync('git', ['init'], { cwd: root });
+    await execFileAsync('git', ['checkout', '-b', rawBranch], { cwd: root });
+    await initProject(root);
+    await writeBranchDocs(root, partition, '# Tasks\n');
+
+    const status = await getProjectStatus(root);
+
+    assert.equal(status.context.rawBranch, rawBranch);
+    assert.equal(status.context.branch, partition);
+    assert.equal(status.context.partition, partition);
+    assert.equal(status.context.branchSource, 'git_branch');
+    assert.equal(status.context.specDir, `specs/${partition}`);
+    assert.equal(status.documents.tasksExists, true);
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+test('Phase 6.4 marks plan and tasks stale after spec revision hash changes', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-spec-revision-stale-'));
+  try {
+    await initProject(root);
+    const branchDir = path.join(root, 'specs', 'feature');
+    await mkdir(branchDir, { recursive: true });
+    const spec = '# Spec\n\nInitial requirement.\n';
+    const planTemplate = '# Plan\n\nbased_on_spec_hash: pending\n\nInitial plan.\n';
+    const specHash = createHash('sha256').update(spec.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+    const plan = planTemplate.replace('pending', specHash);
+    const planHash = createHash('sha256').update(plan.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+    await writeFile(path.join(branchDir, 'spec.md'), spec, 'utf8');
+    await writeFile(path.join(branchDir, 'plan.md'), plan, 'utf8');
+    await writeFile(path.join(branchDir, 'tasks.md'), `${validTaskMarkdown('T1', [])}\nbased_on_plan_hash: ${planHash}\n`, 'utf8');
+
+    const fresh = await getProjectStatus(root, { branch: 'feature' });
+    await writeFile(path.join(branchDir, 'spec.md'), '# Spec\n\nChanged requirement.\n', 'utf8');
+    const stale = await getProjectStatus(root, { branch: 'feature' });
+
+    assert.equal(fresh.documents.planStale, false);
+    assert.equal(fresh.documents.tasksStale, false);
+    assert.equal(stale.documents.planStale, true);
+    assert.equal(stale.documents.tasksStale, true);
+    assert.equal(stale.gaps.some((gap) => gap.field === 'plan.md' && /stale/.test(gap.message)), true);
+    assert.equal(stale.gaps.some((gap) => gap.field === 'tasks.md' && /stale/.test(gap.message)), true);
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+test('getProjectStatus rejects unresolved branch instead of silently using specs master', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-context-no-fallback-'));
+  try {
+    await initProject(root);
+    const configPath = path.join(root, '.sdd', 'project.yml');
+    const config = await readFile(configPath, 'utf8');
+    await writeFile(configPath, config.replace(/  default_branch: master\n/, ''), 'utf8');
+
+    await assert.rejects(() => getProjectStatus(root), /Cannot resolve SDD branch/);
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+test('statusline token health uses context and team runtime projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-status-token-health-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', contextBuildTaskMarkdown('T1'));
+    const unknown = await getStatuslineProjection(root, { branch: 'master' });
+    await buildContextBuildPackage(root, { taskId: 'T1', branch: 'master', mode: 'do', agent: 'implementer' });
+    const nominal = await getProjectStatus(root, { branch: 'master' });
+    await decideCommandTeamRuntime(root, { command: 'recover', activation: 'force', riskTags: ['blocked'] });
+    const pressure = await getStatuslineProjection(root, { branch: 'master' });
+
+    assert.equal(unknown.tokenHealth, 'unknown');
+    assert.notEqual(nominal.tokenProjection.health, 'unknown');
+    assert.equal(nominal.tokenProjection.contextPackages, 1);
+    assert.equal(pressure.tokenHealth, 'pressure');
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+test('getProjectStatus exposes observable workflow handoff projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-status-handoff-'));
+  try {
+    await initProject(root);
+    await recordStageRunProjection(root, statusStageRun());
+    await recordWorkflowHandoffProjection(root, statusHandoff());
+
+    const status = await getProjectStatus(root, { branch: 'master' });
+
+    assert.equal(status.workflowHandoff.status, 'fresh');
+    assert.equal(status.workflowHandoff.latestStageRun?.stage, 'do');
+    assert.equal(status.workflowHandoff.latestHandoff?.status, 'accepted');
+    assert.equal(status.workflowHandoff.projectionCounts.stageRuns, 1);
+    assert.equal(status.workflowHandoff.projectionCounts.handoffs, 1);
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+test('statusline exposes context offload and subagent dispatch projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-status-context-subagent-'));
+  try {
+    await initProject(root);
+    const signal = evaluateContextLoadSignal({
+      scope: { branch: 'master', taskId: 'T1', runId: 'run-1' },
+      refs: [{ kind: 'document', ref: 'specs/master/tasks.md' }],
+      fileCount: 20,
+      artifactBytes: 200_000,
+      dependencyFanout: 12,
+      unknownImpact: true,
+      generatedAt: '2026-05-18T00:00:00.000Z'
+    });
+    await recordContextLoadSignalProjection(root, signal);
+    await recordContextOffloadDecisionProjection(root, decideContextOffload(signal, { dispatchRefs: [{ kind: 'projection', ref: 'phase8_subagent_dispatch:master:T1:run-1:none:dispatch-1' }] }));
+    await recordSubagentDispatchProjection(root, statusSubagentDispatch());
+
+    const statusline = await getStatuslineProjection(root, { branch: 'master' });
+
+    assert.equal(statusline.contextLoad, 'high');
+    assert.equal(statusline.contextAction, 'dispatch-subagent');
+    assert.equal(statusline.subagentHealth, 'blocked');
+    assert.equal(statusline.counts.subagentDispatches, 1);
+    assert.equal(statusline.counts.blockingSubagents, 1);
+  } finally {
+    await removeTempRoot(root);
+  }
+});
+
+function statusStageRun(): StageRun {
+  return {
+    contract: STAGE_RUN_CONTRACT_VERSION,
+    id: 'stage-status-do',
+    scope: { branch: 'master', taskId: 'T1', runId: 'run-1' },
+    stage: 'do',
+    ownerAgent: 'implementer',
+    coMainAgents: ['reviewer'],
+    status: 'completed',
+    inputRefs: [{ kind: 'projection', ref: 'phase8_lifecycle_risk_decision:master:T1:run-1:none' }],
+    outputRefs: [{ kind: 'artifact', ref: 'artifacts/status-handoff.md' }],
+    decisionRefs: [{ kind: 'projection', ref: 'phase8_lifecycle_risk_decision:master:T1:run-1:none' }],
+    blockingReasons: [],
+    createdAt: '2026-05-18T00:00:00.000Z',
+    updatedAt: '2026-05-18T00:01:00.000Z'
+  };
+}
+
+function statusHandoff(): WorkflowHandoff {
+  return {
+    contract: WORKFLOW_HANDOFF_CONTRACT_VERSION,
+    id: 'handoff-status-do-test',
+    scope: { branch: 'master', taskId: 'T1', runId: 'run-1' },
+    fromStage: 'do',
+    toStage: 'test',
+    fromAgent: 'implementer',
+    toAgent: 'validator',
+    status: 'accepted',
+    outputRefs: [{ kind: 'artifact', ref: 'artifacts/status-handoff.md' }],
+    requiredInputRefs: [{ kind: 'projection', ref: 'phase8_lifecycle_risk_decision:master:T1:run-1:none' }],
+    riskDecisionRef: { kind: 'projection', ref: 'phase8_lifecycle_risk_decision:master:T1:run-1:none' },
+    evidenceRefs: [{ kind: 'evidence', ref: 'artifacts/status-handoff-validation.md#AC-1' }],
+    openQuestions: [],
+    blockingGaps: [],
+    createdAt: '2026-05-18T00:02:00.000Z',
+    decidedAt: '2026-05-18T00:03:00.000Z'
+  };
+}
+
+function statusSubagentDispatch(): SubagentDispatch {
+  return {
+    contract: SUBAGENT_DISPATCH_CONTRACT_VERSION,
+    id: 'dispatch-1',
+    scope: { branch: 'master', taskId: 'T1', runId: 'run-1' },
+    workUnitId: 'wu-subagent-1',
+    definitionName: 'test-writer',
+    mode: 'background',
+    status: 'queued',
+    blocking: true,
+    requiredBefore: 'handoff',
+    contextRef: { kind: 'projection', ref: 'sdd-scoped-context-handoff:T1' },
+    createdAt: '2026-05-18T00:00:00.000Z',
+    updatedAt: '2026-05-18T00:01:00.000Z'
+  };
+}