SDD workflow upgrade v0.4.0

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.4.0 - 2026-06-09
+
+- Added the first SDD/context-engineering workflow upgrade for Codex-managed
+  repositories.
+- Documented spec-first and spec-anchored workflow modes, context packs,
+  conditional steering, decision locks, context budgets, delta specs, expert
+  routing profiles, and spec drift verification.
+- Clarified quick-flow versus full orchestrator criteria and added upgrade
+  guidance for existing target repositories.
+
 ## 0.3.0 - 2026-05-23
 
 - Added public release metadata for the Codex workflow template.

README.md

@@ -1,22 +1,22 @@
 # Agentic Engineering Workflow Template
 
-Current version: 0.3.0
+Current version: 0.4.0
 
 > **Codex 5.5-led setup:** do not install this workflow by hand first.
 > Use Codex 5.5 as the setup and orchestration agent, let it inspect the target
 > repository, and let it implement the workflow layer with a scoped setup plan.
 
 `Agentic Engineering Workflow Template` turns an existing or new repository into
-a governed agentic engineering workspace. It gives Codex 5.5 an automatic
-ticket, documentation, proof, and memory workflow so agent work stays scoped,
-traceable, and reviewable.
+a governed SDD/context-engineering workspace for Codex 5.5. It gives Codex an
+automatic spec, ticket, documentation, proof, and memory workflow so agent work
+stays scoped, traceable, and reviewable.
 
 The template is designed to reduce drift and hallucinations by forcing clear
-ownership, explicit handoffs, maximum available repository context, proof gates,
-and documentation checkpoints between every meaningful step. Tickets, notes, and
-agent memory files act as the working memory for the agent system, so humans can
-focus on engineering decisions instead of manually tracking what each agent did,
-why it did it, and what must happen next.
+ownership, explicit handoffs, bounded context packs, proof gates, spec drift
+checks, and documentation checkpoints between every meaningful step. Specs,
+tickets, notes, and agent memory files act as the working memory for the agent
+system, so humans can focus on engineering decisions instead of manually
+tracking what each agent did, why it did it, and what must happen next.
 
 It is not an app, framework, service, or runtime. Use it when work needs more
 structure than one chat prompt: multi-step delivery, risky refactors, UI changes
@@ -26,6 +26,7 @@ implementation, review, and final verification.
 | Signal | Meaning |
 | --- | --- |
 | Codex 5.5 first | Use Codex 5.5 to understand, initialize, calibrate, and orchestrate the workflow. |
+| SDD mode | Use specs, tickets, context packs, and proof gates to keep agent work anchored to explicit intent. |
 | Ticket-driven memory | Tickets, closeouts, and `agent/*.md` files preserve context between agent steps. |
 | Drift control | Scope, proof gates, role boundaries, and documentation checkpoints keep work reviewable. |
 | Target-repo installed | This template stays the source; the workflow files are installed into another repo. |
@@ -57,15 +58,85 @@ the setup.
 
 ## Public Release Status
 
-Version 0.3.0 is an early public template release for Codex-managed repository
-workflows. It is meant to be copied, reviewed, and adapted inside a target
-repository before relying on it for day-to-day work.
+Version 0.4.0 is the first SDD/context-engineering upgrade for Codex-managed
+repository workflows. It is meant to be copied, reviewed, and adapted inside a
+target repository before relying on it for day-to-day work.
 
 Maturity: early practical template / pre-1.0.
 
