wicked-crew-api-types 0.186.0 → 0.191.0

package/index.d.ts

@@ -259,6 +259,12 @@ export interface HealthCapabilities {
    * send the field (its strict launch schema 400s on it) and do not call the preview.
    */
   linkedIssuesExclude?: boolean;
+  /**
+   * (api-types 0.187.0, DES-PM-001 PM-1) This daemon serves project-management sources: the `pm` registration field,
+   * the human-only `/tracker-links` routes (and `/tracker-links/issues`), `GET /sources/:name/trackers`, the tracker
+   * set in linked issues (`LinkedIssuesPreviewBody.projectId`), and `/runs/:id/tracker-actions`. Absent = none of it.
+   */
+  trackerLinks?: boolean;
   /**
    * Repo-bound runs get an EVIDENCE ROOT for walkthroughs (WT-W1, api-types 0.74.0): the engine
    * addon takes `LaunchOptions.evidenceRoot` (wicked-core-ts ≥ 0.7.35), so a walkthrough step on a
@@ -353,6 +359,13 @@ export interface HealthCapabilities {
    * ABSENT on an older daemon: read as `false` and hide the switch.
    */
   powerMode?: boolean | undefined;
+  /**
+   * (api-types 0.188.0, crew#1139) A `plan_approval` approval carries the operator's note: `GateDecision.amend`
+   * on `{approve: true}` or `{approve: true, plan}` at a plan gate lands on the first creator step the plan
+   * releases (else its first step) as `unitReworkAmended`. ABSENT or `false` (an engine without it refuses the
+   * note): offer no note field on the plan card.
+   */
+  planGateNote?: boolean | undefined;
   /**
    * (api-types 0.156.0, DES-VOICE) Voice mode's routes are served: `GET /voice/status`, `POST|DELETE /voice/model`,
    * `POST /voice/transcribe` and `GET|PUT /voice/dashboard`. Whether transcription can run NOW (the engine and
@@ -2456,6 +2469,18 @@ export interface GateDecision {
      *  `operator_judgment` then applies). Refused (409, gate left open) at every other gate and on a
      *  run that does not require QE acceptance. Engine: wicked-core-ts after 0.16.3. */
     | 'skip_qe'
+    /** (api-types 0.190.0, DES-RULE-CHECK-001 S2) At a `rules_unchecked` gate (a steering rule no
+     *  judge ruled on), with `approve: true` and no `amend` / `amendScope` / `plan`: RE-RUN THE RULE
+     *  CHECK on the same work (the step's seat does not run again; every verdict whose rule and
+     *  evidence are unchanged is reused). The engine refuses it at any other gate (409). */
+    | 'retry_rules'
+    /** (api-types 0.190.0) SKIP UNCHECKED STEERING RULES, each with the person's written reason in
+     *  {@link GateDecision.skipRules} (required), `approve: true`, no `amend` / `amendScope` / `plan`;
+     *  then the check re-runs. A skipped rule's row is `skipped`, labelled with its reason on the
+     *  gate receipt and the delivery. Only a rule the gate holds as `unchecked` can be skipped (a
+     *  `broken` one denies); the human operator's call alone (a seat or standing order: 403
+     *  `human_operator_only`). Refused (409, gate left open) at any other gate. */
+    | 'skip_rules'
     /** (core#820) A `consent` gate's choice from its dry-run plan (`awaitingHuman.choices`), with
      *  `approve: true`: `consent:worker` (the default), `consent:operator`, …; `reject` declines. */
     | `consent:${string}`;
@@ -2464,7 +2489,8 @@ export interface GateDecision {
    * Absent = `'cursor'` (today: the gated unit's description). `'creator'` — the first creator
    * phase at or after the cursor receives it (`unitReworkAmended{scope: 'creator'}`) while the
    * cursor dispatches unamended: the intake steer that must reach the fix phase, not triage.
-   * Identical text already present on the target is not appended twice.
+   * Identical text already present on the target is not appended twice. At a `plan_approval` gate
+   * it does not apply (api-types 0.188.0): the note lands as {@link GateDecision.plan} says.
    */
   amendScope?: 'cursor' | 'creator';
   /**
@@ -2473,8 +2499,16 @@ export interface GateDecision {
    * `plan.proposed{by:"human", kind:"edit"}`, floor-fills it (phases below the floor are ADDED,
    * never refused) and accepts it as the next `plan_rev` — or refuses it (`plan.refused`) and
    * re-opens the gate under a new `gate_id`, answering `awaiting_human`. Requires `approve: true`
-   * and `action` omitted or `'edit_plan'`; `amend` / `amendScope` do not apply. A plain approve
-   * (no `plan`) releases the held plan as it is; `approve: false` rejects (cancels).
+   * and `action` omitted or `'edit_plan'`; no `amendScope` (a 400). A plain approve (no `plan`)
+   * releases the held plan as it is; `approve: false` rejects (cancels).
+   *
+   * THE OPERATOR'S NOTE (api-types 0.188.0, crew#1139; {@link HealthCapabilities.planGateNote}): `amend`
+   * on a plan gate's approve, with or without `plan`, is carried to the steps the plan releases. It lands
+   * once the answer applies (after an edit's re-plan, so on the edited plan's units) on the FIRST CREATOR
+   * step at or after the cursor (`unitReworkAmended{scope: 'creator'}`), else on the cursor step
+   * (`scope: 'cursor'`), and the gate's recorded answer carries it. A refused edit re-opens the gate and
+   * lands nothing. An engine without it answers 501 for a note beside `plan` and 409 for one on a plain
+   * approve, with the gate left open.
    */
   plan?: LaunchPlan;
   /**
@@ -2510,6 +2544,9 @@ export interface GateDecision {
    * draft, **409** `draft_changed` when an id is not in the draft as it reads now (the gate stays open).
    */
   keepRules?: string[];
+  /** (api-types 0.190.0) With `action: 'skip_rules'` (and only with it): each unchecked rule to
+   *  skip, with the person's written reason (both non-empty, no rule twice). */
+  skipRules?: RuleSkipAnswer[];
 }
 
 /**
@@ -3278,6 +3315,50 @@ export interface AssuranceReceipt {
    *  ABSENT when every judge was the run's own (the routine case) or on an older engine. A unit
    *  receipt carries at most one; a delivery receipt lists the run's. */
   judgeFallbacks?: JudgeFallback[];
+  /** (api-types 0.190.0, DES-RULE-CHECK-001 S2) Every steering rule in force and its verdict at this
+   *  gate (the review step's rule check), or, on a delivery receipt, the worst row per rule across
+   *  the run's gates. ABSENT when no rule check ran (not a review gate, no rule store, no change, an
+   *  older engine). Deny-dominates: a `broken` row denied the gate, an `unchecked` row held it. */
+  rules?: RuleVerdict[];
+}
+
+/** (api-types 0.190.0) A steering rule's verdict: `kept` · `broken` · `n_a` (not applicable) ·
+ *  `unchecked` (no judge ruled; holds the gate) · `skipped` (the operator skipped it, with a reason;
+ *  a confirmed waiver reads `waived by instruction (…), confirmed by <who>: <reason>`) · `waived`
+ *  (the person's own instruction conflicts with the rule: holds the gate until the person confirms
+ *  it with a reason through `skip_rules`; never kept, never skipped silently) · `deferred` (api-types
+ *  0.191.0: the rule's subject only exists at delivery, by recorded fact: obligations
+ *  `evidence:delivery` or `applies_to` naming only the deliver step; it does not hold review or QE,
+ *  and the deliver step's receipt carries its verdict on the pull request's text). */
+export type RuleVerdictStatus = 'kept' | 'broken' | 'n_a' | 'unchecked' | 'skipped' | 'waived' | 'deferred';
+/** How it was reached: `fact` (a recorded fact ruled it out) · `judge` (a seat distinct from the
+ *  creators ruled) · `machine` (an engine check, e.g. `check:test-fails-on-base`) · `cache` (an
+ *  earlier verdict on the same rule and evidence) · `operator` (skipped) · `none` (unchecked). */
+export type RuleVerdictHow = 'fact' | 'judge' | 'machine' | 'cache' | 'operator' | 'none';
+
+/** (api-types 0.190.0) One steering rule's row on an assurance receipt. */
+export interface RuleVerdict {
+  ruleId: string;
+  status: RuleVerdictStatus;
+  how: RuleVerdictHow;
+  /** Why, in words: the fact, the cite, the skip's reason (`skipped by <who>: <reason>`), or why nobody ruled. */
+  reason: string;
+  /** The evidence the judge or the machine check cited, when one ruled. */
+  cite?: string;
+  /** The seat that ruled. */
+  judge?: string;
+  /** SHA-256 of the rule's judged content (statement, criteria, obligations, facets). */
+  ruleKey: string;
+  /** SHA-256 of the evidence the verdict read; absent on a `fact` row. */
+  evidenceKey?: string;
+}
+
+/** (api-types 0.190.0) One skip in a `skip_rules` gate answer. */
+export interface RuleSkipAnswer {
+  /** The unchecked rule's id. */
+  id: string;
+  /** The person's written reason (labelled on the run, the gate and the delivery). */
+  reason: string;
 }
 
 /**
@@ -3604,7 +3685,10 @@ export interface GateEscalatedEvent {
    * (0.7.27) · `governance` · `same_seat_evaluator` (a `dead_seat` condition: the review ran on its
    * builder's seat — core-ts 0.7.46, EX-01) · `evaluator_error` · `judge_unavailable` (a
    * `judge_unavailable` condition; since core-ts 0.7.46 also a required judge with no distinct
-   * seat — EX-02). `""` (EMPTY) = a hook veto whose source identity was folded away
+   * seat — EX-02) · `rule_check` (a `rule_broken` condition: a steering rule the review's rule check
+   * found broken, api-types 0.190.0) · `rules_unchecked` (a `rules_unchecked` condition: a rule no
+   * judge ruled on, answered by `retry_rules` / `skip_rules`). `""` (EMPTY) = a hook veto whose
+   * source identity was folded away
    * (`actor.rs` `boundary_deny` arm with no structured denial) — a reader keys copy on
    * `(condition, denialSource)` and treats `""` beside `boundary_deny` as input governance.
    */
@@ -6034,6 +6118,11 @@ export interface LinkedIssuesPreviewBody {
   problem: string;
   repoRef?: string;
   excludeLinkedIssues?: string[];
+  /**
+   * (api-types 0.187.0, DES-PM-001 §3.2) The project the launch is filed in: with a registered PM source, a
+   * reference resolves only through the tracker set of this project and `repoRef`.
+   */
+  projectId?: string;
 }
 
 /** The `POST /linked-issues/preview` 200 body: the same reading `POST /runs` does, nothing launched. */
@@ -6064,6 +6153,23 @@ export interface LinkedIssue {
   chars?: number;
   /** (crew#825; additive) `true` when the launch left this ref out (`excludeLinkedIssues`). */
   excluded?: true;
+  /**
+   * (api-types 0.187.0, DES-PM-001 §3.2, Q-PM5) Read through a registered PM source: the tracker that admitted it,
+   * that source's registry name, and its system. Absent on the daemon's `gh` path (no GitHub source registered).
+   */
+  trackerId?: string;
+  source?: string;
+  system?: PmSystem;
+  /**
+   * (api-types 0.187.0) Why it was not read, as a code: `not_linked` (no tracker of the run's project or repos has
+   * it), `ambiguous` (two trackers in the set share the key: pick one, which writes `<source>:<KEY-N>`), `hidden`
+   * (the source's Agents switches keep this project out), `query_off`, `unavailable` (the vendor could not be
+   * read), `not_found`. To pick among `ambiguous` candidates, write `<source>:<KEY-N>` (two sources) or
+   * `<source>@<tenant>:<KEY-N>` (two sites behind one source).
+   */
+  code?: 'not_linked' | 'ambiguous' | 'hidden' | 'query_off' | 'unavailable' | 'not_found';
+  /** (api-types 0.187.0) `ambiguous` only: the trackers that share the key, for the composer to pick from. */
+  candidates?: Array<{ source: string; tenant: string; tenantLabel?: string; key: string; trackerId: string }>;
 }
 
 /** The `POST /runs` 201 body. `linkedIssues` (crew#627, additive) is present when the intent of a
@@ -7392,6 +7498,10 @@ export interface WorkflowCatalogInput {
  * How a client starts an entry: `run` = `POST /runs {workflow}`; `demo` = `POST /projects/:id/demo`;
  * `compose` = `POST /projects/:id/product/compose` (draft epics); `document` = a new interactive document
  * of that style (its draft run); `chat` = a chat on its own page; `none` = nothing to launch (coming soon).
+ * (api-types 0.187.0, additive) `app` = a new app by chat: `POST /apps` in the project, then the words as its
+ * first turn, `POST /apps/:app/turns` (DES-APPS-001 §6.2); offered only where `GET /health.capabilities.apps.turns`
+ * is true; `repo` = register a repository, which onboards it (`POST /repos`; studio's Add a repository). A
+ * client that does not know a kind shows the entry and does not start it.
  */
 export type WorkflowCatalogLaunch =
   | { kind: 'run'; workflow: string }
@@ -7399,6 +7509,8 @@ export type WorkflowCatalogLaunch =
   | { kind: 'compose' }
   | { kind: 'document'; style: 'web' | 'doc' | 'ppt' | 'brochure' }
   | { kind: 'chat' }
+  | { kind: 'app' }
+  | { kind: 'repo' }
   | { kind: 'none' };
 
 /** The requesting operator's use of an entry (scope: {@link WorkflowCatalogResponse.usage}). */
@@ -12497,6 +12609,35 @@ export interface McpServerConfigBody {
    * response, log, audit entry or file.
    */
   secret?: string;
+  /**
+   * (api-types 0.187.0, DES-PM-001 §3) `mcp-http` and `mcp-stdio` only: this server is a project-management
+   * system's own MCP server (GitHub's `github-mcp-server`, the Atlassian remote server). Its calls then go through
+   * crew's data gate with resource bindings (§3.1), and trackers of it can be linked to projects and repos. A
+   * human operator's only, at the preview and at the save (else 403 `pm_source_human_only`). PM-1 registers `github`
+   * and `jira`; a re-save of a PM source must name the same system (409 `pm_marker_fixed`).
+   */
+  pm?: { system: 'github' | 'jira' };
+}
+
+/** (api-types 0.187.0, DES-PM-001 §1) The project-management system a registry entry is. PM-1 registers `github` and `jira`. */
+export interface McpPmMarker {
+  system: PmSystem;
+}
+
+/** (api-types 0.187.0) A project-management system. `gitlab` and `ado` are wave PM-2: a registration naming them is a 400 today. */
+export type PmSystem = 'github' | 'jira' | 'gitlab' | 'ado';
+
+/**
+ * (api-types 0.187.0, DES-PM-001 §3.1) A PM tool's resource binding as crew holds it: crew's binding for the tool
+ * (`policy`, e.g. `jira/getJiraIssue@1`), bound to the schema it was reviewed against. In force only while both
+ * match: a changed schema, or a new binding-policy version, makes the tool unavailable to agents until a person
+ * saves the server again. `null` = crew has no binding for this tool, so no agent may use it.
+ */
+export interface McpToolBinding {
+  policy: string;
+  schemaHash: string;
+  /** Whether it is in force now (the saved schema is the reviewed one and the policy is crew's current one). */
+  inForce: boolean;
 }
 
 /**
@@ -12554,6 +12695,8 @@ export interface McpTool {
   observedSchemaHash: string;
   /** (api-types 0.183.0) The disclosure class in force; `null` = none reviewed for the saved schema. */
   disclosure: McpToolDisclosure | null;
+  /** (api-types 0.187.0) PM entries only: the tool's resource binding; `null` = unbound, so unavailable to agents. */
+  binding?: McpToolBinding | null;
 }
 
 export interface McpServer {
@@ -12602,6 +12745,13 @@ export interface McpServer {
   policyVersion?: string;
   /** (api-types 0.183.0) Data sources only: the agent switches (defaults filled in). */
   agents?: McpSourceAgents;
+  /** (api-types 0.187.0, DES-PM-001) A project-management system's server: its system. */
+  pm?: McpPmMarker;
+  /**
+   * (api-types 0.187.0) PM entries only: the trackers linked to projects or repos, with their links (read-only
+   * here; written only through `POST`/`DELETE /tracker-links`).
+   */
+  trackers?: TrackerLink[];
   /**
    * (api-types 0.174.0) `mcp-http` and `rest` only: the ranges confirmed for this server's
    * connections. A server saved before 0.174.0 shows what crew re-derived for it: the IP literal or
@@ -12657,6 +12807,8 @@ export interface McpServerAgentView {
   tools: Array<{ name: string; subject: string; class: McpToolClass; disclosure: McpToolDisclosure | null; enabled: boolean; status: McpToolStatus }>;
   /** Data sources only. */
   agents?: { see: boolean; query: boolean };
+  /** (api-types 0.187.0) PM entries only. */
+  pm?: McpPmMarker;
 }
 
 /** (api-types 0.183.0) `GET /mcp/servers?view=agent`, and `GET /mcp/servers` for any non-human actor. */
@@ -12741,6 +12893,8 @@ export interface McpPreviewTool {
    * class while its schema is unchanged, crew's own class for a tool of crew's Toolbox configuration, else `null`.
    */
   disclosure: McpToolDisclosure | null;
+  /** (api-types 0.187.0) PM entries only: the binding a save gives the tool; `null` = crew has none, so agents never get it. */
+  binding?: { policy: string } | null;
 }
 
 /**
@@ -13655,8 +13809,15 @@ export interface KnowledgeShapeRecord {
 /** (api-types 0.186.0) A node of the Knowledge map. `key` is `<store>:<id>` (`source:`, `repo:`, `knowledge:`, `estate:`). */
 export interface KnowledgeMapNode {
   key: string;
-  kind: 'source' | 'table' | 'shape' | 'code' | 'repo' | 'knowledge';
+  /**
+   * (api-types 0.187.0, DES-PM-001 §3.4) `tracker`: a linked tracker; `project`: a studio project a tracker is
+   * `tracked_in`; `issue`: an issue a run addresses (an `issue_ref`, only its key); `run`: the job that addresses it;
+   * `pr`: the pull request that run delivered (`closes` the issue; `repo` names its repo).
+   */
+  kind: 'source' | 'table' | 'shape' | 'code' | 'repo' | 'knowledge' | 'tracker' | 'project' | 'issue' | 'run' | 'pr';
   label: string;
+  /** (api-types 0.187.0) A tracker node's PM source (registry name) and key. */
+  tracker?: { source: string; key: string };
   /** A table's source name. */
   source?: string;
   /** A code entity's repo id. */
@@ -13699,6 +13860,171 @@ export interface KnowledgeMapResponse {
   notes: string[];
 }
 
+// ── Project-management trackers (DES-PM-001 rev 4, PM-1; api-types 0.187.0) ───────────────────────────────
+
+/**
+ * What a tracker link points at: a studio project (`proj_…`) or a registered repo. A tracker linked to a repo is in
+ * the tracker set of every project that repo belongs to, and of any run that targets it; a tracker linked to a
+ * project reaches only units filed in that project, never another project through a shared repo (§3.2).
+ */
+export type TrackerLinkTarget = { kind: 'project'; id: string } | { kind: 'repo'; id: string };
+
+/**
+ * One link of one tracker (§3.3). A tracker is (source, tenant, key): one project inside one tenant of a registered PM
+ * system (a Jira project on one site, a GitHub repo's issues). Ids are derived: `trk_` + 16 hex of
+ * sha256(source id, tenant, key) and `tl_` + 16 hex of sha256(tracker id, kind, id), so linking twice is one link.
+ */
+export interface TrackerLink {
+  /** `tl_<hash16>` */
+  id: string;
+  /** `trk_<hash16>` */
+  trackerId: string;
+  /** The PM source's registry name, for display. */
+  source: string;
+  /** The PM source's registry id. */
+  sourceId: string;
+  system: PmSystem;
+  /** Jira: the site's `cloudId`; GitHub: the host (`github.com`). */
+  tenant: string;
+  /** The tenant as a person reads it (a Jira site's name or URL host); absent when not known. */
+  tenantLabel?: string;
+  /** Jira: the project key (`PROJA`); GitHub: `owner/repo`. */
+  key: string;
+  /** The vendor's name for it, at most 120 characters. Vendor text: render it as text. */
+  label: string;
+  target: TrackerLinkTarget;
+  linkedAt: string;
+  /** The person who linked it (the actor id). */
+  linkedBy: string;
+  /** Whether estate holds the link yet (Understand follows when it lands; access follows the registry at once). */
+  projection: 'current' | 'pending' | 'failed';
+}
+
+/** `POST /tracker-links` (human-only). */
+export interface CreateTrackerLinkBody {
+  /** The PM source's registry name. */
+  source: string;
+  tenant: string;
+  key: string;
+  target: TrackerLinkTarget;
+}
+
+/**
+ * `GET /tracker-links?project=<id>`, `?repo=<id>`, or both (human-only; 403 `tracker_links_human_only` for any other
+ * actor). With both, `links` + `viaRepos` are the tracker set a run in that project targeting that repo would have.
+ */
+export interface TrackerLinksResponse {
+  target: { project?: string; repo?: string };
+  /** Linked to the target itself (the project, or with only `repo`, that repo). */
+  links: TrackerLink[];
+  /** With a project: the links of its member repos (and of `repo`, when given), each marked with the repo it comes through. */
+  viaRepos: Array<TrackerLink & { viaRepo: string }>;
+  /** With only a repo: the projects the repo is in (its links reach each of them). */
+  projects: Array<{ id: string; name: string }>;
+  /** With a project: for each PM source with a link here, whether its Agents switches let this project see / query it. */
+  agents: Array<{ source: string; see: boolean; query: boolean }>;
+}
+
+/**
+ * `GET /sources/:name/trackers?q=<text>&cursor=<c>&tenant=<t>` (human-only): one page of the projects the PM source
+ * lists NOW (a live read with the source's own credential), each with its links. `next` is the following page's
+ * cursor, `null` at the end. 503 `source_unavailable` when the vendor cannot be reached; 409 `not_a_tracker` for a
+ * source that is not a PM system.
+ */
+export interface SourceTrackersResponse {
+  name: string;
+  trackers: Array<{ tenant: string; tenantLabel?: string; key: string; label: string; links: TrackerLink[] }>;
+  next: string | null;
+}
+
+/**
+ * `GET /tracker-links/issues?project=<id>&repo=<id>&q=<text>` (human-only): for "Start a job from an issue" (§6 step 1),
+ * the issues of each tracker in the tracker set that project and repo would give a run (under the sources' Agents
+ * switches), read live through the same bindings and response projectors an agent's reads go through. `key` is the
+ * reference a launch intent takes (`PROJA-12`, `owner/repo#212`). A tracker that cannot be read says why in `error`
+ * (`query_off`, `unavailable`, `tool_unbound`) and has no issues.
+ */
+export interface TrackerIssuesResponse {
+  trackers: Array<{
+    trackerId: string;
+    source: string;
+    system: PmSystem;
+    key: string;
+    label: string;
+    tenantLabel?: string;
+    via: { kind: 'project' } | { kind: 'repo'; id: string };
+    /** Jira: the site's cloudId; GitHub: the host. */
+    tenant: string;
+    /** `ref`: the reference a launch intent takes for it (`<source>@<tenant>:KEY-N` when two trackers share the key). */
+    issues: Array<{ key: string; ref: string; title: string; state: string | null }>;
+    error?: string;
+  }>;
+}
+
+/**
+ * (DES-PM-001 §5) A governed action on an issue of a run's tracker set: a comment, a transition, or both on one card.
+ * `POST /runs/:id/tracker-actions` (human-only). Without `confirm` it does NOTHING and answers the card (exactly what
+ * would be posted, as whom, from and to which state, and the link that admits the issue) and its `actionHash`; with
+ * `confirm` equal to that hash it does exactly that. An issue outside the run's tracker set has no card: 404
+ * `issue_not_in_tracker_set`. Recorded against the run and audited `knowledge.tracker.action`.
+ */
+export interface TrackerActionBody {
+  /**
+   * Jira `PROJA-1` (`<source>:PROJA-1` or `<source>@<cloudId>:PROJA-1` picks one of several trackers with that key);
+   * GitHub `owner/repo#42` (or `#42` for the run's own repo).
+   */
+  issue: string;
+  /** The exact comment text (at most 8,000 characters). */
+  comment?: string;
+  /** The state to move it to, by name: a Jira transition's target status (`In Review`), or GitHub `closed` / `open`. */
+  transition?: string;
+  confirm?: string;
+}
+
+export interface TrackerActionCard {
+  runId: string;
+  source: string;
+  system: PmSystem;
+  tenant: string;
+  tenantLabel?: string;
+  /** The issue as the tracker names it (`PROJA-1`, `owner/repo#42`). */
+  issue: string;
+  /** The issue's title; vendor text, render it as text. `null` when it could not be read. */
+  title: string | null;
+  /** Who the tracker will say did it (the registered credential's account), `null` when it could not be read. */
+  identity: string | null;
+  comment?: string;
+  transition?: {
+    from: string | null;
+    to: string;
+    /** The states mapped to `todo` / `doing` / `done` (Jira status categories; GitHub open = todo, closed = done). */
+    mapped: { from: 'todo' | 'doing' | 'done' | null; to: 'todo' | 'doing' | 'done' | null };
+  };
+  /** The link that admits the issue for this run: to its project, or through one of its repos. */
+  admittedBy: { kind: 'project'; id: string } | { kind: 'repo'; id: string };
+}
+
+export type TrackerActionResponse =
+  | { done: false; card: TrackerActionCard; actionHash: string }
+  | {
+      done: true;
+      card: TrackerActionCard;
+      at: string;
+      /** Each part as it went; a transition after a failed comment is not attempted. */
+      results: Array<{ part: 'comment' | 'transition'; ok: boolean; error?: string }>;
+    };
+
+/**
+ * `GET /runs/:id/tracker-actions` (human-only): the issues this run addresses (resolved at launch through its tracker
+ * set) that a governed action can be proposed for, each with the link that still admits it (`null`: no longer in the
+ * run's tracker set, so no card).
+ */
+export interface RunTrackerIssuesResponse {
+  runId: string;
+  /** `ref`: the reference `POST` takes for it (`<source>@<tenant>:KEY-N` when two trackers of the run's set share the key). */
+  issues: Array<{ issue: string; ref: string; source: string; system: PmSystem; trackerId: string; admittedBy: TrackerActionCard['admittedBy'] | null }>;
+}
+
 /**
  * `POST /sources/:name/test-call` (G6) — human operator only. Without `confirm` it sends NOTHING and
  * answers the exact request it would send and its `requestHash`; with `confirm` equal to that hash it
@@ -15428,8 +15754,12 @@ export interface AppLinkComponent extends AppComponentBase {
   to: AppLinkTarget;
 }
 
-/** A source kind a query reads; it names the text file: `sql` `.sql`, `graphql` `.graphql`, else `.json`. */
-export type AppQueryKind = 'sql' | 'graphql' | 'rest' | 'mcp' | 'crew';
+/**
+ * A source kind a query reads; it names the text file: `sql` `.sql`, `graphql` `.graphql`, else `.json`.
+ * (api-types 0.189.0) `recall` reads the system's KNOWLEDGE (DES-KNOWLEDGE-DATA-001 §9.1) in the app's own project,
+ * on the reserved source `estate`: its text is an {@link AppRecallQueryText}. Studio-hosted only: Publish refuses it.
+ */
+export type AppQueryKind = 'sql' | 'graphql' | 'rest' | 'mcp' | 'crew' | 'recall';
 
 /** A declared output column's type. A value the source cannot confirm is validated on every row (DES §7.2). */
 export type AppColumnType = 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'datetime';
@@ -15615,6 +15945,80 @@ export interface AppCrewQueryText {
   query: Record<string, AppQueryArg>;
 }
 
+/**
+ * (api-types 0.189.0, DES-KNOWLEDGE-DATA-001 §9.1) `queries/<id>.json` of a `recall` query (source `estate`): one
+ * read of the knowledge the APP'S project may see (crew computes `visible` from the app's project, never from the
+ * request, and re-checks every item before release). `from` names what is read:
+ *
+ * - `knowledge`: documents, source structure and approved data shapes (estate recall); needs `query`; `source`
+ *   keeps only what was derived from that registry source;
+ * - `memories`: what the project remembers (estate memory recall, the project's facet); needs `query`;
+ * - `steering`: the active steering rules that apply to the project; `query` keeps rules whose statement holds its
+ *   words;
+ * - `tables`: one registry source's tables as estate holds them (structure, never rows), with each table's approved
+ *   data shape (its text says what the table joins); needs `source`, takes no `query`.
+ *
+ * Rows have the columns of {@link AppRecallColumns} for that `from` (an app's `output` declares a subset, with
+ * exactly these types); with `group` they are `key` (string) and `count` (integer) per value of that column instead.
+ * `limit` is 1-50 (default 20). Text from a source's structure is marked `untrusted`.
+ */
+export interface AppRecallQueryText {
+  from: AppRecallFrom;
+  /**
+   * The words recalled: a literal of 1-200 characters, or the query's ONE parameter (a string, never viewer-bound:
+   * no `from`), which a search filter binds.
+   */
+  query?: AppQueryArg;
+  /** A registry source name (`tables`: required; `knowledge`: optional). */
+  source?: string;
+  group?: 'kind' | 'source' | 'severity';
+  limit?: number;
+}
+
+export type AppRecallFrom = 'knowledge' | 'memories' | 'steering' | 'tables';
+
+/**
+ * (api-types 0.189.0) The columns a `recall` query answers, per `from`, with their types. Every `from` has `title`,
+ * `content`, `cite` (where it came from: `memory:<id>`, `rule:<id>`, `src:<source>/<table>`, a document's
+ * provenance) and `kind` (document, table, shape or note; a memory's tier; a rule's steering type).
+ */
+export interface AppRecallColumns {
+  knowledge: 'title' | 'content' | 'cite' | 'kind' | 'source' | 'score' | 'untrusted';
+  memories: 'title' | 'content' | 'cite' | 'kind' | 'score';
+  steering: 'title' | 'content' | 'cite' | 'kind' | 'severity';
+  tables: 'title' | 'content' | 'cite' | 'kind' | 'columns' | 'shape' | 'untrusted';
+}
+
+/**
+ * (api-types 0.189.0) `GET /knowledge/summary?project=<id>` (a HUMAN operator): what knowledge an app in that project
+ * can be built on, as counts and registry names only (never a row, a document's text or a memory's words). The same
+ * summary is in the apps builder's knowledge package, so a suggestion never names knowledge the builder cannot use.
+ */
+export interface KnowledgeSummaryResponse {
+  projectId: string;
+  /** The data sources the project may see (the agents switch `see`), in name order. */
+  sources: Array<{
+    name: string;
+    /** Its structure is in estate under its current description (a `tables` query can read it). */
+    described: boolean;
+    /** Agents may read its rows for this project. */
+    query: boolean;
+    /**
+     * Approved data shapes on it that the project may see, each verified against estate's own node and deps, counted
+     * up to 5. `null` = the count could not be established (the review queue or a shape's node could not be read, or
+     * the summary's budget ran out before enough were checked): unknown, not zero.
+     */
+    shapes: number | null;
+  }>;
+  /**
+   * Memories a recall in this project can reach (every facet of a memory must match the project's: faceted to it, or
+   * to nothing), working memories left out (an app's memory recall leaves them out too). `null` = estate did not answer.
+   */
+  memories: { project: number; shared: number } | null;
+  /** Active steering rules that apply to this project, by steering type. `null` = the engine did not answer. */
+  steering: { total: number; byType: Partial<Record<SteeringType, number>> } | null;
+}
+
 // How a query's text binds its parameters (api-types 0.176.0): SQL `$n` (Postgres) and the n-th `?` (MySQL,
 // SQLite) bind the n-th parameter in the order `params.properties` declares them, and every declared
 // parameter is used; GraphQL variables are the parameters by name; `.json` texts name them in `AppQueryArg`s.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.186.0",
+  "version": "0.191.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",