@ai-dev-orchestrator/policy-engine 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 +40 -0
- package/dist/domain/errors.d.ts +28 -0
- package/dist/domain/errors.js +41 -0
- package/dist/domain/index.d.ts +1 -0
- package/dist/domain/index.js +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +4 -0
- package/dist/infrastructure/confidence-evaluator.d.ts +6 -0
- package/dist/infrastructure/confidence-evaluator.js +72 -0
- package/dist/infrastructure/custom-evaluator.d.ts +7 -0
- package/dist/infrastructure/custom-evaluator.js +12 -0
- package/dist/infrastructure/default-policy-engine.d.ts +30 -0
- package/dist/infrastructure/default-policy-engine.js +78 -0
- package/dist/infrastructure/governance-file-loader.d.ts +5 -0
- package/dist/infrastructure/governance-file-loader.js +120 -0
- package/dist/infrastructure/index.d.ts +4 -0
- package/dist/infrastructure/index.js +4 -0
- package/dist/infrastructure/iteration-limit-evaluator.d.ts +7 -0
- package/dist/infrastructure/iteration-limit-evaluator.js +35 -0
- package/dist/infrastructure/model-constraint-evaluator.d.ts +7 -0
- package/dist/infrastructure/model-constraint-evaluator.js +45 -0
- package/dist/infrastructure/ownership-evaluator.d.ts +7 -0
- package/dist/infrastructure/ownership-evaluator.js +49 -0
- package/dist/infrastructure/policy-registry.d.ts +23 -0
- package/dist/infrastructure/policy-registry.js +112 -0
- package/dist/infrastructure/policy-resolver.d.ts +29 -0
- package/dist/infrastructure/policy-resolver.js +99 -0
- package/dist/infrastructure/quality-gate-evaluator.d.ts +7 -0
- package/dist/infrastructure/quality-gate-evaluator.js +61 -0
- package/dist/infrastructure/retry-limit-evaluator.d.ts +7 -0
- package/dist/infrastructure/retry-limit-evaluator.js +28 -0
- package/dist/infrastructure/specification-readiness-evaluator.d.ts +7 -0
- package/dist/infrastructure/specification-readiness-evaluator.js +38 -0
- package/dist/infrastructure/stage-skip-evaluator.d.ts +8 -0
- package/dist/infrastructure/stage-skip-evaluator.js +45 -0
- package/dist/infrastructure/token-budget-evaluator.d.ts +7 -0
- package/dist/infrastructure/token-budget-evaluator.js +28 -0
- package/package.json +45 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AI Dev Orchestrator Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# @ai-dev-orchestrator/policy-engine
|
|
2
|
+
|
|
3
|
+
Policy evaluation engine that loads, resolves, and enforces governance policies from YAML configuration. Provides the rule evaluation layer that the governance engine delegates to for iteration limits, quality thresholds, and budget constraints.
|
|
4
|
+
|
|
5
|
+
## Architecture Layer
|
|
6
|
+
|
|
7
|
+
**Domain** -- defines the policy model, resolution logic, and evaluation semantics.
|
|
8
|
+
|
|
9
|
+
## Workspace Dependencies
|
|
10
|
+
|
|
11
|
+
- `@ai-dev-orchestrator/ports`
|
|
12
|
+
- `@ai-dev-orchestrator/schemas`
|
|
13
|
+
- `@ai-dev-orchestrator/utils`
|
|
14
|
+
|
|
15
|
+
## Structure
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
src/
|
|
19
|
+
domain/
|
|
20
|
+
__tests__/
|
|
21
|
+
infrastructure/
|
|
22
|
+
__tests__/
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Key Exports
|
|
26
|
+
|
|
27
|
+
### Domain
|
|
28
|
+
|
|
29
|
+
- `PolicyEvaluationError` -- thrown when a policy fails to evaluate
|
|
30
|
+
- `PolicyConfigurationError` -- thrown for invalid policy configuration
|
|
31
|
+
- `PolicyResolverError` -- thrown when policy resolution fails
|
|
32
|
+
- `UnknownPolicyTypeError` -- thrown for unrecognized policy types
|
|
33
|
+
|
|
34
|
+
### Infrastructure
|
|
35
|
+
|
|
36
|
+
- `DefaultPolicyEngine` -- evaluates policies against the current workflow state
|
|
37
|
+
- `DefaultPolicyRegistry` -- stores and retrieves registered policy definitions
|
|
38
|
+
- `PolicyResolver` -- resolves which policies apply to a given context
|
|
39
|
+
- `loadGovernanceFromYaml` -- parses governance configuration from YAML files
|
|
40
|
+
- `loadPoliciesFromGovernance` -- extracts policy definitions from a governance config
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { NonRecoverableErrorBase } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
import type { PolicyType } from '@ai-dev-orchestrator/schemas';
|
|
3
|
+
/** Thrown when a policy evaluation fails unexpectedly. */
|
|
4
|
+
export declare class PolicyEvaluationError extends NonRecoverableErrorBase {
|
|
5
|
+
readonly policyId: string;
|
|
6
|
+
readonly cause: string;
|
|
7
|
+
readonly code = "POLICY_EVALUATION_ERROR";
|
|
8
|
+
constructor(policyId: string, cause: string);
|
|
9
|
+
}
|
|
10
|
+
/** Thrown when a policy definition is invalid or misconfigured. */
|
|
11
|
+
export declare class PolicyConfigurationError extends NonRecoverableErrorBase {
|
|
12
|
+
readonly policyId: string;
|
|
13
|
+
readonly cause: string;
|
|
14
|
+
readonly code = "POLICY_CONFIGURATION_ERROR";
|
|
15
|
+
constructor(policyId: string, cause: string);
|
|
16
|
+
}
|
|
17
|
+
/** Thrown when an unregistered policy type is referenced. */
|
|
18
|
+
export declare class UnknownPolicyTypeError extends NonRecoverableErrorBase {
|
|
19
|
+
readonly policyType: PolicyType;
|
|
20
|
+
readonly code = "UNKNOWN_POLICY_TYPE";
|
|
21
|
+
constructor(policyType: PolicyType);
|
|
22
|
+
}
|
|
23
|
+
/** Thrown when policy resolution fails. */
|
|
24
|
+
export declare class PolicyResolverError extends NonRecoverableErrorBase {
|
|
25
|
+
readonly cause: string;
|
|
26
|
+
readonly code = "POLICY_RESOLVER_ERROR";
|
|
27
|
+
constructor(cause: string);
|
|
28
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { NonRecoverableErrorBase } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
/** Thrown when a policy evaluation fails unexpectedly. */
|
|
3
|
+
export class PolicyEvaluationError extends NonRecoverableErrorBase {
|
|
4
|
+
policyId;
|
|
5
|
+
cause;
|
|
6
|
+
code = 'POLICY_EVALUATION_ERROR';
|
|
7
|
+
constructor(policyId, cause) {
|
|
8
|
+
super(`Policy evaluation failed for "${policyId}": ${cause}`);
|
|
9
|
+
this.policyId = policyId;
|
|
10
|
+
this.cause = cause;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
/** Thrown when a policy definition is invalid or misconfigured. */
|
|
14
|
+
export class PolicyConfigurationError extends NonRecoverableErrorBase {
|
|
15
|
+
policyId;
|
|
16
|
+
cause;
|
|
17
|
+
code = 'POLICY_CONFIGURATION_ERROR';
|
|
18
|
+
constructor(policyId, cause) {
|
|
19
|
+
super(`Invalid policy configuration for "${policyId}": ${cause}`);
|
|
20
|
+
this.policyId = policyId;
|
|
21
|
+
this.cause = cause;
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
/** Thrown when an unregistered policy type is referenced. */
|
|
25
|
+
export class UnknownPolicyTypeError extends NonRecoverableErrorBase {
|
|
26
|
+
policyType;
|
|
27
|
+
code = 'UNKNOWN_POLICY_TYPE';
|
|
28
|
+
constructor(policyType) {
|
|
29
|
+
super(`Unknown policy type: "${policyType}"`);
|
|
30
|
+
this.policyType = policyType;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
/** Thrown when policy resolution fails. */
|
|
34
|
+
export class PolicyResolverError extends NonRecoverableErrorBase {
|
|
35
|
+
cause;
|
|
36
|
+
code = 'POLICY_RESOLVER_ERROR';
|
|
37
|
+
constructor(cause) {
|
|
38
|
+
super(`Policy resolution failed: ${cause}`);
|
|
39
|
+
this.cause = cause;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { PolicyConfigurationError, PolicyEvaluationError, PolicyResolverError, UnknownPolicyTypeError, } from './errors';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { PolicyConfigurationError, PolicyEvaluationError, PolicyResolverError, UnknownPolicyTypeError, } from './errors';
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
export { PolicyConfigurationError, PolicyEvaluationError, PolicyResolverError, UnknownPolicyTypeError, } from './domain/index';
|
|
2
|
+
export { DefaultPolicyEngine, DefaultPolicyRegistry, loadGovernanceFromYaml, loadPoliciesFromGovernance, PolicyResolver, } from './infrastructure/index';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
// Domain — Policy Engine
|
|
2
|
+
export { PolicyConfigurationError, PolicyEvaluationError, PolicyResolverError, UnknownPolicyTypeError, } from './domain/index';
|
|
3
|
+
// Infrastructure — Policy Engine
|
|
4
|
+
export { DefaultPolicyEngine, DefaultPolicyRegistry, loadGovernanceFromYaml, loadPoliciesFromGovernance, PolicyResolver, } from './infrastructure/index';
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
3
|
+
export declare class ConfidenceEvaluator implements PolicyEvaluator {
|
|
4
|
+
evaluate(policy: PolicyDefinition, context: PolicyContext): PolicyResult;
|
|
5
|
+
private computeHeuristicScore;
|
|
6
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
const RETRY_PENALTY = 0.15;
|
|
2
|
+
const MAX_RETRY_PENALTY = 0.45;
|
|
3
|
+
const HIGH_FINDING_PENALTY = 0.2;
|
|
4
|
+
const TOKEN_OVERUSE_PENALTY = 0.15;
|
|
5
|
+
const TOKEN_OVERUSE_RATIO = 0.8;
|
|
6
|
+
const DIVERGENCE_THRESHOLD = 0.3;
|
|
7
|
+
export class ConfidenceEvaluator {
|
|
8
|
+
evaluate(policy, context) {
|
|
9
|
+
if (policy.type !== 'confidence_gate') {
|
|
10
|
+
throw new Error(`ConfidenceEvaluator received policy type '${policy.type}'`);
|
|
11
|
+
}
|
|
12
|
+
const config = policy.config;
|
|
13
|
+
const report = context.metadata?.confidenceReport;
|
|
14
|
+
const heuristicScore = this.computeHeuristicScore(context, config);
|
|
15
|
+
let finalScore;
|
|
16
|
+
let reason;
|
|
17
|
+
if (report) {
|
|
18
|
+
const agentScore = report.score;
|
|
19
|
+
const divergence = Math.abs(agentScore - heuristicScore);
|
|
20
|
+
if (divergence > DIVERGENCE_THRESHOLD) {
|
|
21
|
+
finalScore = Math.min(agentScore, heuristicScore);
|
|
22
|
+
reason = `Agent (${agentScore.toFixed(2)}) and heuristic (${heuristicScore.toFixed(2)}) scores diverge by ${divergence.toFixed(2)} — using lower score`;
|
|
23
|
+
}
|
|
24
|
+
else {
|
|
25
|
+
finalScore =
|
|
26
|
+
agentScore * (1 - config.heuristicWeight) + heuristicScore * config.heuristicWeight;
|
|
27
|
+
reason = `Blended score: agent=${agentScore.toFixed(2)}, heuristic=${heuristicScore.toFixed(2)}, final=${finalScore.toFixed(2)}`;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
else {
|
|
31
|
+
finalScore = heuristicScore;
|
|
32
|
+
reason = `No agent confidence report — heuristic-only score: ${heuristicScore.toFixed(2)}`;
|
|
33
|
+
}
|
|
34
|
+
if (finalScore >= config.modelEscalationThreshold) {
|
|
35
|
+
return {
|
|
36
|
+
policyId: policy.id,
|
|
37
|
+
policyType: 'confidence_gate',
|
|
38
|
+
outcome: 'pass',
|
|
39
|
+
reason,
|
|
40
|
+
source: { layer: 'builtin' },
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
return {
|
|
44
|
+
policyId: policy.id,
|
|
45
|
+
policyType: 'confidence_gate',
|
|
46
|
+
outcome: 'fail',
|
|
47
|
+
reason,
|
|
48
|
+
source: { layer: 'builtin' },
|
|
49
|
+
escalationTrigger: 'confidence_too_low',
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
computeHeuristicScore(context, config) {
|
|
53
|
+
let score = 1.0;
|
|
54
|
+
if (config.heuristicSignals.penalizeHighRetryCount) {
|
|
55
|
+
const retryCount = context.metadata?.retryCount ?? 0;
|
|
56
|
+
if (retryCount > 0) {
|
|
57
|
+
score -= Math.min(RETRY_PENALTY * retryCount, MAX_RETRY_PENALTY);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
if (config.heuristicSignals.penalizeUnresolvedFindings && context.findings) {
|
|
61
|
+
const highSeverityOpen = context.findings.filter((f) => f.severity === 'high' && f.status === 'open');
|
|
62
|
+
score -= HIGH_FINDING_PENALTY * highSeverityOpen.length;
|
|
63
|
+
}
|
|
64
|
+
if (context.tokenUsage) {
|
|
65
|
+
const budgetRatio = context.tokenUsage.totalTokens / (context.tokenUsage.totalTokens + 1);
|
|
66
|
+
if (budgetRatio > TOKEN_OVERUSE_RATIO) {
|
|
67
|
+
score -= TOKEN_OVERUSE_PENALTY;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
return Math.max(0, score);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Pass-through evaluator for custom policies. Always returns pass. */
|
|
2
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
3
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
4
|
+
export declare class CustomEvaluator implements PolicyEvaluator {
|
|
5
|
+
/** @inheritdoc */
|
|
6
|
+
evaluate(policy: PolicyDefinition, _context: PolicyContext): PolicyResult;
|
|
7
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { PolicyEngine } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
import type { PolicyContext, PolicyDecision, PolicyDefinition, PolicyScope, PolicyTypeInfo, PolicyValidationResult, ResolvedPolicySet } from '@ai-dev-orchestrator/schemas';
|
|
3
|
+
import type { DefaultPolicyRegistry } from './policy-registry';
|
|
4
|
+
import type { PolicyResolver } from './policy-resolver';
|
|
5
|
+
/** Default stateless policy engine that resolves, evaluates, and synthesizes policy decisions. */
|
|
6
|
+
export declare class DefaultPolicyEngine implements PolicyEngine {
|
|
7
|
+
private readonly registry;
|
|
8
|
+
private readonly resolver;
|
|
9
|
+
constructor(registry: DefaultPolicyRegistry, resolver: PolicyResolver);
|
|
10
|
+
/**
|
|
11
|
+
* Evaluate all resolved policies against a runtime context.
|
|
12
|
+
* @param context - Current run state, iteration count, and artifacts
|
|
13
|
+
* @returns Aggregated decision: allow, deny, or escalate
|
|
14
|
+
*/
|
|
15
|
+
evaluate(context: PolicyContext): PolicyDecision;
|
|
16
|
+
/**
|
|
17
|
+
* Resolve the effective policy set for a given scope.
|
|
18
|
+
* @param scope - Scope filter for policy resolution
|
|
19
|
+
* @returns Merged policy set with full audit trail
|
|
20
|
+
*/
|
|
21
|
+
resolve(scope: PolicyScope): ResolvedPolicySet;
|
|
22
|
+
/**
|
|
23
|
+
* Validate a policy definition against the registry.
|
|
24
|
+
* @param definition - Policy definition to validate
|
|
25
|
+
* @returns Validation result with errors and warnings
|
|
26
|
+
*/
|
|
27
|
+
validate(definition: PolicyDefinition): PolicyValidationResult;
|
|
28
|
+
/** @inheritdoc */
|
|
29
|
+
listPolicyTypes(): readonly PolicyTypeInfo[];
|
|
30
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/** Default stateless policy engine that resolves, evaluates, and synthesizes policy decisions. */
|
|
2
|
+
export class DefaultPolicyEngine {
|
|
3
|
+
registry;
|
|
4
|
+
resolver;
|
|
5
|
+
constructor(registry, resolver) {
|
|
6
|
+
this.registry = registry;
|
|
7
|
+
this.resolver = resolver;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Evaluate all resolved policies against a runtime context.
|
|
11
|
+
* @param context - Current run state, iteration count, and artifacts
|
|
12
|
+
* @returns Aggregated decision: allow, deny, or escalate
|
|
13
|
+
*/
|
|
14
|
+
evaluate(context) {
|
|
15
|
+
const resolved = this.resolver.resolve({});
|
|
16
|
+
const results = [];
|
|
17
|
+
let escalationTrigger;
|
|
18
|
+
for (const policy of resolved.policies) {
|
|
19
|
+
const evaluator = this.registry.getEvaluator(policy.type);
|
|
20
|
+
const result = evaluator.evaluate(policy, context);
|
|
21
|
+
results.push(result);
|
|
22
|
+
if (result.escalationTrigger) {
|
|
23
|
+
escalationTrigger = result.escalationTrigger;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
if (escalationTrigger) {
|
|
27
|
+
return {
|
|
28
|
+
outcome: 'escalate',
|
|
29
|
+
results,
|
|
30
|
+
reason: `Escalation triggered: ${escalationTrigger}`,
|
|
31
|
+
escalationTrigger,
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
const failures = results.filter((r) => r.outcome === 'fail');
|
|
35
|
+
if (failures.length > 0) {
|
|
36
|
+
const reasons = failures.map((f) => f.reason);
|
|
37
|
+
return {
|
|
38
|
+
outcome: 'deny',
|
|
39
|
+
results,
|
|
40
|
+
reason: reasons.join('; '),
|
|
41
|
+
remediations: failures.map((f) => `Fix: ${f.reason}`),
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
return {
|
|
45
|
+
outcome: 'allow',
|
|
46
|
+
results,
|
|
47
|
+
reason: 'All policies passed',
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Resolve the effective policy set for a given scope.
|
|
52
|
+
* @param scope - Scope filter for policy resolution
|
|
53
|
+
* @returns Merged policy set with full audit trail
|
|
54
|
+
*/
|
|
55
|
+
resolve(scope) {
|
|
56
|
+
return this.resolver.resolve(scope);
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Validate a policy definition against the registry.
|
|
60
|
+
* @param definition - Policy definition to validate
|
|
61
|
+
* @returns Validation result with errors and warnings
|
|
62
|
+
*/
|
|
63
|
+
validate(definition) {
|
|
64
|
+
const errors = [];
|
|
65
|
+
const warnings = [];
|
|
66
|
+
try {
|
|
67
|
+
this.registry.getEvaluator(definition.type);
|
|
68
|
+
}
|
|
69
|
+
catch {
|
|
70
|
+
warnings.push(`No evaluator registered for type "${definition.type}"`);
|
|
71
|
+
}
|
|
72
|
+
return { valid: errors.length === 0, errors, warnings };
|
|
73
|
+
}
|
|
74
|
+
/** @inheritdoc */
|
|
75
|
+
listPolicyTypes() {
|
|
76
|
+
return this.registry.listTypes();
|
|
77
|
+
}
|
|
78
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { GovernanceConfig, PolicyDefinition } from '@ai-dev-orchestrator/schemas';
|
|
2
|
+
/** Parses governance.yaml content into a typed governance configuration. */
|
|
3
|
+
export declare function loadGovernanceFromYaml(yamlContent: string): GovernanceConfig;
|
|
4
|
+
/** Derives policy definitions from a parsed governance configuration. */
|
|
5
|
+
export declare function loadPoliciesFromGovernance(config: GovernanceConfig): PolicyDefinition[];
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { isObject, requireNumber, requireObject, snakeToCamelDeep, } from '@ai-dev-orchestrator/utils';
|
|
2
|
+
import { parse as parseYaml, YAMLParseError } from 'yaml';
|
|
3
|
+
/** Parses governance.yaml content into a typed governance configuration. */
|
|
4
|
+
export function loadGovernanceFromYaml(yamlContent) {
|
|
5
|
+
let parsed;
|
|
6
|
+
try {
|
|
7
|
+
parsed = parseYaml(yamlContent);
|
|
8
|
+
}
|
|
9
|
+
catch (error) {
|
|
10
|
+
const message = error instanceof YAMLParseError ? error.message : `Invalid YAML: ${String(error)}`;
|
|
11
|
+
throw new Error(message);
|
|
12
|
+
}
|
|
13
|
+
const raw = snakeToCamelDeep(parsed);
|
|
14
|
+
if (!isObject(raw)) {
|
|
15
|
+
throw new Error('governance.yaml must contain a YAML mapping');
|
|
16
|
+
}
|
|
17
|
+
const iterationLimits = requireObject(raw, 'iterationLimits');
|
|
18
|
+
const qualityGates = requireObject(raw, 'qualityGates');
|
|
19
|
+
const specificationReadiness = requireObject(qualityGates, 'specificationReadiness');
|
|
20
|
+
const implementationReview = requireObject(qualityGates, 'implementationReview');
|
|
21
|
+
let config = {
|
|
22
|
+
iterationLimits: {
|
|
23
|
+
defaults: {
|
|
24
|
+
maxReviewIterations: requireNumber(iterationLimits, 'maxReviewIterations'),
|
|
25
|
+
maxJudgeArbitrations: requireNumber(iterationLimits, 'maxJudgeArbitrations'),
|
|
26
|
+
maxClarificationRounds: requireNumber(iterationLimits, 'maxClarificationRounds'),
|
|
27
|
+
maxAcceptanceIterations: requireNumber(iterationLimits, 'maxAcceptanceIterations'),
|
|
28
|
+
},
|
|
29
|
+
},
|
|
30
|
+
qualityGates: {
|
|
31
|
+
specificationReadiness: {
|
|
32
|
+
minCompletenessScore: requireNumber(specificationReadiness, 'minCompletenessScore'),
|
|
33
|
+
},
|
|
34
|
+
implementationReview: {
|
|
35
|
+
maxHighSeverityFindings: requireNumber(implementationReview, 'maxHighSeverityFindings'),
|
|
36
|
+
maxMediumSeverityFindings: requireNumber(implementationReview, 'maxMediumSeverityFindings'),
|
|
37
|
+
},
|
|
38
|
+
},
|
|
39
|
+
};
|
|
40
|
+
const budget = raw['budget'];
|
|
41
|
+
if (isObject(budget)) {
|
|
42
|
+
const maxTokensPerRun = budget['maxTokensPerRun'];
|
|
43
|
+
if (typeof maxTokensPerRun === 'number') {
|
|
44
|
+
config = { ...config, budget: { maxTokensPerRun } };
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
const confidenceGate = raw['confidenceGate'];
|
|
48
|
+
if (isObject(confidenceGate)) {
|
|
49
|
+
const modelEscalationThreshold = confidenceGate['modelEscalationThreshold'];
|
|
50
|
+
const humanEscalationThreshold = confidenceGate['humanEscalationThreshold'];
|
|
51
|
+
const heuristicWeight = confidenceGate['heuristicWeight'];
|
|
52
|
+
const signals = confidenceGate['heuristicSignals'];
|
|
53
|
+
if (typeof modelEscalationThreshold === 'number' &&
|
|
54
|
+
typeof humanEscalationThreshold === 'number' &&
|
|
55
|
+
typeof heuristicWeight === 'number' &&
|
|
56
|
+
isObject(signals)) {
|
|
57
|
+
config = {
|
|
58
|
+
...config,
|
|
59
|
+
confidenceGate: {
|
|
60
|
+
modelEscalationThreshold,
|
|
61
|
+
humanEscalationThreshold,
|
|
62
|
+
heuristicWeight,
|
|
63
|
+
heuristicSignals: {
|
|
64
|
+
penalizeHedgingLanguage: signals['penalizeHedgingLanguage'] === true,
|
|
65
|
+
penalizeHighRetryCount: signals['penalizeHighRetryCount'] === true,
|
|
66
|
+
penalizeUnresolvedFindings: signals['penalizeUnresolvedFindings'] === true,
|
|
67
|
+
},
|
|
68
|
+
},
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
return config;
|
|
73
|
+
}
|
|
74
|
+
/** Derives policy definitions from a parsed governance configuration. */
|
|
75
|
+
export function loadPoliciesFromGovernance(config) {
|
|
76
|
+
const { iterationLimits, qualityGates } = config;
|
|
77
|
+
const policies = [
|
|
78
|
+
{
|
|
79
|
+
id: 'governance:iteration_limit',
|
|
80
|
+
type: 'iteration_limit',
|
|
81
|
+
scope: {},
|
|
82
|
+
config: {
|
|
83
|
+
maxReviewIterations: iterationLimits.defaults.maxReviewIterations,
|
|
84
|
+
maxJudgeArbitrations: iterationLimits.defaults.maxJudgeArbitrations,
|
|
85
|
+
maxClarificationRounds: iterationLimits.defaults.maxClarificationRounds,
|
|
86
|
+
maxAcceptanceIterations: iterationLimits.defaults.maxAcceptanceIterations,
|
|
87
|
+
},
|
|
88
|
+
enabled: true,
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
id: 'governance:quality_gate',
|
|
92
|
+
type: 'quality_gate',
|
|
93
|
+
scope: {},
|
|
94
|
+
config: {
|
|
95
|
+
maxHighSeverityFindings: qualityGates.implementationReview.maxHighSeverityFindings,
|
|
96
|
+
maxMediumSeverityFindings: qualityGates.implementationReview.maxMediumSeverityFindings,
|
|
97
|
+
},
|
|
98
|
+
enabled: true,
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
id: 'governance:specification_readiness',
|
|
102
|
+
type: 'specification_readiness',
|
|
103
|
+
scope: {},
|
|
104
|
+
config: {
|
|
105
|
+
minCompletenessScore: qualityGates.specificationReadiness.minCompletenessScore,
|
|
106
|
+
},
|
|
107
|
+
enabled: true,
|
|
108
|
+
},
|
|
109
|
+
];
|
|
110
|
+
if (config.confidenceGate) {
|
|
111
|
+
policies.push({
|
|
112
|
+
id: 'governance:confidence_gate',
|
|
113
|
+
type: 'confidence_gate',
|
|
114
|
+
scope: {},
|
|
115
|
+
config: config.confidenceGate,
|
|
116
|
+
enabled: true,
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
return policies;
|
|
120
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { loadGovernanceFromYaml, loadPoliciesFromGovernance } from './governance-file-loader';
|
|
2
|
+
export { DefaultPolicyEngine } from './default-policy-engine';
|
|
3
|
+
export { DefaultPolicyRegistry } from './policy-registry';
|
|
4
|
+
export { PolicyResolver } from './policy-resolver';
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { loadGovernanceFromYaml, loadPoliciesFromGovernance } from './governance-file-loader';
|
|
2
|
+
export { DefaultPolicyEngine } from './default-policy-engine';
|
|
3
|
+
export { DefaultPolicyRegistry } from './policy-registry';
|
|
4
|
+
export { PolicyResolver } from './policy-resolver';
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Evaluates iteration count against configured limits. */
|
|
2
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
3
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
4
|
+
export declare class IterationLimitEvaluator implements PolicyEvaluator {
|
|
5
|
+
/** @inheritdoc */
|
|
6
|
+
evaluate(policy: PolicyDefinition, context: PolicyContext): PolicyResult;
|
|
7
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
export class IterationLimitEvaluator {
|
|
2
|
+
/** @inheritdoc */
|
|
3
|
+
evaluate(policy, context) {
|
|
4
|
+
if (policy.type !== 'iteration_limit') {
|
|
5
|
+
throw new Error(`Expected iteration_limit policy, got ${policy.type}`);
|
|
6
|
+
}
|
|
7
|
+
const { config } = policy;
|
|
8
|
+
const iterationCount = context.iterationCount ?? 0;
|
|
9
|
+
const currentState = context.currentState;
|
|
10
|
+
let limit;
|
|
11
|
+
if (currentState === 'WAITING_FOR_HUMAN' || currentState === 'REFINEMENT') {
|
|
12
|
+
limit = config.maxClarificationRounds;
|
|
13
|
+
}
|
|
14
|
+
else {
|
|
15
|
+
limit = config.maxReviewIterations;
|
|
16
|
+
}
|
|
17
|
+
if (iterationCount < limit) {
|
|
18
|
+
return {
|
|
19
|
+
policyId: policy.id,
|
|
20
|
+
policyType: policy.type,
|
|
21
|
+
outcome: 'pass',
|
|
22
|
+
reason: `Iteration ${String(iterationCount)} is within limit of ${String(limit)}`,
|
|
23
|
+
source: { layer: 'builtin' },
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
return {
|
|
27
|
+
policyId: policy.id,
|
|
28
|
+
policyType: policy.type,
|
|
29
|
+
outcome: 'fail',
|
|
30
|
+
reason: `Iteration limit exceeded: ${String(iterationCount)} >= ${String(limit)}`,
|
|
31
|
+
source: { layer: 'builtin' },
|
|
32
|
+
escalationTrigger: 'iteration_limit_exceeded',
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Validates that the model being used matches the configured allowed models list. */
|
|
2
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
3
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
4
|
+
export declare class ModelConstraintEvaluator implements PolicyEvaluator {
|
|
5
|
+
/** @inheritdoc */
|
|
6
|
+
evaluate(policy: PolicyDefinition, context: PolicyContext): PolicyResult;
|
|
7
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
export class ModelConstraintEvaluator {
|
|
2
|
+
/** @inheritdoc */
|
|
3
|
+
evaluate(policy, context) {
|
|
4
|
+
if (policy.type !== 'model_constraint') {
|
|
5
|
+
throw new Error(`Expected model_constraint policy, got ${policy.type}`);
|
|
6
|
+
}
|
|
7
|
+
const { config } = policy;
|
|
8
|
+
const allowedModels = config.allowedModels;
|
|
9
|
+
const model = context.metadata?.model;
|
|
10
|
+
if (allowedModels.length === 0) {
|
|
11
|
+
return {
|
|
12
|
+
policyId: policy.id,
|
|
13
|
+
policyType: policy.type,
|
|
14
|
+
outcome: 'pass',
|
|
15
|
+
reason: 'No model constraints configured',
|
|
16
|
+
source: { layer: 'builtin' },
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
if (model === undefined) {
|
|
20
|
+
return {
|
|
21
|
+
policyId: policy.id,
|
|
22
|
+
policyType: policy.type,
|
|
23
|
+
outcome: 'warn',
|
|
24
|
+
reason: 'No model specified in context; cannot validate constraint',
|
|
25
|
+
source: { layer: 'builtin' },
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
if (allowedModels.includes(model)) {
|
|
29
|
+
return {
|
|
30
|
+
policyId: policy.id,
|
|
31
|
+
policyType: policy.type,
|
|
32
|
+
outcome: 'pass',
|
|
33
|
+
reason: `Model "${model}" is in the allowed models list`,
|
|
34
|
+
source: { layer: 'builtin' },
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
return {
|
|
38
|
+
policyId: policy.id,
|
|
39
|
+
policyType: policy.type,
|
|
40
|
+
outcome: 'fail',
|
|
41
|
+
reason: `Model "${model}" is not in the allowed models list: ${allowedModels.join(', ')}`,
|
|
42
|
+
source: { layer: 'builtin' },
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Checks whether the role has ownership permission for the artifact type in context. */
|
|
2
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
3
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
4
|
+
export declare class OwnershipEvaluator implements PolicyEvaluator {
|
|
5
|
+
/** @inheritdoc */
|
|
6
|
+
evaluate(policy: PolicyDefinition, context: PolicyContext): PolicyResult;
|
|
7
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
export class OwnershipEvaluator {
|
|
2
|
+
/** @inheritdoc */
|
|
3
|
+
evaluate(policy, context) {
|
|
4
|
+
if (policy.type !== 'ownership') {
|
|
5
|
+
throw new Error(`Expected ownership policy, got ${policy.type}`);
|
|
6
|
+
}
|
|
7
|
+
const { config } = policy;
|
|
8
|
+
const role = context.role;
|
|
9
|
+
const strict = config.strict;
|
|
10
|
+
if (!role) {
|
|
11
|
+
if (strict) {
|
|
12
|
+
return {
|
|
13
|
+
policyId: policy.id,
|
|
14
|
+
policyType: policy.type,
|
|
15
|
+
outcome: 'fail',
|
|
16
|
+
reason: 'No role specified in context; strict ownership requires a role',
|
|
17
|
+
source: { layer: 'builtin' },
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
return {
|
|
21
|
+
policyId: policy.id,
|
|
22
|
+
policyType: policy.type,
|
|
23
|
+
outcome: 'pass',
|
|
24
|
+
reason: 'No role specified; ownership check skipped (non-strict mode)',
|
|
25
|
+
source: { layer: 'builtin' },
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
const ownershipMap = config.ownershipMap;
|
|
29
|
+
const ownedTypes = ownershipMap[role] ?? [];
|
|
30
|
+
const artifactTypes = context.artifacts.map((a) => a.type);
|
|
31
|
+
const violations = artifactTypes.filter((t) => !ownedTypes.includes(t));
|
|
32
|
+
if (violations.length === 0) {
|
|
33
|
+
return {
|
|
34
|
+
policyId: policy.id,
|
|
35
|
+
policyType: policy.type,
|
|
36
|
+
outcome: 'pass',
|
|
37
|
+
reason: `Role "${role}" has ownership of all artifact types`,
|
|
38
|
+
source: { layer: 'builtin' },
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
return {
|
|
42
|
+
policyId: policy.id,
|
|
43
|
+
policyType: policy.type,
|
|
44
|
+
outcome: 'fail',
|
|
45
|
+
reason: `Role "${role}" lacks ownership of artifact types: ${violations.join(', ')}`,
|
|
46
|
+
source: { layer: 'builtin' },
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { PolicyEvaluator, PolicyRegistry as PolicyRegistryPort } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
import type { PolicyType, PolicyTypeInfo } from '@ai-dev-orchestrator/schemas';
|
|
3
|
+
/** Registry of policy type evaluators with built-in types pre-registered. */
|
|
4
|
+
export declare class DefaultPolicyRegistry implements PolicyRegistryPort {
|
|
5
|
+
private readonly evaluators;
|
|
6
|
+
private readonly typeInfos;
|
|
7
|
+
constructor();
|
|
8
|
+
/**
|
|
9
|
+
* Register a policy evaluator for a given type.
|
|
10
|
+
* @param type - Policy type identifier
|
|
11
|
+
* @param evaluator - Evaluator that handles this policy type
|
|
12
|
+
*/
|
|
13
|
+
registerType(type: PolicyType, evaluator: PolicyEvaluator): void;
|
|
14
|
+
/**
|
|
15
|
+
* Get the evaluator for a policy type.
|
|
16
|
+
* @param type - Policy type to look up
|
|
17
|
+
* @returns The registered evaluator
|
|
18
|
+
* @throws UnknownPolicyTypeError if no evaluator is registered for the type
|
|
19
|
+
*/
|
|
20
|
+
getEvaluator(type: PolicyType): PolicyEvaluator;
|
|
21
|
+
/** @inheritdoc */
|
|
22
|
+
listTypes(): readonly PolicyTypeInfo[];
|
|
23
|
+
}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { UnknownPolicyTypeError } from '../domain/errors';
|
|
2
|
+
import { ConfidenceEvaluator } from './confidence-evaluator';
|
|
3
|
+
import { CustomEvaluator } from './custom-evaluator';
|
|
4
|
+
import { IterationLimitEvaluator } from './iteration-limit-evaluator';
|
|
5
|
+
import { ModelConstraintEvaluator } from './model-constraint-evaluator';
|
|
6
|
+
import { OwnershipEvaluator } from './ownership-evaluator';
|
|
7
|
+
import { QualityGateEvaluator } from './quality-gate-evaluator';
|
|
8
|
+
import { RetryLimitEvaluator } from './retry-limit-evaluator';
|
|
9
|
+
import { SpecificationReadinessEvaluator } from './specification-readiness-evaluator';
|
|
10
|
+
import { StageSkipEvaluator } from './stage-skip-evaluator';
|
|
11
|
+
import { TokenBudgetEvaluator } from './token-budget-evaluator';
|
|
12
|
+
const BUILT_IN_EVALUATORS = [
|
|
13
|
+
{
|
|
14
|
+
type: 'iteration_limit',
|
|
15
|
+
evaluator: new IterationLimitEvaluator(),
|
|
16
|
+
description: 'Limits the number of iterations in produce-review loops',
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
type: 'quality_gate',
|
|
20
|
+
evaluator: new QualityGateEvaluator(),
|
|
21
|
+
description: 'Evaluates artifacts against quality thresholds',
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
type: 'specification_readiness',
|
|
25
|
+
evaluator: new SpecificationReadinessEvaluator(),
|
|
26
|
+
description: 'Evaluates whether canonical specification meets readiness criteria',
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
type: 'stage_skip',
|
|
30
|
+
evaluator: new StageSkipEvaluator(),
|
|
31
|
+
description: 'Checks if a stage should be skipped based on configured criteria',
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
type: 'retry_limit',
|
|
35
|
+
evaluator: new RetryLimitEvaluator(),
|
|
36
|
+
description: 'Checks if retry count exceeds configured maximum',
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
type: 'token_budget',
|
|
40
|
+
evaluator: new TokenBudgetEvaluator(),
|
|
41
|
+
description: 'Checks if token usage exceeds configured budget',
|
|
42
|
+
},
|
|
43
|
+
{
|
|
44
|
+
type: 'model_constraint',
|
|
45
|
+
evaluator: new ModelConstraintEvaluator(),
|
|
46
|
+
description: 'Validates that the model matches configured allowed models list',
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
type: 'ownership',
|
|
50
|
+
evaluator: new OwnershipEvaluator(),
|
|
51
|
+
description: 'Checks if the role has ownership permission for artifact types',
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
type: 'confidence_gate',
|
|
55
|
+
evaluator: new ConfidenceEvaluator(),
|
|
56
|
+
description: 'Evaluates agent confidence and triggers model or human escalation',
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
type: 'custom',
|
|
60
|
+
evaluator: new CustomEvaluator(),
|
|
61
|
+
description: 'Pass-through evaluator for custom extensibility',
|
|
62
|
+
},
|
|
63
|
+
];
|
|
64
|
+
/** Registry of policy type evaluators with built-in types pre-registered. */
|
|
65
|
+
export class DefaultPolicyRegistry {
|
|
66
|
+
evaluators = new Map();
|
|
67
|
+
typeInfos = new Map();
|
|
68
|
+
constructor() {
|
|
69
|
+
for (const entry of BUILT_IN_EVALUATORS) {
|
|
70
|
+
this.evaluators.set(entry.type, entry.evaluator);
|
|
71
|
+
this.typeInfos.set(entry.type, {
|
|
72
|
+
type: entry.type,
|
|
73
|
+
description: entry.description,
|
|
74
|
+
configSchema: {},
|
|
75
|
+
builtIn: true,
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Register a policy evaluator for a given type.
|
|
81
|
+
* @param type - Policy type identifier
|
|
82
|
+
* @param evaluator - Evaluator that handles this policy type
|
|
83
|
+
*/
|
|
84
|
+
registerType(type, evaluator) {
|
|
85
|
+
this.evaluators.set(type, evaluator);
|
|
86
|
+
if (!this.typeInfos.has(type)) {
|
|
87
|
+
this.typeInfos.set(type, {
|
|
88
|
+
type,
|
|
89
|
+
description: `Custom policy type: ${type}`,
|
|
90
|
+
configSchema: {},
|
|
91
|
+
builtIn: false,
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Get the evaluator for a policy type.
|
|
97
|
+
* @param type - Policy type to look up
|
|
98
|
+
* @returns The registered evaluator
|
|
99
|
+
* @throws UnknownPolicyTypeError if no evaluator is registered for the type
|
|
100
|
+
*/
|
|
101
|
+
getEvaluator(type) {
|
|
102
|
+
const evaluator = this.evaluators.get(type);
|
|
103
|
+
if (!evaluator) {
|
|
104
|
+
throw new UnknownPolicyTypeError(type);
|
|
105
|
+
}
|
|
106
|
+
return evaluator;
|
|
107
|
+
}
|
|
108
|
+
/** @inheritdoc */
|
|
109
|
+
listTypes() {
|
|
110
|
+
return [...this.typeInfos.values()];
|
|
111
|
+
}
|
|
112
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { PolicyResolver as PolicyResolverPort } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
import type { PolicyDefinition, PolicyScope, PolicySource, ResolvedPolicySet } from '@ai-dev-orchestrator/schemas';
|
|
3
|
+
interface PolicyHierarchy {
|
|
4
|
+
readonly organization?: readonly PolicyDefinition[];
|
|
5
|
+
readonly project?: readonly PolicyDefinition[];
|
|
6
|
+
readonly workflowVariant?: readonly PolicyDefinition[];
|
|
7
|
+
readonly overrides?: readonly PolicyDefinition[];
|
|
8
|
+
}
|
|
9
|
+
/** Resolves applicable policies by merging all hierarchy layers. */
|
|
10
|
+
export declare class PolicyResolver implements PolicyResolverPort {
|
|
11
|
+
private readonly hierarchy;
|
|
12
|
+
private mergeLog;
|
|
13
|
+
private lastSources;
|
|
14
|
+
constructor(projectOrHierarchy?: readonly PolicyDefinition[] | PolicyHierarchy);
|
|
15
|
+
/**
|
|
16
|
+
* Resolve applicable policies by merging built-in defaults with all hierarchy layers.
|
|
17
|
+
* @param _scope - Scope filter (reserved for future per-role/per-state filtering)
|
|
18
|
+
* @returns Merged policy set with sources and merge audit log
|
|
19
|
+
*/
|
|
20
|
+
resolve(_scope: PolicyScope): ResolvedPolicySet;
|
|
21
|
+
/**
|
|
22
|
+
* Trace which hierarchy layer provided a specific policy.
|
|
23
|
+
* @param policyId - The policy identifier to trace
|
|
24
|
+
* @param _field - Config field name (reserved for field-level tracing)
|
|
25
|
+
* @returns The source layer, or null if the policy was not resolved
|
|
26
|
+
*/
|
|
27
|
+
traceSource(policyId: string, _field: string): PolicySource | null;
|
|
28
|
+
}
|
|
29
|
+
export {};
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/** Resolves applicable policies by merging all hierarchy layers. */
|
|
2
|
+
export class PolicyResolver {
|
|
3
|
+
hierarchy;
|
|
4
|
+
mergeLog = [];
|
|
5
|
+
lastSources = new Map();
|
|
6
|
+
constructor(projectOrHierarchy) {
|
|
7
|
+
if (!projectOrHierarchy) {
|
|
8
|
+
this.hierarchy = {};
|
|
9
|
+
}
|
|
10
|
+
else if (Array.isArray(projectOrHierarchy)) {
|
|
11
|
+
this.hierarchy = { project: projectOrHierarchy };
|
|
12
|
+
}
|
|
13
|
+
else {
|
|
14
|
+
this.hierarchy = projectOrHierarchy;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Resolve applicable policies by merging built-in defaults with all hierarchy layers.
|
|
19
|
+
* @param _scope - Scope filter (reserved for future per-role/per-state filtering)
|
|
20
|
+
* @returns Merged policy set with sources and merge audit log
|
|
21
|
+
*/
|
|
22
|
+
resolve(_scope) {
|
|
23
|
+
this.mergeLog = [];
|
|
24
|
+
const sources = new Map();
|
|
25
|
+
const merged = new Map();
|
|
26
|
+
const layers = [
|
|
27
|
+
{ name: 'organization', policies: this.hierarchy.organization ?? [] },
|
|
28
|
+
{ name: 'project', policies: this.hierarchy.project ?? [] },
|
|
29
|
+
{ name: 'workflow_variant', policies: this.hierarchy.workflowVariant ?? [] },
|
|
30
|
+
{ name: 'role', policies: this.hierarchy.overrides ?? [] },
|
|
31
|
+
];
|
|
32
|
+
for (const layer of layers) {
|
|
33
|
+
for (const layerPolicy of layer.policies) {
|
|
34
|
+
const existing = merged.get(layerPolicy.type);
|
|
35
|
+
if (existing) {
|
|
36
|
+
const existingConfig = existing.config;
|
|
37
|
+
const layerConfig = layerPolicy.config;
|
|
38
|
+
if (existing.locked) {
|
|
39
|
+
const previousSource = sources.get(existing.id);
|
|
40
|
+
const fromLayer = previousSource?.layer ?? 'builtin';
|
|
41
|
+
for (const key of Object.keys(layerConfig)) {
|
|
42
|
+
this.mergeLog.push({
|
|
43
|
+
policyId: existing.id,
|
|
44
|
+
field: key,
|
|
45
|
+
fromLayer,
|
|
46
|
+
toLayer: layer.name,
|
|
47
|
+
action: 'blocked_by_lock',
|
|
48
|
+
fromValue: existingConfig[key],
|
|
49
|
+
toValue: layerConfig[key],
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
continue;
|
|
53
|
+
}
|
|
54
|
+
const previousSource = sources.get(existing.id);
|
|
55
|
+
const fromLayer = previousSource?.layer ?? 'builtin';
|
|
56
|
+
const mergedConfig = { ...existingConfig, ...layerConfig };
|
|
57
|
+
const mergedPolicy = {
|
|
58
|
+
...existing,
|
|
59
|
+
config: mergedConfig,
|
|
60
|
+
enabled: layerPolicy.enabled,
|
|
61
|
+
};
|
|
62
|
+
merged.set(layerPolicy.type, mergedPolicy);
|
|
63
|
+
for (const key of Object.keys(layerConfig)) {
|
|
64
|
+
this.mergeLog.push({
|
|
65
|
+
policyId: existing.id,
|
|
66
|
+
field: key,
|
|
67
|
+
fromLayer,
|
|
68
|
+
toLayer: layer.name,
|
|
69
|
+
action: 'override',
|
|
70
|
+
fromValue: existingConfig[key],
|
|
71
|
+
toValue: layerConfig[key],
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
sources.set(existing.id, { layer: layer.name });
|
|
75
|
+
}
|
|
76
|
+
else {
|
|
77
|
+
merged.set(layerPolicy.type, layerPolicy);
|
|
78
|
+
sources.set(layerPolicy.id, { layer: layer.name });
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
const policies = [...merged.values()].filter((p) => p.enabled);
|
|
83
|
+
this.lastSources = sources;
|
|
84
|
+
return {
|
|
85
|
+
policies,
|
|
86
|
+
sources,
|
|
87
|
+
mergeLog: [...this.mergeLog],
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Trace which hierarchy layer provided a specific policy.
|
|
92
|
+
* @param policyId - The policy identifier to trace
|
|
93
|
+
* @param _field - Config field name (reserved for field-level tracing)
|
|
94
|
+
* @returns The source layer, or null if the policy was not resolved
|
|
95
|
+
*/
|
|
96
|
+
traceSource(policyId, _field) {
|
|
97
|
+
return this.lastSources.get(policyId) ?? null;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
2
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
3
|
+
/** Evaluates artifacts against quality gate thresholds. */
|
|
4
|
+
export declare class QualityGateEvaluator implements PolicyEvaluator {
|
|
5
|
+
/** @inheritdoc */
|
|
6
|
+
evaluate(policy: PolicyDefinition, context: PolicyContext): PolicyResult;
|
|
7
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
const POST_CODE_REVIEW_STATES = new Set([
|
|
2
|
+
'CODE_REVIEW',
|
|
3
|
+
'JUDGE_REVIEW',
|
|
4
|
+
'VERIFICATION',
|
|
5
|
+
]);
|
|
6
|
+
const REVIEW_GATE_CHECKS = [
|
|
7
|
+
{ configKey: 'requireDesignReview', artifactType: 'design_review', label: 'Design' },
|
|
8
|
+
{
|
|
9
|
+
configKey: 'requireAdversarialReview',
|
|
10
|
+
artifactType: 'adversarial_review',
|
|
11
|
+
label: 'Adversarial',
|
|
12
|
+
},
|
|
13
|
+
];
|
|
14
|
+
/** Evaluates artifacts against quality gate thresholds. */
|
|
15
|
+
export class QualityGateEvaluator {
|
|
16
|
+
/** @inheritdoc */
|
|
17
|
+
evaluate(policy, context) {
|
|
18
|
+
if (policy.type !== 'quality_gate') {
|
|
19
|
+
throw new Error(`Expected quality_gate policy, got ${policy.type}`);
|
|
20
|
+
}
|
|
21
|
+
const { config } = policy;
|
|
22
|
+
const findings = context.findings ?? [];
|
|
23
|
+
const failures = [];
|
|
24
|
+
const maxHigh = config.maxHighSeverityFindings;
|
|
25
|
+
const maxMedium = config.maxMediumSeverityFindings;
|
|
26
|
+
const highCount = findings.filter((f) => f.severity === 'high' && f.status === 'open').length;
|
|
27
|
+
if (highCount > maxHigh) {
|
|
28
|
+
failures.push(`${String(highCount)} high-severity findings exceed limit of ${String(maxHigh)}`);
|
|
29
|
+
}
|
|
30
|
+
const mediumCount = findings.filter((f) => f.severity === 'medium' && f.status === 'open').length;
|
|
31
|
+
if (mediumCount > maxMedium) {
|
|
32
|
+
failures.push(`${String(mediumCount)} medium-severity findings exceed limit of ${String(maxMedium)}`);
|
|
33
|
+
}
|
|
34
|
+
const reviewArtifactsApplicable = POST_CODE_REVIEW_STATES.has(context.currentState);
|
|
35
|
+
if (reviewArtifactsApplicable) {
|
|
36
|
+
const artifactTypes = new Set(context.artifacts.map((a) => a.type));
|
|
37
|
+
for (const gate of REVIEW_GATE_CHECKS) {
|
|
38
|
+
if (config[gate.configKey] &&
|
|
39
|
+
!artifactTypes.has(gate.artifactType)) {
|
|
40
|
+
failures.push(`${gate.label} review artifact required but not found`);
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
if (failures.length > 0) {
|
|
45
|
+
return {
|
|
46
|
+
policyId: policy.id,
|
|
47
|
+
policyType: policy.type,
|
|
48
|
+
outcome: 'fail',
|
|
49
|
+
reason: failures.join('; '),
|
|
50
|
+
source: { layer: 'builtin' },
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
return {
|
|
54
|
+
policyId: policy.id,
|
|
55
|
+
policyType: policy.type,
|
|
56
|
+
outcome: 'pass',
|
|
57
|
+
reason: 'All quality gates passed',
|
|
58
|
+
source: { layer: 'builtin' },
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Evaluates whether the retry count exceeds the configured maximum. */
|
|
2
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
3
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
4
|
+
export declare class RetryLimitEvaluator implements PolicyEvaluator {
|
|
5
|
+
/** @inheritdoc */
|
|
6
|
+
evaluate(policy: PolicyDefinition, context: PolicyContext): PolicyResult;
|
|
7
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
export class RetryLimitEvaluator {
|
|
2
|
+
/** @inheritdoc */
|
|
3
|
+
evaluate(policy, context) {
|
|
4
|
+
if (policy.type !== 'retry_limit') {
|
|
5
|
+
throw new Error(`Expected retry_limit policy, got ${policy.type}`);
|
|
6
|
+
}
|
|
7
|
+
const { config } = policy;
|
|
8
|
+
const retryCount = context.metadata?.retryCount ?? 0;
|
|
9
|
+
const maxRetries = config.maxRetries;
|
|
10
|
+
if (retryCount < maxRetries) {
|
|
11
|
+
return {
|
|
12
|
+
policyId: policy.id,
|
|
13
|
+
policyType: policy.type,
|
|
14
|
+
outcome: 'pass',
|
|
15
|
+
reason: `Retry ${String(retryCount)} is within limit of ${String(maxRetries)}`,
|
|
16
|
+
source: { layer: 'builtin' },
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
return {
|
|
20
|
+
policyId: policy.id,
|
|
21
|
+
policyType: policy.type,
|
|
22
|
+
outcome: 'fail',
|
|
23
|
+
reason: `Retry limit exceeded: ${String(retryCount)} >= ${String(maxRetries)}`,
|
|
24
|
+
source: { layer: 'builtin' },
|
|
25
|
+
escalationTrigger: 'retry_limit_exceeded',
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Evaluates whether the canonical specification meets readiness criteria before proceeding. */
|
|
2
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
3
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
4
|
+
export declare class SpecificationReadinessEvaluator implements PolicyEvaluator {
|
|
5
|
+
/** @inheritdoc */
|
|
6
|
+
evaluate(policy: PolicyDefinition, context: PolicyContext): PolicyResult;
|
|
7
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
export class SpecificationReadinessEvaluator {
|
|
2
|
+
/** @inheritdoc */
|
|
3
|
+
evaluate(policy, context) {
|
|
4
|
+
if (policy.type !== 'specification_readiness') {
|
|
5
|
+
throw new Error(`Expected specification_readiness policy, got ${policy.type}`);
|
|
6
|
+
}
|
|
7
|
+
const { config } = policy;
|
|
8
|
+
const failures = [];
|
|
9
|
+
const hasSpec = context.artifacts.some((a) => a.type === 'canonical_specification');
|
|
10
|
+
if (!hasSpec) {
|
|
11
|
+
failures.push('Canonical specification artifact is required but not found');
|
|
12
|
+
}
|
|
13
|
+
const completeness = context.metadata?.completenessScore;
|
|
14
|
+
if (completeness !== undefined && completeness < config.minCompletenessScore) {
|
|
15
|
+
failures.push(`Completeness score ${String(completeness)} is below minimum ${String(config.minCompletenessScore)}`);
|
|
16
|
+
}
|
|
17
|
+
const ambiguities = context.metadata?.ambiguityCount ?? 0;
|
|
18
|
+
if (ambiguities > 0) {
|
|
19
|
+
failures.push(`${String(ambiguities)} ambiguities found; none are allowed`);
|
|
20
|
+
}
|
|
21
|
+
if (failures.length > 0) {
|
|
22
|
+
return {
|
|
23
|
+
policyId: policy.id,
|
|
24
|
+
policyType: policy.type,
|
|
25
|
+
outcome: 'fail',
|
|
26
|
+
reason: failures.join('; '),
|
|
27
|
+
source: { layer: 'builtin' },
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
return {
|
|
31
|
+
policyId: policy.id,
|
|
32
|
+
policyType: policy.type,
|
|
33
|
+
outcome: 'pass',
|
|
34
|
+
reason: 'Specification meets readiness criteria',
|
|
35
|
+
source: { layer: 'builtin' },
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** Evaluates whether a stage should be skipped based on configured criteria. */
|
|
2
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
3
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
4
|
+
export declare class StageSkipEvaluator implements PolicyEvaluator {
|
|
5
|
+
/** @inheritdoc */
|
|
6
|
+
evaluate(policy: PolicyDefinition, context: PolicyContext): PolicyResult;
|
|
7
|
+
private matchesCondition;
|
|
8
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
export class StageSkipEvaluator {
|
|
2
|
+
/** @inheritdoc */
|
|
3
|
+
evaluate(policy, context) {
|
|
4
|
+
if (policy.type !== 'stage_skip') {
|
|
5
|
+
throw new Error(`Expected stage_skip policy, got ${policy.type}`);
|
|
6
|
+
}
|
|
7
|
+
const { config } = policy;
|
|
8
|
+
const conditions = config.skipWhen;
|
|
9
|
+
for (const condition of conditions) {
|
|
10
|
+
if (this.matchesCondition(condition, context)) {
|
|
11
|
+
return {
|
|
12
|
+
policyId: policy.id,
|
|
13
|
+
policyType: policy.type,
|
|
14
|
+
outcome: 'skip',
|
|
15
|
+
reason: `Stage "${context.currentState}" skipped: ${condition.reason ?? 'condition matched'}`,
|
|
16
|
+
source: { layer: 'builtin' },
|
|
17
|
+
detail: `skip_condition:${condition.field}`,
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
return {
|
|
22
|
+
policyId: policy.id,
|
|
23
|
+
policyType: policy.type,
|
|
24
|
+
outcome: 'pass',
|
|
25
|
+
reason: `No skip conditions matched for stage "${context.currentState}"`,
|
|
26
|
+
source: { layer: 'builtin' },
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
matchesCondition(condition, context) {
|
|
30
|
+
if (condition.field === 'state' && condition.equals !== undefined) {
|
|
31
|
+
return context.currentState === condition.equals;
|
|
32
|
+
}
|
|
33
|
+
if (condition.field === 'role' && condition.equals !== undefined) {
|
|
34
|
+
return context.role === condition.equals;
|
|
35
|
+
}
|
|
36
|
+
if (condition.field === 'workflowVariant' && condition.equals !== undefined) {
|
|
37
|
+
return context.workflowVariant === condition.equals;
|
|
38
|
+
}
|
|
39
|
+
if (condition.field === 'metadata' && condition.key !== undefined) {
|
|
40
|
+
const value = context.metadata?.[condition.key];
|
|
41
|
+
return value === condition.equals;
|
|
42
|
+
}
|
|
43
|
+
return false;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Evaluates whether token usage exceeds the configured budget. */
|
|
2
|
+
import type { PolicyEvaluator } from '@ai-dev-orchestrator/ports';
|
|
3
|
+
import type { PolicyContext, PolicyDefinition, PolicyResult } from '@ai-dev-orchestrator/schemas';
|
|
4
|
+
export declare class TokenBudgetEvaluator implements PolicyEvaluator {
|
|
5
|
+
/** @inheritdoc */
|
|
6
|
+
evaluate(policy: PolicyDefinition, context: PolicyContext): PolicyResult;
|
|
7
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
export class TokenBudgetEvaluator {
|
|
2
|
+
/** @inheritdoc */
|
|
3
|
+
evaluate(policy, context) {
|
|
4
|
+
if (policy.type !== 'token_budget') {
|
|
5
|
+
throw new Error(`Expected token_budget policy, got ${policy.type}`);
|
|
6
|
+
}
|
|
7
|
+
const { config } = policy;
|
|
8
|
+
const tokensUsed = context.tokenUsage?.totalTokens ?? 0;
|
|
9
|
+
const maxTokens = config.maxTokens;
|
|
10
|
+
if (tokensUsed <= maxTokens) {
|
|
11
|
+
return {
|
|
12
|
+
policyId: policy.id,
|
|
13
|
+
policyType: policy.type,
|
|
14
|
+
outcome: 'pass',
|
|
15
|
+
reason: `Token usage ${String(tokensUsed)} is within budget of ${String(maxTokens)}`,
|
|
16
|
+
source: { layer: 'builtin' },
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
return {
|
|
20
|
+
policyId: policy.id,
|
|
21
|
+
policyType: policy.type,
|
|
22
|
+
outcome: 'fail',
|
|
23
|
+
reason: `Token budget exceeded: ${String(tokensUsed)} > ${String(maxTokens)}`,
|
|
24
|
+
source: { layer: 'builtin' },
|
|
25
|
+
escalationTrigger: 'token_budget_exceeded',
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@ai-dev-orchestrator/policy-engine",
|
|
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/policy-engine"
|
|
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
|
+
"yaml": "^2.9.0",
|
|
25
|
+
"@ai-dev-orchestrator/ports": "0.1.1",
|
|
26
|
+
"@ai-dev-orchestrator/schemas": "0.1.1",
|
|
27
|
+
"@ai-dev-orchestrator/utils": "0.1.1"
|
|
28
|
+
},
|
|
29
|
+
"devDependencies": {
|
|
30
|
+
"@types/node": "^26.4.0",
|
|
31
|
+
"fast-check": "^4.9.0",
|
|
32
|
+
"vitest": "^4.1.11",
|
|
33
|
+
"@ai-dev-orchestrator/build-config": "0.1.1",
|
|
34
|
+
"@ai-dev-orchestrator/test-utils": "0.1.1"
|
|
35
|
+
},
|
|
36
|
+
"scripts": {
|
|
37
|
+
"clean": "rimraf dist tsconfig.build.tsbuildinfo",
|
|
38
|
+
"build:base": "rimraf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
|
|
39
|
+
"build:dev": "pnpm run build:base",
|
|
40
|
+
"build:prod": "pnpm run clean && tsc -p tsconfig.build.json --sourceMap false --declarationMap false",
|
|
41
|
+
"lint": "eslint src/ test/",
|
|
42
|
+
"test:unit": "vitest run",
|
|
43
|
+
"typecheck": "tsc -p tsconfig.build.json --noEmit"
|
|
44
|
+
}
|
|
45
|
+
}
|