ai-sdlc-change-set: Isolated Change Workspace

Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. A change workspace proposes intent; it never becomes canonical truth by itself.

0. Skill Card

• Skill name:

  ai-sdlc-change-set

• Primary audience: Delivery, Dev, BA
• Supporting audience: PM, QA, Architecture, Security
• Audience tags: Delivery, Dev, BA, PM, QA
• SDLC stage: Controlled change intake
• Purpose: Create and validate an isolated, reviewable workspace before any authoritative specification mutation.
• Output:

  changes/<change-id>/

  with proposal, design, tasks, delta and evidence indexes, lifecycle records, preview, approval, and recovery evidence

0.1 Required Inputs

• Repository root and a lowercase hyphenated change ID.
• Change title, summary, owner, and one or more repository-relative canonical target paths.
• Quick or full flow selection when organization policy requires it.

0.2 Clarification Rules

• Ask when the owner, target authority, or intended outcome is ambiguous.
• Reject absolute paths, parent traversal, targets inside

  changes/

  , and duplicate targets instead of normalizing them silently.
• Treat generated workspace content as a proposal until a later controlled apply workflow proves approval and conflict freedom.

0.2.1 Flow Mode Flags

• Support

  --quick-flow

  and

  --full-flow

  ; full flow takes precedence.
• Quick flow may create a draft from confirmed repository context and visible assumptions.
• Full flow requires explicit owner, summary, and canonical targets.
• Neither flow reads, writes, renames, or deletes canonical targets.

0.3 Output Rules

• Report the change ID, workspace path, status, owner, targets, fingerprint, validation result, and next required action.
• Before the final response, emit an

  ai-sdlc-handoff/v1

  result that routes a structurally valid workspace to delta authoring and validation. Include

  next_required

  and

  next_optional

  actions with reasons, commands, and expected artifacts.
• Return progress, validation, and handoff summaries directly in the Codex response.
• Do not create

  summary.txt

  ,

  *-summary.txt

  , or another standalone summary file.
• Do not create ad hoc summaries outside the canonical workspace files.

0.4 Artifact Routing

• Route every change to

  <repository>/changes/<change-id>/

  .
• Keep human intent in

  proposal.md

  ,

  design.md

  ,

  tasks.md

  ,

  deltas/index.md

  , and

  evidence/index.md

  .
• Keep complete agent-facing TOON beside interoperable JSON for the change set, delta set, apply preview, approval, and recovery records.
• Never store a change workspace inside

  specs/

  ,

  specs-refiniment/

  , or a canonical target directory.

0.5 Feature State Machine

• Change status begins as

  draft

  in the change-set record.
• T002 creates only the intake state; later delta, preview, apply, and archive tasks own their state transitions.
• Read the owning feature

  _ai_sdlc/state.toon

  when targets belong to an existing feature, but do not modify feature

  state.toon

  during intake.

0.6 Artifact Metadata And Metatags

• Generated Markdown starts with

  artifact_metadata

  frontmatter using

  ai-sdlc-change-set-metadata/v1

  .
• Include change ID, artifact, status, owner, created and updated dates, canonical targets, and

  metatags

  for

  ai-sdlc

  ,

  change-set

  ,

  proposal

  , and

  draft

  .
• The JSON record uses schema

  ai-sdlc-change-set/v1

  and a deterministic contract fingerprint.

0.7 Specs Index

• Read

  _ai_sdlc/specs-index.toon

  first and use

  specs-index.md

  for human feature discovery when canonical targets belong to existing specs.
• A draft change workspace is not a feature spec and does not refresh either specs index.
• The later apply workflow refreshes indexes only after an approved canonical artifact change.

References

• Read

  references/change-set-contract.md

  before creating or reviewing a workspace.
• Use

  references/change-set.schema.json

  for the versioned machine contract.
• Use

  scripts/change_set.py

  for deterministic emit, create, and validation.
• Read

  references/spec-delta-contract.md

  before authoring or reviewing delta Markdown and use

  references/spec-delta.schema.json

  for its projection.
• Use

  scripts/spec_delta.py

  to validate and project semantic deltas.
• Read

  references/apply-preview-contract.md

  before reviewing planned target changes and use

  references/change-preview.schema.json

  for the projection.
