@event4u/agent-config 8.11.0 → 8.13.0

package/src/scripts/_cli/cmd_doctor.ts

@@ -29,7 +29,7 @@
  * scope · global-binary · claude-plugin · stale-orphans · manifest-integrity ·
  * lockfile-freshness · bridge-drift · mcp-mode · mcp-beta-readiness ·
  * offline-readiness · python-runtime · humanizer-runtime · tier-usage-readiness ·
- * council-cli ·
+ * council-cli · team ·
  * unsupported-combos · wizard-state.
  * Each emits a structured `{id, status, message, remedy}` record with
  * `status` ∈ `ok` / `warn` / `fail` / `skipped` (rendered
@@ -731,6 +731,7 @@ function relativeTo(p: string, base: string): string | null {
 const CHECK_IDS = [
     'scope',
     'global-binary',
+    'git-identity',
     'claude-plugin',
     'claude-command-wrappers',
     'surface-state',
@@ -746,6 +747,7 @@ const CHECK_IDS = [
     'humanizer-runtime',
     'tier-usage-readiness',
     'council-cli',
+    'team',
     'unsupported-combos',
     'wizard-state',
     'settings-review-pending',
@@ -755,6 +757,7 @@ const CHECK_IDS = [
 const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'scope',
     'global-binary',
+    'git-identity',
     'claude-plugin',
     'claude-command-wrappers',
     'surface-state',
@@ -767,6 +770,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'humanizer-runtime',
     'tier-usage-readiness',
     'council-cli',
+    'team',
     'wizard-state',
     'settings-review-pending',
 ]);
@@ -840,6 +844,97 @@ function _check_scope(project_root: string): Dict {
     };
 }
 
+/** Placeholder git identities that must never author real history — the
+ * 8.11 feedback found 72/100 recent commits stamped `t <t@t.t>` because a
+ * repo-local config carried a throwaway identity. Reads config FILES (no
+ * shell-out): repo-local wins over global, worktree gitdirs resolved. */
+const _PLACEHOLDER_EMAIL_RE = /^(t@t\.t|.*@example\.(com|org)|.*@localhost)$/i;
+const _PLACEHOLDER_NAME_RE = /^(t|test|user|nobody|x)$/i;
+
+export function _git_config_path(project_root: string): string | null {
+    const gd = path.join(project_root, '.git');
+    try {
+        const st = fs.statSync(gd);
+        if (st.isDirectory()) {
+            return path.join(gd, 'config');
+        }
+        // Worktree: `.git` is a file "gitdir: <path>".
+        const m = readText(gd).match(/^gitdir:\s*(.+)\s*$/m);
+        if (m === null) {
+            return null;
+        }
+        const gdPath = path.resolve(project_root, m[1]!.trim());
+        const commondirFile = path.join(gdPath, 'commondir');
+        if (pathExists(commondirFile)) {
+            const common = path.resolve(gdPath, readText(commondirFile).trim());
+            return path.join(common, 'config');
+        }
+        return path.join(gdPath, 'config');
+    } catch {
+        return null;
+    }
+}
+
+function _parse_git_user(configText: string): { name: string | null; email: string | null } {
+    let inUser = false;
+    let name: string | null = null;
+    let email: string | null = null;
+    for (const raw of configText.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith('[')) {
+            inUser = /^\[user\]/i.test(line);
+            continue;
+        }
+        if (!inUser) {
+            continue;
+        }
+        const m = line.match(/^(name|email)\s*=\s*(.+)$/i);
+        if (m !== null) {
+            if (m[1]!.toLowerCase() === 'name') name = m[2]!.trim();
+            else email = m[2]!.trim();
+        }
+    }
+    return { name, email };
+}
+
+export function _check_git_identity(project_root: string): Dict {
+    const cfgPath = _git_config_path(project_root);
+    if (cfgPath === null || !pathExists(cfgPath)) {
+        return { id: 'git-identity', status: 'skipped', message: 'not a git repository', remedy: '' };
+    }
+    let ident = _parse_git_user(readText(cfgPath));
+    if (ident.name === null && ident.email === null) {
+        const globalCfg = path.join(os.homedir(), '.gitconfig');
+        if (pathExists(globalCfg)) {
+            ident = _parse_git_user(readText(globalCfg));
+        }
+    }
+    if (ident.name === null && ident.email === null) {
+        return {
+            id: 'git-identity',
+            status: 'warn',
+            message: 'no git user identity configured (repo or global)',
+            remedy: 'git config user.name "<you>" && git config user.email "<you@host>"',
+        };
+    }
+    const badEmail = ident.email !== null && _PLACEHOLDER_EMAIL_RE.test(ident.email);
+    const badName = ident.name !== null && _PLACEHOLDER_NAME_RE.test(ident.name);
+    if (badEmail || badName) {
+        return {
+            id: 'git-identity',
+            status: 'warn',
+            message: `placeholder git identity configured: ${ident.name ?? '?'} <${ident.email ?? '?'}> — commits will be unattributable`,
+            remedy: 'git config user.name "<you>" && git config user.email "<you@host>" (and add a .mailmap for already-authored history)',
+        };
+    }
+    return {
+        id: 'git-identity',
+        status: 'ok',
+        message: `${ident.name ?? '?'} <${ident.email ?? '?'}>`,
+        remedy: '',
+    };
+}
+
 function _check_manifest_integrity(manifest: Dict): Dict {
     const schema = manifest['schema_version'];
     const version = manifest['agent_config_version'];
@@ -1882,6 +1977,196 @@ function pyFloat(value: number): string {
     return String(value);
 }
 
+// ---------------------------------------------------------------------------
+// team check (road-to-team-mode Phase 1) — codex binary + auth, official
+// codex plugin on Claude-Code hosts, Review-Gate consistency.
+// ---------------------------------------------------------------------------
+
+/**
+ * Codex CLI home — `CODEX_HOME` env override (the codex CLI's own
+ * convention), else `~/.codex`.
+ */
+function _codex_home(): string {
+    const env = (process.env['CODEX_HOME'] ?? '').trim();
+    return env !== '' ? env : path.join(os.homedir(), '.codex');
+}
+
+/**
+ * Codex binary name for the team check — REUSES the council probe's binary
+ * discovery: when a council config exists and declares an enabled cli-mode
+ * `openai` member with a `binary` override, honour it; else the provider
+ * default from `_CLI_PROVIDER_META` (`codex`). Never throws — an unreadable
+ * or invalid council config falls back to the default binary (the council-cli
+ * check owns reporting that problem).
+ */
+function _team_codex_binary_name(project_root: string): string {
+    const default_bin = (_CLI_PROVIDER_META['openai'] as [string, boolean])[0];
+    const { load_council_config, resolve_config_path } = ai_council_config;
+    const council_path = resolve_config_path(project_root);
+    if (!pathExists(String(council_path))) {
+        return default_bin;
+    }
+    let cfg: ai_council_config.CouncilConfig;
+    try {
+        cfg = load_council_config(council_path);
+    } catch {
+        return default_bin;
+    }
+    const member = cfg.members.get('openai');
+    if (member && member.enabled && member.mode === 'cli' && member.binary) {
+        return member.binary;
+    }
+    return default_bin;
+}
+
+/** Settings-flag coercion shared with the tier-usage check (bool or string). */
+function _settings_flag(val: unknown): boolean {
+    if (typeof val === 'boolean') return val;
+    if (typeof val === 'string') {
+        return ['true', 'yes', 'on', '1'].includes(val.trim().toLowerCase());
+    }
+    return false;
+}
+
+/** The `ai_team` block from `.agent-settings.yml` — lenient, `{}` when absent. */
+function _read_ai_team_block(project_root: string): Dict {
+    const settings_file = project_settings_path(project_root);
+    if (!isFile(settings_file)) return {};
+    let content: string;
+    try {
+        content = readText0(settings_file);
+    } catch {
+        return {};
+    }
+    const loaded = yamlSafeLoad(content);
+    if (typeof loaded !== 'object' || loaded === null || Array.isArray(loaded)) return {};
+    const raw = (loaded as Dict)['ai_team'];
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return {};
+    return raw as Dict;
+}
+
+/**
+ * `team` health check — three sub-signals folded into one result:
+ *
+ * (a) codex binary present (council-probe binary discovery reused) AND
+ *     auth present. Auth is a READ-ONLY presence probe of
+ *     `$CODEX_HOME/auth.json` (default `~/.codex/auth.json`) — token
+ *     expiry cannot be validated without a billable call; runtime expiry
+ *     is caught by `OpenAICliClient._AUTH_FAILURE_PATTERNS`.
+ * (b) on Claude-Code hosts (claude binary on PATH or the Claude config dir
+ *     present): the official codex plugin recorded in
+ *     `plugins/installed_plugins.json`. Detection is read-only — doctor
+ *     never writes under `~/.claude/`.
+ * (c) Review-Gate consistency: `ai_team.review_gate.managed` on while the
+ *     loop bound (`max_consecutive_blocks`, Phase 4 — unbuilt) is absent
+ *     → WARN.
+ *
+ * Absent feature ≠ broken feature: with `ai_team` absent or disabled the
+ * check reports ok ("team mode not configured (default-off)"); WARN fires
+ * only on failing sub-signals or inconsistent half-configured states.
+ */
+function _check_team(project_root: string): Dict {
+    const ai_team = _read_ai_team_block(project_root);
+    const enabled = _settings_flag(ai_team['enabled']);
+    const gateRaw = ai_team['review_gate'];
+    const gate =
+        typeof gateRaw === 'object' && gateRaw !== null && !Array.isArray(gateRaw)
+            ? (gateRaw as Dict)
+            : {};
+    const gate_managed = _settings_flag(gate['managed']);
+    const bound = gate['max_consecutive_blocks'];
+    const bound_present = typeof bound === 'number' && Number.isInteger(bound) && bound > 0;
+
+    if (!enabled) {
+        if (gate_managed) {
+            return {
+                id: 'team',
+                status: 'warn',
+                message:
+                    'half-configured: ai_team.review_gate.managed is on but ' +
+                    'ai_team.enabled is false — the gate never runs',
+                remedy:
+                    'set `ai_team.enabled: true` in .agent-settings.yml, or ' +
+                    'remove `ai_team.review_gate.managed`',
+            };
+        }
+        return {
+            id: 'team',
+            status: 'ok',
+            message: 'team mode not configured (default-off)',
+            remedy:
+                'opt in via `ai_team.enabled: true` in .agent-settings.yml, ' +
+                'then re-run `agent-config doctor --check team`',
+        };
+    }
+
+    const remedies: string[] = [];
+
+    // (a) codex binary — council-probe discovery reused.
+    const binary_name = _team_codex_binary_name(project_root);
+    const binary_resolved = shutilWhich(binary_name);
+    const binary_glyph = binary_resolved !== null ? '✅' : '❌';
+    if (binary_resolved === null) {
+        remedies.push('install the codex CLI: `npm install -g @openai/codex`');
+    }
+
+    // (a, cont.) codex auth — presence probe of $CODEX_HOME/auth.json.
+    const auth_path = path.join(_codex_home(), 'auth.json');
+    const authed = pathExists(auth_path);
+    const auth_glyph = authed ? '✅' : '❌';
+    if (!authed) {
+        remedies.push('run `codex login`');
+    }
+
+    // (b) official codex plugin — Claude-Code hosts only.
+    const is_claude_host =
+        shutilWhich('claude') !== null || pathExists(claude_plugin.claude_config_dir());
+    let plugin_str: string;
+    if (is_claude_host) {
+        const plugin_present = claude_plugin.codex_plugin_installed();
+        plugin_str = `codex plugin ${plugin_present ? '✅' : '❌'}`;
+        if (!plugin_present) {
+            remedies.push(
+                'install the official codex plugin: ' +
+                    claude_plugin.CODEX_PLUGIN_INSTALL_HINT.map((c) => `\`${c}\``).join(' then '),
+            );
+        }
+    } else {
+        plugin_str = 'codex plugin — (not a Claude Code host; fallback path applies)';
+    }
+
+    // (c) Review-Gate consistency.
+    let gate_str: string;
+    if (gate_managed && !bound_present) {
+        gate_str = 'review-gate ⚠️ on, loop bound absent';
+        remedies.push(
+            'set `ai_team.review_gate.max_consecutive_blocks` (loop bound; ' +
+                'ships with the Review-Gate governance phase) or set ' +
+                '`ai_team.review_gate.managed: false`',
+        );
+    } else {
+        gate_str = `review-gate ${gate_managed ? 'on' : 'off'}`;
+    }
+
+    const detail =
+        `codex binary ${binary_glyph} (${binary_name}) · ` +
+        `codex auth ${auth_glyph} (${auth_path}) · ${plugin_str} · ${gate_str}`;
+    if (remedies.length > 0) {
+        return {
+            id: 'team',
+            status: 'warn',
+            message: `${remedies.length} team sub-signal(s) failing · ${detail}`,
+            remedy: remedies.join('; '),
+        };
+    }
+    return {
+        id: 'team',
+        status: 'ok',
+        message: `team mode enabled · ${detail}`,
+        remedy: '',
+    };
+}
+
 function _check_unsupported_combos(manifest: Dict): Dict {
     const global_only = new Set(['droid', 'qoder']);
     const bad: string[] = [];
@@ -2142,6 +2427,7 @@ function _run_checks(
     const runners: Record<string, CheckRunner> = {
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
+        'git-identity': () => _check_git_identity(project_root),
         'claude-plugin': _check_claude_plugin,
         'claude-command-wrappers': _check_claude_command_wrappers,
         'surface-state': _check_surface_state,
@@ -2163,6 +2449,7 @@ function _run_checks(
         'humanizer-runtime': () => _check_humanizer_runtime(),
         'tier-usage-readiness': () => _check_tier_usage_readiness(project_root),
         'council-cli': () => _check_council_cli(project_root),
+        team: () => _check_team(project_root),
         'unsupported-combos': () => _check_unsupported_combos(manifest),
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
@@ -2219,6 +2506,7 @@ function _run_checks_no_manifest(
     const runners: Record<string, CheckRunner> = {
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
+        'git-identity': () => _check_git_identity(project_root),
         'claude-plugin': _check_claude_plugin,
         'claude-command-wrappers': _check_claude_command_wrappers,
         'surface-state': _check_surface_state,
@@ -2234,6 +2522,7 @@ function _run_checks_no_manifest(
         'humanizer-runtime': () => _check_humanizer_runtime(),
         'tier-usage-readiness': () => _check_tier_usage_readiness(project_root),
         'council-cli': () => _check_council_cli(project_root),
+        team: () => _check_team(project_root),
         'unsupported-combos': () => _skipped_manifest_check('unsupported-combos'),
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
@@ -2723,6 +3012,7 @@ export {
     _check_mcp_beta_readiness,
     _check_tier_usage_readiness,
     _check_council_cli,
+    _check_team,
     _check_unsupported_combos,
     _check_wizard_state,
     _check_settings_review_pending,

package/src/scripts/_lib/claude_plugin.ts

@@ -27,6 +27,22 @@ export const CLAUDE_PLUGIN_INSTALL_HINT: readonly string[] = [
     `claude plugin install ${CLAUDE_PLUGIN_ID}@${CLAUDE_MARKETPLACE_NAME}`,
 ];
 
+/**
+ * Official OpenAI codex plugin for Claude Code (team mode's Claude-Code
+ * transport). Marketplace name verified against the upstream repo's
+ * `.claude-plugin/marketplace.json` (`name: "openai-codex"`, plugin
+ * `name: "codex"`) at HEAD 2026-07-12.
+ */
+export const CODEX_PLUGIN_ID = 'codex';
+export const CODEX_MARKETPLACE_NAME = 'openai-codex';
+export const CODEX_MARKETPLACE_REPO = 'openai/codex-plugin-cc';
+
+/** The one-time install commands surfaced when the codex plugin is missing. */
+export const CODEX_PLUGIN_INSTALL_HINT: readonly string[] = [
+    `claude plugin marketplace add ${CODEX_MARKETPLACE_REPO}`,
+    `claude plugin install ${CODEX_PLUGIN_ID}@${CODEX_MARKETPLACE_NAME}`,
+];
+
 /** Claude Code config dir — `CLAUDE_CONFIG_DIR` env override, else `~/.claude`. */
 export function claude_config_dir(): string {
     const env = (process.env['CLAUDE_CONFIG_DIR'] ?? '').trim();
@@ -34,11 +50,11 @@ export function claude_config_dir(): string {
 }
 
 /**
- * True when the agent-config plugin is recorded in Claude Code's
+ * True when a plugin with the given id is recorded in Claude Code's
  * `plugins/installed_plugins.json` (any marketplace — matched by the
- * `agent-config@` id prefix). Unreadable / absent file → false.
+ * `<id>@` key prefix). Unreadable / absent file → false. Read-only.
  */
-export function claude_plugin_installed(): boolean {
+function _plugin_id_recorded(plugin_id: string): boolean {
     const p = path.join(claude_config_dir(), 'plugins', 'installed_plugins.json');
     let data: unknown;
     try {
@@ -50,10 +66,29 @@ export function claude_plugin_installed(): boolean {
     const plugins = (data as { plugins?: unknown }).plugins;
     if (plugins === null || plugins === undefined || typeof plugins !== 'object') return false;
     return Object.keys(plugins as Record<string, unknown>).some((k) =>
-        k.startsWith(`${CLAUDE_PLUGIN_ID}@`),
+        k.startsWith(`${plugin_id}@`),
     );
 }
 
+/**
+ * True when the agent-config plugin is recorded in Claude Code's
+ * `plugins/installed_plugins.json` (any marketplace — matched by the
+ * `agent-config@` id prefix). Unreadable / absent file → false.
+ */
+export function claude_plugin_installed(): boolean {
+    return _plugin_id_recorded(CLAUDE_PLUGIN_ID);
+}
+
+/**
+ * True when the official OpenAI codex plugin is recorded in Claude Code's
+ * `plugins/installed_plugins.json` (any marketplace — matched by the
+ * `codex@` id prefix). Unreadable / absent file → false. Read-only:
+ * detection never writes under `~/.claude/`.
+ */
+export function codex_plugin_installed(): boolean {
+    return _plugin_id_recorded(CODEX_PLUGIN_ID);
+}
+
 /**
  * Version recorded in the installed marketplace snapshot's
  * `.claude-plugin/marketplace.json` (`metadata.version` — bumped per

package/src/scripts/_lib/knowledge_global.ts

@@ -58,6 +58,29 @@ export const TIERS: readonly string[] = ['public', 'vendor', 'proprietary'];
  */
 export const DEFAULT_ALLOWED_TIERS: readonly string[] = ['public'];
 
+/**
+ * Sensitivity axis (Phase 1, road-to-feedback-8.11 / successor note to
+ * ADR-119) — orthogonal to `TIERS` (origin) and layered on top of the
+ * existing tier + redaction gate. `tier` classifies WHERE a card came from;
+ * `sensitivity` classifies WHETHER it may ever leave the project at all.
+ *
+ *   * `prohibited` — contains redaction-class content; never leaves the
+ *     repo. Machine-derived from the redaction scan (a card is never
+ *     hand-labelled into this class — a positive hit forces it).
+ *   * `project` — DEFAULT. Stays project-local; promotion is refused
+ *     unless a human explicitly reclassifies the card to `shareable`.
+ *   * `shareable` — eligible for the global store; must pass redaction
+ *     AND carry full promotion provenance (see the G5 footer fields).
+ *
+ * Deliberately kept to three machine-anchored classes — a wider
+ * team/organization taxonomy is phantom for a single-maintainer install and
+ * would over-fit; revisit only once a real multi-tenant consumer exists.
+ */
+export const SENSITIVITIES: readonly string[] = ['prohibited', 'project', 'shareable'];
+
+/** Default sensitivity for a card with no explicit `sensitivity:` field. */
+export const DEFAULT_SENSITIVITY = 'project';
+
 /**
  * Hard defaults applied when the setting block is absent. Default is ON for
  * the safe tiers; turning sharing on never makes promotion automatic.
@@ -384,6 +407,14 @@ const _PROVENANCE_FIELDS: readonly string[] = [
     'last_verified',
     'tier',
     'seen_in',
+    // G5 promotion audit-trail fields (Phase 1, road-to-feedback-8.11):
+    // the more consistent home for these than frontmatter, since they sit
+    // alongside the other promotion-time facts above, not the card's own
+    // origin-tier/sensitivity classification (which lives in frontmatter).
+    'source_repo',
+    'owner',
+    'review_after',
+    'promotion_reason',
 ];
 
 /** Render the global-card provenance footer (the unversioned-store audit trail). */
@@ -394,6 +425,10 @@ export function render_provenance_footer(args: {
     last_verified: string;
     tier: string;
     seen_in: string[];
+    source_repo: string;
+    owner: string;
+    review_after: string;
+    promotion_reason: string;
 }): string {
     return [
         PROVENANCE_START,
@@ -403,11 +438,20 @@ export function render_provenance_footer(args: {
         `- last_verified: ${args.last_verified}`,
         `- tier: ${args.tier}`,
         `- seen_in: ${args.seen_in.join(', ')}`,
+        `- source_repo: ${args.source_repo}`,
+        `- owner: ${args.owner}`,
+        `- review_after: ${args.review_after}`,
+        `- promotion_reason: ${_singleLine(args.promotion_reason)}`,
         PROVENANCE_END,
         '',
     ].join('\n');
 }
 
+/** Collapse a human-entered reason to one line — footer fields are line-based. */
+function _singleLine(s: string): string {
+    return s.replace(/\r\n|\r|\n/g, ' ').trim();
+}
+
 /** Extract the provenance footer fields as a flat dict (empty if absent). */
 export function parse_provenance_footer(text: string): Record<string, string> {
     if (!text.includes(PROVENANCE_START) || !text.includes(PROVENANCE_END)) {

package/src/scripts/_lib/knowledge_global_promote.ts

@@ -187,6 +187,156 @@ export function should_suggest(
     return len >= options.threshold;
 }
 
+// ---------------------------------------------------------------------------
+// Sensitivity gate (Phase 1, road-to-feedback-8.11 — successor note to
+// ADR-119). Layered ON TOP of the existing tier/redaction gate in
+// `knowledge_global_redaction.ts`: a card must clear tier + redaction FIRST,
+// then clear this gate before its write is allowed to proceed.
+// ---------------------------------------------------------------------------
+
+/** Outcome of the sensitivity gate for one promotion attempt. */
+export interface SensitivityGateResult {
+    readonly eligible: boolean;
+    readonly reason: string;
+    /** The EFFECTIVE sensitivity used for the decision (post auto-derivation). */
+    readonly sensitivity: string;
+}
+
+/**
+ * Resolve the effective sensitivity used for a promotion decision.
+ *
+ * A redaction hit always forces `prohibited`, overriding any declared value —
+ * this is independent of the tier gate's own `halt_on_trigger` setting, so a
+ * `prohibited` override never depends on that unrelated config flag. An
+ * unset / invalid declared value defaults to `project` (never `shareable` —
+ * `shareable` is never auto-assigned, only explicitly declared by a human).
+ */
+export function resolve_effective_sensitivity(declared: string, violations_present: boolean): string {
+    if (violations_present) {
+        return 'prohibited';
+    }
+    const d = (declared ?? '').trim();
+    return knowledge_global.SENSITIVITIES.includes(d) ? d : knowledge_global.DEFAULT_SENSITIVITY;
+}
+
+/**
+ * Gate a card for promotion on the sensitivity axis.
+ *
+ * Refuses anything whose effective sensitivity is not `shareable` (including
+ * the machine-derived `prohibited` override), and refuses a `shareable` card
+ * that has no human-entered `promotion_reason` — the auto-promote
+ * *suggestion* only ever leads to a write once a human states why the card
+ * is safe to share.
+ */
+export function gate_sensitivity_for_promotion(
+    declared_sensitivity: string,
+    options: { violations_present?: boolean; promotion_reason?: string } = {},
+): SensitivityGateResult {
+    const violations_present = options.violations_present ?? false;
+    const effective = resolve_effective_sensitivity(declared_sensitivity, violations_present);
+
+    if (effective === 'prohibited') {
+        return {
+            eligible: false,
+            sensitivity: effective,
+            reason:
+                'sensitivity: prohibited — redaction-class content, never leaves the repo',
+        };
+    }
+    if (effective !== 'shareable') {
+        return {
+            eligible: false,
+            sensitivity: effective,
+            reason:
+                `sensitivity '${effective}' — promotion refused unless a human explicitly ` +
+                "reclassifies the card to 'shareable'",
+        };
+    }
+    const reason = (options.promotion_reason ?? '').trim();
+    if (!reason) {
+        return {
+            eligible: false,
+            sensitivity: effective,
+            reason:
+                "sensitivity 'shareable' but no promotion_reason given — a human must state " +
+                'why this card is safe to share before it may be promoted',
+        };
+    }
+    return { eligible: true, sensitivity: effective, reason: 'sensitivity gate passed' };
+}
+
+// ---------------------------------------------------------------------------
+// Revocation ledger — append-only tombstone trail (Phase 1, road-to-feedback-8.11)
+// ---------------------------------------------------------------------------
+
+export const REVOCATIONS_FILENAME = '.revocations.jsonl';
+
+/** One append-only tombstone line: what was revoked, when, and why. */
+export interface RevocationEntry {
+    readonly revoked_at: string;
+    readonly card_id: string;
+    readonly reason: string;
+}
+
+function _revocations_path(env: knowledge_global.EnvMapType): string {
+    return path.join(knowledge_global.global_store_dir(env, { create: true }), REVOCATIONS_FILENAME);
+}
+
+/**
+ * Append one tombstone line to the revocation ledger — the caller MUST call
+ * this BEFORE deleting the card/usage entry it documents. Append-only (a
+ * single `fs.appendFileSync`, never rewritten): no `forget` / `forget --tier`
+ * / `purge` call ever removes a prior tombstone, so the ledger stays a
+ * durable audit trail across every deletion path — including `purge`, which
+ * deliberately spares this one file while wiping everything else.
+ */
+export function append_tombstone(
+    card_id: string,
+    reason: string,
+    options: { today?: string; env?: knowledge_global.EnvMapType } = {},
+): RevocationEntry {
+    const entry: RevocationEntry = {
+        revoked_at: options.today ?? '',
+        card_id,
+        reason: reason || 'no reason given',
+    };
+    fs.appendFileSync(_revocations_path(options.env ?? null), JSON.stringify(entry) + '\n', 'utf-8');
+    return entry;
+}
+
+/** Read the revocation ledger. Tolerant: missing file → []; malformed lines are skipped. */
+export function load_tombstones(env: knowledge_global.EnvMapType = null): RevocationEntry[] {
+    let text: string;
+    try {
+        text = fs.readFileSync(
+            path.join(knowledge_global.global_store_dir(env), REVOCATIONS_FILENAME),
+            'utf-8',
+        );
+    } catch {
+        return [];
+    }
+    const out: RevocationEntry[] = [];
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.trim();
+        if (!line) {
+            continue;
+        }
+        try {
+            const obj: unknown = JSON.parse(line);
+            if (_isPlainObject(obj) && typeof obj['card_id'] === 'string') {
+                out.push({
+                    revoked_at: String(obj['revoked_at'] ?? ''),
+                    card_id: obj['card_id'],
+                    reason: String(obj['reason'] ?? ''),
+                });
+            }
+        } catch {
+            // corrupt line — skip; never let one bad line crash the ledger read
+        }
+    }
+    return out;
+}
+
 /**
  * List cards that warrant a promotion suggestion under the current config.
  *