-The template is mature enough to describe repeatable Codex roles, scoped tickets,
-proof expectations, and closeout records. It is not a guarantee that a target
-repository is ready to ship.
+The template is mature enough to describe repeatable Codex roles, scoped
+tickets, spec artifacts, context packs, proof expectations, and closeout records.
+It is not a guarantee that a target repository is ready to ship, and it does not
+claim Spec-as-Source maturity.
+
+## SDD Mode
+
+SDD mode means Codex works from explicit intent before implementation. For
+non-trivial changes, the manager should establish requirements, design, tasks,
+and, when durable behavior changes, a delta spec before assigning scoped work.
+The worker then implements against the ticket, linked specs, selected steering,
+locked decisions, and bounded context pack instead of improvising from a single
+chat prompt.
+
+This template supports two levels of SDD practice:
+
+| Mode | Use when | Required anchor |
+| --- | --- | --- |
+| Spec-first | New behavior, API, data, workflow, UI, security, migration, or architecture work needs explicit agreement before implementation. | Requirements, design, tasks, ticket scope, and delta spec when durable specs must change. |
+| Spec-anchored | A smaller change can start from an existing ticket or current spec, but implementation still has to stay aligned with the recorded contract. | Existing current specs, ticket acceptance, context pack, locked decisions, and proof gates. |
+
+This is different from Vibe Coding. Codex can still move quickly, but the work
+is not accepted because it "looks right" in a chat. The workflow asks Codex to
+name the relevant files and specs, lock grey-area decisions, state what context
+is intentionally excluded, prove the result, and record whether any spec drift
+or follow-up remains.
+
+SDD artifacts in this template include:
+
+- `specs/current/**` for durable current behavior, contracts, workflows, and
+  important constraints after installation in a target repository.
+- `specs/changes/<change-id>/proposal.md`, `delta-spec.md`, `design.md`, and
+  `tasks.md` for proposed changes.
+- `templates/specs/TEMPLATE.*.md` for requirements, design, tasks, and delta
+  spec structure.
+- `context_pack.required_files`, `context_pack.required_specs`,
+  `context_pack.required_steering_files`, `context_pack.excluded_context`, and
+  `context_pack.budget_notes` in ticket templates.
+- `locked_decisions` for pre-implementation decisions that resolve grey areas.
+- `templates/steering/*.md` for conditional steering that loads specialized
+  guidance only when file patterns, task types, or manual selection require it.
+- `expert_routing` profiles for targeted read-only review by lens, such as
+  requirements, architecture, test, security/privacy, UX/visual,
+  performance/reliability, data migration, or docs/release.
+- `prompts/spec-drift-verifier.md` for read-only comparison of specs, tickets,
+  implementation, tests, docs, and closeout.
+
+## Quick-Flow vs Full Orchestrator
+
+Use quick-flow only for tiny, clear, low-risk work that already has repository
+discovery evidence, exact `allowed_files`, exact `forbidden_files`, concrete
+Given-When-Then acceptance, proof, closeout, no-secrets handling, approval
+boundaries, and a justified `spec_contract.quick_flow_exemption`.
+
+Use a full ticket or orchestrator when the change needs more than 3 non-ticket
+files, more than 1 behavior module, requirements/design/tasks specs, a delta
+spec lifecycle, conditional steering conflict resolution, expert routing,
+architecture decisions, dependency changes, data migration, auth, security,
+privacy, unclear acceptance, unavailable proof, visual/product ambiguity, files
+outside scope, or spec drift repair. For larger delivery, the orchestrator owns
+the context budget, creates child tickets, routes the minimum useful read-only
+experts, and keeps specs, tickets, implementation, and proof aligned.
+
+## Upgrade Notes For Existing Targets
+
+Existing repositories initialized from 0.3.0 should update the workflow files
+intentionally instead of blindly overwriting local rules. Ask Codex to compare
+the target `AGENTS.md`, `agent/*.md`, ticket templates, prompts, checklists,
+steering files, and specs against this template, preserve project-specific
+rules, and add the 0.4.0 concepts only where they fit the target repository.
+After updating, run one small calibration ticket and one quick-flow candidate to
+confirm context packs, quick-flow escalation, spec drift verification, and
+closeout records are working as expected.
 
 ## Codex Quickstart
 
@@ -139,6 +210,7 @@ target. Source files in this template install into different paths in the target
 | [`templates/AGENTS.md.template`](templates/AGENTS.md.template) | `AGENTS.md` |
 | [`agent/*.md`](agent/) | `agent/*.md` |
 | [`templates/TEMPLATE.ticket.yaml`](templates/TEMPLATE.ticket.yaml) | `tickets/templates/TEMPLATE.ticket.yaml` |
+| [`templates/TEMPLATE.quick-ticket.yaml`](templates/TEMPLATE.quick-ticket.yaml) | `tickets/templates/TEMPLATE.quick-ticket.yaml` |
 | [`templates/TEMPLATE.orchestrator-ticket.yaml`](templates/TEMPLATE.orchestrator-ticket.yaml) | `tickets/templates/TEMPLATE.orchestrator-ticket.yaml` |
 | [`templates/TEMPLATE.execution-result.yaml`](templates/TEMPLATE.execution-result.yaml) | `tickets/templates/TEMPLATE.execution-result.yaml` |
 | [`templates/TEMPLATE.reusable-feature-path.md`](templates/TEMPLATE.reusable-feature-path.md) | `docs/reusable_feature_implementation_paths.md` |
@@ -165,6 +237,7 @@ shape around its normal product code, tests, package files, docs, and scripts:
 ├── tickets/
 │   ├── templates/
 │   │   ├── TEMPLATE.ticket.yaml
