@alphafox/cli 0.1.5 → 0.3.2

package/dist/keychain/store.js

@@ -5,6 +5,11 @@
  * (local unit tests only; not a production automation path — ADR 0004).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLastTokenSaveResult = getLastTokenSaveResult;
+exports.keychainServiceName = keychainServiceName;
+exports.keychainAccountName = keychainAccountName;
+exports.keychainPlatform = keychainPlatform;
+exports.probeOsKeychain = probeOsKeychain;
 exports.saveTokens = saveTokens;
 exports.loadTokens = loadTokens;
 exports.deleteTokens = deleteTokens;
@@ -14,12 +19,52 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_child_process_1 = require("node:child_process");
-function serviceName(profile) {
+const linux_secret_service_1 = require("./linux-secret-service");
+const windows_credential_1 = require("./windows-credential");
+/** Last save outcome — callers/tests can observe silent-fallback without stderr parsing. */
+let lastSaveResult = null;
+function getLastTokenSaveResult() {
+    return lastSaveResult;
+}
+function keychainServiceName(profile) {
     return `alphafox-cli.${profile}`;
 }
-function accountName() {
+function keychainAccountName() {
     return "oauth-tokens";
 }
+function serviceName(profile) {
+    return keychainServiceName(profile);
+}
+function accountName() {
+    return keychainAccountName();
+}
+/** Test-only override. Production code uses process.platform. */
+function keychainPlatform(env = process.env) {
+    const raw = env.ALPHAFOX_KEYCHAIN_PLATFORM?.trim();
+    if (raw === "darwin" || raw === "linux" || raw === "win32") {
+        return raw;
+    }
+    return process.platform;
+}
+function probeOsKeychain(env = process.env) {
+    const platform = keychainPlatform(env);
+    if (platform === "darwin") {
+        return { kind: "macos-security", available: true };
+    }
+    if (platform === "linux") {
+        return {
+            kind: "linux-secret-service",
+            available: (0, linux_secret_service_1.linuxSecretServiceAvailable)(env),
+        };
+    }
+    if (platform === "win32") {
+        return {
+            kind: "windows-credential-manager",
+            available: (0, windows_credential_1.windowsCredentialAvailable)(env),
+        };
+    }
+    return { kind: "none", available: false };
+}
 /** File fallback under secure mode 0600 when OS keychain is unavailable (CI/Linux headless). */
 function fileFallbackPath(profile, env) {
     const base = env.ALPHAFOX_KEYCHAIN_DIR?.trim() ||
@@ -29,11 +74,31 @@ function fileFallbackPath(profile, env) {
 function saveTokens(profile, tokens, env = process.env) {
     const payload = JSON.stringify(tokens);
     if (tryKeychainWrite(profile, payload, env)) {
-        return;
+        lastSaveResult = {
+            backend: "keychain",
+            kind: probeOsKeychain(env).kind,
+            degraded: false,
+        };
+        return lastSaveResult;
     }
     const path = fileFallbackPath(profile, env);
     (0, node_fs_1.mkdirSync)((0, node_path_1.join)(path, ".."), { recursive: true });
     (0, node_fs_1.writeFileSync)(path, payload, { mode: 0o600 });
+    const intentionalFile = env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1";
+    lastSaveResult = {
+        backend: "file",
+        path,
+        // Intentional file mode is not a silent degrade.
+        degraded: !intentionalFile,
+    };
+    // Observable signal when OS keychain failed unexpectedly (not force-file).
+    if (!intentionalFile) {
+        process.emitWarning(`OS keychain unavailable for profile "${profile}"; tokens stored in file ${path} (mode 0600). Set ALPHAFOX_FORCE_FILE_KEYCHAIN=1 when file storage is intentional.`, {
+            code: "ALPHAFOX_KEYCHAIN_FILE_FALLBACK",
+            detail: path,
+        });
+    }
+    return lastSaveResult;
 }
 function loadTokens(profile, env = process.env) {
     // Controlled test injection — never document as prod automation.
@@ -77,7 +142,14 @@ function tryKeychainWrite(profile, payload, env) {
     if (env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1") {
         return false;
     }
-    if (process.platform === "darwin") {
+    const platform = keychainPlatform(env);
+    if (platform === "linux") {
+        return (0, linux_secret_service_1.linuxSecretServiceWrite)(serviceName(profile), accountName(), payload, env);
+    }
+    if (platform === "win32") {
+        return (0, windows_credential_1.windowsCredentialWrite)(profile, payload, env);
+    }
+    if (platform === "darwin") {
         try {
             // delete existing silently
             try {
@@ -114,7 +186,14 @@ function tryKeychainRead(profile, env) {
     if (env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1") {
         return null;
     }
-    if (process.platform === "darwin") {
+    const platform = keychainPlatform(env);
+    if (platform === "linux") {
+        return (0, linux_secret_service_1.linuxSecretServiceRead)(serviceName(profile), accountName(), env);
+    }
+    if (platform === "win32") {
+        return (0, windows_credential_1.windowsCredentialRead)(profile, env);
+    }
+    if (platform === "darwin") {
         try {
             const out = (0, node_child_process_1.execFileSync)("security", [
                 "find-generic-password",
@@ -136,7 +215,16 @@ function tryKeychainDelete(profile, env) {
     if (env.ALPHAFOX_FORCE_FILE_KEYCHAIN === "1") {
         return;
     }
-    if (process.platform === "darwin") {
+    const platform = keychainPlatform(env);
+    if (platform === "linux") {
+        (0, linux_secret_service_1.linuxSecretServiceDelete)(serviceName(profile), accountName(), env);
+        return;
+    }
+    if (platform === "win32") {
+        (0, windows_credential_1.windowsCredentialDelete)(profile, env);
+        return;
+    }
+    if (platform === "darwin") {
         try {
             (0, node_child_process_1.execFileSync)("security", [
                 "delete-generic-password",

package/dist/keychain/windows-credential.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Windows Credential Manager via advapi32 CredWrite/CredRead/CredDelete.
+ * Payload is passed on stdin to PowerShell — never as argv.
+ */
+/** CRED_MAX_CREDENTIAL_BLOB_SIZE is 5*512 = 2560. */
+export declare const WINDOWS_CRED_MAX_BYTES = 2560;
+export declare const WINDOWS_CRED_PS1 = "# Alphafox CLI \u2014 Windows Credential Manager helper (t101360)\nparam(\n  [Parameter(Mandatory = $true)][ValidateSet('write','read','delete')][string]$Action,\n  [Parameter(Mandatory = $true)][string]$Target\n)\n$ErrorActionPreference = 'Stop'\nAdd-Type -TypeDefinition @\"\nusing System;\nusing System.Runtime.InteropServices;\nnamespace AlphafoxCred {\n  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]\n  public struct CREDENTIAL {\n    public uint Flags;\n    public uint Type;\n    public string TargetName;\n    public string Comment;\n    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;\n    public uint CredentialBlobSize;\n    public IntPtr CredentialBlob;\n    public uint Persist;\n    public uint AttributeCount;\n    public IntPtr Attributes;\n    public string TargetAlias;\n    public string UserName;\n  }\n  public static class Native {\n    [DllImport(\"advapi32.dll\", CharSet = CharSet.Unicode, SetLastError = true)]\n    public static extern bool CredWrite(ref CREDENTIAL credential, uint flags);\n    [DllImport(\"advapi32.dll\", CharSet = CharSet.Unicode, SetLastError = true)]\n    public static extern bool CredRead(string target, uint type, uint flags, out IntPtr credentialPtr);\n    [DllImport(\"advapi32.dll\", CharSet = CharSet.Unicode, SetLastError = true)]\n    public static extern bool CredDelete(string target, uint type, uint flags);\n    [DllImport(\"advapi32.dll\", SetLastError = true)]\n    public static extern void CredFree(IntPtr credential);\n  }\n}\n\"@\n$CredTypeGeneric = 1\n$PersistLocalMachine = 2\nswitch ($Action) {\n  'write' {\n    $payload = [Console]::In.ReadToEnd()\n    $bytes = [Text.Encoding]::UTF8.GetBytes($payload)\n    if ($bytes.Length -gt 2560) { throw \"credential blob too large\" }\n    $blob = [Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)\n    try {\n      [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)\n      $cred = New-Object AlphafoxCred.CREDENTIAL\n      $cred.Type = $CredTypeGeneric\n      $cred.TargetName = $Target\n      $cred.UserName = \"alphafox-cli\"\n      $cred.CredentialBlobSize = [uint32]$bytes.Length\n      $cred.CredentialBlob = $blob\n      $cred.Persist = $PersistLocalMachine\n      $ok = [AlphafoxCred.Native]::CredWrite([ref]$cred, 0)\n      if (-not $ok) {\n        throw \"CredWrite failed Win32=$([Runtime.InteropServices.Marshal]::GetLastWin32Error())\"\n      }\n    } finally {\n      [Runtime.InteropServices.Marshal]::FreeHGlobal($blob)\n    }\n  }\n  'read' {\n    $ptr = [IntPtr]::Zero\n    $ok = [AlphafoxCred.Native]::CredRead($Target, $CredTypeGeneric, 0, [ref]$ptr)\n    if (-not $ok) { exit 2 }\n    try {\n      $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][AlphafoxCred.CREDENTIAL])\n      $size = [int]$cred.CredentialBlobSize\n      $bytes = New-Object byte[] $size\n      [Runtime.InteropServices.Marshal]::Copy($cred.CredentialBlob, $bytes, 0, $size)\n      [Console]::Out.Write([Text.Encoding]::UTF8.GetString($bytes))\n    } finally {\n      [AlphafoxCred.Native]::CredFree($ptr)\n    }\n  }\n  'delete' {\n    [void][AlphafoxCred.Native]::CredDelete($Target, $CredTypeGeneric, 0)\n  }\n}\n";
+export declare function windowsCredentialTarget(profile: string): string;
+export declare function windowsPowershellBin(env?: NodeJS.ProcessEnv): string;
+export declare function windowsCredentialWrite(profile: string, payload: string, env?: NodeJS.ProcessEnv): boolean;
+export declare function windowsCredentialRead(profile: string, env?: NodeJS.ProcessEnv): string | null;
+export declare function windowsCredentialDelete(profile: string, env?: NodeJS.ProcessEnv): void;
+export declare function windowsCredentialAvailable(env?: NodeJS.ProcessEnv): boolean;

package/dist/keychain/windows-credential.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Windows Credential Manager via advapi32 CredWrite/CredRead/CredDelete.
+ * Payload is passed on stdin to PowerShell — never as argv.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WINDOWS_CRED_PS1 = exports.WINDOWS_CRED_MAX_BYTES = void 0;
+exports.windowsCredentialTarget = windowsCredentialTarget;
+exports.windowsPowershellBin = windowsPowershellBin;
+exports.windowsCredentialWrite = windowsCredentialWrite;
+exports.windowsCredentialRead = windowsCredentialRead;
+exports.windowsCredentialDelete = windowsCredentialDelete;
+exports.windowsCredentialAvailable = windowsCredentialAvailable;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** CRED_MAX_CREDENTIAL_BLOB_SIZE is 5*512 = 2560. */
+exports.WINDOWS_CRED_MAX_BYTES = 2560;
+exports.WINDOWS_CRED_PS1 = `# Alphafox CLI — Windows Credential Manager helper (t101360)
+param(
+  [Parameter(Mandatory = $true)][ValidateSet('write','read','delete')][string]$Action,
+  [Parameter(Mandatory = $true)][string]$Target
+)
+$ErrorActionPreference = 'Stop'
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+namespace AlphafoxCred {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  public struct CREDENTIAL {
+    public uint Flags;
+    public uint Type;
+    public string TargetName;
+    public string Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public uint CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public uint Persist;
+    public uint AttributeCount;
+    public IntPtr Attributes;
+    public string TargetAlias;
+    public string UserName;
+  }
+  public static class Native {
+    [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    public static extern bool CredWrite(ref CREDENTIAL credential, uint flags);
+    [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    public static extern bool CredRead(string target, uint type, uint flags, out IntPtr credentialPtr);
+    [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    public static extern bool CredDelete(string target, uint type, uint flags);
+    [DllImport("advapi32.dll", SetLastError = true)]
+    public static extern void CredFree(IntPtr credential);
+  }
+}
+"@
+$CredTypeGeneric = 1
+$PersistLocalMachine = 2
+switch ($Action) {
+  'write' {
+    $payload = [Console]::In.ReadToEnd()
+    $bytes = [Text.Encoding]::UTF8.GetBytes($payload)
+    if ($bytes.Length -gt ${exports.WINDOWS_CRED_MAX_BYTES}) { throw "credential blob too large" }
+    $blob = [Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)
+    try {
+      [Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
+      $cred = New-Object AlphafoxCred.CREDENTIAL
+      $cred.Type = $CredTypeGeneric
+      $cred.TargetName = $Target
+      $cred.UserName = "alphafox-cli"
+      $cred.CredentialBlobSize = [uint32]$bytes.Length
+      $cred.CredentialBlob = $blob
+      $cred.Persist = $PersistLocalMachine
+      $ok = [AlphafoxCred.Native]::CredWrite([ref]$cred, 0)
+      if (-not $ok) {
+        throw "CredWrite failed Win32=$([Runtime.InteropServices.Marshal]::GetLastWin32Error())"
+      }
+    } finally {
+      [Runtime.InteropServices.Marshal]::FreeHGlobal($blob)
+    }
+  }
+  'read' {
+    $ptr = [IntPtr]::Zero
+    $ok = [AlphafoxCred.Native]::CredRead($Target, $CredTypeGeneric, 0, [ref]$ptr)
+    if (-not $ok) { exit 2 }
+    try {
+      $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][AlphafoxCred.CREDENTIAL])
+      $size = [int]$cred.CredentialBlobSize
+      $bytes = New-Object byte[] $size
+      [Runtime.InteropServices.Marshal]::Copy($cred.CredentialBlob, $bytes, 0, $size)
+      [Console]::Out.Write([Text.Encoding]::UTF8.GetString($bytes))
+    } finally {
+      [AlphafoxCred.Native]::CredFree($ptr)
+    }
+  }
+  'delete' {
+    [void][AlphafoxCred.Native]::CredDelete($Target, $CredTypeGeneric, 0)
+  }
+}
+`;
+function windowsCredentialTarget(profile) {
+    return `alphafox-cli/${profile}/oauth-tokens`;
+}
+function windowsPowershellBin(env = process.env) {
+    return env.ALPHAFOX_POWERSHELL?.trim() || "powershell.exe";
+}
+function scriptPath() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), "alphafox-cli");
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const path = (0, node_path_1.join)(dir, "windows-cred.ps1");
+    (0, node_fs_1.writeFileSync)(path, exports.WINDOWS_CRED_PS1, { encoding: "utf8" });
+    return path;
+}
+function runCred(action, target, env, input) {
+    const result = (0, node_child_process_1.execFileSync)(windowsPowershellBin(env), [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        scriptPath(),
+        action,
+        target,
+    ], {
+        input: input ?? "",
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 15_000,
+        windowsHide: true,
+        env: { ...process.env, ...env },
+    });
+    return typeof result === "string" ? result : String(result);
+}
+function windowsCredentialWrite(profile, payload, env = process.env) {
+    if (Buffer.byteLength(payload, "utf8") > exports.WINDOWS_CRED_MAX_BYTES) {
+        return false;
+    }
+    try {
+        runCred("write", windowsCredentialTarget(profile), env, payload);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function windowsCredentialRead(profile, env = process.env) {
+    try {
+        const out = runCred("read", windowsCredentialTarget(profile), env);
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+function windowsCredentialDelete(profile, env = process.env) {
+    try {
+        runCred("delete", windowsCredentialTarget(profile), env);
+    }
+    catch {
+        // none
+    }
+}
+function windowsCredentialAvailable(env = process.env) {
+    try {
+        (0, node_child_process_1.execFileSync)(windowsPowershellBin(env), ["-NoProfile", "-Command", "exit 0"], {
+            stdio: "ignore",
+            timeout: 5_000,
+            windowsHide: true,
+            env: { ...process.env, ...env },
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/safety/confirmation.d.ts

@@ -1,4 +1,4 @@
-export type RiskLevel = "read" | "write" | "high-risk-write";
+export type RiskLevel = "read" | "write" | "high-risk-write" | "unknown";
 export interface ConfirmationGateResult {
     readonly allowed: boolean;
     readonly error?: {
@@ -6,12 +6,19 @@ export interface ConfirmationGateResult {
         readonly subtype: "confirmation_required";
         readonly message: string;
         readonly hint: string;
-        readonly risk: "high-risk-write";
+        readonly risk: "high-risk-write" | "unknown";
         readonly action: string;
     };
 }
 /**
- * High-risk writes require explicit --yes (or equivalent confirmation token).
+ * Infer risk for raw `api METHOD PATH` calls.
+ * Catalog-matched risks win; uncataloged mutations are treated as high-risk
+ * so they cannot skip the `--yes` gate.
+ */
+export declare function inferRawApiRisk(method: string, catalogRisk: string | undefined): RiskLevel | string;
+export declare function requiresHighRiskConfirmation(risk: RiskLevel | string): boolean;
+/**
+ * High-risk writes (and uncataloged/unknown mutations) require explicit --yes.
  * Server still enforces scopes/roles; this is CLI UX only.
  */
 export declare function assertHighRiskConfirmation(input: {

package/dist/safety/confirmation.js

@@ -1,12 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferRawApiRisk = inferRawApiRisk;
+exports.requiresHighRiskConfirmation = requiresHighRiskConfirmation;
 exports.assertHighRiskConfirmation = assertHighRiskConfirmation;
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 /**
- * High-risk writes require explicit --yes (or equivalent confirmation token).
+ * Infer risk for raw `api METHOD PATH` calls.
+ * Catalog-matched risks win; uncataloged mutations are treated as high-risk
+ * so they cannot skip the `--yes` gate.
+ */
+function inferRawApiRisk(method, catalogRisk) {
+    if (catalogRisk) {
+        return catalogRisk;
+    }
+    if (MUTATING_METHODS.has(method.toUpperCase())) {
+        return "unknown";
+    }
+    return "read";
+}
+function requiresHighRiskConfirmation(risk) {
+    return risk === "high-risk-write" || risk === "unknown";
+}
+/**
+ * High-risk writes (and uncataloged/unknown mutations) require explicit --yes.
  * Server still enforces scopes/roles; this is CLI UX only.
  */
 function assertHighRiskConfirmation(input) {
-    if (input.risk !== "high-risk-write") {
+    if (!requiresHighRiskConfirmation(input.risk)) {
         return { allowed: true };
     }
     if (input.dryRun) {
@@ -15,14 +35,17 @@ function assertHighRiskConfirmation(input) {
     if (input.yes) {
         return { allowed: true };
     }
+    const unknown = input.risk === "unknown";
     return {
         allowed: false,
         error: {
             type: "confirmation",
             subtype: "confirmation_required",
             message: `${input.action} requires confirmation`,
-            hint: "add --yes to confirm",
-            risk: "high-risk-write",
+            hint: unknown
+                ? "uncataloged mutation treated as high-risk; add --yes to confirm"
+                : "add --yes to confirm",
+            risk: unknown ? "unknown" : "high-risk-write",
             action: input.action,
         },
     };

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 export declare const CLI_NAME = "alphafox";
 export declare const CLI_PACKAGE = "@alphafox/cli";
-export declare const CLI_VERSION = "0.1.5";
-export declare const CLI_CONTRACT_VERSION = "2026-08-11";
+export declare const CLI_VERSION = "0.3.2";
+export { CATALOG_VERSION as CLI_CONTRACT_VERSION } from "./catalog/operations";

package/dist/version.js

@@ -3,5 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLI_CONTRACT_VERSION = exports.CLI_VERSION = exports.CLI_PACKAGE = exports.CLI_NAME = void 0;
 exports.CLI_NAME = "alphafox";
 exports.CLI_PACKAGE = "@alphafox/cli";
-exports.CLI_VERSION = "0.1.5";
-exports.CLI_CONTRACT_VERSION = "2026-08-11";
+exports.CLI_VERSION = "0.3.2";
+var operations_1 = require("./catalog/operations");
+Object.defineProperty(exports, "CLI_CONTRACT_VERSION", { enumerable: true, get: function () { return operations_1.CATALOG_VERSION; } });

package/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,156 @@
+# Issue tracker: Feishu Tasks
+
+Issues and specs for this repo live as tasks in the **Alphafox-Issues** Feishu (Lark) tasklist. Use the `lark-cli` CLI ([`@larksuite/cli`](https://github.com/larksuite/cli)) for all operations, always with `--as user` — a task created by the bot identity is invisible in the human's task centre.
+
+List: <https://applink.feishu.cn/client/todo/task_list?guid=6d628d79-cdfe-47cc-98f7-35561944494b>
+
+## Identifiers
+
+An issue's identity is its **task GUID** — a UUID. There is no usable short number: the `t101420`-style id the Feishu UI shows (`task_id`, `suite_entity_num`) is **display-only** and every API rejects it, so a bare `#42` or `t101420` cannot be looked up directly.
+
+- Prefer the task **URL** (`https://applink.feishu.cn/client/todo/detail?guid=<GUID>`) — the GUID is the `guid` query param. Every write command below also accepts the URL in place of the GUID.
+- Given only a `t1014xx` number or a title fragment, resolve it with `lark-cli task +search --query "<title words>" --as user` and match on `summary`. Search spans **all** the user's tasks, not just this tasklist, so confirm the match before writing.
+- When narrating to the human, refer to an issue by its **title**, not its GUID.
+
+## Setup values
+
+- **Tasklist GUID**: `6d628d79-cdfe-47cc-98f7-35561944494b`
+- **`Type` field GUID**: `227d69e7-e535-40f0-b64f-4e90247149e2`
+
+Triage roles are **sections** — a task sits in exactly one, so the state machine can't be violated. `待分类` is the default section, so anything created without a section lands there as untriaged.
+
+| Canonical role | Section | Section GUID |
+| -------------- | ------- | ------------ |
+| _(untriaged)_ | `待分类` (default) | `4ca8fd68-9a08-5794-1598-8e5a394e8638` |
+| `needs-triage` | `待评估` | `44e58692-1ced-462b-99bb-bf082a745ef3` |
+| `needs-info` | `待补充信息` | `0cff4cf9-00b9-42bd-b482-5cd06a51b99b` |
+| `ready-for-agent` | `可交给 Agent` | `1ce586d5-7953-4d68-b41a-d4b2851f5806` |
+| `ready-for-human` | `需人工处理` | `8713387c-e758-4730-9de8-0b30859674ff` |
+| `wontfix` | `不予处理` | `00d4b874-1a4a-43d8-b0cf-fcb52460f9bf` |
+| _(wayfinder — outside the triage queue)_ | `探路图` | `bab88abf-0bf9-407d-806b-680901a86dd7` |
+
+Every other label is an option on the single-select `Type` field. Address an option by its GUID, never by name — the skills' canonical labels use a colon (`wayfinder:map`) while the Feishu options are named with a hyphen (`wayfinder-map`), so this table is the only mapping between them:
+
+| Label | Option GUID |
+| ----- | ----------- |
+| `bug` | `0eb51704-bead-4e8e-93be-dd8d02c1d20c` |
+| `enhancement` | `ebd05bc8-ab6c-4a56-8628-6c3284d9f1f9` |
+| `spec` | `399a640f-5d51-4dab-a4f3-da3df638ec8a` |
+| `ticket` | `3bb7ca44-ac8c-4b75-8925-96fc457fb974` |
+| `wayfinder:map` | `8cd13987-010e-46f0-808f-a8f289791cf5` |
+| `wayfinder:research` | `f18b808a-d978-41cb-9bef-cd0708fecf0c` |
+| `wayfinder:prototype` | `49126969-48dc-4297-96d4-36d176ffb8bb` |
+| `wayfinder:grilling` | `265feb46-9ac8-4c03-afa8-9400296defe4` |
+| `wayfinder:task` | `ed48b848-01d0-406b-ac7d-a96ce66cee0d` |
+
+## Conventions
+
+- **Shared-list title** — prefix every issue/task title with `[alphafox-cli]` so the repository remains identifiable on the shared board.
+- **Tracker boundary** — Matt Skills issues, specs, tickets, triage items, and wayfinder maps belong in `Alphafox-Issues`, not a quarterly execution list. If quarterly planning initiated the work, link its absolute Feishu task URL instead of duplicating workflow state.
+
+- **Create an issue** — one call sets body, section (triage role) and `Type`:
+
+  ```bash
+  lark-cli task tasks create --as user --params '{"user_id_type":"open_id"}' --data '{
+    "summary": "<title>",
+    "description": "<body>",
+    "tasklists": [{"tasklist_guid": "6d628d79-cdfe-47cc-98f7-35561944494b", "section_guid": "<SECTION_GUID>"}],
+    "custom_fields": [{"guid": "227d69e7-e535-40f0-b64f-4e90247149e2", "single_select_value": "<OPTION_GUID>"}]
+  }'
+  ```
+
+  For an untriaged issue with no label, `lark-cli task +create --tasklist-id 6d628d79-cdfe-47cc-98f7-35561944494b --summary "..." --description "..." --as user` is enough — it lands in `待分类`.
+
+- **Read an issue** — the body and the comments are two calls:
+
+  ```bash
+  lark-cli task tasks get --as user --params '{"task_guid": "<GUID>", "user_id_type": "open_id"}'
+  lark-cli api GET /open-apis/task/v2/comments --as user \
+    --params '{"resource_type": "task", "resource_id": "<GUID>", "page_size": 50, "user_id_type": "open_id"}'
+  ```
+
+  `tasks get` returns `description` (the body), `custom_fields` (the `Type` label), `tasklists[].section_guid` (the triage role), `members` (assignees), `status` (`todo`/`done`), `dependencies` (blockers) and `parent_task_guid`. Comments are **not** exposed by `lark-cli task`; the raw `api` call above is the only way to read them.
+
+- **List a triage bucket** — one call per section, and this is the cheap path:
+
+  ```bash
+  lark-cli task sections tasks --as user --params '{"section_guid": "<SECTION_GUID>", "completed": false, "page_size": 100}'
+  ```
+
+  Returns a brief per task — `guid`, `summary`, `completed_at`, `subtask_count` — which is all a queue listing needs. Pass `created_from`/`created_to` to window by age; results come oldest-first. Reading a task's `Type` or assignees means a `tasks get` per task, so don't do it while building a queue listing.
+
+- **List every issue**: `lark-cli task tasklists tasks --as user --params '{"tasklist_guid": "6d628d79-cdfe-47cc-98f7-35561944494b", "completed": false, "page_size": 100}'`.
+
+- **Comment on an issue**: `lark-cli task +comment --task-id <GUID> --content "..." --as user`. Plain text — Feishu renders no markdown in comments, so keep formatting light.
+
+- **Apply a triage role** — move the task to that role's section. Re-adding an existing task with a new `--section-guid` moves it; there is no separate "remove from old section" step:
+
+  ```bash
+  lark-cli task +tasklist-task-add --tasklist-id 6d628d79-cdfe-47cc-98f7-35561944494b --task-id <GUID> --section-guid <SECTION_GUID> --as user
+  ```
+
+- **Apply a `Type` label** — patch the custom field. This replaces the previous value, since the field is single-select:
+
+  ```bash
+  lark-cli task tasks patch --as user --params '{"task_guid": "<GUID>"}' --data '{
+    "task": {"custom_fields": [{"guid": "227d69e7-e535-40f0-b64f-4e90247149e2", "single_select_value": "<OPTION_GUID>"}]},
+    "update_fields": ["custom_fields"]
+  }'
+  ```
+
+- **Edit the body**: same shape, with `{"task": {"description": "..."}, "update_fields": ["description"]}`. A patch **replaces** the description, so read it first and re-send the whole text.
+
+- **Every markdown link in a body needs a real absolute URL.** Feishu parses `[text](target)` in `description` and validates the target, rejecting the entire write with `Invalid Param 'description', url in description is invalid` when it isn't one. A placeholder `(link)`, an empty `()`, and a repo-relative `(./src/foo.ts)` all fail. Link to an absolute `https://` URL, or drop the link syntax and name the thing in plain text. Headings, lists, bold, bare URLs and task GUIDs are all fine.
+
+- **Close**: `lark-cli task +complete --task-id <GUID> --as user`. It takes no closing comment, so post the explanation with `+comment` first, then complete. Reopen with `lark-cli task +reopen --task-id <GUID> --as user`.
+
+- **Assign**: `lark-cli task +assign --task-id <GUID> --add <open_id> --as user` (`--remove` to unassign). Get your own `open_id` from `lark-cli auth status --jq '.identities.user.openId'`.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+Feishu Tasks holds no code, so PRs live on the GitHub remote. When this flag is `yes`, triage reads a PR and its diff with `gh pr view` / `gh pr list` / `gh pr diff` while the roles and states stay here in the tasklist: a PR under triage gets a task in this list whose body links the PR. Numbering never collides, because a task GUID and a `#42` are different shapes.
+
+## When a skill says "publish to the issue tracker"
+
+Create a task in this tasklist. Put the whole document in `description`, set `Type`, and place it in the section matching its triage role.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `tasks get` for the body plus the raw `comments` call for the history — an agent brief or a resolution lives in one or the other.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a task; its tickets are **subtasks** of it.
+
+- **Map**: a task with `Type` = `wayfinder:map`, in `探路图`, holding the Destination / Notes / Decisions-so-far / Fog body in `description`.
+- **Child ticket**: create the task, then parent it — `lark-cli task +set-ancestor --task-id <CHILD_GUID> --ancestor-id <MAP_GUID> --as user`. Parenting **keeps** the child's tasklist and section membership, so tickets stay visible in `探路图`. Label each with `Type` = `wayfinder:<type>`.
+- **Blocking**: Feishu's **native task dependencies** — the canonical, UI-visible representation. `type: "prev"` means "blocks this task", so a child blocked by another records the blocker as `prev`:
+
+  ```bash
+  lark-cli api POST /open-apis/task/v2/tasks/<CHILD_GUID>/add_dependencies --as user \
+    --data '{"dependencies": [{"task_guid": "<BLOCKER_GUID>", "type": "prev"}]}'
+  ```
+
+  The reciprocal `next` edge appears on the blocker automatically. Drop an edge with `--data '{"dependencies": [{"task_guid": "<BLOCKER_GUID>"}]}'` against `.../remove_dependencies`. Dependencies are **not** settable through `tasks create` or `tasks patch` — the raw `api` call is the only route, so tickets must exist before they can be wired, which is why charting creates first and wires second.
+
+- **Frontier query** — one call, because `subtasks list` returns *full* task objects rather than briefs:
+
+  ```bash
+  lark-cli task subtasks list --as user --params '{"task_guid": "<MAP_GUID>", "page_size": 100, "user_id_type": "open_id"}'
+  ```
+
+  Each child carries `status`, `members`, `dependencies` and `description`. Filter locally: keep `status` of `todo`, drop any with a `members` entry whose `role` is `assignee` (claimed), and drop any whose `prev` dependencies include a task still `todo` (blocked). Blockers that are siblings on the same map are already in this response; resolve any others with `tasks get`. First in map order wins.
+
+- **Claim**: `lark-cli task +assign --task-id <GUID> --add <your open_id> --as user` — the session's first write.
+- **Resolve**: `+comment` with the answer, then `+complete`, then patch the map's `description` to append a context pointer to Decisions-so-far. That pointer's link must be the ticket's full applink URL — a Decisions-so-far line written as `[title](link)` is rejected by the description's URL validation, taking the whole map update with it.
+
+## Re-reading the setup values
+
+```bash
+lark-cli task sections list --as user --params '{"resource_type": "tasklist", "resource_id": "6d628d79-cdfe-47cc-98f7-35561944494b", "page_size": 50}'
+lark-cli task custom_fields list --as user --params '{"resource_type": "tasklist", "resource_id": "6d628d79-cdfe-47cc-98f7-35561944494b", "page_size": 50}'
+```
+
+`custom_fields list` returns each option's `guid` alongside its `name`, which is what the `Type` table above records.