@alphafox/cli 0.1.5 → 0.2.0

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.2.0";
+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.2.0";
+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.

package/docs/agents/triage-labels.md

@@ -0,0 +1,18 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. On this repo's tracker (Feishu Tasks) a role is not a label but a **section** of the Alphafox-Issues tasklist — a task sits in exactly one, so the state machine can't be violated. `issue-tracker.md` holds the section GUIDs and the command that moves a task between them.
+
+| Label in mattpocock/skills | Section in our tracker | Meaning                                  |
+| -------------------------- | ---------------------- | ---------------------------------------- |
+| _(no label yet)_           | `待分类`               | Never triaged — the default section       |
+| `needs-triage`             | `待评估`               | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `待补充信息`           | Waiting on reporter for more information |
+| `ready-for-agent`          | `可交给 Agent`         | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `需人工处理`           | Requires human implementation            |
+| `wontfix`                  | `不予处理`             | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), move the task to the corresponding section from this table.
+
+The remaining labels — the `bug` / `enhancement` categories and wayfinder's `wayfinder:<type>` — are **not** sections. They are options on the single-select `Type` field, because they coexist with a triage role rather than replacing it. `issue-tracker.md` holds their option GUIDs.
+
+Editing the right-hand column here is not enough on its own: rename a section in Feishu and its GUID stays the same, so update this table and leave `issue-tracker.md`'s GUIDs alone. Adding or removing a section is the case that changes GUIDs, and then both files need re-syncing.

package/docs/e2e-staging.md

@@ -1,5 +1,9 @@
 # Staging E2E checklist (t101364 / t101369)
 
+Run only against the stable public facade `https://staging.alphafox.app`. Do not use Preview URLs, internal service tokens, or production.
+
+Staging CLI issuer: `https://staging.alphafox.app`. Test login (staging-only, gated on `ALPHAFOX_DEPLOY_ENV=staging`): `test@local.com` / `localtest`. Device Flow approve without a human click: `node scripts/e2e-staging-device-approve.mjs --user-code <code>`. Isolate credentials with `ALPHAFOX_CONFIG_DIR` and `ALPHAFOX_FORCE_FILE_KEYCHAIN=1`.
+
 ## Scenarios
 
 1. Install CLI → `version` / `doctor`
@@ -12,13 +16,79 @@
 8. Logout / revoke
 9. Cross-env token rejection (prod token on staging)
 
