legacy-step-contract

<!-- Legacy Spec Factory Copyright 2026 Leo L Zhang Original author: Leo L Zhang License: Apache License 2.0 This skill is part of the Legacy Spec Factory project. Retain this notice in substantial copies or derived versions. -->

Legacy Step Contract

Skill Card

Field	Notes
Problem solved	Defines the shared INPUT -> EXECUTION -> OUTPUT -> VALIDATION contract every Legacy Spec Factory step must follow.
Input	A skill, step design, or artifact that needs contract shape, quality gates, and validation semantics.
Output	Contract guidance for readiness, execution rules, output status, validation expectations, and workflow state write-back.
Core prompt strategy	Make stage boundaries explicit, define allowed inference and stop conditions, and keep status transitions auditable.
Upstream skill	None; this is the governance baseline for the skill family.
Downstream consumer	All Legacy Spec Factory skills and legacy-step-validator.
Validation standard	Each step declares inputs, execution rules, outputs, validation result semantics, and blocked/warning handling.
Known risk	Treating the contract as prose guidance only instead of a required quality gate.
Practical example	Use the contract to add a Step Contract section to a new data-model analysis skill before accepting it.

Purpose

Every step in the Legacy Spec Factory reverse chain follows the same shape:

INPUT  →  EXECUTION  →  OUTPUT  →  VALIDATION

This skill formalizes that shape into a portable Step Contract so that authors, agents, and reviewers share one vocabulary across:

• legacy-ibmi-inventory
• legacy-ibmi-program-analyzer
• legacy-ibmi-flow-analyzer
• legacy-ibmi-module-analyzer
• legacy-spec-writer
• legacy-spec-reviewer (planned)
• forward SDLC handoff (docs/forward-sdlc-contract.md)
• future Layer 1 families (legacy-cobol-*, legacy-mainframe-*)

The skill defines (or reviews) Step Contract blocks and the Step Validation Report shape. legacy-step-validator applies this contract to completed artifacts and emits filled validation reports under 06_quality/. This skill does not produce inventory, program analyses, specs, or business findings.

When to Use

Trigger on any of these signals:

• An author or agent is designing a new pipeline step and needs a contract to anchor it.
• A step is about to execute and the runner wants to confirm its inputs and stop conditions before producing output.
• A step has produced output and a reviewer wants a structured pass / warn / block decision before downstream handoff.
• A skill review (docs/skill-review-gate.md) wants to verify that a skill's workflow and output contract are explicit and enforceable.
• An orchestrator (legacy-modernization-orchestrator) needs to surface why a gate is blocked in a uniform shape.

When NOT to Use

Do not trigger when:

• The user wants the business artifact itself (inventory, program analysis, flow, module, spec, review). Route to the dedicated skill.
• The user wants SME interviews, capability discovery, or rule mining.
• The task is forward SDLC code generation. Use wwa-lab/build-agent-skill.
• The task is platform-specific extraction. Use the matching Layer 1 skill.

This skill is a contract layer. If you find yourself producing IBM i facts, you are in the wrong skill.

Role

You are the contract author / contract checker for one pipeline step.

You must:

• restate the step's INPUT, EXECUTION, OUTPUT, and VALIDATION explicitly
• distinguish mechanical validation, AI semantic review, and SME / human approval — they are not interchangeable
• produce a compact validation result with one of three statuses
• surface unresolved items by category so the next skill (or human) can act
• refuse to infer step content the upstream artifact does not contain

You must not:

• invent inputs the step does not actually have
• mark a step pass because it "looks right" — pass requires the validation evidence enumerated below
• collapse SME approval into AI semantic review

The Step Contract

A Step Contract has four mandatory sections. See references/step-contract.md for the full field-level specification, defaults, and worked examples.

1. INPUT

Required fields:

• step_id — stable ID for this step instance (STEP-<SLUG>-<NNN> per docs/id-conventions.md)
• skill — the skill or doc that executes the step (e.g. legacy-ibmi-program-analyzer)
• prerequisite_artifacts — list of upstream artifacts with their required status (e.g. inventory.yaml at approved or approved_with_non_blocking_tbd)
• prerequisite_gates — gates that must already be passing (Evidence Authorization, Inventory Completeness, Evidence Approval, Forward Handoff)
• evidence_scope — the EV-* IDs and OBJ-* IDs that are in scope, plus authorization fields (sensitivity, source_path_verified, redaction_required, redaction_status) that must already be resolved
• sme_availability — whether an SME owner is required for this step and the capability slug they own
• assumptions_recorded — assumptions the runner is allowed to make explicitly, never silently

