docs(skills): record CI gating and worktree failure modes

docs/skills/ci/SKILL.md

@@ -50,6 +50,18 @@ gh run rerun RUN_ID --repo projectbluefin/bluefin --failed-only
 Read the actual workflow before describing or changing its behavior. Shared
 logic belongs in the reusable workflow that owns it; callers should stay thin.
 
+A pull request whose head branch lives on a fork reports **zero** checks until a
+maintainer approves the run. That looks identical to "checks still queued", so
+confirm the state before waiting on it:
+
+```bash
+gh pr view PR --repo projectbluefin/bluefin --json headRepositoryOwner,maintainerCanModify
+gh api -X POST repos/projectbluefin/bluefin/actions/runs/RUN_ID/approve
+```
+
+`maintainerCanModify: true` also means fix commits can be pushed straight to the
+contributor's branch.
+
 Containerfile stages that consume source through bind mounts inherit the mounted
 stage's image ID as part of their cache key. Give the package stage its own
 narrow `scratch` context so unrelated edits do not invalidate it, and pass an
@@ -63,6 +75,25 @@ MergeRaptor installation token to update one `testing-lab / bluefin` Check Run
 for the exact PR head SHA. Do not duplicate the result in a PR comment or commit
 status.
 
+## Workflow input and job constraints
+
+A `type: string` input is truthy in an `if:` even when its value is `"false"`.
+Gating on the bare input therefore fails **open**. Compare explicitly and treat
+any unexpected value as the safe state:
+
+```yaml
+if: inputs.publish_stream_tag == 'true'
+```
+
+A job that calls a reusable workflow accepts only `name`, `uses`, `with`,
+`secrets`, `needs`, `if`, and `permissions`. `continue-on-error` and
+`runs-on` are rejected, so a reusable-workflow call cannot be made advisory —
+it either gates or it is absent. `actionlint` catches this.
+
+A job listed in `needs:` without `always()` makes its dependents `skipped` when
+it fails. Confirm whether a promotion job is *failing* or *never running*; the
+two look the same in the UI and have different fixes.
+
 ## Hard rules
 
 - Verify the pull request base branch before debugging missing checks.
@@ -113,3 +144,6 @@ Read the affected YAML, identify the owning reusable workflow, validate locally.
 
 - Changing a caller when the behavior belongs in shared workflow logic.
 - Posting a lab result as a PR comment instead of updating the MergeRaptor Check Run.
+- Reading a gate's log message as proof of what it did. A step can report that a
+  tag was excluded and push it anyway; confirm against the pushed artifact.
+- Treating a fork PR with no checks as pending rather than unapproved.

docs/skills/release-artifacts/SKILL.md

@@ -39,6 +39,26 @@ gh run view RUN_ID --repo projectbluefin/bluefin --log-failed
 gh run watch RUN_ID --repo projectbluefin/bluefin --exit-status
 ```
 
+## Verify a stream tag against its gate
+
+A stream tag (`:testing`, `:stable`) is a claim that a digest passed its gate.
+Verify the claim rather than trusting the tag: resolve what the tag points at,
+then confirm that digest actually passed.
+
+```bash
+skopeo inspect docker://ghcr.io/projectbluefin/bluefin:testing --format '{{.Digest}}'
+gh run list --repo projectbluefin/bluefin --workflow post-testing-e2e.yml --limit 20
+```
+
+A promotion job reported as `skipped` while the stream tag still advanced means
+something outside the gate is publishing it. Build-time tag computation is the
+usual source: the bare stream tag can sit in the tag list that the push step
+consumes, so excluding it from a conditional does not remove it from the push.
+Filter the stream tag out of the list itself.
+
+Never re-point or delete a published stream tag to "repair" this — that is
+user-visible and belongs to a human.
+
 ## Red flags
 
 - Re-pulling a large image during release only to generate metadata.
@@ -65,8 +85,11 @@ Read the workflow, verify the exact digest and artifact, then inspect the run.
 ## Red Flags
 
 - Guessing tags or bypassing a failed release gate.
+- Trusting a stream tag as evidence of promotion without resolving its digest.
+- A promotion job that has never succeeded, yet its stream tag keeps advancing.
 
 ## Verification
 
 - [ ] The selected source and focused command were checked.
+- [ ] The stream tag's digest was resolved and traced to a passing gate run.
 - [ ] The repository default gate passes.

docs/skills/worktrees/SKILL.md

@@ -105,6 +105,23 @@ whether a branch is finished. `worktree.sh` asks the forge via `gh` instead.
 | `worktree already exists` | Stale directory from earlier work | `worktree.sh done <branch>`, or `git worktree prune` if the directory is already gone |
 | Untracked `.worktrees/` in `git status` | Hook and ignore rules predate this setup | Confirm `.worktrees/` is in `.gitignore` |
 | Uncommitted work blocks `done` | Real changes in the worktree | Commit them, or `git worktree remove <path> --force` to discard |
+| A repo script reports zero files | It filters `.worktrees` out by path and is running inside one | Run it from the main checkout, or fix the filter to be checkout-relative |
+
+Tooling that excludes `.worktrees/` by absolute path components silently matches
+*everything* when it runs from inside a worktree. A validator that passes with a
+zero-file count is failing, not succeeding — check the count, not the exit code.
 
 Never use `git add -A` or `git add .`. Stage explicit paths, then verify with
 `git status` and `git diff --cached --name-only` before committing.
+
+## Red Flags
+
+- Feature work committed directly in the main checkout.
+- A validator or linter reporting suspiciously few files while run in a worktree.
+- Removing a worktree with uncommitted changes instead of resolving them.
+
+## Verification
+
+- [ ] `bash .github/scripts/worktree.sh list` shows the expected worktrees.
+- [ ] Repository checks were run and reported a non-zero file count.
+- [ ] The main checkout is clean and on `testing` or `main`.