@bamr87/fleet-engines 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# `@bamr87/fleet-engines` — the fleet's engines, versioned once
+
+The pure logic behind every fleet console, published from the hub and consumed **by dependency**: GitFactory's Fleet Ops cockpit, Observe map and Harness tab run it in the browser; zer0-CMS's Fleet console runs it inside VS Code. One implementation, one rulebook, one set of tests.
+
+```bash
+npm install @bamr87/fleet-engines
+```
+
+```ts
+import { parseFleetManifest, extractFacts, auditWorkflow, harnessHealth } from '@bamr87/fleet-engines';
+```
+
+## What is in it
+
+| Module | What it does | Pure? |
+| --- | --- | --- |
+| `harness/lanes` | The `fleet/v1` vocabulary (`FleetLane`, `FleetManifest`), `parseFleetManifest` (tolerant, never throws), `laneForPath` | yes |
+| `harness/manifest-yaml` | `toFleetManifestYaml(lanes, meta)` — a manifest document from lanes, deterministic emitter | yes |
+| `fleet/parse`, `fleet/facts` | Reverse-import any repo's `.github/workflows/*.yml`: triggers, sinks, the AI runner (the hub's `claude-run` by reference, a vendored copy, `claude-code-action`, the bare CLI, the agentic engine), kill switches, guards, permissions, pins | yes |
+| `fleet/audit` | The rulebook: the fleet's conventions as data (`AUDIT_RULES`) and the checkers (`auditWorkflow`, `auditRepo`, `gradeFor`). Every rule is one entry — meta, applies, violations — so the published rulebook and the checks cannot drift | yes |
+| `fleet/metrics` | Run-level rollups per workflow and repo | yes |
+| `fleet/import` | The one orchestrator: fetches workflows + the manifest through a `GithubClient` you inject | I/O via the client only |
+| `harness/health` | The hub's harness scorecard and six trip wires, recomputed from committed signals | yes |
+| `harness/signals`, `harness/hubread`, `harness/hub-paths` | Live signals from a scan; the eight hub reads; the hub's paths and snapshot shape | I/O via the client only |
+| `github/types`, `github/telemetry` | The `GithubClient` contract (22 members) every console implements over its own fetch, `RepoRef`, `GithubError`; ETag-polled run telemetry | yes |
+
+Not in it, on purpose: a fetch client (each consumer brings its own: a browser client, an editor client over VS Code's fetch and SecretStorage, a fixture client for demos), and the blueprint → lanes direction, which belongs to GitFactory's compiler.
+
+## Where it came from
+
+Lifted verbatim from GitFactory (`bamr87/gitorio` `app/src/{fleet,harness,github}`) at the commit named in `VERSION`, with two seams cut so it stands alone; GitFactory switches to consuming this package next (its backlog item), and the copy there is retired, never edited. The tests came with the code: 230+ cases over 39 real-fleet workflow fixtures and the hub's own committed signal files.
+
+## Developing
+
+```bash
+cd templates/fleet-engines
+npm install --no-package-lock     # always-latest: floors, no lockfile
+npm test                          # vitest, node environment
+npm run typecheck
+npm run build                     # dist/ (ESM + d.ts); prepack runs it for publish
+```
+
+`fleet-engines-contract.yml` runs the tests, the typecheck and the build on every change here; `publish-kits.yml` builds, packs and publishes on a version bump. Bump `version` in `package.json` **and** `VERSION` together.

package/VERSION

@@ -0,0 +1,31 @@
+kit: fleet-engines
+version: 0.1.0
+source: "bamr87/bamr87 templates/fleet-engines/ (npm: @bamr87/fleet-engines)"
+seeded-by: "consumed BY DEPENDENCY — npm install @bamr87/fleet-engines (publish-kits.yml publishes on version change); not fanned out by tools/fanout.sh"
+files: package.json, src/**/*.ts (github/, fleet/, harness/), tests + fixtures beside the sources, README.md
+updated: 2026-09-08
+changelog: |
+  0.1.0 — the fleet's pure engines, lifted from GitFactory (bamr87/gitorio app/src at
+  1ea1836) so that GitFactory and zer0-CMS run ONE implementation: fleet/v1 manifest
+  parse + emit (harness/lanes, manifest-yaml), workflow facts (fleet/facts, parse),
+  the audit rulebook (fleet/audit — the fleet's conventions as data: OAuth-first,
+  kill switch on scheduled AI, loop guards, concurrency, least privilege, timeouts,
+  pinning, plan/apply, dormant crons, sticky markers, the runner by reference),
+  metrics, the harness scorecard + six trip wires (harness/health), live signals,
+  the hub reader, and the GithubClient contract (github/types) every console
+  implements over its own fetch. Two seams cut on the way out: the blueprint →
+  lanes direction (toFleetLanes) stays with GitFactory's compiler, and
+  toFleetManifestYaml now takes lanes + meta instead of a blueprint; HUB_PATHS /
+  HubSnapshot were lifted out of GitFactory's zustand store into harness/hub-paths.
+  Tests travel with the code (vitest, node environment): 230+ cases over 39
+  real-fleet workflow fixtures and the hub's committed signal files. The live
+  signals adapter (harness/signals) is exercised by GitFactory's demo scan and
+  keeps its test there.
+notes: |
+  Runtime dependency: exactly one, `yaml` (floor, per the always-latest policy).
+  Ships built JS + d.ts (dist/, produced by `prepack`; publish-kits.yml builds
+  before its `node --check` because the source is TypeScript). Consumers bundle it
+  (Vite, esbuild) and implement `GithubClient` themselves — a browser fetch
+  client, an editor fetch + SecretStorage client, a fixture client for demos.
+  Until GitFactory switches to this package (gitorio BL item) its app/src copy is
+  the same code at the SHA above; that copy is retired by the switch, never edited.