+│   │   ├── TEMPLATE.quick-ticket.yaml
 │   │   ├── TEMPLATE.orchestrator-ticket.yaml
 │   │   └── TEMPLATE.execution-result.yaml
 │   └── TKT-YYYY-MM-DD-example.yaml
@@ -181,7 +254,10 @@ shape around its normal product code, tests, package files, docs, and scripts:
   explicit `allowed_files`, reports changed files and proof, and stops if scope
   needs to expand.
 - `read-only reviewer`: a Codex subagent or role prompt that reviews plans,
-  risks, code, tests, or architecture without editing files.
+  risks, code, tests, or architecture without editing files. Reviewer routes can
+  use the `requirements`, `architecture`, `test`, `security_privacy`,
+  `ux_visual`, `performance_reliability`, `data_migration`, or `docs_release`
+  profile as a narrow review lens.
 - `final verifier`: a Codex reviewer that checks scope, proof gates, regression
   gates, skipped checks, and agent-memory closeout before a ticket or chain is
   marked done.
@@ -194,6 +270,24 @@ The execution modes are defined in the templates and docs:
 `standard_worker`, `expert_supported`, `bounded_expert_rounds`, and
 `research_only`.
 
+Tickets can add `expert_routing` to declare required profiles, optional
+profiles, trigger conditions, `max_rounds`, escalation behavior, and where
+reviewer output is recorded. The manager chooses the minimum useful read-only
+route from ticket risk and repository evidence; simple tickets can explicitly
+set no required profiles and `max_rounds: 0`.
+
+Quick-flow is available for tiny, clear, low-risk work through
+[`templates/TEMPLATE.quick-ticket.yaml`](templates/TEMPLATE.quick-ticket.yaml)
+and [`prompts/quick-dev.md`](prompts/quick-dev.md). It still requires repository
+discovery evidence, exact `allowed_files`, `forbidden_files`, Given-When-Then
+acceptance, proof, closeout, no-secrets handling, approval boundaries, and no
+bulk staging. It must escalate to the full ticket or orchestrator flow if the
+change needs more than 3 non-ticket files, more than 1 behavior module, an
+architecture decision, dependency changes, data migration, auth/security/privacy
+work, unclear acceptance, failing or unavailable proof, ambiguous visual/product
+behavior, files outside scope, spec drift, delta lifecycle work, or expert
+routing.
+
 ## Safety Model
 
 The template is built around narrow scope and explicit proof:
@@ -204,8 +298,13 @@ The template is built around narrow scope and explicit proof:
 - Tickets declare `allowed_files`, `forbidden_files`, in-scope work,
   out-of-scope work, proof gates, regression gates, stop conditions, and done
   definitions.
+- Quick-flow tickets are allowed only for tiny bounded work and must escalate
+  when scope or risk grows; they cannot bypass proof gates, forbidden files,
+  no-secrets rules, approval boundaries, closeout, or no bulk staging.
 - Implementation workers edit only assigned scope and do not use bulk staging.
-- Read-only Codex reviewers may analyze but do not edit files.
+- Read-only Codex reviewers may analyze but do not edit files, run migrations,
+  install dependencies, deploy, release, use secrets, push, perform remote
+  operations, or widen scope.
 - Closeout records changed files, commands run, proof, skipped checks, blockers,
   risks, and whether `agent/*.md` needed updates.
 - If no durable agent-memory update is needed, closeout records:
@@ -228,7 +327,8 @@ rules only after reviewing the target repository's real context.
    [`prompts/scoped-worker.md`](prompts/scoped-worker.md), edits only the ticket
    scope, and records proof.
 5. If the work is risky or blocked, the manager asks a read-only Codex reviewer
-   using [`prompts/read-only-expert.md`](prompts/read-only-expert.md).
+   using [`prompts/read-only-expert.md`](prompts/read-only-expert.md) and the
+   smallest useful `expert_routing` profile.
 6. The worker or manager records closeout using
    [`templates/TEMPLATE.execution-result.yaml`](templates/TEMPLATE.execution-result.yaml).
 7. A final verifier uses
@@ -242,6 +342,11 @@ For larger delivery, start from
 [`templates/TEMPLATE.orchestrator-ticket.yaml`](templates/TEMPLATE.orchestrator-ticket.yaml)
 and let the manager split the outcome into child tickets.
 
