config: Normalize workflow language and format

Author: davidabram

.agents/skills/sce-change-to-plan/SKILL.md

@@ -10,10 +10,10 @@ 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 phase results internal and continue immediately until a defined wait or stop.
+Keep internal phase results private and continue immediately until a defined wait or stop.
 Resume user waits in this same skill and session.
-Use only the specified `references/output.md` layouts for gates and terminal
-responses. Do not expose raw state or add text around a layout.
+Render user-visible output only from the named workflow layouts or phase 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.
 Do not invoke another SCE skill, package, or workflow command.

.agents/skills/sce-change-to-plan/references/context-load.md

@@ -61,15 +61,15 @@ sentence.
 
 ## 1.5 Return the brief
 
-Set exactly one internal state:
+Return one internal result with one of these statuses:
 
 - `loaded`
 - `bootstrap_required`
 
 Report facts the workflow can act on. A brief that only lists file paths has
 moved no knowledge.
 
-Record only the internal state. Do not add explanatory prose before or after it.
+Return only the internal result. Do not add explanatory prose before or after it.
 
 Step 2 consumes a `loaded` brief verbatim and treats its `key_facts` as recorded
 current state, its `gaps` as areas with no durable context, and its `drift` as

.agents/skills/sce-change-to-plan/references/output.md

@@ -48,7 +48,7 @@ candidate plan paths and explain that naming one candidate resolves it.
 
 This plan is a draft. State a correction and it will be updated.
 
-Next up:
+Next step:
 
 {next-task-id} — {next-task-title}
 
@@ -71,17 +71,17 @@ This is chat output, not a file. Nothing here is written to the plan.
 
 Path: {plan.path}
 
-## Summary:
+## Summary
 {plan summary}
 
-## Tasks:
+## Tasks
 1. {task.id} — {task.title}
 2. {task.id} — {task.title}
 
-## Assumptions:
+## Assumptions
 - {assumption}
 
-## Open questions:
+## Open questions
 - {open question}
 ```
 
@@ -93,13 +93,13 @@ not carry.
 - `Plan:` — `plan.name`. Append ` (updated)` when `plan.action` is `updated`.
   Render nothing extra when it is `created`.
 - `Path:` — `plan.path`, exactly as returned, so it stays runnable.
-- `Summary:` — `summary`, as prose. This is the only place the reader learns
+- `Summary` — `summary`, as prose. This is the only place the reader learns
   what the plan actually does, so never omit it and never replace it with a
   restatement of the task titles.
-- `Tasks:` — one numbered line per entry in `tasks`, in plan order. Append
+- `Tasks` — one numbered line per entry in `tasks`, in plan order. Append
   ` (done)` to any task whose `status` is `done`.
-- `Assumptions:` — one line per entry in `assumptions`.
-- `Open questions:` — one line per entry in `open_questions`.
+- `Assumptions` — one line per entry in `assumptions`.
+- `Open questions` — one line per entry in `open_questions`.
 
 ## Empty sections
 
@@ -109,14 +109,14 @@ explicit `None.` confirms nothing is pending.
 When `assumptions` is empty:
 
 ```
-## Assumptions:
+## Assumptions
 - None.
 ```
 
 When `open_questions` is absent:
 
 ```
-## Open questions:
+## Open questions
 - None.
 ```
 
@@ -137,16 +137,16 @@ When `open_questions` is absent:
 
 Path: context/plans/red-sce-banner.md
 
-## Summary:
-Renders the ASCII-art SCE banner at the top of `sce` help in red instead of the current gradient. Colour-disabled output is unchanged, and no other help surface is affected.
+## Summary
+Renders the ASCII-art SCE banner at the top of `sce` help in red instead of the current gradient. Color-disabled output is unchanged, and no other help surface is affected.
 
-## Tasks:
+## Tasks
 1. T01 — Render the SCE banner in red
 
-## Assumptions:
+## Assumptions
 - "SCE letters" refers to the ASCII-art banner in top-level help.
 - Red is uniform terminal red when colors are enabled; plain ASCII remains unchanged otherwise.
 
-## Open questions:
+## Open questions
 - None.
 ```

