@zaip-ai/cli 4.4.0 → 4.6.0

package/templates/.agents/skills/zaip-skill-github-deploy/references/deployment-workflow.md

@@ -1,139 +1,107 @@
+# GitHub deploy contract
 
-# Deploy and repair GitHub publication
+Resolve mode and scope before selecting validation or changing Git. An affirmative deployment request authorizes its resolved route; discussion, a quoted command or a negated release is not publication authority. Generic “faça deploy” follows project policy without a routine confirmation or an extra warning about existing pipelines. Actual integrity, authentication, destructive-action and scope blockers remain.
 
-The exact command “faça deploy” authorizes publication of everything versionable in the selected worktree, including tracked and untracked files, after the safety gates below. It does not authorize provider deployment.
+## Project policy and reviewed resolver
 
-An explicit current-turn request to `deploy`, `push`, `publicar`, `publicação` or GitHub publication selects this skill. For the verified `zaip-ai/zaip-aios` source, a default “faça deploy” includes the guarded Git push, GitHub Release and terminal observation of the npm workflow it triggers. Consumer repositories remain GitHub-only. Discussing or editing deployment does not authorize publication, and neither route authorizes provider deployment.
+`.agents/config/deploy-policy.json` is a separate project-owned preference seeded silently once at installation. Its fields are `schema_version: 1`, `default_mode: auto|commits|release` (default `auto`) and `default_scope: current-work`. Preserve it on upgrades; never add mode fields to `project.yaml#deploy` or save `all-worktree` as a default.
 
-## Authorization
+Use the portable, versioned resolver from the selected checkout:
 
-- Require an explicit deploy, push, publicar, publicação, GitHub publication, or failed-deploy repair request in the current turn.
-- The request authorizes the initial publication, automatic reconciliation needed to publish the selected branch, commits covering all versionable pending changes in the selected worktree, and up to five repair cycles needed to make required local and remote GitHub checks pass. Do not stop merely because the worktree is dirty, history is behind/diverged, generated files are pending, or a local gate has a repairable failure.
-- Limit repairs to the intended repository state and the evidenced failure. Do not add unrelated features or broaden product scope.
-- Never force push, rewrite history, replace remotes, change credentials or Git/SSH configuration, bypass checks, or deploy to another service.
-- Do not create lifecycle artifacts merely to publish already-existing commits. The deploy authorization permits staging every inventoried versionable path in the selected worktree after secret, size, and ignore checks; it never authorizes changes outside that worktree.
-- Every product commit needs its evidenced Task and canonical Task title, including Task-first. If ownership is missing, materialize the authorized work before editing/committing; never borrow the latest global Task. Only records/local-only snapshots are exempt. Omit nonexistent PRD/SPEC lineage. Explicit deploy authorizes reviewed path staging, never force, destructive reset, history rewrite, or credential changes.
-
-## Mandatory authorization record
-
-Before the first Git mutation, retain a sanitized authorization record in the task's visible progress and terminal report. It must state:
-
-1. the user's current-turn publication intent;
-2. repository, remote, branch and selected worktree;
-3. whether the grant is simple push or partitioned commit plus push;
-4. the bounded history-reconciliation strategy (`rebase` by default, or user-selected `merge`);
-5. allowed repair cycles, excluded worktrees/scopes and prohibited actions;
-6. the preflight result and the recoverable preservation reference used before reconciliation.
-
-For publication of existing commits, the conversation and terminal deploy report are the authority record; no artificial Task is needed. New product edits or commits require Task ownership under the workflow and commit policy. Never store credentials, private-key contents, tokens or environment values. Request only authority actually missing from the current request.
+```text
+node .agents/skills/zaip-skill-github-deploy/scripts/deploy-contract.mjs --repository <ROOT> --request-file <FILE> [--plan-file <FILE>]
+```
 
-## Multiple worktrees and divergent history
+The request file is UTF-8 plain text containing the real human request. The resolver reads the project's policy and manifest/origin identity and writes a JSON plan binding mode, phase, scope and their digests. Save paths, pending commits, configured branch and work attribution separately as observed evidence; those are not invented request-file fields. The resolver is a planning step, not a publication command. Invalid policy, contradictory repository identity or missing work attribution cannot be replaced with guessed defaults.
 