package/dist/fleet/audit.d.ts

@@ -0,0 +1,26 @@
+import type { AuditFinding, AuditRuleMeta, Grade, RepoAudit, WorkflowFacts } from './types.js';
+/** The rulebook, in check order — what the UI renders as the certification standard. */
+export declare const AUDIT_RULES: AuditRuleMeta[];
+/**
+ * Run every workflow-scoped rule against one workflow's facts. Repo-scoped rules
+ * (standard-trio, disabled-workflow) only run in {@link auditRepo}. PURE and total.
+ */
+export declare function auditWorkflow(f: WorkflowFacts): AuditFinding[];
+/**
+ * Certify one repo's whole workflow fleet: all workflow-scoped rules across every
+ * workflow, plus the repo-scoped rules. `opts.workflowStates` (path → Actions API
+ * state) feeds the disabled-workflow rule when the caller has polled live states.
+ *
+ * Scoring: 100 − 10·fails − 3·warns − 1·infos, clamped to 0–100. A rule lands in
+ * `passedRules` only when it applied to ≥1 workflow (or to the repo) and produced
+ * zero findings — a rule that never applied is neither passed nor failed.
+ */
+export declare function auditRepo(facts: WorkflowFacts[], opts?: {
+    workflowStates?: Record<string, string>;
+}): RepoAudit;
+/**
+ * Factorio-style certification grade. 'S' demands a spotless run (no fail, no warn,
+ * score ≥ 95 — infos alone can't block it); 'A' tolerates warns at ≥ 85 but no fail;
+ * below that only the score matters: 'B' ≥ 70, 'C' ≥ 50, else 'D'.
+ */
+export declare function gradeFor(score: number, findings: AuditFinding[]): Grade;

package/dist/fleet/audit.js

