diff --git a/README.md b/README.md index 2c58158..6c238df 100644 --- a/README.md +++ b/README.md @@ -133,6 +133,8 @@ Workflow completion is defined by `kind`: SLDD uses this kind-specific completion rule when filtering active workflows, validating predecessor gates, and resolving `/sldd resume`. +For Markdown-producing steps, saved artifacts are reviewable drafts until the owning step is explicitly approved and marked `complete` in `_spec-journal.json`. Saving a draft is persistence; approval is gate advancement. + For `/sldd resume` without a workflow name, SLDD: 1. Finds all journals under `.sldd/specs/*/_spec-journal.json`. @@ -169,7 +171,7 @@ Formal gate order is: 01 -> 99 when needed -> 02 -> 03 -> 04 -> 05 -> 06 ``` -Step 99 is required before Step 02 for existing codebases. It may run during Step 88 when brownfield context is needed, but it satisfies the gate only after `existing-codebase-understanding.md` is approved, saved, current, and marked complete. +Step 99 is required before Step 02 for existing codebases. It may run during Step 88 when brownfield context is needed, but it satisfies the gate only after the current `existing-codebase-understanding.md` draft is explicitly approved, saved, current, and marked complete. A saved Step 99 draft may exist while the step remains `pending`. Feature step files: @@ -188,6 +190,8 @@ Feature step files: Core feature rules: - No implementation prompts or code changes before Step 01, Step 02, and Step 03 are approved. +- Markdown-producing steps save reviewable draft artifacts before approval, but artifact existence never satisfies a gate; only `status: "complete"` does. +- Revision or rejection updates the draft and keeps the step pending; explicit approval of the current draft marks the step complete and allows routing forward. - Step 88 context is conversational and non-binding unless formalized into approved numbered artifacts. - Step 04 writes tests first and must stay Red-only. - Step 05 makes the minimum production changes needed to pass Step 04 tests and must not modify Step 04 tests. @@ -230,7 +234,7 @@ Workflow-set parent steps: Workflow-set parents plan and scaffold children. They do not execute child workflows, approve child Step 01, enforce child implementation gates, or persist child execution progress. -Creating or updating a workflow-set parent requires explicit approval. A new parent journal is created only through `01-workflow-set-plan`. Existing journals without `name` or `kind` are invalid and must be corrected before routing. Existing `kind: "feature"` journals stop the workflow-set path unless the user chooses another workflow-set name or gives explicit direction. +Creating or updating a workflow-set parent plan starts by saving a reviewable `01-workflow-set-plan.md` draft. For a new workflow-set parent, draft persistence does not create `_spec-journal.json`; the parent journal is created only after explicit approval of the current plan draft, which marks `01-workflow-set-plan` complete. Existing parent journals may keep pending draft links during revision, but artifact existence never approves the plan or authorizes scaffolding. Existing journals without `name` or `kind` are invalid and must be corrected before routing. Existing `kind: "feature"` journals stop the workflow-set path unless the user chooses another workflow-set name or gives explicit direction. Child scaffolding requires: @@ -283,6 +287,8 @@ Workflow-set parents also use: Workflow-set Step 03 does not write a separate verification artifact. Scaffolded child workflows write their own `01-product-intent-specification.md` from `templates/01-product-intent-from-workflow-set.md`. +During review, any Markdown artifact above may exist as a draft while its journal step remains `pending`. Draft artifacts are intentionally persisted for review; they are not evidence of gate completion. + Child workflows scaffolded from a workflow-set get their own `.sldd/specs//` directory and journal. Legacy `docs/specs//SPEC.md` files are not `_spec-journal.json` files and do not satisfy the current journal contract. @@ -291,6 +297,8 @@ Legacy `docs/specs//SPEC.md` files are not `_spec-journal.json` fi `_spec-journal.json` is journal-only state. It records progress, artifact links, evidence, relationships, workflow kind, reasons, notes, and workflow-set scaffold state. It must not contain numbered artifact body content, command logs, or implementation reports. +A pending Markdown-producing step may include `artifact: ".md"` and `reason: "draft pending explicit approval"` or an equivalent blocker reason. This records a reviewable draft only; the gate remains closed until that step has `status: "complete"`. New workflow-set parent drafts are the exception: `01-workflow-set-plan.md` may be saved before `_spec-journal.json` exists, because parent journal creation itself waits for explicit plan approval. + Required top-level fields in the current schema: | Field | Contract | @@ -315,7 +323,7 @@ complete requires_rerun ``` -Step entries may include `artifact`, `evidence`, `reason`, `updated_at`, and `origin`. `origin.type` is currently used for `workflow-set-scaffold`. +Step entries may include `artifact`, `evidence`, `reason`, `updated_at`, and `origin`. `artifact` may point to either a pending draft or an approved artifact, so gate checks must read `status`, not infer completion from the file. `origin.type` is currently used for `workflow-set-scaffold`. Workflow-set child entries require `name`, `title`, `kind`, and `scaffold`. Child `kind` is always `feature`. Scaffold state is one of: @@ -356,6 +364,7 @@ Option 1 is an explicit override. Option 2 marks later completed steps in the se - Preserve `/sldd resume` active-workflow selection: exclude complete workflows, filter blocked workflows by predecessors, auto-resume exactly one unblocked active workflow, otherwise ask or report blockers. - Preserve `/sldd help` as informational and non-mutating. - Preserve the Step 88/Step 99 boundary: exploration context is conversational; Step 99 is approved, saved brownfield context. +- Preserve the draft artifact approval policy: saving a draft is persistence; explicit approval and `status: "complete"` are gate advancement. - Preserve the Step 04/Step 05 Red-Green contract. - Preserve workflow-set parent sequencing: `01-workflow-set-plan -> 02-scaffold-children -> 03-verify-workflow-set`. - Preserve workflow-set parent boundaries: parents do not execute children or persist child progress. diff --git a/skills/sldd/SKILL.md b/skills/sldd/SKILL.md index c205d12..9f14943 100644 --- a/skills/sldd/SKILL.md +++ b/skills/sldd/SKILL.md @@ -50,6 +50,14 @@ Legacy `docs/specs//SPEC.md` files are not `_spec-journal.json` fi Use `_spec-journal.json` as journal-only state. It records the workflow name, progress, artifact links, evidence, relationships, workflow kind, and rerun notes. It must not contain numbered artifact body content, command logs, or implementation reports. +### Draft Artifact Gate Policy + +For steps that produce Markdown artifacts, saving the artifact is draft persistence, not gate approval. Save or update the generated Markdown artifact as a reviewable draft before asking for explicit gate approval. When a journal exists or the workflow permits draft journal state, keep the step `pending` in `_spec-journal.json` with the artifact link and a concise reason such as `draft pending explicit approval`. + +A Markdown artifact's existence never satisfies a gate. A gate is satisfied only when the relevant journal step has `status: "complete"` and all workflow-specific prerequisites are valid. On revision requests or rejection, update the draft artifact and keep the step `pending`; do not route forward. On explicit approval of the current draft, mark the step `complete` with the same artifact link unless another gate rule, such as an incomplete predecessor, still blocks completion. + +Keep `_spec-journal.json` journal-only during draft persistence and approval. Do not store artifact body content, command logs, or reports in the journal. Step 04 and Step 05 remain evidence phases, not mandatory Markdown artifact phases. Step 88 remains non-mutating by default; saving `00-exploration-summary.md` still requires explicit approval and does not satisfy numbered gates. + Every `_spec-journal.json` must include `name` and `kind`. `name` is the workflow/spec name. Journals without `name` or `kind` are invalid and must not be routed, resumed, or treated as `feature`. Do not use `feature` as a top-level journal field. `feature` remains only the workflow kind value `kind: "feature"` and the feature workflow concept. @@ -118,6 +126,8 @@ Allowed step statuses: - `complete` - `requires_rerun` +A `pending` step may include an `artifact` link to a saved draft and a `reason` such as `draft pending explicit approval`; that link is review context only and does not satisfy the gate. New workflow-set parent journals are the exception: draft plan persistence may save `01-workflow-set-plan.md` without creating `_spec-journal.json` until explicit plan approval. + Step 04 (`04-tests-red`) completion requires `evidence: "red_confirmed"`. Step 05 (`05-implementation-green`) completion requires `evidence: "green_confirmed"`. For Step 04 and Step 05, non-complete statuses must omit `evidence` or set it to `null`. If a journal has `relationships.predecessors`, every listed predecessor journal must exist and have Step 06 complete before this workflow can mark Step 01 complete or route to Step 02+. @@ -133,7 +143,7 @@ When the journal exists: When no journal exists: 1. Detect the initial workflow kind from the user's intent. -2. Persist the detected `kind` in the new journal after the required workflow approval path allows journal creation. +2. Persist the detected `kind` in the new journal when the selected workflow's draft or approval path allows journal creation. 3. Load exactly one workflow file: - `workflows/feature.md` for `kind: "feature"` - `workflows/workflow-set.md` for `kind: "workflow-set"` @@ -170,6 +180,8 @@ Slash commands are convenience syntax only. Always enforce the same gates, journ 5. Load exactly one step file from the selected workflow's `steps//` step map. 6. Load a template only when that step produces or updates the matching Markdown artifact. +When a loaded step produces a Markdown artifact, apply the Draft Artifact Gate Policy: save or update the reviewable draft, keep the step `pending`, request explicit approval, and advance only after the journal step becomes `complete`. + For `/sldd run step `, stop before loading a completed step and ask whether to: 1. Run it again only. diff --git a/skills/sldd/steps/feature/00-navigation.md b/skills/sldd/steps/feature/00-navigation.md index 9789fc5..da17a17 100644 --- a/skills/sldd/steps/feature/00-navigation.md +++ b/skills/sldd/steps/feature/00-navigation.md @@ -25,7 +25,7 @@ Expected new-workflow artifacts: - `05-implementation-green` completion in `_spec-journal.json` with `evidence: "green_confirmed"` - `06-verification-and-feedback-report.md` -Approved numbered artifacts take precedence over `00-exploration-summary.md`. +Approved numbered artifacts take precedence over `00-exploration-summary.md`. A numbered Markdown artifact may exist as a pending draft; only the journal step `status: "complete"` makes it approved for routing. ## Start/Resume Flow @@ -82,7 +82,7 @@ When the command is `/sldd run step `, `/sldd run step is already complete. After the user chooses: 1. For option 1, run the step only after explicit confirmation. Do not automatically invalidate later completed steps. If the target step artifact, files, or journal entry changes, add a journal-only note: `Step was run again without downstream invalidation by explicit user choice.` -2. For option 2, run the step only after explicit confirmation. After the target step completes through its normal approval or confirmation flow, mark later completed steps in gate order as `requires_rerun`. +2. For option 2, run the step only after explicit confirmation. After the target step completes through its normal draft and approval or confirmation flow, mark later completed steps in gate order as `requires_rerun`. 3. For each invalidated later step, set `reason` to `Step was run again; this later step must be reviewed again.` 4. When invalidating Step 04 or Step 05, clear `evidence`; keep any existing `artifact` link as a historical reference. 5. For option 3, do not load the step, write artifacts, run commands, or update the journal. diff --git a/skills/sldd/steps/feature/01-product-intent.md b/skills/sldd/steps/feature/01-product-intent.md index 8aae426..e78e08c 100644 --- a/skills/sldd/steps/feature/01-product-intent.md +++ b/skills/sldd/steps/feature/01-product-intent.md @@ -23,26 +23,36 @@ For a child workflow scaffolded from a workflow-set, use the existing Step 01 dr If any predecessor is missing or incomplete, Step 01 may be drafted, saved, reviewed, or revised, but it must remain `pending` with a `reason` explaining the predecessor gate. Do not route to Step 02+. -Wait for approval. +Save the draft for review, keep the step pending, then wait for explicit approval. ## Approval Protocol -- Save or update artifacts only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. +- Save or update the Step 01 artifact as a reviewable draft before gate approval. +- Draft persistence must keep `01-product-intent` as `pending` in `_spec-journal.json`, preserve the artifact link, and set `reason` to `draft pending explicit approval` or a more specific blocking reason. +- The existence of `01-product-intent-specification.md` does not satisfy the Step 01 gate. +- On rejection, requested changes, hold, or ambiguous approval, update the draft when needed, keep the step pending, and do not route to Step 02+. +- Only explicit approval of the current draft may mark Step 01 complete, and predecessor gates may still keep it pending. - If writes are unavailable, stop and report the limitation. -## Save Flow After Approval +## Draft Save Flow 1. Save only Step 01 content to the resolved workflow directory as `01-product-intent-specification.md`; for new workflows, this is `.sldd/specs//01-product-intent-specification.md`. +2. Create or update journal-only `_spec-journal.json` with required top-level fields (`schema_version`, `name`, `workflow: "sldd"`, `kind: "feature"`) when needed. +3. Set `steps["01-product-intent"].status: "pending"`, preserve the artifact link, and set `reason` to `draft pending explicit approval` unless a predecessor gate requires a more specific reason. +4. Ask for explicit approval, revision requests, or hold. + +## Gate Approval Flow + +1. On explicit approval of the current draft, verify predecessor gates again. 2. If `relationships.predecessors` exists and any predecessor is missing or incomplete, keep `01-product-intent` as `pending`, preserve the artifact link, set `reason` to the predecessor-gate explanation, and route to the incomplete predecessor instead of continuing. 3. Otherwise, mark `01-product-intent` as `complete` in journal-only `_spec-journal.json` with the artifact link. 4. Ask whether to continue to the next step or hold. -For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. +For legacy or user-provided workflow paths, save the draft and update progress in the resolved directory instead. ## Response Format 1. Gate and resume check result -2. Draft summary with required Step 01 headings -3. Approval request -4. Continue/hold prompt +2. Saved draft summary with required Step 01 headings +3. Pending journal update and explicit approval request +4. Continue/hold prompt after approval, or revision/hold prompt while pending diff --git a/skills/sldd/steps/feature/02-high-level-design.md b/skills/sldd/steps/feature/02-high-level-design.md index 63b52cb..ece414f 100644 --- a/skills/sldd/steps/feature/02-high-level-design.md +++ b/skills/sldd/steps/feature/02-high-level-design.md @@ -22,25 +22,33 @@ If Step 99 was completed before Step 01, verify that its saved context still fit Trace approved Step 01 requirements, including formalized exploration outcomes, into architecture, responsibilities, data flow, security/observability, trade-offs, and high-level test scenarios. -Wait for approval. +Save the draft for review, keep the step pending, then wait for explicit approval. ## Approval Protocol -- Save or update artifacts only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. +- Save or update the Step 02 artifact as a reviewable draft before gate approval. +- Draft persistence must keep `02-high-level-design` as `pending` in `_spec-journal.json`, preserve the artifact link, and set `reason` to `draft pending explicit approval` or an equivalent review reason. +- The existence of `02-high-level-technical-design.md` does not satisfy the Step 02 gate. +- On rejection, requested changes, hold, or ambiguous approval, update the draft when needed, keep the step pending, and do not route to Step 03+. +- Only explicit approval of the current draft may mark Step 02 complete. - If writes are unavailable, stop and report the limitation. -## Save Flow After Approval +## Draft Save Flow 1. Save only Step 02 content to the resolved workflow directory as `02-high-level-technical-design.md`; for new workflows, this is `.sldd/specs//02-high-level-technical-design.md`. -2. Mark `02-high-level-design` as `complete` in journal-only `_spec-journal.json` with the artifact link. -3. Ask whether to continue to the next step or hold. +2. Update journal-only `_spec-journal.json` with `steps["02-high-level-design"].status: "pending"`, the artifact link, and `reason: "draft pending explicit approval"`. +3. Ask for explicit approval, revision requests, or hold. -For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. +## Gate Approval Flow + +1. On explicit approval of the current draft, mark `02-high-level-design` as `complete` in journal-only `_spec-journal.json` with the artifact link. +2. Ask whether to continue to the next step or hold. + +For legacy or user-provided workflow paths, save the draft and update progress in the resolved directory instead. ## Response Format 1. Gate and resume check result -2. Draft summary with required Step 02 headings -3. Approval request -4. Continue/hold prompt +2. Saved draft summary with required Step 02 headings +3. Pending journal update and explicit approval request +4. Continue/hold prompt after approval, or revision/hold prompt while pending diff --git a/skills/sldd/steps/feature/03-low-level-design.md b/skills/sldd/steps/feature/03-low-level-design.md index 7b9067f..6c45a52 100644 --- a/skills/sldd/steps/feature/03-low-level-design.md +++ b/skills/sldd/steps/feature/03-low-level-design.md @@ -43,25 +43,33 @@ The draft must include a dedicated `Mandatory Architecture Decisions` section. F Classify each decision as `mandatory`, `optional`, `deferred`, or `prohibited`. Decisions classified as `mandatory` are Step 05 blockers: Step 05 must not mark `green_confirmed` if any mandatory decision is absent, substituted, or implemented with an unapproved fallback. Decisions classified as `prohibited` must not appear in Step 05 production code unless Step 03 is rerun and explicitly changes that classification. -Wait for approval. +Save the draft for review, keep the step pending, then wait for explicit approval. ## Approval Protocol -- Save or update artifacts only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. +- Save or update the Step 03 artifact as a reviewable draft before gate approval. +- Draft persistence must keep `03-low-level-design` as `pending` in `_spec-journal.json`, preserve the artifact link, and set `reason` to `draft pending explicit approval` or an equivalent review reason. +- The existence of `03-low-level-design-and-version-policy.md` does not satisfy the Step 03 gate. +- On rejection, requested changes, hold, or ambiguous approval, update the draft when needed, keep the step pending, and do not route to Step 04+. +- Only explicit approval of the current draft may mark Step 03 complete. - If writes are unavailable, stop and report the limitation. -## Save Flow After Approval +## Draft Save Flow 1. Save only Step 03 content to the resolved workflow directory as `03-low-level-design-and-version-policy.md`; for new workflows, this is `.sldd/specs//03-low-level-design-and-version-policy.md`. -2. Mark `03-low-level-design` as `complete` in journal-only `_spec-journal.json` with the artifact link. -3. Ask whether to continue to the next step or hold. +2. Update journal-only `_spec-journal.json` with `steps["03-low-level-design"].status: "pending"`, the artifact link, and `reason: "draft pending explicit approval"`. +3. Ask for explicit approval, revision requests, or hold. -For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. +## Gate Approval Flow + +1. On explicit approval of the current draft, mark `03-low-level-design` as `complete` in journal-only `_spec-journal.json` with the artifact link. +2. Ask whether to continue to the next step or hold. + +For legacy or user-provided workflow paths, save the draft and update progress in the resolved directory instead. ## Response Format 1. Gate and resume check result -2. Draft summary with required Step 03 headings -3. Approval request -4. Continue/hold prompt +2. Saved draft summary with required Step 03 headings +3. Pending journal update and explicit approval request +4. Continue/hold prompt after approval, or revision/hold prompt while pending diff --git a/skills/sldd/steps/feature/06-verification.md b/skills/sldd/steps/feature/06-verification.md index a1a7acb..13e395a 100644 --- a/skills/sldd/steps/feature/06-verification.md +++ b/skills/sldd/steps/feature/06-verification.md @@ -29,25 +29,33 @@ The Step 06 verification report must include an `Architecture Compliance Matrix` A `violated` mandatory decision requires a No-Go decision. An `environment-blocked` mandatory decision may still allow Go only when the approved mechanism is implemented in production code, the blockage is limited to local verification infrastructure, no unapproved fallback was introduced, and remediation steps are documented. -Wait for approval. +Save the draft report for review, keep the step pending, then wait for explicit approval. ## Approval Protocol -- Save or update artifacts only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. +- Save or update the Step 06 report as a reviewable draft before gate approval. +- Draft persistence must keep `06-verification` as `pending` in `_spec-journal.json`, preserve the artifact link, and set `reason` to `draft pending explicit approval` or an equivalent review reason. +- The existence of `06-verification-and-feedback-report.md` does not complete the workflow. +- On rejection, requested changes, hold, or ambiguous approval, update the draft report when needed, keep the step pending, and do not mark the feature workflow complete. +- Only explicit approval of the current draft report may mark Step 06 complete. - If writes are unavailable, stop and report the limitation. -## Save Flow After Approval +## Draft Save Flow 1. Save only Step 06 report content to the resolved workflow directory as `06-verification-and-feedback-report.md`; for new workflows, this is `.sldd/specs//06-verification-and-feedback-report.md`. -2. Mark `06-verification` as `complete` in journal-only `_spec-journal.json` with the artifact link. -3. Ask whether to continue to the next step or hold. +2. Update journal-only `_spec-journal.json` with `steps["06-verification"].status: "pending"`, the artifact link, and `reason: "draft pending explicit approval"`. +3. Ask for explicit approval, revision requests, or hold. -For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. +## Gate Approval Flow + +1. On explicit approval of the current draft report, mark `06-verification` as `complete` in journal-only `_spec-journal.json` with the artifact link. +2. State that the feature workflow is complete only after this journal update. + +For legacy or user-provided workflow paths, save the draft and update progress in the resolved directory instead. ## Response Format 1. Gate and resume check result -2. Draft summary with required Step 06 headings -3. Approval request -4. Continue/hold prompt +2. Saved draft summary with required Step 06 headings +3. Pending journal update and explicit approval request +4. Workflow completion notice after approval, or revision/hold prompt while pending diff --git a/skills/sldd/steps/feature/99-codebase-context.md b/skills/sldd/steps/feature/99-codebase-context.md index bcc014b..c8f31bb 100644 --- a/skills/sldd/steps/feature/99-codebase-context.md +++ b/skills/sldd/steps/feature/99-codebase-context.md @@ -9,8 +9,8 @@ Capture and approve existing-codebase context for brownfield exploration and saf - Required before Step 02 for existing codebases. - May be run during Step 88 exploration when codebase understanding is needed to clarify scope, constraints, risks, or alternatives. - Optional for greenfield projects. -- Do not mark Step 99 complete without explicit approval and a saved `existing-codebase-understanding.md` artifact. -- Conversational or unsaved Step 99 context is non-gating context only; it does not satisfy Step 02+ brownfield prerequisites. +- Do not mark Step 99 complete without explicit approval of the current `existing-codebase-understanding.md` draft and a saved artifact link. +- Conversational, unsaved, or pending-draft Step 99 context is non-gating context only; it does not satisfy Step 02+ brownfield prerequisites. - If resuming later, re-evaluate the current codebase before relying on any previous Step 99 summary. - Reuse a previous Step 99 only if it still reflects the current codebase and approved Step 01 scope; update or rerun it if stale, incomplete, or scoped to a rejected exploration direction. - Reject inconsistent journal states where Step 02+ is complete while Step 99 is required and incomplete. @@ -20,28 +20,36 @@ Capture and approve existing-codebase context for brownfield exploration and saf Load `templates/existing-codebase-understanding.md` before drafting the artifact. -Wait for approval. +Save the draft for review, keep the step pending, then wait for explicit approval. ## Approval Protocol -- Save the artifact and mark Step 99 complete in `_spec-journal.json` only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. +- Save or update `existing-codebase-understanding.md` as a reviewable draft before gate approval. +- Draft persistence must keep `99-codebase-context` as `pending` in `_spec-journal.json`, preserve the artifact link, and set `reason` to `draft pending explicit approval` or a more specific blocking reason. +- The existence of `existing-codebase-understanding.md` does not satisfy the Step 99 or Step 02+ brownfield gate. +- On rejection, requested changes, hold, or ambiguous approval, update the draft when needed, keep Step 99 pending, and do not route to Step 02+. +- Only explicit approval of the current draft may mark Step 99 complete, and predecessor gates may still keep it pending. - If writes are unavailable, stop and report the limitation. -## Save Flow After Approval +## Draft Save Flow -1. Confirm that approval includes saving `existing-codebase-understanding.md` in the resolved workflow directory. -2. If persistence is approved, save `existing-codebase-understanding.md`. -3. If `relationships.predecessors` exists and any predecessor is missing or incomplete, keep Step 99 as `pending`, preserve the artifact link, set `reason` to the predecessor-gate explanation, and route to the incomplete predecessor instead of Step 02+. -4. Otherwise, mark Step 99 in journal-only `_spec-journal.json` with `status: "complete"` and the saved artifact link. -5. If persistence is not approved, do not save, do not mark Step 99 complete, and do not route to Step 02+; state that Step 99 remains incomplete until the artifact is saved and approved. -6. Ask whether to continue to the next step or hold. +1. Save only Step 99 context content to the resolved workflow directory as `existing-codebase-understanding.md`. +2. Create or update journal-only `_spec-journal.json` with required top-level fields when Step 99 is persisted before the journal exists. +3. Set `steps["99-codebase-context"].status: "pending"`, preserve the artifact link, and set `reason` to `draft pending explicit approval` unless a predecessor gate requires a more specific reason. +4. Ask for explicit approval, revision requests, or hold. -For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. +## Gate Approval Flow + +1. On explicit approval of the current draft, verify predecessor gates and current codebase relevance again. +2. If `relationships.predecessors` exists and any predecessor is missing or incomplete, keep Step 99 as `pending`, preserve the artifact link, set `reason` to the predecessor-gate explanation, and route to the incomplete predecessor instead of Step 02+. +3. Otherwise, mark Step 99 in journal-only `_spec-journal.json` with `status: "complete"` and the saved artifact link. +4. Ask whether to continue to the next step or hold. + +For legacy or user-provided workflow paths, save the draft and update progress in the resolved directory instead. ## Response Format 1. Gate and resume check result -2. Draft summary with required Step 99 headings -3. Persistence requirement for Step 99 completion -4. Approval request and continue/hold prompt +2. Saved draft summary with required Step 99 headings +3. Pending journal update and explicit approval requirement for Step 99 completion +4. Continue/hold prompt after approval, or revision/hold prompt while pending diff --git a/skills/sldd/steps/workflow-set/01-workflow-set-plan.md b/skills/sldd/steps/workflow-set/01-workflow-set-plan.md index ee557d6..d530bb4 100644 --- a/skills/sldd/steps/workflow-set/01-workflow-set-plan.md +++ b/skills/sldd/steps/workflow-set/01-workflow-set-plan.md @@ -6,8 +6,8 @@ Create or revise the parent workflow-set plan for a large idea that should be de ## Gate + Resume Checks -- Require explicit approval before creating or updating workflow-set files. -- If no parent journal exists, allow this step to draft a new workflow-set plan and create the parent journal only after explicit user approval. +- Allow this step to save or update a reviewable workflow-set plan draft before gate approval. +- If no parent journal exists, save the draft artifact only; do not create `_spec-journal.json` until the current plan draft is explicitly approved. - If a parent journal exists, require `name` and `kind: "workflow-set"`. - If an existing journal has no `name` or `kind`, stop and report it as invalid. - If an existing journal has top-level `feature`, stop and report it as invalid. @@ -22,43 +22,59 @@ Load `templates/01-workflow-set-plan.md` before drafting the artifact. The plan must include the large idea, source inputs, decomposition rationale, proposed child workflows, child names, titles, kinds, scopes, predecessor relationships by name, all-or-nothing scaffold policy, and approval status. -## Plan Materialization Modes +## Draft Materialization -Ask how to handle the plan: +Save or update the plan as a reviewable draft unless the user explicitly requests no file writes. Draft materialization creates review state only: -1. Write it and mark it complete. -2. Write it as a draft and wait for review. -3. Do not write files yet. +1. Write or update `01-workflow-set-plan.md`. +2. If a valid parent journal already exists, update it with `01-workflow-set-plan` still `pending`. +3. If no parent journal exists, leave `_spec-journal.json` absent until explicit plan approval. +4. Preserve proposed child workflows in the draft artifact; persist them to `workflowSet.children` only when a valid parent journal exists or when explicit plan approval creates the parent journal. +5. Ask for explicit plan approval, revisions, scaffold approval after plan completion, or hold. -Writing or completing the plan does not approve child scaffolding unless the user explicitly approves scaffold. Scaffold approval never substitutes for completing the plan; Step 02 may run only after `01-workflow-set-plan` is complete. +Writing the draft does not approve the plan, does not create a new parent journal, and does not approve child scaffolding. Scaffold approval never substitutes for completing the plan; Step 02 may run only after `01-workflow-set-plan` is complete and scaffold approval is explicit. ## Approval Protocol -- Save or update artifacts only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. -- Do not infer approval to scaffold children from approval to write or complete the plan. -- If the user approves scaffold while the plan is still pending, ask whether to mark the plan complete first and keep Step 02 blocked until that completion is approved and saved. +- Save or update `01-workflow-set-plan.md` as a reviewable draft before gate approval. +- When a valid parent journal exists, draft persistence must keep `01-workflow-set-plan` as `pending` in `_spec-journal.json`, preserve the artifact link, and set `reason` to `draft pending explicit approval` or an equivalent review reason. +- When no parent journal exists, draft persistence must not create `_spec-journal.json`; approval of the current draft is the trigger for parent journal creation. +- The existence of `01-workflow-set-plan.md` does not satisfy the workflow-set plan gate. +- On rejection, requested changes, hold, or ambiguous approval, update the draft when needed, keep the plan pending, and do not route to Step 02. +- Only explicit approval of the current draft may mark the plan complete. +- Do not infer approval to scaffold children from approval to draft or complete the plan. +- If the user approves scaffold while the plan is still pending, ask whether to approve the current plan draft first and keep Step 02 blocked until that completion is saved. - If writes are unavailable, stop and report the limitation. -## Save Flow After Approval +## Draft Save Flow 1. Create or update `.sldd/specs//01-workflow-set-plan.md`. -2. Create or update `_spec-journal.json` with `name` and `kind: "workflow-set"`. -3. When creating a new parent journal, initialize it with: +2. If a valid parent journal exists, keep `01-workflow-set-plan` pending, preserve the artifact link, update `workflowSet.children` from the draft, and set `reason` to `draft pending explicit approval`. +3. If no parent journal exists, do not create `_spec-journal.json` during draft save; report the draft path and state that the parent journal will be created only after explicit plan approval. +4. For explicit no-write mode, do not create or update files. +5. Ask whether to approve the current plan draft, revise it, approve scaffold after plan completion, or hold. + +## Gate Approval Flow + +1. On explicit approval of the current plan draft, create or update `_spec-journal.json` with `name`, `workflow: "sldd"`, and `kind: "workflow-set"`. +2. When creating a new parent journal, initialize it with: + - `schema_version: 1` - `name: ""` + - `workflow: "sldd"` - `kind: "workflow-set"` - - `steps["01-workflow-set-plan"]` - - `steps["02-scaffold-children"]` - - `steps["03-verify-workflow-set"]` - - `workflowSet.children` from the proposed plan, with scaffold state `proposed` -4. For write-complete mode, mark `01-workflow-set-plan` complete and keep `02-scaffold-children` pending. -5. For write-draft mode, keep `01-workflow-set-plan` pending. -6. For no-write mode, do not create or update files. -7. Ask whether to continue, revise, approve scaffold, or hold. + - `steps["01-workflow-set-plan"].status: "complete"` + - `steps["01-workflow-set-plan"].artifact: "01-workflow-set-plan.md"` + - `steps["02-scaffold-children"].status: "pending"` + - `steps["03-verify-workflow-set"].status: "pending"` + - `workflowSet.children` from the approved plan, with scaffold state `proposed` +3. For existing parent journals, mark `01-workflow-set-plan` complete with the artifact link and update `workflowSet.children` from the approved plan. +4. Keep `02-scaffold-children` pending. +5. Do not create child workflows in this step. +6. Ask whether to continue to Step 02, separately approve scaffold, revise, or hold. ## Response Format 1. Gate and resume check result -2. Draft summary with required workflow-set plan headings -3. Materialization mode prompt -4. Approval request and continue/hold prompt +2. Saved draft summary with required workflow-set plan headings +3. Pending journal update and explicit plan approval request +4. Separate scaffold approval reminder and continue/revise/hold prompt diff --git a/skills/sldd/workflows/feature.md b/skills/sldd/workflows/feature.md index 2488f95..4baf32d 100644 --- a/skills/sldd/workflows/feature.md +++ b/skills/sldd/workflows/feature.md @@ -16,7 +16,7 @@ The formal feature gate order is: 01-product-intent -> 99-codebase-context -> 02-high-level-design -> 03-low-level-design -> 04-tests-red -> 05-implementation-green -> 06-verification ``` -Step 99 is required before Step 02 for existing codebases. It may run during Step 88 when brownfield context is needed. Step 99 completion requires an approved and saved `existing-codebase-understanding.md` artifact. +Step 99 is required before Step 02 for existing codebases. It may run during Step 88 when brownfield context is needed. Step 99 may save `existing-codebase-understanding.md` as a pending draft, but completion requires explicit approval of the current draft, current codebase relevance, and `steps["99-codebase-context"].status == "complete"`. ## Step Files @@ -50,6 +50,8 @@ Load only the template needed by the selected step: ## Gate Rules - No implementation prompts or code changes before Step 01, Step 02, and Step 03 are approved. +- For Markdown-producing steps, save or update the reviewable artifact draft while keeping the step `pending`; artifact existence never satisfies the gate. +- Route to the next formal step only when the current gate step is `complete` in `_spec-journal.json`. - For existing codebases, Step 99 must be complete and current before Step 02. - For any workflow with `relationships.predecessors`, every predecessor journal must exist and have Step 06 complete before Step 01 may be marked complete or Step 02+ may be loaded. - If any predecessor is missing or incomplete, keep Step 01 and any drafted Step 99 context pending, preserve artifact links as drafts, record the predecessor-gate reason, and route to the predecessor instead of advancing. @@ -72,7 +74,7 @@ This kind of workflow is complete when `steps["06-verification"].status == "comp 3. Require existing `_spec-journal.json` files to include `name` and `kind: "feature"`; journals without `name` or `kind` are invalid. 4. Reject journals that use top-level `feature` as the workflow name field. 5. Reject `kind: "feature"` journals that include top-level `workflowSet`. -6. Validate that referenced Markdown artifacts exist. +6. Validate that referenced Markdown artifacts exist, but do not treat a referenced artifact as gate completion unless the owning step is `complete`. 7. Validate predecessor completion when `relationships.predecessors` exists. 8. Detect out-of-order completions or missing prerequisites. 9. For Step 99, validate freshness and relevance before reuse. @@ -89,7 +91,7 @@ If the target step is already `complete`, stop before loading the step and ask t 2. Run it again and mark later completed steps as `requires_rerun`. 3. Do nothing. -For option 1, run the step only after explicit confirmation and record a journal-only note if the target step changes without downstream invalidation. For option 2, after the target step completes through its normal approval or confirmation flow, mark later completed steps in gate order as `requires_rerun`. +For option 1, run the step only after explicit confirmation and record a journal-only note if the target step changes without downstream invalidation. For option 2, after the target step completes through its normal draft and approval or confirmation flow, mark later completed steps in gate order as `requires_rerun`. When invalidating Step 04 or Step 05, clear `evidence`; keep any existing `artifact` link as a historical reference. diff --git a/skills/sldd/workflows/workflow-set.md b/skills/sldd/workflows/workflow-set.md index 5703d71..c1e58b7 100644 --- a/skills/sldd/workflows/workflow-set.md +++ b/skills/sldd/workflows/workflow-set.md @@ -33,8 +33,9 @@ Load only the template needed by the selected step: ## Gate Rules -- Workflow-set planning requires explicit approval. -- A new workflow-set parent journal may be created only after explicit approval. +- Workflow-set plan drafts may be saved as reviewable Markdown artifacts before approval; artifact existence alone never satisfies the gate. +- When a parent journal already exists, draft updates keep `01-workflow-set-plan` pending until explicit approval marks it complete. +- A new workflow-set parent journal may be created only after explicit approval of the current Step 01 plan draft; draft persistence for a new parent must not create `_spec-journal.json`. - Existing journals without `name` or `kind` are invalid and must not be routed automatically. - Existing journals with `kind: "feature"` stop the workflow-set path and require a different workflow-set name or explicit user direction. - Child scaffolding requires `01-workflow-set-plan` complete and separate explicit scaffold approval. @@ -63,7 +64,7 @@ This kind of workflow is complete when `steps["03-verify-workflow-set"].status = 4. Reject journals that use top-level `feature` as the workflow name field. 5. Require top-level `workflowSet` on workflow-set parent journals. 6. If the user explicitly approved creating a new workflow-set and no parent journal exists, route to `01-workflow-set-plan` instead of treating the missing journal as a resume failure. -7. Validate that referenced Markdown artifacts exist. +7. Validate that referenced Markdown artifacts exist, but do not treat a referenced artifact as gate completion unless the owning step is `complete`. 8. Resume pending parent workflow-set steps first. 9. If the parent is complete, compute a read-only child overview by reading child journals. 10. Do not write child progress to the parent journal. @@ -80,7 +81,7 @@ If the target workflow-set step is already `complete`, stop before loading the s 2. Run it again and mark later completed workflow-set steps as `requires_rerun`. 3. Do nothing. -For option 1, run the step only after explicit confirmation and record a journal-only note if the target step changes without downstream invalidation. For option 2, after the target step completes through its normal approval or confirmation flow, mark later completed workflow-set steps as `requires_rerun`. +For option 1, run the step only after explicit confirmation and record a journal-only note if the target step changes without downstream invalidation. For option 2, after the target step completes through its normal draft and approval or confirmation flow, mark later completed workflow-set steps as `requires_rerun`. ## Response Format