-1. Resolve the selected publishing worktree and inspect its `git status --porcelain`; use `git worktree list --porcelain` only to detect a path collision, never to scan every worktree.
-2. Select exactly one publishing worktree. Its named branch, recovery branch or detached HEAD is the source candidate; `deploy.<scope>.branch` is the remote target. A different local branch or detached source does not join another worktree and is not a blocker. The selected worktree is the complete publication scope.
-3. Report a detected path collision, but do not block solely because the selected worktree is dirty, detached, on a recovery branch or contains mixed changes; the explicit “faça deploy” authorization includes those changes. Stop only for an unresolved index conflict, secret/oversize file, authentication failure, or destructive/rewrite requirement.
-4. Prunable or missing worktrees are reported but never pruned automatically. Unselected dirty detached or temporary worktrees are never deleted, reset, stashed or copied into the publishing worktree implicitly.
-5. Fetch once and compute ahead/behind between the source candidate and the configured remote target. If it is behind or diverged, automatically reconcile only the selected source under this deploy authorization and continue; divergence is not a blocker by itself.
-6. Before reconciliation, create a recoverable branch reference and preserve tracked plus untracked changes in a named stash. Verify both references before proceeding. Use `rebase` unless the user explicitly selected `merge`.
-7. Apply the bounded reconciliation without force and without checking out the configured target branch locally. Restore with `git stash apply`, retain the stash until publication succeeds, and resolve generated aggregate conflicts by regenerating them from canonical sources. For ordinary textual conflicts, combine both sides when safe; use the selected worktree's intended version only when the diff and commit history establish that it supersedes the remote version.
-8. After restoration, prove that no unmerged paths remain, re-inventory the diff, and only then begin functional partitioning. Continue automatically through recoverable conflicts and pending repairs; stop only for a genuine terminal blocker defined below.
+| Affirmative request or saved preference | Result |
+| --- | --- |
+| Generic deploy with `default_mode: auto`, verified builder | Release plus npm through GitHub Actions |
+| Generic deploy with `default_mode: auto`, consumer | Commits plus exact-SHA push |
+| Generic deploy with saved `commits` or `release` | That saved mode, subject to repository capabilities |
+| “faça deploy apenas commits”, “sem release”, explicit push-only | Commits for this request |
+| “deploy com release”, “próxima versão”, “novo release” | Release for this request |
+| Prepare/qualify only, discuss release or negate publication | No publication authority |
 
-## Repair-loop integrity
+Overrides apply once. “Sempre faça deploy com release” is an explicit preference change; a single “deploy com release” does not save that preference. Consumers stay GitHub-only even when release is selected.
 
-- A publication cycle is: run deploy preflight, inventory the intended pending diff, synchronize, create any required functional commits with explicit pathspecs, push, and verify the remote hash. When no intended pending diff exists, publish already-formed commits. Run only gates required or evidenced by repository Rules, the active Change, or failed remote CI.
-- Inventory the complete pending diff, run the safety gates, then stage the reviewed inventory with `git add -- <explicit-pathspecs>` and commit it. Generate pathspecs from the reviewed tracked and untracked inventory; do not use `git add -A`, broad globs, or paths outside the selected worktree. Do not require functional partitioning for this explicit broad-deploy mode.
-- Run each diagnostic, gate, fetch, stage, commit, push, and hash verification at most once per cycle, except the single documented transient push retry below.
-- Start a new cycle only after a repository change or new remote evidence. Never repeat an unchanged failing command hoping for a different result.
-- Continue until all required checks pass or a terminal blocker occurs. Stop after five repair cycles, or when the same root cause remains after two repairs.
-- Treat authentication, unavailable credentials, unresolved conflicts after bounded repair, secret exposure, destructive changes, GitHub outages, and ambiguous scope expansion as terminal blockers. Ordinary branch divergence, dirty state, untracked versionable files, generated projections, lint/format failures, and other repairable pending work are not blockers: repair them within the selected worktree and continue under the same authorization.
+Recognize builder only through the approved `zaip-ai/zaip-aios` origin, root `@zaip-ai/aios` manifest and public CLI `@zaip-ai/cli` manifest together. A consumer may install these skills but does not acquire builder npm capability. Conflicting builder signals must fail closed rather than silently downgrade.
 
-## Prove folder-scoped SSH first
+## Scope and authority evidence
 
-From the repository root, read `.agents/config/project.yaml` immediately before deployment. `deploy.frontend.branch` and `deploy.backend.branch` are persistent authorization and may be `main`; pass their explicit `--scope`. `deploy.database.branch` is literal `beta`, never falls back to `main`, and requires `--scope database`. The internal `--scope framework` and a legacy preflight without `--scope` use `deploy.branch`, which must remain non-production. A malformed config is a terminal preflight failure. Preflight reports the local source branch or detached state separately, treats the configured branch only as the remote target, and never creates, renames or switches a branch.
+Default `current-work` covers the attributable files and commits of the current authorized work, including causally required projections. A generic deploy never absorbs unrelated dirty files or already-formed unrelated commits. A commit containing mixed ownership requires safe reconciliation before publication; a path filter alone cannot scope the contents of a pushed SHA.
 
-For a database migration request, the database worktree may push only `HEAD:refs/heads/request/<id>` to open its PR against `beta`. That route never targets `main`, never applies SQL, and does not provision a beta branch or Supabase resource.
+Only explicit “deploy de tudo” selects `all-worktree`: inventory all versionable work in exactly the selected checkout, preserve attribution and apply secret, size and ignore checks. Other worktrees remain outside the grant.
 
