@hassangameryt/freeflow 0.7.3 → 0.9.0

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.

package/skills/deliver-work/scripts/commit-state.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// What a commit would hold, and whose it is, before touching the index: every staged, unstaged and untracked path,
+// marked yours, pre-existing or unknown; staged changes that were already staged before your work (never absorb or
+// unstage them); files with both staged and unstaged changes; sensitive-looking paths and Working Records; and what
+// `git diff --cached --check` finds. Read-only apart from its own snapshot file.
+// Usage: commit-state.mjs snapshot [--root <repository>] [--scratch <dir>]
+//        commit-state.mjs [--mine <path>]... [--root <repository>] [--scratch <dir>] [--json]
+// `snapshot`, taken before your first edit, records the dirty and staged state that is not yours. Without one, --mine
+// names the paths you changed; a path neither names is "unknown". --scratch defaults to a folder under the system
+// temporary directory. Exit code 0 when it reports, 2 on a usage error or outside a Git repository.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { git, repositoryRoot, workingState } from "./lib/git-state.mjs";
+
+const USAGE = [
+  "Usage: commit-state.mjs snapshot [--root <repository>] [--scratch <dir>]",
+  "       commit-state.mjs [--mine <path>]... [--root <repository>] [--scratch <dir>] [--json]",
+].join("\n");
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      root: { type: "string" },
+      scratch: { type: "string" },
+      mine: { type: "string", multiple: true, default: [] },
+      json: { type: "boolean", default: false },
+    },
+  });
+} catch (error) {
+  console.error(`${error.message}\n${USAGE}`);
+  process.exit(2);
+}
+const { values, positionals } = parsed;
+if (positionals.length > 1 || (positionals.length && positionals[0] !== "snapshot")) {
+  console.error(USAGE);
+  process.exit(2);
+}
+const root = repositoryRoot(values.root ?? ".");
+if (!root) {
+  console.error("not inside a Git repository");
+  process.exit(2);
+}
+const scratch = resolve(
+  values.scratch ??
+    join(
+      tmpdir(),
+      "freeflow-commit-state",
+      `${basename(root)}-${createHash("sha256").update(root).digest("hex").slice(0, 8)}`,
+    ),
+);
+const snapshotPath = join(scratch, "commit-state-snapshot.json");
+
+// A path's identity in the index and in the working tree, so a later change to either shows.
+const identity = (path) => ({
+  index: git(root, ["ls-files", "-s", "--", path])?.split(/\s+/)[1] ?? null,
+  tree: existsSync(join(root, path)) ? git(root, ["hash-object", "--", path]) : null,
+});
+const working = workingState(root);
+
+if (positionals[0] === "snapshot") {
+  mkdirSync(scratch, { recursive: true });
+  const paths = Object.fromEntries(working.entries.map((entry) => [entry.path, { ...entry, ...identity(entry.path) }]));
+  writeFileSync(
+    snapshotPath,
+    `${JSON.stringify({ root, head: git(root, ["rev-parse", "HEAD"]), at: new Date().toISOString(), paths }, null, 2)}\n`,
+  );
+  console.log(`Snapshot of ${working.entries.length} pre-existing changed path(s): ${snapshotPath}`);
+  process.exit(0);
+}
+
+const snapshot = existsSync(snapshotPath) ? JSON.parse(readFileSync(snapshotPath, "utf8")) : null;
+const mine = new Set(values.mine.map((path) => relative(root, resolve(path)).split("\\").join("/")));
+function owner(entry) {
+  if (snapshot) {
+    const before = snapshot.paths[entry.path];
+    if (!before) return "yours";
+    const now = identity(entry.path);
+    return now.index === before.index && now.tree === before.tree ? "pre-existing" : "mixed: pre-existing plus yours";
+  }
+  // A --mine path names a file, or a folder holding it.
+  if ([...mine].some((path) => entry.path === path || entry.path.startsWith(`${path}/`))) return "yours";
+  return "unknown";
+}
+const SENSITIVE =
+  /(^|\/)(\.env(\..*)?|\.npmrc|\.pypirc|id_(rsa|ed25519|ecdsa)(\.pub)?|.*\.(pem|key|p12|pfx|keystore)|credentials?(\.json)?|secrets?(\.[a-z]+)?|.*\.tfstate)$/i;
+const flags = (entry) => [
+  ...(/^\.freeflow\/(tasks\/.*)?$/.test(entry.path) ? ["Working Record: never stage"] : []),
+  ...(SENSITIVE.test(entry.path) ? ["sensitive-looking: inspect before staging"] : []),
+];
+const describe = (entry) => ({
+  path: entry.path,
+  ...(entry.from ? { from: entry.from } : {}),
+  index: entry.x,
+  tree: entry.y,
+  owner: owner(entry),
+  partial: entry.x !== " " && entry.x !== "?" && entry.y !== " " && entry.y !== "?",
+  flags: flags(entry),
+});
+const staged = working.staged.map(describe);
+const unstaged = working.unstaged.filter((entry) => entry.x === " ").map(describe);
+const untracked = working.untracked.map(describe);
+const conflicted = working.conflicted.map(describe);
+// Conflict markers and whitespace damage in what is staged; Git exits nonzero when it finds any.
+const cached = spawnSync("git", ["diff", "--cached", "--check"], { cwd: root, encoding: "utf8" });
+const check =
+  cached.status === 0 ? "clean" : (cached.stdout || cached.stderr).trim().split("\n").slice(0, 20).join("\n");
+const report = {
+  command: "commit-state",
+  root,
+  ownership: snapshot ? `snapshot of ${snapshot.at}` : mine.size ? "--mine paths" : "unknown: no snapshot or --mine",
+  staged,
+  stagedNotYours: staged.filter((each) => each.owner !== "yours").map((each) => each.path),
+  unstaged,
+  untracked,
+  conflicted,
+  cachedCheck: check,
+};
+
+if (values.json) console.log(JSON.stringify(report, null, 2));
+else {
+  const line = (each) =>
+    `  ${each.index}${each.tree} ${each.from ? `${each.from} -> ` : ""}${each.path}  [${each.owner}]${each.partial ? " (staged and unstaged changes)" : ""}${each.flags.length ? `  ! ${each.flags.join("; ")}` : ""}`;
+  const out = [`Ownership from: ${report.ownership}`];
+  out.push(`Staged (${staged.length}):`, ...(staged.length ? staged.map(line) : ["  none"]));
+  if (report.stagedNotYours.length)
+    out.push(
+      `  Not yours, or not known to be: ${report.stagedNotYours.join(", ")}. Do not absorb or unstage them; ask which commit the user wants.`,
+    );
+  out.push(`Unstaged only (${unstaged.length}):`, ...(unstaged.length ? unstaged.map(line) : ["  none"]));
+  out.push(`Untracked (${untracked.length}):`, ...(untracked.length ? untracked.map(line) : ["  none"]));
+  if (conflicted.length) out.push(`Conflicted (${conflicted.length}):`, ...conflicted.map(line));
+  out.push(`git diff --cached --check: ${check}`);
+  console.log(out.join("\n"));
+}

