@devtrack-solution/codesdd 1.2.2 → 1.2.3

package/dist/core/sdd/agent-binding.js

@@ -0,0 +1,343 @@
+import { z } from 'zod';
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const ADAPTER_ID_PATTERN = /^codesdd-agent-[a-z0-9][a-z0-9-]*$/;
+const agentProviderSchema = z.enum([
+    'codex',
+    'opencode',
+    'claude-code',
+    'cloudcode',
+    'deepagents',
+    'fake',
+]);
+const agentTaskKindSchema = z.enum([
+    'planning',
+    'review',
+    'validation',
+    'implementation',
+    'reverse-engineering',
+    'plugin-execution',
+    'adr-governance',
+    'quality-witness',
+    'documentation-sync',
+]);
+const adapterStatusSchema = z.enum(['active', 'disabled', 'experimental']);
+const trustTierSchema = z.enum(['enterprise-approved', 'local-dev', 'experimental', 'blocked']);
+const riskTierSchema = z.enum(['low', 'medium', 'high', 'critical']);
+const TRUST_RANK = {
+    'enterprise-approved': 3,
+    'local-dev': 2,
+    experimental: 1,
+    blocked: 0,
+};
+const RISK_RANK = {
+    low: 4,
+    medium: 3,
+    high: 2,
+    critical: 1,
+};
+export const agentBindingCapabilitySchema = z.object({
+    task_kind: agentTaskKindSchema,
+    description: z.string().min(20),
+    read_only: z.boolean(),
+    edits: z.boolean(),
+    background: z.boolean(),
+    worktree_isolation: z.boolean(),
+    mcp: z.boolean(),
+    skills: z.boolean(),
+    structured_evidence: z.boolean(),
+    risk_tier: riskTierSchema.default('medium'),
+});
+export const agentBindingAdapterSchema = z
+    .object({
+    schema_version: z.literal(1).default(1),
+    id: z.string().regex(ADAPTER_ID_PATTERN),
+    provider: agentProviderSchema,
+    label: z.string().min(2),
+    status: adapterStatusSchema.default('active'),
+    execution: z.object({
+        mode: z.enum(['local-cli', 'cloud', 'test-double']),
+        command: z.string().min(1).optional(),
+        args: z.array(z.string()).default([]),
+        network: z.enum(['disabled', 'restricted', 'enabled']).default('disabled'),
+        evidence_contract: z.string().min(1).default('agent-evidence/v1'),
+    }),
+    capabilities: z.array(agentBindingCapabilitySchema).min(1),
+    governance: z.object({
+        owner: z.string().min(2),
+        trust_tier: trustTierSchema,
+        approval: z.enum(['none', 'maintainer', 'architecture-board', 'security']).default('maintainer'),
+        notes: z.array(z.string()).default([]),
+    }),
+})
+    .superRefine((adapter, context) => {
+    const seen = new Set();
+    for (const [index, capability] of adapter.capabilities.entries()) {
+        if (seen.has(capability.task_kind)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['capabilities', index, 'task_kind'],
+                message: `Duplicate agent capability: ${capability.task_kind}.`,
+            });
+        }
+        seen.add(capability.task_kind);
+    }
+    if (adapter.execution.mode !== 'test-double' && !adapter.execution.command) {
+        context.addIssue({
+            code: 'custom',
+            path: ['execution', 'command'],
+            message: 'Non-test agent adapters must declare an execution command.',
+        });
+    }
+});
+export const agentBindingResolutionRequestSchema = z.object({
+    schema_version: z.literal(1).default(1),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN),
+    task_kind: agentTaskKindSchema,
+    provider: agentProviderSchema.optional(),
+    allowed_providers: z
+        .array(agentProviderSchema)
+        .default(['codex', 'opencode', 'claude-code', 'cloudcode', 'deepagents', 'fake']),
+    statuses: z.array(adapterStatusSchema).default(['active']),
+    trust_tiers: z.array(trustTierSchema).default(['enterprise-approved', 'local-dev', 'experimental']),
+    require_edits: z.boolean().default(false),
+    require_background: z.boolean().default(false),
+    require_worktree_isolation: z.boolean().default(false),
+    require_mcp: z.boolean().default(false),
+    require_skills: z.boolean().default(false),
+    require_structured_evidence: z.boolean().default(true),
+    created_at: z.string().datetime().optional(),
+});
+export const agentBindingCandidateSchema = z.object({
+    adapter_ref: z.object({
+        id: z.string().regex(ADAPTER_ID_PATTERN),
+        provider: agentProviderSchema,
+        label: z.string().min(2),
+    }),
+    task_kind: agentTaskKindSchema,
+    rank: z.number().int().nonnegative(),
+    reasons: z.array(z.string()).default([]),
+});
+export const agentBindingResolutionSchema = z.object({
+    schema_version: z.literal(1),
+    created_at: z.string().datetime(),
+    status: z.enum(['resolved', 'fallback']),
+    request: agentBindingResolutionRequestSchema,
+    selected: agentBindingCandidateSchema.optional(),
+    candidates: z.array(agentBindingCandidateSchema).default([]),
+    reasons: z.array(z.string()).default([]),
+    fallback: z
+        .object({
+        strategy: z.enum(['manual-agent-selection', 'local-human-execution', 'no-compatible-agent']),
+        message: z.string().min(1),
+    })
+        .optional(),
+});
+export function builtInAgentBindingAdapters() {
+    return [
+        createAdapter('codesdd-agent-codex-local', 'codex', 'Codex Local', 'local-cli', 'codex', {
+            background: true,
+            worktree_isolation: true,
+            mcp: true,
+            trust_tier: 'enterprise-approved',
+        }),
+        createAdapter('codesdd-agent-opencode-cli', 'opencode', 'OpenCode CLI', 'local-cli', 'opencode', {
+            background: false,
+            worktree_isolation: false,
+            mcp: false,
+            trust_tier: 'local-dev',
+        }),
+        createAdapter('codesdd-agent-claude-code-cli', 'claude-code', 'Claude Code CLI', 'local-cli', 'claude', {
+            background: false,
+            worktree_isolation: false,
+            mcp: true,
+            trust_tier: 'local-dev',
+        }),
+        createAdapter('codesdd-agent-cloudcode', 'cloudcode', 'Claude Code CloudCode', 'cloud', 'cloudcode', {
+            background: true,
+            worktree_isolation: true,
+            mcp: true,
+            trust_tier: 'enterprise-approved',
+            network: 'restricted',
+        }),
+        createAdapter('codesdd-agent-deepagents', 'deepagents', 'DeepAgents Governed Runtime', 'local-cli', 'codesdd-agent-run', {
+            background: true,
+            worktree_isolation: true,
+            mcp: true,
+            trust_tier: 'enterprise-approved',
+            network: 'restricted',
+        }),
+        createAdapter('codesdd-agent-fake-test', 'fake', 'Fake Deterministic Agent', 'test-double', undefined, {
+            background: false,
+            worktree_isolation: true,
+            mcp: false,
+            trust_tier: 'experimental',
+        }),
+    ];
+}
+export function resolveAgentBindingAdapter(adapters, request) {
+    const parsedAdapters = adapters.map((adapter) => agentBindingAdapterSchema.parse(adapter));
+    const parsedRequest = agentBindingResolutionRequestSchema.parse(request);
+    const createdAt = parsedRequest.created_at ?? new Date().toISOString();
+    const reasons = [];
+    const candidates = parsedAdapters.flatMap((adapter) => buildCandidate(adapter, parsedRequest, reasons));
+    const sortedCandidates = candidates.sort(compareCandidates);
+    const [selected] = sortedCandidates;
+    if (!selected) {
+        return agentBindingResolutionSchema.parse({
+            schema_version: 1,
+            created_at: createdAt,
+            status: 'fallback',
+            request: {
+                ...parsedRequest,
+                created_at: createdAt,
+            },
+            reasons: reasons.length > 0 ? reasons : ['No compatible agent adapter was found.'],
+            candidates: [],
+            fallback: {
+                strategy: 'no-compatible-agent',
+                message: 'Continue with manual execution or configure a compatible agent adapter before delegating work.',
+            },
+        });
+    }
+    return agentBindingResolutionSchema.parse({
+        schema_version: 1,
+        created_at: createdAt,
+        status: 'resolved',
+        request: {
+            ...parsedRequest,
+            created_at: createdAt,
+        },
+        selected,
+        candidates: sortedCandidates,
+        reasons: [
+            `Resolved ${parsedRequest.task_kind} to ${selected.adapter_ref.id} (${selected.adapter_ref.provider}).`,
+            ...selected.reasons,
+        ],
+    });
+}
+function createAdapter(id, provider, label, mode, command, options) {
+    return agentBindingAdapterSchema.parse({
+        schema_version: 1,
+        id,
+        provider,
+        label,
+        execution: {
+            mode,
+            command,
+            args: [],
+            network: options.network ?? 'disabled',
+            evidence_contract: 'agent-evidence/v1',
+        },
+        capabilities: [
+            capability('planning', true, false, options, 'low'),
+            capability('review', true, false, options, 'low'),
+            capability('validation', true, false, options, 'medium'),
+            capability('implementation', false, true, options, 'high'),
+            capability('reverse-engineering', true, false, options, 'medium'),
+            capability('plugin-execution', false, true, options, 'high'),
+            capability('adr-governance', false, true, options, 'medium'),
+            capability('quality-witness', true, false, options, 'medium'),
+            capability('documentation-sync', false, true, options, 'medium'),
+        ],
+        governance: {
+            owner: 'platform-engineering',
+            trust_tier: options.trust_tier,
+            approval: provider === 'fake' ? 'none' : 'maintainer',
+            notes: [`${label} adapter is declarative and non-executing in FEAT-0150.`],
+        },
+    });
+}
+function capability(taskKind, readOnly, edits, options, riskTier) {
+    return agentBindingCapabilitySchema.parse({
+        task_kind: taskKind,
+        description: `${taskKind} capability advertised by the agent binding adapter.`,
+        read_only: readOnly,
+        edits,
+        background: options.background,
+        worktree_isolation: options.worktree_isolation,
+        mcp: options.mcp,
+        skills: true,
+        structured_evidence: true,
+        risk_tier: riskTier,
+    });
+}
+function buildCandidate(adapter, request, reasons) {
+    const capability = adapter.capabilities.find((candidate) => candidate.task_kind === request.task_kind);
+    const rejectionReasons = collectRejectionReasons(adapter, capability, request);
+    if (rejectionReasons.length > 0) {
+        reasons.push(...rejectionReasons.map((reason) => `${adapter.id}/${request.task_kind}: ${reason}`));
+        return [];
+    }
+    const resolvedCapability = capability;
+    return [
+        agentBindingCandidateSchema.parse({
+            adapter_ref: {
+                id: adapter.id,
+                provider: adapter.provider,
+                label: adapter.label,
+            },
+            task_kind: resolvedCapability.task_kind,
+            rank: rankCandidate(adapter, resolvedCapability, request),
+            reasons: candidateReasons(adapter, resolvedCapability),
+        }),
+    ];
+}
+function collectRejectionReasons(adapter, capability, request) {
+    const reasons = [];
+    if (request.provider && adapter.provider !== request.provider) {
+        reasons.push(`provider ${adapter.provider} does not match requested provider ${request.provider}.`);
+    }
+    if (!request.allowed_providers.includes(adapter.provider)) {
+        reasons.push(`provider ${adapter.provider} is not allowed.`);
+    }
+    if (!request.statuses.includes(adapter.status)) {
+        reasons.push(`status ${adapter.status} is not eligible.`);
+    }
+    if (!request.trust_tiers.includes(adapter.governance.trust_tier)) {
+        reasons.push(`trust tier ${adapter.governance.trust_tier} is not eligible.`);
+    }
+    if (!capability) {
+        reasons.push(`task kind ${request.task_kind} is not advertised.`);
+        return reasons;
+    }
+    if (request.require_edits && !capability.edits) {
+        reasons.push('edits are required but not supported.');
+    }
+    if (request.require_background && !capability.background) {
+        reasons.push('background execution is required but not supported.');
+    }
+    if (request.require_worktree_isolation && !capability.worktree_isolation) {
+        reasons.push('worktree isolation is required but not supported.');
+    }
+    if (request.require_mcp && !capability.mcp) {
+        reasons.push('MCP support is required but not supported.');
+    }
+    if (request.require_skills && !capability.skills) {
+        reasons.push('skill support is required but not supported.');
+    }
+    if (request.require_structured_evidence && !capability.structured_evidence) {
+        reasons.push('structured evidence is required but not supported.');
+    }
+    return reasons;
+}
+function candidateReasons(adapter, capability) {
+    return [
+        `${adapter.label} supports ${capability.task_kind} with ${capability.edits ? 'edit' : 'read-only'} scope.`,
+    ];
+}
+function rankCandidate(adapter, capability, request) {
+    const providerRank = request.provider && adapter.provider === request.provider ? 100_000 : 0;
+    const trustRank = TRUST_RANK[adapter.governance.trust_tier] * 1_000;
+    const isolationRank = capability.worktree_isolation ? 200 : 0;
+    const backgroundRank = capability.background ? 100 : 0;
+    const mcpRank = capability.mcp ? 50 : 0;
+    const riskRank = RISK_RANK[capability.risk_tier] * 10;
+    return providerRank + trustRank + isolationRank + backgroundRank + mcpRank + riskRank;
+}
+function compareCandidates(left, right) {
+    if (right.rank !== left.rank) {
+        return right.rank - left.rank;
+    }
+    return left.adapter_ref.id.localeCompare(right.adapter_ref.id);
+}
+//# sourceMappingURL=agent-binding.js.map