-```powershell
-node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository . --remote origin
-```
+Before mutation record actual intent, policy source, mode, scope, selected worktree, local source branch/detached SHA, remote and configured target, reviewed file/commit inventory, valid checks, reconciliation strategy and preservation refs. Keep these details in evidence, not a long chat report. Never record credential values.
 
-The preflight must prove that the push URL uses SSH, no process override is active, the effective `core.sshCommand` comes from repository-local or matching folder configuration, its private key exists, Git identity exists, and `git ls-remote` succeeds.
+New product commits require their real Task/Change/Execution and write scopes. Existing commits need no synthetic Task. Records/local-only snapshots retain their exemption; conversation capture is not product attribution. Never select the latest global Task as a fallback.
 
-Run preflight once at the start of the authorized deployment. Classify a failure before stopping: authentication, SSH configuration, unavailable authority, or an external access failure is a terminal blocker; an evidenced repository-content or missing-prerequisite failure within the authorized scope may be repaired in the bounded cycle and then rechecked. Do not edit Git/SSH configuration, use `git -c core.sshCommand=...`, set an environment override, or invoke `ssh -i` directly. Retain the sanitized result as evidence.
+## Branch and access
 
-## Environment and access contract
+Read `.agents/config/project.yaml` for the actual application target. Frontend/backend follow `deploy.frontend.branch`/`deploy.backend.branch`, including configured `main`. These explicit targets take precedence over a legacy generic `deploy.branch`. Do not create beta or assume production promotion is needed for a configured application main.
 
-- `READ-ONLY-BETA` and `READ-ONLY-PROD` are explicit query-only identities. They must have separate credentials and targets, remain unable to apply migrations, mutate backend data, change provider settings, or publish Git refs, and must never be substituted for a deploy credential.
-- Database automation publishes only the literal `beta` branch through reviewed migration PRs. Backend follows `deploy.backend.branch`, including `main` when configured. Database production promotion remains a human GitHub merge after review and required checks.
-- Frontend and site can publish their own validation builds from the configured validation branch. Their provider configuration remains project-owned and separate from production; this Git-only skill does not authorize a provider deployment.
-- A central database repository is optional and configured by the consuming project. Do not infer a repository name, remote, service target, or credential from another repository.
+Database alone retains literal `beta`, reviewed request-branch PRs and human production promotion. A migration request may publish its authorized `request/<id>` ref for a PR against beta; it never applies SQL or provisions resources. Read-only beta/production credentials cannot publish Git or mutate services.
 
-## Validation budget
+Run the reviewed folder-scoped SSH preflight for the selected application scope:
 
-Guarded local framework preparation requires the signed `essential-v3` receipt. It excludes
-dashboard-tab and XLSX certification; select `--profile full` explicitly when that extended
-coverage is required.
-The default legacy GitHub publisher accepts its separate exact-candidate qualification
-receipt only after the remote full gate and TGZ matrix. Explicit administrator activation after signed local qualification switches the
-publisher to the verified local receipt. One read-only install smoke then gates npm;
-no private-draft pilot is required. Activation is never implicit.
-Follow [local preparation](../../zaip-skill-release-qualification/references/local-preparation.md)
-for exact-candidate evidence, deadlines and rapid-preparation limits. Impact selection has
-no test-count ceiling; rapid results are not release receipts. Preserve consumer policy
-boundaries and reuse only valid matching evidence. On timeout, terminate the command tree,
-retain the failed gate and repair its evidenced cause; never omit gates to obtain success.
+```text
+node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository <ROOT> --remote origin --scope frontend
+```
 
-## Review and validate
+Use backend when that is the actual scope. Require SSH origin, repository-local or matching folder `core.sshCommand`, an existing key, Git identity and successful `ls-remote`. Do not change Git/SSH configuration, keys, remotes, accounts or transport; do not use process overrides. A configured remote target differs legitimately from a recovery branch or detached source.
 
-1. Snapshot `git status --short --branch`, file names, and the diff summary.
-2. Inspect suspicious environment, key, certificate, state, or credential files without printing secret values. Block secrets and files at or above GitHub's 100 MB limit.
-3. Reuse valid evidence for unchanged work. Run only gates required by repository Rules, the active Change, or the failed GitHub job.
-   - Turbo cache hits are valid only when the active work did not originate from a failed remote CI gate.
-   - When repairing failed CI, reproduce the exact failed gate once per repair cycle with Turbo cache bypassed when applicable.
-4. If a local gate fails, capture the exact failing command and error, make the smallest authorized repair, update lifecycle evidence, and start the next cycle without asking for another deploy authorization.
-5. After all required local gates pass, stage each reviewed selected-worktree path with `git add -- <explicit-pathspecs>`. If a file is secret, oversized, ignored by policy, or outside the selected worktree, exclude it and report the reason; otherwise include it.
+## Preserve and reconcile
 
