@devtrack-solution/codesdd 1.2.3 → 1.2.4-rc3

package/dist/core/sdd/docs-sync.js

@@ -31,6 +31,16 @@ function upsertMarkedBlock(source, startMarker, endMarker, blockContent) {
     const next = `${prefix}${replacement}\n`;
     return { content: next, changed: true, hasMarkers: false };
 }
+function validateManagedBlock(source, startMarker, endMarker, expectedBlock, label, missingBlocks) {
+    if (!source.includes(startMarker) || !source.includes(endMarker)) {
+        missingBlocks.push(label);
+        return;
+    }
+    const expected = upsertMarkedBlock(source, startMarker, endMarker, expectedBlock);
+    if (expected.changed) {
+        missingBlocks.push(`${label}:DRIFT`);
+    }
+}
 function buildReadmeBlock(memoryDir, config) {
     return `## Onboarding SDD
 
@@ -41,6 +51,8 @@ Operational authority:
 
 Initial operational directives:
 - CodeSDD is the official planner for any build request; other planners or agent-native plans are secondary execution aids only.
+- In initialized CodeSDD repositories, any user request that implies implementation, file edits, validation, execution, or finalize must be treated as requiring CodeSDD planning unless the user explicitly marks it as read-only or outside CodeSDD.
+- For change requests, agents must bind the work to an active or ready FEAT through \`${CLI_NAME} sdd next\` and \`${CLI_NAME} sdd context <FEAT-ID>\` before implementation; agent-native plans may only decompose execution after that CodeSDD context exists.
 - For API/backend work, use \`devtrack-api\` by default unless the user or SDD context explicitly selects another skill/profile; Python/Flask API work stays routed to \`api-clean-flask-langgraph\`.
 - During init, onboard, insight, and debate flows, CodeSDD-managed agent instruction blocks must be inspected and reconfigured when they drift from this contract.
 - Commit requests must follow Conventional Commits, selective staging, and grouping by modified directory plus change protocol (\`src\`, \`${memoryDir}\`, docs, config, infra, dependencies, or generated files).
@@ -102,6 +114,8 @@ Operational exclusivity:
 
 Initial directives:
 - CodeSDD is the official planner for requested work; model-native plans and other planning tools are subordinate to CodeSDD artifacts.
+- In initialized CodeSDD repositories, implementation, edit, validation, execution, and finalize requests implicitly require CodeSDD planning unless the user explicitly marks the request as read-only or outside CodeSDD.
+- A change request must use the active or ready FEAT returned by \`${CLI_NAME} sdd next\` and must load \`${CLI_NAME} sdd context <FEAT-ID>\` before coding; model-native plans may only refine execution after that context exists.
 - API/backend work uses \`devtrack-api\` by default unless an explicit skill/profile says otherwise; Python/Flask API work uses \`api-clean-flask-langgraph\`.
 - CodeSDD-managed blocks in \`AGENTS.md\`, \`AGENT.md\`, \`CLAUDE.md\`, \`GEMINI.md\`, \`.codex\`, \`.opencode\`, \`.ai\`, \`.cloud\`, or equivalent agent files must be inspected and normalized during init/onboard/insight/debate when CodeSDD owns project governance.
 - Commits must use Conventional Commits, selective staging, and grouping by modified directory plus protocol: source, \`${memoryDir}\`, docs, config, infra, dependencies, generated files, renames, or deletions.`;
@@ -134,6 +148,8 @@ Do not use external context, memory, workflow, backlog, scratchpad, or handoff t
 
 Initial directives:
 - CodeSDD is the official planner. Other planning systems may assist execution only after CodeSDD context exists.
+- In initialized CodeSDD repositories, implementation, edit, validation, execution, and finalize requests implicitly require CodeSDD planning unless the user explicitly marks the request as read-only or outside CodeSDD.
+- Agents must bind each change request to the active or ready FEAT returned by \`${CLI_NAME} sdd next\` and load \`${CLI_NAME} sdd context <FEAT-ID>\` before coding.
 - API/backend work defaults to \`devtrack-api\` unless an explicit skill/profile overrides it; Python/Flask API work remains a documented exception routed to \`api-clean-flask-langgraph\`.
 - CodeSDD lifecycle entrypoints must inspect and normalize CodeSDD-managed agent instruction blocks in root and tool-specific agent files.
 - Commit work must use Conventional Commits, selective staging, and directory/protocol grouping. Source changes, \`${memoryDir}\` governance, docs, config, infra, dependencies, generated files, renames, and deletions should be staged and committed separately unless indivisible.`;
@@ -225,11 +241,9 @@ export async function validateSddGuideDocs(projectRoot, paths, config) {
     const agentCompatRaw = (await fileExists(agentCompatPath))
         ? await fs.readFile(agentCompatPath, 'utf-8')
         : '';
-    if (!readmeRaw.includes(README_SDD_BLOCK_START) || !readmeRaw.includes(README_SDD_BLOCK_END)) {
-        missingBlocks.push('README.md::SDD:ONBOARDING');
-    }
+    validateManagedBlock(readmeRaw, README_SDD_BLOCK_START, README_SDD_BLOCK_END, buildReadmeBlock(memoryDirName, config), 'README.md::SDD:ONBOARDING', missingBlocks);
     if (internalReadmeRaw !==
-        buildSddInternalReadme(path.relative(projectRoot, paths.memoryRoot) || '.sdd', {
+        buildSddInternalReadme(memoryDirName, {
             discovery: config?.folders.discovery,
             planning: config?.folders.planning,
             skills: config?.folders.skills,
@@ -240,17 +254,9 @@ export async function validateSddGuideDocs(projectRoot, paths, config) {
         })) {
         missingBlocks.push(`${memoryDirName}/README.md::SDD:INTERNAL`);
     }
-    if (!agentRaw.includes(AGENT_SDD_BLOCK_START) || !agentRaw.includes(AGENT_SDD_BLOCK_END)) {
-        missingBlocks.push(`${memoryDirName}/AGENT.md::SDD:GUIA`);
-    }
-    if (!agentsRaw.includes(ROOT_AGENTS_SDD_BLOCK_START) ||
-        !agentsRaw.includes(ROOT_AGENTS_SDD_BLOCK_END)) {
-        missingBlocks.push('AGENTS.md::SDD:ROOT-AGENTS');
-    }
-    if (!agentCompatRaw.includes(ROOT_AGENTS_SDD_BLOCK_START) ||
-        !agentCompatRaw.includes(ROOT_AGENTS_SDD_BLOCK_END)) {
-        missingBlocks.push('AGENT.md::SDD:ROOT-AGENTS');
-    }
+    validateManagedBlock(agentRaw, AGENT_SDD_BLOCK_START, AGENT_SDD_BLOCK_END, buildAgentGuideBlock(memoryDirName, config), `${memoryDirName}/AGENT.md::SDD:GUIA`, missingBlocks);
+    validateManagedBlock(agentsRaw, ROOT_AGENTS_SDD_BLOCK_START, ROOT_AGENTS_SDD_BLOCK_END, buildRootAgentsBlock(memoryDirName), 'AGENTS.md::SDD:ROOT-AGENTS', missingBlocks);
+    validateManagedBlock(agentCompatRaw, ROOT_AGENTS_SDD_BLOCK_START, ROOT_AGENTS_SDD_BLOCK_END, buildRootAgentsBlock(memoryDirName), 'AGENT.md::SDD:ROOT-AGENTS', missingBlocks);
     return {
         documentationSync: missingBlocks.length === 0,
         missingBlocks,

package/dist/core/sdd/domain/capability-diff.d.ts

@@ -0,0 +1,63 @@
+import type { ChangeSafetyEvaluation, PlannedFileChange } from './change-safety-guardrails.js';
+export declare const CAPABILITY_KINDS: readonly ["route", "page", "cli_command", "public_contract", "schema", "event", "core_flow", "governance_state"];
+export declare const CAPABILITY_CHANGE_TYPES: readonly ["added", "removed", "modified", "unchanged"];
+export declare const CAPABILITY_RISK_LEVELS: readonly ["none", "low", "medium", "high", "critical"];
+export type CapabilityKind = (typeof CAPABILITY_KINDS)[number];
+export type CapabilityChangeType = (typeof CAPABILITY_CHANGE_TYPES)[number];
+export type CapabilityRiskLevel = (typeof CAPABILITY_RISK_LEVELS)[number];
+export interface CapabilityInventoryItem {
+    kind: CapabilityKind;
+    id: string;
+    path?: string;
+    fingerprint?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CapabilityInventory {
+    schema_version: 1;
+    contract: 'capability-inventory/v1';
+    items: CapabilityInventoryItem[];
+}
+export interface CapabilityDiffEntry {
+    kind: CapabilityKind;
+    id: string;
+    change: CapabilityChangeType;
+    before?: CapabilityInventoryItem;
+    after?: CapabilityInventoryItem;
+}
+export interface CapabilityDiffCounts {
+    added: number;
+    removed: number;
+    modified: number;
+    unchanged: number;
+}
+export interface CapabilityDiffReport {
+    schema_version: 1;
+    contract: 'capability-diff-report/v1';
+    entries: CapabilityDiffEntry[];
+    counts: CapabilityDiffCounts;
+}
+export interface CapabilityRiskSignal {
+    code: string;
+    level: Exclude<CapabilityRiskLevel, 'none'>;
+    message: string;
+    capability_ref?: string;
+    path?: string;
+}
+export interface CapabilityRiskReport {
+    schema_version: 1;
+    contract: 'deterministic-capability-risk/v1';
+    level: CapabilityRiskLevel;
+    score: number;
+    signals: CapabilityRiskSignal[];
+}
+export interface CapabilityRiskInput {
+    diff: CapabilityDiffReport;
+    change_safety?: ChangeSafetyEvaluation;
+    planned_changes?: PlannedFileChange[];
+    required_kinds?: CapabilityKind[];
+}
+export declare function buildCapabilityInventory(items: CapabilityInventoryItem[]): CapabilityInventory;
+export declare function diffCapabilityInventories(before: CapabilityInventory, after: CapabilityInventory): CapabilityDiffReport;
+export declare function scoreCapabilityDiffRisk(input: CapabilityRiskInput): CapabilityRiskReport;
+export declare function capabilityKey(item: Pick<CapabilityInventoryItem, 'kind' | 'id'>): string;
+//# sourceMappingURL=capability-diff.d.ts.map

package/dist/core/sdd/domain/capability-diff.js

@@ -0,0 +1,200 @@
+import { createHash } from 'node:crypto';
+export const CAPABILITY_KINDS = [
+    'route',
+    'page',
+    'cli_command',
+    'public_contract',
+    'schema',
+    'event',
+    'core_flow',
+    'governance_state',
+];
+export const CAPABILITY_CHANGE_TYPES = ['added', 'removed', 'modified', 'unchanged'];
+export const CAPABILITY_RISK_LEVELS = ['none', 'low', 'medium', 'high', 'critical'];
+const PUBLIC_SURFACE_KINDS = new Set([
+    'route',
+    'page',
+    'cli_command',
+    'public_contract',
+    'schema',
+    'event',
+]);
+const CRITICAL_KIND_WEIGHTS = new Map([
+    ['core_flow', 'critical'],
+    ['governance_state', 'critical'],
+]);
+const RISK_SCORE = {
+    none: 0,
+    low: 25,
+    medium: 50,
+    high: 75,
+    critical: 100,
+};
+export function buildCapabilityInventory(items) {
+    return {
+        schema_version: 1,
+        contract: 'capability-inventory/v1',
+        items: normalizeCapabilityItems(items),
+    };
+}
+export function diffCapabilityInventories(before, after) {
+    const beforeByKey = indexByCapabilityKey(before.items);
+    const afterByKey = indexByCapabilityKey(after.items);
+    const keys = [...new Set([...beforeByKey.keys(), ...afterByKey.keys()])].sort();
+    const entries = keys.map((key) => {
+        const beforeItem = beforeByKey.get(key);
+        const afterItem = afterByKey.get(key);
+        const item = afterItem ?? beforeItem;
+        if (!item) {
+            throw new Error(`Capability key ${key} resolved without an inventory item.`);
+        }
+        if (!beforeItem)
+            return { kind: item.kind, id: item.id, change: 'added', after: afterItem };
+        if (!afterItem)
+            return { kind: item.kind, id: item.id, change: 'removed', before: beforeItem };
+        if (beforeItem.fingerprint !== afterItem.fingerprint) {
+            return { kind: item.kind, id: item.id, change: 'modified', before: beforeItem, after: afterItem };
+        }
+        return { kind: item.kind, id: item.id, change: 'unchanged', before: beforeItem, after: afterItem };
+    });
+    return {
+        schema_version: 1,
+        contract: 'capability-diff-report/v1',
+        entries,
+        counts: countDiffEntries(entries),
+    };
+}
+export function scoreCapabilityDiffRisk(input) {
+    const signals = [];
+    const presentKinds = new Set(input.diff.entries.map((entry) => entry.kind));
+    for (const requiredKind of input.required_kinds ?? []) {
+        if (!presentKinds.has(requiredKind)) {
+            signals.push({
+                code: 'required_capability_inventory_missing',
+                level: CRITICAL_KIND_WEIGHTS.get(requiredKind) ?? 'high',
+                message: `Required capability inventory kind ${requiredKind} is missing from before/after diff evidence.`,
+                capability_ref: requiredKind,
+            });
+        }
+    }
+    for (const entry of input.diff.entries) {
+        if (entry.change === 'removed') {
+            signals.push(riskForRemovedCapability(entry));
+        }
+        if (entry.change === 'modified' && PUBLIC_SURFACE_KINDS.has(entry.kind)) {
+            signals.push({
+                code: 'public_capability_modified',
+                level: 'medium',
+                message: `Public capability ${capabilityRef(entry)} changed.`,
+                capability_ref: capabilityRef(entry),
+                path: entry.after?.path ?? entry.before?.path,
+            });
+        }
+        if (entry.change === 'added' && PUBLIC_SURFACE_KINDS.has(entry.kind)) {
+            signals.push({
+                code: 'public_capability_added',
+                level: 'low',
+                message: `Public capability ${capabilityRef(entry)} was added.`,
+                capability_ref: capabilityRef(entry),
+                path: entry.after?.path,
+            });
+        }
+    }
+    if (input.change_safety?.status === 'blocked') {
+        signals.push(...input.change_safety.violations.map((violation) => ({
+            code: `change_safety_${violation.code}`,
+            level: 'critical',
+            message: violation.message,
+            path: violation.path,
+        })));
+    }
+    for (const plannedChange of input.planned_changes ?? []) {
+        if (plannedChange.operation === 'delete' || plannedChange.operation === 'rename' || plannedChange.operation === 'replace') {
+            signals.push({
+                code: 'destructive_planned_change',
+                level: 'high',
+                message: `Planned ${plannedChange.operation} change affects ${plannedChange.path}.`,
+                path: plannedChange.path,
+            });
+        }
+    }
+    const level = maxRiskLevel(signals.map((signal) => signal.level));
+    return {
+        schema_version: 1,
+        contract: 'deterministic-capability-risk/v1',
+        level,
+        score: RISK_SCORE[level],
+        signals: sortRiskSignals(signals),
+    };
+}
+export function capabilityKey(item) {
+    return `${item.kind}:${item.id}`;
+}
+function normalizeCapabilityItems(items) {
+    const byKey = new Map();
+    for (const item of items) {
+        const normalized = {
+            kind: item.kind,
+            id: item.id.trim(),
+            path: item.path?.trim(),
+            metadata: item.metadata ?? {},
+            fingerprint: item.fingerprint ?? fingerprintCapabilityItem(item),
+        };
+        byKey.set(capabilityKey(normalized), normalized);
+    }
+    return [...byKey.values()].sort((left, right) => capabilityKey(left).localeCompare(capabilityKey(right)));
+}
+function fingerprintCapabilityItem(item) {
+    const stable = stableStringify({
+        kind: item.kind,
+        id: item.id.trim(),
+        path: item.path?.trim() ?? '',
+        metadata: item.metadata ?? {},
+    });
+    return createHash('sha256').update(stable).digest('hex');
+}
+function indexByCapabilityKey(items) {
+    return new Map(items.map((item) => [capabilityKey(item), item]));
+}
+function countDiffEntries(entries) {
+    return entries.reduce((counts, entry) => {
+        counts[entry.change] += 1;
+        return counts;
+    }, { added: 0, removed: 0, modified: 0, unchanged: 0 });
+}
+function riskForRemovedCapability(entry) {
+    const criticalLevel = CRITICAL_KIND_WEIGHTS.get(entry.kind);
+    const level = criticalLevel ?? (PUBLIC_SURFACE_KINDS.has(entry.kind) ? 'high' : 'medium');
+    return {
+        code: 'capability_removed',
+        level,
+        message: `Capability ${capabilityRef(entry)} was removed.`,
+        capability_ref: capabilityRef(entry),
+        path: entry.before?.path,
+    };
+}
+function capabilityRef(entry) {
+    return `${entry.kind}:${entry.id}`;
+}
+function maxRiskLevel(levels) {
+    if (levels.length === 0)
+        return 'none';
+    return levels.reduce((max, level) => (RISK_SCORE[level] > RISK_SCORE[max] ? level : max), 'none');
+}
+function sortRiskSignals(signals) {
+    return [...signals].sort((left, right) => RISK_SCORE[right.level] - RISK_SCORE[left.level] ||
+        left.code.localeCompare(right.code) ||
+        (left.capability_ref ?? '').localeCompare(right.capability_ref ?? '') ||
+        (left.path ?? '').localeCompare(right.path ?? ''));
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=capability-diff.js.map

package/dist/core/sdd/domain/change-safety-guardrails.d.ts

@@ -0,0 +1,74 @@
+export declare const CHANGE_SAFETY_OPERATIONS: readonly ["add", "modify", "remove", "replace", "refactor", "optimize"];
+export type ChangeSafetyOperation = (typeof CHANGE_SAFETY_OPERATIONS)[number];
+export type PlannedFileOperation = 'create' | 'modify' | 'delete' | 'rename' | 'replace';
+export interface ExplicitModificationIntent {
+    operation?: string;
+}
+export interface ContextLock {
+    allowed_paths?: string[];
+    forbidden_paths?: string[];
+    protected_core?: string[];
+}
+export interface ChangeBudget {
+    max_files_changed?: number;
+    max_new_files?: number;
+    max_deleted_files?: number;
+}
+export interface GovernedOverride {
+    feature_id?: string;
+    intent?: string;
+    rationale?: string;
+    write_scope?: string[];
+    expected_deletions?: string[];
+    rollback_plan?: string;
+    compensating_control?: string;
+    approver?: string;
+    expires_at?: string;
+}
+export interface PlannedFileChange {
+    path: string;
+    operation: PlannedFileOperation;
+    previous_path?: string;
+}
+export interface ChangeSafetyContract {
+    explicit_modification_intent?: ExplicitModificationIntent;
+    intent?: ExplicitModificationIntent;
+    context_lock?: ContextLock;
+    change_budget?: ChangeBudget;
+    governed_override?: GovernedOverride;
+}
+export type ChangeSafetyViolationCode = 'planned_changes_missing' | 'intent_missing' | 'intent_invalid' | 'add_intent_destructive_change' | 'context_lock_outside_allowed_paths' | 'context_lock_forbidden_path' | 'protected_core_change' | 'change_budget_files_exceeded' | 'change_budget_new_files_exceeded' | 'change_budget_deleted_files_exceeded' | 'governed_override_required' | 'governed_override_field_missing' | 'governed_override_feature_mismatch' | 'governed_override_intent_mismatch' | 'governed_override_expires_at_invalid' | 'governed_override_expired' | 'governed_override_scope_mismatch' | 'governed_override_deletions_mismatch';
+export interface ChangeSafetyViolation {
+    code: ChangeSafetyViolationCode;
+    message: string;
+    path?: string;
+    limit?: number;
+    actual?: number;
+}
+export interface ChangeSafetyCounts {
+    files_changed: number;
+    new_files: number;
+    deleted_files: number;
+}
+export interface ChangeSafetyEvaluation {
+    status: 'allowed' | 'blocked';
+    operation: ChangeSafetyOperation | '';
+    violations: ChangeSafetyViolation[];
+    counts: ChangeSafetyCounts;
+    governed_override: GovernedOverrideEvaluation;
+}
+export interface ChangeSafetyEvaluationOptions {
+    feature_id?: string;
+    now?: Date | string;
+}
+export interface GovernedOverrideEvaluation {
+    required: boolean;
+    status: 'not_required' | 'valid' | 'invalid';
+    violations: ChangeSafetyViolation[];
+}
+export declare function isChangeSafetyOperation(value: string | undefined): value is ChangeSafetyOperation;
+export declare function evaluateChangeSafety(contract: ChangeSafetyContract, plannedChanges: PlannedFileChange[], options?: ChangeSafetyEvaluationOptions): ChangeSafetyEvaluation;
+export declare function countPlannedChanges(plannedChanges: PlannedFileChange[]): ChangeSafetyCounts;
+export declare function normalizeProjectPath(value: string): string;
+export declare function pathMatchesPattern(candidatePath: string, pattern: string): boolean;
+//# sourceMappingURL=change-safety-guardrails.d.ts.map