@1aboveio/skills 0.20.1 → 0.20.3

package/skills/document-utils/reg-parser/scripts/validate_mandate.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Validate a mandate (Mode A — Clause Annotation Extract) Markdown file.
+
+Catches the failure modes specific to mandate extracts produced by the
+`reg-parser` skill:
+
+  - Agent left the raw template scaffolding behind (Status: RAW, HTML
+    comment placeholders, the embedded raw-text fenced block).
+  - One of the four canonical sections is missing or silently empty.
+  - Header metadata (Source attribution, jurisdiction/version/date) is
+    missing.
+  - Notes section is empty or stub.
+
+Optional --source <converted-md> enables citation-existence warnings:
+each `§<ref>` cited in the extract is fuzzy-matched against the source
+markdown. Missing citations emit warnings, not errors (refs are often
+restyled during extraction).
+
+Usage:
+    python3 validate_mandate.py <mandate.md> [--source <converted-md>]
+
+Exit code 0 = valid. Non-zero = errors found.
+"""
+
+import argparse
+import re
+import sys
+import os
+
+REQUIRED_SECTIONS = [
+    "Mandatory Downstream Agreement Clauses",
+    "Prohibited Conduct",
+    "Thresholds & Triggers",
+    "Audit & Oversight Rights",
+    "Notes",
+]
+
+# Markers an agent may use to indicate a section legitimately has no entries.
+EMPTY_MARKERS = ("_none_", "(none)", "n/a", "not applicable", "none.")
+
+# Header metadata keywords — at least one must appear in the header block
+# (between H1 and the first H2). Matches the conventions in the existing
+# extracts (visa-vars.md, hk-amlo-cap615.md).
+HEADER_KEYWORDS = ("source", "jurisdiction", "version", "effective", "updated", "date")
+
+# Patterns that indicate the agent left raw template artifacts behind.
+RAW_STATUS_RE = re.compile(r"^\s*>\s*\*?\*?Status:\*?\*?\s*RAW", re.IGNORECASE)
+RAW_TEXT_HEADING_RE = re.compile(r"^##\s+Raw Text\b", re.IGNORECASE)
+SCAFFOLDING_COMMENT_RES = [
+    re.compile(r"<!--\s*Agent:\s*replace", re.IGNORECASE),
+    re.compile(r"<!--\s*Format:\s*\*\*§\[ref\]"),
+    re.compile(r"<!--\s*Clauses the counterparty"),
+    re.compile(r"<!--\s*Explicitly prohibited"),
+    re.compile(r"<!--\s*Numeric thresholds"),
+    re.compile(r"<!--\s*Rights granted"),
+    re.compile(r"<!--\s*Jurisdiction scope, effective date"),
+]
+
+# A §-style citation. Captures common forms: §AACQ.C2.1, §76E,
+# §Sched.2 §2(1)(a), § 14(3)(b). The capturing group keeps just the
+# alphanumeric/punctuation token; the leading § is consumed.
+CITATION_RE = re.compile(r"§\s*([A-Za-z0-9][A-Za-z0-9.\-]*(?:\([^)]+\))*)")
+
+H1_RE = re.compile(r"^#\s+(.+?)\s*$")
+H2_RE = re.compile(r"^##\s+(.+?)\s*$")
+
+
+def split_sections(lines: list[str]) -> tuple[list[str], dict[str, list[str]]]:
+    """Return (header_lines, {section_title: body_lines})."""
+    header: list[str] = []
+    sections: dict[str, list[str]] = {}
+    current: str | None = None
+    seen_h1 = False
+
+    for line in lines:
+        if not seen_h1 and H1_RE.match(line):
+            seen_h1 = True
+            continue
+        h2 = H2_RE.match(line)
+        if h2:
+            current = h2.group(1).strip()
+            sections.setdefault(current, [])
+            continue
+        if current is None:
+            header.append(line)
+        else:
+            sections[current].append(line)
+
+    return header, sections
+
+
+def section_is_empty(body: list[str]) -> bool:
+    """A section is empty if it has no §-bullet entries AND no explicit
+    'none' marker."""
+    text = "\n".join(body).strip()
+    if not text:
+        return True
+    lower = text.lower()
+    if any(marker in lower for marker in EMPTY_MARKERS):
+        return False
+    if "**§" in text or re.search(r"^\s*§", text, re.MULTILINE):
+        return False
+    if "§" in text and re.search(r"§\s*[A-Za-z0-9]", text):
+        return False
+    return True
+
+
+def extract_citations(text: str) -> set[str]:
+    """Pull §-style citation tokens out of arbitrary text."""
+    return {m.group(1) for m in CITATION_RE.finditer(text)}
+
+
+def fuzzy_present(token: str, haystack_lower: str) -> bool:
+    """Best-effort: token appears in source if either the literal token
+    or a heavily-normalized form (lowercased, punctuation stripped) does.
+    """
+    if token.lower() in haystack_lower:
+        return True
+    norm = re.sub(r"[^a-z0-9]", "", token.lower())
+    if not norm:
+        return False
+    norm_haystack = re.sub(r"[^a-z0-9]", "", haystack_lower)
+    return norm in norm_haystack
+
+
+def validate(filepath: str, source_path: str | None) -> tuple[list[str], list[str]]:
+    """Return (errors, warnings)."""
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if not os.path.isfile(filepath):
+        return [f"File not found: {filepath}"], []
+
+    with open(filepath, "r", encoding="utf-8") as f:
+        raw = f.read()
+    lines = raw.splitlines()
+
+    # --- Raw template artifacts ---
+    for line_num, line in enumerate(lines, 1):
+        if RAW_STATUS_RE.match(line):
+            errors.append(
+                f"Line {line_num}: 'Status: RAW' marker still present — "
+                f"agent extraction not completed"
+            )
+        if RAW_TEXT_HEADING_RE.match(line):
+            errors.append(
+                f"Line {line_num}: '## Raw Text' section still present — "
+                f"remove the embedded raw-text dump after extraction"
+            )
+        for pat in SCAFFOLDING_COMMENT_RES:
+            if pat.search(line):
+                errors.append(
+                    f"Line {line_num}: leftover template scaffolding comment"
+                )
+                break
+
+    # --- Structure ---
+    header_lines, sections = split_sections(lines)
+
+    if not any(H1_RE.match(line) for line in lines):
+        errors.append("Missing H1 title (expected '# <Source> — Contract Obligation Extract')")
+
+    # Header metadata: at least one of Source/Jurisdiction/Version/etc.
+    header_text = "\n".join(header_lines).lower()
+    if not any(kw in header_text for kw in HEADER_KEYWORDS):
+        errors.append(
+            "Header metadata block missing — expected blockquote with "
+            "Source / Jurisdiction / Version / Effective Date"
+        )
+
+    # The Source attribution specifically is critical.
+    if "source" not in header_text:
+        errors.append("Header missing 'Source:' attribution")
+
+    # Required sections present
+    for required in REQUIRED_SECTIONS:
+        if required not in sections:
+            errors.append(f"Missing required section: ## {required}")
+
+    # Required content sections non-empty
+    for required in REQUIRED_SECTIONS[:-1]:  # everything except Notes
+        body = sections.get(required)
+        if body is not None and section_is_empty(body):
+            errors.append(
+                f"Section '## {required}' is empty — if there are no "
+                f"items, mark explicitly as '_None_'"
+            )
+
+    # Notes substance check
+    notes_body = sections.get("Notes")
+    if notes_body is not None:
+        notes_text = "\n".join(notes_body).strip()
+        if len(notes_text) < 50:
+            errors.append(
+                "Section '## Notes' is too short — include jurisdiction "
+                "scope, effective date, version, and caveats"
+            )
+
+    # --- Optional: citation existence check ---
+    if source_path:
+        if not os.path.isfile(source_path):
+            warnings.append(f"--source file not found: {source_path}")
+        else:
+            with open(source_path, "r", encoding="utf-8") as sf:
+                source_lower = sf.read().lower()
+            cites = extract_citations(raw)
+            missing = sorted(c for c in cites if not fuzzy_present(c, source_lower))
+            if missing:
+                preview = ", ".join(f"§{c}" for c in missing[:8])
+                more = "" if len(missing) <= 8 else f" (+{len(missing) - 8} more)"
+                warnings.append(
+                    f"{len(missing)} citation(s) not found in source: {preview}{more}"
+                )
+
+    return errors, warnings
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    p.add_argument("filepath", help="Path to mandate Markdown file")
+    p.add_argument(
+        "--source",
+        help="Optional path to the converted source Markdown for citation checks",
+    )
+    args = p.parse_args()
+
+    errors, warnings = validate(args.filepath, args.source)
+
+    for w in warnings:
+        print(f"  ⚠️  {w}", file=sys.stderr)
+
+    if errors:
+        print(f"❌ Validation failed for {args.filepath}:", file=sys.stderr)
+        for err in errors:
+            print(f"  • {err}", file=sys.stderr)
+        sys.exit(1)
+    print(f"✅ {args.filepath} is valid.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -342,7 +342,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1"
+        "version": "0.20.3"
       },
       "contentDigest": "eff6c7b5931bce5b2265a619bccddd371a89df6ce7bc2edc74f11d00060a71dd",
       "digestExcludes": []
@@ -355,7 +355,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1"
+        "version": "0.20.3"
       },
       "contentDigest": "d97abeff7bdc5ae2e4be2f631d09dba46d4753ce1e67334793364329af59f066",
       "digestExcludes": []
@@ -368,9 +368,9 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1"
+        "version": "0.20.3"
       },
-      "contentDigest": "00cfdd3e5bfbc3e37b1369ad93aae91161e671829760a8867ea9be25047ba461",
+      "contentDigest": "fe2ec3bae2bfec2dbef19db30ab0272391d7c1d9b6893341a76a9f339adefc57",
       "digestExcludes": []
     },
     {
@@ -381,7 +381,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1"
+        "version": "0.20.3"
       },
       "contentDigest": "58b0556228a9271cf9e33727a05fc08a4fdfd29512ec0936b169f0a55d60e6ef",
       "digestExcludes": []
@@ -394,9 +394,9 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1"
+        "version": "0.20.3"
       },
-      "contentDigest": "4664873230f22de2fcf46b7b529570cfedabdc850620031d8f96baf89fcdc5b4",
+      "contentDigest": "d28dd4d3c4394df0cc7e6b48d0e5daa7d2277701ea459e39fba99acf1d8ff670",
       "digestExcludes": []
     },
     {
@@ -407,9 +407,9 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1"
+        "version": "0.20.3"
       },
-      "contentDigest": "01c192d8b4fd416af4ea02e8000e5fce0cee723a6ac2f8c0c48372087e1a262e",
+      "contentDigest": "56fb5843788c9073b0d5a65ffa72bd7d2fa80dc6a1ff06fb0e19fab513c51502",
       "digestExcludes": []
     },
     {
@@ -420,7 +420,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1"
+        "version": "0.20.3"
       },
       "contentDigest": "f048fd00c69f2dc666fc7a3096cfeee6dfba73933bfb69602f3f0e26159798cc",
       "digestExcludes": []
@@ -433,9 +433,9 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1"
+        "version": "0.20.3"
       },
-      "contentDigest": "27861f6dac89c32a97a7d249ce2695cea2d3d80dd2e9bc0607b0c4048a0e3b25",
+      "contentDigest": "d533684db4483cfc90be2aa7161980b6548057ef18a4b54f0cdbcd53c79dd46d",
       "digestExcludes": []
     },
     {
@@ -446,15 +446,15 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1"
+        "version": "0.20.3"
       },
-      "contentDigest": "3e0952beee7078463464872943d414fa944b395ae723ec78b385a28a3548897a",
+      "contentDigest": "aa7b7dbeec2fd5d64883f4b6bf5ae99a3f77cad84f635cfbdf7cb1999de362e6",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "baec385a2bc0414623c97a83ac4ebf3c44ede2654185b748a03ef955cb3f1c8d",
+  "releaseIdentity": "4804a31efab8c7a93325ebdfeee74ce04c89130470d4eb5a878b37ac183266cd",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",
@@ -512,7 +512,7 @@
         "sourceId": "first-party",
         "sourceType": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.20.1",
+        "version": "0.20.3",
         "installPath": null,
         "members": [
           "harness-runtime",
@@ -528,7 +528,7 @@
         "commands": [
           {
             "transport": "npm",
-            "command": "npx @1aboveio/skills@0.20.1 install --group engineering-workflow --yes"
+            "command": "npx @1aboveio/skills@0.20.3 install --group engineering-workflow --yes"
           }
         ],
         "onFailure": {

package/skills/engineering/engineering-runtime/scripts/workflow-coherence.mjs

@@ -154,6 +154,10 @@ const TEST_FIXTURE = /\.fixtures?\.[^.]+$/;
 export function publishedContentExcluded(name) {
   return name.startsWith('.')
     || name === 'node_modules'
+    || name === '__pycache__'
+    || name === 'evals'
+    || name === 'samples'
+    || name === 'tests'
     || name.endsWith('-workspace')
     || name.endsWith('.test.mjs')
     || TEST_FIXTURE.test(name);

package/skills/engineering/engineering-runtime/scripts/workflow-policy.mjs

@@ -86,7 +86,7 @@ export const WORKFLOW_TRUSTED_SOURCES = deepFreeze({
     id: 'first-party',
     type: 'first-party',
     package: '@1aboveio/skills',
-    version: '0.20.1',
+    version: '0.20.3',
   },
   matt: {
     id: 'matt-pocock',

package/skills/engineering/rush-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rush-release
-description: "Slash/explicit-only (/rush-release). Cut a GitHub Flow release from main: freeze the latest CI-green trunk SHA, write the changelog, choose SemVer, merge the metadata cut through a verified PR, tag the exact merged main SHA, and watch Cloud Build or npm publish. Do not auto-select. Use only on explicit user/orchestrator invoke. NOT for GitFlow/release-branch/0%-traffic promotion (resolve-release) and NOT for implementing a spec (rush-issues)."
+description: "Slash/explicit-only (/rush-release). Cut a GitHub Flow release from main: freeze the latest CI-green trunk SHA, write the changelog, choose SemVer, merge the metadata cut through a verified PR, publish npm artifacts, or validate a Cloud Run candidate at 0% before shifting it to 100%. One complete-plan confirmation covers the conditional release. Do not auto-select. Use only on explicit user/orchestrator invoke. NOT for GitFlow/release-branch promotion and NOT for implementing a spec (rush-issues)."
 disable-model-invocation: true
 ---
 
@@ -10,9 +10,10 @@ Cut a **GitHub Flow** release from **main**. Freeze one already-green trunk
 SHA, write a metadata-only version cut on that parent, merge it through a
 verified PR, tag the exact merged SHA on `main`, and watch the publisher.
 
-The orchestrator sequences local programs and one confirmation. It does not
-assemble a release branch, shift traffic, or verify production like
-`resolve-release`.
+The orchestrator sequences local programs and exactly one user confirmation per
+release plan. It does not assemble a long-lived release branch. For Cloud Run,
+it owns one bounded candidate-at-0% -> validate -> shift-to-100% -> verify-live
+sequence; the confirmation conditionally authorizes that whole sequence.
 
 ```text
 preflight (main + publisher)
@@ -21,8 +22,9 @@ preflight (main + publisher)
   -> confirm
   -> bump version files + commit the cut
   -> merge metadata PR + verify merged main SHA
-  -> annotated tag on the merged SHA
-  -> push tag -> watch Cloud Build or npm
+  -> npm: final tag -> watch publish
+  -> Cloud Run: rc tag -> candidate at 0% -> validate -> shift to 100%
+     -> verify live -> final tag
 ```
 
 This file is the workflow and index. Read the linked procedure immediately
@@ -33,7 +35,8 @@ before its stage; do not invent an unlinked substitute.
 | Trunk, publisher, version files | [references/preflight.md](references/preflight.md) |
 | Latest CI-green HEAD | [references/candidate.md](references/candidate.md) |
 | Changelog, SemVer, file bump, commit | [references/cut.md](references/cut.md) |
-| Tag, push, watch deploy | [references/publish.md](references/publish.md) |
+| Tag, push, watch publisher | [references/publish.md](references/publish.md) |
+| Cloud Run 0% -> 100%, verification, rollback | [references/promotion.md](references/promotion.md) |
 
 Run every script as
 `node <skillsRoot>/rush-release/scripts/<name>.mjs …` with the absolute skill
@@ -54,8 +57,22 @@ target repo and will not find these files.
   release tree's CI evidence.
 - Tags are immutable annotated `vMAJOR.MINOR.PATCH` names. Do not move, delete,
   or force-push a tag that reached a remote.
-- Show the plan and wait for confirmation before any git mutation or push.
-- A failed watch is a hand-back. This lane does not roll back production.
+- A Cloud Run release uses one immutable `vMAJOR.MINOR.PATCH-rc.N` tag to build
+  the candidate at 0%. The final tag is created only after that exact candidate
+  serves 100% and passes live verification; it must not trigger another deploy.
+- Ask once, on the complete plan, before any git mutation or push. That answer
+  authorizes the listed branch/commit, metadata PR delivery, candidate build,
+  conditional traffic shift, rollback, final tag, optional GitHub Release, and
+  publisher watch as one operation. Do not ask separate cut, merge, RC,
+  exposure, tag, finalization, or publish questions.
+- Preflight facts are detected, not confirmed by the user. Fold any genuinely
+  missing choice into the one plan question instead of asking a preliminary
+  question. If the plan's frozen SHA, version/tag, metadata diff, publisher, or
+  outward actions later change, stop and present one replacement plan; otherwise
+  continue without re-confirming.
+- A pre-exposure failure is a hand-back with production untouched. A known
+  post-exposure failure automatically restores and verifies the recorded
+  incumbent. Ambiguous production state is a stop for operator recovery.
 - The cut is metadata only (changelog + version identity files). Refuse a
   cut that changes product code.
 
@@ -63,8 +80,8 @@ target repo and will not find these files.
 
 ### 1. Preflight
 
-Confirm `main` is the trunk, detect whether the tag should fire Cloud Build,
-npm, or both, and list the files that carry the version. Details:
+Verify `main` is the trunk, detect npm and/or the staged Cloud Run contract,
+and list the files that carry the version. Details:
 [preflight.md](references/preflight.md).
 
 ### 2. Candidate
@@ -72,28 +89,32 @@ npm, or both, and list the files that carry the version. Details:
 Fetch `origin/main` and pick the newest green SHA. Freeze it. Details:
 [candidate.md](references/candidate.md).
 
-### 3. Plan and confirm
+### 3. Plan and confirm once
 
-Derive the changelog and SemVer bump from `baselineTag..frozenSHA`. Show SHA,
-bump, version, tag, files, publisher, and notes. Do not mutate until the human
-confirms. Details: [cut.md](references/cut.md).
+Derive the changelog and SemVer bump from `baselineTag..frozenSHA`. For Cloud
+Run, pass `--cloud-run` so the plan also reserves the next unused RC tag. Show
+SHA, bump, version, tags, files, publisher, notes, and every outward action. Ask one
+question that both settles any unresolved choice and authorizes the whole listed
+sequence. Do not mutate until the human confirms, and do not ask again while the
+approved plan remains unchanged. Details: [cut.md](references/cut.md).
 
 ### 4. Cut
 
 Branch from the frozen SHA, apply the changelog and version files, commit.
 Keep the diff metadata-only.
 
-### 5. Merge, tag, and watch
+### 5. Merge and publish
 
-Push the cut ref, merge its PR through the repository queue, verify the exact
-merged SHA on `main`, create the annotated tag on that SHA, push
-`refs/tags/<tag>` with hook-safe `--no-verify`, then watch Cloud Build and/or
-npm. Details: [publish.md](references/publish.md).
+Push the cut ref, merge its PR through the repository queue, and verify the
+exact merged SHA on `main`. An artifact-only release pushes the final tag and
+watches npm. A staged Cloud Run release pushes its RC tag, executes
+[promotion.md](references/promotion.md), and creates the final tag only after
+live verification. Details: [publish.md](references/publish.md).
 
 ## Done
 
-Success is the confirmed version tagged at the verified merged `main` SHA, the tag visible on the
-remote, and the chosen publisher reporting that version (Cloud Build SUCCESS
-and/or `npm view <pkg>@<version>`). Hand back the cut SHA, merged SHA, tag,
-changelog excerpt, publisher evidence, and the merged metadata PR. A publisher failure hands back the same identities without claiming
-the version shipped to users.
+Success is the confirmed version tagged at the verified merged `main` SHA and
+visible on the remote. npm must report the version when selected. Cloud Run
+must report the exact candidate serving 100%, the incumbent at 0%, and an ALIVE
+`prod-active` verdict. Hand back the cut SHA, merged SHA, RC/final tags,
+changelog excerpt, publisher and traffic evidence, and the merged metadata PR.

package/skills/engineering/rush-release/references/cut.md

@@ -8,10 +8,16 @@ along for the ride.
 ```bash
 node <skillsRoot>/rush-release/scripts/plan.mjs --sha <candidateSha> --json \
   > /tmp/rush-release-plan.json
+# Add --cloud-run when preflight selected cloud-run-staged.
 ```
 
 The plan names `baselineTag`, `currentVersion`, `bump`, `reason`,
-`nextVersion`, `tag`, `changelogMarkdown`, and `versionFiles`.
+`nextVersion`, final `tag`, optional `candidateTag`, `changelogMarkdown`, and
+`versionFiles`.
+
+Before showing the plan, use `git ls-remote --tags origin` to prove the proposed
+candidate and final tags are both unused remotely. Local tag discovery chooses
+the next RC ordinal; remote absence is the collision authority.
 
 SemVer (0.x treats breaking as minor unless the human asks for strict):
 
@@ -26,13 +32,24 @@ Changelog entries come from conventional-commit subjects in
 tag). Keep an existing `## [Unreleased]` body — derived entries merge with it,
 they do not replace it.
 
-## 2. Confirm
+## 2. Confirm once
 
-Show the frozen SHA, proposed version/tag, bump reason, changelog, version
-files, and publisher. Wait for confirmation. A different bump the human names
+Show the frozen SHA, proposed version/tag(s), bump reason, changelog, version
+files, publisher/deployment mode, and the complete outward-action sequence: create the cut
+branch/commit, push it, deliver its metadata PR through the queue, push the
+immutable tag(s), validate and conditionally promote Cloud Run when applicable,
+create a GitHub Release when required, and watch the publisher.
+Ask exactly one question. Its answer both settles any displayed unresolved
+choice and authorizes that entire sequence. A different bump the human names
 wins, as long as it is still SemVer.
 
 Do not create a branch, edit files, or tag before that confirmation.
+After it, proceed through publication without asking separate cut, merge, RC,
+exposure, tag, finalization, or publish questions. Repository/provider checks
+are gates the orchestrator evaluates, not reasons to ask the human to confirm
+facts. Ask again only by replacing the whole plan when its frozen SHA,
+version/tag, metadata diff, publisher, or outward actions change. A retry or
+resume of the unchanged plan inherits the original authorization.
 
 ## 3. Apply and commit
 

package/skills/engineering/rush-release/references/preflight.md

@@ -1,12 +1,15 @@
 # Preflight
 
-Preflight has three outputs: trunk `main`, the publisher to watch, and the
-files that carry the version. It does not pick the SHA, bump the version, or
-push.
+Preflight outputs trunk `main`, publishers, deployment mode, release commands,
+and the files that carry the version. It does not pick the SHA, bump the
+version, or push. Resolve these facts from repository and provider state without asking the
+human to confirm each one. If a required choice cannot be inferred, carry it
+into the single complete-plan question in [cut.md](cut.md); do not create a
+separate preflight confirmation.
 
 ## 1. Trunk
 
-Fetch `origin`. Confirm the release trunk is `main` from those fetched refs
+Fetch `origin/main` and all remote tags. Verify the release trunk is `main` from those fetched refs
 (`origin/main` exists). A repo whose production branch is `master` or `release`
 is not this workflow.
 
@@ -17,12 +20,28 @@ otherwise look at the tree:
 
 | Signal | Publisher |
 |---|---|
-| `cloudbuild.yaml` / `cloudbuild.json`, or a Cloud Build trigger on `v*` / `v*-rc.*` tags | `cloudbuild` |
+| Cloud Build production trigger matching only `v*-rc.*`, whose prod path emits immutable candidate coordinates after `--no-traffic` | `cloudbuild`, mode `cloud-run-staged` |
 | `package.json` with a publish workflow, `publishConfig`, or an explicit npm release | `npm` |
 | both | watch both |
 | neither, and the human did not name one | refuse — nothing to watch |
 
-Record `publisher` as `cloudbuild`, `npm`, or `both`. If a GitHub Actions
+Cloud Build presence alone is not a staged contract. For `cloud-run-staged`,
+verify from repository policy and live trigger configuration:
+
+- the production trigger matches RC tags and excludes the final `vX.Y.Z` tag;
+- each affected service deploys an immutable revision with `--no-traffic` and
+  publishes one receipt binding RC tag, merged SHA, revision, image digest, and
+  candidate URL;
+- `smoke.manifest.json` defines read-only `prod-preview` and `prod-active`
+  profiles with at least one eligible path;
+- exact inspect, traffic-shift, rollback, and candidate-delete commands are
+  documented, including service dependency order;
+- any durable processing affected by a shift has exact pause, quiescence,
+  resume, and restoration checks.
+
+Refuse staged release when any applicable item is absent; never improvise
+production commands. Record `publisher` as `cloudbuild`, `npm`, or `both` and
+`deploymentMode` as `artifact-only` or `cloud-run-staged`. If a GitHub Actions
 workflow publishes on `release: published` rather than on tag push, note that
 `gh release create` is required at publish time.