+For tiny bounded work, start from
+[`templates/TEMPLATE.quick-ticket.yaml`](templates/TEMPLATE.quick-ticket.yaml)
+and use [`prompts/quick-dev.md`](prompts/quick-dev.md). Convert to a full ticket
+as soon as any escalation condition is true.
+
 ## Reference
 
 - [`docs/workflow.md`](docs/workflow.md) explains the workflow, roles, execution

VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

agent/CHANGELOG.md

@@ -3,6 +3,11 @@
 Concise local workflow changelog. This is not a replacement for Git history or
 release notes.
 
+## 2026-06-09
+
+- `TKT-2026-06-09-readme-terminology-version-0-4-0`: recorded the template
+  0.4.0 SDD/context-engineering release metadata and README terminology update.
+
 ## YYYY-MM-DD
 
 - `<ticket id>`: `<short completed change and proof summary>`

agent/DECISIONS.md

@@ -7,5 +7,8 @@ Newest entries go at the bottom.
 
 - Context: `<why the decision was needed>`
 - Decision: `<what was decided>`
+- Rationale: `<why this option was selected>`
+- Owner: `<user|manager|ticket|spec>`
 - Consequence: `<what future Codex sessions must do because of it>`
 - Source: `<ticket or doc path>`
+- Expiry/change rule: `<when this expires, or what approval/spec/ticket is required to change it>`

checklists/closeout.md

@@ -16,6 +16,14 @@ Use before marking a ticket `done`.
 - [ ] Browser/UI proof was collected when user-facing UI changed.
 - [ ] Screenshots/recordings were captured when visual gate required them.
 - [ ] Temporary logs, debug UI, fixtures, and probes were removed or gated.
+- [ ] Significant behavior/API/data/workflow changes checked the delta-spec lifecycle.
+- [ ] Accepted delta-spec `ADDED`, `MODIFIED`, and `REMOVED` items were merged into `specs/current/**`, or a deferred spec update blocker is recorded.
+- [ ] Closed delta-spec change package was archived under `specs/archive/<date>-<change-id>/`, or the archive deferral is recorded.
+- [ ] Parallel spec conflicts for the same `specs/current/**` path or requirement ID were checked and reconciled or recorded as blockers.
+- [ ] Spec drift verification ran for non-trivial tickets, or a justified `spec_contract.quick_flow_exemption` is recorded.
+- [ ] Spec drift verifier stayed read-only and any material findings were left for separate scoped repair/spec/test/doc tickets.
+- [ ] `execution_result.spec_alignment` records `verdict`, `checked_specs`, `drift_findings`, and `required_followups`, or the quick-flow exemption reason.
+- [ ] Implemented-but-unspecified, specified-but-unimplemented, tests-missing-for-acceptance, docs-outdated, and changed-behavior-not-approved questions were checked.
 - [ ] `agent/STATE.md` was checked and updated if current state changed.
 - [ ] `agent/DECISIONS.md` was checked and updated if a durable decision was made.
 - [ ] `agent/KNOWN_ISSUES.md` was checked and updated if a repeatable hazard remains.

checklists/spec-drift.md

@@ -0,0 +1,30 @@
+# Spec Drift Checklist
+
+Use before final verification for non-trivial tickets unless
+`spec_contract.quick_flow_exemption.used: true` is justified in the ticket.
+
+- [ ] The verifier stayed read-only and did not repair code, rewrite specs,
+      update docs, or change ticket fields.
+- [ ] Requirements acceptance criteria were compared with the implemented diff
+      and proof.
+- [ ] Design constraints were compared with changed files, interfaces, data
+      flow, failure modes, and security/privacy notes.
+- [ ] Tasks were compared with completed work, skipped work, and
+      `execution_result`.
+- [ ] Delta-spec `ADDED`, `MODIFIED`, and `REMOVED` items were checked when a
+      delta spec was in scope.
+- [ ] Current spec updates, archives, or explicit deferrals were checked when
+      durable behavior changed.
+- [ ] Implemented-but-unspecified behavior was checked.
+- [ ] Specified-but-unimplemented behavior was checked.
+- [ ] Tests-missing-for-acceptance criteria were checked.
+- [ ] Docs-outdated risk was checked.
+- [ ] Changed behavior not approved by ticket/specs/decisions was checked.
+- [ ] Drift findings list concrete file references and mark blocking versus
+      non-blocking impact.
+- [ ] Required follow-ups are separate scoped repair/spec/test/doc tickets, not
+      auto-repairs by the verifier.
+- [ ] `execution_result.spec_alignment.verdict` is `pass`, `pass_with_risk`,
+      or `fail`.
+- [ ] `execution_result.spec_alignment.checked_specs`,
+      `drift_findings`, and `required_followups` are complete.