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..1e3689039 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 @@ -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/.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..7dd3a59ae 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 @@ -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/.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..5f6134ff3 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 @@ -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/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..54f1868da 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 @@ -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/.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/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/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 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/config/pkl/base/workflow-content.pkl b/config/pkl/base/workflow-content.pkl index cff15cbb6..588948945 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`, @@ -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/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 { 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 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 diff --git a/config/pkl/renderers/generation-contract-check.pkl b/config/pkl/renderers/generation-contract-check.pkl index cb689a8c7..553e5b170 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" @@ -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) -> @@ -1230,13 +1230,14 @@ 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"]) 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:") @@ -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") 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