-## Consumer release preparation
+1. Inspect selected status, intended tracked/untracked paths, index and pending commits. Check ignores, secrets and GitHub's 100 MB file limit without printing secrets.
+2. Fetch the target and compute ahead/behind for the authorized source. Before reconciliation, create and verify a recoverable ref and named stash covering tracked/untracked changes. Preserve concurrent index entries.
+3. Rebase by default, or merge when the user chose it, within authorized scope. Do not switch locally to the target, force, reset or rewrite published history. Restore with `stash apply`, retain it until preservation is verified and reconcile generated aggregates from canonical inputs.
+4. Re-inventory after repair. Stage explicit reviewed paths only, never `git add -A`, `git add -u` or broad globs. Functional partitioning is useful when ownership requires it, not a universal extra step.
+5. Use causal Task commit identity, hook and range validation. `CODEX|CLAUDE` and compact P/S/T lineage must be observed; standalone Task uses `[Task-first:XXXX]`. Subject is at most 96 characters with full IDs in trailers. See [commit policy](../../zaip-skill-task/references/commit-policy.md).
 
-Every authorized deploy must first compose `$zaip-skill-release-qualification` and use its guarded delivery entrypoint. Complete synchronization and commits before preparing the exact clean candidate. See [the executable preparation guide](../../zaip-skill-release-qualification/references/local-preparation.md). A prose review or an unsigned test result does not replace preparation.
+Dirty state, recovery branches, missing generated files and repairable divergence do not require a second authorization. Unresolved integrity/authentication failures, secrets, destructive requirements or necessary scope expansion are blockers.
 
-For `zaip-ai/zaip-aios` framework releases, use `scripts/local-release-deploy.mjs`: it prepares and verifies the candidate, pushes the exact SHA to `main`, uploads the verified assets to a draft release, and publishes that release. npm publication remains exclusively in GitHub Actions. Run the folder-scoped SSH preflight with the explicitly configured frontend scope before this entrypoint.
+## Select checks and deliver
 
-Before classifying a missing signer as a blocker, inspect the configured external signing-key path, trust store, policy and protected GitHub release variables without exposing secret contents. The private Ed25519 release key is distinct from the Git SSH key and a local `.env` npm token; the latter does not automatically reach Actions. If a required key or protected setting truly is absent, stop with its exact name and recovery action. Do not generate a replacement, rotate public trust or publish locally without separate authority. The user's 2026-09-23 standing authorization permits routine version-specific updates of **only** `ZAIP_LOCAL_RELEASE_POLICY_B64` in the verified `zaip-ai/zaip-aios` repository. When the enrolled policy names an older release, prepare a reviewed policy for the exact new version and fixed qualification profile; preserve repository, branch, channel, publication mode, non-force/non-replacement controls and trusted key. After successful signed local qualification and before Release publication, set that one variable to the exact UTF-8 policy bytes encoded in base64 and read it back byte-for-byte. A missing key, changed trust, weaker policy, failed readback or insufficient GitHub permission remains a blocker, not a reason to ask again for the already-authorized routine version update.
+**Commits mode:** use `scripts/guarded-commits.mjs` with its reviewed CLI. It validates scoped checks and binds delivery to the exact candidate and configured branch refspec. Select checks from changed behavior, acceptance criteria and observed failures. Do not require a release receipt, version bump, signing key, TGZ, dense distribution gate or full suite just to push commits. Direct installer/security impact still requires its relevant integrity or regression checks.
 
-After exact-candidate qualification, a missing GitHub Release is normal. Unless the request is explicitly push-only, use the configured entrypoint to create a draft for that SHA or resume a verified draft for the same SHA; do not recreate an existing Release. A published Release for the exact SHA is verified as a no-op, or its failed checks are repaired within the bounded cycle. An authentication or API error does not prove that a Release is absent.
+```text
+node .agents/skills/zaip-skill-github-deploy/scripts/guarded-commits.mjs --repository <ROOT> --sha <SHA> --branch <BRANCH> --scope frontend --request-file <FILE> --plan-file <FILE> --checks-file <FILE>
+```
 
-For a consumer repository, bootstrap its own Ed25519 trust store and define `configured_branch`, GitHub version `vN.N`, and `required_commands` in its project policy. `prepare` runs only those policy commands and signs a receipt after the Git identity is unchanged before and after them. `verify` checks the configured branch, exact SHA/tree, policy digest and trusted key. `guarded-push` runs prepare and verify before its explicit push command; a failed required command, dirty checkout, changed SHA/policy, or unavailable key prevents that command from running. This consumer flow is GitHub-only: it has no npm channel, package manifest version, or TGZ contract.
+Use the resolver's same plain-text request and JSON plan. The checks file is a JSON array of objects with `command` and `args`, selected for this work; for example, `[{"command":"node","args":["--test","path/to/affected.test.mjs"]}]`. It is not an array of argv arrays. Backend uses its actual scope. Complete Task-owned commits before calling the helper; it sends an already-committed exact SHA and does not create product commits.
 