-## Evidence policy
+## Evidence (2026-08-13) — vertical slice pass
+
+Anonymous `GET https://staging.alphafox.app/api/v1/meta` → **HTTP 200**, `environment=staging`, `contractVersion=2026-08-13`, `commitSha=65d1f816007adc7acc09db5e86671931737e0379`, `x-request-id=66511bcf-dda9-4974-9378-3aacd8d938ff`. No 302 to `vercel.com/sso-api`. Vercel Authentication is disabled for the whole `alphafox-web` project (Preview `*.vercel.app` is also public; accepted).
+
+CLI used: local `alphafox-cli` `fd04570747b1096b57a5a12ef20994b6c79531d7` (`dist/cli.js --profile staging --format json --no-input`). Config dir `/tmp/alphafox-e2e-staging`.
+
+| Step | Result | Evidence |
+|------|--------|----------|
+| 1. `version` | pass | `contractsSha` matches freeze `5a4f9c0175951a6bedc52640fe917abe992ec824` |
+| 1. `doctor` | pass | `apiBaseUrl` / issuer `https://staging.alphafox.app` |
+| 2. password sign-in | pass | HTTP 200, session cookie, `userId=019f3073-307f-76e9-adf1-0203af9ab22b` |
+| 2. Device Flow `--no-wait` | pass | `user_code` issued; verification `https://staging.alphafox.app/cli/device` |
+| 2. device approve helper | pass | HTTP 200, `requestId=821fa89f-04c9-490a-8e45-88f83a7e69e6` |
+| 2. `auth login --device-code` | pass | authenticated, `requestId=a90ef882-c341-4af5-b68c-f27b2a280bfd` |
+| 3. `whoami` | pass | same `userId`, `requestId=8202f6b0-517d-44fa-acf3-0e19c39db7c7` |
+| 3. `auth status --verify` | pass | `verified: true`, issuer/audience/clientId staging |
+| 4. `GET /api/v1/trading/strategy-definitions` | pass | HTTP 200 via CLI, `requestId=22afdb63-d8cf-4512-a6b7-326f97a876a9` |
+| 4. `GET /api/v1/exchange-connectors` | pass | HTTP 200, `requestId=1284cfe7-a06a-4f30-bac1-6322eaf05e1b` |
+| 4. `GET /api/v1/trading/traders` | pass | HTTP 200, `requestId=c09ced70-d704-4b78-bc72-96a7048d4c7a` |
+| 7. high-risk without `--yes` | pass | `api POST /api/v1/trading/traders/{id}/start` → **exit 10**, `confirmation_required` (no HTTP call) |
+| Rate limit | pass (live) | 80 sequential `POST /api/auth/oauth/device/code` → first **HTTP 429** at request 72, `x-request-id=e585251a-2768-4cfc-aab6-77da1ae20570`, `Retry-After: 43`. Limit is 10/min **per serverless instance**; cross-instance windows do not share memory. Feishu alert is debounce 10 min/key via `ALPHAFOX_OPS_FEISHU_WEBHOOK_URL`. |
+
+Login UI on the website is still OTP/passwordless. E2E used API password + the approve helper. Remaining human click if someone uses the browser `/cli/device` page: they must already have a web session (OTP unless they hit the sign-in API).
+
+Web PR: https://github.com/alphafoxai/alphafox-web/pull/448 (head `65d1f816`). Do not enable production OAuth client or npm `latest` from this evidence.
+
+## Evidence (2026-08-13) — leftover checklist (5 / 6 / 8 / 9)
+
+Reused staging Device Flow session `userId=019f3073-307f-76e9-adf1-0203af9ab22b` (`whoami` `requestId=51222050-1226-4d2f-92d2-96059778fb36`). Anonymous `GET /api/v1/meta` still **HTTP 200**, `commitSha=65d1f816007adc7acc09db5e86671931737e0379`, `x-request-id=d0f964ef-1f5a-4271-ad6e-0cf0f57b6ae2`. CLI: local `alphafox-cli` `1db8f416` (`--profile staging --format json --no-input`). Staging is **not** MVP in-process stubs (`ALPHAFOX_PUBLIC_API_USE_MVP_HANDLERS` unset); product handlers go through the BFF / llm-gateway / trader.
+
+| Step | Result | Evidence |
+|------|--------|----------|
+| 5. `POST /api/v1/chats` create | **pass** | HTTP **201**, `{chatId}`, `x-matched-path=/api/v1/chats`. Raw: `chatId=7fb9b5ce-f4c2-47e1-a8f6-804bcbfadedb`, `x-request-id=6a091c9b-e08d-4bb6-9e05-9e66e124f073`. CLI: `chatId=ce72df27-b207-49cd-a99a-d6d692e4e725`, `requestId=ea3f253d-3050-4060-9296-e56687c71313` |
+| 5. same `Idempotency-Key` replay | **fail** | Expected HTTP 200 + same `chatId` / `replayed=true`. Got a **second HTTP 201** with a **new** chat. Raw replay `chatId=be5664ad-5fc8-4288-9a29-f865ec554dd6`, `x-request-id=ab54ca06-1b59-4b4c-89f2-4909204b8813`. CLI replay `chatId=d880e9e5-ae39-46c2-8719-6546f637575b`, `requestId=3fed3750-6564-45c9-94cf-89b6ac8634b4`. BFF `/api/chats` does not honor `Idempotency-Key` |
+| 6. `POST /api/v1/backtests` `{}` | **fail** | HTTP **400** `chatId is required`, `x-request-id=946c02c7-1ce8-4ef9-9405-9cd407af3ace` |
+| 6. `POST /api/v1/backtests` contract `{backtestSettings:{}}` | **fail** | HTTP **400** `unknown request keys: backtestSettings`, `x-request-id=49610211-7980-4726-97a1-47b87ee98bd5`. Facade BFF expects `{chatId, strategyId}`; contracts catalog wants `backtestSettings` |
+| 6. `POST /api/v1/backtests` `{chatId, strategyId:1}` | **fail** | HTTP **404** `JOB_NOT_FOUND` `strategy not found` (trader `POST /v2/backtests`), `x-request-id=5715eb82-0fe8-427b-86e2-bb1ce1bd6029`. New chat has no compiled strategy |
+| 6. get / stream / cancel (no live job) | **fail** (blocked by create) | Handlers are on the facade (not catch-all 404). Missing id `00000000-0000-0000-0000-000000000001`: GET **404** `JOB_NOT_FOUND` `x-request-id=406b0439-4c33-4f4c-b117-bac6787e7f59`; stream GET **404** `x-request-id=0e1f335b-2865-4fdf-ae5f-e5450514ad8a`; cancel POST **404** `x-request-id=8793823c-3ea8-405e-9c15-1eae47b4a4af`. Did **not** watch a live stream or cancel a created job |
+| 8. `POST /api/auth/oauth/revoke` | **pass** | HTTP **200** `{revoked:true}`, `x-request-id=f8dbc0da-1784-46ba-8180-0ad56225e253` |
+| 8. revoked AT on `GET /api/v1/me` | **pass** | HTTP **401** `unauthorized`, `x-request-id=992b12f5-f1b7-4750-ab7e-f162278be8e8` |
+| 8. `auth logout` | **pass** | `localCleared: true`, `remoteRevoke: ok`, `fullyLoggedOut: true`. Keychain file removed. Follow-up `whoami` HTTP **401**, `requestId=c52c8c33-d898-4471-b008-27b4d558664a`, CLI exit 77 |
+| 9. CLI prod-audience token → staging | **pass** | No HTTP. CLI **exit 77**, `subtype=cross_origin_token`, `status=403`: refuses to send tokens whose audience origin is `https://alphafox.app` to `https://staging.alphafox.app` |
+| 9. unknown / prod-shaped bearer on staging `/api/v1/me` | **pass** (fail-closed) | No production OAuth client (not enabled). Unknown opaque bearer HTTP **401** `x-request-id=c73deb73-8ae4-472f-9d19-ad0b930f04fe`. Forged JWT with `iss=https://alphafox.app/api/auth` HTTP **401** `x-request-id=cb92f0f7-05ab-4e25-9455-a770467d4a07`. Staging token table does not accept foreign tokens |
+
+### Leftover blockers (do not treat the full checklist as green)
+
+- **Idempotency:** `chats.create` on staging creates a real llm-gateway chat (201) but ignores `Idempotency-Key`.
+- **Backtest vertical slice:** cannot `create → stream → cancel` until a chat has an integer `strategyId`, and until the facade body matches contracts (`backtestSettings`) or the catalog is updated to `{chatId, strategyId}`.
+- Parent Feishu task and t101364 (production publish / npm `latest` / production OAuth) stay **todo**. Do not merge web PR 448 to production `main` from this evidence.
+
+## Evidence (2026-08-13) — gapfix retest (idempotency + backtests.create)
+
+Anonymous `GET https://staging.alphafox.app/api/v1/meta` → **HTTP 200**, `environment=staging`, `contractVersion=2026-08-13`, `commitSha=fba21ef4b2c3909c51a5a19e2d2a45b30d1d598c`, `x-request-id=8702a21b-a749-4007-82eb-76ca1dd0caaf`. No SSO redirect. Device Flow `test@local.com`: approve `requestId=77293035-ebfd-4b03-b0e1-0779dce81fdd`, token `requestId=9dcc28c1-c1cc-49fc-9435-687dfdb591c2`, `whoami` `userId=019f3073-307f-76e9-adf1-0203af9ab22b` `requestId=1473f107-d742-42eb-99e7-b60c6b583928`. CLI local `92c8610250b30e7881f79a2fde60b00fe50b4628`, catalog `contractsSha=d1f184e3d72581f155497978880d9ab3029ff858`. Staging llm-gateway image `0a10d8e3a1304b04eff2f21c503922a5b7c11491` (workflow `31683345740` failed after the container was healthy: `/opt/alphafox/images/alphafox-llm-gateway.env` permission denied). Do not merge web PR 448 to production `main`.
+
+| Step | Result | Evidence |
+|------|--------|----------|
+| 5. `POST /api/v1/chats` create | **pass** | HTTP **201** `chatId=8d1a569a-e19e-44f6-84e3-4f5f28f8e1e6`, `x-request-id=6cfe0cdc-db13-455b-87a7-7ddcc56aa30f`. CLI create `chatId=6ca09650-b259-4343-95fb-dc5891dd81a4`, `requestId=d647b1aa-2a07-4d42-80bc-b88384f6c8b5` |
+| 5. same `Idempotency-Key` replay | **pass** | HTTP **200** same `chatId=8d1a569a-e19e-44f6-84e3-4f5f28f8e1e6`, `x-request-id=eaea63ac-07ff-49b9-b049-ff8c402a8fb6`. CLI replay same `chatId=6ca09650-b259-4343-95fb-dc5891dd81a4`, `requestId=3e9d6246-3f6c-4be3-a804-1de5d8abf772`. Same key + different title → HTTP **409** `IDEMPOTENCY_CONFLICT`, `x-request-id=f18d8aaf-16b2-4784-a42e-b2a088a586d3` |
+| 6. `POST /api/v1/backtests` `{}` | **pass** (honest 400) | HTTP **400** `chatId is required`, `code=validation_error`, `x-request-id=811c9938-337e-4364-85c6-1a5e34f8427f`. CLI `requestId=2bd9e4c8-c33c-4123-84fa-ff999c1a2bed` |
+| 6. `POST /api/v1/backtests` `{backtestSettings:{}}` | **pass** (honest 400) | HTTP **400** `chatId is required` (no longer `unknown request keys: backtestSettings`), `x-request-id=6ee3856f-73da-4888-b23d-f3981f8bec22`. CLI `requestId=1b26087b-73ea-4422-98d8-9050a403322e` |
+| 6. `POST /api/v1/backtests` `{chatId, strategyId:1}` on empty chat | **pass** (honest 404) | HTTP **404** `STRATEGY_NOT_FOUND` (not `JOB_NOT_FOUND`), `x-request-id=1c58acd7-ed0f-40d3-9d71-618adbf634b5`, chat `88497dc2-1f86-4edc-ae08-f11e8ded57f8` |
+| 6. `POST /api/v1/backtests` `{chatId}` omit strategyId | **pass** (honest 422) | HTTP **422** `CHAT_HAS_NO_COMPILED_STRATEGY`, `x-request-id=011c1b47-df76-4a5e-b045-799666eac304`. CLI `requestId=16e44bcc-8780-4146-8f72-8383bc415e07` |
+| 6. create → stream → cancel (live job) | **fail** (blocked) | `test@local.com` has no compiled `strategyId`. Chat stream `x-request-id=2e26667b-0cfd-4bfe-9a75-25971120f1ab` ended `finishReason=tool-calls` (`modifyBacktestSettings`) without `save_strategy`. Follow-up create still **422** `x-request-id=37198479-fbd1-462f-8d5a-3a0d1d8f49bb` |
 
-If staging domain/secrets are unavailable in the runner, capture provisioning failure to evidence logs and rely on:
+### Remaining blockers after this retest
 
-- local unit/integration tests of envelope, allowlist, token model, confirmation
-- structural presence of deploy workflow + runbooks
+- Live `backtests.create` → GET stream → POST cancel still needs a chat with a compiled `strategyId`. Generating one is the multi-step chat tool loop, not this facade fix.
+- llm-gateway staging deploy workflow `31683345740` is red on a post-start file permission; the new image is serving (replay evidence above). Do not merge gateway `feat/chats-create-idempotency` to `main`.
+- Parent Feishu task and t101364 stay **todo**. Do not enable production OAuth or npm `latest`.
 
-**Never fabricate staging success.**
+## Policy
 
-Parent Feishu task stays `todo` until human acceptance of staging evidence.
+- Capture the real HTTP status, redirect, and request-id. Never fabricate staging success.
+- External dependency outage → fail the test. No mock success, no silent skip.
+- Parent Feishu task stays `todo` until production publish / OAuth latest is accepted.
+- Do not enable production OAuth client or npm latest from a staging-only pass.