@ai-dev-orchestrator/governance 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +60 -0
- package/dist/domain/governance/errors.d.ts +20 -0
- package/dist/domain/governance/errors.js +30 -0
- package/dist/domain/governance/index.d.ts +2 -0
- package/dist/domain/governance/index.js +1 -0
- package/dist/domain/governance/ownership-check-result.d.ts +5 -0
- package/dist/domain/governance/ownership-check-result.js +1 -0
- package/dist/domain/iteration-contracts/errors.d.ts +21 -0
- package/dist/domain/iteration-contracts/errors.js +32 -0
- package/dist/domain/iteration-contracts/index.d.ts +1 -0
- package/dist/domain/iteration-contracts/index.js +1 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +10 -0
- package/dist/infrastructure/collaboration-model/default-collaboration-model.d.ts +19 -0
- package/dist/infrastructure/collaboration-model/default-collaboration-model.js +109 -0
- package/dist/infrastructure/collaboration-model/index.d.ts +1 -0
- package/dist/infrastructure/collaboration-model/index.js +1 -0
- package/dist/infrastructure/governance/decision-recorder.d.ts +14 -0
- package/dist/infrastructure/governance/decision-recorder.js +37 -0
- package/dist/infrastructure/governance/escalation-manager.d.ts +7 -0
- package/dist/infrastructure/governance/escalation-manager.js +49 -0
- package/dist/infrastructure/governance/index.d.ts +7 -0
- package/dist/infrastructure/governance/index.js +6 -0
- package/dist/infrastructure/governance/iteration-limiter.d.ts +9 -0
- package/dist/infrastructure/governance/iteration-limiter.js +33 -0
- package/dist/infrastructure/governance/ownership-enforcer.d.ts +16 -0
- package/dist/infrastructure/governance/ownership-enforcer.js +55 -0
- package/dist/infrastructure/governance/quality-gate-checker.d.ts +6 -0
- package/dist/infrastructure/governance/quality-gate-checker.js +29 -0
- package/dist/infrastructure/governance/transition-gate.d.ts +34 -0
- package/dist/infrastructure/governance/transition-gate.js +194 -0
- package/dist/infrastructure/iteration-contracts/built-in-contracts.d.ts +10 -0
- package/dist/infrastructure/iteration-contracts/built-in-contracts.js +160 -0
- package/dist/infrastructure/iteration-contracts/contract-registry.d.ts +32 -0
- package/dist/infrastructure/iteration-contracts/contract-registry.js +144 -0
- package/dist/infrastructure/iteration-contracts/index.d.ts +2 -0
- package/dist/infrastructure/iteration-contracts/index.js +2 -0
- package/package.json +44 -0
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
export class QualityGateChecker {
|
|
2
|
+
/** Evaluate findings against severity thresholds. */
|
|
3
|
+
evaluate(findings, maxHighSeverity, maxMediumSeverity) {
|
|
4
|
+
const openFindings = findings.filter((f) => f.status === 'open');
|
|
5
|
+
const highCount = openFindings.filter((f) => f.severity === 'high').length;
|
|
6
|
+
const mediumCount = openFindings.filter((f) => f.severity === 'medium').length;
|
|
7
|
+
const failures = [];
|
|
8
|
+
if (highCount > maxHighSeverity) {
|
|
9
|
+
failures.push(`${String(highCount)} high-severity findings (max ${String(maxHighSeverity)})`);
|
|
10
|
+
}
|
|
11
|
+
if (mediumCount > maxMediumSeverity) {
|
|
12
|
+
failures.push(`${String(mediumCount)} medium-severity findings (max ${String(maxMediumSeverity)})`);
|
|
13
|
+
}
|
|
14
|
+
if (failures.length > 0) {
|
|
15
|
+
return {
|
|
16
|
+
policy: 'quality_gate',
|
|
17
|
+
evaluated: true,
|
|
18
|
+
result: 'fail',
|
|
19
|
+
detail: `Quality gate failed: ${failures.join('; ')}`,
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
return {
|
|
23
|
+
policy: 'quality_gate',
|
|
24
|
+
evaluated: true,
|
|
25
|
+
result: 'pass',
|
|
26
|
+
detail: `Quality gate passed: ${String(openFindings.length)} open findings within thresholds`,
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { AgreementGate, GovernanceEngine, IterationContractRegistry, Logger, PolicyEngine } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
import type { AgreementStatus, GovernanceDecision, TransitionDecision, TransitionRequest } from '@ai-dev-orchestrator/schemas';
|
|
3
|
+
import type { OwnershipEnforcer } from './ownership-enforcer';
|
|
4
|
+
/** Optional dependencies for the DefaultGovernanceEngine. */
|
|
5
|
+
export interface GovernanceEngineOptions {
|
|
6
|
+
readonly agreementGate?: AgreementGate;
|
|
7
|
+
readonly policyEngine?: PolicyEngine;
|
|
8
|
+
readonly ownershipEnforcer?: OwnershipEnforcer;
|
|
9
|
+
readonly logger?: Logger;
|
|
10
|
+
}
|
|
11
|
+
/** Default governance engine implementing the transition gate pattern. */
|
|
12
|
+
export declare class DefaultGovernanceEngine implements GovernanceEngine {
|
|
13
|
+
private readonly limiter;
|
|
14
|
+
private readonly qualityChecker;
|
|
15
|
+
private readonly escalationManager;
|
|
16
|
+
private readonly recorder;
|
|
17
|
+
private readonly agreementGate;
|
|
18
|
+
private readonly policyEngine;
|
|
19
|
+
private readonly ownershipEnforcer;
|
|
20
|
+
private readonly logger;
|
|
21
|
+
private lastRunId;
|
|
22
|
+
constructor(contractRegistry: IterationContractRegistry, options?: GovernanceEngineOptions);
|
|
23
|
+
/** @inheritdoc */
|
|
24
|
+
evaluateTransition(request: TransitionRequest): TransitionDecision;
|
|
25
|
+
/** @inheritdoc */
|
|
26
|
+
checkAgreement(stageId: string): AgreementStatus;
|
|
27
|
+
/** @inheritdoc */
|
|
28
|
+
recordDecision(decision: GovernanceDecision): void;
|
|
29
|
+
private evaluateViaPolicyEngine;
|
|
30
|
+
private evaluateViaInternalCheckers;
|
|
31
|
+
private synthesize;
|
|
32
|
+
private checkOwnership;
|
|
33
|
+
private toOutcome;
|
|
34
|
+
}
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
import { noopLogger } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
import { DecisionRecorder } from './decision-recorder';
|
|
3
|
+
import { EscalationManager } from './escalation-manager';
|
|
4
|
+
import { IterationLimiter } from './iteration-limiter';
|
|
5
|
+
import { QualityGateChecker } from './quality-gate-checker';
|
|
6
|
+
const STAGE_AGREEMENT_TYPE = {
|
|
7
|
+
IMPLEMENTATION: 'planning_agreement',
|
|
8
|
+
VERIFICATION: 'implementation_agreement',
|
|
9
|
+
};
|
|
10
|
+
/** Default governance engine implementing the transition gate pattern. */
|
|
11
|
+
export class DefaultGovernanceEngine {
|
|
12
|
+
limiter;
|
|
13
|
+
qualityChecker;
|
|
14
|
+
escalationManager;
|
|
15
|
+
recorder;
|
|
16
|
+
agreementGate;
|
|
17
|
+
policyEngine;
|
|
18
|
+
ownershipEnforcer;
|
|
19
|
+
logger;
|
|
20
|
+
lastRunId = '';
|
|
21
|
+
constructor(contractRegistry, options) {
|
|
22
|
+
this.limiter = new IterationLimiter(contractRegistry);
|
|
23
|
+
this.qualityChecker = new QualityGateChecker();
|
|
24
|
+
this.escalationManager = new EscalationManager();
|
|
25
|
+
this.recorder = new DecisionRecorder();
|
|
26
|
+
this.agreementGate = options?.agreementGate ?? null;
|
|
27
|
+
this.policyEngine = options?.policyEngine ?? null;
|
|
28
|
+
this.ownershipEnforcer = options?.ownershipEnforcer ?? null;
|
|
29
|
+
this.logger = options?.logger ?? noopLogger;
|
|
30
|
+
}
|
|
31
|
+
/** @inheritdoc */
|
|
32
|
+
evaluateTransition(request) {
|
|
33
|
+
this.lastRunId = request.runId;
|
|
34
|
+
if (this.ownershipEnforcer && request.artifacts.length > 0) {
|
|
35
|
+
const ownershipResult = this.checkOwnership(request);
|
|
36
|
+
if (!ownershipResult.allowed) {
|
|
37
|
+
return {
|
|
38
|
+
allowed: false,
|
|
39
|
+
reason: ownershipResult.reason,
|
|
40
|
+
remediation: 'Assign artifact production to the correct role',
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
if (this.agreementGate) {
|
|
45
|
+
const requiredAgreement = STAGE_AGREEMENT_TYPE[request.to];
|
|
46
|
+
if (requiredAgreement) {
|
|
47
|
+
const result = this.agreementGate.check(requiredAgreement, request.runId);
|
|
48
|
+
this.logger.debug(`[GovernanceEngine] agreement check: type=${requiredAgreement}, exists=${String(result.exists)}, valid=${String(result.valid)}, reason=${result.reason ?? 'none'}`);
|
|
49
|
+
if (!result.exists || !result.valid) {
|
|
50
|
+
const reason = `Required ${requiredAgreement} not satisfied for transition to ${request.to}`;
|
|
51
|
+
this.recorder.record({
|
|
52
|
+
timestamp: new Date().toISOString(),
|
|
53
|
+
runId: request.runId,
|
|
54
|
+
transitionRequested: { from: request.from, to: request.to },
|
|
55
|
+
policiesEvaluated: [
|
|
56
|
+
{ policy: 'agreement_gate', evaluated: true, result: 'fail', detail: reason },
|
|
57
|
+
],
|
|
58
|
+
outcome: 'denied',
|
|
59
|
+
reason,
|
|
60
|
+
artifactsInspected: request.artifacts,
|
|
61
|
+
});
|
|
62
|
+
return {
|
|
63
|
+
allowed: false,
|
|
64
|
+
reason,
|
|
65
|
+
remediation: `Ensure ${requiredAgreement} is generated before transitioning to ${request.to}`,
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
const evaluations = this.policyEngine
|
|
71
|
+
? this.evaluateViaPolicyEngine(request)
|
|
72
|
+
: this.evaluateViaInternalCheckers(request);
|
|
73
|
+
const decision = this.synthesize(request, evaluations);
|
|
74
|
+
this.recorder.record({
|
|
75
|
+
timestamp: new Date().toISOString(),
|
|
76
|
+
runId: request.runId,
|
|
77
|
+
transitionRequested: { from: request.from, to: request.to },
|
|
78
|
+
policiesEvaluated: evaluations,
|
|
79
|
+
outcome: this.toOutcome(decision),
|
|
80
|
+
reason: decision.reason,
|
|
81
|
+
artifactsInspected: request.artifacts,
|
|
82
|
+
});
|
|
83
|
+
return decision;
|
|
84
|
+
}
|
|
85
|
+
/** @inheritdoc */
|
|
86
|
+
checkAgreement(stageId) {
|
|
87
|
+
if (this.agreementGate) {
|
|
88
|
+
const agreementType = STAGE_AGREEMENT_TYPE[stageId];
|
|
89
|
+
if (agreementType) {
|
|
90
|
+
const result = this.agreementGate.check(agreementType, this.lastRunId);
|
|
91
|
+
return {
|
|
92
|
+
exists: result.exists,
|
|
93
|
+
valid: result.valid,
|
|
94
|
+
artifact: result.artifactRef,
|
|
95
|
+
missingReason: result.reason,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
return {
|
|
100
|
+
exists: false,
|
|
101
|
+
valid: false,
|
|
102
|
+
missingReason: 'No agreement gate configured or no mapping for stage',
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
/** @inheritdoc */
|
|
106
|
+
recordDecision(decision) {
|
|
107
|
+
this.recorder.record(decision);
|
|
108
|
+
}
|
|
109
|
+
evaluateViaPolicyEngine(request) {
|
|
110
|
+
if (!this.policyEngine) {
|
|
111
|
+
return [];
|
|
112
|
+
}
|
|
113
|
+
const policyDecision = this.policyEngine.evaluate({
|
|
114
|
+
runId: request.runId,
|
|
115
|
+
currentState: request.from,
|
|
116
|
+
requestedTransition: { from: request.from, to: request.to },
|
|
117
|
+
artifacts: request.artifacts,
|
|
118
|
+
findings: request.findings?.map((f) => ({
|
|
119
|
+
id: f.id,
|
|
120
|
+
severity: f.severity,
|
|
121
|
+
blocking: f.severity === 'high' ? 'must_fix' : 'should_fix',
|
|
122
|
+
status: f.status,
|
|
123
|
+
})),
|
|
124
|
+
iterationCount: request.iterationCount,
|
|
125
|
+
humanApproval: request.humanApproval,
|
|
126
|
+
tokenUsage: request.tokenUsage,
|
|
127
|
+
});
|
|
128
|
+
return policyDecision.results.map((r) => ({
|
|
129
|
+
policy: r.policyType,
|
|
130
|
+
evaluated: true,
|
|
131
|
+
result: r.outcome === 'pass' ? 'pass' : 'fail',
|
|
132
|
+
detail: r.detail ?? r.reason,
|
|
133
|
+
escalationTrigger: r.escalationTrigger,
|
|
134
|
+
}));
|
|
135
|
+
}
|
|
136
|
+
evaluateViaInternalCheckers(request) {
|
|
137
|
+
const evaluations = [];
|
|
138
|
+
const iterationEval = this.limiter.evaluate(request.from, request.iterationCount ?? 0);
|
|
139
|
+
evaluations.push(iterationEval);
|
|
140
|
+
const qualityEval = this.qualityChecker.evaluate(request.findings ?? [], 0, 3);
|
|
141
|
+
evaluations.push(qualityEval);
|
|
142
|
+
return evaluations;
|
|
143
|
+
}
|
|
144
|
+
synthesize(request, evaluations) {
|
|
145
|
+
const iterationFailed = evaluations.some((e) => e.policy === 'iteration_limit' && e.result === 'fail');
|
|
146
|
+
if (iterationFailed) {
|
|
147
|
+
const context = this.escalationManager.buildContext(request.runId, request.from, 'iteration_limit_exceeded', request.findings ?? [], request.artifacts);
|
|
148
|
+
return {
|
|
149
|
+
escalate: true,
|
|
150
|
+
reason: 'Iteration limit exceeded',
|
|
151
|
+
context,
|
|
152
|
+
};
|
|
153
|
+
}
|
|
154
|
+
const budgetEscalation = evaluations.find((e) => e.result === 'fail' && e.escalationTrigger);
|
|
155
|
+
if (budgetEscalation) {
|
|
156
|
+
const trigger = budgetEscalation.escalationTrigger;
|
|
157
|
+
const context = this.escalationManager.buildContext(request.runId, request.from, trigger, request.findings ?? [], request.artifacts);
|
|
158
|
+
return {
|
|
159
|
+
escalate: true,
|
|
160
|
+
reason: budgetEscalation.detail,
|
|
161
|
+
context,
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
const failures = evaluations.filter((e) => e.result === 'fail');
|
|
165
|
+
if (failures.length > 0) {
|
|
166
|
+
const reasons = failures.map((f) => f.detail);
|
|
167
|
+
return {
|
|
168
|
+
allowed: false,
|
|
169
|
+
reason: reasons.join('; '),
|
|
170
|
+
remediation: failures.map((f) => `Fix: ${f.detail}`).join('; '),
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
return {
|
|
174
|
+
allowed: true,
|
|
175
|
+
reason: 'All governance policies passed',
|
|
176
|
+
};
|
|
177
|
+
}
|
|
178
|
+
checkOwnership(request) {
|
|
179
|
+
if (!this.ownershipEnforcer) {
|
|
180
|
+
return { allowed: true, reason: 'No ownership enforcer configured' };
|
|
181
|
+
}
|
|
182
|
+
const roleId = request.from.toLowerCase().replace(/_/g, '-');
|
|
183
|
+
return this.ownershipEnforcer.validateTransitionArtifacts(roleId, request.artifacts, true);
|
|
184
|
+
}
|
|
185
|
+
toOutcome(decision) {
|
|
186
|
+
if ('escalate' in decision) {
|
|
187
|
+
return 'escalated';
|
|
188
|
+
}
|
|
189
|
+
if (decision.allowed) {
|
|
190
|
+
return 'allowed';
|
|
191
|
+
}
|
|
192
|
+
return 'denied';
|
|
193
|
+
}
|
|
194
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { IterationContract, IterationLimitDefaults } from '@ai-dev-orchestrator/schemas';
|
|
2
|
+
/** Build all iteration contracts using the provided governance limits. */
|
|
3
|
+
export declare function buildContracts(limits: IterationLimitDefaults): readonly IterationContract[];
|
|
4
|
+
/** Convenience aliases built with fallback limits — use `buildContracts(limits)` in production. */
|
|
5
|
+
export declare const PLAN_REVIEW_LOOP: IterationContract;
|
|
6
|
+
export declare const IMPLEMENTATION_REVIEW_LOOP: IterationContract;
|
|
7
|
+
export declare const CLARIFICATION_LOOP: IterationContract;
|
|
8
|
+
export declare const ACCEPTANCE_VALIDATION_LOOP: IterationContract;
|
|
9
|
+
/** All built-in iteration contracts (with fallback limits). */
|
|
10
|
+
export declare const BUILT_IN_CONTRACTS: readonly IterationContract[];
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fallback limits used only when no governance config is available (e.g. fixture mode).
|
|
3
|
+
* Production runs always use values from governance.yaml / UI settings.
|
|
4
|
+
*/
|
|
5
|
+
const FALLBACK_LIMITS = {
|
|
6
|
+
maxReviewIterations: 5,
|
|
7
|
+
maxJudgeArbitrations: 3,
|
|
8
|
+
maxClarificationRounds: 3,
|
|
9
|
+
maxAcceptanceIterations: 3,
|
|
10
|
+
};
|
|
11
|
+
function buildPlanReviewLoop(limits) {
|
|
12
|
+
return {
|
|
13
|
+
id: 'plan_review_loop',
|
|
14
|
+
name: 'Plan Review Loop',
|
|
15
|
+
description: 'Iterative review of the implementation plan by the plan reviewer',
|
|
16
|
+
producer: 'planner',
|
|
17
|
+
reviewers: [
|
|
18
|
+
{
|
|
19
|
+
role: 'plan_reviewer',
|
|
20
|
+
output: 'plan_review',
|
|
21
|
+
inputs: ['plan'],
|
|
22
|
+
},
|
|
23
|
+
],
|
|
24
|
+
aggregation: 'all_must_pass',
|
|
25
|
+
producerInputs: ['canonical_specification', 'clarification_answers'],
|
|
26
|
+
producerOutput: 'plan',
|
|
27
|
+
successCondition: { type: 'no_blocking_findings' },
|
|
28
|
+
failureCondition: { type: 'max_iterations_exceeded' },
|
|
29
|
+
maxIterations: limits.maxReviewIterations,
|
|
30
|
+
maxJudgeArbitrations: limits.maxJudgeArbitrations,
|
|
31
|
+
escalationPolicy: {
|
|
32
|
+
action: 'escalate_to_human',
|
|
33
|
+
produceEscalationArtifact: true,
|
|
34
|
+
includeFullHistory: true,
|
|
35
|
+
},
|
|
36
|
+
completionAgreement: 'planning_agreement',
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
function buildImplementationReviewLoop(limits) {
|
|
40
|
+
return {
|
|
41
|
+
id: 'implementation_review_loop',
|
|
42
|
+
name: 'Implementation Review Loop',
|
|
43
|
+
description: 'Iterative review of implementation by all configured code reviewers',
|
|
44
|
+
producer: 'implementer',
|
|
45
|
+
reviewers: [
|
|
46
|
+
{
|
|
47
|
+
role: 'static_reviewer',
|
|
48
|
+
output: 'static_review',
|
|
49
|
+
inputs: ['implementation'],
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
role: 'security_reviewer',
|
|
53
|
+
output: 'security_review',
|
|
54
|
+
inputs: ['implementation'],
|
|
55
|
+
},
|
|
56
|
+
{
|
|
57
|
+
role: 'performance_reviewer',
|
|
58
|
+
output: 'performance_review',
|
|
59
|
+
inputs: ['implementation'],
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
role: 'adversarial_reviewer',
|
|
63
|
+
output: 'adversarial_review',
|
|
64
|
+
inputs: ['implementation'],
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
role: 'design_reviewer',
|
|
68
|
+
output: 'design_review',
|
|
69
|
+
inputs: ['implementation'],
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
role: 'docs_reviewer',
|
|
73
|
+
output: 'docs_review',
|
|
74
|
+
inputs: ['implementation'],
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
role: 'ux_reviewer',
|
|
78
|
+
output: 'ux_review',
|
|
79
|
+
inputs: ['implementation'],
|
|
80
|
+
},
|
|
81
|
+
],
|
|
82
|
+
aggregation: 'all_must_pass',
|
|
83
|
+
producerInputs: ['plan', 'test_plan'],
|
|
84
|
+
producerOutput: 'implementation',
|
|
85
|
+
successCondition: { type: 'no_blocking_findings' },
|
|
86
|
+
failureCondition: { type: 'max_iterations_exceeded' },
|
|
87
|
+
maxIterations: limits.maxReviewIterations,
|
|
88
|
+
maxJudgeArbitrations: limits.maxJudgeArbitrations,
|
|
89
|
+
escalationPolicy: {
|
|
90
|
+
action: 'escalate_to_human',
|
|
91
|
+
produceEscalationArtifact: true,
|
|
92
|
+
includeFullHistory: true,
|
|
93
|
+
},
|
|
94
|
+
completionAgreement: 'implementation_agreement',
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
function buildClarificationLoop(limits) {
|
|
98
|
+
return {
|
|
99
|
+
id: 'clarification_loop',
|
|
100
|
+
name: 'Clarification Loop',
|
|
101
|
+
description: 'Iterative clarification of requirements with the human',
|
|
102
|
+
producer: 'requirements_analyst',
|
|
103
|
+
reviewers: [],
|
|
104
|
+
aggregation: 'all_must_pass',
|
|
105
|
+
producerInputs: ['canonical_specification'],
|
|
106
|
+
producerOutput: 'clarification_questions',
|
|
107
|
+
successCondition: { type: 'all_findings_addressed' },
|
|
108
|
+
failureCondition: { type: 'max_iterations_exceeded' },
|
|
109
|
+
maxIterations: limits.maxClarificationRounds,
|
|
110
|
+
maxJudgeArbitrations: 0,
|
|
111
|
+
escalationPolicy: {
|
|
112
|
+
action: 'abort',
|
|
113
|
+
produceEscalationArtifact: false,
|
|
114
|
+
includeFullHistory: false,
|
|
115
|
+
},
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
function buildAcceptanceValidationLoop(limits) {
|
|
119
|
+
return {
|
|
120
|
+
id: 'acceptance_validation_loop',
|
|
121
|
+
name: 'Acceptance Validation Loop',
|
|
122
|
+
description: 'Iterative acceptance validation cycle — implementer addresses uncovered or failed criteria',
|
|
123
|
+
producer: 'implementer',
|
|
124
|
+
reviewers: [],
|
|
125
|
+
aggregation: 'all_must_pass',
|
|
126
|
+
producerInputs: ['plan', 'canonical_specification', 'acceptance_validation'],
|
|
127
|
+
producerOutput: 'implementation',
|
|
128
|
+
successCondition: { type: 'all_findings_addressed' },
|
|
129
|
+
failureCondition: { type: 'max_iterations_exceeded' },
|
|
130
|
+
maxIterations: limits.maxAcceptanceIterations,
|
|
131
|
+
maxJudgeArbitrations: 0,
|
|
132
|
+
escalationPolicy: {
|
|
133
|
+
action: 'escalate_to_human',
|
|
134
|
+
produceEscalationArtifact: true,
|
|
135
|
+
includeFullHistory: true,
|
|
136
|
+
},
|
|
137
|
+
completionAgreement: 'verification_agreement',
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
/** Build all iteration contracts using the provided governance limits. */
|
|
141
|
+
export function buildContracts(limits) {
|
|
142
|
+
return [
|
|
143
|
+
buildPlanReviewLoop(limits),
|
|
144
|
+
buildImplementationReviewLoop(limits),
|
|
145
|
+
buildClarificationLoop(limits),
|
|
146
|
+
buildAcceptanceValidationLoop(limits),
|
|
147
|
+
];
|
|
148
|
+
}
|
|
149
|
+
/** Convenience aliases built with fallback limits — use `buildContracts(limits)` in production. */
|
|
150
|
+
export const PLAN_REVIEW_LOOP = buildPlanReviewLoop(FALLBACK_LIMITS);
|
|
151
|
+
export const IMPLEMENTATION_REVIEW_LOOP = buildImplementationReviewLoop(FALLBACK_LIMITS);
|
|
152
|
+
export const CLARIFICATION_LOOP = buildClarificationLoop(FALLBACK_LIMITS);
|
|
153
|
+
export const ACCEPTANCE_VALIDATION_LOOP = buildAcceptanceValidationLoop(FALLBACK_LIMITS);
|
|
154
|
+
/** All built-in iteration contracts (with fallback limits). */
|
|
155
|
+
export const BUILT_IN_CONTRACTS = [
|
|
156
|
+
PLAN_REVIEW_LOOP,
|
|
157
|
+
IMPLEMENTATION_REVIEW_LOOP,
|
|
158
|
+
CLARIFICATION_LOOP,
|
|
159
|
+
ACCEPTANCE_VALIDATION_LOOP,
|
|
160
|
+
];
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { IterationContractRegistry } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
import type { IterationContract, IterationState } from '@ai-dev-orchestrator/schemas';
|
|
3
|
+
/** Default registry of iteration contracts with built-in contracts pre-loaded. */
|
|
4
|
+
export declare class DefaultIterationContractRegistry implements IterationContractRegistry {
|
|
5
|
+
private readonly contracts;
|
|
6
|
+
private readonly iterationCounts;
|
|
7
|
+
private readonly judgeArbitrationCounts;
|
|
8
|
+
private readonly findingStatuses;
|
|
9
|
+
constructor(additionalContracts?: readonly IterationContract[]);
|
|
10
|
+
/** @inheritdoc */
|
|
11
|
+
getContract(id: string): IterationContract | null;
|
|
12
|
+
/** @inheritdoc */
|
|
13
|
+
listContracts(): readonly IterationContract[];
|
|
14
|
+
/** @inheritdoc */
|
|
15
|
+
getContractForState(stateId: string): IterationContract | null;
|
|
16
|
+
/** Record that the FSM entered a state, incrementing the iteration count only for round-entry states. */
|
|
17
|
+
recordStateEntry(stateId: string, _stateType?: string): void;
|
|
18
|
+
/** Restore iteration counts from persisted state (e.g. on resume). */
|
|
19
|
+
restoreIterationCounts(counts: Map<string, number>): void;
|
|
20
|
+
/** Restore judge arbitration counts from persisted state (e.g. on resume). */
|
|
21
|
+
restoreJudgeArbitrationCounts(counts: ReadonlyMap<string, number>): void;
|
|
22
|
+
/** Reset iteration count for a specific contract (e.g. after human rejection restarts a loop). */
|
|
23
|
+
resetIterationCount(contractId: string): void;
|
|
24
|
+
/** Record a finding being raised or resolved, scoped to a contract. */
|
|
25
|
+
recordFinding(contractId: string, findingId: string, status: 'open' | 'resolved'): void;
|
|
26
|
+
/** Get the current iteration counts for all contracts. */
|
|
27
|
+
getIterationCounts(): ReadonlyMap<string, number>;
|
|
28
|
+
/** Get the current judge arbitration counts for all contracts. */
|
|
29
|
+
getJudgeArbitrationCounts(): ReadonlyMap<string, number>;
|
|
30
|
+
/** @inheritdoc */
|
|
31
|
+
getIterationState(contractId: string): IterationState;
|
|
32
|
+
}
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { BUILT_IN_CONTRACTS } from './built-in-contracts';
|
|
2
|
+
const STATE_TO_CONTRACT = {
|
|
3
|
+
PLAN_REVIEW: 'plan_review_loop',
|
|
4
|
+
CODE_REVIEW: 'implementation_review_loop',
|
|
5
|
+
REVIEW_SYNTHESIS: 'implementation_review_loop',
|
|
6
|
+
IMPLEMENTATION: 'implementation_review_loop',
|
|
7
|
+
TEST_AUTHORING: 'implementation_review_loop',
|
|
8
|
+
JUDGE_REVIEW: 'implementation_review_loop',
|
|
9
|
+
REFINEMENT: 'clarification_loop',
|
|
10
|
+
WAITING_FOR_HUMAN: 'clarification_loop',
|
|
11
|
+
ACCEPTANCE_VALIDATION: 'acceptance_validation_loop',
|
|
12
|
+
};
|
|
13
|
+
const ROUND_ENTRY_STATES = new Set([
|
|
14
|
+
'PLAN_REVIEW',
|
|
15
|
+
'CODE_REVIEW',
|
|
16
|
+
'REFINEMENT',
|
|
17
|
+
'ACCEPTANCE_VALIDATION',
|
|
18
|
+
]);
|
|
19
|
+
const JUDGE_ENTRY_STATES = new Set(['JUDGE_REVIEW']);
|
|
20
|
+
/** Default registry of iteration contracts with built-in contracts pre-loaded. */
|
|
21
|
+
export class DefaultIterationContractRegistry {
|
|
22
|
+
contracts = new Map();
|
|
23
|
+
iterationCounts = new Map();
|
|
24
|
+
judgeArbitrationCounts = new Map();
|
|
25
|
+
findingStatuses = new Map();
|
|
26
|
+
constructor(additionalContracts = []) {
|
|
27
|
+
for (const contract of BUILT_IN_CONTRACTS) {
|
|
28
|
+
this.contracts.set(contract.id, contract);
|
|
29
|
+
}
|
|
30
|
+
for (const contract of additionalContracts) {
|
|
31
|
+
this.contracts.set(contract.id, contract);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** @inheritdoc */
|
|
35
|
+
getContract(id) {
|
|
36
|
+
return this.contracts.get(id) ?? null;
|
|
37
|
+
}
|
|
38
|
+
/** @inheritdoc */
|
|
39
|
+
listContracts() {
|
|
40
|
+
return [...this.contracts.values()];
|
|
41
|
+
}
|
|
42
|
+
/** @inheritdoc */
|
|
43
|
+
getContractForState(stateId) {
|
|
44
|
+
const contractId = STATE_TO_CONTRACT[stateId];
|
|
45
|
+
if (!contractId) {
|
|
46
|
+
return null;
|
|
47
|
+
}
|
|
48
|
+
return this.contracts.get(contractId) ?? null;
|
|
49
|
+
}
|
|
50
|
+
/** Record that the FSM entered a state, incrementing the iteration count only for round-entry states. */
|
|
51
|
+
recordStateEntry(stateId, _stateType) {
|
|
52
|
+
const contract = this.getContractForState(stateId);
|
|
53
|
+
if (!contract) {
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
if (JUDGE_ENTRY_STATES.has(stateId)) {
|
|
57
|
+
const current = this.judgeArbitrationCounts.get(contract.id) ?? 0;
|
|
58
|
+
this.judgeArbitrationCounts.set(contract.id, current + 1);
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
if (!ROUND_ENTRY_STATES.has(stateId)) {
|
|
62
|
+
return;
|
|
63
|
+
}
|
|
64
|
+
const current = this.iterationCounts.get(contract.id) ?? 0;
|
|
65
|
+
this.iterationCounts.set(contract.id, current + 1);
|
|
66
|
+
}
|
|
67
|
+
/** Restore iteration counts from persisted state (e.g. on resume). */
|
|
68
|
+
restoreIterationCounts(counts) {
|
|
69
|
+
for (const [contractId, count] of counts) {
|
|
70
|
+
this.iterationCounts.set(contractId, count);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
/** Restore judge arbitration counts from persisted state (e.g. on resume). */
|
|
74
|
+
restoreJudgeArbitrationCounts(counts) {
|
|
75
|
+
for (const [contractId, count] of counts) {
|
|
76
|
+
this.judgeArbitrationCounts.set(contractId, count);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/** Reset iteration count for a specific contract (e.g. after human rejection restarts a loop). */
|
|
80
|
+
resetIterationCount(contractId) {
|
|
81
|
+
this.iterationCounts.set(contractId, 0);
|
|
82
|
+
}
|
|
83
|
+
/** Record a finding being raised or resolved, scoped to a contract. */
|
|
84
|
+
recordFinding(contractId, findingId, status) {
|
|
85
|
+
let findings = this.findingStatuses.get(contractId);
|
|
86
|
+
if (!findings) {
|
|
87
|
+
findings = new Map();
|
|
88
|
+
this.findingStatuses.set(contractId, findings);
|
|
89
|
+
}
|
|
90
|
+
findings.set(findingId, status);
|
|
91
|
+
}
|
|
92
|
+
/** Get the current iteration counts for all contracts. */
|
|
93
|
+
getIterationCounts() {
|
|
94
|
+
return this.iterationCounts;
|
|
95
|
+
}
|
|
96
|
+
/** Get the current judge arbitration counts for all contracts. */
|
|
97
|
+
getJudgeArbitrationCounts() {
|
|
98
|
+
return this.judgeArbitrationCounts;
|
|
99
|
+
}
|
|
100
|
+
/** @inheritdoc */
|
|
101
|
+
getIterationState(contractId) {
|
|
102
|
+
const contract = this.contracts.get(contractId);
|
|
103
|
+
const currentIteration = this.iterationCounts.get(contractId) ?? 0;
|
|
104
|
+
const judgeArbitrations = this.judgeArbitrationCounts.get(contractId) ?? 0;
|
|
105
|
+
let findingsTotal = 0;
|
|
106
|
+
let findingsResolved = 0;
|
|
107
|
+
const contractFindings = this.findingStatuses.get(contractId);
|
|
108
|
+
if (contractFindings) {
|
|
109
|
+
for (const status of contractFindings.values()) {
|
|
110
|
+
findingsTotal++;
|
|
111
|
+
if (status === 'resolved') {
|
|
112
|
+
findingsResolved++;
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
const findingsOpen = findingsTotal - findingsResolved;
|
|
117
|
+
if (!contract) {
|
|
118
|
+
return {
|
|
119
|
+
contractId,
|
|
120
|
+
currentIteration,
|
|
121
|
+
judgeArbitrations,
|
|
122
|
+
producerArtifactVersions: [],
|
|
123
|
+
reviewerArtifactVersions: [],
|
|
124
|
+
findingsTotal,
|
|
125
|
+
findingsResolved,
|
|
126
|
+
findingsOpen,
|
|
127
|
+
status: 'in_progress',
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
const exceeded = currentIteration >= contract.maxIterations;
|
|
131
|
+
const status = exceeded ? 'failed' : 'in_progress';
|
|
132
|
+
return {
|
|
133
|
+
contractId,
|
|
134
|
+
currentIteration,
|
|
135
|
+
judgeArbitrations,
|
|
136
|
+
producerArtifactVersions: [],
|
|
137
|
+
reviewerArtifactVersions: [],
|
|
138
|
+
findingsTotal,
|
|
139
|
+
findingsResolved,
|
|
140
|
+
findingsOpen,
|
|
141
|
+
status,
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@ai-dev-orchestrator/governance",
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git+https://github.com/caponetto/ai-dev-orchestrator.git",
|
|
8
|
+
"directory": "packages/governance"
|
|
9
|
+
},
|
|
10
|
+
"type": "module",
|
|
11
|
+
"engines": {
|
|
12
|
+
"node": ">=22"
|
|
13
|
+
},
|
|
14
|
+
"exports": {
|
|
15
|
+
".": {
|
|
16
|
+
"types": "./dist/index.d.ts",
|
|
17
|
+
"import": "./dist/index.js"
|
|
18
|
+
}
|
|
19
|
+
},
|
|
20
|
+
"files": [
|
|
21
|
+
"dist"
|
|
22
|
+
],
|
|
23
|
+
"dependencies": {
|
|
24
|
+
"@ai-dev-orchestrator/ports": "0.1.1",
|
|
25
|
+
"@ai-dev-orchestrator/schemas": "0.1.1"
|
|
26
|
+
},
|
|
27
|
+
"devDependencies": {
|
|
28
|
+
"@types/node": "^26.4.0",
|
|
29
|
+
"vitest": "^4.1.11",
|
|
30
|
+
"@ai-dev-orchestrator/artifacts": "0.1.1",
|
|
31
|
+
"@ai-dev-orchestrator/role-system": "0.1.1",
|
|
32
|
+
"@ai-dev-orchestrator/build-config": "0.1.1",
|
|
33
|
+
"@ai-dev-orchestrator/test-utils": "0.1.1"
|
|
34
|
+
},
|
|
35
|
+
"scripts": {
|
|
36
|
+
"clean": "rimraf dist tsconfig.build.tsbuildinfo",
|
|
37
|
+
"build:base": "rimraf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
|
|
38
|
+
"build:dev": "pnpm run build:base",
|
|
39
|
+
"build:prod": "pnpm run clean && tsc -p tsconfig.build.json --sourceMap false --declarationMap false",
|
|
40
|
+
"lint": "eslint src/ test/",
|
|
41
|
+
"test:unit": "vitest run",
|
|
42
|
+
"typecheck": "tsc -p tsconfig.build.json --noEmit"
|
|
43
|
+
}
|
|
44
|
+
}
|