config: Reduce workflow instruction duplication

[davidabram]

Summary

Reduce duplicated workflow instructions, repair one related next-task recovery contract, and normalize workflow terminology in 12 commits covering 11 tracked changes while preserving workflow behavior.

1. Compact shared execution preambles

Replace the repeated Purpose, User-visible output, and Composite control flow sections with one inline Execution contract in change-to-plan, next-task, commit, validate, and handover.

• Author the contract once in workflow-content.pkl, using explicit standard and task-decision variants.
• Preserve phase references, input parsing, phase logic, waits, output layouts, terminal rules, and next-task's bounded sce-decision exception.
• Brownfield remains unchanged. The standalone decision package is unchanged by this initial preamble change and is later updated by tracked change 10.

2. Deduplicate next-task approval-gate ownership

• sce-next-task/SKILL.md parses approved and conditionally passes the approve flag.
• references/task-execution.md owns gate behavior, waits, decisions, and the no-edit-before-approval boundary.
• references/output.md owns the exact gate layout and approval question.

3. Deduplicate next-task complete execution handoff

• references/task-execution.md owns the composite live complete handoff field list exactly once.
• sce-next-task/SKILL.md passes the result verbatim.
• references/context-sync.md validates and consumes that contract without restating the live field list.
• Package mode keeps references/execution-contract.yaml; cross-session retry remains a distinct persisted completed-task record shape.

4. Repair synchronization-debt recovery

Remove the stale dependency on a persisted Context synchronization handoff, which no longer exists.

• Plan review owns synchronization-debt resolution and returns the resolved plan path, debt task ID/title, completed task record read directly from the plan, and persisted blocker when present.
• /next-task only routes that resolved record to the Task context synchronization phase.
• Context sync continues to validate and consume the completed task record directly from the plan.
• Legacy completed tasks without a durable completion record still block with the existing migration path.
• Debt scan ordering, lifecycle writes, sync-specific blocked output, and post-recovery re-review are unchanged.

5. Deduplicate the mandatory five-root context pass

Make task context synchronization the sole owner of the exact mandatory root-file set.

• references/task-execution.md now only validates and hands off context_impact; it no longer restates synchronization policy.
• references/context-sync.md discovery points to the named mandatory-root-pass subsection instead of relisting the five root paths.
• The mandatory-root-pass subsection remains the single exact definition of context/overview.md, context/architecture.md, context/glossary.md, context/patterns.md, and context/context-map.md.
• The retained plan-context-sync discovery body uses the same ownership rule in canonical Pkl.
• Impact classifications still cannot waive the pass; missing root files remain reportable gaps; synchronization verification still requires every root file to be checked against code truth.
• A generated semantic contract rejects root-path relisting in discovery and root-pass policy leakage back into task execution.

6. Deduplicate change-to-plan template policy

Make references/plan-template.md the sole owner of persisted plan schema and generic plan-authoring rules.

• references/plan-authoring.md now owns planning process only: resolving the target, challenging the change, clarification, deriving plan-specific criteria, deciding task boundaries/dependencies/order, no_actionable_work, and writing/revising one plan.
• references/plan-template.md owns acceptance-criteria format and validation semantics, task fields and atomic slicing, the no-validation-task rule, completion records, and existing-plan update preservation.
• The sequential T01..T0N rule moved into the template rather than being dropped.
• Plan authoring references the template at the acceptance, task, write, and revision boundaries instead of retelling those rules.
• A generated semantic contract requires the policy in the template and rejects its reappearance in plan-authoring.

7. Deduplicate commit bypass execution

Make references/atomic-commit.md the sole owner of the exact bypass execution handoff.

• sce-commit/SKILL.md invokes that handoff once instead of restating the temp-file, commit, hash, cleanup, and failure procedure.
• The Atomic commit phase still returns the message; the invoking /commit workflow still performs the actual commit.
• The handoff retains the verbatim temp-file write, exactly one git commit -F, git rev-parse --verify HEAD^{commit} only after success, no retry/amend/staging/hash fabrication on failure, and cleanup where practical.
• The workflow continues to own success/failure output-layout selection.
• A generated semantic contract requires the exact sequence in references/atomic-commit.md and rejects its reappearance in sce-commit/SKILL.md.

8. Deduplicate validation report policy

Make references/validation.md the sole owner of validation execution policy and keep references/validation-report.md focused on persisted presentation.

• references/validation.md owns command selection and execution, evidence interpretation, acceptance-criterion state, outcome classification, and the non-repairing boundary.
• references/validation-report.md owns only the persisted ## Validation Report schema and rendering of already-established status, command results, criterion evidence, failures, and retry guidance.
• The embedded Validation Result report rules consume the status and evidence produced by validation execution instead of restating pass-evidence and no-repair rules.
• Plan-authored validation checks, repository fallback behavior, debug/scaffolding failure semantics, failed retry output, observational behavior, and task/context mutation boundaries are unchanged.
• A generated semantic contract requires execution policy in the validation reference and rejects the old duplicated execution-policy wording in the persisted report reference.

9. Deduplicate handover completeness contract

Make references/handover-template.md the sole owner of the persisted handover schema and completeness validity rules.

• Writer composition reads the template and populates its layout without relisting the four required section names.
• Writer post-write validation checks the written file against the template's Completeness contract instead of restating the section requirement.
• Loader validation consumes the same contract instead of carrying a second required-section list and content-validity algorithm.
• The template retains the required section order and now explicitly owns non-whitespace/content checks, empty-list and unreplaced-placeholder rejection, and None identified.-style valid content.
• Writer/loader side-effect boundaries, path rules, output layouts, and read-only loader behavior are unchanged.
• A generated semantic contract requires the completeness policy in the template and rejects its reappearance in sce-handover/SKILL.md.

