implement-slice-from-contract

name

implement-slice-from-contract

description

Implement exactly one approved slice from existing contracts and architecture rules. Use only when Codex has one approved `SLICE-*`, relevant contracts, architecture rules, resolved technology context, and codebase context and must write or modify code, tests, and a mandatory implementation report using established repository conventions, repo-backed stack profiles, or explicitly justified fallback practices. Do not use for planning, architecture redesign, or multi-slice delivery.

Implement Slice From Contract

Goal

Implement one approved slice with minimal, architecture-conformant changes, inspectable stack-conformant implementation choices, externally injected runtime configuration, and enough tests to prove the slice works. Treat implementation as a test-and-fix loop: do not finalize the slice on the first failing validation when it can still be corrected within the approved slice boundary.

Read Shared Contract Reference before editing code or reporting results.

Trigger boundary

• Use only when a single approved SLICE-* is ready to implement.
• Do not use for planning slices, redesigning the architecture, or implementing multiple slices at once.

Required input

• Required: one approved slice from slice-plan.md or equivalent with metadata showing approval_status: approved and a stable SLICE-* identifier
• Required: relevant contracts with metadata showing approval_status: approved and stable identifiers
• Required: relevant architecture rules from an approved architecture artifact
• Required: resolved technology context that identifies the active stack and its standard configuration mechanism, either from workflow state, approved artifacts, or a repo-backed stack profile
• Required: git workflow context that identifies the dedicated work-branch rule, the selected slice branch name, and the integration branch name
• Required: existing codebase context

Refusal and blocked policy

• Refuse to widen scope to multiple slices.
• Do not redesign the system while implementing.
• Prefer established repository conventions first; when the repository is silent, use an applicable repo-backed stack profile; only when both are absent may you fall back to widely adopted stack practices, and that fallback must be justified in the implementation report.
• Keep secrets and runtime configuration outside the codebase; wire them in through an external mechanism such as .env, .env.example, environment-based framework config, or the stack's equivalent.
• Avoid unrelated refactors unless they are required to complete the approved slice safely.
• Stop and report if the slice is not actually approved or if critical upstream artifacts are missing.
• Return BLOCKED when the slice definition, contract IDs, architecture rules, or stack/configuration context needed for safe implementation are missing.
• Return BLOCKED when neither repo conventions nor a repo-backed stack profile make implementation choices inspectable enough for review.
• Return BLOCKED when the slice cannot reach a passing focused validation result because an external prerequisite is missing or failing outside the approved slice boundary.
• Return BLOCKED when the required integration branch does not exist or the slice cannot be merged back into it within the approved slice boundary.

Workflow

1. Read the slice definition, contracts, architecture rules, resolved stack context, git workflow context, and current codebase conventions before editing code.
2. Confirm that the configured integration branch exists and that a dedicated slice work branch is selected for this SLICE-*.
3. Create or switch to the dedicated slice branch from the integration branch before editing code.
4. Identify the active stack details that constrain implementation choices, including language, framework, ORM or persistence layer, test tooling, runtime configuration mechanism, and any applicable repo-backed stack profile.
5. Identify the smallest set of code changes needed for the slice.
6. Stop if the required behavior spills into additional SLICE-* goals or unrelated refactors.
7. Implement only the modules, adapters, configuration wiring, and tests required by the slice, using repository-native patterns, repo-backed stack profile rules, or explicitly justified fallback practices.
8. Externalize every new runtime setting, secret, endpoint, credential, or environment-dependent value through the stack's standard external configuration path rather than hard-coding it in source.
9. Check the diff against dependency rules, boundary rules, configuration handling rules, and slice-branch scope.
10. Run focused validation for the touched behavior on the slice branch.
11. If focused validation fails and the failure is fixable within the approved slice, fix the slice and rerun validation before reporting completion.
12. Once the slice branch has a passing focused validation result, commit the slice work, merge it back into the configured integration branch using a non-interactive flow, and rerun the focused validation on the integration branch when feasible.
13. Only stop with status: completed when the last required validation run passes and the merge into the integration branch succeeds. Use status: blocked only when an external blocker prevents a passing rerun or the required merge inside the slice boundary.
14. Produce a mandatory implementation report without silently expanding scope.

Output contract

After implementation, write a slice-specific implementation report such as implementation-report-SLICE-01.md or return equivalent Markdown using this structure. Do not overwrite earlier slice reports when the workflow contains multiple approved slices.

# Implementation Report

## Artifact Metadata
- artifact_id:
- artifact_type: implementation-report
- artifact_status: draft | current | superseded
- approval_status: pending_review | approved | changes_required | rejected
- approved_by_gate_profile: none | implementation-conformance | architecture-boundaries
- gate_report_ref: none | <ref>
- upstream_artifact_refs:

## Status
- implemented_slice_id: SLICE-*
- status: completed | blocked | partial

## Implemented Scope
- summary:

## Files Changed
- ...

## Stack Context Used
- language_or_runtime:
- framework_or_platform:
- persistence_or_orm:
- configuration_mechanism:
- stack_profile_ref: none | <ref>
- context_sources:
  - workflow_state | approved_artifact | existing_codebase | repo-backed_stack_profile

## Stack Conventions Applied
- area: package_layout | transport_adapter | persistence | testing | configuration | migrations
- convention_source: existing repo pattern | repo-backed stack profile | justified stack fallback
- convention_reference:
- why_applied:
- deviation_or_none:
- deviation_justification:

## Configuration And Env Changes
- config_item:
- externalization_mechanism:
- checked_in_template_or_docs:
- runtime_injection_point:

## Git Workflow
- working_branch:
- integration_branch:
- branch_created_from:
- merge_status: merged | blocked
- merge_commit_ref:
- post_merge_validation:

## Contracts Touched
- contract_id:
- how_touched:

## Invariants Validated
- invariant_id:
- validation_evidence:

## Tests Added Or Updated
- ...

## Tests Run
- ...

## Validation Loop
- final_validation_status: passed | blocked
- fix_iterations_completed:
- last_failing_signal_before_fix:
- remaining_validation_blockers:

## Tests Not Run With Reason
- test_or_scope:
- reason:

## Assumptions
- ...

## Deviations From Slice Plan
- deviation:
- reason:

## Remaining Follow-Ups
- ...

Quality bar

• Keep the diff traceable to one approved slice.
• Follow established repository conventions when they exist; otherwise use a repo-backed stack profile and record the specific convention reference used.
• Only fall back to popular, maintainable stack practices when neither the repo nor a stack profile is decisive, and record explicit justification for that fallback.
• Make tests target the contract and invariant affected by the slice.
• Rerun focused validation after every fix that changes slice behavior; do not stop on the first failing run if the slice can still be corrected safely.
• Treat a green final validation run as the default completion bar for the slice. If that bar cannot be reached because of an external blocker, mark the slice blocked and record the blocker explicitly.
• Do not mark the slice complete while it exists only on a work branch; completion requires merge evidence into the configured integration branch.
• Route all runtime configuration from outside the application boundary; never hard-code secrets, credentials, endpoints, or deployment-specific values into source files.
• When configuration is added, update the repo-facing handoff surface such as .env.example, config templates, docs, or the stack-equivalent bootstrap so another operator can supply values externally.
• Preserve boundary rules even when the surrounding codebase is imperfect.
• Prefer small, reversible changes over broad cleanup.
• Record scope drift explicitly instead of smuggling extra work into the same implementation step.
• Make stack-convention choices inspectable by citing repo files, stack profile sections, or explicit fallback justification in the implementation report.
• Initialize artifact metadata with approval_status: pending_review until a gate or approver marks it otherwise.