-## Synchronize and publish each cycle
+**Release mode:** follow [release identity](release-identity.md), then [local preparation](../../zaip-skill-release-qualification/references/local-preparation.md). Synchronize and commit the candidate before exact-SHA qualification. Check published SHA before allocating a new version: unchanged published SHA is a no-op.
 
-Fetch the selected remote and configured target branch once per publication cycle, without SSH overrides. Compute ahead/behind from the selected source candidate against `<selected remote>/<configured branch>`. When the source is behind or diverged, apply the recorded bounded reconciliation strategy in place and continue after successful verification; do not switch to the target branch merely to satisfy publication. Stop only if reconciliation cannot be completed safely within the bounded repair cycles. Never reset or force.
+- Verified builder uses `scripts/local-release-deploy.mjs` and its protected signed preparation. Resolve mode locally first; perform signed preparation only for release mode. Once preparation has created its receipt directory, save the UTF-8 human request at `<output-dir>/deploy-request.txt` and generate the final-candidate contract at `<output-dir>/deploy-contract.json` using the resolver's `--request-file` and `--plan-file`. Do not pre-create the preparation directory for these inputs. The protected helper reads these fixed paths before reusing preparation or using credentials; no new request/plan CLI arguments expand the installed hook allowlist. Only GitHub Actions publishes `@zaip-ai/cli`.
+- The private Ed25519 release key is distinct from the Git SSH key and a local `.env` npm token. Never substitute credentials or print them; existing builder trust and protected policy remain mandatory for Release, not for commits.
+- Consumer release uses only its project's GitHub checks and reviewed release route. Do not demand builder Ed25519 material, protected GitHub variables, npm channel, package version or TGZ. An existing project-specific signed consumer helper may be used only under that project's adopted policy.
+- `prepare`, `verify` and dry-run never authorize or perform publication.
+- Immediately before sending, recheck policy, scope, target, candidate and checks. Changed identity or stale evidence requires renewed preparation. Use the guarded route; never bypass it with manual push.
+- Use immutable `<sha>:refs/heads/<configured-branch>`. After push, compare that SHA with the remote ref. A local branch name is not the proof.
 
-Commits created during Task execution use `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`: the effective executing-agent prefix followed by compact lineage.
+Detailed reviewed notes belong only in the GitHub Release. Observe the complete previous-Release-to-candidate Git diff and commit range; retain the full range/inventory as source and evidence. It is not limited to the current Task or chat. Group meaningful final outcomes, validate [release notes](release-notes.md), publish the reviewed UTF-8 body and read it back byte-for-byte. A compare link or generated notes alone is insufficient.
 
-- Codex: `[CODEX] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`
-- Claude: `[CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`
+## Recovery and verification
 
-The effective provider is `CODEX` or `CLAUDE`. P/S/T blocks require evidence; standalone Tasks use `[Task-first:XXXX]` followed by their canonical title. The subject remains ≤96 characters with title truncation at word boundaries; full IDs remain in `ZAIP-*` trailers. All product commits require a real Task, matching causal records and write scopes. Only `.agents/records/**` and `.local/**` changes are exempt; conversation capture does not authorize commits. Run `commit validate` and preserve the installed `commit-msg` hook. See `docs/task-commit-policy.md`. Explicit deploy never authorizes broad staging, force, destructive reset or squashing.
+Use the frozen Task autonomy profile, not a deploy-specific repair cap. Balanced permits 1 initial plus 9 repairs (10 executions total) and 3 replans. Tests, tool calls and elapsed time are not executions; continuation preserves the ledger. Persistent and essential retain their own configured limits. There is no independent five-cycle/two-repair stop or Task wallclock rule.
 
-Immediately before delivery, re-read the configured target with preflight and the explicit scope. If it changed, restart preparation for the new target. Consumer frontend/backend publication must use `consumer-release-preparation.mjs guarded-push`; framework publication must use `scripts/local-release-deploy.mjs`. These entrypoints bind preparation to the exact SHA and explicit branch refspec. Do not bypass them with a manual push. The separately authorized database request-branch PR route retains its database-specific gates and is outside these release helpers. A default deploy completes the Release flow; only an explicit push-only request stops after the push. If there is no unpushed commit or pending release after reconciliation and review, report a no-op.
+Run diagnostics/checks once per unchanged state and retry only after a concrete repair or new remote evidence. A transport ambiguity requires reading remote state first; a documented transient retry must stay within the existing attempt. Inspect exact failed CI steps, bypass stale cache only for the affected gate and never weaken checks.
 