10. Deduplicate decision qualification and ADR-template ownership

• Task context synchronization solely owns the decision-qualification threshold and decides whether to invoke sce-decision.
• sce-decision consumes the caller's gate result and owns ADR lifecycle, history, path, and internal-result behavior without redefining the threshold.
• references/adr-template.md solely owns the persisted ADR schema and section semantics.
• Existing qualification outcomes, immutability, supersession, collision handling, and blocking/nonblocking behavior remain unchanged.

11. Normalize workflow language and document format

• Add context/sce/workflow-vocabulary.md as the single authority for workflow terminology, lifecycle language, verbs, and document roles.
• Consistently distinguish workflows, skills, phases, steps, internal results, reports, layouts, handoffs, and completion records.
• Normalize sentence-case headings, continuation wording, validation-report terminology, and persisted-document structure across canonical Pkl and generated Pi/Claude/Codex mirrors.
• Preserve command names, argument tokens, status values, approval gates, phase order, write permissions, persisted plan/task fields, decision qualification, and lifecycle transitions.

The PR contains 12 commits implementing 11 tracked changes (T01–T11); the workflow-language and document-consistency work was completed in two commits. No temporary preparation scripts, workflow files, or generated config trees are included. The runtime-managed root .opencode/ tree is untouched.

Measured reduction

For the first commit, the replaced workflow preambles shrink by 48.62–50.98% in UTF-8 bytes. The five .pi entrypoints contain 78 fewer Markdown lines; all fifteen tracked mirrors contain 234 fewer lines from that preamble change alone.

For the third commit, the selected next-task entrypoint/execution/context-sync documents shrink by another 19 Markdown lines per tracked Pi/Claude/Codex target.

For the fifth commit, task-execution.md and context-sync.md shrink by another 7 Markdown lines per tracked target, 21 lines across Pi/Claude/Codex.

For the sixth commit, plan-authoring.md plus plan-template.md shrink by another 16 Markdown lines per tracked target, 48 lines across Pi/Claude/Codex.

For the seventh commit, sce-commit/SKILL.md plus references/atomic-commit.md shrink by another 7 Markdown lines per tracked target, 21 lines across Pi/Claude/Codex.

For the eighth commit, references/validation.md plus references/validation-report.md shrink by another 6 Markdown lines per tracked target, 18 lines across Pi/Claude/Codex.

For the ninth tracked change, sce-handover/SKILL.md plus references/handover-template.md shrink by another 3 Markdown lines per tracked target, 9 lines across Pi/Claude/Codex.

For the tenth tracked change, the selected decision skill/template and next-task context-sync documents shrink by another 13 Markdown lines per tracked target, 39 lines across Pi/Claude/Codex.

The eleventh tracked change standardizes terminology and document format; no additional size-reduction claim is made for it.

Verification

Passed in branch-only Nix verification environments:

• pkl eval config/pkl/renderers/generation-contract-check.pkl.
• nix run .#pkl-check-generated.
• Approval-gate ownership checks across Pi, Claude, and Codex.
• Complete execution-handoff ownership checks across Pi, Claude, and Codex.
• Synchronization-debt checks confirm the ghost persisted handoff is absent and recovery routes the completed task record directly.
• Root-pass ownership checks confirm the exact five paths are defined by the mandatory-root-pass subsection, omitted from discovery, and absent from task-execution policy.
• Plan-template ownership checks confirm generic acceptance/task/update policy exists in the template and is not restated in plan-authoring.
• Commit-bypass ownership checks confirm the exact execution sequence exists only in the atomic reference and the workflow entrypoint only invokes it.
• Validation-report ownership checks confirm execution policy remains in references/validation.md while references/validation-report.md only renders established results.
• Handover schema/completeness ownership checks confirm the persisted template solely owns required-section and content-validity policy while writer and loader consume it.
• Decision ownership checks confirm task context synchronization solely owns qualification, the decision skill consumes the gate result, and the ADR template solely owns persisted schema and section semantics.
• Workflow-language consistency checks confirm the canonical vocabulary, lifecycle terms, report/result terminology, continuation wording, and document-role conventions across generated artifacts.
• Generated Pi/Claude/Codex mirrors match canonical output, and the generated inventory remains exactly 141 artifacts.
• Negative Pkl fixtures still pass with their expected diagnostics.
• git diff --check passed.

Preamble generation/measurement evidence: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34204063303

Preamble context/contract verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34204430298

Approval-gate implementation verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34206812301

Final approval-reference verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34207392059

Execution-handoff generation and ownership verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34209628861

Synchronization-debt recovery verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34213665376

Root-pass ownership verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34214976922

Plan-template ownership verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34216059288

Commit-bypass ownership verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34218845674

Validation-report ownership verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34221068225

Handover schema/completeness ownership verification: https://github.com/crocoder-dev/shared-context-engineering/actions/runs/34225274990

Textual and generation checks do not prove identical model behavior; no model-run or tokenizer-based savings claim is made.

Plan and scope

Plan: context/plans/compress-workflow-execution-preamble.md. It records completed work items T01 through T11 for the eleven tracked changes above.

Still out of scope: other workflow-duplication audit findings not represented by T01–T11.