@@ -0,0 +1,467 @@
+// Alignment-audit rules engine — Fleet Ops' "certification" pass. Grades one repo's
+// reverse-engineered WorkflowFacts against the real bamr87 fleet conventions
+// (ground-truthed by survey): OAuth-first Claude auth, default-OFF vars.*_ENABLED
+// kill switches on scheduled AI, loop guards on event-triggered writers, near-universal
+// concurrency blocks, least-privilege permissions, plan/apply duality on mutating
+// crons, sticky-marker dedup on issue-filing crons, and the standard trio (a CI
+// workflow + the @claude mention handler + the markdown-oneline prose kit).
+//
+// Every rule is ONE entry in a single data-driven list (meta + applies + violations),
+// so the published rulebook (AUDIT_RULES) and the checkers cannot drift — there is no
+// parallel switch statement. `applies` is deliberately separate from the violation
+// check: a rule only counts as *passed* when it actually applied and stayed silent;
+// silence from an inapplicable rule is neither pass nor fail. Pure and total: no I/O,
+// no globals, no clock, never throws.
+function wfRule(meta, applies, violations) {
+    return { scope: 'workflow', meta, applies, violations };
+}
+function repoRule(meta, applies, violations) {
+    return { scope: 'repo', meta, applies, violations };
+}
+// ── shared predicates ─────────────────────────────────────────────────────────
+/** Events whose payloads a writer can retrigger — the feedback-loop surface. */
+const LOOP_EVENT_TRIGGERS = ['issue_comment', 'issues', 'pull_request', 'pull_request_target'];
+/** Sinks that can feed one of those events back. */
+const LOOP_WRITE_SINKS = ['comment', 'issue', 'label', 'pr', 'commit'];
+/** Triggers where parallel runs pile up or race without a concurrency group. */
+const PILE_UP_TRIGGERS = ['push', 'pull_request', 'schedule'];
+/** Sinks that mutate repo state — the plan/apply-duality surface. */
+const MUTATING_SINKS = ['commit', 'pr', 'issue', 'merge'];
+function hasTrigger(f, kinds) {
+    return f.triggers.some((t) => kinds.includes(t.kind));
+}
+/** Deduped trigger kinds of `f` that fall in `kinds`, for citing evidence. */
+function triggersIn(f, kinds) {
+    return Array.from(new Set(f.triggers.map((t) => t.kind).filter((k) => kinds.includes(k))));
+}
+/** The subset of `f.sinks` in `kinds` — intersection test and evidence in one. */
+function sinksIn(f, kinds) {
+    return f.sinks.filter((s) => kinds.includes(s));
+}
+/**
+ * Reusable-workflow refs (`…/x.yml@main`) may float on a branch by fleet convention —
+ * the hub's standard-ci.yml callers all track @main — so the pin rules exclude them.
+ */
+function isReusableWorkflowRef(a) {
+    return /\.ya?ml$/i.test(a.action);
+}
+/** A marketplace action `uses:` — excludes reusable-workflow refs (`…/*.yml`) and local composites. */
+function isMarketplaceAction(a) {
+    return !isReusableWorkflowRef(a) && a.pin !== 'local';
+}
+/**
+ * Whether a `pull_request`/`pull_request_target` trigger subscribes to a given activity.
+ * facts.ts surfaces the explicit `types:` in the trigger `detail`; a MISSING detail means
+ * the `types:` block was omitted, so GitHub's DEFAULT PR activity set — [opened, synchronize,
+ * reopened] — applies. So `synchronize`/`opened`/`reopened` count when the detail is absent
+ * (the default includes them), while non-default activities like `labeled` count only when
+ * an explicit `detail` names them.
+ */
+function prSubscribes(f, activity, inDefaultSet) {
+    return f.triggers.some((t) => {
+        if (t.kind !== 'pull_request' && t.kind !== 'pull_request_target')
+            return false;
+        if (t.detail === undefined)
+            return inDefaultSet; // no types: → GitHub default set
+        return t.detail.includes(activity);
+    });
+}
+/** A self-push (`commit` to the PR branch) re-emits `synchronize`, which is in the default set. */
+function subscribesSynchronize(f) {
+    return prSubscribes(f, 'synchronize', true);
+}
+/**
+ * The write sinks that can retrigger this workflow: a sink is loopy only when the event it
+ * emits is one the workflow already subscribes to. Emission map — comment→issue_comment;
+ * issue→issues; label→issues(labeled) for an issue label OR pull_request(labeled) for a PR
+ * label; pr→pull_request(opened); merge→nothing (terminal); commit→push (always) plus
+ * pull_request(synchronize) when the PR trigger subscribes to synchronize. A writer whose
+ * sinks emit nothing it listens for cannot feed itself and needs no guard.
+ */
+function selfRetriggerSinks(f) {
+    const subscribed = new Set(f.triggers.map((t) => t.kind));
+    const prFamily = subscribed.has('pull_request') || subscribed.has('pull_request_target');
+    const sync = subscribesSynchronize(f);
+    // `labeled` is NOT in the default PR set, so it only counts with an explicit `types:`.
+    const prLabeled = prFamily && prSubscribes(f, 'labeled', false);
+    const loops = (s) => {
+        switch (s) {
+            case 'comment':
+                return subscribed.has('issue_comment');
+            case 'issue':
+                return subscribed.has('issues');
+            case 'label':
+                // the `label` sink can be an issue label (→issues) or a PR label (→pull_request labeled)
+                return subscribed.has('issues') || prLabeled;
+            case 'pr':
+                return prFamily;
+            case 'commit':
+                return subscribed.has('push') || (prFamily && sync);
+            default:
+                return false; // merge (terminal), deploy, cross_repo_issue, dispatch — emit nothing we listen for
+        }
+    };
+    return f.sinks.filter(loops);
+}
+// ── the rulebook ──────────────────────────────────────────────────────────────
+const RULES = [
+    wfRule({
+        id: 'auth-oauth-first',
+        title: 'OAuth-first Claude auth',
+        severity: 'warn',
+        standard: 'AI workflows authenticate with CLAUDE_CODE_OAUTH_TOKEN first and keep ANTHROPIC_API_KEY only as the fallback.',
+    }, (f) => f.ai.present, (f) => f.ai.authMode === 'api-key-only'
+        ? [
+            {
+                message: 'uses ANTHROPIC_API_KEY only; fleet convention is OAuth-first (CLAUDE_CODE_OAUTH_TOKEN with API-key fallback)',
+                fix: 'Pass claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} first and keep anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} as the fallback.',
+            },
+        ]
+        : []),
+    wfRule({
+        id: 'kill-switch',
+        title: 'Kill switch on scheduled AI',
+        severity: 'fail',
+        standard: 'Scheduled AI lines gate on a default-OFF vars.*_ENABLED repo variable so they can be disarmed without a redeploy.',
+    }, (f) => f.ai.present && f.crons.length > 0, (f) => f.killSwitches.length === 0
+        ? [
+            {
+                message: `scheduled AI line with no vars.*_ENABLED kill switch — cannot be disarmed without a redeploy (crons: ${f.crons.join(', ')})`,
+                fix: "Gate the job with if: vars.<LINE>_ENABLED == 'true' (a default-OFF repo variable) so the schedule can be disarmed from repo settings.",
+            },
+        ]
+        : []),
+    wfRule({
+        id: 'loop-safety',
+        title: 'Loop guard on self-retriggering writers',
+        severity: 'fail',
+        standard: 'A workflow whose write sink can re-emit an event it subscribes to carries at least one loop guard; a writer that cannot retrigger itself (its sink emits nothing it listens for) needs none.',
+    }, (f) => hasTrigger(f, LOOP_EVENT_TRIGGERS) && sinksIn(f, LOOP_WRITE_SINKS).length > 0, (f) => {
+        const loopy = selfRetriggerSinks(f);
+        if (loopy.length === 0)
+            return [];
+        // A GENERAL guard (attempt limit, label opt-in, actor guard, rate limiter, gate job,
+        // singleton concurrency, sticky marker, …) breaks any loop. `synchronize-skip` is
+        // narrower: it neutralizes ONLY the commit→synchronize path, so it counts only when
+        // every loopy sink is `commit` — never for a label/comment/pr self-retrigger.
+        const generalGuards = f.guards.filter((g) => g !== 'synchronize-skip');
+        if (generalGuards.length > 0)
+            return [];
+        if (f.guards.includes('synchronize-skip') && loopy.every((s) => s === 'commit'))
+            return [];
+        return [
+            {
+                message: `event-triggered writer with no loop guard — writing ${loopy.join(', ')} re-emits an event its own trigger subscribes to (${triggersIn(f, LOOP_EVENT_TRIGGERS).join(', ')})`,
+                fix: 'Add a loop guard (attempt-limit counter, label opt-in, actor/bot guard, rate limiter, sticky marker, gate job, or singleton concurrency), or stop subscribing to the activity the sink emits (e.g. drop pull_request synchronize).',
+            },
+        ];
+    }),
+    wfRule({
+        id: 'concurrency',
+        title: 'Concurrency block',
+        severity: 'warn',
+        standard: 'Push, pull_request, and scheduled workflows declare a concurrency group so runs cannot pile up or race.',
+    }, (f) => !f.isReusable && hasTrigger(f, PILE_UP_TRIGGERS), (f) => f.concurrency.present
+        ? []
+        : [
+            {
+                message: `no concurrency block; parallel runs can pile up or race (triggers: ${triggersIn(f, PILE_UP_TRIGGERS).join(', ')})`,
+                fix: 'Add a top-level concurrency block, e.g. concurrency: { group: "<line>-${{ github.ref }}", cancel-in-progress: true }.',
+            },
+        ]),
+    wfRule({
+        id: 'permissions',
+        title: 'Least-privilege permissions',
+        severity: 'warn',
+        standard: 'Every non-reusable workflow declares an explicit permissions block instead of inheriting the repo default token grants.',
+    }, (f) => !f.isReusable, (f) => f.permissions.declared
+        ? []
+        : [
+            {
+                message: "no permissions block — the job runs with the repo's default token grants",
+                fix: 'Declare a permissions: block with the minimal scopes each job needs (start from contents: read).',
+            },
+        ]),
+    wfRule({
+        id: 'top-level-write',
+        title: 'Job-scoped write grants',
+        severity: 'info',
+        standard: 'Write scopes are escalated per job, never granted at the workflow top level.',
+    }, (f) => f.permissions.declared, (f) => f.permissions.topLevelWrite
+        ? [
+            {
+                message: `write scopes granted at the top level; prefer per-job escalation${f.permissions.writeScopes.length > 0
+                    ? ` (write scopes in file: ${f.permissions.writeScopes.join(', ')})`
+                    : ''}`,
+                fix: 'Move write scopes down to the jobs that need them and keep the top level read-only.',
+            },
+        ]
+        : []),
+    wfRule({
+        id: 'ai-timeout',
+        title: 'Timeout on AI jobs',
+        severity: 'warn',
+        standard: 'AI jobs declare timeout-minutes so a wedged agent cannot burn unbounded minutes.',
+    }, (f) => f.ai.present, (f) => f.timeoutMinutes === null
+        ? [
+            {
+                message: 'AI job without timeout-minutes — an unbounded cost risk',
+                fix: 'Set timeout-minutes on the AI job (e.g. timeout-minutes: 30).',
+            },
+        ]
+        : []),
+    wfRule({
+        id: 'pin-branch',
+        title: 'No branch-pinned actions',
+        severity: 'warn',
+        standard: 'Actions are pinned to a tag or SHA; only reusable fleet-hub workflow refs may float on a branch.',
+    }, (f) => f.actions.some((a) => !isReusableWorkflowRef(a)), (f) => f.actions
+        .filter((a) => !isReusableWorkflowRef(a) && a.pin === 'branch')
+        .map((a) => ({
+        message: `${a.action}@${a.ref ?? '?'} — action pinned to a moving branch`,
+        fix: `Pin ${a.action} to a release tag or commit SHA instead of @${a.ref ?? '?'}.`,
+    }))),
+    wfRule({
+        id: 'pin-unpinned',
+        title: 'No unpinned actions',
+        severity: 'warn',
+        standard: 'Every non-local uses: reference carries an explicit @ref pin.',
+    }, (f) => f.actions.some((a) => a.pin !== 'local'), (f) => f.actions
+        .filter((a) => a.pin === 'unpinned')
+        .map((a) => ({
+        message: `${a.action} has no @ref — it resolves to whatever the default branch holds`,
+        fix: `Add an explicit pin: ${a.action}@<tag-or-sha>.`,
+    }))),
+    repoRule({
+        id: 'pin-sha',
+        title: 'SHA-pin marketplace actions',
+        severity: 'info',
+        standard: 'In repos that pin marketplace actions to commit SHAs by convention (SHA-pins outnumber tag-pins), every marketplace action is SHA-pinned rather than left tag-pinned.',
+    }, ({ facts }) => {
+        let sha = 0;
+        let tag = 0;
+        for (const f of facts) {
+            for (const a of f.actions) {
+                if (!isMarketplaceAction(a))
+                    continue;
+                if (a.pin === 'sha')
+                    sha += 1;
+                else if (a.pin === 'tag')
+                    tag += 1;
+            }
+        }
+        return sha > tag;
+    }, ({ facts }) => {
+        const out = [];
+        for (const f of facts) {
+            for (const a of f.actions) {
+                if (!isMarketplaceAction(a) || a.pin !== 'tag')
+                    continue;
+                out.push({
+                    path: f.path,
+                    message: `${a.action}@${a.ref ?? '?'} is tag-pinned while this repo SHA-pins marketplace actions by convention`,
+                    fix: `Pin ${a.action} to a full commit SHA (${a.action}@<sha>) to match the repo's SHA-pinning convention.`,
+                });
+            }
+        }
+        return out;
+    }),
+    wfRule({
+        id: 'plan-apply',
+        title: 'Plan/apply duality on mutating crons',
+        severity: 'info',
+        standard: 'Mutating scheduled lines expose a plan-first (dry-run) apply input so a human can preview before the line writes.',
+    }, (f) => f.crons.length > 0 && sinksIn(f, MUTATING_SINKS).length > 0, (f) => f.planApply
+        ? []
+        : [
+            {
+                message: `mutating scheduled line without a plan-first apply input (dry-run duality) — writes ${sinksIn(f, MUTATING_SINKS).join(', ')}`,
+                fix: 'Add a workflow_dispatch apply input (default false) and keep the scheduled path plan-only.',
+            },
+        ]),
+    wfRule({
+        id: 'dormant-cron',
+        title: 'No dormant schedules',
+        severity: 'info',
+        standard: 'Commented-out cron lines are re-armed or removed rather than left as dead automation.',
+    }, (f) => f.crons.length > 0 || f.dormantCrons.length > 0, (f) => f.dormantCrons.length > 0
+        ? [
+            {
+                message: `schedule is commented out — dormant automation; re-arm or remove it (${f.dormantCrons.join(', ')})`,
+                fix: 'Uncomment the cron to re-arm the schedule, or delete the commented-out block.',
+            },
+        ]
+        : []),
+    wfRule({
+        id: 'sticky-marker',
+        title: 'Sticky-marker dedup on issue-filing crons',
+        severity: 'info',
+        standard: 'Scheduled issue-filers upsert against an HTML-comment marker instead of filing duplicates.',
+    }, (f) => f.crons.length > 0 && f.sinks.includes('issue'), (f) => f.guards.includes('sticky-marker')
+        ? []
+        : [
+            {
+                message: 'scheduled issue-filer without an HTML-comment dedup marker — risks duplicate issues',
+                fix: 'Embed an HTML-comment marker (e.g. <!-- fleet:rule-id -->) in the issue body and update the marked issue when it already exists.',
+            },
+        ]),
+    repoRule({
+        id: 'standard-trio',
+        title: 'Standard trio',
+        severity: 'warn',
+        standard: 'Every fleet repo carries a CI workflow, the @claude mention handler, and the markdown-oneline prose kit.',
+    }, () => true, ({ facts }) => {
+        const has = (...kinds) => facts.some((f) => kinds.includes(f.archetype));
+        const out = [];
+        if (!has('standard-ci-caller', 'ci-gate')) {
+            out.push({
+                path: null,
+                message: "standard trio: no CI workflow — nothing with archetype 'standard-ci-caller' or 'ci-gate'",
+                fix: 'Add the thin caller of the hub reusable standard-ci.yml (or a repo-local CI gate).',
+            });
+        }
+        if (!has('mention-handler')) {
+            out.push({
+                path: null,
+                message: "standard trio: no @claude mention handler — nothing with archetype 'mention-handler'",
+                fix: 'Seed the @claude mention workflow from the agent-context kit (standardize fan-out).',
+            });
+        }
+        if (!has('prose-kit')) {
+            out.push({
+                path: null,
+                message: "standard trio: no markdown-oneline prose kit — nothing with archetype 'prose-kit'",
+                fix: 'Seed the markdown-oneline prose workflow (fan-out kit: prose).',
+            });
+        }
+        return out;
+    }),
+    repoRule({
+        id: 'disabled-workflow',
+        title: 'No disabled workflows',
+        severity: 'info',
+        standard: 'Disabled workflows are dead weight — re-enabled or deleted, never left lingering.',
+    }, ({ workflowStates }) => workflowStates !== undefined && Object.keys(workflowStates).length > 0, ({ workflowStates }) => Object.entries(workflowStates ?? {})
+        .filter(([, state]) => typeof state === 'string' && state.startsWith('disabled'))
+        .map(([path, state]) => ({
+        path,
+        message: `workflow is disabled (${state}) — dead weight; remove it or re-enable it`,
+        fix: 'Re-enable the workflow from the Actions tab, or delete the file if the line is retired.',
+    }))),
+];
+// ── public API ────────────────────────────────────────────────────────────────
+/** The rulebook, in check order — what the UI renders as the certification standard. */
+export const AUDIT_RULES = RULES.map((r) => r.meta);
+/**
+ * Run every workflow-scoped rule against one workflow's facts. Repo-scoped rules
+ * (standard-trio, disabled-workflow) only run in {@link auditRepo}. PURE and total.
+ */
+export function auditWorkflow(f) {
+    const out = [];
+    for (const rule of RULES) {
+        if (rule.scope !== 'workflow' || !rule.applies(f))
+            continue;
+        for (const v of rule.violations(f)) {
+            out.push({
+                ruleId: rule.meta.id,
+                severity: rule.meta.severity,
+                path: f.path,
+                message: v.message,
+                fix: v.fix,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Certify one repo's whole workflow fleet: all workflow-scoped rules across every
+ * workflow, plus the repo-scoped rules. `opts.workflowStates` (path → Actions API
+ * state) feeds the disabled-workflow rule when the caller has polled live states.
+ *
+ * Scoring: 100 − 10·fails − 3·warns − 1·infos, clamped to 0–100. A rule lands in
+ * `passedRules` only when it applied to ≥1 workflow (or to the repo) and produced
+ * zero findings — a rule that never applied is neither passed nor failed.
+ */
+export function auditRepo(facts, opts) {
+    const ctx = { facts, workflowStates: opts?.workflowStates };
+    const findings = [];
+    const passedRules = [];
+    for (const rule of RULES) {
+        let applied = false;
+        const before = findings.length;
+        if (rule.scope === 'workflow') {
+            for (const f of facts) {
+                if (!rule.applies(f))
+                    continue;
+                applied = true;
+                for (const v of rule.violations(f)) {
+                    findings.push({
+                        ruleId: rule.meta.id,
+                        severity: rule.meta.severity,
+                        path: f.path,
+                        message: v.message,
+                        fix: v.fix,
+                    });
+                }
+            }
+        }
+        else if (rule.applies(ctx)) {
+            applied = true;
+            for (const v of rule.violations(ctx)) {
+                findings.push({
+                    ruleId: rule.meta.id,
+                    severity: rule.meta.severity,
+                    path: v.path,
+                    message: v.message,
+                    fix: v.fix,
+                });
+            }
+        }
+        if (applied && findings.length === before)
+            passedRules.push(rule.meta.id);
+    }
+    let fails = 0;
+    let warns = 0;
+    let infos = 0;
+    const byWorkflow = {};
+    for (const f of facts)
+        byWorkflow[f.path] = { fails: 0, warns: 0, infos: 0 };
+    for (const fd of findings) {
+        if (fd.severity === 'fail')
+            fails += 1;
+        else if (fd.severity === 'warn')
+            warns += 1;
+        else
+            infos += 1;
+        if (fd.path === null)
+            continue;
+        const cell = byWorkflow[fd.path] ?? { fails: 0, warns: 0, infos: 0 };
+        byWorkflow[fd.path] = cell;
+        if (fd.severity === 'fail')
+            cell.fails += 1;
+        else if (fd.severity === 'warn')
+            cell.warns += 1;
+        else
+            cell.infos += 1;
+    }
+    const score = Math.max(0, Math.min(100, 100 - 10 * fails - 3 * warns - infos));
+    return { score, grade: gradeFor(score, findings), findings, passedRules, byWorkflow };
+}
+/**
+ * Factorio-style certification grade. 'S' demands a spotless run (no fail, no warn,
+ * score ≥ 95 — infos alone can't block it); 'A' tolerates warns at ≥ 85 but no fail;
+ * below that only the score matters: 'B' ≥ 70, 'C' ≥ 50, else 'D'.
+ */
+export function gradeFor(score, findings) {
+    const hasFail = findings.some((f) => f.severity === 'fail');
+    const hasWarn = findings.some((f) => f.severity === 'warn');
+    if (!hasFail && !hasWarn && score >= 95)
+        return 'S';
+    if (!hasFail && score >= 85)
+        return 'A';
+    if (score >= 70)
+        return 'B';
+    if (score >= 50)
+        return 'C';
+    return 'D';
+}

package/dist/fleet/facts.d.ts

@@ -0,0 +1,25 @@
+import type { Archetype, DashType, WorkflowFacts } from './types.js';
+/**
+ * Exact port of the dash's ordered-substring workflow-type classifier: the first
+ * rule with any keyword contained in `"<name> <path>".toLowerCase()` wins;
+ * anything unmatched is 'other'. PURE.
+ */
+export declare function classifyDashType(name: string, path: string): DashType;
+/** The pre-archetype subset of WorkflowFacts that classifyArchetype reads. */
+export type ArchetypeSignals = Pick<WorkflowFacts, 'path' | 'name' | 'triggers' | 'crons' | 'isReusable' | 'reusableCalls' | 'jobCount' | 'hasMatrix' | 'matrixDynamic' | 'sinks' | 'crossRepoTargets' | 'ai' | 'guards' | 'generated'>;
+/**
+ * First-match archetype classification, ground-truthed against the real fleet.
+ * Name-flavored checks run against `"<name> <path>"` (not the raw text) because
+ * real workflows *mention* their siblings constantly — zer0's auto-merge denylists
+ * `release-please-config.json`, the UI audit describes the issue autopilot — and a
+ * raw-text match on those words would misfile them. Raw text is only consulted for
+ * signals that genuinely live in the body (the @claude mention, seeded-kit script
+ * names, dispatch plans). PURE.
+ */
+export declare function classifyArchetype(f: ArchetypeSignals, rawText: string): Archetype;
+/**
+ * Extract the full {@link WorkflowFacts} for one workflow file. PURE and total:
+ * never throws — unparseable YAML degrades to raw-text signals (jobCount 0, raw
+ * fallbacks for matrix/timeout/concurrency), exactly like parseWorkflow.
+ */
+export declare function extractFacts(path: string, yamlText: string): WorkflowFacts;