-- If a push result is uncertain, read the remote state before acting. Reconcile a non-fast-forward through the existing bounded policy; retry one documented transient server or transport failure per cycle. Authentication, authorization, configuration, or other external-access failures are terminal blockers.
-- Never switch keys, accounts, remotes, or transport, and never pass SSH/config overrides or force options.
+Observe required checks for the exact SHA with concise progress while pending. Keep waiting through an active remote run; a tool timeout is not Task abandonment. Unavailable authentication/API access is a real blocker, never evidence that a Release, tag or check does not exist. Report push success separately from unconfirmed CI.
 
-## Verify and monitor GitHub checks
+## Completion and brief chat result
 
-1. After every push, compare `git rev-parse HEAD` with one `git ls-remote <remote> refs/heads/<configured branch>` result.
-2. Inspect required GitHub checks for that exact commit using an available authenticated GitHub CLI, API, connector, or browser session. Wait up to 20 minutes for terminal status and provide a concise progress update at least once per minute.
-3. If all required checks pass, confirm the remote hash, commit title, SSH identity source, key path, and worktree status.
-4. If a check fails, read the exact job and step logs before editing. Do not weaken or remove the check merely to obtain green status.
-5. Repair the evidenced cause, complete lifecycle records, and start the next cycle under the same user authorization.
-6. If checks cannot be observed, report the push as successful but CI as unconfirmed; never claim the deployment is fully validated.
+| Resolved mode | Required observed result |
+| --- | --- |
+| Commits | Scoped exact SHA on configured remote branch and valid required checks |
+| Consumer release | Commits result plus exact tag/SHA, Release URL and reviewed-body readback |
+| Builder release | Release result plus protected assets, terminal `publish-cli.yml` success and npm version/dist-tag/artifact integrity |
 
-## Release identity
+Verify preservation of unrelated files and index entries; require a clean owned candidate, not deletion or inclusion of unrelated work to make the whole checkout clean. Retry/resume an existing Release only with its original SHA/identity. Never create an empty new Release for an already-published candidate.
 
-Unless the request is push-only, resolve the release identity before mutation using the verified candidate SHA and tag list. Follow [the release identity contract](release-identity.md): consumer GitHub releases stay independent; framework `vN.N` maps to package `N.N.0`, and only qualified GitHub Actions can publish `@zaip-ai/cli` to npm.
+Chat reports the mode, branch/SHA, Release link when applicable and actual blocker/pending check briefly. Detailed change notes stay in the Release; evidence retains authority, full Git range and verification. Formal Task closure remains the responsible orchestrator/finalizer's work. GitHub publication does not authorize provider deployment, SQL, paid provisioning or host power actions.
 
-## Success condition
+## Current release and pre-main candidate
 
-For a full framework deploy, finish only when the local and remote hashes match, the intended worktree is clean, the exact Release identity/assets/body are verified, the associated `publish-cli.yml` run reaches success, and the npm registry confirms the intended `@zaip-ai/cli@N.N.0` version, dist-tag and artifact integrity. The workflow uses its configured GitHub credential/environment; a local `.env` does not publish the package. A published Release with failed or unobserved npm is partial, never a completed deploy. For a consumer or an explicit push-only request, apply only its authorized GitHub scope. Otherwise report the exact terminal blocker and repair cycles consumed.
+For builder release or a critical Task, reconcile attributed branches/worktrees first. An isolated terminal Task closes only after verified bundle/snapshot backup; a shared checkout with mixed product changes blocks for attribution. The current release's frozen manifest and exact SHA audit precede fixed local candidate checks. The only open-work exception is the authenticated critical release-only coordinator Task and its owner SPEC; its Task Run remains active during audit and advance, with exact SPEC/Execution/macro ancestry and candidate records. All other open current-release work blocks. Push only `main`, then require the successful `pre-main-candidate.yml` push run on that exact SHA before Release publication. Never create a remote CI candidate branch. Failed local checks block the push; failed remote CI or unavailable credentials block Release publication and require repair on `main`. After Release/npm and advance, bind closure Evidence to the published candidate, close Task and SPEC, then push one exact main metadata-only commit through `local-release-deploy.mjs push-closure` and observe CI on the new main SHA. PRD/SPEC drafts for a later release may remain.

package/templates/.agents/skills/zaip-skill-github-deploy/references/release-identity.md

@@ -1,49 +1,52 @@
 # Release identity contract
 
-Use the helper before a GitHub Release decision. It accepts a verified candidate SHA and either a verified tag list or an explicit canonical product version:
+Read only after the deploy resolver selects release, or for an explicitly requested local release preparation. Commits mode has no release version decision. Preparation alone never authorizes publication.
 
