fixup: Revise for consistency with task-docmenting parent branch

Change-Id: I08aae438ee4e238ba919cad55fddacd8eb68a095

Author: maru-ava

docs/ci.md

@@ -1,81 +1,81 @@
 # CI
 
-This document explains the CI rules that apply across the repo.
+This document explains how to maintain the CI conventions that apply across the
+repo.
 
 Use it when changing workflows, adding actions, or reviewing CI changes that
 should follow a shared repo rule rather than a one-off local choice.
 
 ## Table of contents
 
-- [Overview](#overview)
-- [Usage](#usage)
-- [Conceptual model](#conceptual-model)
-  - [Use stable repo entrypoints](#use-stable-repo-entrypoints)
+- [Principles](#principles)
+- [How CI should work in this repo](#how-ci-should-work-in-this-repo)
+  - [Keep repo behavior in stable entrypoints](#keep-repo-behavior-in-stable-entrypoints)
   - [Pin runner labels](#pin-runner-labels)
   - [Pin third-party actions](#pin-third-party-actions)
-  - [Only `actions/*` may use major tags](#only-actionsmay-use-major-tags)
-  - [How these rules are enforced today](#how-these-rules-are-enforced-today)
+  - [Only `actions/*` may use major tags](#only-actions-may-use-major-tags)
+  - [Some CI-only setup still belongs in workflows](#some-ci-only-setup-still-belongs-in-workflows)
+  - [Checks enforce common mistakes](#checks-enforce-common-mistakes)
+- [Examples](#examples)
+  - [Good: a workflow runs a named task](#good-a-workflow-runs-a-named-task)
+  - [Good: a workflow uses a local action](#good-a-workflow-uses-a-local-action)
+  - [Avoid: workflow-only repo behavior](#avoid-workflow-only-repo-behavior)
 - [Maintainer guidance](#maintainer-guidance)
 - [References](#references)
 
-## Overview
+## Principles
 
-The main CI goals in this repo are:
-
-- keep workflow behavior easy to find and review
-- make CI runs easier to reproduce locally when that is useful
-- make upgrades to runners and external actions intentional
+- Keeping CI behavior in the repo makes it **easy to find and review**.
+  - A contributor can inspect how a workflow launches an operation without
+    reconstructing a shell command from YAML.
+- Reusing normal repo entrypoints makes CI **easier to reproduce locally**.
+  - Local execution may still need CI-only infrastructure or credentials.
+- Pinning runner images and external actions makes upgrades **intentional**.
+  - A change to either is visible in a reviewed repo change rather than
+    happening when an upstream floating reference moves.
 
 Feature-specific CI details should live with the feature that owns them. This
-page is only for rules that apply across workflows and local composite actions.
-
-## Usage
+page is for rules that apply across workflows and local composite actions.
 
-Use this document when you are:
+## How CI should work in this repo
 
-- adding or reviewing a GitHub Actions workflow
-- adding or updating a GitHub Action from outside this repo
-- deciding whether workflow logic belongs in a task, a local action, or a
-  small CI-only helper
-- deciding whether a workflow is doing too much work in YAML
+These guidelines describe the repo's default approach to CI, not rules that
+forbid every exception. When a different design is warranted, it should still
+be easy to explain in terms of keeping behavior discoverable, reproducible when
+useful, and intentional to upgrade.
 
-For task-specific guidance, including when workflows should call
-`./scripts/run_task.sh`, see [Tasks](./tasks.md).
-
-## Conceptual model
-
-### Use stable repo entrypoints
+### Keep repo behavior in stable entrypoints
 
 When CI runs behavior defined in this repo, it should usually call an existing
 repo command, task, script, or action instead of building the real command in
-the workflow.
+workflow YAML.
 
 In practice, that usually means one of:
 
 - a named task launched with `./scripts/run_task.sh`
 - a local composite action under `./.github/actions/`
-- a small CI-only helper script when the behavior is truly CI glue and not a
+- a small CI-only helper script when the behavior is CI glue rather than a
   developer-facing entrypoint
 
-When a workflow does call a CI-only helper script directly, the script should
-follow the `scripts/workflow-*.sh` naming convention. That is the documented
-exception to the normal preference for repo entrypoints such as tasks and local
-actions, and `scripts/actionlint.sh` checks for it.
+When a workflow calls a CI-only helper script directly, the script should use
+the `scripts/workflow-*.sh` naming convention. This is the documented exception
+to the normal preference for repo entrypoints such as tasks and local actions.
 
-Keep the supported behavior visible in the repo instead of hiding it in
-workflow YAML.
+Most non-trivial shell logic should live under [`scripts/`](../scripts/), while
+logic specific to GitHub Actions or packaging may live under
+[`.github/`](../.github/). Keeping it out of workflow YAML makes the real
+behavior easier to inspect, check, test, reuse, and review.
 
-This helps with review and maintenance. If CI runs behavior defined in this repo, a
-contributor should usually be able to find how it is launched in the tree and rerun it
-or inspect it directly.
+For task-specific guidance, including when workflows should call
+`./scripts/run_task.sh`, see [Tasks](./tasks.md).
 
 ### Pin runner labels
 
 GitHub-hosted runner labels should use explicit versions such as `ubuntu-24.04`
 or `macos-26`, not floating labels such as `ubuntu-latest` or `macos-latest`.
 
-Floating labels can change underneath the default branch without any matching
-repo change. Explicit labels make runner image upgrades a reviewed repo change.
+Floating labels can change underneath the default branch without a matching repo
+change. Explicit labels make runner image upgrades a reviewed repo change.
 
 ### Pin third-party actions
 
@@ -85,69 +85,125 @@ This repo treats actions in two groups:
 - third-party actions outside this repository
 
 Local actions under `./.github/actions/` are part of this repo, so there is no
-external version to pin.
-
-For third-party actions, the default rule is to pin a full commit SHA. This
+external version to pin. Other actions should use a full commit SHA. This
 reduces supply-chain risk and makes upgrades explicit.
 
 ### Only `actions/*` may use major tags
 
-This repo currently allows `actions/*` to use floating major version tags
-instead of full SHAs.
+This repo allows `actions/*` to use floating major version tags instead of full
+SHAs. This is a repo convention, not a universal rule.
 
-This is a repo convention, not a universal rule.
+Pinning every action by SHA would make every upgrade more explicit, but it would
+also add churn for the one provider the repo already has to trust to run GitHub
+Actions. The current rule is:
 
-The trade-off is that pinning every action by SHA would make every upgrade more
-explicit, but it would also add more churn for the one provider this repo
-already has to trust as part of running GitHub Actions at all.
+- `actions/*` may use major tags such as `@v5` or `@v6`
+- every other third-party action must use a full commit SHA
 
-So the current repo rule is:
+The repo may still pin an `actions/*` action by SHA in a specific case. The
+important rule is that actions outside `actions/*` do not float.
 
-- `actions/*` may use major tags such as `@v5` or `@v6`
-- all other third-party actions should be pinned to full commit SHAs
+### Some CI-only setup still belongs in workflows
+
+CI sometimes needs setup that a local command does not. That is fine when it
+adapts the execution environment rather than changes the repo operation being
+run.
 
-The repo may still choose to pin an `actions/*` action by SHA in a specific
-case. The repo rule is that everything outside `actions/*` should not float.
+For example, workflows may need runner choice, container setup, artifact
+uploads, secrets, or a `workflow_dispatch` input. This is normal CI setup, not
+a reason to move the underlying operation into YAML.
 
-### How these rules are enforced today
+### Checks enforce common mistakes
 
-Current automated checks include:
+[`scripts/actionlint.sh`](../scripts/actionlint.sh) checks several common CI
+mistakes:
 
 - workflows should usually invoke stable tasks or local actions instead of
   calling most `scripts/*` paths directly
 - direct workflow script calls are allowed only for CI-only helpers following
   the `scripts/workflow-*.sh` naming convention
 - workflow task invocations should not change task behavior by passing extra
   option flags after `--`
+- third-party actions outside `actions/*` must be pinned by full SHA
 - floating GitHub-hosted runner labels are forbidden
 
-Those checks live in [`scripts/actionlint.sh`](../scripts/actionlint.sh).
+These checks are practical guardrails, not a complete model of workflow
+behavior. Code review still decides whether a new action or exception is
+appropriate.
+
+## Examples
+
+### Good: a workflow runs a named task
+
+In [`.github/workflows/ci.yml`](../.github/workflows/ci.yml), the unit-test job
+runs:
+
+```bash
+./scripts/run_task.sh test-unit
+```
+
+A contributor can run the same operation locally with:
+
+```bash
+task test-unit
+```
+
+The task may call scripts, tools, or other tasks underneath, but the workflow
+is not hiding extra behavior.
+
+### Good: a workflow uses a local action
+
+In [`.github/workflows/ci.yml`](../.github/workflows/ci.yml), end-to-end jobs
+use the local `run-monitored-tmpnet-cmd` action. The action owns shared
+monitoring and artifact behavior, while the workflow selects the named task:
+
+```yaml
+- uses: ./.github/actions/run-monitored-tmpnet-cmd
+  with:
+    run: ./scripts/run_task.sh test-e2e-ci
+```
+
+This keeps shared GitHub Actions glue in one local action instead of duplicating
+it across jobs.
+
+### Avoid: workflow-only repo behavior
+
+Avoid defining the only real form of a repo operation through workflow commands,
+environment variables, or task configuration. For example:
+
+```yaml
+- run: ./scripts/run_task.sh test-e2e
+  env:
+    E2E_RUNTIME: kube
+```
 
-The action-pinning rule is checked by repo lint: `actions/*` may use major
-version tags, while other third-party actions should be pinned by full SHA.
-Code review still matters for deciding whether a newly introduced action is
-appropriate in the first place.
+That forces a contributor to reconstruct workflow state instead of rerunning a
+clear named task. In a case like this, prefer a dedicated task such as
+`test-e2e-kube-ci`. Workflow environment configuration is still appropriate when
+it is needed only to run that task in CI.
 
 ## Maintainer guidance
 
 When changing CI, work through these questions:
 
 1. what existing repo command, task, script, or action should this use?
 2. should that be a task, a local action, or a CI-only helper?
-3. does this change add an external action, and if so how should it be pinned?
-4. is the workflow mostly calling existing repo behavior, or is it starting to
-   define the only real way to invoke a given check?
+3. does this change add an external action, and if so is it pinned correctly?
+4. does the workflow use an explicit runner image?
+5. is the workflow calling existing repo behavior, or defining the only real
+   way to invoke a check?
 
 Useful review questions:
 
 - can an engineer find the real behavior without reading too much workflow
   glue?
-- if this workflow adds a third-party action outside `actions/*`, is it pinned
-  by full SHA?
-- does the workflow use an explicit runner image instead of a floating
-  `*-latest` label?
-- if a task is involved, is CI calling a stable named task rather than shaping
-  the behavior in the workflow?
+- can a contributor rerun the same named task locally when that is useful?
+- if a task has an argument, is that argument part of its normal local
+  interface rather than hidden CI-only configuration?
+- if the workflow calls a script directly, is it truly CI-only glue with the
+  `scripts/workflow-*.sh` naming convention?
+- if a workflow adds a third-party action outside `actions/*`, is it pinned by
+  full SHA?
 
 If the same CI rule keeps showing up in review comments, that is usually a sign
 that it should be documented here and possibly automated.