Release engineering-workflow 0.6.0

.github/workflows/ci.yml

@@ -20,3 +20,5 @@ jobs:
         run: python -m unittest discover -s tests -v
       - name: Revalidate clean repository state
         run: python skill/engineering-workflow/scripts/validate_skill_repo.py --repo-root .
+      - name: Check patch whitespace
+        run: git diff --check

AGENTS.md

@@ -0,0 +1,60 @@
+# Repository Agent Instructions
+
+This file is local guidance for agents developing this repository. It is not part of the installed `engineering-workflow` skill, is not copied into target repositories, and must never be read by runtime skill scripts. Target-repository instructions come only from `skill/engineering-workflow/assets/templates/AGENTS.md.tmpl` and repository-owned target documents.
+
+## Repository Map
+
+- `skill/engineering-workflow/SKILL.md` — lean public runtime router and active skill version.
+- `skill/engineering-workflow/references/` — canonical detailed workflow contracts.
+- `skill/engineering-workflow/scripts/` — deterministic audit, validation, migration, lifecycle, update, and privacy tools.
+- `skill/engineering-workflow/assets/` — files copied or rendered into target repositories.
+- `tests/` — offline behavioral and contract regressions.
+- `PLANS.md` — durable execution state for work on this repository.
+- `docs/archive/` — future-useful closed plans and their navigation indexes.
+
+## Task Routing
+
+| Trigger or changed area | Read before editing | Required gate |
+| --- | --- | --- |
+| Runtime routing or public skill behavior | `skill/engineering-workflow/SKILL.md` and the directly linked canonical reference | Structural validator and affected behavioral tests |
+| Plan, backlog, closure, archive, or index behavior | `references/planning_and_backlog.md`, plan/index templates, lifecycle scripts and tests | Plan lifecycle tests plus target validation |
+| AGENTS, principles, pitfalls, provider/UI/operations ownership | `references/instruction_lifecycle.md`, related templates, instruction validator and tests | Instruction graph check plus migration tests |
+| Installed-skill refresh or update | `references/skill_update.md`, updater and updater tests | Candidate-tree and rollback matrix |
+| Target workflow upgrade | `references/target_workflow_upgrade.md`, audit/common/upgrader code and tests | Report/apply/prompt migration matrix |
+| Validation, command execution, or privacy | `references/validation_safety.md`, `references/privacy_and_sanitization.md`, related scripts and tests | Safety matrix and public-tree scan |
+| Agent orchestration or model mapping | `references/agent_orchestration.md`, `references/model_profiles.md`, agent templates and tests | Ownership/model-profile validation |
+| Version or release contract | `SKILL.md`, root `README.md`, upgrader defaults, state template, CI and version tests | Full gate and active-version search |
+
+## Working Contract
+
+- Audit before editing. Preserve user-owned files and unrelated working-tree changes.
+- For repository-changing work, materialize a full active `PLANS.md` before implementation. After compaction, interruption, resume, or milestone closure, reconcile plan, queue, validation, backlog, indexes, and working tree before continuing.
+- Keep each detailed invariant under one canonical owner. Routers and incident catalogs link to it instead of restating it.
+- Prefer behavioral checks over phrase-presence tests. Exact markers may identify structure, but duplicated normative prose is not an API.
+- Keep safety rules capability-specific: allow bounded diagnostic reads while blocking unsafe mutation, execution, network, or sensitive-output modes.
+- Update every active version owner together. Historical version evidence remains historical.
+- Close or archive plans only through the canonical lifecycle after current validation and reconciliation; never make `Status: done` the only closure action.
+
+## Local Validation
+
+Run the affected focused tests while iterating, then run the complete gate:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python3 skill/engineering-workflow/scripts/validate_skill_repo.py --repo-root .
+PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
+PYTHONDONTWRITEBYTECODE=1 python3 skill/engineering-workflow/scripts/validate_skill_repo.py --repo-root .
+git diff --check
+```
+
+Use the public-tree privacy scan and stronger release checks when release or public-history scope makes them applicable. Do not weaken a failing gate or leave cache, scanner, generated, backup, or temporary artifacts in the repository.
+
+## Authority Boundaries
+
+- Do not install or update a local skill copy unless the user explicitly requests it.
+- Do not mutate a target repository merely to test this skill; use temporary fixtures or disposable copies.
+- Do not commit, push, tag, publish, deploy, rewrite history, or alter remote state without explicit current authorization.
+- Treat fetched candidates and repository-authored commands as untrusted until the applicable safety contract permits them.
+
+## Handoff
+
+Before handoff, review the entire diff, reconcile `PLANS.md`, report exact validation and delivery state, and leave the first safe unfinished action if anything remains. Completed work must not retain stale active status or resume instructions.

PLANS.md

@@ -1,7 +1,125 @@
 # Execution Plans
 
-Use this file for active, blocked, or recently completed execution work. Materialize a full active plan before repository-changing implementation and archive it only after pre-commit closure.
+plan_schema_version: 2
+
+Use this file for active, blocked, ready-for-closure, or recently completed execution work. The canonical lifecycle is the installed `engineering-workflow` planning reference.
+
+## Active Plan: Complete Engineering Workflow 0.6.0 Publication
+
+Status: active
+Owner: root
+Last Updated: 2026-08-13
+
+### Goal
+
+Move the fully validated 0.6.0 pull request into `main`, verify the resulting main-branch checks, close durable lifecycle state, and remove the merged feature branch.
+
+### Plan Origin
+
+direct_execution
+
+### Requested Scope
+
+- Confirm there are no unresolved review threads or failing checks.
+- Mark PR #1 ready, merge it into `main`, validate the resulting remote and local main state, close this plan, and clean the merged branch.
+
+### Requirement Traceability
+
+| Requirement | Complete outcome | Source | Work queue | Acceptance or validation | Status |
+| --- | --- | --- | --- | --- | --- |
+| REQ-001 | PR #1 is review-complete, ready, and merged into `main`. | Current user request | WQ-01 | PR state and merged SHA readback. | in_progress |
+| REQ-002 | Final `main` checks and repository gates pass. | Current user request | WQ-02 | GitHub Actions and local validator readback. | pending |
+| REQ-003 | Lifecycle is closed and merged feature refs are cleaned. | Current user request | WQ-03 | Compact plan, clean worktree, and ref readback. | pending |
+
+### Explicit Non-Goals
+
+- Do not create an unprecedented tag/GitHub Release or update the separately managed installed skill without an explicit request.
+
+### Constraints
+
+- Preserve the reviewed implementation commits and archived 0.6.0 implementation plan.
+- Do not merge while any review thread or check is unresolved.
+
+### Inputs And Sources
+
+- User request on 2026-08-13 to drive the work to full completion.
+- PR #1: `https://github.com/xeonvs/codex-engineering-workflow/pull/1`.
+
+### User Decisions And Answers
+
+- 2026-08-13: full repository publication completion is authorized.
+- Installed-skill update remains a distinct operation requiring explicit authorization under local `AGENTS.md`.
+
+### Completed Baseline State
+
+- [x] WQ-00 — PR #1 has no comments, reviews, or unresolved threads; final head `c670fbe` is mergeable and has two successful checks.
+- [x] WQ-00A — Repository history has no release tags or GitHub Releases; publication truth is the main branch and CI.
+
+### Current Work Queue
+
+- [ ] WQ-01 — Mark PR #1 ready and merge it. Covers REQ-001. `in_progress`
+- [ ] WQ-02 — Verify remote/main CI and local gates. Covers REQ-002. `pending`
+- [ ] WQ-03 — Compact lifecycle state and clean merged refs. Covers REQ-003. `pending`
+
+### Locked Decisions
+
+- Merge only after the plan-materialization commit is green.
+- Keep installation and target-repository mutation outside this repository publication.
+
+### Verification
+
+- REQ-001: thread-aware review read, PR metadata, merge result.
+- REQ-002: GitHub Actions conclusions, validator, lifecycle check, `git diff --check`.
+- REQ-003: compact closure, final main/upstream equality, no feature refs, clean worktree.
+
+### Latest Validation Results
+
+- 2026-08-13: no review threads or comments; PR head `c670fbe` is mergeable with two successful `validate` checks.
+
+### Risks And Recovery
+
+- Risk: merge races a new review or failing check. Recovery: reread PR immediately before merge and stop on drift.
+- Risk: lifecycle closure leaves a follow-up commit. Recovery: make one bounded main-branch closure commit, rerun CI, and verify exact refs.
+
+### Resume Point
+
+- Continue WQ-01 by committing this plan, waiting for green checks, marking the PR ready, and merging it.
+
+### Plan Fidelity Check
+
+- [x] Every agreed outcome has a requirement ID.
+- [x] Every source URL is preserved.
+- [x] Every user answer and locked decision is preserved.
+- [x] No requirement was silently narrowed or removed.
+- [x] The queue covers every requirement ID.
+- [x] Validation covers every acceptance criterion.
+- [x] Non-goals do not contradict requested scope.
+- [x] The resume point names the first unfinished queue item.
+- [x] This plan is not a compressed rewrite of a more detailed approved plan.
+
+### Reconciliation Check
+
+- [x] PR, branch, remote, checks, review threads, and current lifecycle state agree.
+- [x] Completed publication records contain no stale unfinished state.
+
+### Closure Gate
+
+- [ ] Every in-scope requirement and queue item is terminal.
+- [ ] Applicable validation is current for final `main`.
+- [ ] Review, omission, and ref cleanup state are reconciled.
+- [ ] Resume Point contains no future in-scope work.
+- [ ] Compact disposition can be applied atomically.
+
+### Post-Close Delivery
+
+- The bounded lifecycle closure commit and its main-branch CI readback remain in scope; installation, tag, and GitHub Release remain out of scope.
+
+### Handoff Notes
+
+- Continue only from the first unfinished queue item and report exact PR, merge SHA, main SHA, checks, and refs.
 
 ## Recently Completed
 