-```powershell
+## Observe before allocating
+
+Verify the repository's actual published Release and tag SHAs, draft state and candidate SHA through authenticated sources. An API/authentication error does not establish absence.
+
+If the current candidate is already the published SHA, verify that delivery as a no-op. Do not bump a version or create an empty Release. Resume a verified draft or retry an observed incomplete pipeline only with the exact same SHA, tag, version and reviewed body. A different candidate cannot reuse that identity or inherit its receipt.
+
+For a new candidate, select the numeric maximum canonical `vN.N` among observed tags, including prereleases, and increment the minor numerically by default: `v1.9` becomes `v1.10`. Initial release is `v1.0`; major changes require an explicit human request. Never move, delete, overwrite or recreate an existing tag. A conflicting tag needs the next allowed identity and a newly qualified candidate.
+
+Use the reviewed identity helper with a verified SHA and tag inventory or explicit candidate product version:
+
+```text
 node .agents/skills/zaip-skill-github-deploy/scripts/resolve-release-identity.mjs --sha <sha> --channel <validation|production> --tags-json <verified-json>
 node .agents/skills/zaip-skill-github-deploy/scripts/resolve-release-identity.mjs --sha <sha> --channel <validation|production> --version <N.N>
 ```
 
-- Product tags use canonical `vN.N`: begin at `v1.0`, increment the numeric minor by default, and change major only on an explicit request. The helper selects the numeric maximum across verified tags, including prereleases.
-- A retry may reuse a tag only when it belongs to the exact candidate SHA. Never move, delete, or recreate a tag.
-- Create a validation release only after preparing and validating the reviewed Markdown body required by the [release-notes contract](release-notes.md): `gh release create <tag> --repo <owner/repo> --target <sha> --title <title> --notes-file <reviewed-notes.md> --prerelease --latest=false`. Never use `--generate-notes`; a compare link alone does not describe a release. Read the published body back with `gh release view <tag> --repo <owner/repo> --json body` and validate it against the same inventory before declaring success. Production is human-promoted, has a new SHA, and must qualify and version again.
-- Record the product version, tag, exact SHA, channel, prerelease flag, and GitHub Release URL. GitHub checks, registry integrity, smoke, and lifecycle closure remain separate evidence.
+Frontend/backend follow their configured application branch, including main. Do not infer beta creation or a human promotion gate from main alone. Where the project selects a beta release, use prerelease without a version suffix. Database production retains its separate human-promotion requirement.
+
+## Reviewed notes and immutable delivery
+
+Observe the entire previous-Release-tag-to-candidate Git range, or explicit initial inventory when no prior tag exists. Follow [release notes](release-notes.md); keep detailed change notes in the Release and the full Git range in source/evidence.
+
+Create or resume the Release only for the verified candidate, using its reviewed UTF-8 notes file. Do not use generated notes alone. Resolve the tag's commit separately from `targetCommitish`, which may contain a branch name, and read back the body byte-for-byte.
+
+Record version, tag, exact SHA, channel, prerelease state, Release URL, range and inventory. Local qualification, GitHub checks, registry proof and lifecycle closure are separate evidence. A missing prior tag is normal for initial mode, not a blocker.
 
-## Deterministic recovery
+## Consumer boundary
 
-Resolve the candidate identity before any release mutation. A missing Release after exact-candidate qualification is normal: for a default deploy, create a new draft for the candidate SHA or resume an existing verified draft for that SHA. A published Release on that exact SHA must be verified as a no-op; retry only its observed failed CI within the bounded repair policy, never recreate the Release.
+A consumer release is GitHub-only. Qualify its own actual checks and adopt its reviewed release route; never require framework package manifests, TGZ, npm channel, builder signing keys or protected builder policy. If that project already requires the signed consumer helper, use its own trust and commands under that policy; do not create a new signing requirement merely because release was selected.
 
-If the intended tag resolves to another SHA, never move, delete, or recreate it. For a consumer, select the next allowed minor under its release policy, then prepare its new exact candidate. For the framework, select the next allowed minor, update all required package manifests, commit the version change, and prepare and qualify the resulting candidate on its configured release branch. A changed candidate never inherits its predecessor's qualification.
+Generic consumer deploy under auto selects commits. Only release mode enters this identity contract. One-shot explicit release does not change the saved preference.
 
-For a missing or expired receipt, use the candidate's configured preparation mechanism: a consumer runs its existing local `prepare` and `verify`; the framework uses its local release helper and receipt; a legacy remote qualification workflow runs only where the configured pipeline requires it, on the exact candidate SHA, branch, and channel. Observe a pending run; repair an observed failure under the existing limit of five cycles, stopping when the same cause remains after two repairs. Authentication, authorization, transport, or API failures do not establish that a Release, tag, receipt, or workflow run is absent; report them as access blockers. Keep exact-SHA readiness gates, protected trust rules, and human-only production promotion intact. A push-only request creates no Release; otherwise the deploy completes the Release flow.
+## Verified builder package and protected publisher
 
-For a first release, prepare the missing local notes and inventory in initial mode and validate them with `--initial`; absence of a prior tag is not a blocker.
+Recognize framework source only through approved origin `zaip-ai/zaip-aios`, root package `@zaip-ai/aios` and public CLI package `@zaip-ai/cli`. Names or installed framework files do not prove builder identity; contradictory signals block classification.
 
-## Framework package contract
+Select the next allowed `N.N` from observed release history, then update canonical root `package.json#version` to `N.N.0` and align the declared public/CLI manifests through the version tooling before committing and qualifying. The root manifest is the candidate's version source. Do not allocate an independent GitHub tag or replace version strings broadly. Retries retain the already-assigned version.
 
