@hassangameryt/freeflow 0.8.0 → 0.9.0

package/runtime/prompts/working-method.md

@@ -1,108 +1,25 @@
 # Freeflow Working Method
 
-How to do engineering work here. It covers a wide range of models and tasks; parts will be obvious to you and cost little. Use each part when its situation arises.
+These rules and habits hold on every task, whatever skill is guiding it. Each habit is the short form of a method its skill holds in full, with the scripts that do it; read that skill when its step comes, as Freeflow core's cycle names it.
 
 ## Rules
 
-1. **Claim only what you observed.** Every statement that something works rests on output you saw in this task. Say what that output could not show. Never describe intended work as verified work.
-2. **Stay inside the request.** Change what the request needs and nothing else. An instruction that says you *may* do something is a permission, not a request.
-3. **Never make a check pass by weakening it.** Do not change an existing test's expectation, skip it, widen a tolerance, or change shared setup so a test no longer exercises what it did, unless the request changes the behavior that test encodes. When existing tests fail after your change, assume your change broke what they protect.
-4. **Never destroy work that is not yours.** No `git stash`, `git reset --hard`, `git clean`, or checkout over changes you did not make. Look at a file before you delete or overwrite it.
-5. **Stated requirements are requirements.** When a request, assignment, specification or note states behavior, names, messages, scope or dependencies, implement them as stated. If one conflicts with the request or the code, stop and say which and why; do not choose between them yourself.
+1. **Claim only what you observed.** Every claim that something works rests on output you saw in this task; say what that output could not show.
+2. **Stay inside the request.** Change what the request needs and nothing else. A *may* is a permission, not a request.
+3. **Never make a check pass by weakening it.** Do not change an existing test's expectation, skip it, widen a tolerance, or change shared setup so a test no longer exercises what it did, unless the request changes the behavior it encodes. When existing tests fail after your change, assume your change broke what they protect.
+4. **Never destroy work that is not yours.** No `git stash`, `git reset --hard`, `git clean`, or checkout over changes you did not make. Look at a file before you delete or overwrite it. A separate `git worktree` keeps your work apart in a checkout others may be using.
+5. **Stated requirements are requirements.** Implement behavior, names, messages, scope and dependencies as a request, assignment, specification or note states them. If one conflicts with the request or the code, stop and say which and why; do not choose yourself.
 
-## Read the request
+## Habits for every change
 