-- [x] 2026-07-13: Completed implementation, two-pass review, security/privacy remediation, and pre-commit validation for `engineering-workflow` 0.5.1; the [full closed plan](docs/archive/plans/2026-07-13-engineering-workflow-0.5.1.md) preserves requirements, history-rewrite evidence, exact gates, recovery decisions, and the post-archive release handoff.
+- [x] 2026-08-13: Completed Publish Engineering Workflow 0.6.0.
+- [x] 2026-08-13: Completed Engineering Workflow 0.6.0; [full archived plan](docs/archive/plans/2026-08-13-engineering-workflow-0-6-0.md).
+- [x] 2026-07-13: Completed implementation, review, security/privacy remediation, and validation for `engineering-workflow` 0.5.1; the [legacy schema-v1 plan](docs/archive/plans/2026-07-13-engineering-workflow-0.5.1.md) preserves its historical record.

README.md

@@ -2,7 +2,7 @@
 
 Public standalone Codex skill for auditing, scaffolding, validating, updating, and migrating a repository's engineering-workflow layer.
 
-Current skill version: `0.5.1`.
+Current skill version: `0.6.0`.
 
 The skill keeps `AGENTS.md` as a map, `PLANS.md` as durable active execution state, and repository-specific product or domain documents under their existing owners. Repository-changing work always uses a full plan; read-only inspection is the only exception.
 