-Consumer repositories remain GitHub-only and independent. Recognize the framework source only when the approved `origin` is `zaip-ai/zaip-aios`, the root package is `@zaip-ai/aios` and `public-cli/packages/cli/package.json` identifies `@zaip-ai/cli`. Read the versions from the root, `public-cli/package.json` and CLI package manifests; require the same canonical `N.N.0` version, then call the helper with explicit `--version N.N`. Never allocate an independent GitHub version in this repository. A version change must update the declared package metadata before the candidate is committed and qualified; do not replace version strings broadly.
+Protected delivery uses `scripts/local-release-deploy.mjs`. First resolve mode in the Task's local area; only release mode may run signed `local-release-preparation.mjs prepare`. After that preparation successfully creates the receipt directory, save the actual UTF-8 human request at `<output-dir>/deploy-request.txt` and resolve its final-candidate contract to `<output-dir>/deploy-contract.json`. Do not pre-create the output directory just to write these files: preparation treats an existing directory as an immutable receipt cache. The resolver retains `--repository ROOT --request-file FILE --plan-file FILE`; the release helper reads only those fixed paths before reusing preparation or using publication credentials. Do not add request/plan CLI arguments or expand the installed hook allowlist. Resolve against the final committed candidate identity; stale contracts block delivery.
 
-Publishing a GitHub Release in this framework triggers its npm workflow. Report this consequence in the GitHub publication scope and follow the configured pipeline through terminal status; no second npm skill or local publication step is needed. A push-only request does not create a Release or publish npm. A successful GitHub Release with failed/unobserved npm checks is a partial result.
+Only qualified GitHub Actions may publish `@zaip-ai/cli`. Never run local `npm publish`, `pnpm publish` or equivalents. Bind SHA, tag, package version and artifact digest.
 
-`qualify-cli.yml` is manual-only. It does not run on every push. For an explicitly
-requested extended qualification, dispatch it on the configured branch with the exact
-current head `sha` and matching `npm_channel`. This extended path qualifies source
-and the runtime matrix; it does not publish npm or create a Release.
+With explicitly enabled `ZAIP_LOCAL_RELEASE_ENABLED=true`, use the signed local `essential-v3` receipt and enrolled public trust. GitHub verifies the published assets and runs one read-only exact-TGZ installation/doctor smoke before the isolated npm job. No legacy qualification receipt or private-draft pilot is required on that configured path.
 
-With explicitly enabled `ZAIP_LOCAL_RELEASE_ENABLED=true`, guarded delivery uses
-the signed local `essential-v3` receipt and enrolled public trust. It does not require a
-legacy `qualify-cli.yml` receipt or a private-draft pilot. GitHub verifies the
-published assets and runs one read-only exact-TGZ installation/doctor smoke before
-the separate npm publication job. Extended full qualification remains an explicit local option.
+When the reduced path is disabled, retain the legacy publisher's exact-candidate qualification receipt and runtime matrix. `qualify-cli.yml` is manual-only; dispatch it only when that configured release path or an explicit extended qualification requires it. `github-readiness.mjs` binds repository, SHA, branch, channel, qualifying run/attempt, receipt lifetime and artifact digests. Maximum receipt lifetime remains seven days. Missing/failed/stale evidence never permits fallback publication.
 
-Only when the reduced path is disabled does the legacy publisher require
-`github-readiness.mjs` with `--workflow-path .github/workflows/qualify-cli.yml`
-and `--checks-json '["receipt"]'` for the exact repository, SHA, branch and channel.
-It verifies the qualifying run/attempt, receipt lifetime and artifact digests.
-Missing or failed evidence never permits fallback publication. Receipts have a
-maximum seven-day lifetime; a changed candidate requires new qualification.
+Inspect configured signing paths, trust and protected policy before declaring a builder credential missing. Preserve the existing authority for routine version-specific updates of only `ZAIP_LOCAL_RELEASE_POLICY_B64`, with exact bytes and readback, described in [local preparation](../../zaip-skill-release-qualification/references/local-preparation.md). Trust rotation, changed protected settings or weaker gates require their own authority.
 
-Only the qualified GitHub Actions workflow may publish `@zaip-ai/cli` to npm. Never run `npm publish`, `pnpm publish`, or an equivalent local publication command. The workflow must bind the publication to the exact qualified SHA, tag, package version, and artifact digest.
+A published builder Release with failed/unobserved npm is partial. Continue its observed recovery under the frozen Task profile, balanced 10 executions/3 replans, without a new Release for the same SHA or a separate five-cycle cap.