@event4u/agent-config 14.15.0 → 14.17.0

package/src/scripts/release_mix_taxonomy.json

@@ -0,0 +1,172 @@
+{
+  "taxonomy_version": "1.0.0",
+  "updated": "2026-09-04",
+  "contract": "docs/decisions/ADR-253-per-pr-user-artifact-gate-declined.md",
+  "reader": "src/scripts/measure_release_mix.ts",
+  "note": [
+    "Path -> category mapping for the release governance-vs-product measurement.",
+    "Versioned so a later reading is comparable to an earlier one: a reading records",
+    "the taxonomy_version it was computed under, and a bump means prior readings are",
+    "recomputed rather than silently compared across two different rulers.",
+    "Matching is LONGEST-PREFIX-WINS over the repository-relative path. A path that",
+    "matches no rule is reported as `unclassified` -- a first-class state, never a",
+    "silent default. `unclassified` alone does not make a commit `mixed`.",
+    "The `consumer` label names a SHIPPED SURFACE, not delivered consumer value.",
+    "openai/codex-default asked for the label `shipped-product` on exactly that",
+    "ground and anthropic/claude-sonnet-4-5 preferred keeping `consumer` for",
+    "consistency with the roadmap's own wording; the roadmap's wording is kept and",
+    "the objection is recorded here rather than dropped."
+  ],
+  "categories": {
+    "consumer": "Shipped surface an installing consumer receives or invokes: skills, rules, commands, guidelines, packs, the agent-config CLI runtime, and user-facing documentation.",
+    "governance": "This repository's own steering layer: roadmaps, evidence ledgers, verdicts, decision records, archive and promotion records, and governance-only contracts.",
+    "maintenance": "Repository infrastructure: CI gates, tests, build and release automation, packaging, dependencies, tooling configuration.",
+    "unclassified": "No rule matches, or the path is genuinely shared between categories and is left visible rather than assigned."
+  },
+  "excluded_generated": [
+    "dist/",
+    ".augment/",
+    ".claude/",
+    ".cursor/",
+    ".clinerules/",
+    ".windsurfrules",
+    "GEMINI.md",
+    ".claude-plugin/",
+    ".augment-plugin/",
+    "package-lock.json",
+    "docs/decisions/INDEX.md",
+    "agents/roadmaps/archive/INDEX.md",
+    "agents/roadmaps/archive/index.json"
+  ],
+  "excluded_note": [
+    "Generated projections and lockfiles are removed BEFORE a commit is classified,",
+    "and are excluded from both the commit view and the diff view. A commit left with",
+    "no path after the exclusion is counted in the `generated_only` diagnostic rather",
+    "than as maintenance -- otherwise a release's ratio would depend on whether the",
+    "regeneration was committed separately from the source edit that caused it."
+  ],
+  "rules": [
+    { "prefix": "src/skills/", "category": "consumer" },
+    { "prefix": "src/rules/", "category": "consumer" },
+    { "prefix": "src/agent-src/", "category": "consumer" },
+    { "prefix": "src/domains/", "category": "consumer" },
+    { "prefix": "src/packs/", "category": "consumer" },
+    { "prefix": "src/profiles/", "category": "consumer" },
+    { "prefix": "src/templates/", "category": "consumer" },
+    { "prefix": "src/patterns/", "category": "consumer" },
+    { "prefix": "src/subagents/", "category": "consumer" },
+    { "prefix": "src/missions/", "category": "consumer" },
+    { "prefix": "src/flows/", "category": "consumer" },
+    { "prefix": "src/config/", "category": "consumer" },
+    { "prefix": "src/cli/", "category": "consumer" },
+    { "prefix": "src/install/", "category": "consumer" },
+    { "prefix": "src/server/", "category": "consumer" },
+    { "prefix": "src/ui/", "category": "consumer" },
+    { "prefix": "src/shared/", "category": "unclassified" },
+
+    { "prefix": "src/scripts/", "category": "maintenance" },
+    { "prefix": "src/scripts/ai_council/", "category": "consumer" },
+    { "prefix": "src/scripts/ai_team/", "category": "consumer" },
+    { "prefix": "src/scripts/ai-video/", "category": "consumer" },
+    { "prefix": "src/scripts/ai-image/", "category": "consumer" },
+    { "prefix": "src/scripts/media/", "category": "consumer" },
+    { "prefix": "src/scripts/hooks/", "category": "consumer" },
+    { "prefix": "src/scripts/mcp_server/", "category": "consumer" },
+    { "prefix": "src/scripts/skill_tools/", "category": "consumer" },
+    { "prefix": "src/scripts/command_suggester/", "category": "consumer" },
+    { "prefix": "src/scripts/code_graph/", "category": "consumer" },
+    { "prefix": "src/scripts/prediction-pool/", "category": "consumer" },
+    { "prefix": "src/scripts/cost/", "category": "consumer" },
+
+    { "prefix": "agents/", "category": "governance" },
+    { "prefix": "internal/", "category": "governance" },
+    { "prefix": "provenance/", "category": "governance" },
+
+    { "prefix": "docs/", "category": "consumer" },
+    { "prefix": "docs/decisions/", "category": "governance" },
+    { "prefix": "docs/adrs/", "category": "governance" },
+    { "prefix": "docs/archive/", "category": "governance" },
+    { "prefix": "docs/maintainers/", "category": "governance" },
+    { "prefix": "docs/parity/", "category": "governance" },
+    { "prefix": "docs/wedge/", "category": "governance" },
+    { "prefix": "docs/experiences/", "category": "governance" },
+    { "prefix": "docs/case-studies/", "category": "governance" },
+    { "prefix": "docs/announcements/", "category": "governance" },
+
+    { "prefix": "tests/", "category": "maintenance" },
+    { "prefix": ".github/", "category": "maintenance" },
+    { "prefix": "taskfiles/", "category": "maintenance" },
+    { "prefix": "deploy/", "category": "maintenance" },
+    { "prefix": "site/", "category": "maintenance" },
+    { "prefix": "hooks/", "category": "consumer" },
+    { "prefix": "user-types/", "category": "consumer" },
+    { "prefix": "tokens/", "category": "consumer" },
+    { "prefix": "LICENSES/", "category": "consumer" },
+
+    { "prefix": "README.md", "category": "consumer" },
+    { "prefix": "ONBOARDING.md", "category": "consumer" },
+    { "prefix": "MIGRATION.md", "category": "consumer" },
+    { "prefix": "BREAKING_CHANGES.md", "category": "consumer" },
+    { "prefix": "SECURITY.md", "category": "consumer" },
+    { "prefix": "LEGAL_NOTICE.md", "category": "consumer" },
+    { "prefix": "CHANGELOG.md", "category": "consumer" },
+    { "prefix": "CAPABILITIES.yaml", "category": "consumer" },
+    { "prefix": "CREDITS.md", "category": "consumer" },
+    { "prefix": "REUSE.toml", "category": "consumer" },
+    { "prefix": "LICENSE", "category": "consumer" },
+    { "prefix": "NOTICE", "category": "consumer" },
+    { "prefix": "llms.txt", "category": "consumer" },
+
+    { "prefix": "AGENTS.md", "category": "governance" },
+    { "prefix": "CLAUDE.md", "category": "governance" },
+    { "prefix": "CONTRIBUTING.md", "category": "governance" },
+
+    { "prefix": "Taskfile.yml", "category": "maintenance" },
+    { "prefix": "agent-config", "category": "maintenance" },
+    { "prefix": "scripts-run", "category": "maintenance" },
+    { "prefix": "setup.sh", "category": "maintenance" },
+    { "prefix": "package.json", "category": "maintenance" },
+    { "prefix": "eslint.config.js", "category": "maintenance" },
+    { "prefix": "tsconfig", "category": "maintenance" },
+    { "prefix": "vite.config.ts", "category": "maintenance" },
+    { "prefix": "vitest.config.ts", "category": "maintenance" },
+    { "prefix": "playwright.config.ts", "category": "maintenance" },
+    { "prefix": "glama.json", "category": "maintenance" },
+    { "prefix": "mcp.json", "category": "maintenance" },
+    { "prefix": "allowlist_backup.json", "category": "maintenance" },
+    { "prefix": ".augmentignore", "category": "maintenance" },
+    { "prefix": ".dockerignore", "category": "maintenance" },
+    { "prefix": ".gitattributes", "category": "maintenance" },
+    { "prefix": ".gitignore", "category": "maintenance" },
+    { "prefix": ".mailmap", "category": "maintenance" },
+    { "prefix": ".npmignore", "category": "maintenance" },
+    { "prefix": ".path-leak-allow", "category": "maintenance" },
+    { "prefix": ".secret-allow", "category": "maintenance" }
+  ],
+  "governance_contracts": [
+    "docs/contracts/adr-layout.md",
+    "docs/contracts/adr-architectural-consensus-mechanism.md",
+    "docs/contracts/ai-council-config.md",
+    "docs/contracts/adversarial-review-protocol.md",
+    "docs/contracts/branch-protection-policy.md",
+    "docs/contracts/ci-green-floor.md",
+    "docs/contracts/ci-cost-budget.md",
+    "docs/contracts/release-pr-gating.md",
+    "docs/contracts/release-sizing.md",
+    "docs/contracts/release-trunk-sync.md",
+    "docs/contracts/CHANGELOG-conventions.md",
+    "docs/contracts/evidence-artifact-types.md",
+    "docs/contracts/kernel-membership.md",
+    "docs/contracts/package-self-orientation.md"
+  ],
+  "governance_contracts_note": [
+    "`docs/contracts/` defaults to `consumer` because most contracts on that page",
+    "describe behavior the package promises an installing consumer -- classifying the",
+    "whole directory as governance would systematically undercount shipped work.",
+    "The files listed above are the exceptions: contracts that govern this",
+    "repository's own process (decision recording, council, release cutting, CI",
+    "floors, evidence discipline) rather than promised behavior. They resolve to",
+    "`governance`. A contract absent from this list and absent from the tree is a",
+    "stale entry and is reported by `--audit`."
+  ]
+}