.agents/skills/sce-change-to-plan/references/plan-authoring.md

@@ -28,7 +28,7 @@ responsibility.
 
 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 context the code has already outrun.
+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*.
@@ -178,43 +178,27 @@ exactly. For revisions, apply its `Updating an existing plan` rules.
 
 ## 2.8 Return the result
 
-Set exactly one internal state:
+Return one internal result with one of these statuses:
 
 - `plan_ready`
 - `needs_clarification`
 - `blocked`
 
-Record only the internal state. Do not add explanatory prose before or after it.
+Return only the internal result. Do not add explanatory prose before or after it.
 
 A `plan_ready` result always names the next task in `next_task`, and carries the
 `total_tasks` count and any open questions the summary needs. Step 3 renders those
 without recomputing them.
 
 ## Plan authoring tone
 
-Every question and open question this phase writes is read by the user. Write
-them the way a senior engineer talks in review: direct, specific, and unbothered
-by the possibility of being unwelcome.
-
-- Ask about the thing that actually worries you, not a safer neighbouring thing.
-  A question you would not bother asking a colleague is not worth the user's
-  attention either.
-- State a doubt as a doubt. "I do not think this is worth the two tasks it
-  costs, because X" is useful. "It may be worth considering whether this aligns
-  with broader goals" is noise.
-- Name the alternative you have in mind. A challenge with no proposal behind it
-  is just friction.
-- Do not open with praise, do not close with reassurance, and do not apologize
-  for asking. Do not pad a doubt with hedges to make it land more gently.
-- Be persistent, not repetitive. Ask once, plainly, and let it stand; do not
-  restate the same doubt in three shapes to give it more weight.
-- Being disagreeable is not the goal. Being easy to agree with is the failure
-  mode. A plan the user waves through without reading has cost them nothing and
-  bought them nothing.
-
-When the user overrules a doubt, record it and move on. Do not relitigate a
-decision the user has made, and do not smuggle the objection back in as a
-constraint, a non-goal, or a task.
+Write user-facing questions and open questions directly and specifically.
+
+- Ask only about material concerns that can change scope, success criteria, or task ordering.
+- State the concern and the concrete evidence for it.
+- Name a smaller or safer alternative when one is known.
+- Do not invent concerns, add praise or reassurance, or repeat the same concern in several forms.
+- When the user overrules a concern, record the decision and continue. Do not reintroduce it as a constraint, non-goal, or task.
 
 ## Plan authoring boundaries
 

.agents/skills/sce-change-to-plan/references/plan-template.md

@@ -146,9 +146,9 @@ invent one: `None.` is the expected answer for a well-specified change.}
 
 - The last task in the stack is an ordinary implementation task. Do not author a
   trailing "validation and cleanup" task.
-- Final validation, cleanup, and success-criteria verification are run by
-  `/validate` from the `Acceptance criteria` section after the last task
-  completes.
+- Final validation and success-criteria verification are run by `/validate`
+  from the `Acceptance criteria` section after the last task completes. Validation
+  reports cleanup or repair work that is still required; it does not perform that work.
 - Do not author a task whose only purpose is running the full check suite,
   verifying durable context, or removing scaffolding.
 - A task may still create or update durable context when that context is part of

.agents/skills/sce-commit/SKILL.md

@@ -10,10 +10,10 @@ 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 phase results internal and continue immediately until a defined wait or stop.
+Keep internal phase results private and continue immediately until a defined wait or stop.
 Resume user waits in this same skill and session.
-Use only the specified `references/output.md` layouts for gates and terminal
-responses. Do not expose raw state or add text around a layout.
+Render user-visible output only from the named workflow layouts or phase 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.
 Do not invoke another SCE skill, package, or workflow command.
@@ -99,14 +99,14 @@ Run `git diff --cached --quiet`. A zero exit status means nothing is staged.
 When nothing is staged, stop with the **No staged changes** layout from
 `references/output.md`.
 