• Use

  scripts/change_preview.py

  to compile diffs, conflicts, stale evidence, reopen actions, and required gates without target writes.
• Read

  references/controlled-apply-contract.md

  before applying or archiving.
• Validate approval with

  references/change-approval.schema.json

  and recovery evidence with

  references/change-recovery.schema.json

  .
• Use

  scripts/change_apply.py

  only after a ready preview and explicit approval.

Script Usage

python3 skills/ai-sdlc-change-set/scripts/change_set.py . --change-id add-session-timeout --title "Add session timeout" --summary "Expire inactive sessions." --owner Security --target specs/auth/requirements.md --emit --quick-flow
python3 skills/ai-sdlc-change-set/scripts/change_set.py . --change-id add-session-timeout --title "Add session timeout" --summary "Expire inactive sessions." --owner Security --target specs/auth/requirements.md --create --full-flow
python3 skills/ai-sdlc-change-set/scripts/change_set.py . --change-id add-session-timeout --validate --format toon
python3 skills/ai-sdlc-change-set/scripts/spec_delta.py . --change-id add-session-timeout --validate --write --format toon
python3 skills/ai-sdlc-change-set/scripts/change_preview.py . --change-id add-session-timeout --preview --write --format toon
python3 skills/ai-sdlc-change-set/scripts/change_apply.py . --change-id add-session-timeout --apply --approval changes/add-session-timeout/evidence/owner-approval.json --format toon
python3 skills/ai-sdlc-change-set/scripts/change_apply.py . --change-id add-session-timeout --archive --format toon

--emit

--create

--validate

Purpose

Inputs

• Use a stable change ID that describes one bounded outcome.
• Use repository-relative POSIX paths for canonical targets.
• Use an accountable role or person as owner.
• Keep summary factual and state uncertainty in the proposal after creation.

Steps

1. Inspect canonical sources read-only and identify their authority owners.
2. Run

   --emit

   to review the planned workspace and fingerprint.
3. Resolve unsafe IDs, paths, duplicate targets, or missing ownership.
4. Run

   --create

   ; confirm canonical target bytes did not change.
5. Edit proposal sections through normal reviewed repository changes.
6. Run

   --validate

   before authoring semantic deltas.
7. Author delta Markdown with stable requirement IDs and operation-specific evidence, then run

   spec_delta.py --validate

   .
8. Compile preview and resolve every conflict, stale reference, reopen action, and required gate.
9. Obtain explicit approval tied to the current preview fingerprint and every required gate.
10. Apply through

    change_apply.py

    , inspect the completed recovery manifest, then archive the evidence-preserving workspace.

Output Spec

ai-sdlc-change-set/v1

change_id

title

summary

status

owner

flow_mode

contract_fingerprint

ai-sdlc-spec-delta/v1

ai-sdlc-change-preview/v1

ai-sdlc-change-approval/v1

ai-sdlc-change-recovery/v1

• Pass when the workspace has every required artifact, the JSON record matches the schema, paths are safe and unique, headings and metadata are complete, and the fingerprint recomputes exactly.
• Fail when creation would overwrite a workspace, a target crosses a safety boundary, metadata and machine state disagree, or any required artifact is missing.

Examples

specs/identity/requirements.md

../../policy.md

Edge Cases

• A target may not exist yet when the proposal adds a new canonical artifact; record it explicitly and let delta validation decide whether

  ADDED

  is valid.
• Multiple targets are sorted for deterministic identity.
• Re-running

  --create

  never merges or replaces an existing workspace.
• A hand-edited record with a stale fingerprint fails validation.
• Empty delta and evidence indexes are valid at intake and become stricter in later lifecycle stages.
• Preview returns status

  blocked

  and exit code 2 for semantic conflicts while still emitting complete review evidence.
• Interrupted or failed multi-target apply uses the persisted recovery manifest to restore every already-replaced target before another attempt is accepted.

Scope Boundary

• Do not treat valid requirement delta semantics as approval or compatibility.
• Never mutate a target outside the controlled apply command or without an accepted, current, all-gates approval record.
• Do not compute downstream impact; use

  $ai-sdlc-change-impact

  and preview.
• Do not mutate canonical artifacts, policy, feature state, or specs indexes.
• This skill does not grant approval and does not merge, commit, or release a change. It may apply and archive only after validating external approval.