package/src/scripts/release_publication.ts

@@ -515,6 +515,97 @@ export function guard_release_branch_push(branch: string): void {
  * and every line above 1500 is charged by the growth ratchet, while this module
  * is far below it.
  */
+/**
+ * Own the whole step-1 branch decision: reuse an existing release branch, and
+ * make sure whatever we end up on carries current `main`.
+ *
+ * Three defects it closes, all measured on 14.15.0 (2026-09-03) in one sitting,
+ * and all the same underlying mistake — a release branch that is not on current
+ * `main`, discovered later than it could have been.
+ *
+ * 1. **Reuse was gated on `--resume`.** The two "branch exists" arms read
+ *    `resume && _branch_exists_local(branch)`, so a PLAIN `task release` over an
+ *    existing branch fell through to `git checkout -b` and died with exit 128.
+ *    That is exactly the state `guard_release_curation` leaves behind — it stops
+ *    before the commit, and the branch it stops on already exists — while its
+ *    own message says to re-run `task release`. The message was right about
+ *    what to do and the code refused to do it. Reuse no longer consults
+ *    `resume`: an existing release branch is a fact about the repository, not
+ *    about the flag.
+ * 2. **A branch cut from an older `main` failed at the PUSH.** The pre-push
+ *    preflight reported `branch is BEHIND origin/main` after steps 2 and 3 had
+ *    already bumped and committed — the cheapest moment to integrate `main` is
+ *    the moment we check the branch out, not eight steps later.
+ * 3. **A fresh branch was cut from whatever local `main` happened to be.** The
+ *    create arm never pulled, so a stale local `main` produced a stale release
+ *    branch and defect 2 followed on the next run. Fixed on the same terms
+ *    rather than left as the half that still bites: leaving it would reproduce
+ *    the "fix that does not fix it" pattern the other two came from.
+ *
+ * `say` is a callback rather than a direct write because the `[N/total]` step
+ * prefix belongs to the orchestrator, which knows the total; this module does
+ * not. Keeping the printing there and the decision here is also what lets
+ * `release.ts` shed twenty lines — it sits ~500 lines past the 1500-line cap,
+ * where every line is charged by the growth ratchet, and this module is under
+ * it.
+ *
+ * The merge is `git merge`, never a rebase and never a force: a release branch
+ * can already carry a pushed commit and somebody else's merge, and neither is
+ * ours to rewrite.
+ */
+export function checkout_release_branch(
+    branch: string,
+    prMerged: boolean,
+    say: (msg: string) => void,
+): void {
+    if (prMerged) {
+        say(`PR for ${branch} already merged — staying on ${MAIN_BRANCH}`);
+        if (git(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true }) !== MAIN_BRANCH) {
+            run(['git', 'checkout', MAIN_BRANCH]);
+        }
+        run(['git', 'pull', '--ff-only', REMOTE, MAIN_BRANCH]);
+        return;
+    }
+    if (_branch_exists_local(branch)) {
+        say(`Branch ${branch} exists locally — checkout`);
+        run(['git', 'checkout', branch]);
+    } else if (_branch_exists_remote(branch)) {
+        say(`Branch ${branch} exists on ${REMOTE} — fetch + checkout`);
+        run(['git', 'fetch', REMOTE, branch]);
+        run(['git', 'checkout', '-b', branch, `${REMOTE}/${branch}`]);
+    } else {
+        // Cut from CURRENT main, not from whatever the local ref happens to be.
+        say(`Create branch ${branch} from current ${MAIN_BRANCH}`);
+        if (git(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true }) === MAIN_BRANCH) {
+            run(['git', 'pull', '--ff-only', REMOTE, MAIN_BRANCH]);
+        }
+        run(['git', 'checkout', '-b', branch]);
+        return;
+    }
+    integrate_main_if_behind(branch, say);
+}
+
+/**
+ * Merge `origin/<default>` into the checked-out release branch when it is
+ * behind, so the pre-push preflight is never the first place that surfaces.
+ *
+ * Silent when the branch is already current — a release run should not print a
+ * merge it did not make. Counting with `rev-list --count` against the fetched
+ * remote ref rather than the local one: the local `main` is exactly what went
+ * stale in the case this exists for.
+ */
+export function integrate_main_if_behind(branch: string, say: (msg: string) => void): void {
+    run(['git', 'fetch', REMOTE, MAIN_BRANCH], { check: false });
+    const behind = git(['rev-list', '--count', `HEAD..${REMOTE}/${MAIN_BRANCH}`], {
+        capture: true,
+    }).trim();
+    if (behind === '' || behind === '0') {
+        return;
+    }
+    say(`Branch ${branch} is ${behind} commit(s) behind ${REMOTE}/${MAIN_BRANCH} — merging it in`);
+    run(['git', 'merge', `${REMOTE}/${MAIN_BRANCH}`, '--no-edit']);
+}
+
 export function guard_release_curation(version: string, prMerged = false): void {
     if (prMerged) {
         return;

package/src/scripts/attest_artifact.ts

@@ -1,193 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Content attestation for any artifact a hook would INJECT.
- *
- * `road-to-skill-ecosystem-runtime-enforcement` Phase 5, Steps 6-7, and the
- * ordering in that step is the argument: attestation is the **precondition** for
- * auto-injection, not a follow-up to it.
- *
- * ── The threat, concretely ──────────────────────────────────────────────────
- * A hook that reads a tracked file and injects its contents into the model's
- * context turns that file into a **standing injection amplifier**. Whoever can
- * write the file can write the agent's instructions, on every session, without
- * a review — which is `untrusted-input-defense`'s found-instructions case
- * arriving through a file the repository itself vouches for. The file being
- * tracked is not the control: a tracked file changes in a pull request, and a
- * pull request that changes an injected file is indistinguishable in the diff
- * from one that changes documentation.
- *
- * ── The contract ────────────────────────────────────────────────────────────
- * An injectable artifact carries a sidecar `<file>.attest.json` holding the
- * sha256 of its bytes and the date the attestation was recorded. Before
- * injecting, a caller asks {@link verifyArtifact}:
- *
- *   - hash matches   → `ok`, inject.
- *   - hash differs   → `mismatch`, REFUSE. The content changed since a human
- *     vouched for it; re-attesting is a deliberate act with a diff.
- *   - no sidecar     → `unattested`, REFUSE. **Not "allow because nothing said
- *     no"** — that default makes the whole mechanism opt-out, and the file an
- *     attacker adds is exactly the one with no sidecar.
- *   - file missing   → `absent`, REFUSE.
- *
- * ── What this does NOT claim ────────────────────────────────────────────────
- * The sidecar is committed beside the artifact, so an attacker who can write
- * both can write a consistent pair. This is NOT a cryptographic signature and
- * does not pretend to be one. What it buys is that the change becomes VISIBLE:
- * a diff that touches an injected file must also touch its attestation, and a
- * hash line changing in a review is a question, where a prose change in the same
- * file is not. Making a change reviewable is the honest claim; making it
- * impossible would need a key this repository does not have.
- *
- * Exit codes: 0 verified · 1 refused (mismatch / unattested / absent) · 2 usage.
- *
- * Usage:
- *     ./scripts-run src/scripts/attest_artifact --record <file>
- *     ./scripts-run src/scripts/attest_artifact --verify <file>
- *     ./scripts-run src/scripts/attest_artifact --verify <file> --json
- */
-import * as crypto from 'node:crypto';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const _HERE = fileURLToPath(import.meta.url);
-
-/** Sidecar suffix. Beside the artifact, so a move takes the attestation with it. */
-export const ATTEST_SUFFIX = '.attest.json';
-
-export type AttestStatus = 'ok' | 'mismatch' | 'unattested' | 'absent';
-
-export interface Attestation {
-    schema_version: 1;
-    /** sha256 of the artifact's bytes, hex. */
-    sha256: string;
-    /** `YYYY-MM-DD` the attestation was recorded. */
-    recorded_at: string;
-    /** Bytes at record time — a cheap second signal that costs nothing to store. */
-    bytes: number;
-}
-
-export interface Verdict {
-    status: AttestStatus;
-    /** True only for `ok`. Every other status refuses. */
-    inject: boolean;
-    detail: string;
-    expected?: string;
-    actual?: string;
-}
-
-export function sidecarPath(artifact: string): string {
-    return `${artifact}${ATTEST_SUFFIX}`;
-}
-
-export function hashFile(artifact: string): string {
-    return crypto.createHash('sha256').update(fs.readFileSync(artifact)).digest('hex');
-}
-
-/**
- * Verify an artifact against its sidecar.
- *
- * Every non-`ok` status sets `inject: false`. That is the whole safety property
- * and it is expressed as data rather than left to each caller's `if`: a caller
- * that reads `verdict.inject` cannot accidentally treat `unattested` as
- * permissive, which is the mistake an `status === 'mismatch'` check invites.
- */
-export function verifyArtifact(artifact: string, today?: string): Verdict {
-    void today;
-    if (!fs.existsSync(artifact)) {
-        return { status: 'absent', inject: false, detail: `${artifact} does not exist` };
-    }
-    const side = sidecarPath(artifact);
-    if (!fs.existsSync(side)) {
-        return {
-            status: 'unattested',
-            inject: false,
-            detail:
-                `${artifact} has no ${ATTEST_SUFFIX} sidecar — REFUSED. An unattested artifact is ` +
-                'not "allowed because nothing said no": that default makes attestation opt-out, and ' +
-                'the file an attacker adds is precisely the one with no sidecar.',
-        };
-    }
-    let att: Partial<Attestation>;
-    try {
-        att = JSON.parse(fs.readFileSync(side, 'utf8')) as Partial<Attestation>;
-    } catch (e) {
-        return {
-            status: 'unattested',
-            inject: false,
-            detail: `${side} does not parse (${e instanceof Error ? e.message : String(e)}) — treated as absent`,
-        };
-    }
-    const actual = hashFile(artifact);
-    if (typeof att.sha256 !== 'string' || att.sha256 === '') {
-        return { status: 'unattested', inject: false, detail: `${side} carries no sha256`, actual };
-    }
-    if (att.sha256 !== actual) {
-        return {
-            status: 'mismatch',
-            inject: false,
-            detail:
-                `${artifact} changed since it was attested — REFUSED. Re-attest deliberately ` +
-                `(--record) so the new hash lands in a diff a reviewer sees.`,
-            expected: att.sha256,
-            actual,
-        };
-    }
-    return { status: 'ok', inject: true, detail: `${artifact} matches its attestation`, expected: att.sha256, actual };
-}
-
-/** Record (or re-record) an attestation. Deliberate, and it lands in a diff. */
-export function recordAttestation(artifact: string, today = new Date().toISOString().slice(0, 10)): Attestation {
-    const att: Attestation = {
-        schema_version: 1,
-        sha256: hashFile(artifact),
-        recorded_at: today,
-        bytes: fs.statSync(artifact).size,
-    };
-    fs.writeFileSync(sidecarPath(artifact), `${JSON.stringify(att, null, 2)}\n`, 'utf8');
-    return att;
-}
-
-export function main(argv: string[] = process.argv.slice(2)): number {
-    const usage =
-        'usage: attest_artifact (--record | --verify) <file> [--json]\n' +
-        '  --verify exits 1 on mismatch, unattested or absent. Refusal is the default.\n';
-    if (argv.includes('-h') || argv.includes('--help')) {
-        process.stdout.write(usage);
-        return 0;
-    }
-    const asJson = argv.includes('--json');
-    const record = argv.includes('--record');
-    const verify = argv.includes('--verify');
-    const file = argv.find((a) => !a.startsWith('--'));
-    if (record === verify || file === undefined) {
-        process.stderr.write(`attest_artifact: error: exactly one of --record / --verify plus a file\n${usage}`);
-        return 2;
-    }
-    const target = path.resolve(file);
-    if (record) {
-        if (!fs.existsSync(target)) {
-            process.stderr.write(`attest_artifact: ${file} does not exist\n`);
-            return 2;
-        }
-        const att = recordAttestation(target);
-        process.stdout.write(`✅  attested ${file} — sha256 ${att.sha256.slice(0, 16)}… (${String(att.bytes)} bytes)\n`);
-        return 0;
-    }
-    const v = verifyArtifact(target);
-    if (asJson) {
-        process.stdout.write(`${JSON.stringify(v, null, 2)}\n`);
-    } else if (v.inject) {
-        process.stdout.write(`✅  ${v.detail}\n`);
-    } else {
-        process.stderr.write(`❌  [${v.status}] ${v.detail}\n`);
-    }
-    return v.inject ? 0 : 1;
-}
-
-/* c8 ignore start */
-if (process.argv[1] !== undefined && pathToFileURL(path.resolve(process.argv[1])).href === pathToFileURL(_HERE).href) {
-    process.exit(main());
-}
-/* c8 ignore stop */