-Do not stage anything. Do not proceed to the skill.
+Do not stage anything. Do not proceed to the phase.
 
 #### 2. Request one commit message
 
 Read `references/atomic-commit.md`, then run the **Atomic commit phase** with
 `mode: bypass` and the commit context.
 
-Bypass mode is the skill's contract for producing exactly one message. Do not
+Bypass mode is the phase's contract for producing exactly one message. Do not
 restate its overrides here; the **Atomic commit phase** owns them.
 
 Branch on `status`:
@@ -115,7 +115,7 @@ Branch on `status`:
 
 `bypass_message` -> Continue to the next step.
 
-The skill never returns `proposal` in bypass mode. Treat a `proposal` result as
+The phase never returns `proposal` in bypass mode. Treat a `proposal` result as
 a contract violation: report it and stop without committing.
 
 #### 3. Execute exactly one commit

.agents/skills/sce-commit/references/atomic-commit.md

@@ -1,4 +1,4 @@
-# SCE Atomic Commit
+# Atomic commit phase
 
 ## Purpose
 
@@ -8,8 +8,8 @@ Write messages matching:
 
 `references/commit-message-style.md`
 
-Committing is not this skill's job. The invoking `/commit` workflow decides
-whether a returned message is committed, and it is the only thing that runs
+This phase does not commit. The invoking `/commit` workflow decides
+whether a returned message is committed, and it is the only part that runs
 `git commit`.
 
 ## Input
@@ -147,7 +147,7 @@ Do not:
 
 ## Completion
 
-The skill is complete after:
+The phase is complete after:
 
 - The staged diff was read, or reading it failed and was reported.
 - Messages were written for every staged file, or a blocker prevented it.

.agents/skills/sce-handover/SKILL.md

@@ -10,10 +10,10 @@ 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 phase results internal and continue immediately until a defined wait or stop.
+Keep internal phase results private and continue immediately until a defined wait or stop.
 Resume user waits in this same skill and session.
-Use only the specified `references/output.md` layouts for gates and terminal
-responses. Do not expose raw state or add text around a layout.
+Render user-visible output only from the named workflow layouts or phase 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.
 Do not invoke another SCE skill, package, or workflow command.

.agents/skills/sce-handover/references/handover-template.md

@@ -1,8 +1,10 @@
+# Handover document format
+
 The Markdown document writer mode creates under
 `context/handovers/{name}.md`. This is the persisted file's content, distinct
 from the terminal response defined in `references/output.md`.
 
-### Layout
+## Template
 
 ```markdown
 # Handover: {plan name or short session topic}
@@ -35,9 +37,9 @@ enough to act on directly.}
   `None.`}
 ```
 
-### Completeness contract
+## Completeness contract
 
-- The first four `##` sections shown in **Layout** are required and must appear
+- The first four `##` sections shown in **Template** are required and must appear
   in that order.
 - Each required section's content, up to the next `##` heading or the end of the
   file, must contain non-whitespace content. An empty list marker, unreplaced
@@ -47,10 +49,10 @@ enough to act on directly.}
 - Writer mode must satisfy this contract before reporting success; loader mode
   validates the same contract before presenting a handover.
 
-### Rules
+## Rules
 
-- Include `Plan` and `Task` only when the session was working one identifiable
-  plan task; omit them rather than guessing.
+- Include `Plan` when one plan is known. Include `Task` only when one task is
+  known. Omit either field rather than guessing its value.
 - Keep `Assumptions` scoped to details actually labeled as inferred elsewhere
   in the document; do not duplicate confirmed facts here.
 - Describe durable state useful to a future session, not a transcript of this

.agents/skills/sce-handover/references/output.md

@@ -83,7 +83,7 @@ This handover has been presented for continuation only. No file was edited, no
 plan task was marked complete, and the recommended next step was not started.
 ```
 
-# Report rules
+## Report rules
 
 - Writer success must report the exact written path so
   `/handover {written path}` is directly runnable.