From 149cafa39c0687f4edf8d536494376208167df99 Mon Sep 17 00:00:00 2001 From: Ivan Ivic Date: Thu, 1 Oct 2026 14:08:11 +0200 Subject: [PATCH 1/8] config: Clarify workflow execution and handover boundaries Refine generated workflow instructions to keep intermediate state private and prevent unintended context or repository mutations. Co-authored-by: SCE --- config/pkl/base/workflow-content.pkl | 6 +++--- config/pkl/base/workflow-handover.pkl | 21 ++++----------------- 2 files changed, 7 insertions(+), 20 deletions(-) diff --git a/config/pkl/base/workflow-content.pkl b/config/pkl/base/workflow-content.pkl index cff15cbb6..201dde0cc 100644 --- a/config/pkl/base/workflow-content.pkl +++ b/config/pkl/base/workflow-content.pkl @@ -217,12 +217,12 @@ hidden executionContract = (variant: ExecutionContractVariant) -> Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. - Keep internal phase results private and continue immediately until a defined wait or stop. + Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. - Render user-visible output only from the named workflow layouts or phase reports. + Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing - phase order, gates, waits, writes, validation, stops, or terminal output. + workflow order, gates, waits, writes, validation, stops, or terminal output. """ + "\n" + if (variant == "task-decision") """ Do not invoke another SCE skill, package, or workflow command except `sce-decision`, diff --git a/config/pkl/base/workflow-handover.pkl b/config/pkl/base/workflow-handover.pkl index b11b9e001..fc874554e 100644 --- a/config/pkl/base/workflow-handover.pkl +++ b/config/pkl/base/workflow-handover.pkl @@ -167,14 +167,15 @@ local renderSkillBody = (mode: model.WorkflowRenderMode, argumentsReference: Str #### 4. Confirm the context root When `context/` does not exist, there is no durable location to write to. + Do not create it; `sce setup --bootstrap-context` owns context bootstrap. Render the **Writer blocked** layout with `sce setup --bootstrap-context` as the required action, and stop without writing a file. #### 5. Write exactly one file - Write the composed document to the path resolved in step 2. Before reporting - success, validate the written file against the template's **Completeness - contract**. + Write only the composed handover document to the path resolved in step 2. + Do not change plan or task state or edit any other file. Before reporting + success, validate the written file against the template's **Completeness contract**. #### 6. Report @@ -214,20 +215,6 @@ local renderSkillBody = (mode: model.WorkflowRenderMode, argumentsReference: Str Loading is read-only: do not edit any file, mark a plan task complete, change repository state, or begin the recommended next step. Presenting the loaded guidance is the entire loader contract. - - ## Rules - - - Handle at most one handover per invocation, in exactly one mode. - - Writer mode never overwrites an existing handover file. - - Writer mode never marks a plan task complete or edits any file outside the - one handover document it writes. - - Loader mode never edits a file, writes a new file, or changes plan or task - state. - - Never invoke another SCE skill, sibling SCE package, or SCE workflow command. - - Never treat a file outside `context/handovers/`, or a non-Markdown file, as a - loadable handover. - - Never create the `context/` root; `sce setup --bootstrap-context` owns that. - - Do not begin, plan, or automate the loaded handover's recommended next step. """ local structuredCommand = new model.StructuredWorkflowDocument { From 6967105776fc7f4a53da6f254ed7dca86f8ff3f7 Mon Sep 17 00:00:00 2001 From: Ivan Ivic Date: Thu, 1 Oct 2026 14:29:56 +0200 Subject: [PATCH 2/8] workflow: Remove context-file guidance gating from commit flow Keep commit analysis focused on staged-diff interpretation without a separate context-only classification. Update the canonical workflow source and related context documentation to describe the reduced flow consistently. Co-authored-by: SCE --- config/pkl/base/workflow-commit.pkl | 45 ++++++++++----------------- context/glossary.md | 2 +- context/sce/atomic-commit-workflow.md | 14 ++++----- 3 files changed, 24 insertions(+), 37 deletions(-) diff --git a/config/pkl/base/workflow-commit.pkl b/config/pkl/base/workflow-commit.pkl index 3daf6e6c6..27c098049 100644 --- a/config/pkl/base/workflow-commit.pkl +++ b/config/pkl/base/workflow-commit.pkl @@ -157,7 +157,6 @@ local renderCommandBody = (mode: model.WorkflowRenderMode) -> """ - Reading and analyzing the staged diff. - Deciding whether staged changes form one coherent unit or several. - - Classifying staged scope and applying context-file guidance gating. - Writing every commit message subject and body. - Applying the plan-citation body rule. @@ -301,8 +300,8 @@ local renderAtomicCommitSkillBody = (mode: model.WorkflowRenderMode) -> """ \(atomicCommitHeadings.stepHeading.apply(mode, 4, "Write each message")) - Follow \(commitMessageStyle.render.apply(mode)) for the subject pattern, the body - rules, issue references, the plan-citation rule, and the anti-patterns. + Follow \(commitMessageStyle.render.apply(mode)) for the subject pattern, body + rules, and issue references. \(atomicCommitHeadings.stepHeading.apply(mode, 5, "Apply the plan-citation rule")) @@ -317,18 +316,7 @@ local renderAtomicCommitSkillBody = (mode: model.WorkflowRenderMode) -> """ - In `bypass` mode, infer the citation when the diff supports it, and otherwise omit it. Never stop, and never invent a slug or task ID. - \(atomicCommitHeadings.stepHeading.apply(mode, 6, "Apply context-file guidance gating")) - - This step applies in `regular` mode only. Skip it entirely in `bypass` mode; do - not classify staged scope there. - - Classify the staged diff: - - - Context-only (`context/**`): context-file-focused guidance is allowed. - - Mixed (`context/**` plus non-`context/**`): suppress default context-file - commit reminders and give guidance that reflects the full staged scope. - - \(atomicCommitHeadings.stepHeading.apply(mode, 7, "Propose split guidance")) + \(atomicCommitHeadings.stepHeading.apply(mode, 6, "Propose split guidance")) This step applies in `regular` mode only. @@ -339,7 +327,7 @@ local renderAtomicCommitSkillBody = (mode: model.WorkflowRenderMode) -> """ When the staged changes form one unit, return one message and no split guidance. Do not split coherent work to appear thorough. - \(atomicCommitHeadings.stepHeading.apply(mode, 8, "Validate the result")) + \(atomicCommitHeadings.stepHeading.apply(mode, 7, "Validate the result")) Confirm before returning that: @@ -348,6 +336,18 @@ local renderAtomicCommitSkillBody = (mode: model.WorkflowRenderMode) -> """ - No plan slug or task ID appears that the staged diff does not support. - The mode's own constraints hold. + \(atomicCommitHeadings.section.apply(mode, "Result contract")) + + Return exactly one internal result: + + - `blocked`: one or more issues, each carrying its problem, impact, and + required decision. + - `proposal`: regular mode only. Include one or more commits, each with its + complete message and covered files. Include split rationale only when more + than one commit is returned. + - `bypass_message`: bypass mode only. Include exactly one complete message and + the full staged file list. + \(atomicCommitHeadings.section.apply(mode, "Bypass execution handoff")) This subsection is the sole definition of the bypass execution sequence. This @@ -431,7 +431,7 @@ local renderCommitMessageStyle = (mode: model.WorkflowRenderMode) -> """ - Start with `scope: Subject` for most code changes. - Common scopes: `runtime`, `language`, `objects`, `tests`, `CI`, `README`. - Combined scopes are fine when needed (for example `language+runtime`). - - Use an imperative verb in the subject: `Fix`, `Add`, `Refactor`, `Remove`, `Implement`, `Update`, `Rewrite`, `Use`, `Allow`. + - Use an imperative verb in the subject. - Keep the subject specific and technical (name the subsystem and actual change). - Keep the subject to one line and do not end it with a period. - Add a body when the change is non-trivial. @@ -455,17 +455,6 @@ local renderCommitMessageStyle = (mode: model.WorkflowRenderMode) -> """ Fixes # (optional) ``` - ## Size-based defaults - - 1. Small fix: subject + 1 short reason line. - 2. Medium refactor: subject + short why + short what changed. - 3. Large architectural change: subject + context + bullets for major changes + impact/tradeoffs. - - ## Anti-patterns to avoid - - - Vague subjects like "misc updates" or "cleanup". - - Bodies that only repeat the subject without explaining why or impact. - - Overly playful tone in serious bug-fix or architectural change. """ local commitSkillBody = (argumentsReference: String, invocationExample: String) -> """ diff --git a/context/glossary.md b/context/glossary.md index 8f805072c..c30ef9ba9 100644 --- a/context/glossary.md +++ b/context/glossary.md @@ -32,7 +32,7 @@ - `baseline-relative task handoff`: The explicit `/next-task` execution result passed to task context synchronization. It contains the resolved plan and task identity, implementation-changed paths computed by comparing post-edit state with a pre-edit Git baseline, implementation summary, verification and done-check evidence, plan update, and context impact; unchanged pre-existing working-tree paths are excluded. Its persisted form is the same completed task record `/next-task` writes onto the task itself — `Completed`, `Files changed`, `Result`, `Verify` outcomes, and `Context impact`, identified only by plan path and task ID — with no separate synchronization-handoff structure, so a cross-session retry reads that record directly from the plan rather than depending on an out-of-band plan/task value supplied by the caller. - `workflow output reference`: The required `references/output.md` in every workflow skill package. It defines all and only that workflow's human-visible Markdown gates, reports, and terminal layouts. Phase-based packages also carry operational phase and persisted-document references, but those never own user-visible layouts. It is also the single statement of each layout: a `SKILL.md` branch that produces output cites the section it renders by heading rather than reproducing it. - `no-improvisation rule`: The agent-behavior policy stated in every generated workflow `SKILL.md`: the five core workflows render the shared `executionContract` from `workflow-content.pkl`, while brownfield retains its existing preamble. Its process half forbids inventing, skipping, reordering, or merging the canonical workflow's steps, gates, and stops; its output half limits user-visible output to the `references/output.md` layouts, forbidding invented layouts and any added preamble, commentary, summary, or extra section around them. It is prose instruction, not a machine-checked contract. See `context/architecture.md`. -- `atomic commit bypass mode`: The `/commit` mode selected when the exact first argument token is `oneshot` or `skip` (case-insensitive; the two aliases are behaviorally identical). It skips the staging-confirmation prompt and the context-file guidance gate, requires exactly one commit message covering all staged files with no split proposals, makes plan citations best-effort instead of blocking, and lets the command run exactly one `git commit`. Any other first token selects proposal-only regular mode. See `context/sce/atomic-commit-workflow.md`. +- `atomic commit bypass mode`: The `/commit` mode selected when the exact first argument token is `oneshot` or `skip` (case-insensitive; the two aliases are behaviorally identical). It skips the staging-confirmation prompt, requires exactly one commit message covering all staged files with no split proposals, makes plan citations best-effort instead of blocking, and lets the command run exactly one `git commit`. Any other first token selects proposal-only regular mode. See `context/sce/atomic-commit-workflow.md`. - `split commit references`: The generated `sce-commit/references/atomic-commit.md`, `references/commit-message-style.md`, and `references/output.md` documents. The atomic reference owns staged-diff procedure, internal result branching, and commit boundaries; the style reference owns commit-message wording; and the output reference owns human-visible layouts. No `commit-contract.yaml` artifact or YAML result-contract section is generated. - `canonical OpenCode plugin registration source`: Shared Pkl-authored plugin-registration definition in `config/pkl/base/opencode.pkl`, re-exported from `config/pkl/renderers/common.pkl` as the canonical plugin list/path JSON consumed by OpenCode renderers before they emit generated `opencode.json` manifests; the current entries, in order, are `sce-bash-policy`, `sce-agent-trace`, and `sce-mutation-scope` (list order is load-bearing — see `sce-mutation-scope plugin`). - `checkout identity`: Stable UUIDv7 identifier assigned to a cloned repository or linked Git worktree, stored in `/sce/checkout-id` (never committed) and resolved via `git rev-parse --git-dir`. The identity is created or reused by `sce setup` through `AgentTraceDbLifecycle::setup()` and also auto-created by hook runtime when `sce setup` has not been run. Checkout identity is now diagnostic metadata for repository-scoped Agent Trace storage; it does not select the active DB and is not stored on Agent Trace rows. Any pre-migration per-checkout DB files at `/sce/agent-trace-{checkout_id}.db` are never touched by SCE and are no longer inspectable via the CLI (the checkout-scoped DB surface was removed by the `retire-legacy-agent-trace-db` plan). See `context/cli/checkout-identity.md`. diff --git a/context/sce/atomic-commit-workflow.md b/context/sce/atomic-commit-workflow.md index 93822c6b0..d87af6c3e 100644 --- a/context/sce/atomic-commit-workflow.md +++ b/context/sce/atomic-commit-workflow.md @@ -80,9 +80,8 @@ output. On failure it reports the failure and stops — no retry, amend, additio staging, fallback commit, or fabricated hash. Either way, the command deletes the temp file after the commit attempt, including on failure, where practical. -Bypass mode relaxes three regular-mode rules: no split proposals, no -context-file guidance gating, and plan citations are best-effort rather than -blocking. +Bypass mode relaxes two regular-mode rules: no split proposals, and plan +citations are best-effort rather than blocking. ## Ownership boundary @@ -94,7 +93,6 @@ says: - Deciding whether staged changes form one coherent unit or several. - Choosing scope and writing every subject and body. - The plan-citation body rule. -- Staged-scope classification and context-file guidance gating. Each rule is stated once by its owner. The skill never commits and never asks about staging. @@ -127,12 +125,12 @@ reference describes the procedure and result branches, while the workflow keeps the statuses internal rather than serializing them between packages. No `commit-contract.yaml` artifact or YAML result-contract section is generated. -- `proposal` — regular mode, one or more messages and an optional split rationale. +- `proposal` — regular mode, one or more complete messages with their covered + files, plus split rationale when more than one commit is proposed. - `bypass_message` — bypass mode, exactly one message plus the full staged file list. -- `blocked` — messages cannot be written faithfully. Categories are - `no_staged_changes`, `plan_citation_ambiguity`, `unreadable_diff`, and - `contradictory_context`. +- `blocked` — messages cannot be written faithfully; each issue carries its + problem, impact, and required decision. Every target renders only the applicable layout from `references/output.md`. Every staged file still belongs to exactly one commit message. The analysis phase From 42cd9459fffb4726cdda09f32990cc8366944f2e Mon Sep 17 00:00:00 2001 From: Ivan Ivic Date: Thu, 1 Oct 2026 15:03:32 +0200 Subject: [PATCH 3/8] workflow: Refine next-task execution contract Remove duplicated implementation-gate requirements and clarify approach-detail and completion-validation wording in the next-task workflow. Co-authored-by: SCE --- config/pkl/base/workflow-next-task.pkl | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/config/pkl/base/workflow-next-task.pkl b/config/pkl/base/workflow-next-task.pkl index b2169b861..8f6725314 100644 --- a/config/pkl/base/workflow-next-task.pkl +++ b/config/pkl/base/workflow-next-task.pkl @@ -1394,9 +1394,6 @@ local EXECUTION_CONTRACT = """ local renderImplementationGate = (mode: model.WorkflowRenderMode) -> """ # Implementation gate - Always show this gate at the start of \(taskExecution.render.apply(mode)), before editing any - file. - The gate is user-facing prose. It is never serialized into a YAML result. This file is the only authority for the gate's content and order. @@ -1427,7 +1424,7 @@ local renderImplementationGate = (mode: model.WorkflowRenderMode) -> """ ## Approach - Describe the smallest coherent implementation approach in 2–5 steps. + Describe the smallest coherent implementation approach with enough detail for approval. ## Assumptions @@ -1806,7 +1803,7 @@ Set internal status `blocked` for every other non-successful outcome, including: Do not determine whether the plan is complete. The `/next-task` workflow owns that decision after context synchronization. -Before returning a `complete` result, verify that it satisfies the authoritative +A `complete` result must satisfy the authoritative handoff contract above. ## 2.9 Return the result @@ -1911,9 +1908,6 @@ Run the final validation: # Implementation gate -Always show this gate at the start of the **Task execution phase**, before editing any -file. - The gate is user-facing prose. It is never serialized into a YAML result. This file is the only authority for the gate's content and order. @@ -1944,7 +1938,7 @@ file is the only authority for the gate's content and order. ## Approach -Describe the smallest coherent implementation approach in 2–5 steps. +Describe the smallest coherent implementation approach with enough detail for approval. ## Assumptions From 357b3dba0bbaad295c083dc3a6ecc4a8285b9897 Mon Sep 17 00:00:00 2001 From: Ivan Ivic Date: Thu, 1 Oct 2026 15:07:33 +0200 Subject: [PATCH 4/8] workflow: Return validation reports unchanged Preserve blocked, failed, and validated report text while continuing the validated flow. Co-authored-by: SCE --- config/pkl/base/workflow-validate.pkl | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/config/pkl/base/workflow-validate.pkl b/config/pkl/base/workflow-validate.pkl index e8b938ee2..cfd4617ea 100644 --- a/config/pkl/base/workflow-validate.pkl +++ b/config/pkl/base/workflow-validate.pkl @@ -127,18 +127,12 @@ local renderCommandBody = (mode: model.WorkflowRenderMode) -> """ \(model.inlinePhaseBody.apply(validationSkillBody).render.apply(mode))\(validationResultHandoff.render.apply(mode)) - `blocked` -> Print the blocked Markdown report as returned. Do not rephrase it - into a different layout. Stop. + `blocked` -> Return the blocked Markdown report unchanged. Stop. - `failed` -> Print the failed Markdown report as returned. It is already a - session handoff: self-contained, actionable, and ending with - `/validate {plan-path}` after repairs. + `failed` -> Return the failed Markdown handoff unchanged. Stop. - Do not rewrite it into a shorter summary. Do not drop the retry command. Do not - add an alternate continuation that replaces `/validate`. Stop. - - `validated` -> Print the complete validated Markdown report as returned. - Continue to the next step. + `validated` -> Return the complete validated Markdown result, then continue to + the next step. ### 2. Report completion @@ -156,8 +150,6 @@ local renderCommandBody = (mode: model.WorkflowRenderMode) -> """ returns `blocked`, and this workflow stops. - On `failed`, print the handoff Markdown as returned and stop. Preserve the retry `/validate {plan-path}` instruction. - - Do not implement remaining plan tasks from this workflow unless the user - explicitly continues in-session after a failed handoff. - Do not create a Git commit or push changes. - Do not mark the plan archived or delete the plan. - Do not execute a follow-up `/next-task`, `/change-to-plan`, or `/validate` @@ -531,9 +523,6 @@ local renderValidationResult = (mode: model.WorkflowRenderMode) -> """ `/validate {plan path}` - Do not stop after the repair. The plan is not finished until `/validate` - returns `validated`. - --- ## Blocked report From 87919813334661b2030182832cd7fe7eadf22d9a Mon Sep 17 00:00:00 2001 From: Ivan Ivic Date: Thu, 1 Oct 2026 15:15:52 +0200 Subject: [PATCH 5/8] workflow: Update plan revision context handling Keep the loaded context brief for in-scope revisions and reload it only when the plan expands beyond that focus. Update generated workflow guidance and draft messaging to match the revised behavior. Co-authored-by: SCE --- config/pkl/base/workflow-change-to-plan.pkl | 66 ++++++++++----------- 1 file changed, 30 insertions(+), 36 deletions(-) diff --git a/config/pkl/base/workflow-change-to-plan.pkl b/config/pkl/base/workflow-change-to-plan.pkl index 7f6988ce5..80483fa22 100644 --- a/config/pkl/base/workflow-change-to-plan.pkl +++ b/config/pkl/base/workflow-change-to-plan.pkl @@ -106,9 +106,13 @@ Then stop and wait. Do not implement, and do not run the handoff yourself. ### 4. Revise the plan on request -When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the same `loaded_context_brief` from step 1. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the same `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. +When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the current `loaded_context_brief`. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the current `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. -Run the **Plan authoring phase** with the applicable continuation fields. The brief still holds; durable context did not change because the user disagreed with a task boundary. Do not reload it. +Reuse `loaded_context_brief` when the revision stays within the focus it covers. +If the revision materially expands the plan into an area the brief did not cover, +rerun the **Context load phase** for the expanded focus before running the +**Plan authoring phase**. Do not reload context for revisions already covered by +the brief. An answer that resolves a doubt removes that open question. An answer that does not resolve it leaves the question standing; do not drop it because the user replied to it. If the reply raises a new doubt, the revised plan carries a new open question. @@ -128,7 +132,6 @@ Stop. - Plan at most one change request per invocation. Revisions to the plan that request produced are part of the same invocation, not a second request. - Read each phase's reference before running that phase. -- Always tell the user the plan can be revised, and always name its assumptions as the first thing worth checking. - Do not gate the handoff on open questions listed in the plan summary. Blocking questions return `needs_clarification` before any plan is written. Offering revision is not the same as demanding it, and inventing doubts to justify a review gate is not allowed. - Do not suppress, soften, or answer an open question or clarification question on the user's behalf. - Do not defer the user's revision to a rerun of `/change-to-plan`, and do not defer it to the implementation phase. Revise the plan here. @@ -245,8 +248,22 @@ changeToPlanPlanAuthoring = """ Run this phase for step 2 of the workflow, and again for each revision in step 4. -Input: the change request, and the complete `loaded` brief from the context load -phase. Pass the brief verbatim; do not restate, summarize, or reinterpret it. +Inputs are one of: + +- Initial authoring: `change_request` and `loaded_context_brief`. +- Clarification continuation: `original_request`, `clarification_answers`, + and `loaded_context_brief`. +- Existing-plan revision: `plan_path`, `correction`, and + `loaded_context_brief`. + +Pass `loaded_context_brief` verbatim. + +For clarification continuation, preserve `original_request` and resolve it with +the supplied `clarification_answers`. + +For an existing-plan revision, read `plan_path` and interpret `correction` +against that plan. A terse correction is not ambiguous merely because it omits +scope and terminology already present in the plan. This phase owns the planning process: @@ -272,19 +289,6 @@ The context brief is the durable memory this plan starts from. Treat its `key_facts` as recorded current state, its `gaps` as areas with no durable context, and its `drift` as recorded context that no longer matches the code. -When no brief is supplied, load the context named by the change request before -authoring, and follow the selection discipline in *Inspect relevant context*. - -Answers the user gave to earlier clarification questions arrive as part of the -change request. Incorporate them into the plan. - -A revision of a plan authored earlier in the session also arrives as the change -request, and it is usually terse: a task boundary the user disagrees with, an -ordering they want changed, work they want added or dropped. Read it against the -existing plan, which supplies the scope, criteria, and terminology it omits. -Terseness is not ambiguity. Do not set internal status `needs_clarification` for -detail the plan already carries; ask only when the revision itself is genuinely -undecidable. ## 2.1 Resolve the plan target @@ -705,7 +709,7 @@ candidate plan paths and explain that naming one candidate resolves it. {total-tasks} {task|tasks} planned. -This plan is a draft. State a correction and it will be updated. +This plan is a draft. Check its assumptions first; state any correction and it will be updated. Next step: @@ -955,7 +959,7 @@ local readyContinuationLayout = model.semanticReference.apply( {total-tasks} tasks planned. - This plan is a draft. State a correction and it will be updated. + This plan is a draft. Check its assumptions first; state any correction and it will be updated. Next step: @@ -1078,9 +1082,13 @@ local renderCommandBody = (mode: model.WorkflowRenderMode) -> """ ### 4. Revise the plan on request - When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the same `loaded_context_brief` from step 1. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the same `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. + When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the current `loaded_context_brief`. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the current `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. - \(invoke.render.apply(mode)) \(planAuthoring.render.apply(mode)) with the applicable continuation fields. The brief still holds; durable context did not change because the user disagreed with a task boundary. Do not reload it. + Reuse `loaded_context_brief` when the revision stays within the focus it covers. + If the revision materially expands the plan into an area the brief did not cover, + rerun the **Context load phase** for the expanded focus before running the + **Plan authoring phase**. Do not reload context for revisions already covered by + the brief. An answer that resolves a doubt removes that open question. An answer that does not resolve it leaves the question standing; do not drop it because the user replied to it. If the reply raises a new doubt, the revised plan carries a new open question. @@ -1099,7 +1107,6 @@ local renderCommandBody = (mode: model.WorkflowRenderMode) -> """ ## Rules - Plan at most one change request per invocation. Revisions to the plan that request produced are part of the same invocation, not a second request. - - Always tell the user the plan can be revised, and always name its assumptions as the first thing worth checking. - Do not gate the handoff on open questions listed in the plan summary. Blocking questions return `needs_clarification` before any plan is written. Offering revision is not the same as demanding it, and inventing doubts to justify a review gate is not allowed. - Do not suppress, soften, or answer an open question or clarification question on the user's behalf. - Do not defer the user's revision to a rerun of `/change-to-plan`, and do not defer it to the implementation phase. Revise the plan here. @@ -1470,19 +1477,6 @@ local renderAuthoringSkillBody = (mode: model.WorkflowRenderMode) -> """ `key_facts` as recorded current state, its `gaps` as areas with no durable context, and its `drift` as recorded context that no longer matches the code. - When no brief is supplied, load the context named by the change request before - authoring, and follow the selection discipline in *Inspect relevant context*. - - Answers the user gave to earlier clarification questions arrive as part of the - change request. Incorporate them into the plan. - - A revision of a plan authored earlier in the session also arrives as the change - request, and it is usually terse: a task boundary the user disagrees with, an - ordering they want changed, work they want added or dropped. Read it against the - existing plan, which supplies the scope, criteria, and terminology it omits. - Terseness is not ambiguity. Do not \(returnLower.render.apply(mode)) `needs_clarification` for detail the - plan already carries; ask only when the revision itself is genuinely undecidable. - \(model.packageOnlyBlock.apply("## Workflow").render.apply(mode))\(planAuthoringHeadings.stepHeading.apply(mode, 1, "Resolve the plan target")) Determine whether the request targets a new plan or an existing plan in From edf0b043b260cd07febc58344b8019444e75cd59 Mon Sep 17 00:00:00 2001 From: Ivan Ivic Date: Thu, 1 Oct 2026 15:32:17 +0200 Subject: [PATCH 6/8] config: Update decision ADR reuse contract Clarify qualified decision handling, active ADR reuse, immutable-record rules, and deterministic result fields. Align generation-contract checks with the revised skill content. Co-authored-by: SCE --- config/pkl/base/decision-skill.pkl | 42 ++++++++++--------- .../renderers/generation-contract-check.pkl | 4 +- 2 files changed, 25 insertions(+), 21 deletions(-) diff --git a/config/pkl/base/decision-skill.pkl b/config/pkl/base/decision-skill.pkl index 2890eac29..f0c2ca9ab 100644 --- a/config/pkl/base/decision-skill.pkl +++ b/config/pkl/base/decision-skill.pkl @@ -5,7 +5,7 @@ import "workflow-content.pkl" as model /// user-facing command or prompt routes to this skill. local SKILL_SLUG = "sce-decision" -local SKILL_DESCRIPTION = "Write one immutable ADR for one decision already qualified by context synchronization" +local SKILL_DESCRIPTION = "Record one already-qualified decision as an immutable ADR, reusing an equivalent active ADR when present" local skillText = (extraFrontmatterLines: String) -> """ --- @@ -18,10 +18,11 @@ description: > ## Purpose -Write exactly one architecture decision record for one decision already qualified -by successful task context synchronization. Return a deterministic internal -result to the invoking synchronization phase. Do not render an independent -user-visible response. +Resolve exactly one architecture decision record for one decision already +qualified by successful task context synchronization. Reuse an equivalent active +ADR when one exists; otherwise write a new immutable ADR. Return a deterministic +internal result to the invoking synchronization phase. Do not render an +independent user-visible response. ## Input @@ -31,7 +32,7 @@ synchronization. It must identify: - One decision stated as a single durable choice. - Why it qualifies under the decision gate. - The implementation / task-verification evidence establishing the decision. -- The resolved plan path and relevant task IDs, when applicable. +- The resolved plan path, plus relevant task IDs when applicable. - Related current-state context and existing ADR paths. - An optional requested status. @@ -48,9 +49,9 @@ rerun that threshold here. Require the request to state why the caller qualified the decision and include supporting evidence. If the request explicitly represents a nonqualifying gate outcome, return `not_qualified` (or `skipped` when the caller deliberately skipped -the gate) without writing an ADR. If a claimed qualification is unsupported by -its supplied evidence, return `not_qualified`. Missing, contradictory, or -otherwise unsafe material input remains `blocked`. +the gate) without writing an ADR. For a qualified request, do not reassess the +qualification threshold. Missing or contradictory qualification evidence is +unsafe decision-writing input and returns `blocked`. `not_qualified` and `skipped` are non-blocking to the invoking synchronization phase. @@ -78,7 +79,8 @@ Read `context/decisions/` and the supplied related ADR paths before writing. - Reuse an existing ADR only when it records an equivalent decision and has an active status: `Proposed` or `Accepted`. Return its path without creating a duplicate. Never reuse a `Rejected`, `Deprecated`, or `Superseded` ADR. -- Existing ADRs are immutable regardless of status. Never edit an ADR whose status is `Accepted`; do not edit, overwrite, or silently change the status of any existing record. +- Existing ADRs are immutable regardless of status; never edit, overwrite, or + change the status of an existing record. - A correction, reversal, or any changed decision always creates a new dated ADR; it references and supersedes the prior record when applicable, rather than modifying that record. @@ -108,7 +110,7 @@ synchronization phase owns linking the new ADR from authoritative context. Confirm that exactly one ADR was created or one existing matching ADR was reused; the filename, status, sections, and references satisfy this contract; every -referenced repository path exists when practical to check; and no accepted ADR +referenced repository path exists when practical to check; and no existing ADR was modified. ### 6. Return the result @@ -116,11 +118,11 @@ was modified. Return exactly one internal result: - `written`: include `status`, `adr_path`, `decision`, `decision_status`, - `created` (`true` for a new ADR and `false` for reuse), `supersedes`, and - concise verification evidence. -- `not_qualified` or `skipped`: include `status`, the reason the decision gate - did not produce an ADR, and concise supporting evidence. These results are - non-blocking; the invoking synchronization phase continues normally. + `created` (`true` for a new ADR and `false` for reuse), `supersedes` (the prior + ADR path or `null`), and `verification`. +- `not_qualified` or `skipped`: include `status`, `reason`, and `evidence`. + These results are non-blocking; the invoking synchronization phase continues + normally. - `blocked`: include `status`, the specific `problem`, its `impact`, and the `required_action`. Use this only when decision writing cannot proceed safely. @@ -135,9 +137,7 @@ Do not: - Write more than one ADR per request. - Run outside successful task context synchronization. - Create a command, prompt, context root, or decisions directory. -- Modify application code, tests, plans, current-state context, or existing - accepted ADRs. -- Treat every context update as an architecture decision. +- Modify application code, tests, plans, current-state context, or existing ADRs. - Choose among unresolved material alternatives on the user's behalf. - Create a Git commit or push changes. """ @@ -153,6 +153,10 @@ Supersedes: `{context/decisions/YYYY-MM-DD-prior-decision.md}` Omit `Task` or `Supersedes` only when it does not apply. Do not omit `Plan`. +Populate sections only from the validated request and supporting evidence. Do +not invent content to satisfy the template; when the evidence establishes no +content for a section, record `None documented.` instead. + ## Context {Forces, constraints, and evidence that require this decision.} diff --git a/config/pkl/renderers/generation-contract-check.pkl b/config/pkl/renderers/generation-contract-check.pkl index cb689a8c7..acfae69d1 100644 --- a/config/pkl/renderers/generation-contract-check.pkl +++ b/config/pkl/renderers/generation-contract-check.pkl @@ -228,7 +228,7 @@ local expectedDecisionDocumentPaths = new Mapping { } local requiredDecisionSkillTokens = new Listing { - "already qualified" + "qualified by successful task context synchronization" "YYYY-MM-DD-.md" "`Proposed`" "`Accepted`" @@ -236,7 +236,7 @@ local requiredDecisionSkillTokens = new Listing { "`Deprecated`" "`Superseded`" "otherwise default" - "Never edit an ADR whose status is `Accepted`" + "Existing ADRs are immutable regardless of status" "creates a new dated ADR" "references/adr-template.md" "exactly one ADR" From d04c29aef8ed9eb12cec6cd5fd79f0a29ee47a62 Mon Sep 17 00:00:00 2001 From: Ivan Ivic Date: Thu, 1 Oct 2026 16:59:48 +0200 Subject: [PATCH 7/8] config: Align generated SCE workflow contracts Keep the SCE workflow skill contracts consistent across supported agent targets. Update the canonical generation contract and synchronized skill/reference artifacts. Co-authored-by: SCE --- .agents/skills/sce-change-to-plan/SKILL.md | 15 +++++--- .../sce-change-to-plan/references/output.md | 2 +- .../references/plan-authoring.md | 31 +++++++-------- .agents/skills/sce-commit/SKILL.md | 6 +-- .../sce-commit/references/atomic-commit.md | 31 +++++++-------- .../references/commit-message-style.md | 13 +------ .agents/skills/sce-decision/SKILL.md | 38 +++++++++---------- .../sce-decision/references/adr-template.md | 4 ++ .agents/skills/sce-handover/SKILL.md | 27 ++++--------- .agents/skills/sce-next-task/SKILL.md | 6 +-- .../skills/sce-next-task/references/output.md | 5 +-- .../references/task-execution.md | 2 +- .agents/skills/sce-validate/SKILL.md | 6 +-- .../sce-validate/references/validation.md | 3 -- .claude/skills/sce-change-to-plan/SKILL.md | 15 +++++--- .../sce-change-to-plan/references/output.md | 2 +- .../references/plan-authoring.md | 31 +++++++-------- .claude/skills/sce-commit/SKILL.md | 6 +-- .../sce-commit/references/atomic-commit.md | 31 +++++++-------- .../references/commit-message-style.md | 13 +------ .claude/skills/sce-decision/SKILL.md | 38 +++++++++---------- .../sce-decision/references/adr-template.md | 4 ++ .claude/skills/sce-handover/SKILL.md | 27 ++++--------- .claude/skills/sce-next-task/SKILL.md | 6 +-- .../skills/sce-next-task/references/output.md | 5 +-- .../references/task-execution.md | 2 +- .claude/skills/sce-validate/SKILL.md | 6 +-- .../sce-validate/references/validation.md | 3 -- .opencode/skills/sce-change-to-plan/SKILL.md | 15 +++++--- .../sce-change-to-plan/references/output.md | 2 +- .../references/plan-authoring.md | 31 +++++++-------- .opencode/skills/sce-commit/SKILL.md | 6 +-- .../sce-commit/references/atomic-commit.md | 31 +++++++-------- .../references/commit-message-style.md | 13 +------ .opencode/skills/sce-decision/SKILL.md | 38 +++++++++---------- .../sce-decision/references/adr-template.md | 4 ++ .opencode/skills/sce-handover/SKILL.md | 27 ++++--------- .opencode/skills/sce-next-task/SKILL.md | 6 +-- .../skills/sce-next-task/references/output.md | 5 +-- .../references/task-execution.md | 2 +- .opencode/skills/sce-validate/SKILL.md | 6 +-- .../sce-validate/references/validation.md | 3 -- .pi/skills/sce-change-to-plan/SKILL.md | 15 +++++--- .../sce-change-to-plan/references/output.md | 2 +- .../references/plan-authoring.md | 31 +++++++-------- .pi/skills/sce-commit/SKILL.md | 6 +-- .../sce-commit/references/atomic-commit.md | 31 +++++++-------- .../references/commit-message-style.md | 13 +------ .pi/skills/sce-decision/SKILL.md | 38 +++++++++---------- .../sce-decision/references/adr-template.md | 4 ++ .pi/skills/sce-handover/SKILL.md | 27 ++++--------- .pi/skills/sce-next-task/SKILL.md | 6 +-- .pi/skills/sce-next-task/references/output.md | 5 +-- .../references/task-execution.md | 2 +- .pi/skills/sce-validate/SKILL.md | 6 +-- .../sce-validate/references/validation.md | 3 -- .../renderers/generation-contract-check.pkl | 22 +++++------ 57 files changed, 347 insertions(+), 431 deletions(-) diff --git a/.agents/skills/sce-change-to-plan/SKILL.md b/.agents/skills/sce-change-to-plan/SKILL.md index d7e569cb9..fad327431 100644 --- a/.agents/skills/sce-change-to-plan/SKILL.md +++ b/.agents/skills/sce-change-to-plan/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase references @@ -121,9 +121,13 @@ Then stop and wait. Do not implement, and do not run the handoff yourself. ### 4. Revise the plan on request -When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the same `loaded_context_brief` from step 1. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the same `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. +When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the current `loaded_context_brief`. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the current `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. -Run the **Plan authoring phase** with the applicable continuation fields. The brief still holds; durable context did not change because the user disagreed with a task boundary. Do not reload it. +Reuse `loaded_context_brief` when the revision stays within the focus it covers. +If the revision materially expands the plan into an area the brief did not cover, +rerun the **Context load phase** for the expanded focus before running the +**Plan authoring phase**. Do not reload context for revisions already covered by +the brief. An answer that resolves a doubt removes that open question. An answer that does not resolve it leaves the question standing; do not drop it because the user replied to it. If the reply raises a new doubt, the revised plan carries a new open question. @@ -143,7 +147,6 @@ Stop. - Plan at most one change request per invocation. Revisions to the plan that request produced are part of the same invocation, not a second request. - Read each phase's reference before running that phase. -- Always tell the user the plan can be revised, and always name its assumptions as the first thing worth checking. - Do not gate the handoff on open questions listed in the plan summary. Blocking questions return `needs_clarification` before any plan is written. Offering revision is not the same as demanding it, and inventing doubts to justify a review gate is not allowed. - Do not suppress, soften, or answer an open question or clarification question on the user's behalf. - Do not defer the user's revision to a rerun of `/change-to-plan`, and do not defer it to the implementation phase. Revise the plan here. diff --git a/.agents/skills/sce-change-to-plan/references/output.md b/.agents/skills/sce-change-to-plan/references/output.md index af24186bc..a0e1ab543 100644 --- a/.agents/skills/sce-change-to-plan/references/output.md +++ b/.agents/skills/sce-change-to-plan/references/output.md @@ -46,7 +46,7 @@ candidate plan paths and explain that naming one candidate resolves it. {total-tasks} {task|tasks} planned. -This plan is a draft. State a correction and it will be updated. +This plan is a draft. Check its assumptions first; state any correction and it will be updated. Next step: diff --git a/.agents/skills/sce-change-to-plan/references/plan-authoring.md b/.agents/skills/sce-change-to-plan/references/plan-authoring.md index 0f08f5a06..5b614219b 100644 --- a/.agents/skills/sce-change-to-plan/references/plan-authoring.md +++ b/.agents/skills/sce-change-to-plan/references/plan-authoring.md @@ -2,8 +2,22 @@ Run this phase for step 2 of the workflow, and again for each revision in step 4. -Input: the change request, and the complete `loaded` brief from the context load -phase. Pass the brief verbatim; do not restate, summarize, or reinterpret it. +Inputs are one of: + +- Initial authoring: `change_request` and `loaded_context_brief`. +- Clarification continuation: `original_request`, `clarification_answers`, + and `loaded_context_brief`. +- Existing-plan revision: `plan_path`, `correction`, and + `loaded_context_brief`. + +Pass `loaded_context_brief` verbatim. + +For clarification continuation, preserve `original_request` and resolve it with +the supplied `clarification_answers`. + +For an existing-plan revision, read `plan_path` and interpret `correction` +against that plan. A terse correction is not ambiguous merely because it omits +scope and terminology already present in the plan. This phase owns the planning process: @@ -29,19 +43,6 @@ The context brief is the durable memory this plan starts from. Treat its `key_facts` as recorded current state, its `gaps` as areas with no durable context, and its `drift` as recorded context that no longer matches the code. -When no brief is supplied, load the context named by the change request before -authoring, and follow the selection discipline in *Inspect relevant context*. - -Answers the user gave to earlier clarification questions arrive as part of the -change request. Incorporate them into the plan. - -A revision of a plan authored earlier in the session also arrives as the change -request, and it is usually terse: a task boundary the user disagrees with, an -ordering they want changed, work they want added or dropped. Read it against the -existing plan, which supplies the scope, criteria, and terminology it omits. -Terseness is not ambiguity. Do not set internal status `needs_clarification` for -detail the plan already carries; ask only when the revision itself is genuinely -undecidable. ## 2.1 Resolve the plan target diff --git a/.agents/skills/sce-commit/SKILL.md b/.agents/skills/sce-commit/SKILL.md index d48fa9c46..082841ef3 100644 --- a/.agents/skills/sce-commit/SKILL.md +++ b/.agents/skills/sce-commit/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase reference diff --git a/.agents/skills/sce-commit/references/atomic-commit.md b/.agents/skills/sce-commit/references/atomic-commit.md index ba529bf29..81e1c1af0 100644 --- a/.agents/skills/sce-commit/references/atomic-commit.md +++ b/.agents/skills/sce-commit/references/atomic-commit.md @@ -57,8 +57,8 @@ changes. ### 4. Write each message -Follow `references/commit-message-style.md` for the subject pattern, the body -rules, issue references, the plan-citation rule, and the anti-patterns. +Follow `references/commit-message-style.md` for the subject pattern, body +rules, and issue references. ### 5. Apply the plan-citation rule @@ -73,18 +73,7 @@ cite faithfully: - In `bypass` mode, infer the citation when the diff supports it, and otherwise omit it. Never stop, and never invent a slug or task ID. -### 6. Apply context-file guidance gating - -This step applies in `regular` mode only. Skip it entirely in `bypass` mode; do -not classify staged scope there. - -Classify the staged diff: - -- Context-only (`context/**`): context-file-focused guidance is allowed. -- Mixed (`context/**` plus non-`context/**`): suppress default context-file - commit reminders and give guidance that reflects the full staged scope. - -### 7. Propose split guidance +### 6. Propose split guidance This step applies in `regular` mode only. @@ -95,7 +84,7 @@ each. When the staged changes form one unit, return one message and no split guidance. Do not split coherent work to appear thorough. -### 8. Validate the result +### 7. Validate the result Confirm before returning that: @@ -104,6 +93,18 @@ Confirm before returning that: - No plan slug or task ID appears that the staged diff does not support. - The mode's own constraints hold. +## Result contract + +Return exactly one internal result: + +- `blocked`: one or more issues, each carrying its problem, impact, and + required decision. +- `proposal`: regular mode only. Include one or more commits, each with its + complete message and covered files. Include split rationale only when more + than one commit is returned. +- `bypass_message`: bypass mode only. Include exactly one complete message and + the full staged file list. + ## Bypass execution handoff This subsection is the sole definition of the bypass execution sequence. This diff --git a/.agents/skills/sce-commit/references/commit-message-style.md b/.agents/skills/sce-commit/references/commit-message-style.md index 056382ff6..1af66addb 100644 --- a/.agents/skills/sce-commit/references/commit-message-style.md +++ b/.agents/skills/sce-commit/references/commit-message-style.md @@ -7,7 +7,7 @@ Use this repository style when writing new commits. - Start with `scope: Subject` for most code changes. - Common scopes: `runtime`, `language`, `objects`, `tests`, `CI`, `README`. - Combined scopes are fine when needed (for example `language+runtime`). -- Use an imperative verb in the subject: `Fix`, `Add`, `Refactor`, `Remove`, `Implement`, `Update`, `Rewrite`, `Use`, `Allow`. +- Use an imperative verb in the subject. - Keep the subject specific and technical (name the subsystem and actual change). - Keep the subject to one line and do not end it with a period. - Add a body when the change is non-trivial. @@ -31,14 +31,3 @@ Use this repository style when writing new commits. Fixes # (optional) ``` -## Size-based defaults - -1. Small fix: subject + 1 short reason line. -2. Medium refactor: subject + short why + short what changed. -3. Large architectural change: subject + context + bullets for major changes + impact/tradeoffs. - -## Anti-patterns to avoid - -- Vague subjects like "misc updates" or "cleanup". -- Bodies that only repeat the subject without explaining why or impact. -- Overly playful tone in serious bug-fix or architectural change. diff --git a/.agents/skills/sce-decision/SKILL.md b/.agents/skills/sce-decision/SKILL.md index 32b74fefe..0093639f5 100644 --- a/.agents/skills/sce-decision/SKILL.md +++ b/.agents/skills/sce-decision/SKILL.md @@ -1,17 +1,18 @@ --- name: sce-decision description: > - Write one immutable ADR for one decision already qualified by context synchronization + Record one already-qualified decision as an immutable ADR, reusing an equivalent active ADR when present --- # SCE Decision ## Purpose -Write exactly one architecture decision record for one decision already qualified -by successful task context synchronization. Return a deterministic internal -result to the invoking synchronization phase. Do not render an independent -user-visible response. +Resolve exactly one architecture decision record for one decision already +qualified by successful task context synchronization. Reuse an equivalent active +ADR when one exists; otherwise write a new immutable ADR. Return a deterministic +internal result to the invoking synchronization phase. Do not render an +independent user-visible response. ## Input @@ -21,7 +22,7 @@ synchronization. It must identify: - One decision stated as a single durable choice. - Why it qualifies under the decision gate. - The implementation / task-verification evidence establishing the decision. -- The resolved plan path and relevant task IDs, when applicable. +- The resolved plan path, plus relevant task IDs when applicable. - Related current-state context and existing ADR paths. - An optional requested status. @@ -38,9 +39,9 @@ rerun that threshold here. Require the request to state why the caller qualified the decision and include supporting evidence. If the request explicitly represents a nonqualifying gate outcome, return `not_qualified` (or `skipped` when the caller deliberately skipped -the gate) without writing an ADR. If a claimed qualification is unsupported by -its supplied evidence, return `not_qualified`. Missing, contradictory, or -otherwise unsafe material input remains `blocked`. +the gate) without writing an ADR. For a qualified request, do not reassess the +qualification threshold. Missing or contradictory qualification evidence is +unsafe decision-writing input and returns `blocked`. `not_qualified` and `skipped` are non-blocking to the invoking synchronization phase. @@ -68,7 +69,8 @@ Read `context/decisions/` and the supplied related ADR paths before writing. - Reuse an existing ADR only when it records an equivalent decision and has an active status: `Proposed` or `Accepted`. Return its path without creating a duplicate. Never reuse a `Rejected`, `Deprecated`, or `Superseded` ADR. -- Existing ADRs are immutable regardless of status. Never edit an ADR whose status is `Accepted`; do not edit, overwrite, or silently change the status of any existing record. +- Existing ADRs are immutable regardless of status; never edit, overwrite, or + change the status of an existing record. - A correction, reversal, or any changed decision always creates a new dated ADR; it references and supersedes the prior record when applicable, rather than modifying that record. @@ -98,7 +100,7 @@ synchronization phase owns linking the new ADR from authoritative context. Confirm that exactly one ADR was created or one existing matching ADR was reused; the filename, status, sections, and references satisfy this contract; every -referenced repository path exists when practical to check; and no accepted ADR +referenced repository path exists when practical to check; and no existing ADR was modified. ### 6. Return the result @@ -106,11 +108,11 @@ was modified. Return exactly one internal result: - `written`: include `status`, `adr_path`, `decision`, `decision_status`, - `created` (`true` for a new ADR and `false` for reuse), `supersedes`, and - concise verification evidence. -- `not_qualified` or `skipped`: include `status`, the reason the decision gate - did not produce an ADR, and concise supporting evidence. These results are - non-blocking; the invoking synchronization phase continues normally. + `created` (`true` for a new ADR and `false` for reuse), `supersedes` (the prior + ADR path or `null`), and `verification`. +- `not_qualified` or `skipped`: include `status`, `reason`, and `evidence`. + These results are non-blocking; the invoking synchronization phase continues + normally. - `blocked`: include `status`, the specific `problem`, its `impact`, and the `required_action`. Use this only when decision writing cannot proceed safely. @@ -125,8 +127,6 @@ Do not: - Write more than one ADR per request. - Run outside successful task context synchronization. - Create a command, prompt, context root, or decisions directory. -- Modify application code, tests, plans, current-state context, or existing - accepted ADRs. -- Treat every context update as an architecture decision. +- Modify application code, tests, plans, current-state context, or existing ADRs. - Choose among unresolved material alternatives on the user's behalf. - Create a Git commit or push changes. diff --git a/.agents/skills/sce-decision/references/adr-template.md b/.agents/skills/sce-decision/references/adr-template.md index 8c2b06e77..e9e8f74f0 100644 --- a/.agents/skills/sce-decision/references/adr-template.md +++ b/.agents/skills/sce-decision/references/adr-template.md @@ -8,6 +8,10 @@ Supersedes: `{context/decisions/YYYY-MM-DD-prior-decision.md}` Omit `Task` or `Supersedes` only when it does not apply. Do not omit `Plan`. +Populate sections only from the validated request and supporting evidence. Do +not invent content to satisfy the template; when the evidence establishes no +content for a section, record `None documented.` instead. + ## Context {Forces, constraints, and evidence that require this decision.} diff --git a/.agents/skills/sce-handover/SKILL.md b/.agents/skills/sce-handover/SKILL.md index 8c2827581..07913c459 100644 --- a/.agents/skills/sce-handover/SKILL.md +++ b/.agents/skills/sce-handover/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Input @@ -82,14 +82,15 @@ confirmed facts. #### 4. Confirm the context root When `context/` does not exist, there is no durable location to write to. +Do not create it; `sce setup --bootstrap-context` owns context bootstrap. Render the **Writer blocked** layout with `sce setup --bootstrap-context` as the required action, and stop without writing a file. #### 5. Write exactly one file -Write the composed document to the path resolved in step 2. Before reporting -success, validate the written file against the template's **Completeness -contract**. +Write only the composed handover document to the path resolved in step 2. +Do not change plan or task state or edit any other file. Before reporting +success, validate the written file against the template's **Completeness contract**. #### 6. Report @@ -129,17 +130,3 @@ step for continuation in the current session. Loading is read-only: do not edit any file, mark a plan task complete, change repository state, or begin the recommended next step. Presenting the loaded guidance is the entire loader contract. - -## Rules - -- Handle at most one handover per invocation, in exactly one mode. -- Writer mode never overwrites an existing handover file. -- Writer mode never marks a plan task complete or edits any file outside the - one handover document it writes. -- Loader mode never edits a file, writes a new file, or changes plan or task - state. -- Never invoke another SCE skill, sibling SCE package, or SCE workflow command. -- Never treat a file outside `context/handovers/`, or a non-Markdown file, as a - loadable handover. -- Never create the `context/` root; `sce setup --bootstrap-context` owns that. -- Do not begin, plan, or automate the loaded handover's recommended next step. diff --git a/.agents/skills/sce-next-task/SKILL.md b/.agents/skills/sce-next-task/SKILL.md index 4eeae8510..b4dd35aba 100644 --- a/.agents/skills/sce-next-task/SKILL.md +++ b/.agents/skills/sce-next-task/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command except `sce-decision`, and only from the successful context-synchronization decision gate. diff --git a/.agents/skills/sce-next-task/references/output.md b/.agents/skills/sce-next-task/references/output.md index c8a9bcbef..1ddc071ab 100644 --- a/.agents/skills/sce-next-task/references/output.md +++ b/.agents/skills/sce-next-task/references/output.md @@ -71,9 +71,6 @@ Run the final validation: # Implementation gate -Always show this gate at the start of the **Task execution phase**, before editing any -file. - The gate is user-facing prose. It is never serialized into a YAML result. This file is the only authority for the gate's content and order. @@ -104,7 +101,7 @@ file is the only authority for the gate's content and order. ## Approach -Describe the smallest coherent implementation approach in 2–5 steps. +Describe the smallest coherent implementation approach with enough detail for approval. ## Assumptions diff --git a/.agents/skills/sce-next-task/references/task-execution.md b/.agents/skills/sce-next-task/references/task-execution.md index ad9ce6373..ae68ed4c3 100644 --- a/.agents/skills/sce-next-task/references/task-execution.md +++ b/.agents/skills/sce-next-task/references/task-execution.md @@ -191,7 +191,7 @@ Set internal status `blocked` for every other non-successful outcome, including: Do not determine whether the plan is complete. The `/next-task` workflow owns that decision after context synchronization. -Before returning a `complete` result, verify that it satisfies the authoritative +A `complete` result must satisfy the authoritative handoff contract above. ## 2.9 Return the result diff --git a/.agents/skills/sce-validate/SKILL.md b/.agents/skills/sce-validate/SKILL.md index 862f03953..32a32ec9e 100644 --- a/.agents/skills/sce-validate/SKILL.md +++ b/.agents/skills/sce-validate/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase references diff --git a/.agents/skills/sce-validate/references/validation.md b/.agents/skills/sce-validate/references/validation.md index 440f21d47..5fdf8e6f9 100644 --- a/.agents/skills/sce-validate/references/validation.md +++ b/.agents/skills/sce-validate/references/validation.md @@ -250,9 +250,6 @@ a normal work session, then rerun validation. `/validate {plan path}` -Do not stop after the repair. The plan is not finished until `/validate` -returns `validated`. - --- ## Blocked report diff --git a/.claude/skills/sce-change-to-plan/SKILL.md b/.claude/skills/sce-change-to-plan/SKILL.md index 6a049f92f..9e2b5e06f 100644 --- a/.claude/skills/sce-change-to-plan/SKILL.md +++ b/.claude/skills/sce-change-to-plan/SKILL.md @@ -11,12 +11,12 @@ compatibility: claude Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase references @@ -120,9 +120,13 @@ Then stop and wait. Do not implement, and do not run the handoff yourself. ### 4. Revise the plan on request -When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the same `loaded_context_brief` from step 1. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the same `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. +When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the current `loaded_context_brief`. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the current `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. -Run the **Plan authoring phase** with the applicable continuation fields. The brief still holds; durable context did not change because the user disagreed with a task boundary. Do not reload it. +Reuse `loaded_context_brief` when the revision stays within the focus it covers. +If the revision materially expands the plan into an area the brief did not cover, +rerun the **Context load phase** for the expanded focus before running the +**Plan authoring phase**. Do not reload context for revisions already covered by +the brief. An answer that resolves a doubt removes that open question. An answer that does not resolve it leaves the question standing; do not drop it because the user replied to it. If the reply raises a new doubt, the revised plan carries a new open question. @@ -142,7 +146,6 @@ Stop. - Plan at most one change request per invocation. Revisions to the plan that request produced are part of the same invocation, not a second request. - Read each phase's reference before running that phase. -- Always tell the user the plan can be revised, and always name its assumptions as the first thing worth checking. - Do not gate the handoff on open questions listed in the plan summary. Blocking questions return `needs_clarification` before any plan is written. Offering revision is not the same as demanding it, and inventing doubts to justify a review gate is not allowed. - Do not suppress, soften, or answer an open question or clarification question on the user's behalf. - Do not defer the user's revision to a rerun of `/change-to-plan`, and do not defer it to the implementation phase. Revise the plan here. diff --git a/.claude/skills/sce-change-to-plan/references/output.md b/.claude/skills/sce-change-to-plan/references/output.md index af24186bc..a0e1ab543 100644 --- a/.claude/skills/sce-change-to-plan/references/output.md +++ b/.claude/skills/sce-change-to-plan/references/output.md @@ -46,7 +46,7 @@ candidate plan paths and explain that naming one candidate resolves it. {total-tasks} {task|tasks} planned. -This plan is a draft. State a correction and it will be updated. +This plan is a draft. Check its assumptions first; state any correction and it will be updated. Next step: diff --git a/.claude/skills/sce-change-to-plan/references/plan-authoring.md b/.claude/skills/sce-change-to-plan/references/plan-authoring.md index 0f08f5a06..5b614219b 100644 --- a/.claude/skills/sce-change-to-plan/references/plan-authoring.md +++ b/.claude/skills/sce-change-to-plan/references/plan-authoring.md @@ -2,8 +2,22 @@ Run this phase for step 2 of the workflow, and again for each revision in step 4. -Input: the change request, and the complete `loaded` brief from the context load -phase. Pass the brief verbatim; do not restate, summarize, or reinterpret it. +Inputs are one of: + +- Initial authoring: `change_request` and `loaded_context_brief`. +- Clarification continuation: `original_request`, `clarification_answers`, + and `loaded_context_brief`. +- Existing-plan revision: `plan_path`, `correction`, and + `loaded_context_brief`. + +Pass `loaded_context_brief` verbatim. + +For clarification continuation, preserve `original_request` and resolve it with +the supplied `clarification_answers`. + +For an existing-plan revision, read `plan_path` and interpret `correction` +against that plan. A terse correction is not ambiguous merely because it omits +scope and terminology already present in the plan. This phase owns the planning process: @@ -29,19 +43,6 @@ The context brief is the durable memory this plan starts from. Treat its `key_facts` as recorded current state, its `gaps` as areas with no durable context, and its `drift` as recorded context that no longer matches the code. -When no brief is supplied, load the context named by the change request before -authoring, and follow the selection discipline in *Inspect relevant context*. - -Answers the user gave to earlier clarification questions arrive as part of the -change request. Incorporate them into the plan. - -A revision of a plan authored earlier in the session also arrives as the change -request, and it is usually terse: a task boundary the user disagrees with, an -ordering they want changed, work they want added or dropped. Read it against the -existing plan, which supplies the scope, criteria, and terminology it omits. -Terseness is not ambiguity. Do not set internal status `needs_clarification` for -detail the plan already carries; ask only when the revision itself is genuinely -undecidable. ## 2.1 Resolve the plan target diff --git a/.claude/skills/sce-commit/SKILL.md b/.claude/skills/sce-commit/SKILL.md index 5fe9ef0f5..1d1a131f7 100644 --- a/.claude/skills/sce-commit/SKILL.md +++ b/.claude/skills/sce-commit/SKILL.md @@ -11,12 +11,12 @@ compatibility: claude Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase reference diff --git a/.claude/skills/sce-commit/references/atomic-commit.md b/.claude/skills/sce-commit/references/atomic-commit.md index ba529bf29..81e1c1af0 100644 --- a/.claude/skills/sce-commit/references/atomic-commit.md +++ b/.claude/skills/sce-commit/references/atomic-commit.md @@ -57,8 +57,8 @@ changes. ### 4. Write each message -Follow `references/commit-message-style.md` for the subject pattern, the body -rules, issue references, the plan-citation rule, and the anti-patterns. +Follow `references/commit-message-style.md` for the subject pattern, body +rules, and issue references. ### 5. Apply the plan-citation rule @@ -73,18 +73,7 @@ cite faithfully: - In `bypass` mode, infer the citation when the diff supports it, and otherwise omit it. Never stop, and never invent a slug or task ID. -### 6. Apply context-file guidance gating - -This step applies in `regular` mode only. Skip it entirely in `bypass` mode; do -not classify staged scope there. - -Classify the staged diff: - -- Context-only (`context/**`): context-file-focused guidance is allowed. -- Mixed (`context/**` plus non-`context/**`): suppress default context-file - commit reminders and give guidance that reflects the full staged scope. - -### 7. Propose split guidance +### 6. Propose split guidance This step applies in `regular` mode only. @@ -95,7 +84,7 @@ each. When the staged changes form one unit, return one message and no split guidance. Do not split coherent work to appear thorough. -### 8. Validate the result +### 7. Validate the result Confirm before returning that: @@ -104,6 +93,18 @@ Confirm before returning that: - No plan slug or task ID appears that the staged diff does not support. - The mode's own constraints hold. +## Result contract + +Return exactly one internal result: + +- `blocked`: one or more issues, each carrying its problem, impact, and + required decision. +- `proposal`: regular mode only. Include one or more commits, each with its + complete message and covered files. Include split rationale only when more + than one commit is returned. +- `bypass_message`: bypass mode only. Include exactly one complete message and + the full staged file list. + ## Bypass execution handoff This subsection is the sole definition of the bypass execution sequence. This diff --git a/.claude/skills/sce-commit/references/commit-message-style.md b/.claude/skills/sce-commit/references/commit-message-style.md index 056382ff6..1af66addb 100644 --- a/.claude/skills/sce-commit/references/commit-message-style.md +++ b/.claude/skills/sce-commit/references/commit-message-style.md @@ -7,7 +7,7 @@ Use this repository style when writing new commits. - Start with `scope: Subject` for most code changes. - Common scopes: `runtime`, `language`, `objects`, `tests`, `CI`, `README`. - Combined scopes are fine when needed (for example `language+runtime`). -- Use an imperative verb in the subject: `Fix`, `Add`, `Refactor`, `Remove`, `Implement`, `Update`, `Rewrite`, `Use`, `Allow`. +- Use an imperative verb in the subject. - Keep the subject specific and technical (name the subsystem and actual change). - Keep the subject to one line and do not end it with a period. - Add a body when the change is non-trivial. @@ -31,14 +31,3 @@ Use this repository style when writing new commits. Fixes # (optional) ``` -## Size-based defaults - -1. Small fix: subject + 1 short reason line. -2. Medium refactor: subject + short why + short what changed. -3. Large architectural change: subject + context + bullets for major changes + impact/tradeoffs. - -## Anti-patterns to avoid - -- Vague subjects like "misc updates" or "cleanup". -- Bodies that only repeat the subject without explaining why or impact. -- Overly playful tone in serious bug-fix or architectural change. diff --git a/.claude/skills/sce-decision/SKILL.md b/.claude/skills/sce-decision/SKILL.md index d75d761fb..0a304f824 100644 --- a/.claude/skills/sce-decision/SKILL.md +++ b/.claude/skills/sce-decision/SKILL.md @@ -1,7 +1,7 @@ --- name: sce-decision description: > - Write one immutable ADR for one decision already qualified by context synchronization + Record one already-qualified decision as an immutable ADR, reusing an equivalent active ADR when present compatibility: claude --- @@ -9,10 +9,11 @@ compatibility: claude ## Purpose -Write exactly one architecture decision record for one decision already qualified -by successful task context synchronization. Return a deterministic internal -result to the invoking synchronization phase. Do not render an independent -user-visible response. +Resolve exactly one architecture decision record for one decision already +qualified by successful task context synchronization. Reuse an equivalent active +ADR when one exists; otherwise write a new immutable ADR. Return a deterministic +internal result to the invoking synchronization phase. Do not render an +independent user-visible response. ## Input @@ -22,7 +23,7 @@ synchronization. It must identify: - One decision stated as a single durable choice. - Why it qualifies under the decision gate. - The implementation / task-verification evidence establishing the decision. -- The resolved plan path and relevant task IDs, when applicable. +- The resolved plan path, plus relevant task IDs when applicable. - Related current-state context and existing ADR paths. - An optional requested status. @@ -39,9 +40,9 @@ rerun that threshold here. Require the request to state why the caller qualified the decision and include supporting evidence. If the request explicitly represents a nonqualifying gate outcome, return `not_qualified` (or `skipped` when the caller deliberately skipped -the gate) without writing an ADR. If a claimed qualification is unsupported by -its supplied evidence, return `not_qualified`. Missing, contradictory, or -otherwise unsafe material input remains `blocked`. +the gate) without writing an ADR. For a qualified request, do not reassess the +qualification threshold. Missing or contradictory qualification evidence is +unsafe decision-writing input and returns `blocked`. `not_qualified` and `skipped` are non-blocking to the invoking synchronization phase. @@ -69,7 +70,8 @@ Read `context/decisions/` and the supplied related ADR paths before writing. - Reuse an existing ADR only when it records an equivalent decision and has an active status: `Proposed` or `Accepted`. Return its path without creating a duplicate. Never reuse a `Rejected`, `Deprecated`, or `Superseded` ADR. -- Existing ADRs are immutable regardless of status. Never edit an ADR whose status is `Accepted`; do not edit, overwrite, or silently change the status of any existing record. +- Existing ADRs are immutable regardless of status; never edit, overwrite, or + change the status of an existing record. - A correction, reversal, or any changed decision always creates a new dated ADR; it references and supersedes the prior record when applicable, rather than modifying that record. @@ -99,7 +101,7 @@ synchronization phase owns linking the new ADR from authoritative context. Confirm that exactly one ADR was created or one existing matching ADR was reused; the filename, status, sections, and references satisfy this contract; every -referenced repository path exists when practical to check; and no accepted ADR +referenced repository path exists when practical to check; and no existing ADR was modified. ### 6. Return the result @@ -107,11 +109,11 @@ was modified. Return exactly one internal result: - `written`: include `status`, `adr_path`, `decision`, `decision_status`, - `created` (`true` for a new ADR and `false` for reuse), `supersedes`, and - concise verification evidence. -- `not_qualified` or `skipped`: include `status`, the reason the decision gate - did not produce an ADR, and concise supporting evidence. These results are - non-blocking; the invoking synchronization phase continues normally. + `created` (`true` for a new ADR and `false` for reuse), `supersedes` (the prior + ADR path or `null`), and `verification`. +- `not_qualified` or `skipped`: include `status`, `reason`, and `evidence`. + These results are non-blocking; the invoking synchronization phase continues + normally. - `blocked`: include `status`, the specific `problem`, its `impact`, and the `required_action`. Use this only when decision writing cannot proceed safely. @@ -126,8 +128,6 @@ Do not: - Write more than one ADR per request. - Run outside successful task context synchronization. - Create a command, prompt, context root, or decisions directory. -- Modify application code, tests, plans, current-state context, or existing - accepted ADRs. -- Treat every context update as an architecture decision. +- Modify application code, tests, plans, current-state context, or existing ADRs. - Choose among unresolved material alternatives on the user's behalf. - Create a Git commit or push changes. diff --git a/.claude/skills/sce-decision/references/adr-template.md b/.claude/skills/sce-decision/references/adr-template.md index 8c2b06e77..e9e8f74f0 100644 --- a/.claude/skills/sce-decision/references/adr-template.md +++ b/.claude/skills/sce-decision/references/adr-template.md @@ -8,6 +8,10 @@ Supersedes: `{context/decisions/YYYY-MM-DD-prior-decision.md}` Omit `Task` or `Supersedes` only when it does not apply. Do not omit `Plan`. +Populate sections only from the validated request and supporting evidence. Do +not invent content to satisfy the template; when the evidence establishes no +content for a section, record `None documented.` instead. + ## Context {Forces, constraints, and evidence that require this decision.} diff --git a/.claude/skills/sce-handover/SKILL.md b/.claude/skills/sce-handover/SKILL.md index 1e04509d8..400dcc97a 100644 --- a/.claude/skills/sce-handover/SKILL.md +++ b/.claude/skills/sce-handover/SKILL.md @@ -11,12 +11,12 @@ compatibility: claude Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Input @@ -81,14 +81,15 @@ confirmed facts. #### 4. Confirm the context root When `context/` does not exist, there is no durable location to write to. +Do not create it; `sce setup --bootstrap-context` owns context bootstrap. Render the **Writer blocked** layout with `sce setup --bootstrap-context` as the required action, and stop without writing a file. #### 5. Write exactly one file -Write the composed document to the path resolved in step 2. Before reporting -success, validate the written file against the template's **Completeness -contract**. +Write only the composed handover document to the path resolved in step 2. +Do not change plan or task state or edit any other file. Before reporting +success, validate the written file against the template's **Completeness contract**. #### 6. Report @@ -128,17 +129,3 @@ step for continuation in the current session. Loading is read-only: do not edit any file, mark a plan task complete, change repository state, or begin the recommended next step. Presenting the loaded guidance is the entire loader contract. - -## Rules - -- Handle at most one handover per invocation, in exactly one mode. -- Writer mode never overwrites an existing handover file. -- Writer mode never marks a plan task complete or edits any file outside the - one handover document it writes. -- Loader mode never edits a file, writes a new file, or changes plan or task - state. -- Never invoke another SCE skill, sibling SCE package, or SCE workflow command. -- Never treat a file outside `context/handovers/`, or a non-Markdown file, as a - loadable handover. -- Never create the `context/` root; `sce setup --bootstrap-context` owns that. -- Do not begin, plan, or automate the loaded handover's recommended next step. diff --git a/.claude/skills/sce-next-task/SKILL.md b/.claude/skills/sce-next-task/SKILL.md index ad4da900f..2806e3a51 100644 --- a/.claude/skills/sce-next-task/SKILL.md +++ b/.claude/skills/sce-next-task/SKILL.md @@ -11,12 +11,12 @@ compatibility: claude Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command except `sce-decision`, and only from the successful context-synchronization decision gate. diff --git a/.claude/skills/sce-next-task/references/output.md b/.claude/skills/sce-next-task/references/output.md index c8a9bcbef..1ddc071ab 100644 --- a/.claude/skills/sce-next-task/references/output.md +++ b/.claude/skills/sce-next-task/references/output.md @@ -71,9 +71,6 @@ Run the final validation: # Implementation gate -Always show this gate at the start of the **Task execution phase**, before editing any -file. - The gate is user-facing prose. It is never serialized into a YAML result. This file is the only authority for the gate's content and order. @@ -104,7 +101,7 @@ file is the only authority for the gate's content and order. ## Approach -Describe the smallest coherent implementation approach in 2–5 steps. +Describe the smallest coherent implementation approach with enough detail for approval. ## Assumptions diff --git a/.claude/skills/sce-next-task/references/task-execution.md b/.claude/skills/sce-next-task/references/task-execution.md index ad9ce6373..ae68ed4c3 100644 --- a/.claude/skills/sce-next-task/references/task-execution.md +++ b/.claude/skills/sce-next-task/references/task-execution.md @@ -191,7 +191,7 @@ Set internal status `blocked` for every other non-successful outcome, including: Do not determine whether the plan is complete. The `/next-task` workflow owns that decision after context synchronization. -Before returning a `complete` result, verify that it satisfies the authoritative +A `complete` result must satisfy the authoritative handoff contract above. ## 2.9 Return the result diff --git a/.claude/skills/sce-validate/SKILL.md b/.claude/skills/sce-validate/SKILL.md index 9f874f37c..284028f66 100644 --- a/.claude/skills/sce-validate/SKILL.md +++ b/.claude/skills/sce-validate/SKILL.md @@ -11,12 +11,12 @@ compatibility: claude Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase references diff --git a/.claude/skills/sce-validate/references/validation.md b/.claude/skills/sce-validate/references/validation.md index 440f21d47..5fdf8e6f9 100644 --- a/.claude/skills/sce-validate/references/validation.md +++ b/.claude/skills/sce-validate/references/validation.md @@ -250,9 +250,6 @@ a normal work session, then rerun validation. `/validate {plan path}` -Do not stop after the repair. The plan is not finished until `/validate` -returns `validated`. - --- ## Blocked report diff --git a/.opencode/skills/sce-change-to-plan/SKILL.md b/.opencode/skills/sce-change-to-plan/SKILL.md index 84d2be6d3..b6461d4f4 100644 --- a/.opencode/skills/sce-change-to-plan/SKILL.md +++ b/.opencode/skills/sce-change-to-plan/SKILL.md @@ -11,12 +11,12 @@ compatibility: opencode Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase references @@ -120,9 +120,13 @@ Then stop and wait. Do not implement, and do not run the handoff yourself. ### 4. Revise the plan on request -When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the same `loaded_context_brief` from step 1. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the same `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. +When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the current `loaded_context_brief`. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the current `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. -Run the **Plan authoring phase** with the applicable continuation fields. The brief still holds; durable context did not change because the user disagreed with a task boundary. Do not reload it. +Reuse `loaded_context_brief` when the revision stays within the focus it covers. +If the revision materially expands the plan into an area the brief did not cover, +rerun the **Context load phase** for the expanded focus before running the +**Plan authoring phase**. Do not reload context for revisions already covered by +the brief. An answer that resolves a doubt removes that open question. An answer that does not resolve it leaves the question standing; do not drop it because the user replied to it. If the reply raises a new doubt, the revised plan carries a new open question. @@ -142,7 +146,6 @@ Stop. - Plan at most one change request per invocation. Revisions to the plan that request produced are part of the same invocation, not a second request. - Read each phase's reference before running that phase. -- Always tell the user the plan can be revised, and always name its assumptions as the first thing worth checking. - Do not gate the handoff on open questions listed in the plan summary. Blocking questions return `needs_clarification` before any plan is written. Offering revision is not the same as demanding it, and inventing doubts to justify a review gate is not allowed. - Do not suppress, soften, or answer an open question or clarification question on the user's behalf. - Do not defer the user's revision to a rerun of `/change-to-plan`, and do not defer it to the implementation phase. Revise the plan here. diff --git a/.opencode/skills/sce-change-to-plan/references/output.md b/.opencode/skills/sce-change-to-plan/references/output.md index af24186bc..a0e1ab543 100644 --- a/.opencode/skills/sce-change-to-plan/references/output.md +++ b/.opencode/skills/sce-change-to-plan/references/output.md @@ -46,7 +46,7 @@ candidate plan paths and explain that naming one candidate resolves it. {total-tasks} {task|tasks} planned. -This plan is a draft. State a correction and it will be updated. +This plan is a draft. Check its assumptions first; state any correction and it will be updated. Next step: diff --git a/.opencode/skills/sce-change-to-plan/references/plan-authoring.md b/.opencode/skills/sce-change-to-plan/references/plan-authoring.md index 0f08f5a06..5b614219b 100644 --- a/.opencode/skills/sce-change-to-plan/references/plan-authoring.md +++ b/.opencode/skills/sce-change-to-plan/references/plan-authoring.md @@ -2,8 +2,22 @@ Run this phase for step 2 of the workflow, and again for each revision in step 4. -Input: the change request, and the complete `loaded` brief from the context load -phase. Pass the brief verbatim; do not restate, summarize, or reinterpret it. +Inputs are one of: + +- Initial authoring: `change_request` and `loaded_context_brief`. +- Clarification continuation: `original_request`, `clarification_answers`, + and `loaded_context_brief`. +- Existing-plan revision: `plan_path`, `correction`, and + `loaded_context_brief`. + +Pass `loaded_context_brief` verbatim. + +For clarification continuation, preserve `original_request` and resolve it with +the supplied `clarification_answers`. + +For an existing-plan revision, read `plan_path` and interpret `correction` +against that plan. A terse correction is not ambiguous merely because it omits +scope and terminology already present in the plan. This phase owns the planning process: @@ -29,19 +43,6 @@ The context brief is the durable memory this plan starts from. Treat its `key_facts` as recorded current state, its `gaps` as areas with no durable context, and its `drift` as recorded context that no longer matches the code. -When no brief is supplied, load the context named by the change request before -authoring, and follow the selection discipline in *Inspect relevant context*. - -Answers the user gave to earlier clarification questions arrive as part of the -change request. Incorporate them into the plan. - -A revision of a plan authored earlier in the session also arrives as the change -request, and it is usually terse: a task boundary the user disagrees with, an -ordering they want changed, work they want added or dropped. Read it against the -existing plan, which supplies the scope, criteria, and terminology it omits. -Terseness is not ambiguity. Do not set internal status `needs_clarification` for -detail the plan already carries; ask only when the revision itself is genuinely -undecidable. ## 2.1 Resolve the plan target diff --git a/.opencode/skills/sce-commit/SKILL.md b/.opencode/skills/sce-commit/SKILL.md index 5e4855c57..aedd17f63 100644 --- a/.opencode/skills/sce-commit/SKILL.md +++ b/.opencode/skills/sce-commit/SKILL.md @@ -11,12 +11,12 @@ compatibility: opencode Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase reference diff --git a/.opencode/skills/sce-commit/references/atomic-commit.md b/.opencode/skills/sce-commit/references/atomic-commit.md index ba529bf29..81e1c1af0 100644 --- a/.opencode/skills/sce-commit/references/atomic-commit.md +++ b/.opencode/skills/sce-commit/references/atomic-commit.md @@ -57,8 +57,8 @@ changes. ### 4. Write each message -Follow `references/commit-message-style.md` for the subject pattern, the body -rules, issue references, the plan-citation rule, and the anti-patterns. +Follow `references/commit-message-style.md` for the subject pattern, body +rules, and issue references. ### 5. Apply the plan-citation rule @@ -73,18 +73,7 @@ cite faithfully: - In `bypass` mode, infer the citation when the diff supports it, and otherwise omit it. Never stop, and never invent a slug or task ID. -### 6. Apply context-file guidance gating - -This step applies in `regular` mode only. Skip it entirely in `bypass` mode; do -not classify staged scope there. - -Classify the staged diff: - -- Context-only (`context/**`): context-file-focused guidance is allowed. -- Mixed (`context/**` plus non-`context/**`): suppress default context-file - commit reminders and give guidance that reflects the full staged scope. - -### 7. Propose split guidance +### 6. Propose split guidance This step applies in `regular` mode only. @@ -95,7 +84,7 @@ each. When the staged changes form one unit, return one message and no split guidance. Do not split coherent work to appear thorough. -### 8. Validate the result +### 7. Validate the result Confirm before returning that: @@ -104,6 +93,18 @@ Confirm before returning that: - No plan slug or task ID appears that the staged diff does not support. - The mode's own constraints hold. +## Result contract + +Return exactly one internal result: + +- `blocked`: one or more issues, each carrying its problem, impact, and + required decision. +- `proposal`: regular mode only. Include one or more commits, each with its + complete message and covered files. Include split rationale only when more + than one commit is returned. +- `bypass_message`: bypass mode only. Include exactly one complete message and + the full staged file list. + ## Bypass execution handoff This subsection is the sole definition of the bypass execution sequence. This diff --git a/.opencode/skills/sce-commit/references/commit-message-style.md b/.opencode/skills/sce-commit/references/commit-message-style.md index 056382ff6..1af66addb 100644 --- a/.opencode/skills/sce-commit/references/commit-message-style.md +++ b/.opencode/skills/sce-commit/references/commit-message-style.md @@ -7,7 +7,7 @@ Use this repository style when writing new commits. - Start with `scope: Subject` for most code changes. - Common scopes: `runtime`, `language`, `objects`, `tests`, `CI`, `README`. - Combined scopes are fine when needed (for example `language+runtime`). -- Use an imperative verb in the subject: `Fix`, `Add`, `Refactor`, `Remove`, `Implement`, `Update`, `Rewrite`, `Use`, `Allow`. +- Use an imperative verb in the subject. - Keep the subject specific and technical (name the subsystem and actual change). - Keep the subject to one line and do not end it with a period. - Add a body when the change is non-trivial. @@ -31,14 +31,3 @@ Use this repository style when writing new commits. Fixes # (optional) ``` -## Size-based defaults - -1. Small fix: subject + 1 short reason line. -2. Medium refactor: subject + short why + short what changed. -3. Large architectural change: subject + context + bullets for major changes + impact/tradeoffs. - -## Anti-patterns to avoid - -- Vague subjects like "misc updates" or "cleanup". -- Bodies that only repeat the subject without explaining why or impact. -- Overly playful tone in serious bug-fix or architectural change. diff --git a/.opencode/skills/sce-decision/SKILL.md b/.opencode/skills/sce-decision/SKILL.md index 193f95a28..42a4d05ef 100644 --- a/.opencode/skills/sce-decision/SKILL.md +++ b/.opencode/skills/sce-decision/SKILL.md @@ -1,7 +1,7 @@ --- name: sce-decision description: > - Write one immutable ADR for one decision already qualified by context synchronization + Record one already-qualified decision as an immutable ADR, reusing an equivalent active ADR when present compatibility: opencode --- @@ -9,10 +9,11 @@ compatibility: opencode ## Purpose -Write exactly one architecture decision record for one decision already qualified -by successful task context synchronization. Return a deterministic internal -result to the invoking synchronization phase. Do not render an independent -user-visible response. +Resolve exactly one architecture decision record for one decision already +qualified by successful task context synchronization. Reuse an equivalent active +ADR when one exists; otherwise write a new immutable ADR. Return a deterministic +internal result to the invoking synchronization phase. Do not render an +independent user-visible response. ## Input @@ -22,7 +23,7 @@ synchronization. It must identify: - One decision stated as a single durable choice. - Why it qualifies under the decision gate. - The implementation / task-verification evidence establishing the decision. -- The resolved plan path and relevant task IDs, when applicable. +- The resolved plan path, plus relevant task IDs when applicable. - Related current-state context and existing ADR paths. - An optional requested status. @@ -39,9 +40,9 @@ rerun that threshold here. Require the request to state why the caller qualified the decision and include supporting evidence. If the request explicitly represents a nonqualifying gate outcome, return `not_qualified` (or `skipped` when the caller deliberately skipped -the gate) without writing an ADR. If a claimed qualification is unsupported by -its supplied evidence, return `not_qualified`. Missing, contradictory, or -otherwise unsafe material input remains `blocked`. +the gate) without writing an ADR. For a qualified request, do not reassess the +qualification threshold. Missing or contradictory qualification evidence is +unsafe decision-writing input and returns `blocked`. `not_qualified` and `skipped` are non-blocking to the invoking synchronization phase. @@ -69,7 +70,8 @@ Read `context/decisions/` and the supplied related ADR paths before writing. - Reuse an existing ADR only when it records an equivalent decision and has an active status: `Proposed` or `Accepted`. Return its path without creating a duplicate. Never reuse a `Rejected`, `Deprecated`, or `Superseded` ADR. -- Existing ADRs are immutable regardless of status. Never edit an ADR whose status is `Accepted`; do not edit, overwrite, or silently change the status of any existing record. +- Existing ADRs are immutable regardless of status; never edit, overwrite, or + change the status of an existing record. - A correction, reversal, or any changed decision always creates a new dated ADR; it references and supersedes the prior record when applicable, rather than modifying that record. @@ -99,7 +101,7 @@ synchronization phase owns linking the new ADR from authoritative context. Confirm that exactly one ADR was created or one existing matching ADR was reused; the filename, status, sections, and references satisfy this contract; every -referenced repository path exists when practical to check; and no accepted ADR +referenced repository path exists when practical to check; and no existing ADR was modified. ### 6. Return the result @@ -107,11 +109,11 @@ was modified. Return exactly one internal result: - `written`: include `status`, `adr_path`, `decision`, `decision_status`, - `created` (`true` for a new ADR and `false` for reuse), `supersedes`, and - concise verification evidence. -- `not_qualified` or `skipped`: include `status`, the reason the decision gate - did not produce an ADR, and concise supporting evidence. These results are - non-blocking; the invoking synchronization phase continues normally. + `created` (`true` for a new ADR and `false` for reuse), `supersedes` (the prior + ADR path or `null`), and `verification`. +- `not_qualified` or `skipped`: include `status`, `reason`, and `evidence`. + These results are non-blocking; the invoking synchronization phase continues + normally. - `blocked`: include `status`, the specific `problem`, its `impact`, and the `required_action`. Use this only when decision writing cannot proceed safely. @@ -126,8 +128,6 @@ Do not: - Write more than one ADR per request. - Run outside successful task context synchronization. - Create a command, prompt, context root, or decisions directory. -- Modify application code, tests, plans, current-state context, or existing - accepted ADRs. -- Treat every context update as an architecture decision. +- Modify application code, tests, plans, current-state context, or existing ADRs. - Choose among unresolved material alternatives on the user's behalf. - Create a Git commit or push changes. diff --git a/.opencode/skills/sce-decision/references/adr-template.md b/.opencode/skills/sce-decision/references/adr-template.md index 8c2b06e77..e9e8f74f0 100644 --- a/.opencode/skills/sce-decision/references/adr-template.md +++ b/.opencode/skills/sce-decision/references/adr-template.md @@ -8,6 +8,10 @@ Supersedes: `{context/decisions/YYYY-MM-DD-prior-decision.md}` Omit `Task` or `Supersedes` only when it does not apply. Do not omit `Plan`. +Populate sections only from the validated request and supporting evidence. Do +not invent content to satisfy the template; when the evidence establishes no +content for a section, record `None documented.` instead. + ## Context {Forces, constraints, and evidence that require this decision.} diff --git a/.opencode/skills/sce-handover/SKILL.md b/.opencode/skills/sce-handover/SKILL.md index 3c02349b6..dd82447cc 100644 --- a/.opencode/skills/sce-handover/SKILL.md +++ b/.opencode/skills/sce-handover/SKILL.md @@ -11,12 +11,12 @@ compatibility: opencode Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Input @@ -81,14 +81,15 @@ confirmed facts. #### 4. Confirm the context root When `context/` does not exist, there is no durable location to write to. +Do not create it; `sce setup --bootstrap-context` owns context bootstrap. Render the **Writer blocked** layout with `sce setup --bootstrap-context` as the required action, and stop without writing a file. #### 5. Write exactly one file -Write the composed document to the path resolved in step 2. Before reporting -success, validate the written file against the template's **Completeness -contract**. +Write only the composed handover document to the path resolved in step 2. +Do not change plan or task state or edit any other file. Before reporting +success, validate the written file against the template's **Completeness contract**. #### 6. Report @@ -128,17 +129,3 @@ step for continuation in the current session. Loading is read-only: do not edit any file, mark a plan task complete, change repository state, or begin the recommended next step. Presenting the loaded guidance is the entire loader contract. - -## Rules - -- Handle at most one handover per invocation, in exactly one mode. -- Writer mode never overwrites an existing handover file. -- Writer mode never marks a plan task complete or edits any file outside the - one handover document it writes. -- Loader mode never edits a file, writes a new file, or changes plan or task - state. -- Never invoke another SCE skill, sibling SCE package, or SCE workflow command. -- Never treat a file outside `context/handovers/`, or a non-Markdown file, as a - loadable handover. -- Never create the `context/` root; `sce setup --bootstrap-context` owns that. -- Do not begin, plan, or automate the loaded handover's recommended next step. diff --git a/.opencode/skills/sce-next-task/SKILL.md b/.opencode/skills/sce-next-task/SKILL.md index aa6732be3..70b87f4f0 100644 --- a/.opencode/skills/sce-next-task/SKILL.md +++ b/.opencode/skills/sce-next-task/SKILL.md @@ -11,12 +11,12 @@ compatibility: opencode Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command except `sce-decision`, and only from the successful context-synchronization decision gate. diff --git a/.opencode/skills/sce-next-task/references/output.md b/.opencode/skills/sce-next-task/references/output.md index c8a9bcbef..1ddc071ab 100644 --- a/.opencode/skills/sce-next-task/references/output.md +++ b/.opencode/skills/sce-next-task/references/output.md @@ -71,9 +71,6 @@ Run the final validation: # Implementation gate -Always show this gate at the start of the **Task execution phase**, before editing any -file. - The gate is user-facing prose. It is never serialized into a YAML result. This file is the only authority for the gate's content and order. @@ -104,7 +101,7 @@ file is the only authority for the gate's content and order. ## Approach -Describe the smallest coherent implementation approach in 2–5 steps. +Describe the smallest coherent implementation approach with enough detail for approval. ## Assumptions diff --git a/.opencode/skills/sce-next-task/references/task-execution.md b/.opencode/skills/sce-next-task/references/task-execution.md index ad9ce6373..ae68ed4c3 100644 --- a/.opencode/skills/sce-next-task/references/task-execution.md +++ b/.opencode/skills/sce-next-task/references/task-execution.md @@ -191,7 +191,7 @@ Set internal status `blocked` for every other non-successful outcome, including: Do not determine whether the plan is complete. The `/next-task` workflow owns that decision after context synchronization. -Before returning a `complete` result, verify that it satisfies the authoritative +A `complete` result must satisfy the authoritative handoff contract above. ## 2.9 Return the result diff --git a/.opencode/skills/sce-validate/SKILL.md b/.opencode/skills/sce-validate/SKILL.md index 6ab623738..80c3e3f41 100644 --- a/.opencode/skills/sce-validate/SKILL.md +++ b/.opencode/skills/sce-validate/SKILL.md @@ -11,12 +11,12 @@ compatibility: opencode Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase references diff --git a/.opencode/skills/sce-validate/references/validation.md b/.opencode/skills/sce-validate/references/validation.md index 440f21d47..5fdf8e6f9 100644 --- a/.opencode/skills/sce-validate/references/validation.md +++ b/.opencode/skills/sce-validate/references/validation.md @@ -250,9 +250,6 @@ a normal work session, then rerun validation. `/validate {plan path}` -Do not stop after the repair. The plan is not finished until `/validate` -returns `validated`. - --- ## Blocked report diff --git a/.pi/skills/sce-change-to-plan/SKILL.md b/.pi/skills/sce-change-to-plan/SKILL.md index 4ce057d98..eef5a7f99 100644 --- a/.pi/skills/sce-change-to-plan/SKILL.md +++ b/.pi/skills/sce-change-to-plan/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase references @@ -119,9 +119,13 @@ Then stop and wait. Do not implement, and do not run the handoff yourself. ### 4. Revise the plan on request -When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the same `loaded_context_brief` from step 1. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the same `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. +When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the current `loaded_context_brief`. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the current `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`. -Run the **Plan authoring phase** with the applicable continuation fields. The brief still holds; durable context did not change because the user disagreed with a task boundary. Do not reload it. +Reuse `loaded_context_brief` when the revision stays within the focus it covers. +If the revision materially expands the plan into an area the brief did not cover, +rerun the **Context load phase** for the expanded focus before running the +**Plan authoring phase**. Do not reload context for revisions already covered by +the brief. An answer that resolves a doubt removes that open question. An answer that does not resolve it leaves the question standing; do not drop it because the user replied to it. If the reply raises a new doubt, the revised plan carries a new open question. @@ -141,7 +145,6 @@ Stop. - Plan at most one change request per invocation. Revisions to the plan that request produced are part of the same invocation, not a second request. - Read each phase's reference before running that phase. -- Always tell the user the plan can be revised, and always name its assumptions as the first thing worth checking. - Do not gate the handoff on open questions listed in the plan summary. Blocking questions return `needs_clarification` before any plan is written. Offering revision is not the same as demanding it, and inventing doubts to justify a review gate is not allowed. - Do not suppress, soften, or answer an open question or clarification question on the user's behalf. - Do not defer the user's revision to a rerun of `/change-to-plan`, and do not defer it to the implementation phase. Revise the plan here. diff --git a/.pi/skills/sce-change-to-plan/references/output.md b/.pi/skills/sce-change-to-plan/references/output.md index af24186bc..a0e1ab543 100644 --- a/.pi/skills/sce-change-to-plan/references/output.md +++ b/.pi/skills/sce-change-to-plan/references/output.md @@ -46,7 +46,7 @@ candidate plan paths and explain that naming one candidate resolves it. {total-tasks} {task|tasks} planned. -This plan is a draft. State a correction and it will be updated. +This plan is a draft. Check its assumptions first; state any correction and it will be updated. Next step: diff --git a/.pi/skills/sce-change-to-plan/references/plan-authoring.md b/.pi/skills/sce-change-to-plan/references/plan-authoring.md index 0f08f5a06..5b614219b 100644 --- a/.pi/skills/sce-change-to-plan/references/plan-authoring.md +++ b/.pi/skills/sce-change-to-plan/references/plan-authoring.md @@ -2,8 +2,22 @@ Run this phase for step 2 of the workflow, and again for each revision in step 4. -Input: the change request, and the complete `loaded` brief from the context load -phase. Pass the brief verbatim; do not restate, summarize, or reinterpret it. +Inputs are one of: + +- Initial authoring: `change_request` and `loaded_context_brief`. +- Clarification continuation: `original_request`, `clarification_answers`, + and `loaded_context_brief`. +- Existing-plan revision: `plan_path`, `correction`, and + `loaded_context_brief`. + +Pass `loaded_context_brief` verbatim. + +For clarification continuation, preserve `original_request` and resolve it with +the supplied `clarification_answers`. + +For an existing-plan revision, read `plan_path` and interpret `correction` +against that plan. A terse correction is not ambiguous merely because it omits +scope and terminology already present in the plan. This phase owns the planning process: @@ -29,19 +43,6 @@ The context brief is the durable memory this plan starts from. Treat its `key_facts` as recorded current state, its `gaps` as areas with no durable context, and its `drift` as recorded context that no longer matches the code. -When no brief is supplied, load the context named by the change request before -authoring, and follow the selection discipline in *Inspect relevant context*. - -Answers the user gave to earlier clarification questions arrive as part of the -change request. Incorporate them into the plan. - -A revision of a plan authored earlier in the session also arrives as the change -request, and it is usually terse: a task boundary the user disagrees with, an -ordering they want changed, work they want added or dropped. Read it against the -existing plan, which supplies the scope, criteria, and terminology it omits. -Terseness is not ambiguity. Do not set internal status `needs_clarification` for -detail the plan already carries; ask only when the revision itself is genuinely -undecidable. ## 2.1 Resolve the plan target diff --git a/.pi/skills/sce-commit/SKILL.md b/.pi/skills/sce-commit/SKILL.md index 0123adeae..0181c4026 100644 --- a/.pi/skills/sce-commit/SKILL.md +++ b/.pi/skills/sce-commit/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase reference diff --git a/.pi/skills/sce-commit/references/atomic-commit.md b/.pi/skills/sce-commit/references/atomic-commit.md index ba529bf29..81e1c1af0 100644 --- a/.pi/skills/sce-commit/references/atomic-commit.md +++ b/.pi/skills/sce-commit/references/atomic-commit.md @@ -57,8 +57,8 @@ changes. ### 4. Write each message -Follow `references/commit-message-style.md` for the subject pattern, the body -rules, issue references, the plan-citation rule, and the anti-patterns. +Follow `references/commit-message-style.md` for the subject pattern, body +rules, and issue references. ### 5. Apply the plan-citation rule @@ -73,18 +73,7 @@ cite faithfully: - In `bypass` mode, infer the citation when the diff supports it, and otherwise omit it. Never stop, and never invent a slug or task ID. -### 6. Apply context-file guidance gating - -This step applies in `regular` mode only. Skip it entirely in `bypass` mode; do -not classify staged scope there. - -Classify the staged diff: - -- Context-only (`context/**`): context-file-focused guidance is allowed. -- Mixed (`context/**` plus non-`context/**`): suppress default context-file - commit reminders and give guidance that reflects the full staged scope. - -### 7. Propose split guidance +### 6. Propose split guidance This step applies in `regular` mode only. @@ -95,7 +84,7 @@ each. When the staged changes form one unit, return one message and no split guidance. Do not split coherent work to appear thorough. -### 8. Validate the result +### 7. Validate the result Confirm before returning that: @@ -104,6 +93,18 @@ Confirm before returning that: - No plan slug or task ID appears that the staged diff does not support. - The mode's own constraints hold. +## Result contract + +Return exactly one internal result: + +- `blocked`: one or more issues, each carrying its problem, impact, and + required decision. +- `proposal`: regular mode only. Include one or more commits, each with its + complete message and covered files. Include split rationale only when more + than one commit is returned. +- `bypass_message`: bypass mode only. Include exactly one complete message and + the full staged file list. + ## Bypass execution handoff This subsection is the sole definition of the bypass execution sequence. This diff --git a/.pi/skills/sce-commit/references/commit-message-style.md b/.pi/skills/sce-commit/references/commit-message-style.md index 056382ff6..1af66addb 100644 --- a/.pi/skills/sce-commit/references/commit-message-style.md +++ b/.pi/skills/sce-commit/references/commit-message-style.md @@ -7,7 +7,7 @@ Use this repository style when writing new commits. - Start with `scope: Subject` for most code changes. - Common scopes: `runtime`, `language`, `objects`, `tests`, `CI`, `README`. - Combined scopes are fine when needed (for example `language+runtime`). -- Use an imperative verb in the subject: `Fix`, `Add`, `Refactor`, `Remove`, `Implement`, `Update`, `Rewrite`, `Use`, `Allow`. +- Use an imperative verb in the subject. - Keep the subject specific and technical (name the subsystem and actual change). - Keep the subject to one line and do not end it with a period. - Add a body when the change is non-trivial. @@ -31,14 +31,3 @@ Use this repository style when writing new commits. Fixes # (optional) ``` -## Size-based defaults - -1. Small fix: subject + 1 short reason line. -2. Medium refactor: subject + short why + short what changed. -3. Large architectural change: subject + context + bullets for major changes + impact/tradeoffs. - -## Anti-patterns to avoid - -- Vague subjects like "misc updates" or "cleanup". -- Bodies that only repeat the subject without explaining why or impact. -- Overly playful tone in serious bug-fix or architectural change. diff --git a/.pi/skills/sce-decision/SKILL.md b/.pi/skills/sce-decision/SKILL.md index 32b74fefe..0093639f5 100644 --- a/.pi/skills/sce-decision/SKILL.md +++ b/.pi/skills/sce-decision/SKILL.md @@ -1,17 +1,18 @@ --- name: sce-decision description: > - Write one immutable ADR for one decision already qualified by context synchronization + Record one already-qualified decision as an immutable ADR, reusing an equivalent active ADR when present --- # SCE Decision ## Purpose -Write exactly one architecture decision record for one decision already qualified -by successful task context synchronization. Return a deterministic internal -result to the invoking synchronization phase. Do not render an independent -user-visible response. +Resolve exactly one architecture decision record for one decision already +qualified by successful task context synchronization. Reuse an equivalent active +ADR when one exists; otherwise write a new immutable ADR. Return a deterministic +internal result to the invoking synchronization phase. Do not render an +independent user-visible response. ## Input @@ -21,7 +22,7 @@ synchronization. It must identify: - One decision stated as a single durable choice. - Why it qualifies under the decision gate. - The implementation / task-verification evidence establishing the decision. -- The resolved plan path and relevant task IDs, when applicable. +- The resolved plan path, plus relevant task IDs when applicable. - Related current-state context and existing ADR paths. - An optional requested status. @@ -38,9 +39,9 @@ rerun that threshold here. Require the request to state why the caller qualified the decision and include supporting evidence. If the request explicitly represents a nonqualifying gate outcome, return `not_qualified` (or `skipped` when the caller deliberately skipped -the gate) without writing an ADR. If a claimed qualification is unsupported by -its supplied evidence, return `not_qualified`. Missing, contradictory, or -otherwise unsafe material input remains `blocked`. +the gate) without writing an ADR. For a qualified request, do not reassess the +qualification threshold. Missing or contradictory qualification evidence is +unsafe decision-writing input and returns `blocked`. `not_qualified` and `skipped` are non-blocking to the invoking synchronization phase. @@ -68,7 +69,8 @@ Read `context/decisions/` and the supplied related ADR paths before writing. - Reuse an existing ADR only when it records an equivalent decision and has an active status: `Proposed` or `Accepted`. Return its path without creating a duplicate. Never reuse a `Rejected`, `Deprecated`, or `Superseded` ADR. -- Existing ADRs are immutable regardless of status. Never edit an ADR whose status is `Accepted`; do not edit, overwrite, or silently change the status of any existing record. +- Existing ADRs are immutable regardless of status; never edit, overwrite, or + change the status of an existing record. - A correction, reversal, or any changed decision always creates a new dated ADR; it references and supersedes the prior record when applicable, rather than modifying that record. @@ -98,7 +100,7 @@ synchronization phase owns linking the new ADR from authoritative context. Confirm that exactly one ADR was created or one existing matching ADR was reused; the filename, status, sections, and references satisfy this contract; every -referenced repository path exists when practical to check; and no accepted ADR +referenced repository path exists when practical to check; and no existing ADR was modified. ### 6. Return the result @@ -106,11 +108,11 @@ was modified. Return exactly one internal result: - `written`: include `status`, `adr_path`, `decision`, `decision_status`, - `created` (`true` for a new ADR and `false` for reuse), `supersedes`, and - concise verification evidence. -- `not_qualified` or `skipped`: include `status`, the reason the decision gate - did not produce an ADR, and concise supporting evidence. These results are - non-blocking; the invoking synchronization phase continues normally. + `created` (`true` for a new ADR and `false` for reuse), `supersedes` (the prior + ADR path or `null`), and `verification`. +- `not_qualified` or `skipped`: include `status`, `reason`, and `evidence`. + These results are non-blocking; the invoking synchronization phase continues + normally. - `blocked`: include `status`, the specific `problem`, its `impact`, and the `required_action`. Use this only when decision writing cannot proceed safely. @@ -125,8 +127,6 @@ Do not: - Write more than one ADR per request. - Run outside successful task context synchronization. - Create a command, prompt, context root, or decisions directory. -- Modify application code, tests, plans, current-state context, or existing - accepted ADRs. -- Treat every context update as an architecture decision. +- Modify application code, tests, plans, current-state context, or existing ADRs. - Choose among unresolved material alternatives on the user's behalf. - Create a Git commit or push changes. diff --git a/.pi/skills/sce-decision/references/adr-template.md b/.pi/skills/sce-decision/references/adr-template.md index 8c2b06e77..e9e8f74f0 100644 --- a/.pi/skills/sce-decision/references/adr-template.md +++ b/.pi/skills/sce-decision/references/adr-template.md @@ -8,6 +8,10 @@ Supersedes: `{context/decisions/YYYY-MM-DD-prior-decision.md}` Omit `Task` or `Supersedes` only when it does not apply. Do not omit `Plan`. +Populate sections only from the validated request and supporting evidence. Do +not invent content to satisfy the template; when the evidence establishes no +content for a section, record `None documented.` instead. + ## Context {Forces, constraints, and evidence that require this decision.} diff --git a/.pi/skills/sce-handover/SKILL.md b/.pi/skills/sce-handover/SKILL.md index f986feda3..2b21a0f56 100644 --- a/.pi/skills/sce-handover/SKILL.md +++ b/.pi/skills/sce-handover/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Input @@ -80,14 +80,15 @@ confirmed facts. #### 4. Confirm the context root When `context/` does not exist, there is no durable location to write to. +Do not create it; `sce setup --bootstrap-context` owns context bootstrap. Render the **Writer blocked** layout with `sce setup --bootstrap-context` as the required action, and stop without writing a file. #### 5. Write exactly one file -Write the composed document to the path resolved in step 2. Before reporting -success, validate the written file against the template's **Completeness -contract**. +Write only the composed handover document to the path resolved in step 2. +Do not change plan or task state or edit any other file. Before reporting +success, validate the written file against the template's **Completeness contract**. #### 6. Report @@ -127,17 +128,3 @@ step for continuation in the current session. Loading is read-only: do not edit any file, mark a plan task complete, change repository state, or begin the recommended next step. Presenting the loaded guidance is the entire loader contract. - -## Rules - -- Handle at most one handover per invocation, in exactly one mode. -- Writer mode never overwrites an existing handover file. -- Writer mode never marks a plan task complete or edits any file outside the - one handover document it writes. -- Loader mode never edits a file, writes a new file, or changes plan or task - state. -- Never invoke another SCE skill, sibling SCE package, or SCE workflow command. -- Never treat a file outside `context/handovers/`, or a non-Markdown file, as a - loadable handover. -- Never create the `context/` root; `sce setup --bootstrap-context` owns that. -- Do not begin, plan, or automate the loaded handover's recommended next step. diff --git a/.pi/skills/sce-next-task/SKILL.md b/.pi/skills/sce-next-task/SKILL.md index 8d51c3aeb..45a7b462f 100644 --- a/.pi/skills/sce-next-task/SKILL.md +++ b/.pi/skills/sce-next-task/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command except `sce-decision`, and only from the successful context-synchronization decision gate. diff --git a/.pi/skills/sce-next-task/references/output.md b/.pi/skills/sce-next-task/references/output.md index c8a9bcbef..1ddc071ab 100644 --- a/.pi/skills/sce-next-task/references/output.md +++ b/.pi/skills/sce-next-task/references/output.md @@ -71,9 +71,6 @@ Run the final validation: # Implementation gate -Always show this gate at the start of the **Task execution phase**, before editing any -file. - The gate is user-facing prose. It is never serialized into a YAML result. This file is the only authority for the gate's content and order. @@ -104,7 +101,7 @@ file is the only authority for the gate's content and order. ## Approach -Describe the smallest coherent implementation approach in 2–5 steps. +Describe the smallest coherent implementation approach with enough detail for approval. ## Assumptions diff --git a/.pi/skills/sce-next-task/references/task-execution.md b/.pi/skills/sce-next-task/references/task-execution.md index ad9ce6373..ae68ed4c3 100644 --- a/.pi/skills/sce-next-task/references/task-execution.md +++ b/.pi/skills/sce-next-task/references/task-execution.md @@ -191,7 +191,7 @@ Set internal status `blocked` for every other non-successful outcome, including: Do not determine whether the plan is complete. The `/next-task` workflow owns that decision after context synchronization. -Before returning a `complete` result, verify that it satisfies the authoritative +A `complete` result must satisfy the authoritative handoff contract above. ## 2.9 Return the result diff --git a/.pi/skills/sce-validate/SKILL.md b/.pi/skills/sce-validate/SKILL.md index 4dc14c48c..ef058333b 100644 --- a/.pi/skills/sce-validate/SKILL.md +++ b/.pi/skills/sce-validate/SKILL.md @@ -10,12 +10,12 @@ description: > Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. -Keep internal phase results private and continue immediately until a defined wait or stop. +Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. -Render user-visible output only from the named workflow layouts or phase reports. +Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing -phase order, gates, waits, writes, validation, stops, or terminal output. +workflow order, gates, waits, writes, validation, stops, or terminal output. Do not invoke another SCE skill, package, or workflow command. ## Phase references diff --git a/.pi/skills/sce-validate/references/validation.md b/.pi/skills/sce-validate/references/validation.md index 440f21d47..5fdf8e6f9 100644 --- a/.pi/skills/sce-validate/references/validation.md +++ b/.pi/skills/sce-validate/references/validation.md @@ -250,9 +250,6 @@ a normal work session, then rerun validation. `/validate {plan path}` -Do not stop after the repair. The plan is not finished until `/validate` -returns `validated`. - --- ## Blocked report diff --git a/config/pkl/renderers/generation-contract-check.pkl b/config/pkl/renderers/generation-contract-check.pkl index acfae69d1..bf8d33a4b 100644 --- a/config/pkl/renderers/generation-contract-check.pkl +++ b/config/pkl/renderers/generation-contract-check.pkl @@ -309,9 +309,9 @@ local requiredHandoverSkillTokens = new Listing { "### Loader path (one path argument)" "references/handover-template.md" "**Completeness contract**" - "Writer mode never overwrites an existing handover file" + "Never overwrite an existing file" "Loading is read-only" - "Never invoke another SCE skill, sibling SCE package, or SCE workflow command" + "Do not invoke another SCE skill, package, or workflow command." } local requiredHandoverTemplateCompletenessTokens = new Listing { @@ -327,7 +327,7 @@ local requiredHandoverTemplateCompletenessTokens = new Listing { local requiredHandoverSkillCompletenessConsumerTokens = new Listing { "sole\nauthority for the persisted schema and **Completeness contract**" - "validate the written file against the template's **Completeness\ncontract**" + "validate the written file against the template's **Completeness contract**" "Validate the file against\nthe template's **Completeness contract**" } @@ -355,12 +355,12 @@ local expectedExecutionContract = (allowsDecision: Boolean) -> Own this workflow from input through its terminal user-visible response. Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them. - Keep internal phase results private and continue immediately until a defined wait or stop. + Keep intermediate workflow state private and continue immediately until a defined wait or stop. Resume user waits in this same skill and session. - Render user-visible output only from the named workflow layouts or phase reports. + Render user-visible output only from the named workflow layouts or reports. Do not expose raw internal state or add text around a rendered layout or report. Non-SCE helpers may assist, but must return to the active step without changing - phase order, gates, waits, writes, validation, stops, or terminal output. + workflow order, gates, waits, writes, validation, stops, or terminal output. """ + "\n" + if (allowsDecision) """ Do not invoke another SCE skill, package, or workflow command except `sce-decision`, @@ -372,10 +372,10 @@ local expectedExecutionContract = (allowsDecision: Boolean) -> local compactContractClauses = new Listing { "Own this workflow from input through its terminal user-visible response." "Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them." - "Keep internal phase results private and continue immediately until a defined wait or stop." + "Keep intermediate workflow state private and continue immediately until a defined wait or stop." "Resume user waits in this same skill and session." - "Render user-visible output only from the named workflow layouts or phase reports.\nDo not expose raw internal state or add text around a rendered layout or report." - "Non-SCE helpers may assist, but must return to the active step without changing\nphase order, gates, waits, writes, validation, stops, or terminal output." + "Render user-visible output only from the named workflow layouts or reports.\nDo not expose raw internal state or add text around a rendered layout or report." + "Non-SCE helpers may assist, but must return to the active step without changing\nworkflow order, gates, waits, writes, validation, stops, or terminal output." } hidden hasExpectedExecutionContract = (text: String, allowsDecision: Boolean) -> @@ -1235,8 +1235,8 @@ hidden assertWorkflowLanguageConsistency = (artifacts: Mapping) -> let (handoverTemplate = artifacts["config/\(target)/skills/sce-handover/references/handover-template.md"]) let (planTemplate = artifacts["config/\(target)/skills/sce-change-to-plan/references/plan-template.md"]) let (contextSync = artifacts["config/\(target)/skills/sce-next-task/references/context-sync.md"]) - next.contains("Keep internal phase results private") - && next.contains("named workflow layouts or phase reports") + next.contains("Keep intermediate workflow state private") + && next.contains("named workflow layouts or reports") && next.contains("**Implementation complete**") && commitRef.contains("# Atomic commit phase") && commitRef.contains("The phase is complete after:") From 440c3e52a7bec381b880cba9b2fa33709732d594 Mon Sep 17 00:00:00 2001 From: David Abram Date: Fri, 2 Oct 2026 11:16:44 +0200 Subject: [PATCH 8/8] workflow: Preserve validation handoff semantics Return blocked and failed validation reports without rewriting them, while allowing validated results to continue through the workflow. Extend the generation contract to enforce the shared wording across targets and canonical Pkl sources. Co-authored-by: SCE --- .agents/skills/sce-validate/SKILL.md | 16 ++++------------ .claude/skills/sce-validate/SKILL.md | 16 ++++------------ .opencode/skills/sce-validate/SKILL.md | 16 ++++------------ .pi/skills/sce-validate/SKILL.md | 16 ++++------------ config/pkl/base/workflow-content.pkl | 16 ++++------------ .../pkl/renderers/generation-contract-check.pkl | 5 +++++ 6 files changed, 25 insertions(+), 60 deletions(-) diff --git a/.agents/skills/sce-validate/SKILL.md b/.agents/skills/sce-validate/SKILL.md index 32a32ec9e..1e3689039 100644 --- a/.agents/skills/sce-validate/SKILL.md +++ b/.agents/skills/sce-validate/SKILL.md @@ -71,18 +71,12 @@ Do not write the Validation Report yourself. Branch on the report's `Status:`. -`blocked` -> Print the blocked Markdown report as returned. Do not rephrase it -into a different layout. Stop. +`blocked` -> Return the blocked Markdown report unchanged. Stop. -`failed` -> Print the failed Markdown report as returned. It is already a session -handoff: self-contained, actionable, and ending with `/validate {plan-path}` after -repairs. +`failed` -> Return the failed Markdown handoff unchanged. Stop. -Do not rewrite it into a shorter summary. Do not drop the retry command. Do not -add an alternate continuation that replaces `/validate`. Stop. - -`validated` -> Print the complete validated Markdown result as returned. -Continue to the next step. +`validated` -> Return the complete validated Markdown result, then continue to +the next step. ### 2. Report completion @@ -101,8 +95,6 @@ Stop. returns `blocked`, and this workflow stops. - On `failed`, print the handoff Markdown as returned and stop. Preserve the retry `/validate {plan-path}` instruction. -- Do not implement remaining plan tasks from this workflow unless the user - explicitly continues in-session after a failed handoff. - Do not create a Git commit or push changes. - Do not mark the plan archived or delete the plan. - Do not execute a follow-up `/next-task`, `/change-to-plan`, or `/validate` diff --git a/.claude/skills/sce-validate/SKILL.md b/.claude/skills/sce-validate/SKILL.md index 284028f66..7dd3a59ae 100644 --- a/.claude/skills/sce-validate/SKILL.md +++ b/.claude/skills/sce-validate/SKILL.md @@ -70,18 +70,12 @@ Do not write the Validation Report yourself. Branch on the report's `Status:`. -`blocked` -> Print the blocked Markdown report as returned. Do not rephrase it -into a different layout. Stop. +`blocked` -> Return the blocked Markdown report unchanged. Stop. -`failed` -> Print the failed Markdown report as returned. It is already a session -handoff: self-contained, actionable, and ending with `/validate {plan-path}` after -repairs. +`failed` -> Return the failed Markdown handoff unchanged. Stop. -Do not rewrite it into a shorter summary. Do not drop the retry command. Do not -add an alternate continuation that replaces `/validate`. Stop. - -`validated` -> Print the complete validated Markdown result as returned. -Continue to the next step. +`validated` -> Return the complete validated Markdown result, then continue to +the next step. ### 2. Report completion @@ -100,8 +94,6 @@ Stop. returns `blocked`, and this workflow stops. - On `failed`, print the handoff Markdown as returned and stop. Preserve the retry `/validate {plan-path}` instruction. -- Do not implement remaining plan tasks from this workflow unless the user - explicitly continues in-session after a failed handoff. - Do not create a Git commit or push changes. - Do not mark the plan archived or delete the plan. - Do not execute a follow-up `/next-task`, `/change-to-plan`, or `/validate` diff --git a/.opencode/skills/sce-validate/SKILL.md b/.opencode/skills/sce-validate/SKILL.md index 80c3e3f41..5f6134ff3 100644 --- a/.opencode/skills/sce-validate/SKILL.md +++ b/.opencode/skills/sce-validate/SKILL.md @@ -70,18 +70,12 @@ Do not write the Validation Report yourself. Branch on the report's `Status:`. -`blocked` -> Print the blocked Markdown report as returned. Do not rephrase it -into a different layout. Stop. +`blocked` -> Return the blocked Markdown report unchanged. Stop. -`failed` -> Print the failed Markdown report as returned. It is already a session -handoff: self-contained, actionable, and ending with `/validate {plan-path}` after -repairs. +`failed` -> Return the failed Markdown handoff unchanged. Stop. -Do not rewrite it into a shorter summary. Do not drop the retry command. Do not -add an alternate continuation that replaces `/validate`. Stop. - -`validated` -> Print the complete validated Markdown result as returned. -Continue to the next step. +`validated` -> Return the complete validated Markdown result, then continue to +the next step. ### 2. Report completion @@ -100,8 +94,6 @@ Stop. returns `blocked`, and this workflow stops. - On `failed`, print the handoff Markdown as returned and stop. Preserve the retry `/validate {plan-path}` instruction. -- Do not implement remaining plan tasks from this workflow unless the user - explicitly continues in-session after a failed handoff. - Do not create a Git commit or push changes. - Do not mark the plan archived or delete the plan. - Do not execute a follow-up `/next-task`, `/change-to-plan`, or `/validate` diff --git a/.pi/skills/sce-validate/SKILL.md b/.pi/skills/sce-validate/SKILL.md index ef058333b..54f1868da 100644 --- a/.pi/skills/sce-validate/SKILL.md +++ b/.pi/skills/sce-validate/SKILL.md @@ -69,18 +69,12 @@ Do not write the Validation Report yourself. Branch on the report's `Status:`. -`blocked` -> Print the blocked Markdown report as returned. Do not rephrase it -into a different layout. Stop. +`blocked` -> Return the blocked Markdown report unchanged. Stop. -`failed` -> Print the failed Markdown report as returned. It is already a session -handoff: self-contained, actionable, and ending with `/validate {plan-path}` after -repairs. +`failed` -> Return the failed Markdown handoff unchanged. Stop. -Do not rewrite it into a shorter summary. Do not drop the retry command. Do not -add an alternate continuation that replaces `/validate`. Stop. - -`validated` -> Print the complete validated Markdown result as returned. -Continue to the next step. +`validated` -> Return the complete validated Markdown result, then continue to +the next step. ### 2. Report completion @@ -99,8 +93,6 @@ Stop. returns `blocked`, and this workflow stops. - On `failed`, print the handoff Markdown as returned and stop. Preserve the retry `/validate {plan-path}` instruction. -- Do not implement remaining plan tasks from this workflow unless the user - explicitly continues in-session after a failed handoff. - Do not create a Git commit or push changes. - Do not mark the plan archived or delete the plan. - Do not execute a follow-up `/next-task`, `/change-to-plan`, or `/validate` diff --git a/config/pkl/base/workflow-content.pkl b/config/pkl/base/workflow-content.pkl index 201dde0cc..588948945 100644 --- a/config/pkl/base/workflow-content.pkl +++ b/config/pkl/base/workflow-content.pkl @@ -442,18 +442,12 @@ Do not write the Validation Report yourself. Branch on the report's `Status:`. -`blocked` -> Print the blocked Markdown report as returned. Do not rephrase it -into a different layout. Stop. +`blocked` -> Return the blocked Markdown report unchanged. Stop. -`failed` -> Print the failed Markdown report as returned. It is already a session -handoff: self-contained, actionable, and ending with `/validate {plan-path}` after -repairs. +`failed` -> Return the failed Markdown handoff unchanged. Stop. -Do not rewrite it into a shorter summary. Do not drop the retry command. Do not -add an alternate continuation that replaces `/validate`. Stop. - -`validated` -> Print the complete validated Markdown result as returned. -Continue to the next step. +`validated` -> Return the complete validated Markdown result, then continue to +the next step. ### 2. Report completion @@ -472,8 +466,6 @@ Stop. returns `blocked`, and this workflow stops. - On `failed`, print the handoff Markdown as returned and stop. Preserve the retry `/validate {plan-path}` instruction. -- Do not implement remaining plan tasks from this workflow unless the user - explicitly continues in-session after a failed handoff. - Do not create a Git commit or push changes. - Do not mark the plan archived or delete the plan. - Do not execute a follow-up `/next-task`, `/change-to-plan`, or `/validate` diff --git a/config/pkl/renderers/generation-contract-check.pkl b/config/pkl/renderers/generation-contract-check.pkl index bf8d33a4b..553e5b170 100644 --- a/config/pkl/renderers/generation-contract-check.pkl +++ b/config/pkl/renderers/generation-contract-check.pkl @@ -1230,6 +1230,7 @@ hidden assertWorkflowLanguageConsistency = (artifacts: Mapping) -> if ( targets.every((target) -> let (next = artifacts["config/\(target)/skills/sce-next-task/SKILL.md"]) + let (validate = artifacts["config/\(target)/skills/sce-validate/SKILL.md"]) let (commitRef = artifacts["config/\(target)/skills/sce-commit/references/atomic-commit.md"]) let (validationRef = artifacts["config/\(target)/skills/sce-validate/references/validation.md"]) let (handoverTemplate = artifacts["config/\(target)/skills/sce-handover/references/handover-template.md"]) @@ -1255,6 +1256,10 @@ hidden assertWorkflowLanguageConsistency = (artifacts: Mapping) -> && !next.contains("Record only the internal state") && !validationRef.contains("Markdown result") && !validationRef.contains("Validation Result") + && validate.contains("Return the blocked Markdown report unchanged") + && validate.contains("Return the failed Markdown handoff unchanged") + && !validate.contains("Do not rewrite it into a shorter summary") + && !validate.contains("Do not implement remaining plan tasks") ) ) "workflow language: shared vocabulary, phase naming, report naming, and document format are consistent" else throw("generated workflow language/format drifted from the shared T11 conventions")