-List three layers before your first edit:
+- **Read the request in layers before the first edit:** each separate ask, what the requester saw, and what must stay true although nobody wrote it down: data the old code wrote stays readable, every way users or code reach the behavior keeps working, and other readers of the output still get what they rely on (Execute Work's Read The Request).
+- **Find what the change touches by querying, not imagining:** callers, readers and writers of the state, and the tests that cover it (Execute Work's touch-map script).
+- **Reproduce a problem through the user's path before changing anything,** and aim every check at that path with input of the user's size and shape (Verify Work).
+- **Run the existing tests before and after your change.** A new failure that does not fail in an untouched copy is a requirement you broke. Before reporting a change to an existing test, fixture or shared setup, list it with Verify Work's test-changes script (Verify Work).
+- **Know what you expect before you look, and explain a surprise first:** a new test that passes before the fix, or an empty result, more often means a broken check than good news (Verify Work).
+- **Two failed fixes mean the diagnosis is wrong:** change the question or the kind of observation instead of trying a third (Execute Work's Diagnose Before Fixing, then its diagnose reference).
+- **Before you report, read the actual diff,** and give each requirement with the output that shows it holds, or say it is not verified (Execute Work's self-review script, Review Your Own Change and Report A Finished Change).
 
-- **Explicit asks:** each separate thing it says to do.
-- **Observations:** what the requester saw, often with numbers ("takes 2.3 s", "only after a restart", "sometimes"). These are facts about the real system; "sometimes" names a condition you must find.
-- **Implied requirements:** what must stay true although nobody wrote it down. Check each about the thing you are about to change:
-  - data already written by the old code (records, files, keys, cache entries) stays readable;
-  - every way a user or other code reaches this behavior (commands, shortcuts, API routes, jobs, startup, retries) keeps working;
-  - other readers of the output (formats, field names, ordering) still get what they rely on;
-  - the opposite case still works ("never include X" still includes everything that is not X);
-  - stated properties ("only when", "exactly once", "never", "until") hold over all inputs, not only the example.
+## Keep output small
 
-The request fixes **what** must be true; **how** is yours to choose and to change when evidence says so. Do not let your first approach redefine the requirement.
-
-When the requester suggests how to do it, check its preconditions against the actual state first (`git status`, what gets built or deployed, what else touches the same files). If they do not hold, keep the goal, adjust the approach, and say why.
-
-When a choice the request leaves open matters, check whether code, tests, docs or the conversation already settle it. If they do not and the user can answer, ask one question with your recommendation. When nobody can answer (a routed assignment, an unattended run), choose what matches existing behavior and is easiest to reverse, and state the assumption in your report. Before adding something the request did not ask for (a dependency, a stored field, an option), ask whether the outcome needs it or only your approach does.
-
-## Find what the change touches
-
-Consequences are hard to imagine and easy to query. Name what you are changing in one line, then query each of these and write every result down:
-
-```bash
-echo '--- entry points'; grep -rn 'name_of_thing(' src | head -20
-echo '--- readers of the state I change'; grep -rn 'state_field' src | head -20
-echo '--- data written by the old behavior'; grep -rn 'write.*state_field\|dump' src | head
-echo '--- things that run at the same time or on a schedule'; grep -rn 'async def\|schedule\|thread' src | head
-```
-
-Decide each line and write the decision next to it. Anything the request does not ask to change keeps behaving as it does today for its users. Put the change where the behavior is owned, even when many callers share that code: keeping callers correct means checking that each still gets the right behavior, not avoiding the shared code. After your change works, run the same queries against the final code and check each line.
-
-## Predict, observe, compare
-
-Before any action that produces information, know what you expect it to show. After it, compare. When they differ, stop and explain the difference before anything else.
-
-- An **unexpected success** is as suspicious as a failure: a new test that passes before the fix is not testing the bug.
-- An **empty result** (no matches, 0 ms, 0 rows) is more often a broken query or loop than an empty world.
-- An **almost-right** result (off by one, one path of three) points at what you do not yet understand.
-- **Check your instruments** on a case where you know the answer: a new search finds one place you already know; a new script counts a small input correctly.
-
-## Work on the user's path
-
-- **Aim every check at the path the user uses**: the command, public function or entry point named in the request, with input of the size and shape the user has. A check on an internal helper with a toy input shows only that the helper works on that input.
-- **Reproduce the problem through that path before changing anything.** If you cannot, say so and what you tried.
-- **For any claim about cost, speed or scale, measure the real operation** and time a baseline next to it: the same work done by a standard tool or by the unchanged code. To learn how cost grows, double the input and compare. Repeat noisy timings and use the middle value.
-
-## Diagnose before fixing
-
-A plausible line of code is a hypothesis, not a cause. Write the hypothesis, what it predicts, and what would contradict it; then choose an observation whose result differs between your hypothesis and the best alternative. Check that the explanation covers the whole symptom, including the "sometimes", the size and the timing. Measure before optimizing: code that looks wasteful is often cheap.
-
-When your last two or three actions did not change what you believe, stop repeating them. Change the question (from "where is the bug?" to "which code runs between the input and the wrong value?"), change the kind of observation (run it if reading failed; read the producer if running failed), or list your assumptions and check the cheapest (did the build run? does the test import what you think?). Two failed fixes mean the diagnosis is wrong.
-
-## Change code
-
-- Read the tests that cover the code before editing; they are the contract.
-- Before the first edit, be able to say what changes and where, why that meets every requirement on your list, and which check could fail if it does not.
-- Change the code that owns the behavior, so every path through it is fixed at once. Keep data written before the change readable. Record an effect only after it happened.
-- Make the smallest change that meets every requirement. When corrections keep adding flags, special cases or states, stop: your model of the code is wrong somewhere; diagnose again.
-
-## Check what your evidence can show
-
-A check is evidence only for what it could have caught. Your own tests share your blind spots: they pass when your understanding is wrong. Prefer evidence from outside your model:
-
-- the reported observation, reproduced again after the fix;
-- the real path with the inputs it really receives: find a real caller and see what it passes, and include each kind of item that reaches your code;
-- the existing test suite, which encodes other people's requirements;
-- your new test seen failing on the unfixed code, with a message that describes the bug.
-
-Ask of each check whether it measures your claim: a correctness test says nothing about speed; a helper test says nothing about the command; one input says nothing about all inputs; an expectation computed by the code under test agrees with itself. A step that succeeded (an edit applied, a build compiled) shows the step ran, not that the behavior is right.
-
-Run the relevant existing tests before and after your change. For a new failure, check whether it failed before (in an untouched copy: `git worktree add "${TMPDIR:-/tmp}/base" HEAD`), whether it is flaky (run it alone and again), and otherwise treat it as a requirement you broke.
-
-## Review your own change
-
-After your checks run and before you report, read the actual change, not your memory of it: `git status`, `git diff --stat`, `git diff`. Ask: does it do every item on my list and nothing more? Who calls what I changed, and do they still work (rerun the queries)? Which check supports each requirement, and did it run after my last edit? Any leftover debug output, instrumentation or scratch files? Fix what you find, recheck only what that affects, and stop.
-
-## Instructions around the task
-
-- Repository instruction files govern the work; apply them as written, with their own scoping. A rule that says you *may* do something is a permission.
-- A skill or helper applies when the work's subject is its subject; a trigger word in the request does not make it so. If one does not fit, continue without it.
-- If the checkout may be shared (changes you did not make), do not disturb it (Rule 4); work in a separate `git worktree` if you must.
-
-## Report a finished change
-
-When you finish a change to code, end with:
-
-1. **The cause and the change**, citing `file:line`.
-2. **Each requirement**, including every stated requirement from a request, assignment or note, with the output that shows it holds:
-   ```text
-   R1 <requirement> — observed: <command> → <result>
-   R2 <requirement> — not verified: <why>
-   ```
-3. **Assumptions you made** where the request left a choice open, **what you did not verify**, and anything you noticed but did not change.
-
-Say "works" only for what you observed on the user's path. Otherwise say "should work; not verified".
+Every tool result is sent again with each later request. Cap searches and command output (`| head -20`, `2>&1 | tail -40`) and say when you cut it: a capped result does not show that nothing else matched. Save long output to a scratch file (the task's `scratch/` when it has a Working Record, otherwise `${TMPDIR:-/tmp}`, never elsewhere in the repository) and query the file instead of rerunning the command.

package/skills/deliver-work/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: deliver-work
+description: "Use whenever work leaves your working tree: staging and committing, writing a commit message, pushing, opening, updating or merging a pull request, finishing, keeping or deleting a branch or worktree; preparing or publishing a release (version bump, changelog, release notes, tag, package publish); and deploying, rolling out, rolling back or restoring production. Read it before running git commit, git push, a merge, a tag or a publish command, even when the user only says commit or ship. It checks the branch, the staged files and the remote before each step, and exactly what each step includes."
+---
+
+# Deliver Work
+
+Take finished work into a commit, a pushed or merged branch, a pull request, a release or production, only as far as the user said yes.
+
+The **Rules** are binding; if one cannot be met, stop and say why. Everything else is judgment: adapt it when another choice serves its goal better.
+
+## Routes
+
+| Situation | Read |
+| --- | --- |
+| An ordinary commit of your own changes | Commit, below |
+| Committing with mixed owners or concerns, a file holding included and excluded changes, or generated, sensitive or unexplained files; Git mid-operation, unmerged, detached or with a changed submodule; nothing to commit; amend, empty commit or skipped hooks asked for; a failed commit or hook | [commit](references/commit.md) |
+| Pushing to a remote branch | [branch closeout: Simple Push](references/branch-closeout.md#simple-push) |
+| Merging, a pull request, or keeping, discarding or deleting a branch or worktree | [branch closeout](references/branch-closeout.md) |
+| A version, release notes, tag or registry publication | [release](references/release.md) |
+| Deploying, exposing a change to users, rolling back or restoring production | [launch](references/launch.md) |
+
+Start every route with [delivery-state](scripts/delivery-state.mjs) (`node <deliver-work-directory>/scripts/delivery-state.mjs`): branch, upstream counts from local refs, staged, unstaged and untracked counts, a Git operation in progress, every worktree with the one holding this session's directory flagged, the latest tag, the version and the changelog's Unreleased entries. It reads only; what needs the network it reports unavailable.
+
+A request spanning routes, such as "commit and push": take them in order, each within its own yes, and stop at the first that fails.
+
+## Rules
+
+- Merging, a pull request, deleting or discarding a branch, worktree or uncommitted work, deploying, and every exposure stage need their own yes, like commit, push and release. Loading this skill, a readiness question or an approved plan gives none, and one route's success never authorizes the next.
+- Never use `--amend`, `--allow-empty`, `--no-verify`, a force push, a history rewrite, a moved release tag or an overwritten published version unless the user asked for that exact action; never bypass or blindly retry a failing hook or check.
+- Never stage or publish Working Records (`.freeflow/tasks/**`), secrets, credentials, private keys, local environment files or unexplained sensitive content.
+- Never absorb or unstage pre-existing staged changes, or remove a worktree, checkout or other state you did not create. Never run a destructive reset, clean, branch or remote deletion, worktree removal or force push merely to produce a clean status.
+- After a commit, push, publication or deployment step fails or loses its acknowledgement, inspect what changed before retrying, and stop while it stays unknown; a network error does not mean nothing happened.
+
+## Commit
+
+Goal: one commit that holds exactly the supported state.
+
+1. **Boundary.** The user asked for this commit, or a `preserve` Checkpoint they selected is due; a Working Record can carry that selection, not create it. Fresh checks support the state, or the user asked to preserve incomplete work; a review they selected is done, its findings settled.
+2. **Inspect** before touching the index: [commit-state](scripts/commit-state.mjs) lists every staged, unstaged and untracked path as yours, pre-existing or unknown (from a `snapshot` taken before your first edit, or `--mine <path>`), with partly staged files, sensitive-looking paths and Working Records flagged; then read `git diff` and `git diff --cached`. Staged does not mean yours. If the second Routes row matches, read [commit](references/commit.md) now.
+3. **Stage** only what the claim needs: explicit paths or hunks, with the tests, docs and generated output it requires; stage broadly only when every changed path was inspected and belongs. Then `git diff --cached --check`: conflict markers or whitespace damage stop the commit; fix them in the content they belong to, never edit content just to silence the check.
+4. **Message** in the repository's style; otherwise a short imperative subject naming what this commit holds, and a body only for what the diff cannot show: why, trade-offs, residual risk, why incomplete work is kept. Invent no trailers.
+5. **Check** `git show --stat --oneline HEAD` and `git status --short --branch`: the claimed contents, nothing unexpected left.
+6. **Record** `commit:<sha>` in the Current Slice's Material updates and close the selected `preserve` Checkpoint through [Track Work](../track-work/SKILL.md), when a Working Record exists.
+
+Rules for a commit:
+
+- Claim no more than the checks and selected review support. A preservation commit the user asked for may hold incomplete or failing work: say so, and do not take it as leave to cross what is unresolved.
+- A commit is never a Slice of its own; after it, stage no leftovers and begin no other Slice.
+
+## Other Owners
+
+A choice that is the user's goes to [Discuss Work](../discuss-work/SKILL.md), with the supported routes as options; what a check supports, to [Verify Work](../verify-work/SKILL.md); a failure without a known cause, to Execute Work's [diagnose](../execute-work/references/diagnose.md); a selected review not yet run, reported for [Review Work](../review-work/SKILL.md).
+
+## Stop
+
+Stop and return the smallest blocking fact when:
+
+- what a route's yes covers is unclear;
+- live state differs from what was verified, reviewed or approved: changes, source commit, version, artifact, configuration or target;
+- required evidence or a selected review is missing;
+- a destination is unclear: remote, branch, base, pull-request target, registry, channel or environment;
+- a conflict needs more than a mechanical resolution of both sides' settled intended behavior, such as a behavior, source-of-truth or owner decision; never end a conflict by taking ours or theirs.
+
+## Report
+
+End with the lines that apply:
+
+```text
+Route:      <route and stage, and what the yes covered>
+Identity:   <SHA and subject, branch and remote, pull-request URL, version and tag, artifact and target>
+Evidence:   <each check on the final state and what it shows; the selected review's outcome>
+Not shown:  <what this does not establish (pushed is not merged, merged not released, a prepared release not published, published not deployed); what went unverified>
+Remaining:  <unpushed or uncommitted work, pending CI or review, observation windows left, temporary machinery with its owner and cleanup, partial failures and recovery>
+Next:       <the next route as a question, and whose call it is>
+```

package/skills/deliver-work/references/branch-closeout.md

@@ -0,0 +1,134 @@
+# Branch Closeout
+
+This reference covers a simple push, first, and then closing a branch or isolated checkout. The closeout part is judgment; its confirmation, ownership and conflict stops are binding. A verified branch does not authorize a merge or push, and a chosen integration route does not authorize branch deletion, worktree removal, release or deployment.
+
+## Simple Push
+
+Its stops and prohibitions are binding; the inspection commands are judgment.
+
+This route is a **simple push**: inspected local commits from the current named branch to one explicit or established remote branch, with no force, deletion, tag publication, integration, pull request, release or deployment. When the request needs any of those, or a choice of how to integrate, share, preserve, rewrite or clean up branch state, use the branch routes below or [release](release.md) instead.
+
+### Confirm What The Yes Covers
+
+Confirm which commits are intended, the local branch, the destination remote and branch, and whether setting a new upstream is included. Do not infer a remote, destination branch, pull-request target or shared-branch policy when the wrong choice could affect collaborators.
+
+### Inspect The Route
+
+[push-route](../scripts/push-route.mjs) (`node <deliver-work-directory>/scripts/push-route.mjs [--remote <name>]`) reports the branch, upstream or destination, the commits it would send and the stop conditions below that local state shows, and prints the push command without running it. By hand:
+
+```bash
+git branch --show-current
+git status --short --branch
+git branch -vv
+git remote -v
+git log -1 --oneline --decorate
+```
+
+When an upstream exists, also:
+
+```bash
+git rev-parse --abbrev-ref --symbolic-full-name @{upstream}
+git rev-list --left-right --count @{upstream}...HEAD
+```
+
+Ahead and behind counts are only as fresh as the local remote-tracking reference; do not claim current remote state unless you observed it freshly.
+
+Stop before pushing when:
+
+- `HEAD` is detached;
+- the destination or upstream is unclear;
+- unexpected commits or dirty state change the route;
+- protected or shared-branch policy disallows the push or leaves it unclear;
+- local and observed upstream history diverge;
+- the push would need force, deletion, tag publication or another separately controlled action.
+
+### Push The Exact Branch
+
+Use the established upstream when it clearly matches the approved route. Set a new upstream only when the remote and branch are explicit and the configuration change is part of the approved route. Push no other branches or tags. A force push is not a simple push: take an explicitly requested history rewrite to the branch routes below.
+
+### Handle Rejection Without Escalation
+
+If the push is rejected or fails, keep the complete result and check whether any remote update happened. Do not automatically pull, merge, rebase, force, change remotes or change destination; return authentication, divergence, policy or destination decisions to the user or to the branch routes below. A failed push does not invalidate the local commit.
+
+### Check The Result
+
+After a successful push, inspect `git status --short --branch` and `git branch -vv`, and report whether an upstream was set or changed. A push proves transfer to the observed destination, not a pull request, merge, release, deployment or passing remote CI.
+
+## Inspect The Exact State
+
+Before offering or executing a route, inspect:
+
+- current branch, detached state, repository root and worktree ownership;
+- the base branch or merge base that repository evidence supports;
+- commits and diff relative to the base;
+- staged, unstaged and untracked work;
+- upstream, remote, and ahead or behind state;
+- fresh verification, self-review and any selected independent review;
+- CI, policy or repository gates for the intended route.
+
+Do not infer the base, remote destination, pull-request target or workspace owner when the wrong choice could lose work or affect collaborators.
+
+## Offer Only Supported Routes
+
+The user decides whether to integrate locally and by which method, push or open a normal or draft pull request, keep the branch, worktree or dirty state, discard commits or uncommitted work, delete local or remote branches, rewrite or force-push history, and clean up a checkout or worktree.
+
+Present only the routes the observed state supports; drop a route that is impossible, unsafe or irrelevant rather than forcing a fixed menu. Ask as [Discuss Work](../../discuss-work/SKILL.md)'s "Ask One Question" describes, with the supported routes as the options. Approval of one route covers only the scope shown and accepted. When a route needs a local commit, use the trunk's Commit steps; do not commit merely to make the branch look finished.
+
+## State Readiness Honestly
+
+Call a branch ready for its integration boundary only when the agreed outcome is clear, intended commits and remaining dirty state are known, fresh direct evidence supports the branch claim, self-review left no unresolved material issue, any selected independent review is resolved for the unchanged state, and no source conflict, owner decision, evidence gap or repository gate blocks the route. A feature-branch pass does not prove the integrated result.
+
+Unverified or failing work may still be kept, handed off, or shared through an explicitly approved draft route: state the gaps, and do not call it ready to integrate.
+
+## Hand Over For Acceptance
+
+Goal: the user can accept or refuse the change from the hand-over alone, without rereading the conversation.
+
+The pull-request description, or the final report when there is no pull request, carries:
+
+- what done looks like, from the work agreement, against what was done, naming anything left out or changed on the way;
+- choices the user has not seen, from Discuss Work's decision list: its `new`, `changed` and `default` items, each with where it shows;
+- the evidence: each check run on the final state and its result;
+- the review outcome: self-review only, or each independent review's judgment with every Rejected finding and why.
+
+Build it from the Working Record ([Track Work](../../track-work/SKILL.md)) when one exists, not from memory. When the repository has a pull-request template or convention, fit these into it. Otherwise write a short briefing from which a reviewer who has the diff can accept or reject the change: why it exists; what changed; its scope, including what it deliberately leaves out; what else it could affect and how risky that is; and the hand-over above.
+
+## Execute Only The Chosen Route
+
+### Local Integration
+
+1. Keep or resolve dirty state deliberately.
+2. Refresh base evidence without overwriting local work.
+3. Integrate with the repository's merge or rebase policy, without rewriting unrelated history.
+4. Run the checks that prove the combined result on the resulting base.
+5. Inspect the final log and status.
+6. Remove branch or worktree state only when cleanup was part of the approved route and integration verification succeeded.
+
+### Pull Request
+
+Fits when review, CI, collaboration, protected branches or remote integration owns the next gate.
+
+- Inspect remote and upstream state, then push only the intended commits to the accepted destination, as [Simple Push](#simple-push) checks them.
+- Capture the target branch, commit range, residual risks, migrations, rollout or compatibility notes, and the reviewers or checks repository policy requires.
+- Create or update the pull request by repository convention, with the hand-over as its description; mark incomplete or failing work as draft when that is the approved route.
+- Keep the worktree when iteration or feedback may continue.
+
+A pull-request URL proves creation, not readiness or merge.
+
+### Keep For Later
+
+Fits when the work is valid but integration is deferred, feedback is expected, or environment ownership prevents cleanup. Report the trunk's lines plus why the branch is kept and what would end the wait. Read Track Work's [handoff](../../track-work/references/handoff.md) only when continuing needs durable transfer context.
+
+### Discard
+
+Classify what is recoverable before deleting anything: uncommitted changes may be unrecoverable; local commits may be recoverable through the reflog for a limited time; pushed commits may affect collaborators; worktrees may be owned by a harness; deleting a remote branch reaches further than local cleanup. State exactly which commits, paths, branches, worktrees and remote state would be lost and what stays recoverable, and require explicit confirmation of that concrete scope. "Finish", "clean up", a menu number or approval of integration is not confirmation of broader destruction.
+
+## Protect Workspace Ownership
+
+Do not remove a worktree, checkout, session or harness state you did not create or are not authorized to manage; if ownership is unclear, keep it and report the uncertainty. Do not assume a detached checkout is disposable: an IDE, CI system, coding harness or worktree manager may own it, so offer only routes that environment supports, such as creating a named branch, keeping the checkout, exporting a patch, or asking the harness to close it.
+
+## Return Conflicts And Failures
+
+Deliver Work's Stop list says when a conflict stops the route. Stop and report it with its evidence also when resolving it would make a user-owned choice (Discuss Work), or choose between changed tests and changed implementation, incompatible migrations or data ownership, or two architecture directions; the next route may be Discuss Work, review, diagnosis, or a Spec or Plan revision.
+
+Use Execute Work's [diagnose](../../execute-work/references/diagnose.md) when integrated checks fail without a supported cause. Take mixed or unrelated branch contents back to the [commit](commit.md) staging decisions. Keep branch state before handing to another activity.

package/skills/deliver-work/references/commit.md

@@ -0,0 +1,83 @@
+# Commit: Staging Decisions And Git State
+
+This reference is judgment about what enters a commit and how to handle unusual Git state; each "do not" and each stop is binding. It grants no commit authority and no permission to alter work that is not yours.
+
+## Classify The Changed Units
+
+Classify at the path level only when the whole path has one role; otherwise classify hunks.
+
+- **Commit content:** implements or proves the commit's claim.
+- **Required companion:** tests, documentation, schema, metadata or generated output the same claim needs.
+- **Related but separable:** useful, but not needed in this commit.
+- **Unrelated or not yours:** outside the agreed outcome, or ownership not established.
+- **Sensitive or unsafe:** secrets, credentials, personal data, environment files, debug output, destructive state or unexplained artifacts.
+- **Unclear:** purpose, generator, ownership or evidence relationship not yet supported.
+
+Only commit content and required companions belong. "Commit everything" may authorize broad inclusion; it does not remove the need to inspect unsafe, unclear or unexpectedly unrelated content.
+
+## Protect Existing Staged State
+
+Staged changes may belong to another workflow. Inspect them, but do not treat them as intended because they are staged. [commit-state](../scripts/commit-state.mjs) tells them from yours when its `snapshot` ran before your first edit. Do not silently absorb them, unstage or reset them, amend them into another commit, move them through a stash or temporary commit, or replace the index to get around the ambiguity.
+
+When your changes and pre-existing staged work cannot be separated without touching ambiguous state, present the smallest safe options and ask which commit the user wants.
+
+## Stage Partial Files Carefully
+
+Stage only the intended hunks of a mixed file when their behavior and evidence hold on their own. Stop when:
+
+- included and excluded hunks depend on each other;
+- partial staging would leave an invalid intermediate state;
+- checks ran against the combined working tree and excluded changes may have affected the result;
+- the staged version differs materially from what was reviewed or verified.
+
+A combined dirty worktree passing does not show that the staged subset is supported.
+
+## Include Generated And Durable Files Deliberately
+
+Include generated files, snapshots, lockfiles, formatter output or build artifacts only when repository convention or the agreed outcome requires them. Establish which command produced them, whether their change follows from the source change, whether they can be reviewed, and whether hand edits are prohibited. Do not include generated output merely because it changed, and do not hand-edit it unless the repository expects that.
+
+A Spec, Plan, ADR, policy, public documentation file or release artifact has its own authority and maintenance rules. Include it only when its change is covered, belongs to the same commit, describes the same agreed behavior, and its own policy permits the update. Do not edit a durable artifact to make the implementation look coherent; settle contradictions through [Discuss Work](../../discuss-work/SKILL.md).
+
+## Reject Sensitive Or Suspicious Content
+
+Besides the trunk's never-stage list, stop before staging databases, dumps, recordings, personal data, unexplained binaries or archives, logs, traces, screenshots or debug output not explicitly required, and files whose inclusion could expose or lose user data. Do not delete or discard suspicious files to tidy up: preserve them and report their exact paths.
+
+## Verify The Candidate
+
+After staging, compare `git diff --cached`, `git diff` and `git status --short --branch`. The commit is narrow only when the index holds exactly the intended change, excluded work is untouched, remaining dirty state is understood, checks still support the staged version rather than only the combined worktree, and the report can name everything left behind.
+
+## In-Progress Operations
+
+A commit during a merge, rebase, cherry-pick or revert may complete or advance that operation instead of creating an ordinary commit. Establish which operation is active, whether this commit is meant to conclude it, whether every conflict and behavior decision is settled, who should continue it, and what must be verified on the result. Do not finish an operation merely because Git permits `commit`. Unmerged paths always stop an ordinary commit.
+
+## Detached HEAD
+
+A detached-`HEAD` commit can be hard to recover or push. Before committing, require an explicit way the commit will stay reachable; when a branch, integration or checkout ownership must be decided, use [branch closeout](branch-closeout.md). Do not silently create or switch branches.
+
+## Amend And Empty Commits
+
+Amend only when the user asked for it and the target commit, included changes, authorship effects and remote-history state are known. If the target may already be shared or pushed, ask before rewriting it. An empty commit needs an explicit request with a named purpose; an accidentally empty index is not one.
+
+## Hooks
+
+When a hook fails:
+
+1. keep its complete output;
+2. inspect `HEAD`, the index and the working tree;
+3. check whether a commit was created despite the failure;
+4. check whether the hook changed files or staged content;
+5. send implementation, verification, policy or environment failures to their owner.
+
+When a hook changes content, the state being committed is no longer the one that was checked: reinspect the whole diff and rerun the affected checks before retrying. Skip hooks with `--no-verify` only when the user asked for that exact bypass and repository policy permits it, and report which checks were skipped and which claims that leaves unsupported.
+
+## Failed Commit Commands
+
+After a failed or interrupted commit, inspect `git status`, `git diff`, `git diff --cached` and `git log -1 --oneline --decorate`; do not assume no commit was created or nothing changed. For identity, signing, credential-helper, editor, lock, filesystem or permission failures, do not change global or repository Git configuration without authority, do not delete lock files while their owner is unclear, do not retry through a materially different command without a supported cause, and report the exact blocker and the preserved state. Use Execute Work's [diagnose](../../execute-work/references/diagnose.md) when the cause stays unclear or a retry repeats the failure.
+
+## Submodules
+
+A parent commit records a submodule pointer, not the submodule's uncommitted contents. Inspect the pointer change, whether the nested worktree is dirty, whether this commit should include the pointer update, and whether nested changes have their own way to be preserved. Do not claim nested changes are preserved by committing only the parent.
+
+## Return
+
+Go back to the trunk's Commit steps only when the repository has one supported, recoverable candidate. Otherwise preserve the exact Git state and hand over to branch closeout, Execute Work's diagnose, or the activity whose responsibility changed.

package/skills/deliver-work/references/launch.md

@@ -0,0 +1,94 @@
+# Launch
+
+This reference is judgment about changing production deliberately and keeping a safe recovery path; its "do not" lines are binding. Deployment changes what runs; rollout changes who or what is exposed. A build, merge, release or staging pass does not prove production behavior.
+
+## Establish The Boundary
+
+Carry out only the stages explicitly requested or approved through an inspected launch contract or accepted operational policy. Take deployment, exposure, rollback, destructive migration, the launch window, acceptable degradation, user communication and recovery direction to [Discuss Work](../../discuss-work/SKILL.md) while they remain the user's choice.
+
+Publish a versioned artifact first through [release](release.md) when one is needed. Use Execute Work's [migration](../../execute-work/references/migration.md) as well when the launch moves data, traffic, consumers, configuration or compatibility contracts from an old path to a replacement.
+
+## Define The Launch Contract
+
+Before changing production, establish:
+
+```text
+Outcome and affected users / systems:
+Artifact / commit / configuration identity:
+Target environment and owner:
+Deployment versus exposure stages:
+Dependencies and migration ordering:
+Expected technical, user, business, and data signals:
+Advance / hold / abort criteria:
+Rollback or forward-recovery path:
+Observation and post-launch verification:
+Communication and escalation:
+Approved stages and scope:
+```
+
+After each stage the next step is one of three, by criteria agreed before it began:
+
+- **Advance** when required behavior and signals stay within bounds. The next stage still needs its yes unless the approved launch contract covers it.
+- **Hold** when evidence is incomplete or a difference unexplained. Elapsed time is no reason to advance while a required signal is missing.
+- **Abort** when a safety, data, security, compatibility or agreed service criterion fails: roll back, or recover forward where rollback is unsafe, without widening scope.
+
+Take thresholds and observation periods from SLOs, baselines, policy or the owner's decision, never from universal percentages or windows; the owner decides consequential thresholds and acceptable degradation.
+
+Feature flags, canaries, blue/green, shadow traffic and phased regions are options, not defaults; choose only what the platform and the accepted failure contract support, and do not adopt "every feature needs a flag" as a rule.
+
+## Establish Readiness
+
+Use only the lenses whose risk applies to this change; this is not a universal checklist. A required lens with missing evidence is not green.
+
+- **Identity and ownership:** exact artifact, commit, image, configuration, migration and target are known; deployment, rollout, rollback, incident and communication owners are known where risk requires; production credentials come through approved channels, never prompts, logs or source.
+- **Behavior and compatibility:** accepted requirements and critical user paths have fresh evidence; public APIs, clients, schemas, feature states and supported versions stay compatible or have an approved migration; failure, retry, idempotency, duplicate, ordering and recovery behavior are settled for consequential operations.
+- **Data:** the authoritative source and migration ordering are explicit; backups, reconciliation, partial failure, restart, rollback and forward recovery are proved to the required level; privacy, retention, deletion, audit and permission obligations still hold.
+- **Security and access:** threat-relevant changes received the required specialist or policy review; authentication, authorization, secret handling, untrusted input, dependency, network and privilege boundaries are verified where affected; telemetry and support tooling expose no secrets or unnecessary personal data. When a security-focused review is selected, read the [security risk lens](../../review-work/references/work.md#security-risk-lens).
+- **Performance and capacity:** representative baseline and expected load are known where capacity can change; latency, throughput, saturation, queue, storage and dependency limits have evidence. Read [performance evidence](../../verify-work/references/runtime-evidence.md#performance) for readiness and improvement claims, and Execute Work's [diagnose](../../execute-work/references/diagnose.md#flaky-and-performance-failures) only when a regression lacks a supported cause.
+- **Accessibility and user experience:** when interfaces change, verify the affected critical paths with the repository's design and accessibility authority and tooling: keyboard, focus, semantics, assistive technology, responsive, loading, empty, error and degraded states, where relevant.
+- **Observability:** start from what operators must answer: is the new path used, succeeding, within latency and capacity bounds; why is a given request, job or migration failing; are data, queues, retries and dependencies healthy; can one operation be traced across components. Use structured logs for event detail, metrics for aggregate rate, error, duration or saturation, and traces for cross-component paths; keep metric dimensions bounded, and do not log secrets, tokens, full sensitive payloads or unrestricted personal identifiers. Verify telemetry itself by inducing or observing a safe known event and finding its signal, fields and alert routing.
+- **CI/CD and environment:** the pipeline and target run the checks this change needs; artifacts are promoted, not rebuilt differently without approval; environment drift, secrets, migrations and deployment ordering are inspected; a failed or ambiguous pipeline step has a known retry or reconciliation contract. Provider-specific workflow syntax belongs to the repository or platform skill.
+
+Confirm the artifact and configuration identity, required pre-production checks, recovery path, operational signals and any selected review before starting an approved stage. Do not deploy to obtain evidence that should exist safely before production. When only production can answer a question, first define an approved bounded learning rollout with its observation, hold, abort and recovery conditions.
+
+## Deploy And Expose In Approved Stages
+
+Separate operations when the platform permits: deploy inert code, configuration or infrastructure; verify health and compatibility; expose a bounded cohort, tenant, region or traffic segment; compare required signals with the accepted baseline; then advance, hold or abort.
+
+For each stage, define:
+
+```text
+Stage / cohort:
+Action:
+Expected signals:
+Advance if:
+Hold if:
+Abort (roll back or recover forward) if:
+Verification:
+Owner:
+```
+
+Then:
+
+1. confirm artifact, configuration, target and current production state;
+2. execute the bounded action once;
+3. verify technical and user-visible behavior;
+4. inspect telemetry, data integrity and unexpected side effects;
+5. preserve anomalies and choose the next step before expanding exposure.
+
+## Handle Failure And Recovery
+
+Before rolling back, determine whether code, schema, data, messages, caches, clients or external effects make rollback unsafe or incomplete, and test or rehearse the recovery path to the level the risk warrants. Do not repeat migrations, jobs, publishes, configuration changes or exposure operations blindly. Preserve incident evidence. Do not weaken alerts, checks, thresholds or accepted behavior to declare the launch healthy.
+
+## Verify The Production Outcome
+
+Observe from the production boundary, as applicable:
+
+- the intended artifact and configuration are active;
+- critical user and failure paths behave as accepted;
+- data, compatibility, privacy and permission invariants hold;
+- telemetry is present, queryable, bounded and free of unexpected sensitive data;
+- alerts, escalation and recovery routes work where required;
+- temporary flags, adapters, dual writes, dashboards, elevated logging, permissions or support procedures have owners and cleanup conditions; route compatibility removal through Execute Work's migration.
+
+A quiet dashboard is not evidence when telemetry is absent or broken. A launch is complete when the accepted exposure and observation contract is satisfied, not when a deployment command succeeds, and it does not authorize later migration removal, release publication or cleanup outside the approved scope.

package/skills/deliver-work/references/release.md

@@ -0,0 +1,85 @@
+# Release
+
+This reference is judgment about preparing and publishing a versioned artifact whose source, version, contents and destination agree; its "do not" lines are binding. A commit is not a release, a tag does not prove which artifact was built, a local build does not prove registry contents, and a published artifact is not deployed.
+
+## Establish The Stage And Source
+
+Carry out only the release stages explicitly requested or approved: preparing, tagging, publishing, deprecating, yanking or replacing are separate. Before editing, read the repository's release policy, versioning scheme, package metadata, changelog convention, release automation, supported branches, signing or provenance requirements, and the latest published versions.
+
+Take these to [Discuss Work](../../discuss-work/SKILL.md) when policy and evidence do not settle them:
+
+- whether to release, and which channel or audience receives it;
+- compatibility or breaking-change classification;
+- the version;
+- credentials, registry, signing, provenance or remote-tag behavior;
+- yanking, deprecating, replacing or republishing an artifact;
+- release branches, history rewriting, or recovery from partial publication.
+
+## Define The Release Contract
+
+Before changing release state, establish:
+
+```text
+Release target and audience:
+Source commit / branch:
+Version and compatibility basis:
+Artifacts and supported platforms:
+Release notes / migration guidance:
+Required checks and selected reviews:
+Signing / provenance / checksums:
+Publication destination and channel:
+Failure and recovery behavior:
+Post-publication verification:
+Approved preparation and publication stages:
+```
+
+Use the repository's declared versioning scheme; do not impose semantic versioning on a project that uses dates, trains, build numbers or another scheme. Classify by what consumers can observe, not by diff size: a small change can be breaking, and a large internal refactor may be compatible. When compatibility is uncertain, inspect the supported consumers and ask rather than choosing the smallest bump.
+
+When consumers must move before a contract can be removed, use Execute Work's [migration](../../execute-work/references/migration.md). An additive replacement release may come before the migration; a release that removes a contract waits for the accepted migration and its removal proof.
+
+## Prepare The Release
+
+For approved preparation:
+
+- confirm the source is a coherent, freshly verified commit and any selected review is resolved;
+- reconcile version declarations, lockfiles, generated metadata and release notes through the repository's tooling, without hand-editing generated artifacts or duplicating version truth that a generator owns;
+- write release notes for consumers, not a commit dump: added or changed behavior, fixed user-visible defects, deprecated and removed contracts, security impact without unsafe disclosure, migration and compatibility requirements, known limitations and unsupported targets;
+- run the canonical build or package process from the intended source;
+- inspect the exact artifacts that would be published;
+- keep credentials and signing material out of prompts, logs, diffs and artifacts.
+
+Propose branch, commit, public-documentation or migration work the release needs through Discuss Work unless the approved release scope includes it.
+
+## Preflight The Exact Release
+
+Before any irreversible remote action, verify the following. [release-preflight](../scripts/release-preflight.mjs) (`node <deliver-work-directory>/scripts/release-preflight.mjs [--version <x.y.z>]`) checks the local part: the version is valid and not older than the latest tag, its tag does not already exist elsewhere, the changelog has its entries, the tree is clean, and for an npm package what `npm pack --dry-run` would publish; the registry and remote it reports unavailable.
+
+- source commit, branch and working-tree expectations;
+- the version is valid, unused and consistent with policy;
+- required tests, builds, package or install checks and compatibility checks;
+- artifact contents: included and excluded files, entry points and permissions, generated code and source maps, dependency and lockfile state, licenses and notices, platform variants, and no debug, test, local configuration, credential or private files; use the package manager's dry-run or list command when available;
+- names, sizes, checksums, signatures and provenance;
+- release notes and migration guidance match the consumer impact;
+- tag, registry, channel and destination identity;
+- credentials and permissions work without exposing secrets.
+
+Know the publication failure contract before publishing: which step first creates irreversible remote state, whether a version or tag can be retried safely, how to detect a publish that committed without acknowledgement, whether repair, deprecation, yank or replacement is supported, and who tells consumers. A dry run proves only the boundaries it exercises; name signing, registry, propagation or publication behavior that remains unverified.
+
+## Publish Only The Approved Stage
+
+Follow the repository's canonical order, and stop when source, version, tag, artifact, signing mode, channel or destination diverges. Do not publish from a dirty or different source state, or substitute a registry, channel, artifact or signing mode. When publication partly fails, identify which external effects committed before choosing to retry, repair, deprecate, replace or stop.
+
+A trustworthy release connects each link: source commit, freshly verified state, version metadata, build invocation and environment, artifact digest, signature or provenance, immutable tag or release record, registry entry, and consumer-side install evidence. Name the links you could not establish instead of implying reproducibility.
+
+## Verify From The Consumer Boundary
+
+When publication is in scope, verify the actual public artifact by version or digest, from a clean environment that does not reuse the local checkout or cache:
+
+- the tag resolves to the intended commit;
+- version, channel and destinations are correct;
+- checksums, signatures, provenance and contents match the inspected artifact;
+- a clean install, download or launch works on supported targets;
+- release notes and migration links resolve;
+- no unexpected artifact, credential, local configuration or private file was published.
+
+Do not call the release complete because the publish command exited successfully; unavailable propagation or consumer evidence leaves that claim unverified. Production deployment is the separate [launch](launch.md) route.