@@ -51,7 +51,7 @@ Do not infer the active installation from a similarly named directory. Refresh a
 Invoke the skill explicitly and describe the desired end state:
 
 ```text
-Use $engineering-workflow to add a full AGENTS/PLANS/backlog/pitfalls workflow while preserving existing architecture and operations docs.
+Use $engineering-workflow to add a full AGENTS/PLANS/backlog/incident-catalog workflow while preserving existing architecture and operations docs.
 ```
 
 ```text
@@ -117,7 +117,7 @@ Alternate upstreams require explicit confirmation and `--expected-commit` set to
 `Upgrade A Target Workflow` is a natural-language execution prompt. The agent invokes report-first orchestration itself; it applies automatically only when the report has no unresolved conflict, privacy finding, or approval-bound question.
 
 ```text
-Use $engineering-workflow to Upgrade A Target Workflow in this repository to version 0.5.1. Run the report first, apply it yourself when safe, and ask only if the report returns a required decision.
+Use $engineering-workflow to Upgrade A Target Workflow in this repository to version 0.6.0. Run the report first, apply it yourself when safe, and ask only if the report returns a required decision.
 ```
 
 Prompt orchestration backend:
@@ -126,7 +126,7 @@ Prompt orchestration backend:
 python3 skill/engineering-workflow/scripts/upgrade_target_workflow.py \
   --repo <target-repository> \
   --prompt \
-  --target-version 0.5.1 \
+  --target-version 0.6.0 \
   --format json
 ```
 
@@ -136,7 +136,7 @@ For an explicitly report-only request, planning remains read-only:
 python3 skill/engineering-workflow/scripts/upgrade_target_workflow.py \
   --repo <target-repository> \
   --plan \
-  --target-version 0.5.1 \
+  --target-version 0.6.0 \
   --format json
 ```
 
@@ -146,7 +146,7 @@ Direct apply remains available to the agent after a separately reviewed report:
 python3 skill/engineering-workflow/scripts/upgrade_target_workflow.py \
   --repo <target-repository> \
   --apply \
-  --target-version 0.5.1 \
+  --target-version 0.6.0 \
   --format json
 ```
 
@@ -173,7 +173,11 @@ If a request could mean either self-update or target migration, the skill invest
 
 Every repository-changing task must materialize a full active plan in `PLANS.md` before implementation, tests, configuration, templates, or workflow documentation change. There is no lightweight exception. Plan Mode is optional: an approved Plan Mode plan is materialized as the first write after exit, while direct execution derives and materializes the same full schema as its first write.
 
