ai-sdlc-policy: Explainable Delivery Controls

Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. Unknown or invalid policy inputs fail closed when they could weaken protection.

0. Skill Card

• Skill name:

  ai-sdlc-policy

• Primary audience: Delivery, Security, Architecture, Release
• Supporting audience: Dev, QA, PM, BA
• Audience tags: Delivery, Security, Architecture, Release, Dev
• SDLC stage: Governance and control evaluation
• Purpose: Resolve policy layers with provenance and evaluate actions against protected, versioned, waiver-aware rules.
• Output:

  _ai_sdlc/policy-resolution.{toon,json}

  or fingerprint-addressed TOON/JSON records below

  _ai_sdlc/policy-decisions/

  when

  --write

  is requested

0.1 Required Inputs

• Action name and JSON context for evaluation.
• Base policy plus optional organization profile, project, and user layers.
• Explicit owner-approved waiver record when an allowed exception is requested.

0.2 Clarification Rules

• Ask when action identity, subject, accountable waiver owner, or decision reference is missing.
• Reject unknown fields, operators, layer scopes, and ambiguous rule identity.
• Never infer approval or create a waiver on the requester's behalf.

0.2.1 Flow Mode Flags

• Support

  --quick-flow

  and

  --full-flow

  ; full flow takes precedence.
• Both modes use the same fail-closed evaluator and protected-rule semantics.
• Full flow requires explicit review of every matched rule, rejected override, required gate, and waiver result.

0.3 Output Rules

• Report resolved policy fingerprint, layer provenance, action decision, matched rules, required gates, reason codes, and applied or rejected waivers.
• Return validation and handoff summaries directly in the Codex response.
• Emit

  ai-sdlc-handoff/v1

  with

  result

  ,

  blockers

  ,

  next_required

  , and

  next_optional

  ; actions include

  reason

  ,

  command

  , and

  expected_artifact

  .
• Do not create

  summary.txt

  ,

  *-summary.txt

  , or another standalone summary file.

0.4 Artifact Routing

• Keep approved policy layers in visible repository-owned paths.
• Write generated resolution and decision records only below

  _ai_sdlc/

  .
• Never overwrite a source policy or waiver during evaluation.

0.5 Feature State Machine

• Read canonical

  _ai_sdlc/state.toon

  before applying a decision to feature work. Policy evaluation does not create or advance feature

  state.toon

  .
• A deny or unsatisfied required gate blocks the owning workflow transition.

0.6 Artifact Metadata And Metatags

• Policy-related Markdown uses canonical

  artifact_metadata

  and

  metatags

  .
• Machine records use

  ai-sdlc-policy-layer/v1

  ,

  ai-sdlc-policy-waiver/v1

  ,

  ai-sdlc-policy-resolution/v1

  , and

  ai-sdlc-policy-decision/v1

  .

0.7 Specs Index

• Read

  _ai_sdlc/specs-index.toon

  first and use

  specs-index.md

  for human discovery when evaluation context refers to feature artifacts.
• Policy evaluation does not refresh either specs index.

References

• Read

  references/policy-contract.md

  before resolving or evaluating policy.
• Validate source layers with

  references/policy-layer.schema.json

  , waivers with

  references/policy-waiver.schema.json

  , and decisions with

  references/policy-decision.schema.json

  .
• Reuse organization profiles from

  references/profiles/

  .
• Use

  scripts/policy.py

  for resolution, evaluation, and explain output.

Script Usage

python3 skills/ai-sdlc-policy/scripts/policy.py . --resolve --profile high-assurance --format toon
python3 skills/ai-sdlc-policy/scripts/policy.py . --evaluate change.apply --context policy-context.json --profile regulated --format toon
python3 skills/ai-sdlc-policy/scripts/policy.py . --explain release.publish --context release-context.json --waiver waiver.json --format markdown

Purpose

Inputs

• Versioned base, organization, project, and user policy layers.
• A stable action such as

  change.apply

  ,

  release.publish

  , or

  command.destructive

  and a JSON context object.
• Optional waiver files tied to exact rule IDs, actions, subjects, constraints, owners, approvers, decisions, issue times, and expiry times.

Steps

1. Load the built-in base and optional organization assurance profile.
2. Validate custom layers and merge them in base, organization, project, user order.
3. Reject any lower-layer change that weakens a protected effect, gate set, protected flag, or non-waivable boundary.
4. Match rules using only declared fields and deterministic operators.
5. Validate waivers against rule eligibility, action, subject, constraints, decision evidence, and the explicit evaluation time.
6. Combine unwaived rules with deny-first, require-second, allow-third precedence.
7. Inspect explain output and satisfy every required gate before acting.

Output Spec

• Pass when all layers are valid, protected rules remain at least as strict, each waiver is current and authorized, and the action result plus gates are understood.
• Fail closed on invalid policy, unknown action, protected weakening, malformed or expired waiver, and missing context required by a predicate.

Examples

security-review

fresh-evidence

change.apply

require

allow

Edge Cases

• Non-matching rules remain visible in explain output only when requested.
• Multiple matching deny rules remain deny even if another rule allows.
• A valid waiver suppresses only its named waivable rule, never an entire action.
• Expiry is evaluated at explicit

  --as-of

  time for reproducible decisions.

Scope Boundary

• Do not edit source policy, issue waivers, record approvals, or satisfy gates.
• Do not treat

  allow

  as authorization outside the evaluated action and context.
• Do not let user or project layers weaken protected organization minimums.
• Do not execute the evaluated action; return the decision to its owning workflow.