sdd-agent-platform 0.3.0 → 0.4.0

package/node_modules/@sdd-agent-platform/core/src/path-safety.test.ts

@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { readRunState } from './run-state/run-state.js';
+import { parseSddBranch } from './sdd-docs/task-parser.js';
+import { getArtifactPath, getEvidenceAttachmentPath } from './runtime-paths.js';
+
+test('safe path segments reject dot-dot branch and run id while allowing dotted names', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-safe-path-'));
+  try {
+    await assert.rejects(() => parseSddBranch(root, '..'), /branch cannot be \. or \.\./);
+    await assert.rejects(() => readRunState(root, '..'), /runId cannot be \. or \.\./);
+    assert.doesNotThrow(() => getArtifactPath(root, 'phase-1.5_run-1', 'evidence.md'));
+    assert.doesNotThrow(() => getEvidenceAttachmentPath(root, 'feat/unsafe branch', 'logs/evidence.md'));
+    assert.throws(() => getEvidenceAttachmentPath(root, 'feature', '../outside.md'), /Evidence path must be relative and stay under evidence/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/node_modules/@sdd-agent-platform/core/src/path-safety.ts

@@ -0,0 +1,37 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+export function assertSafePathSegment(value: string, field: string): void {
+  if (value === '.' || value === '..') {
+    throw new Error(`${field} cannot be . or ...`);
+  }
+  if (!/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new Error(`${field} must contain only letters, digits, dot, underscore, or dash.`);
+  }
+}
+
+export function safeBranchOrNull(branch: string): string | null {
+  try {
+    assertSafePathSegment(branch, 'branch');
+    return branch;
+  } catch {
+    return null;
+  }
+}
+
+export function branchToSafePartition(branch: string): string {
+  const trimmed = branch.trim();
+  const safe = safeBranchOrNull(trimmed);
+  if (safe) {
+    return safe;
+  }
+  const hash = createHash('sha256').update(trimmed).digest('hex').slice(0, 8);
+  const slug = trimmed.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48);
+  const candidate = slug && slug !== '.' && slug !== '..' ? `${slug}-${hash}` : `branch-${hash}`;
+  assertSafePathSegment(candidate, 'partition');
+  return candidate;
+}
+
+export function normalizePortablePath(value: string): string {
+  return path.posix.normalize(value.replace(/\\/g, '/'));
+}

package/node_modules/@sdd-agent-platform/core/src/phase8-contracts.test.ts

@@ -0,0 +1,242 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CODING_FACT_SET_CONTRACT_VERSION, LIFECYCLE_RISK_DECISION_CONTRACT_VERSION, MODEL_PRODUCED_ARTIFACT_CONTRACT_VERSION, RUNTIME_PROJECTION_ENVELOPE_CONTRACT_VERSION, type ModelProducedArtifact, type RuntimeProjectionEnvelope } from './contracts.js';
+import type { CodingFactSet } from './coding-facts.js';
+import type { LifecycleRiskDecision } from './risk.js';
+import type { StageRun, WorkflowHandoff } from './stage-runtime.js';
+import type { WorkUnit } from './work-units.js';
+import type { SubagentDefinition, SubagentResult } from './subagents.js';
+import type { ContextLoadSignal, ContextOffloadDecision } from './context-offload.js';
+import type { UnifiedTestEvidenceRun } from './evidence-runtime.js';
+
+const scope = { branch: 'master', taskId: 'PHASE8-1', runId: 'run-1' };
+const now = '2026-05-16T00:00:00.000Z';
+const projectionRef = { kind: 'projection' as const, ref: 'lifecycle-risk-decision:PHASE8-1' };
+const artifactRef = { kind: 'artifact' as const, ref: 'artifacts/phase8-contract-validation.md' };
+
+test('Phase 8 contract objects expose required runtime boundaries', () => {
+  const facts: CodingFactSet = {
+    contract: CODING_FACT_SET_CONTRACT_VERSION,
+    scope,
+    request: { intentKnown: true, acceptanceKnown: true, validationKnown: true },
+    documents: { specExists: true, planExists: true, tasksExists: true, verifiesExists: false },
+    facts: [],
+    files: [],
+    tests: [],
+    runtime: [],
+    evidence: [],
+    external: [],
+    generatedAt: now
+  };
+
+  const decision: LifecycleRiskDecision = {
+    contract: LIFECYCLE_RISK_DECISION_CONTRACT_VERSION,
+    scope,
+    profile: 'compact',
+    requiredStages: ['tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back'],
+    skippedStages: [],
+    blockedStages: [],
+    requiredEvidence: [],
+    requiredReviews: [],
+    humanCheckpointRequired: false,
+    approvalPolicy: 'review-required',
+    inputRefs: [],
+    signalRefs: [],
+    policyVersion: 'phase8-risk-policy-v1',
+    inputHash: 'input-hash',
+    confidence: 'high',
+    reasons: ['contract foundation sample'],
+    generatedAt: now
+  };
+
+  const stageRun: StageRun = {
+    contract: 'sdd-stage-run-v1',
+    id: 'stage-1',
+    scope,
+    stage: 'do',
+    ownerAgent: 'implementer',
+    coMainAgents: ['reviewer'],
+    status: 'active',
+    inputRefs: [projectionRef],
+    outputRefs: [],
+    decisionRefs: [projectionRef],
+    blockingReasons: [],
+    createdAt: now,
+    updatedAt: now
+  };
+
+  const handoff: WorkflowHandoff = {
+    contract: 'sdd-workflow-handoff-v1',
+    id: 'handoff-1',
+    scope,
+    fromStage: 'do',
+    toStage: 'test',
+    fromAgent: 'implementer',
+    toAgent: 'validator',
+    status: 'proposed',
+    outputRefs: [artifactRef],
+    requiredInputRefs: [projectionRef],
+    riskDecisionRef: projectionRef,
+    evidenceRefs: [],
+    openQuestions: [],
+    blockingGaps: [],
+    createdAt: now
+  };
+
+  assert.equal(facts.contract, 'sdd-coding-fact-set-v1');
+  assert.equal(decision.profile, 'compact');
+  assert.equal(stageRun.ownerAgent, 'implementer');
+  assert.equal(handoff.status, 'proposed');
+});
+
+test('lifecycle risk decision keeps agent and subagent selection out of policy output', () => {
+  const decision: LifecycleRiskDecision = {
+    contract: LIFECYCLE_RISK_DECISION_CONTRACT_VERSION,
+    scope,
+    profile: 'direct',
+    requiredStages: ['test'],
+    skippedStages: ['plan'],
+    blockedStages: [],
+    requiredEvidence: [],
+    requiredReviews: [],
+    humanCheckpointRequired: false,
+    approvalPolicy: 'auto-allow',
+    inputRefs: [],
+    signalRefs: [],
+    policyVersion: 'phase8-risk-policy-v1',
+    inputHash: 'input-hash',
+    confidence: 'high',
+    reasons: [],
+    generatedAt: now
+  };
+
+  const forbiddenKeys = ['agent', 'agentId', 'ownerAgent', 'team', 'subagent', 'subagents', 'selectedAgent'];
+  for (const key of forbiddenKeys) {
+    assert.equal(Object.hasOwn(decision, key), false, key);
+  }
+});
+
+test('work units, subagents, context offload, evidence, and model artifacts stay non-authoritative by default', () => {
+  const workUnit: WorkUnit = {
+    contract: 'sdd-work-unit-v1',
+    id: 'work-1',
+    scope,
+    stageRunId: 'stage-1',
+    type: 'subagent',
+    name: 'review-subagent',
+    purpose: 'bounded review',
+    status: 'pending',
+    blocking: false,
+    authority: 'non-authoritative',
+    requiredBefore: 'never',
+    contextRef: artifactRef,
+    outputRefs: [],
+    evidenceRefs: [],
+    createdAt: now
+  };
+
+  const subagent: SubagentDefinition = {
+    contract: 'sdd-subagent-definition-v1',
+    name: 'test-writer',
+    description: 'Writes tests under allowed test paths only.',
+    promptRef: artifactRef,
+    allowedToolRefs: [],
+    canEditProduction: false,
+    canOwnLifecycle: false,
+    allowedWritePaths: ['**/*.test.ts'],
+    resultAuthority: 'non-authoritative'
+  };
+
+  const modelArtifact: ModelProducedArtifact = {
+    contract: MODEL_PRODUCED_ARTIFACT_CONTRACT_VERSION,
+    producer: 'subagent',
+    authority: 'non-authoritative',
+    allowedUse: ['summary', 'diagnostic'],
+    forbiddenUse: ['final-risk-decision', 'stage-completion', 'ship-gate-pass'],
+    artifactRefs: [artifactRef.ref],
+    reviewedByRuntime: false
+  };
+
+  const subagentResult: SubagentResult = {
+    contract: 'sdd-subagent-result-v1',
+    dispatchId: 'dispatch-1',
+    status: 'completed',
+    authority: 'diagnostic-only',
+    summary: 'No production edits attempted.',
+    artifactRefs: [artifactRef],
+    evidenceRefs: [],
+    modelArtifacts: [modelArtifact],
+    completedAt: now
+  };
+
+  const contextSignal: ContextLoadSignal = {
+    contract: 'sdd-context-load-signal-v1',
+    scope,
+    level: 'high',
+    score: 8,
+    fileCountScore: 2,
+    artifactSizeScore: 2,
+    dependencyFanoutScore: 1,
+    unknownImpactScore: 1,
+    staleEvidenceScore: 1,
+    logVolumeScore: 1,
+    confidence: 'medium',
+    inputRefs: [artifactRef],
+    reasons: ['large artifact set'],
+    generatedAt: now
+  };
+
+  const contextDecision: ContextOffloadDecision = {
+    contract: 'sdd-context-offload-decision-v1',
+    scope,
+    action: 'dispatch-subagent',
+    loadSignalRef: projectionRef,
+    requiredBefore: 'never',
+    inlineRefs: [],
+    summarizeRefs: [artifactRef],
+    dispatchRefs: [artifactRef],
+    blockingReasons: [],
+    generatedAt: now
+  };
+
+  const evidenceRun: UnifiedTestEvidenceRun = {
+    contract: 'sdd-test-evidence-run-v1',
+    id: 'evidence-1',
+    scope,
+    commandStatus: 'PASS',
+    evidenceCoverage: 'complete',
+    policyJudgment: 'PASS',
+    commands: [],
+    acceptanceCoverage: [],
+    syncBackReady: true,
+    gaps: [],
+    next: 'sdd sync-back inspect --branch master',
+    generatedAt: now
+  };
+
+  assert.equal(workUnit.authority, 'non-authoritative');
+  assert.equal(subagent.canEditProduction, false);
+  assert.equal(subagent.canOwnLifecycle, false);
+  assert.equal(subagentResult.authority, 'diagnostic-only');
+  assert.equal(contextSignal.level, 'high');
+  assert.equal(contextDecision.action, 'dispatch-subagent');
+  assert.equal(evidenceRun.policyJudgment, 'PASS');
+});
+
+test('projection envelope records deterministic freshness inputs', () => {
+  const envelope: RuntimeProjectionEnvelope<{ ok: true }> = {
+    contract: RUNTIME_PROJECTION_ENVELOPE_CONTRACT_VERSION,
+    projectionType: 'phase8.lifecycle-risk-decision',
+    scopeKey: 'master:PHASE8-1',
+    id: 'phase8.lifecycle-risk-decision:master:PHASE8-1:input-hash:producer-v1',
+    inputHash: 'input-hash',
+    producer: 'phase8-contract-test',
+    producerVersion: 'producer-v1',
+    generatedAt: now,
+    payload: { ok: true }
+  };
+
+  assert.equal(envelope.contract, 'sdd-runtime-projection-envelope-v1');
+  assert.equal(envelope.inputHash, 'input-hash');
+  assert.equal(envelope.producerVersion, 'producer-v1');
+});

package/node_modules/@sdd-agent-platform/core/src/phase8-projection-compat.test.ts

@@ -0,0 +1,153 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { initProject } from './config/init-project.js';
+import { evaluateLifecycleDecisionGate } from './lifecycle/decision-gate.js';
+import { buildTaskRiskProfile } from './task-risk-profile.js';
+import { evaluateLifecycleRiskDecisionFromProfile, legacyLifecycleDecisionToRiskDecision, taskRiskProfileToCodingRiskProfile, taskRiskProfileToCodingRiskSignals } from './risk.js';
+import { readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, runtimeProjectionStaleness } from './storage/runtime-store.js';
+
+test('Phase 8 projection envelope writes are deterministic and stale-aware', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-projection-'));
+  try {
+    await initProject(root);
+    const first = await recordRuntimeProjectionEnvelope(root, {
+      projectionType: 'phase8-test-risk',
+      scopeKey: 'branch:master',
+      inputHash: 'input-a',
+      producer: 'phase8-test',
+      producerVersion: 'v1',
+      generatedAt: '2026-05-01T00:00:00.000Z',
+      payload: { status: 'one' }
+    });
+    const second = await recordRuntimeProjectionEnvelope(root, {
+      projectionType: 'phase8-test-risk',
+      scopeKey: 'branch:master',
+      inputHash: 'input-a',
+      producer: 'phase8-test',
+      producerVersion: 'v1',
+      generatedAt: '2026-05-02T00:00:00.000Z',
+      payload: { status: 'one' }
+    });
+
+    assert.equal(first.status, 'created');
+    assert.equal(first.staleness, 'unknown');
+    assert.equal(second.status, 'unchanged');
+    assert.equal(second.envelope.id, first.envelope.id);
+    assert.equal(second.envelope.generatedAt, '2026-05-01T00:00:00.000Z');
+    assert.equal(runtimeProjectionStaleness(second.envelope, { inputHash: 'input-b', producerVersion: 'v1' }), 'stale');
+    assert.equal(runtimeProjectionStaleness(second.envelope, { inputHash: 'input-a', producerVersion: 'v2' }), 'incompatible');
+
+    const third = await recordRuntimeProjectionEnvelope(root, {
+      projectionType: 'phase8-test-risk',
+      scopeKey: 'branch:master',
+      inputHash: 'input-b',
+      producer: 'phase8-test',
+      producerVersion: 'v1',
+      generatedAt: '2026-05-03T00:00:00.000Z',
+      payload: { status: 'two' }
+    });
+    const restored = await readRuntimeProjectionEnvelope<{ status: string }>(root, 'phase8-test-risk', 'branch:master');
+
+    assert.equal(third.status, 'updated');
+    assert.equal(third.staleness, 'stale');
+    assert.equal(restored?.inputHash, 'input-b');
+    assert.deepEqual(restored?.payload, { status: 'two' });
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('legacy task risk profiles map to Phase 8 coding risk signals', () => {
+  const scope = { branch: 'master', taskId: 'PHASE8-2' };
+  const sourceProfile = buildTaskRiskProfile({
+    id: 'PHASE8-2',
+    risk: ['security', 'external', 'context', 'token', 'performance'],
+    affectedFiles: ['packages/core/src/storage/runtime-store.ts', '.sdd/run-index.json'],
+    validation: ['npm test']
+  });
+  const docsProfile = buildTaskRiskProfile({
+    id: 'DOCS-1',
+    risk: [],
+    affectedFiles: ['specs/master/phase8-spec.md'],
+    validation: ['npm run typecheck']
+  });
+
+  const sourceSignals = taskRiskProfileToCodingRiskSignals(sourceProfile, scope);
+  const docsSignals = taskRiskProfileToCodingRiskSignals(docsProfile, { branch: 'master', taskId: 'DOCS-1' });
+  const dimensions = sourceSignals.map((signal) => signal.dimension);
+  const docsDimensions = docsSignals.map((signal) => signal.dimension);
+  const profile = taskRiskProfileToCodingRiskProfile(sourceProfile, scope, '2026-05-01T00:00:00.000Z');
+
+  assert.equal(dimensions.includes('source'), true);
+  assert.equal(dimensions.includes('runtime-state'), true);
+  assert.equal(dimensions.includes('security'), true);
+  assert.equal(dimensions.includes('external'), true);
+  assert.equal(dimensions.includes('context'), true);
+  assert.equal(dimensions.includes('performance'), true);
+  assert.equal(docsDimensions.includes('workflow'), true);
+  assert.equal(docsDimensions.includes('evidence'), true);
+  assert.equal(profile.contract, 'sdd-coding-risk-profile-v1');
+  assert.equal(profile.level, 'high');
+  assert.equal(profile.dimensions.includes('source'), true);
+});
+
+test('known external risk stays distinct from unknown external risk', () => {
+  const known = buildTaskRiskProfile({
+    id: 'KNOWN-EXTERNAL',
+    risk: ['external', 'third-party'],
+    affectedFiles: ['docs/integration.md'],
+    validation: ['npm test']
+  });
+  const unknown = buildTaskRiskProfile({
+    id: 'UNKNOWN-EXTERNAL',
+    risk: ['external-unknown'],
+    affectedFiles: ['docs/integration.md'],
+    validation: ['npm test']
+  });
+  const knownRisk = taskRiskProfileToCodingRiskProfile(known, { branch: 'master', taskId: 'KNOWN-EXTERNAL' }, '2026-05-01T00:00:00.000Z');
+  const unknownRisk = taskRiskProfileToCodingRiskProfile(unknown, { branch: 'master', taskId: 'UNKNOWN-EXTERNAL' }, '2026-05-01T00:00:00.000Z');
+  const knownDecision = evaluateLifecycleRiskDecisionFromProfile(knownRisk);
+  const unknownDecision = evaluateLifecycleRiskDecisionFromProfile(unknownRisk);
+
+  assert.deepEqual(known.normalizedTags, ['external']);
+  assert.equal(known.externalKnown, true);
+  assert.equal(known.externalUnknown, false);
+  assert.equal(unknown.externalUnknown, true);
+  assert.equal(knownRisk.signals.some((signal) => signal.id.endsWith(':external-known') && signal.level === 'medium' && signal.confidence === 'high'), true);
+  assert.equal(unknownRisk.signals.some((signal) => signal.id.endsWith(':external-unknown') && signal.level === 'high' && signal.confidence === 'low'), true);
+  assert.notEqual(knownDecision.profile, 'research');
+  assert.equal(unknownDecision.profile, 'research');
+  assert.equal(unknownDecision.approvalPolicy, 'human-required');
+});
+
+test('legacy lifecycle decisions map to Phase 8 comparison decisions', () => {
+  const legacy = evaluateLifecycleDecisionGate({
+    intent_clarity: 'high',
+    acceptance_clarity: 'high',
+    impact_confidence: 'high',
+    validation_clarity: 'clear',
+    validation_available: true,
+    validation_cost: 'cheap',
+    reversibility: 'reversible',
+    affected_contracts: ['public-api'],
+    risk_tags: ['security']
+  }, new Date('2026-05-01T00:00:00.000Z')).record;
+  const decision = legacyLifecycleDecisionToRiskDecision(legacy, { branch: 'master', taskId: 'PHASE8-2' }, { inputHash: 'legacy-input' });
+
+  assert.equal(decision.contract, 'sdd-lifecycle-risk-decision-v1');
+  assert.equal(decision.profile, 'full');
+  assert.equal(decision.requiredStages.includes('test'), true);
+  assert.equal(decision.requiredStages.includes('verifies'), true);
+  assert.equal(decision.requiredStages.includes('goal-verify'), true);
+  assert.equal(decision.requiredEvidence.length, 1);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'security'), true);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'source-boundary'), true);
+  assert.equal(decision.approvalPolicy, 'review-required');
+  assert.equal(decision.reasons[0], 'Mapped from legacy lifecycle decision for comparison only.');
+  assert.equal(Object.hasOwn(decision, 'ownerAgent'), false);
+  assert.equal(Object.hasOwn(decision, 'subagent'), false);
+});