Stop and refuse to execute the step if:

• any prerequisite artifact is missing or below the required status
• any prerequisite gate is blocked
• any evidence has sensitivity: unknown, lacks source-path authorization, or requires redaction without an approval record
• SME is required by the step but not assigned

2. EXECUTION

Required fields:

• procedure — pointer to the workflow inside the executing skill (SKILL.md section or references/ file). The Step Contract does not re-describe the procedure; it cites it.
• inputs_to_outputs_mapping — which input fields drive which output fields
• tools_allowed — what the executing skill is allowed to do (read source, read DDS, call sub-skill, call SME, etc.)
• tools_forbidden — what the step must refuse (e.g. generating Java, inventing object names, reading unauthorized evidence)
• decision_points — any branch where the step must choose between alternatives, plus how that choice is recorded

Execution rules:

• The step writes its own output. The Step Contract does not.
• The step preserves IDs; it does not renumber on re-execution.
• The step records every assumption inline with the artifact it produces.
• The step treats rendered previews, browser views, image/PDF previews, Mermaid previews, spreadsheet previews, and HTML openings as optional review aids. They must not be automatic completion gates unless the executing skill explicitly says so or the user asks for visual inspection.
• After primary artifacts, validation status, and workflow-state write-back are recorded, the step stops. It does not keep polling workflow status, re-reading changed files, or reopening previews. Re-entry is allowed only when a deterministic validator finding names a concrete artifact to fix.

3. OUTPUT

Required fields:

• primary_artifacts — file paths, suggested filenames, and the schema or template each one must follow
• id_namespaces — which ID prefixes the step is allowed to mint (BEH-*, BR-*, BR-* seeds, STEP-*, TBD-*, etc.) per docs/id-conventions.md
• cross_references — what the output must link back to (every claim links to one or more EV-*; every BR-* links to BEH-* and EV-*)
• status_field — the lifecycle field the artifact carries (draft, delivery_draft, in_review, approved, approved_with_non_blocking_tbd, blocked, rejected, retired; poc_draft is allowed only for internal POC artifacts)
• non_outputs — what the step is not allowed to produce (e.g. a flow analyzer does not produce capability specs)

4. VALIDATION

Validation has three distinct layers, in order. None substitutes for another.

4a. Mechanical Validation

What can be checked by a script, a schema, or a deterministic linter:

• required files exist at expected paths
• YAML / JSON validates against schemas/spec.schema.yaml (or the relevant schema)
• all referenced IDs resolve (no dangling EV-*, BR-*, OBJ-*)
• ID prefixes match docs/id-conventions.md
• every claim has at least one linked evidence item
• every sensitivity: unknown is resolved and every evidence item has either source-path authorization or completed required redaction
• review status fields are in the allowed enum

Mechanical validation must be reproducible. If it depends on judgment, move it to AI semantic review.

4b. AI Semantic Review

What an LLM (or careful reviewer) can check by reading the artifact against the upstream evidence:

• the artifact's claims are consistent with linked evidence
• knowledge type (observed_behavior / inferred_business_rule / modernization_decision / unknown_tbd) matches the kind of claim made
• evidence strength is not overstated (no weakly_inferred posing as confirmed_from_code)
• no invented IBM i facts (object names, fields, jobs, screens, reports)
• no scope creep into a different capability
• TBDs are explicit, not hidden inside prose

AI semantic review must call out uncertainty rather than smooth it over.

4c. SME / Human Approval

What only a domain expert can decide:

• whether an inferred rule is actually a business rule
• whether a behavior the code shows is intentional or a bug
• whether a modernization decision is acceptable
• whether a TBD is blocking or non-blocking
• whether the step's output is safe to promote to approved

SME approval is a control point, not a rubber stamp. The Step Validation Report must record the SME's name (or role), the date, and the specific decision against the specific IDs.

Compact Validation Result

Every step run must produce one of three statuses:

Status	Meaning	Downstream Effect

---

Content truncated.