package/dist/core/sdd/backlog-cli.d.ts

@@ -0,0 +1,16 @@
+import { type BacklogProviderId, type BacklogProjectionPlan, type CanonicalBacklogItem } from './backlog-provider-contract.js';
+export interface BacklogProjectDryRunOptions {
+    provider: BacklogProviderId;
+    ref: string;
+    items?: CanonicalBacklogItem[];
+    created_at?: string;
+}
+export interface BacklogProjectDryRunResult {
+    schema_version: 1;
+    dry_run: true;
+    ref: string;
+    fixture: string;
+    plan: BacklogProjectionPlan;
+}
+export declare function buildBacklogProjectDryRun(options: BacklogProjectDryRunOptions): BacklogProjectDryRunResult;
+//# sourceMappingURL=backlog-cli.d.ts.map

package/dist/core/sdd/backlog-cli.js

@@ -0,0 +1,146 @@
+import { backlogProjectionPlanSchema, buildBacklogProjectionItem, } from './backlog-provider-contract.js';
+const azureDevOpsContract = {
+    schema_version: 1,
+    provider: 'azure-devops',
+    adapter_id: 'azure-devops',
+    label: 'Azure DevOps Boards',
+    status: 'experimental',
+    auth: {
+        mode: 'pat',
+        required_env: ['AZURE_DEVOPS_EXT_PAT'],
+        secret_fields: ['AZURE_DEVOPS_EXT_PAT'],
+    },
+    capabilities: [
+        {
+            operation: 'create',
+            entity_kinds: ['epic', 'feature'],
+            dry_run: true,
+            apply: false,
+            idempotent: true,
+            required_fields: ['System.Title', 'System.State', 'Custom.CodeSDDRef'],
+        },
+        {
+            operation: 'link',
+            entity_kinds: ['epic', 'feature'],
+            dry_run: true,
+            apply: false,
+            idempotent: true,
+        },
+    ],
+    mapping: {
+        external_project_field: 'System.TeamProject',
+        external_id_field: 'System.Id',
+        external_url_field: 'System.Url',
+        canonical_ref_field: 'Custom.CodeSDDRef',
+        parent_ref_field: 'Custom.CodeSDDParentRef',
+        entity_type_field: 'Custom.CodeSDDEntityType',
+        title_field: 'System.Title',
+        status_field: 'System.State',
+    },
+    canonical_state_boundary: {
+        source_of_truth: 'codesdd',
+        state_paths: ['.sdd/state/*.yaml'],
+        external_state_authoritative: false,
+        hidden_state_allowed: false,
+    },
+    governance: {
+        owner: 'platform-architecture',
+        sync_requires_dry_run: true,
+        mutation_requires_approval: true,
+        audit_event: 'codesdd.backlog.projection',
+    },
+};
+const epic0039Fixture = [
+    {
+        ref: 'EPIC-0039',
+        kind: 'epic',
+        title: 'Provider-agnostic backlog integration and CodeSDD naming governance',
+        status: 'SPLIT',
+        labels: ['codesdd', 'backlog-integration'],
+    },
+    {
+        ref: 'FEAT-0166',
+        kind: 'feature',
+        title: 'Backlog provider contract and canonical projection schema',
+        status: 'DONE',
+        parent_ref: 'EPIC-0039',
+        labels: ['codesdd', 'backlog-integration'],
+    },
+    {
+        ref: 'FEAT-0167',
+        kind: 'feature',
+        title: 'Azure DevOps dry-run projection planner',
+        status: 'IN_PROGRESS',
+        parent_ref: 'EPIC-0039',
+        labels: ['codesdd', 'backlog-integration'],
+    },
+    {
+        ref: 'FEAT-0168',
+        kind: 'feature',
+        title: 'Backlog sync conflict and idempotency policy',
+        status: 'IN_PROGRESS',
+        parent_ref: 'EPIC-0039',
+        labels: ['codesdd', 'backlog-integration'],
+    },
+    {
+        ref: 'FEAT-0169',
+        kind: 'feature',
+        title: 'Backlog integration CLI dry-run surface',
+        status: 'IN_PROGRESS',
+        parent_ref: 'EPIC-0039',
+        labels: ['codesdd', 'backlog-integration'],
+    },
+    {
+        ref: 'FEAT-0170',
+        kind: 'feature',
+        title: 'Backlog integration documentation and handoff',
+        status: 'IN_PROGRESS',
+        parent_ref: 'EPIC-0039',
+        labels: ['codesdd', 'backlog-integration'],
+    },
+];
+export function buildBacklogProjectDryRun(options) {
+    if (options.provider !== 'azure-devops') {
+        throw new Error(`Unsupported backlog provider for dry-run projection: ${options.provider}.`);
+    }
+    const items = options.items ?? resolveFixtureItems(options.ref);
+    const createdAt = options.created_at ?? new Date().toISOString();
+    const plan = backlogProjectionPlanSchema.parse({
+        schema_version: 1,
+        created_at: createdAt,
+        provider: options.provider,
+        mode: 'dry-run',
+        direction: 'push',
+        source_of_truth: 'codesdd',
+        items: items.map((item) => buildBacklogProjectionItem({
+            contract: azureDevOpsContract,
+            item,
+            external_type: toAzureDevOpsWorkItemType(item),
+        })),
+        warnings: [
+            'Dry-run only: no network calls, credentials, external IDs, or provider writes are used.',
+            `Projection source: ${options.items ? 'caller-provided canonical items' : `built-in ${options.ref} fixture`}.`,
+        ],
+    });
+    return {
+        schema_version: 1,
+        dry_run: true,
+        ref: options.ref,
+        fixture: options.items ? 'provided' : options.ref,
+        plan,
+    };
+}
+function resolveFixtureItems(ref) {
+    if (ref !== 'EPIC-0039') {
+        throw new Error(`No built-in backlog projection fixture for ${ref}. Provide canonical items in code or use EPIC-0039.`);
+    }
+    return epic0039Fixture;
+}
+function toAzureDevOpsWorkItemType(item) {
+    if (item.kind === 'epic')
+        return 'Epic';
+    if (item.kind === 'feature')
+        return 'User Story';
+    return item.kind;
+}
+//# sourceMappingURL=backlog-cli.js.map

