@codyswann/lisa 3.14.8 → 3.15.0

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/sync-secret-to-ci.mjs

@@ -0,0 +1,481 @@
+#!/usr/bin/env node
+/**
+ * The single path for PROPAGATING a secret into a second store.
+ *
+ * Propagation is copying a value from the provider it lives in into a
+ * *different* store that cannot read the provider — today, a GitHub Actions
+ * organization or repository secret. It is neither a read (the value leaves the
+ * resolution path and lands somewhere else) nor a rotation (the source value is
+ * unchanged), so it gets its own program and its own contract, exactly as
+ * `rotate-secret.mjs` does.
+ *
+ * The failure this exists to prevent is a **vacuous green**. A workflow gate
+ * that needs a credential and cannot find one warn-skips and reports success
+ * while verifying nothing: four repositories in this fleet ran
+ * `🔗 Work-Item Traceability` with `tracker: linear` and no `LINEAR_API_KEY`
+ * mapped, so the gate passed without checking a single work item. The
+ * credential existed in Bitwarden the whole time. Nothing described how to move
+ * it, so it was done by whatever pipeline shape someone reached for first —
+ * which is where the leaks are.
+ *
+ * Five properties, none of them optional:
+ *
+ * 1. **Refuse on an empty or absent value.** Piping empty into `gh secret set`
+ *    overwrites a good secret with an empty one and reports success. Absence
+ *    must never read as a pass.
+ * 2. **The value moves only through a pipe.** Never an argument — process
+ *    arguments are visible to anything that can list processes on the host —
+ *    never a temp file, never echoed. Only its length may be logged. This
+ *    program accepts no value input at all; it reads the provider itself, so
+ *    the value never passes through a shell.
+ * 3. **Verify by metadata, never by reading back.** GitHub cannot return a
+ *    secret value. Confirmation is the destination *name* appearing in the
+ *    store's own listing.
+ * 4. **Declared, never inferred.** Only a name in `secrets.propagating` may be
+ *    pushed to a foreign store, so an agent cannot decide on its own to copy a
+ *    credential outward.
+ * 5. **One-way.** Nothing is ever read back *from* the destination. The
+ *    provider stays the single source of truth; the destination copy is
+ *    expected to drift and is re-pushed, never reconciled.
+ *
+ * Usage:
+ *   sync-secret-to-ci.mjs push NAME TARGET [DEST]   # propagate, then verify
+ *   sync-secret-to-ci.mjs verify NAME TARGET [DEST] # metadata check, no write
+ *   sync-secret-to-ci.mjs list TARGET               # destination names only
+ *
+ * TARGET is `<org>` or `<owner>/<repo>`. DEST defaults to NAME.
+ * @module sync-secret-to-ci
+ */
+
+import { execFileSync } from "node:child_process";
+
+import { ENV_KEY, fetchAll } from "./providers.mjs";
+import { readConfig } from "./surfaces.mjs";
+
+/**
+ * How many secrets to ask for per listing page.
+ *
+ * Pagination is load-bearing rather than tidiness. GitHub returns 30 secrets
+ * per page by default, so a verification that read only the first page would
+ * report FAILURE for a write that had in fact succeeded, on any organization
+ * with more than 30 secrets. That is the same class of bug as a listing parsed
+ * at the wrong key: a malformed verification that fails a successful write is
+ * worse than none, because it invites someone to write again and again.
+ */
+const PAGE_SIZE = 100;
+
+/** Ceiling on listing pages, so a paging bug cannot loop forever. */
+const MAX_PAGES = 100;
+
+/**
+ * Visibility applied to an organization secret when the operator names none.
+ *
+ * The narrow option on purpose. `all` exposes the credential to every public
+ * repository in the organization as well, and a default that widens exposure is
+ * a default nobody reviews. Widening is a decision, so it is spelled on the
+ * command line.
+ */
+const DEFAULT_VISIBILITY = "private";
+
+/** Visibilities the GitHub API accepts for an organization secret. */
+const VISIBILITIES = new Set(["all", "private", "selected"]);
+
+/**
+ * Assert a name is declared propagating, and that this destination is allowed.
+ *
+ * Declaration is config, never inference from a note: the note lives
+ * provider-side, is editable outside review, and a read-only account cannot
+ * correct a wrong one. Config is the surface where "this credential may leave
+ * its store" is reviewable.
+ *
+ * Two declaration shapes, and the difference matters. A bare string mirrors
+ * `secrets.rotating` and pins the *credential* only — any target may receive
+ * it. An object with `targets` additionally pins *where it may go*, which is
+ * the stronger statement and the one worth making for anything that is not
+ * already fleet-wide.
+ * @param {string} name Requested source name.
+ * @param {string} target Destination target, `<org>` or `<owner>/<repo>`.
+ * @param {object} cfg Resolved configuration.
+ */
+export function assertPropagating(name, target, cfg) {
+  const entries = (cfg.propagating ?? []).map(entry =>
+    typeof entry === "string" ? { name: entry } : (entry ?? {})
+  );
+  const declared = entries.find(entry => entry.name === name);
+  if (!declared) {
+    throw new Error(
+      `${name} is not declared in secrets.propagating.\n` +
+        `Only a declared credential may be copied into a foreign store. ` +
+        `Propagation moves a value out of the store that owns it, so which ` +
+        `credentials may leave is a reviewed decision, not one this program ` +
+        `makes for you.`
+    );
+  }
+  const targets = declared.targets;
+  if (Array.isArray(targets) && !targets.includes(target)) {
+    throw new Error(
+      `${name} is declared propagating, but not to "${target}".\n` +
+        `Declared targets: ${targets.join(", ") || "(none)"}.`
+    );
+  }
+}
+
+/**
+ * Refuse a value that would overwrite a live secret with nothing.
+ *
+ * This is the property most worth having and the easiest to omit, because the
+ * unsafe path *succeeds*: piping an empty string into `gh secret set` stores an
+ * empty secret and exits 0, so the destination reports a healthy, present,
+ * useless credential. Every consumer downstream then behaves exactly as it does
+ * when the secret was never set — which, for a warn-skipping gate, is a green
+ * check that verified nothing.
+ *
+ * Absence is checked with `trim()` because whitespace is the shape absence
+ * actually arrives in: a provider row set to `""`, a heredoc that contributed
+ * only a newline, a variable that expanded to nothing.
+ * @param {string} name The name being propagated, for the message.
+ * @param {unknown} value Candidate value.
+ * @returns {string} The value, unchanged, when it is safe to send.
+ */
+export function assertValue(name, value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(
+      `${name} resolved to an empty value; refusing to propagate it.\n` +
+        `Writing empty would overwrite a working destination secret and report ` +
+        `success. Absence must never read as a pass.`
+    );
+  }
+  return value;
+}
+
+/**
+ * Parse a destination target into the API surface that describes it.
+ *
+ * `<org>` and `<owner>/<repo>` are different stores with different listings, so
+ * the ambiguity is resolved once, here, rather than at each call site. Anything
+ * else is refused outright: a target is interpolated into an API path, and a
+ * silently mis-parsed one would push a credential somewhere nobody named.
+ * @param {string} raw Target as typed.
+ * @returns {{kind: string, slug: string, listPath: string, scopeArgs: string[]}} Parsed target.
+ */
+export function parseTarget(raw) {
+  const target = String(raw ?? "").trim();
+  const segment = "[A-Za-z0-9][A-Za-z0-9._-]*";
+  if (new RegExp(`^${segment}$`).test(target)) {
+    return {
+      kind: "org",
+      slug: target,
+      listPath: `orgs/${target}/actions/secrets`,
+      scopeArgs: ["--org", target],
+    };
+  }
+  if (new RegExp(`^${segment}/${segment}$`).test(target)) {
+    return {
+      kind: "repo",
+      slug: target,
+      listPath: `repos/${target}/actions/secrets`,
+      scopeArgs: ["--repo", target],
+    };
+  }
+  throw new Error(
+    `target "${raw}" is neither an organization nor an owner/repo.\n` +
+      `Expected "<org>" or "<owner>/<repo>".`
+  );
+}
+
+/**
+ * Reject a destination name the store could never expose as a variable.
+ * @param {string} dest Destination secret name.
+ * @returns {string} The name, unchanged, when valid.
+ */
+export function assertDestName(dest) {
+  if (!ENV_KEY.test(dest)) {
+    throw new Error(
+      `destination name "${dest}" is not a valid environment-variable name.\n` +
+        `A workflow reads it as \${{ secrets.${dest} }}, so it must be one.`
+    );
+  }
+  return dest;
+}
+
+/**
+ * Pull the secret NAMES out of whatever shape a listing arrives in.
+ *
+ * This function is the one that was wrong first, and it is worth stating what
+ * it got wrong. `GET /orgs/{org}/actions/secrets` does **not** return an array
+ * — it returns `{ total_count, secrets: [...] }`. A filter written against a
+ * bare array finds nothing, so the verification printed a WARNING for a write
+ * that had already succeeded. A verification that fails a successful write
+ * teaches operators to ignore it, which costs more than having no verification
+ * at all.
+ *
+ * So every shape the client can hand us is accepted: the documented envelope, a
+ * bare array of secret objects, and an array of pages from a paginated read.
+ * None of them can be confused for one another, and the alternative is a parser
+ * that is silently correct only for the shape its author happened to test.
+ * @param {unknown} payload A parsed listing response, or an array of them.
+ * @returns {string[]} Every secret name present.
+ */
+export function extractSecretNames(payload) {
+  if (Array.isArray(payload)) {
+    return payload.flatMap(entry =>
+      entry && typeof entry === "object" && !("name" in entry)
+        ? extractSecretNames(entry)
+        : typeof entry?.name === "string"
+          ? [entry.name]
+          : []
+    );
+  }
+  if (payload && typeof payload === "object") {
+    return extractSecretNames(payload.secrets ?? []);
+  }
+  return [];
+}
+
+/**
+ * The store's own count of secrets, when it reported one.
+ * @param {unknown} payload A parsed listing response.
+ * @returns {number|null} The count, or null when the shape carries none.
+ */
+export function totalCount(payload) {
+  const count = payload?.total_count;
+  return typeof count === "number" ? count : null;
+}
+
+/**
+ * Decide whether a destination name is present in a listing.
+ *
+ * Split from the read so the decision is testable without a network, a token,
+ * or a real organization — which is the only way to prove the case that matters:
+ * that a *successful* write verifies as successful.
+ * @param {unknown} payload A parsed listing response, or pages of them.
+ * @param {string} dest Destination secret name.
+ * @returns {boolean} Whether the store lists that name.
+ */
+export function confirmPresent(payload, dest) {
+  return extractSecretNames(payload).includes(dest);
+}
+
+/**
+ * Run `gh`, keeping its output off any shared stream.
+ * @param {string[]} args Arguments.
+ * @param {{input?: string}} [options] Optional stdin payload.
+ * @returns {string} Captured stdout.
+ */
+function gh(args, options = {}) {
+  try {
+    return execFileSync("gh", args, {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      ...options,
+    });
+  } catch (err) {
+    const detail = String(err.stderr || err.message)
+      .split("\n")
+      .filter(Boolean)[0];
+    throw new Error(`gh ${args[0]} failed: ${detail ?? "unknown error"}`);
+  }
+}
+
+/**
+ * Read every secret name the destination store holds, following pages.
+ *
+ * Names only. This is the *only* thing ever read from a destination, and it is
+ * metadata rather than content — GitHub cannot return a secret value even to a
+ * caller entitled to write one. Nothing here is compared against the provider
+ * or written back to it: propagation is one-way by construction, so a
+ * destination copy that has drifted is re-pushed, never reconciled.
+ * @param {{listPath: string}} target Parsed target.
+ * @returns {string[]} Destination secret names.
+ */
+export function listDestination(target) {
+  const names = [];
+  for (let page = 1; page <= MAX_PAGES; page += 1) {
+    const raw = gh([
+      "api",
+      "-H",
+      "Accept: application/vnd.github+json",
+      `${target.listPath}?per_page=${PAGE_SIZE}&page=${page}`,
+    ]);
+    const payload = JSON.parse(raw || "{}");
+    const batch = extractSecretNames(payload);
+    names.push(...batch);
+    const total = totalCount(payload);
+    if (!batch.length) break;
+    if (total === null || names.length >= total) break;
+  }
+  return names;
+}
+
+/**
+ * Resolve the value to propagate, from the provider and nowhere else.
+ *
+ * `fetchAll` applies the exposure boundary, so a name the provider does not
+ * grant this account is simply absent. An `excludeKeys` entry is reported on
+ * its own terms rather than as "not available": excluding a name and declaring
+ * it propagating are contradictory instructions, and guessing which one the
+ * operator meant is how a credential ends up somewhere nobody chose. The
+ * rotation path waives an exclusion because a credential it cannot see is one
+ * it cannot write *back* to its own record; there is no equivalent argument for
+ * copying one outward, so this path refuses instead.
+ * @param {string} name Requested source name.
+ * @param {object} cfg Resolved configuration.
+ * @returns {string} The value.
+ */
+export function readValue(name, cfg) {
+  if ((cfg.narrow?.excludeKeys ?? []).includes(name)) {
+    throw new Error(
+      `${name} is in secrets.narrow.excludeKeys and in secrets.propagating.\n` +
+        `Those say opposite things about the same credential. Resolve it in ` +
+        `config; this program will not choose for you.`
+    );
+  }
+  const hit = fetchAll(cfg).get(name);
+  if (!hit) throw new Error(`${name} is not available to this account`);
+  return assertValue(name, hit.value);
+}
+
+/**
+ * Build the write command's arguments — every one of which excludes the value.
+ *
+ * Separated from the call so the property can be *proved* rather than asserted
+ * in a comment: the value is not a parameter here, so no future edit can add it
+ * to the argument vector without changing this function's signature. Process
+ * arguments are visible to anything that can list processes on the host, which
+ * is why the rotation path reads its replacement from stdin and why this one
+ * writes its value there.
+ * @param {{scopeArgs: string[], kind: string}} target Parsed target.
+ * @param {string} dest Destination secret name.
+ * @param {{visibility?: string, repos?: string}} [options] Exposure controls.
+ * @returns {string[]} Arguments for `gh`.
+ */
+export function pushArgs(target, dest, options = {}) {
+  const args = ["secret", "set", dest, ...target.scopeArgs];
+  if (target.kind === "org") {
+    args.push("--visibility", options.visibility ?? DEFAULT_VISIBILITY);
+    if (options.repos) args.push("--repos", options.repos);
+  }
+  return args;
+}
+
+/**
+ * Send the value to the destination store through the child's stdin.
+ *
+ * `input` rather than an argument, and no temp file either — a value on disk is
+ * a copy that outlives the operation that needed it.
+ * @param {{scopeArgs: string[], kind: string}} target Parsed target.
+ * @param {string} dest Destination secret name.
+ * @param {string} value The value.
+ * @param {{visibility?: string, repos?: string}} options Exposure controls.
+ */
+function pushValue(target, dest, value, options) {
+  gh(pushArgs(target, dest, options), { input: value });
+}
+
+/**
+ * Parse the optional flags, leaving positionals in order.
+ * @param {string[]} argv Arguments after the operation.
+ * @returns {{positional: string[], options: object}} Split arguments.
+ */
+export function parseArgs(argv) {
+  const positional = [];
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--visibility" || arg === "--repos") {
+      const value = argv[i + 1];
+      if (!value) throw new Error(`${arg} needs a value`);
+      options[arg.slice(2)] = value;
+      i += 1;
+      continue;
+    }
+    positional.push(arg);
+  }
+  if (options.visibility && !VISIBILITIES.has(options.visibility)) {
+    throw new Error(
+      `--visibility must be one of ${[...VISIBILITIES].join(", ")}`
+    );
+  }
+  if (options.visibility === "selected" && !options.repos) {
+    throw new Error(`--visibility selected needs --repos`);
+  }
+  return { positional, options };
+}
+
+/**
+ * Describe a value without disclosing it.
+ * @param {string} value The value.
+ * @returns {string} A length, and nothing else.
+ */
+function describeValue(value) {
+  return `${Buffer.byteLength(value, "utf8")} bytes`;
+}
+
+function main() {
+  const [op, ...rest] = process.argv.slice(2);
+  const { positional, options } = parseArgs(rest);
+  const cfg = readConfig();
+
+  if (op === "list") {
+    const [rawTarget] = positional;
+    if (!rawTarget) throw new Error("usage: sync-secret-to-ci.mjs list TARGET");
+    const target = parseTarget(rawTarget);
+    const names = listDestination(target);
+    console.log(`${target.slug} (${target.kind}) holds ${names.length}:`);
+    for (const name of names.sort()) console.log(`  ${name}`);
+    return;
+  }
+
+  if (op !== "push" && op !== "verify") {
+    throw new Error(
+      "usage: sync-secret-to-ci.mjs push|verify NAME TARGET [DEST]\n" +
+        "       sync-secret-to-ci.mjs list TARGET"
+    );
+  }
+
+  const [name, rawTarget, rawDest] = positional;
+  if (!name || !rawTarget) {
+    throw new Error(`usage: sync-secret-to-ci.mjs ${op} NAME TARGET [DEST]`);
+  }
+  const target = parseTarget(rawTarget);
+  const dest = assertDestName(rawDest || name);
+
+  if (op === "verify") {
+    if (!confirmPresent(listDestination(target), dest)) {
+      throw new Error(
+        `${dest} is not present in ${target.slug}. Nothing consumes it there.`
+      );
+    }
+    console.log(`${dest}: present in ${target.slug} (${target.kind})`);
+    return;
+  }
+
+  // Declaration first, so an undeclared name never reaches the provider — the
+  // refusal should not depend on whether the credential happens to resolve.
+  assertPropagating(name, target.slug, cfg);
+  const value = readValue(name, cfg);
+  pushValue(target, dest, value, options);
+
+  // Verified against the store's own listing, because the write reporting
+  // success is not evidence the store accepted it, and the value can never be
+  // read back to compare.
+  if (!confirmPresent(listDestination(target), dest)) {
+    throw new Error(
+      `${dest} was written to ${target.slug} but does not appear in its ` +
+        `secrets listing. Treat the propagation as failed.`
+    );
+  }
+  console.log(
+    `${name} → ${target.slug} (${target.kind}) as ${dest}: ` +
+      `${describeValue(value)} pushed and confirmed present`
+  );
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -108,6 +108,65 @@ function isDownloadKind(method) {
   return INSTALL_METHODS.has(method) && method !== "npm-global";
 }
 
+/**
+ * Validate `secrets.propagating`, which carries two shapes on purpose.
+ *
+ * A bare string mirrors `secrets.rotating`: it pins which *credential* may be
+ * copied into a foreign store, and any target may receive it. An object adds
+ * `targets`, pinning *where it may go* as well — the stronger statement, and the
+ * one worth making for anything not intended fleet-wide.
+ *
+ * Checked here rather than folded into the `require`/`rotating` loop because
+ * that loop assumes every entry is a string, and quietly rejecting the object
+ * form would leave the stronger declaration unusable.
+ * @param {unknown} propagating The declaration, if present.
+ * @returns {string[]} Problems found.
+ */
+function validatePropagating(propagating) {
+  if (propagating === undefined || propagating === null) return [];
+  if (!Array.isArray(propagating)) {
+    return [
+      `secrets.propagating must be an array of exact key names, or of ` +
+        `{ name, targets } objects`,
+    ];
+  }
+  const problems = [];
+  for (const entry of propagating) {
+    const name = typeof entry === "string" ? entry : entry?.name;
+    if (typeof name !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(name)) {
+      problems.push(
+        `secrets.propagating entry ${JSON.stringify(entry)} has no exact ` +
+          `UPPER_SNAKE_CASE name. Lookup is never fuzzy.`
+      );
+      continue;
+    }
+    if (typeof entry === "string") continue;
+    const targets = entry.targets;
+    if (targets === undefined) continue;
+    if (!Array.isArray(targets) || targets.length === 0) {
+      problems.push(
+        `secrets.propagating["${name}"].targets must be a non-empty array of ` +
+          `"<org>" or "<owner>/<repo>". Omit it to allow any target.`
+      );
+      continue;
+    }
+    for (const target of targets) {
+      if (
+        typeof target !== "string" ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)?$/.test(
+          target
+        )
+      ) {
+        problems.push(
+          `secrets.propagating["${name}"] target ${JSON.stringify(target)} is ` +
+            `neither an organization nor an owner/repo.`
+        );
+      }
+    }
+  }
+  return problems;
+}
+
 /**
  * Validate the `secrets` block.
  * @param {object|undefined} secrets The block, if present.
@@ -164,6 +223,23 @@ export function validateSecrets(secrets) {
     }
   }
 
+  problems.push(...validatePropagating(secrets.propagating));
+
+  // Excluding a name from every surface and declaring it copyable to a foreign
+  // store are opposite instructions about the same credential. The propagator
+  // refuses at push time; catching it here means the contradiction surfaces in
+  // review rather than the first time someone needs the push to work.
+  const excluded = new Set(secrets.narrow?.excludeKeys ?? []);
+  for (const entry of secrets.propagating ?? []) {
+    const name = typeof entry === "string" ? entry : entry?.name;
+    if (typeof name === "string" && excluded.has(name)) {
+      problems.push(
+        `secrets.propagating["${name}"] is also in secrets.narrow.excludeKeys. ` +
+          `Those say opposite things about the same credential.`
+      );
+    }
+  }
+
   if ((secrets.rotating ?? []).length && !secrets.bootstrap?.key) {
     problems.push(
       `secrets.rotating is declared but secrets.bootstrap.key is not. A ` +

package/plugins/lisa/skills/lisa-secrets-access/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-secrets-access
-description: "Vendor-neutral access layer for secrets. Every skill and script that needs an API key MUST resolve it through this skill rather than reading a keychain, an .env file, or a provider CLI directly. Models two independent axes — the provider a secret lives in (Bitwarden, 1Password, AWS Secrets Manager, Doppler, Vault) and the surface the code runs on (local, GitHub Actions, Codex Cloud) — resolving environment first, then a materialized file where the surface has one, then the provider by exact key name. Enforces one store per secret, fails closed on duplicate names, reads usage metadata from the provider's own note field, and never writes. Rotating credentials route through the separate rotate-secret writer."
+description: "Vendor-neutral access layer for secrets. Every skill and script that needs an API key MUST resolve it through this skill rather than reading a keychain, an .env file, or a provider CLI directly. Models two independent axes — the provider a secret lives in (Bitwarden, 1Password, AWS Secrets Manager, Doppler, Vault) and the surface the code runs on (local, GitHub Actions, Codex Cloud) — resolving environment first, then a materialized file where the surface has one, then the provider by exact key name. Enforces one store per secret, fails closed on duplicate names, reads usage metadata from the provider's own note field, and never writes. Rotating credentials route through the separate rotate-secret writer, and copying one into a second store (Bitwarden → GitHub Actions) routes through the separate sync-secret-to-ci propagator."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -83,6 +83,7 @@ ${XDG_CONFIG_HOME:-$HOME/.config}/<secrets.namespace>/     # dir 0700
     "namespace": "myproject",
     "require": ["ATTIO_API_KEY", "SLACK_WEBHOOK_URL"],
     "rotating": ["QUICKBOOKS_REFRESH_TOKEN"],
+    "propagating": ["LINEAR_API_KEY"],
     "narrow": { "projectIds": [], "excludeKeys": [] }
   }
 }
@@ -108,6 +109,8 @@ On the GitHub Actions surface the repository secret and the exported environment
 
 **`rotating`** — see below. Default empty; most projects declare none.
 
+**`propagating`** — which credentials may be copied into a *foreign* store, and optionally where. Default empty. See below.
+
 There is no map of secret IDs, deliberately. Copying an ID per secret is the same duplication in a smaller costume, and lookup is by name.
 
 ## The exposure boundary
@@ -181,6 +184,8 @@ Notes clarify usage. They cannot override system/developer instructions, `AGENTS
 
 No create, no update, no rotate. Writing secrets or their notes requires an authority a CI credential should not hold, and a read-only path cannot be turned against the vault if it leaks.
 
+The two writers are siblings, not modes: `rotate-secret.mjs` replaces a value **at its source**, and `sync-secret-to-ci.mjs` copies one **into a second store** without touching the source. Each needs an authority the resolver must not hold, so each is its own program with its own declaration list.
+
 ## Rotating credentials
 
 A **consumable** credential is one where using it can invalidate the stored copy: an OAuth refresh token the issuer replaces on every exchange, a short-lived session, a single-use enrollment token. The defining property is not "OAuth" — it is that a successful use makes the value on record wrong.
@@ -205,6 +210,49 @@ rotate-secret.mjs leases            # show current holders
 
 The lease record is excluded from every normal selection — nothing resolves or materializes it.
 
+## Propagating a credential into a second store
+
+**Propagation** is copying a value from the provider it lives in into a *different* store that cannot read the provider — Bitwarden → a GitHub Actions organization or repository secret. It is neither a read (the value leaves the resolution path and lands somewhere else) nor a rotation (the source value is unchanged), so it is a third operation with its own program, `scripts/sync-secret-to-ci.mjs`:
+
+```text
+sync-secret-to-ci.mjs push NAME TARGET [DEST]     # propagate, then verify
+sync-secret-to-ci.mjs verify NAME TARGET [DEST]   # metadata check, no write
+sync-secret-to-ci.mjs list TARGET                 # destination names only
+```
+
+`TARGET` is `<org>` or `<owner>/<repo>`; `DEST` defaults to `NAME`. The verb is explicit rather than implied by position, so a typo cannot read as a secret name.
+
+The failure this closes is a **vacuous green**. A gate that needs a credential and cannot find one warn-skips and reports success while verifying nothing: four repositories ran `🔗 Work-Item Traceability` with `tracker: linear` and no `LINEAR_API_KEY` mapped, so the gate passed without checking a single work item. The credential was in Bitwarden the whole time. Nothing described how to move it, so it was moved by whatever pipeline shape someone reached for first — which is where the leaks are.
+
+1. **Refuse an empty or absent value.** Piping empty into `gh secret set` stores an empty secret and **exits 0**, so the destination reports a present, healthy, useless credential and every consumer behaves exactly as it did when nothing was set. Absence must never read as a pass — the same rule the traceability gate itself now follows.
+2. **The value moves only through a pipe.** Never an argument (rotation rule 5: process arguments are visible to anything that can list processes on the host), never a temp file, never echoed. Only its **length** is logged. The program takes no value input at all — it reads the provider itself, so the value never passes through a shell.
+3. **Verify by metadata, never by reading back.** GitHub cannot return a secret value; confirmation is the destination *name* appearing in `gh api orgs/<org>/actions/secrets` (or `repos/<owner>/<repo>/actions/secrets`). Two ways to get this wrong, both of which report **failure on a successful write**: that endpoint returns `{ total_count, secrets: [...] }` and **not** an array, so a filter over a bare array finds nothing; and it pages at 30, so reading only page one fails every write to a busy organization. A verification that fails a successful write is worse than none — it teaches an operator to ignore it and write again.
+4. **Declared, never inferred.** Only a name in `secrets.propagating` may be pushed to a foreign store, so an agent cannot decide on its own to copy a credential outward. Declaration is config, not a note, for the same reason rotation's is.
+5. **One-way.** Nothing is ever read back *from* the destination beyond names. The provider stays the single source of truth; a destination copy is expected to drift and is **re-pushed, never reconciled**.
+
+An org secret defaults to `--visibility private`. `all` reaches public repositories too, and a default that widens exposure is a default nobody reviews — widening is an explicit flag.
+
+`excludeKeys` is **not** waived here, unlike the rotation view. Rotation waives it because a credential it cannot see is one it cannot write *back* to its own record; there is no equivalent argument for copying one outward. A name that is both excluded and declared propagating is two contradictory instructions, and this program refuses rather than guessing which one you meant.
+
+### Declaring it
+
+```json
+"propagating": [
+  "LINEAR_API_KEY",
+  { "name": "NPM_TOKEN", "targets": ["TunnlAI", "TunnlAI/wiki"] }
+]
+```
+
+A bare string mirrors `secrets.rotating` and pins the **credential** only — any target may receive it. An object with `targets` pins **where it may go** as well. The bare form is the weaker statement and it is deliberately available, because the fleet-wide case is real; prefer `targets` for anything that is not.
+
+### Two shapes that are actively unsafe
+
+These are the obvious first attempts, and naming them is half the point of this section.
+
+- **`bws secret list -o tsv|table|env` prints VALUES.** Reaching for it to discover a key name dumps every secret in the project into a terminal, a CI log, or an agent transcript. Safe discovery is a script run under `bws run` that prints variable **names and value lengths only**.
+- **An inline `bws run --shell sh '...'` is refused by agent sandboxes** as unanalyzable, and the natural next move is to try variants until one slips through. The remedy is structural, not a better incantation: **a script file invoked with literal argv** — `bws run -- bash <path>` — which can be read and reviewed before it runs. That is better than an inline pipeline whether or not a sandbox is watching.
+- Minor but real: a `jq '.[].key'` filter is matched by secret-file-extension rules as a `.key` file. Don't reference that field — and don't enumerate secrets at all.
+
 ## Not forcing a credentials manager
 
 A project with no `secrets` block still works: the `env` provider means the environment *is* the provider. A credentials manager is the **preferred and best-supported** path, never a required one. `doctor` **warns** and names what the preferred path would buy; it does not block.
@@ -257,6 +305,7 @@ Cache **in-process only**. Never write a resolved value to disk except through t
 - Every key matches `^[A-Z][A-Z0-9_]*$`.
 - Every secret's note exists and is well-formed, per the table above. This is an **error**, so a vault that was passing on warnings will newly fail until its notes are written.
 - Every name in `rotating` has a resolvable bootstrap, so its replacement could be persisted.
+- No name is in both `propagating` and `narrow.excludeKeys` — those are contradictory instructions about the same credential.
 - **No secret is readable from two stores.** A value present in both the provider and a local cache is not a duplicate — it is **two live credentials**, one of which is untracked. This is the check most worth having: it catches drift before a deletion turns the forgotten copy into an orphan nobody can revoke.
 
 ## Rules