package/skills/deliver-work/scripts/delivery-state.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// The delivery state in one read-only call, before any commit, push, merge, cleanup or release: branch or detached
+// HEAD, upstream and ahead/behind from local refs, staged, unstaged, untracked and conflicted counts, a Git operation
+// left in progress, every worktree with the one holding this session's working directory flagged, the latest tag, the
+// declared version and the changelog's Unreleased section. Anything that needs the network is reported unavailable.
+// Usage: delivery-state.mjs [--root <repository>] [--cwd <session directory>] [--json]
+// --cwd defaults to the current directory. Exit code 0 when it reports, 2 outside a Git repository.
+import { parseArgs } from "node:util";
+import {
+  branchState,
+  changelog,
+  inProgress,
+  latestTag,
+  projectVersion,
+  repositoryRoot,
+  workingState,
+  worktrees,
+} from "./lib/git-state.mjs";
+
+const USAGE = "Usage: delivery-state.mjs [--root <repository>] [--cwd <session directory>] [--json]";
+let values;
+try {
+  ({ values } = parseArgs({
+    options: { root: { type: "string" }, cwd: { type: "string" }, json: { type: "boolean", default: false } },
+  }));
+} catch (error) {
+  console.error(`${error.message}\n${USAGE}`);
+  process.exit(2);
+}
+const cwd = values.cwd ?? process.cwd();
+const root = repositoryRoot(values.root ?? cwd);
+if (!root) {
+  console.error("not inside a Git repository");
+  process.exit(2);
+}
+
+const branch = branchState(root);
+const working = workingState(root);
+const operations = inProgress(root);
+const trees = worktrees(root, cwd);
+const tag = latestTag(root);
+const version = projectVersion(root);
+const notes = changelog(root);
+const state = {
+  command: "delivery-state",
+  root,
+  branch,
+  working: {
+    staged: working.staged.length,
+    unstaged: working.unstaged.length,
+    untracked: working.untracked.length,
+    conflicted: working.conflicted.length,
+  },
+  inProgress: operations,
+  worktrees: trees,
+  latestTag: tag,
+  version,
+  versionTagged:
+    version?.version && tag ? [tag.tag, `v${version.version}`].includes(tag.tag) || tag.tag === version.version : false,
+  changelog: notes,
+  unavailable: [
+    "the remote's current state: ahead/behind uses local remote-tracking refs (fetch to refresh them, when that is covered)",
+    "pull requests, CI results, registry versions and deployments",
+  ],
+};
+
+if (values.json) console.log(JSON.stringify(state, null, 2));
+else {
+  const out = [];
+  out.push(
+    branch.branch
+      ? `Branch: ${branch.branch}${branch.upstream ? `, upstream ${branch.upstream} (ahead ${branch.ahead}, behind ${branch.behind}, from local refs)` : ", no upstream"}`
+      : branch.detached
+        ? `Detached HEAD at ${branch.head.slice(0, 12)}`
+        : "No commits yet",
+  );
+  if (branch.head) out.push(`HEAD: ${branch.head.slice(0, 12)} ${branch.subject}`);
+  out.push(
+    `Working tree: ${state.working.staged} staged, ${state.working.unstaged} unstaged, ${state.working.untracked} untracked, ${state.working.conflicted} conflicted`,
+  );
+  out.push(`In progress: ${operations.length ? operations.join(", ") : "no Git operation"}`);
+  out.push(`Worktrees (${trees.length}):`);
+  for (const tree of trees)
+    out.push(
+      `  ${tree.path} ${tree.branch ?? (tree.detached ? "(detached)" : "")} ${tree.head ?? ""}${tree.sessionCwd ? "  <- this session's cwd is inside" : ""}${tree.locked ? " [locked]" : ""}${tree.prunable ? " [prunable]" : ""}`,
+    );
+  out.push(
+    `Latest tag: ${tag ? `${tag.tag} at ${tag.commit}, ${tag.commitsSince} commit(s) since` : "none"}; version: ${version ? `${version.version ?? "unreadable"} (${version.source})` : "none declared"}`,
+  );
+  if (notes)
+    out.push(
+      `Changelog ${notes.file}: ${
+        notes.unreleased
+          ? `Unreleased has ${notes.unreleased.entries} entr${notes.unreleased.entries === 1 ? "y" : "ies"}${
+              Object.keys(notes.unreleased.categories).length
+                ? ` (${Object.entries(notes.unreleased.categories)
+                    .map(([name, count]) => `${name} ${count}`)
+                    .join(", ")})`
+                : ""
+            }`
+          : "no Unreleased section"
+      }`,
+    );
+  else out.push("Changelog: none found");
+  out.push(`Unavailable without the network: ${state.unavailable.join("; ")}.`);
+  console.log(out.join("\n"));
+}