package/dist/core/sdd/backlog-conflict-policy.d.ts

@@ -0,0 +1,58 @@
+import type { BacklogEntityKind, BacklogProviderId } from './backlog-provider-contract.js';
+export type BacklogConflictClassification = 'none' | 'create' | 'update' | 'manual-review' | 'stale-external' | 'canonical-drift';
+export type BacklogSyncOperation = 'noop' | 'create' | 'update' | 'manual-review';
+export type BacklogSyncDecisionSeverity = 'info' | 'warning' | 'error';
+export interface BacklogSyncFieldSet {
+    title: string;
+    status: string;
+    parent_ref?: string;
+    labels?: string[];
+}
+export interface CanonicalBacklogSyncItem extends BacklogSyncFieldSet {
+    ref: string;
+    kind: Exclude<BacklogEntityKind, 'task'>;
+    updated_at?: string;
+    last_synced_at?: string;
+    last_synced_fingerprint?: string;
+    fields?: Record<string, string | string[] | undefined>;
+}
+export interface ExternalBacklogWorkItem extends Partial<BacklogSyncFieldSet> {
+    provider: BacklogProviderId;
+    external_id?: string;
+    canonical_ref?: string;
+    updated_at?: string;
+    last_synced_at?: string;
+    codesdd_fingerprint?: string;
+    idempotency_key?: string;
+    fields?: Record<string, string | string[] | undefined>;
+}
+export interface BacklogConflictDecision {
+    code: string;
+    severity: BacklogSyncDecisionSeverity;
+    message: string;
+    field?: string;
+    source_of_truth: 'codesdd';
+    canonical_value?: unknown;
+    external_value?: unknown;
+}
+export interface BacklogConflictPolicyInput {
+    provider: BacklogProviderId;
+    canonical: CanonicalBacklogSyncItem;
+    external?: ExternalBacklogWorkItem;
+    source_of_truth?: string;
+}
+export interface BacklogConflictPolicyResult {
+    classification: BacklogConflictClassification;
+    operation: BacklogSyncOperation;
+    idempotency_key: string;
+    canonical_fingerprint: string;
+    decisions: BacklogConflictDecision[];
+}
+export declare function classifyBacklogSyncConflict(input: BacklogConflictPolicyInput): BacklogConflictPolicyResult;
+export declare function buildBacklogSyncIdempotencyKey(input: {
+    provider: BacklogProviderId;
+    canonical_ref: string;
+    operation: BacklogSyncOperation;
+}): string;
+export declare function fingerprintBacklogSyncFields(fields: BacklogSyncFieldSet): string;
+//# sourceMappingURL=backlog-conflict-policy.d.ts.map