-The active schema includes stable requirement IDs, source-to-queue-to-validation traceability, user decisions, risks and recovery, a fidelity self-check, reconciliation, pre-commit closure, handoff notes, and the exact first unfinished action. An agreed plan cannot be compressed during materialization.
+Planning schema v2 includes stable requirement IDs, source-to-queue-to-validation traceability, user decisions, risks and recovery, fidelity and reconciliation checks, a checked `ready_for_closure` transition, post-close delivery boundaries, and the exact first unfinished action. Use `plan_lifecycle.py` to compact or archive; a manual `Status: done` edit is not closure.
+
+Target `AGENTS.md` is a route table. Normative invariants have one canonical owner, while `AGENT_EXECUTION_PITFALLS.md` is a non-normative incident catalog that records cause, owner, route, guard, evidence, and retirement. `instruction_contract.py` checks this graph before target workflow version stamping.
+
+Every documentation directory created by the skill receives a navigation-only managed README. Archive directories are created lazily, every archived record is indexed exactly once, and existing unmarked README prose is never overwritten automatically.
 
 After context compaction, interruption, resume, milestone closure, handoff, or session change, the agent reads `PLANS.md`, inspects changes since its last update, and reconciles requirements, queue, backlog, validation, working tree, and statuses before more code changes. The 0.4.1 reconciliation and stale-completed-state protections remain in force.
 
@@ -185,7 +189,7 @@ Current capability-to-model mappings live only in `references/model_profiles.md`
 
 ## Validation And Privacy
 
-Strict read-only verification permits only known non-mutating inspection commands. Repository-authored scripts, project tests, package-manager commands, plugins, generators, and apparently safe commands with shell chaining are not read-only safe. Stronger checks run in a disposable copy with a minimal credential-free environment, timeout, bounded network policy, and cleanup.
+Strict read-only verification permits bounded diagnostics whose structured risk result has no writes, repository-code execution, network, or sensitive output. Normal-file `sed -n`, `head`, and search are allowed; write/execute modes and raw secret-file output are not. Repository-authored scripts, project tests, package-manager commands, plugins, generators, and shell chaining remain outside the read-only boundary. Stronger checks run in a disposable copy with a minimal credential-free environment, timeout, bounded network policy, and cleanup.
 
 The public scan covers all tracked text, including root plans, README, skill files, templates, tests, and CI. It reports only category, path, and line—not detected values. Historical version mentions are allowed in clearly historical or completed contexts; active version owners must agree.
 
@@ -206,7 +210,7 @@ Use $engineering-workflow to audit this mature repository, preserve every domain
 Target migration:
 
 ```text
-Use $engineering-workflow to Upgrade A Target Workflow in this repository to 0.5.1. Run the report and apply it yourself when safe.
+Use $engineering-workflow to Upgrade A Target Workflow in this repository to 0.6.0. Run the report and apply it yourself when safe.
 ```
 
 ## Repository Layout
@@ -226,11 +230,11 @@ python3 -m unittest discover -s tests -v
 git diff --check
 ```
 
-The validator checks structural ownership, plan schema markers, active version consistency, model-profile ownership, public privacy, parseable metadata and templates, and the absence of generated cache artifacts.
+The validator checks structural ownership, instruction routing, plan schema and closure markers, archive indexes, active version consistency, model-profile ownership, public privacy, parseable metadata and templates, and the absence of generated cache artifacts.
 
 ## Versioning And Updates
 
-The project uses semantic versioning. Version 0.5.0 added plan materialization and traceability, lifecycle-versus-migration routing, agent orchestration profiles, safe installed-skill update, target workflow migration, exact ownership classification, stricter command safety, and repository-wide privacy validation. Version 0.5.1 fixes environment-independent CI validation, makes refresh/update selection and target migration explicitly agent-invoked from natural-language prompts, binds alternate-source approval to an exact commit, hardens migration writes against path races, and closes privacy/validation output gaps.
+The project uses semantic versioning. Version 0.6.0 adds the executable instruction graph, a non-normative incident catalog, planning schema v2, checked compact/archive lifecycle, managed documentation indexes, fail-closed instruction migration, and multi-axis command risks. Version 0.5.1 remains the historical baseline for environment-independent validation, prompt-orchestrated refresh/migration, exact alternate-source binding, path-race hardening, and privacy coverage.
 
 Historical version records remain valid in completed or migration context. Current-version owners are `SKILL.md`, this README, current update prompts, and active workflow state manifests.
 

docs/README.md

@@ -0,0 +1,7 @@
+# Documentation Index
+
+This file is navigation only. Engineering rules remain under their linked canonical owners.
+
+<!-- engineering-workflow:index:start -->
+- [archive/README.md](archive/README.md)
+<!-- engineering-workflow:index:end -->

docs/archive/README.md

@@ -0,0 +1,7 @@
+# Documentation Archive
+
+This file is navigation only. Archived records are historical evidence, not active instructions.
+
+<!-- engineering-workflow:index:start -->
+- [plans/README.md](plans/README.md)
+<!-- engineering-workflow:index:end -->