@sayknow-cli/coding-agent 0.7.16 → 0.7.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -15,6 +15,7 @@ import pickUiLibrarySkill from "./skc/ui-skills/pick-ui-library/SKILL.md" with {
15
15
  import prototypeSkill from "./skc/ui-skills/prototype/SKILL.md" with { type: "text" };
16
16
  import reactBitsSkill from "./skc/ui-skills/react-bits/SKILL.md" with { type: "text" };
17
17
  import reviewAnimationsSkill from "./skc/ui-skills/review-animations/SKILL.md" with { type: "text" };
18
+ import stageshowSkill from "./skc/ui-skills/stageshow/SKILL.md" with { type: "text" };
18
19
 
19
20
  /**
20
21
  * Bundled frontend UI/UX craft skills. These are NOT public SKC workflow skills.
@@ -24,6 +25,7 @@ import reviewAnimationsSkill from "./skc/ui-skills/review-animations/SKILL.md" w
24
25
  * `skc/ui-skills/NOTICE.md`; regenerate with `scripts/build-ui-skill-bundle.ts`.
25
26
  */
26
27
  export const BUNDLED_SKC_UI_SKILL_NAMES = [
28
+ "stageshow",
27
29
  "emil-design-eng",
28
30
  "animate",
29
31
  "review-animations",
@@ -48,6 +50,7 @@ interface BundledUiSkillSource {
48
50
  }
49
51
 
50
52
  const BUNDLED_UI_SKILL_SOURCES: readonly BundledUiSkillSource[] = [
53
+ { name: "stageshow", relativePath: "ui-skills/stageshow/SKILL.md", content: stageshowSkill },
51
54
  { name: "emil-design-eng", relativePath: "ui-skills/emil-design-eng/SKILL.md", content: emilDesignEngSkill },
52
55
  { name: "animate", relativePath: "ui-skills/animate/SKILL.md", content: animateSkill },
53
56
  { name: "review-animations", relativePath: "ui-skills/review-animations/SKILL.md", content: reviewAnimationsSkill },
@@ -23,20 +23,27 @@ export interface UiSkillKeywordDefinition {
23
23
  pattern: RegExp;
24
24
  }
25
25
 
26
+ /**
27
+ * SKC's design center. Every frontend match loads it first, ahead of the
28
+ * specialized lead and the craft baseline, whatever the surface.
29
+ */
30
+ export const UI_SKILL_CORE: BundledSkcUiSkillName = "stageshow";
31
+
26
32
  /** Base craft skill paired with any specialized web frontend match. */
27
33
  export const UI_SKILL_BASE: BundledSkcUiSkillName = "emil-design-eng";
28
34
 
29
35
  /**
30
36
  * Skills that already carry their own complete craft bar, so pairing them with
31
37
  * the web baseline only adds noise. `appllama-app-design-skill` targets native
32
- * Expo/React Native screens and ships its own motion and fidelity rules.
38
+ * Expo/React Native screens and ships its own motion and fidelity rules. The
39
+ * design center still leads them.
33
40
  */
34
41
  const SELF_SUFFICIENT_UI_SKILLS = new Set<BundledSkcUiSkillName>(["appllama-app-design-skill"]);
35
42
 
36
43
  /**
37
44
  * Ordered specialized detectors. The first (highest priority) match selects the
38
- * lead skill; `emil-design-eng` is added as the craft baseline for build and
39
- * review work.
45
+ * lead skill; `stageshow` is loaded ahead of it and `emil-design-eng` after it
46
+ * as the craft baseline for build and review work.
40
47
  */
41
48
  export const UI_SKILL_KEYWORD_DEFINITIONS: readonly UiSkillKeywordDefinition[] = [
42
49
  {
@@ -134,45 +141,52 @@ const WEB_SURFACE_PATTERN =
134
141
  /\b(web|browser|css|html|react|vue|svelte|next\.?js|tailwind|dom|mobile|ios|android|page|screen)\b|웹|브라우저|화면|페이지/i;
135
142
 
136
143
  /**
137
- * Detect frontend UI/UX intent. Returns matches ordered by priority, most
138
- * specific first, with `emil-design-eng` appended as the craft baseline.
144
+ * Detect frontend UI/UX intent. Returns `stageshow` first, then the most
145
+ * specific match, then `emil-design-eng` as the craft baseline.
139
146
  */
140
147
  export function detectUiSkillKeywords(text: string): UiSkillKeywordMatch[] {
148
+ const lead = detectLeadUiSkill(text);
149
+ return lead ? pairWithCoreAndBaseline(lead) : [];
150
+ }
151
+
152
+ /** The highest-priority specialized match, or null when the prompt is not frontend work. */
153
+ function detectLeadUiSkill(text: string): UiSkillKeywordMatch | null {
141
154
  const trimmed = text.trim();
142
- if (!trimmed) return [];
155
+ if (!trimmed) return null;
143
156
  // A prompt about SKC's own TUI with no web surface mentioned is handled by
144
157
  // docs/ui-design-visual-qa.md, not the web craft skills.
145
- if (TERMINAL_ONLY_PATTERN.test(trimmed) && !WEB_SURFACE_PATTERN.test(trimmed)) return [];
158
+ if (TERMINAL_ONLY_PATTERN.test(trimmed) && !WEB_SURFACE_PATTERN.test(trimmed)) return null;
146
159
 
147
- const matches: UiSkillKeywordMatch[] = [];
160
+ let lead: UiSkillKeywordMatch | null = null;
148
161
  for (const definition of UI_SKILL_KEYWORD_DEFINITIONS) {
149
162
  const match = trimmed.match(definition.pattern);
150
163
  if (!match) continue;
151
- matches.push({ skill: definition.skill, keyword: match[0], priority: definition.priority });
164
+ const candidate = { skill: definition.skill, keyword: match[0], priority: definition.priority };
165
+ if (
166
+ !lead ||
167
+ candidate.priority > lead.priority ||
168
+ (candidate.priority === lead.priority && candidate.skill.localeCompare(lead.skill) < 0)
169
+ ) {
170
+ lead = candidate;
171
+ }
152
172
  }
153
- if (matches.length === 0) return [];
173
+ return lead;
174
+ }
154
175
 
155
- matches.sort((a, b) => b.priority - a.priority || a.skill.localeCompare(b.skill));
156
- const deduped: UiSkillKeywordMatch[] = [];
157
- for (const item of matches) {
158
- if (deduped.some(existing => existing.skill === item.skill)) continue;
159
- deduped.push(item);
160
- }
161
- // Keep the lead skill plus the craft baseline; more than that is noise.
162
- const lead = deduped[0]!;
163
- return pairWithBaseline(lead.skill);
176
+ function skillMatch(skill: BundledSkcUiSkillName): UiSkillKeywordMatch {
177
+ const definition = UI_SKILL_KEYWORD_DEFINITIONS.find(item => item.skill === skill);
178
+ return { skill, keyword: skill, priority: definition?.priority ?? 0 };
164
179
  }
165
180
 
166
181
  /**
167
- * A specialized skill plus the craft baseline, which is the pairing the skills
168
- * themselves assume. Skills that carry their own complete craft bar stand alone.
182
+ * The design center, the specialized lead, then the craft baseline the skills
183
+ * themselves assume. Skills that carry their own complete craft bar skip the
184
+ * baseline but never the design center.
169
185
  */
170
- function pairWithBaseline(skill: BundledSkcUiSkillName): UiSkillKeywordMatch[] {
171
- const definition = UI_SKILL_KEYWORD_DEFINITIONS.find(item => item.skill === skill);
172
- const lead: UiSkillKeywordMatch = { skill, keyword: skill, priority: definition?.priority ?? 0 };
173
- if (skill === UI_SKILL_BASE || SELF_SUFFICIENT_UI_SKILLS.has(skill)) return [lead];
174
- const base = UI_SKILL_KEYWORD_DEFINITIONS.find(item => item.skill === UI_SKILL_BASE);
175
- return [lead, { skill: UI_SKILL_BASE, keyword: UI_SKILL_BASE, priority: base?.priority ?? 0 }];
186
+ function pairWithCoreAndBaseline(lead: UiSkillKeywordMatch): UiSkillKeywordMatch[] {
187
+ const paired = [skillMatch(UI_SKILL_CORE), lead];
188
+ if (!SELF_SUFFICIENT_UI_SKILLS.has(lead.skill)) paired.push(skillMatch(UI_SKILL_BASE));
189
+ return paired.filter((item, index) => paired.findIndex(other => other.skill === item.skill) === index);
176
190
  }
177
191
 
178
192
  function renderUiSkillDirective(skills: readonly BundledSkcUiSkillName[], evidence: string): string {
@@ -180,6 +194,7 @@ function renderUiSkillDirective(skills: readonly BundledSkcUiSkillName[], eviden
180
194
  return [
181
195
  `SKC detected frontend UI/UX work in this prompt (${evidence}).`,
182
196
  `Before writing or reviewing that surface, load ${names} with the \`skill\` tool.`,
197
+ `\`${UI_SKILL_CORE}\` is the design center for every frontend surface, real product UI included; apply it even when the task is not a demo.`,
183
198
  "These skills are bundled with SKC: never tell the user to install them, and never skip them because the task looks small.",
184
199
  "They are not workflow skills and have no `skc state` mode state.",
185
200
  ].join(" ");
@@ -187,15 +202,15 @@ function renderUiSkillDirective(skills: readonly BundledSkcUiSkillName[], eviden
187
202
 
188
203
  /**
189
204
  * Build the `UserPromptSubmit` directive that makes the agent load the matching
190
- * bundled UI skill for this turn. Returns null when the prompt is not frontend
205
+ * bundled UI skills for this turn. Returns null when the prompt is not frontend
191
206
  * UI/UX work.
192
207
  */
193
208
  export function buildUiSkillActivationContext(text: string): string | null {
194
- const matches = detectUiSkillKeywords(text);
195
- if (matches.length === 0) return null;
209
+ const lead = detectLeadUiSkill(text);
210
+ if (!lead) return null;
196
211
  return renderUiSkillDirective(
197
- matches.map(match => match.skill),
198
- `matched "${matches[0]!.keyword}"`,
212
+ pairWithCoreAndBaseline(lead).map(match => match.skill),
213
+ `matched "${lead.keyword}"`,
199
214
  );
200
215
  }
201
216
 
@@ -207,7 +222,7 @@ export function buildUiSkillActivationContext(text: string): string | null {
207
222
  */
208
223
  export function buildUiSkillDirectiveForSkill(skill: BundledSkcUiSkillName): string {
209
224
  return renderUiSkillDirective(
210
- pairWithBaseline(skill).map(match => match.skill),
225
+ pairWithCoreAndBaseline(skillMatch(skill)).map(match => match.skill),
211
226
  "semantic match",
212
227
  );
213
228
  }
@@ -220,8 +235,10 @@ export function buildUiSkillDirectiveForSkill(skill: BundledSkcUiSkillName): str
220
235
  * signal. Kept next to the patterns so the two cannot drift apart.
221
236
  */
222
237
  export const BUNDLED_UI_SKILL_MEANINGS: Record<BundledSkcUiSkillName, string> = {
238
+ stageshow:
239
+ "Faux product UI for marketing and docs pages: hero demos, feature cards, bento grids, cursor walkthroughs, mocked app screenshots, product shots. Every other frontend pick loads it too as the design center.",
223
240
  "emil-design-eng":
224
- "General web UI/UX craft: building or reviewing components, layout, spacing, typography, design systems, CSS. The default for frontend work with no more specific fit. Also faux product UI for marketing and docs pages: hero demos, feature cards, bento grids, cursor walkthroughs, mocked app screenshots.",
241
+ "General web UI/UX craft: building or reviewing components, layout, spacing, typography, design systems, CSS. The default for frontend work with no more specific fit.",
225
242
  animate:
226
243
  "Adding new motion to a web UI: animations, transitions, easing, keyframes, hover effects, micro-interactions.",
227
244
  "review-animations": "Reviewing motion that already exists and judging whether it is good.",
@@ -137,5 +137,5 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
137
137
  "tree.md": "# `/tree` Command Reference\n\n`/tree` opens the interactive **Session Tree** navigator. It lets you jump to any entry in the current session file and continue from that point.\n\nThis is an in-file leaf move, not a new session export.\n\n## What `/tree` does\n\n- Builds a tree from current session entries (`SessionManager.getTree()`)\n- Opens `TreeSelectorComponent` with keyboard navigation, filters, and search\n- On selection, calls `AgentSession.navigateTree(targetId, { summarize, customInstructions })`\n- Rebuilds visible chat from the new leaf path\n- Optionally prefills editor text when selecting a user/custom message\n\nPrimary implementation:\n\n- `src/modes/controllers/input-controller.ts` (`/tree`, keybinding wiring, double-escape behavior)\n- `src/modes/controllers/selector-controller.ts` (tree UI launch + summary prompt flow)\n- `src/modes/components/tree-selector.ts` (navigation, filters, search, labels, rendering)\n- `src/session/agent-session.ts` (`navigateTree` leaf switching + optional summary)\n- `src/session/session-manager.ts` (`getTree`, `branch`, `branchWithSummary`, `resetLeaf`, label persistence)\n\n## How to open it\n\nAny of the following opens the same selector:\n\n- `/tree`\n- configured keybinding action `tree`\n- double-escape on empty editor when `doubleEscapeAction = \"tree\"` (default)\n- `/branch` when `doubleEscapeAction = \"tree\"` (routes to tree selector instead of user-only branch picker)\n\n## Tree UI model\n\nThe tree is rendered from session entry parent pointers (`id` / `parentId`).\n\n- Children are sorted by timestamp ascending (older first, newer lower)\n- Active branch (path from root to current leaf) is marked with a bullet\n- Labels (if present) render as `[label]` before node text\n- If multiple roots exist (orphaned/broken parent chains), they are shown under a virtual branching root\n\n```text\nExample tree view (active path marked with •):\n\n├─ user: \"Start task\"\n│ └─ assistant: \"Plan\"\n│ ├─ • user: \"Try approach A\"\n│ │ └─ • assistant: \"A result\"\n│ │ └─ • [milestone] user: \"Continue A\"\n│ └─ user: \"Try approach B\"\n│ └─ assistant: \"B result\"\n```\n\nThe selector recenters around current selection and shows up to:\n\n- `max(5, floor(terminalHeight / 2))` rows\n\n## Keybindings inside tree selector\n\n- `Up` / `Down`: move selection (wraps)\n- `Left` / `Right`: page up / page down\n- `Enter`: select node\n- `Esc`: clear search if active; otherwise close selector\n- `Ctrl+C`: close selector\n- `Type`: append to search query\n- `Backspace`: delete search character\n- `Shift+L`: edit/clear label on selected entry\n- `Ctrl+O`: cycle filter forward\n- `Shift+Ctrl+O`: cycle filter backward\n- `Alt+D/T/U/L/A`: jump directly to specific filter mode\n\n## Filters and search semantics\n\nFilter modes (`TreeList`):\n\n1. `default`\n2. `no-tools`\n3. `user-only`\n4. `labeled-only`\n5. `all`\n\n### `default`\n\nShows most conversational nodes, but hides bookkeeping entry types:\n\n- `label`\n- `custom`\n- `model_change`\n- `thinking_level_change`\n\n### `no-tools`\n\nSame as `default`, plus hides `toolResult` messages.\n\n### `user-only`\n\nOnly `message` entries where role is `user`.\n\n### `labeled-only`\n\nOnly entries that currently resolve to a label.\n\n### `all`\n\nEverything in the session tree, including bookkeeping/custom entries.\n\n### Tool-only assistant node behavior\n\nAssistant messages that contain **only tool calls** (no text) are hidden by default in all filtered views unless:\n\n- message is error/aborted (`stopReason` not `stop`/`toolUse`), or\n- it is the current leaf (always kept visible)\n\n### Search behavior\n\n- Query is tokenized by spaces\n- Matching is case-insensitive\n- All tokens must match (AND semantics)\n- Searchable text includes label, role, and type-specific content (message text, branch summary text, custom type, tool command snippets, etc.)\n\n## Selection outcomes (important)\n\n`navigateTree` computes new leaf behavior from selected entry type:\n\n### Selecting `user` message\n\n- New leaf becomes selected entry’s `parentId`\n- If parent is `null` (root user message), leaf resets to root (`resetLeaf()`)\n- Selected message text is copied to editor for editing/resubmit\n\n### Selecting `custom_message`\n\n- Same leaf rule as user messages (`parentId`)\n- Text content is extracted and copied to editor\n\n### Selecting non-user node (assistant/tool/summary/compaction/custom bookkeeping/etc.)\n\n- New leaf becomes selected node id\n- Editor is not prefilled\n\n### Selecting current leaf\n\n- No-op; selector closes with “Already at this point”\n\n```text\nSelection decision (simplified):\n\nselected node\n │\n ├─ is current leaf? ── yes ──> close selector (no-op)\n │\n ├─ is user/custom_message? ── yes ──> leaf := parentId (or resetLeaf for root)\n │ + prefill editor text\n │\n └─ otherwise ──> leaf := selected node id\n + no editor prefill\n```\n\n## Summary-on-switch flow\n\nSummary prompt is controlled by `branchSummary.enabled` (default: `false`).\n\nWhen enabled, after picking a node the UI asks:\n\n- `No summary`\n- `Summarize`\n- `Summarize with custom prompt`\n\nFlow details:\n\n- Escape in summary prompt reopens tree selector\n- Custom prompt cancellation returns to summary choice loop\n- During summarization, UI shows loader and binds `Esc` to `abortBranchSummary()`\n- If summarization aborts, tree selector reopens and no move is applied\n\n`navigateTree` internals:\n\n- Collects abandoned-branch entries from old leaf to common ancestor\n- Emits `session_before_tree` (extensions can cancel or inject summary)\n- Uses default summarizer only if requested and needed\n- Applies move with:\n - `branchWithSummary(...)` when summary exists\n - `branch(newLeafId)` for non-root move without summary\n - `resetLeaf()` for root move without summary\n- Replaces agent conversation with rebuilt session context\n- Emits `session_tree`\n\nNote: if user requests summary but there is nothing to summarize, navigation proceeds without creating a summary entry.\n\n## Labels\n\nLabel edits in tree UI call `appendLabelChange(targetId, label)`.\n\n- non-empty label sets/updates resolved label\n- empty label clears it\n- labels are stored as append-only `label` entries\n- tree nodes display resolved label state, not raw label-entry history\n\n## `/tree` vs adjacent operations\n\n| Operation | Scope | Result |\n| --------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `/tree` | Current session file | Moves leaf to selected point (same file) |\n| `/branch` | Usually current session file -> new session file | By default branches from selected **user** message into a new session file; if `doubleEscapeAction = \"tree\"`, `/branch` opens tree navigation UI instead |\n| `/fork` | Whole current session | Duplicates session into a new persisted session file |\n| `/resume` | Session list | Switches to another session file |\n\nKey distinction: `/tree` is a navigation/repositioning tool inside one session file. `/branch`, `/fork`, and `/resume` all change session-file context.\n\n## Operator workflows\n\n### Re-run from an earlier user prompt without losing current branch\n\n1. `/tree`\n2. search/select earlier user message\n3. choose `No summary` (or summarize if needed)\n4. edit prefilled text in editor\n5. submit\n\nEffect: new branch grows from selected point within same session file.\n\n### Leave current branch with context breadcrumb\n\n1. enable `branchSummary.enabled`\n2. `/tree` and select target node\n3. choose `Summarize` (or custom prompt)\n\nEffect: a `branch_summary` entry is appended at the target position before continuing.\n\n### Investigate hidden bookkeeping entries\n\n1. `/tree`\n2. press `Alt+A` (all)\n3. search for `model`, `thinking`, `custom`, or labels\n\nEffect: inspect full internal timeline, not just conversational nodes.\n\n### Bookmark pivot points for later jumps\n\n1. `/tree`\n2. move to entry\n3. `Shift+L` and set label\n4. later use `Alt+L` (`labeled-only`) to jump quickly\n\nEffect: fast navigation among durable branch landmarks.\n",
138
138
  "ttsr-injection-lifecycle.md": "# TTSR Injection Lifecycle\n\nThis document covers the current Time Traveling Stream Rules (TTSR) runtime path from rule discovery to stream interruption, retry injection, extension notifications, and session-state handling.\n\n## Implementation files\n\n- [`../src/sdk/session.ts`](../packages/coding-agent/src/sdk/session.ts)\n- [`../src/export/ttsr.ts`](../packages/coding-agent/src/export/ttsr.ts)\n- [`../src/session/agent-session.ts`](../packages/coding-agent/src/session/agent-session.ts)\n- [`../src/session/session-manager.ts`](../packages/coding-agent/src/session/session-manager.ts)\n- [`../src/prompts/system/ttsr-interrupt.md`](../packages/coding-agent/src/prompts/system/ttsr-interrupt.md)\n- [`../src/capability/index.ts`](../packages/coding-agent/src/capability/index.ts)\n- [`../src/extensibility/extensions/types.ts`](../packages/coding-agent/src/extensibility/extensions/types.ts)\n- [`../src/extensibility/hooks/types.ts`](../packages/coding-agent/src/extensibility/hooks/types.ts)\n- [`../src/extensibility/custom-tools/types.ts`](../packages/coding-agent/src/extensibility/custom-tools/types.ts)\n- [`../src/modes/controllers/event-controller.ts`](../packages/coding-agent/src/modes/controllers/event-controller.ts)\n\n## 1. Discovery feed and rule registration\n\nAt session creation, `createAgentSession()` loads discovered rules and constructs a `TtsrManager`:\n\n```ts\nconst ttsrSettings = settings.getGroup(\"ttsr\");\nconst ttsrManager = new TtsrManager(ttsrSettings);\nconst rulesResult = await loadCapability<Rule>(ruleCapability.id, { cwd });\nfor (const rule of rulesResult.items) {\n if (rule.condition?.length && ttsrManager.addRule(rule)) continue;\n // non-TTSR rules continue through normal rule handling\n}\n```\n\n### Pre-registration dedupe behavior\n\n`loadCapability(\"rules\")` deduplicates by `rule.name` with first-wins semantics (higher provider priority first). Shadowed duplicates are removed before TTSR registration.\n\n### `TtsrManager.addRule()` behavior\n\nRegistration is skipped when:\n\n- `rule.condition` is absent or all condition regexes fail to compile\n- a rule with the same `rule.name` was already registered in this manager\n- the rule scope excludes all monitored streams\n\nInvalid regex conditions and unreachable scopes are logged as warnings and ignored; session startup continues.\n\n### Setting caveat\n\n`TtsrSettings.enabled=false` makes `TtsrManager` no-op (`addRule`, `checkDelta`, `hasRules`, `restoreInjected`), so no conditional rules are registered or injected.\n\n## 2. Streaming monitor lifecycle\n\nTTSR detection runs inside `AgentSession.#handleAgentEvent`.\n\n### Turn start\n\nOn `turn_start`, the stream buffer is reset:\n\n- `ttsrManager.resetBuffer()`\n\n### During stream (`message_update`)\n\nWhen assistant updates arrive and rules exist:\n\n- monitor `text_delta`, `thinking_delta`, and `toolcall_delta`\n- append delta into a source/tool scoped manager buffer\n- call `checkDelta(delta, matchContext)`\n\n`checkDelta()` iterates registered rules and returns all matching rules that pass scope, global-path, condition, and repeat policy checks.\n\n## 3. Trigger decision and immediate abort path\n\nWhen one or more rules match and at least one matched rule allows interruption:\n\n1. Matched rules are deduplicated into `#pendingTtsrInjections`.\n2. `#ttsrAbortPending = true` and a TTSR resume gate is created.\n3. `agent.abort()` is called immediately.\n4. `ttsr_triggered` event is emitted asynchronously (fire-and-forget).\n5. retry work is scheduled via the post-prompt task scheduler with a 50ms delay.\n\nAbort is not blocked on extension callbacks.\n\n## 4. Retry scheduling, context mode, and reminder injection\n\nAfter the 50ms timeout:\n\n1. `#ttsrAbortPending = false`\n2. read `ttsrManager.getSettings().contextMode`\n3. if `contextMode === \"discard\"`, drop the targeted partial assistant output with `agent.replaceMessages(...slice(0, targetAssistantIndex))`\n4. build injection content from pending rules using `ttsr-interrupt.md` template\n5. append and persist a hidden `custom_message`/runtime custom message with `customType: \"ttsr-injection\"` and `details.rules`\n6. mark those rule names injected, persist a `ttsr_injection` entry, and call `agent.continue()` to retry generation\n\nTemplate payload is:\n\n```xml\n<system-interrupt reason=\"rule_violation\" rule=\"{{name}}\" path=\"{{path}}\">\n...\n{{content}}\n</system-interrupt>\n```\n\nPending injections are cleared after content generation.\n\n### `contextMode` behavior on partial output\n\n- `discard`: partial/aborted assistant message is removed before retry.\n- `keep`: partial assistant output remains in conversation state; reminder is appended after it.\n\n### Non-interrupting matches\n\nNon-interrupting matches split by `matchContext.source`:\n\n- **`source === \"tool\"` (tool-source match).** The rule is bucketed into `#perToolTtsrInjections`, keyed by the matched tool call's `id`. There is **no** deferred follow-up turn and the stream is not aborted. When the tool actually produces a result, the `afterToolCall` hook prepends a rendered `ttsr-tool-reminder.md` block to `ctx.result.content` (a single `text` block inserted ahead of the tool's own content), and persists a `ttsr_injection` entry with the consumed rule names. The template payload is:\n\n ```xml\n <system-reminder reason=\"rule_violation\" rule=\"{{name}}\" path=\"{{path}}\">\n ...\n {{content}}\n </system-reminder>\n ```\n\n- **`source === \"text\"` / `\"thinking\"` (prose-source match).** Behavior is unchanged: the rule is queued in `#pendingTtsrInjections` and, after a successful non-error, non-aborted assistant message, `AgentSession` injects the hidden `ttsr-injection` custom message as a follow-up and schedules continuation.\n\nWithin a single matching batch, each rule is attached to exactly one sibling tool call — if multiple sibling tool calls would satisfy the same rule, deduplication picks one and the others are left untouched. Multiple distinct rules can still fold onto the same tool call.\n\n#### Implications for tool authors and transcript readers\n\n- The tool's own `toolResult` content is preserved verbatim; the reminder is **prepended** as an additional leading text block. Renderers that assume `content[0]` is the tool's primary output must scan past any block whose text begins with `<system-reminder reason=\"rule_violation\"` (or filter on the wrapper tag) to find the real payload.\n- The reminder is in-band on the tool result, not a separate `custom_message`/`ttsr-injection` entry. Transcript readers looking for non-interrupting TTSR activity on tool-source rules MUST inspect tool results (and the persisted `ttsr_injection` entry list), not just synthetic injection entries.\n- A single tool result may carry reminders for several rules concatenated with a blank line between rendered templates.\n- If the assistant message ends with `stopReason === \"aborted\"` or `\"error\"` before the matched tools run, the pending per-tool buckets are cleared — those rules are **not** persisted as injected and remain eligible to re-trigger on a future turn (subject to repeat policy).\n\n## 5. Repeat policy and gap logic\n\n`TtsrManager` tracks `#messageCount` and per-rule `lastInjectedAt`.\n\n### `repeatMode: \"once\"`\n\nA rule can trigger only once after it has an injection record.\n\n### `repeatMode: \"after-gap\"`\n\nA rule can re-trigger only when:\n\n- `messageCount - lastInjectedAt >= repeatGap`\n\n`messageCount` increments on `turn_end`, so gap is measured in completed turns, not stream chunks.\n\n## 6. Event emission and extension/hook surfaces\n\n### Session event\n\n`AgentSessionEvent` includes:\n\n```ts\n{ type: \"ttsr_triggered\"; rules: Rule[] }\n```\n\n### Extension runner\n\n`#emitSessionEvent()` routes the event to:\n\n- extension listeners (`ExtensionRunner.emit({ type: \"ttsr_triggered\", rules })`)\n- local session subscribers\n\n### Hook and custom-tool typing\n\n- extension API exposes `on(\"ttsr_triggered\", ...)`\n- hook API exposes `on(\"ttsr_triggered\", ...)`\n- custom tools receive `onSession({ reason: \"ttsr_triggered\", rules })`\n\n### Interactive-mode rendering difference\n\nInteractive mode uses `session.isTtsrAbortPending` to suppress showing the aborted assistant stop reason as a visible failure during TTSR interruption, and renders a `TtsrNotificationComponent` when the event arrives.\n\n## 7. Persistence and resume state (current implementation)\n\n`SessionManager` persists injected-rule state:\n\n- entry type: `ttsr_injection`\n- append API: `appendTtsrInjection(ruleNames)`\n- query API: `getInjectedTtsrRules()`\n- context reconstruction includes `SessionContext.injectedTtsrRules`\n\n`TtsrManager` supports restoration via `restoreInjected(ruleNames)`.\n\n### Current wiring status\n\nIn the current runtime path:\n\n- interrupted injections append a hidden `custom_message` with `customType: \"ttsr-injection\"` and append a `ttsr_injection` entry via `appendTtsrInjection(...)`\n- deferred non-interrupting prose-source injections are marked/persisted when their queued custom message reaches `message_end`\n- non-interrupting tool-source injections are marked at match time and persisted via `appendTtsrInjection(...)` from the `afterToolCall` hook when the matched tool's result is produced\n- `createAgentSession()` restores `existingSession.injectedTtsrRules` into `ttsrManager`\n\nNet effect: injected-rule suppression is persisted/restored across session reload/resume for the current branch path.\n\n## 8. Race boundaries and ordering guarantees\n\n### Abort vs retry callback\n\n- abort is synchronous from TTSR handler perspective (`agent.abort()` called immediately)\n- retry is deferred by timer (`50ms`)\n- extension notification is asynchronous and intentionally not awaited before abort/retry scheduling\n\n### Multiple matches in same stream window\n\n`checkDelta()` returns all currently matching eligible rules for that scoped buffer. Pending injections are deduplicated by rule name before injection.\n\n### Between abort and continue\n\nDuring the timer window, state can change (user interruption, mode actions, additional events). The retry call is best-effort: `agent.continue().catch(() => {})` swallows follow-up errors.\n\n## 9. Edge cases summary\n\n- Invalid `condition` regex: skipped with warning; other conditions/rules continue.\n- Duplicate rule names at capability layer: lower-priority duplicates are shadowed before registration.\n- Duplicate names at manager layer: second registration is ignored.\n- `contextMode: \"keep\"`: partial violating output can remain in context before reminder retry. **Cost warning:** every aborted partial turn is retained, so context (and token spend) grows each time a rule fires. Prefer the default `discard` unless the partial output is specifically needed.\n- `interruptMode: \"never\"`: prose-source matches queue a deferred hidden injection after a successful assistant message; tool-source matches fold an in-band `<system-reminder>` into the matched tool call's `toolResult` content via the `afterToolCall` hook (no mid-stream abort, no separate follow-up turn).\n- Tool-source non-interrupting buckets are cleared when the parent assistant message ends with `stopReason === \"aborted\"` or `\"error\"`, so rules whose target tool never produced a result remain eligible to re-trigger.\n- Repeat-after-gap depends on turn count increments at `turn_end`; mid-turn chunks do not advance gap counters.\n",
139
139
  "tui-runtime-internals.md": "# TUI runtime internals\n\nThis document maps the non-theme runtime path from terminal input to rendered output in interactive mode. It focuses on behavior in `packages/tui` and its integration from `packages/coding-agent` controllers.\n\n## Runtime layers and ownership\n\n- **`packages/tui` engine**: terminal lifecycle, stdin normalization, focus routing, render scheduling, differential painting, overlay composition, hardware cursor placement.\n- **`packages/coding-agent` interactive mode**: builds component tree, binds editor callbacks and keymaps, reacts to agent/session events, and translates domain state (streaming, tool execution, retries, plan mode) into UI components.\n\nBoundary rule: the TUI engine is message-agnostic. It only knows `Component.render(width)`, `handleInput(data)`, focus, and overlays. Agent semantics stay in interactive controllers.\n\n## Implementation files\n\n- [`../src/modes/interactive-mode.ts`](../packages/coding-agent/src/modes/interactive-mode.ts)\n- [`../src/modes/controllers/event-controller.ts`](../packages/coding-agent/src/modes/controllers/event-controller.ts)\n- [`../src/modes/controllers/input-controller.ts`](../packages/coding-agent/src/modes/controllers/input-controller.ts)\n- [`../src/modes/components/custom-editor.ts`](../packages/coding-agent/src/modes/components/custom-editor.ts)\n- [`../../tui/src/tui.ts`](../packages/tui/src/tui.ts)\n- [`../../tui/src/terminal.ts`](../packages/tui/src/terminal.ts)\n- [`../../tui/src/editor-component.ts`](../packages/tui/src/editor-component.ts)\n- [`../../tui/src/stdin-buffer.ts`](../packages/tui/src/stdin-buffer.ts)\n- [`../../tui/src/components/loader.ts`](../packages/tui/src/components/loader.ts)\n\n## Boot and component tree assembly\n\n`InteractiveMode` constructs `TUI(new ProcessTerminal(), settings.get(\"showHardwareCursor\"))`, applies `settings.get(\"clearOnShrink\")`, and creates persistent containers:\n\n- `chatContainer`\n- `pendingMessagesContainer`\n- `statusContainer`\n- `todoContainer`\n- `btwContainer`\n- `statusLine`\n- `hookWidgetContainerAbove`\n- `editorContainer` (holds `CustomEditor`)\n- `hookWidgetContainerBelow`\n\n`init()` wires the tree in that order, focuses the editor, registers input handlers via `InputController`, subscribes terminal appearance changes into theme auto-detection, starts TUI, and requests a forced render.\nA forced render (`requestRender(true)`) resets previous-line caches and cursor bookkeeping before repainting.\n\n## Terminal lifecycle and stdin normalization\n\n`ProcessTerminal.start()`:\n\n1. Enables raw mode and bracketed paste.\n2. Attaches resize handler.\n3. Creates a `StdinBuffer` to split partial escape chunks into complete sequences.\n4. Queries Kitty keyboard protocol support (`CSI ? u`), then enables protocol flags if supported; otherwise enables modifyOtherKeys fallback after a short timeout.\n5. Queries OSC 11 background color and enables Mode 2031 appearance notifications for dark/light theme detection.\n6. On Windows, attempts VT input enablement via `kernel32` mode flags.\n `StdinBuffer` behavior:\n\n- Buffers fragmented escape sequences (CSI/OSC/DCS/APC/SS3).\n- Emits `data` only when a sequence is complete or timeout-flushed.\n- Detects bracketed paste and emits a `paste` event with raw pasted text.\n\nThis prevents partial escape chunks from being misinterpreted as normal keypresses.\n\n## Input routing and focus model\n\nInput path:\n\n`stdin -> ProcessTerminal -> StdinBuffer -> TUI.#handleInput -> focusedComponent.handleInput`\n\nRouting details:\n\n1. TUI runs registered input listeners first (`addInputListener`), allowing consume/transform behavior.\n2. TUI handles global debug shortcut (`shift+ctrl+d`) before component dispatch.\n3. If focused component belongs to an overlay that is now hidden/invisible, TUI reassigns focus to next visible overlay or saved pre-overlay focus.\n4. Key release events are filtered unless focused component sets `wantsKeyRelease = true`.\n5. After dispatch, TUI schedules render.\n\n`setFocus()` also toggles `Focusable.focused`, which controls whether components emit `CURSOR_MARKER` for hardware cursor placement.\n\n## Key handling split: editor vs controller\n\n`CustomEditor` intercepts high-priority combos first (escape, ctrl-c/d/z, ctrl-v, ctrl-p variants, ctrl-t, alt-up, extension custom keys) and delegates the rest to base `Editor` behavior (text editing, history, autocomplete, cursor movement).\n\n`InputController.setupKeyHandlers()` then binds editor callbacks to mode actions:\n\n- cancellation / mode exits on `Escape`\n- shutdown on double `Ctrl+C` or empty-editor `Ctrl+D`\n- suspend/resume on `Ctrl+Z`\n- slash-command and selector hotkeys\n- follow-up/dequeue toggles and expansion toggles\n\nThis keeps key parsing/editor mechanics in `packages/tui` and mode semantics in coding-agent controllers.\n\n## Render loop and diffing strategy\n\n`TUI.requestRender()` is debounced to one render per tick using `process.nextTick`. Multiple state changes in the same turn coalesce.\n\n`#doRender()` pipeline:\n\n1. Render root component tree to `newLines`.\n2. Composite visible overlays (if any).\n3. Extract and strip `CURSOR_MARKER` from visible viewport lines.\n4. Append segment reset suffixes for non-image lines.\n5. Choose a viewport repaint, full repaint, or differential patch:\n - real process terminals repaint the visible viewport for width/height changes, forced renders, and edits above the live viewport so native scrollback is not cleared/replayed; host markers refine policy only after this process-terminal capability is established;\n - virtual/headless terminals retain full clear/replay regardless of inherited terminal-host environment markers, keeping historical buffer repair deterministic;\n - steady-state visible changes use differential patches, including viewport repaint when a contraction exposes earlier transcript rows.\n6. For differential updates, patch only changed line ranges and clear stale trailing lines when needed.\n7. Reposition hardware cursor for IME support.\n\nRender writes use synchronized output mode (`CSI ? 2026 h/l`) to reduce flicker/tearing.\n\n## Render safety constraints\n\nCritical safety checks in `TUI`:\n\n- Non-image rendered lines are expected to fit terminal width; the differential path truncates overwide lines as a last-resort guard and can write debug diagnostics when redraw debugging is enabled.\n- Overlay compositing includes defensive truncation and post-composite width guarding.\n- Width changes re-render wrapped content; real process terminals limit emission to the visible viewport because their native scrollback position is not observable.\n- Cursor position is clamped before movement.\n\nThese constraints are runtime guards plus component conventions; renderers should still return width-safe lines rather than rely on truncation.\n\n## Virtual viewport (default-on, `PI_TUI_VIRTUAL_VIEWPORT`)\n\nBy default `#doRender` reuses the previous normalized off-screen prefix and only normalizes/diffs the visible window (terminal rows + a small overscan) when the terminal width is unchanged and the off-screen raw prefix is unchanged from the previous frame. This bounds steady-state append/edit work on very long sessions / weak hardware while preserving byte-identical output.\n\nSet `PI_TUI_VIRTUAL_VIEWPORT=0` (or `false`) to opt out and restore the legacy path that normalizes/truncates and diffs the full rendered transcript every frame (`O(total lines)`). The fast path compares the off-screen raw prefix by raw value equality per line, which short-circuits to a fast reference check when components return stable string instances for unchanged lines; reused entries are deterministic normalizations of identical raw lines. Any width change, off-screen edit, forced render (`requestRender(true)`), or first frame transparently falls back to the full path. `PI_TUI_METRICS` exposes `lineCounts` gauges (`rendered`, `normalized`, `measured`, `diffed`, and `offscreenScan`) to observe the bound.\n\n### Manual transcript scrolling and sticky composer\n\n`CustomEditor` routes `PageUp` and `PageDown` to `TUI.scrollViewportPages()` when autocomplete is not active. Page keys move by the visible transcript lane height minus one; SGR mouse-wheel input moves by `DEFAULT_WHEEL_LINES` (three rows). The TUI records semantic anchors for eligible transcript rows so a manually selected viewport can survive streaming updates, content contraction, and width-dependent reflow.\n\nWhile manual ownership is active, `statusLine` and every following direct child (hooks, editor, pet floor) remain fixed at the bottom. The transcript scrolls only in the remaining rows. If semantic output changes while the user is reviewing history, the TUI shows `New output — type to follow`; reflow and transient chrome changes do not trigger it. Ordinary composer input and paste preserve the existing policy: focus stays on the editor, then `followLiveViewport()` returns to current output before processing the input.\n\nSome rendered pages contain no semantic rows—for example, a page made entirely of tool output or transient panels. Paging into such a page switches manual viewport ownership to the numeric transcript offset instead of rejecting the keypress. Paging back to eligible transcript content establishes a fresh semantic anchor. Pinned chrome and the notice are outside transcript selection/copy coordinates. Under constrained height, the notice and decorative pet/low-priority rows are dropped before the focused editor and status content.\n\nManual-era output remains authoritative in the application transcript but is not retroactively replayed into native terminal/tmux scrollback when following live. Later ordinary live output may naturally move current tail rows into host history.\n\nWhen a downward movement (wheel or `PageDown`) in `scrollViewportBy` clamps to the true maximum transcript top for the current effective manual capacity, the TUI transitions through the existing `followLiveViewport()` transaction instead of painting another manual frame. This makes the bottom reachable through both discrete wheel steps and full-page jumps: a partial downward movement that does not reach the bottom retains manual ownership and the new-output notice, and upward movement never follows. The transition reuses the same live-follow path that ordinary composer input triggers, so focus, pinned chrome, manual-anchor clearing, notice clearing, and fatal terminal transaction semantics remain consistent. Manual-era output is never replayed into native/host scrollback on the transition; the next new semantic output appends through the live frontier exactly once.\n\n### PR1 semantic revision and observer safety\n\nA visible, capped IRC sidebar contributes its semantic projection to the manual-viewport new-output revision even when it produces no inline transcript component. The revision advances only for actual semantic output: duplicate, elided, hidden, geometry-only, and theme-only changes do not show the notice. Re-submitting an equal output source is a no-render operation. When the pinned suffix is constrained, the renderer selects its suffix rows without copying the full transcript-length prefix.\n\n`Session Observer` reads only stable source snapshots. It retains an incomplete append until a complete JSONL line is available, validates replacement candidates before publishing them, and clears cached transcript/model/tool content when the source is replaced, truncated, deleted, unreadable, or malformed. This is source-acquisition safety only: the observer still eagerly rebuilds full-history transcript projections, so its memory and refresh work remain `O(total observed history)`. PR1 does not add projection virtualization or bounded full-history memory.\n\n`PI_TUI_METRICS` structural counters are opt-in deterministic evidence. Timing and RSS samples are advisory observations, not release thresholds.\n\n## Resize handling\n\nResize events are event-driven from `ProcessTerminal` to `TUI.requestResizeRender()`.\n\nEffects:\n\n- Real process terminals repaint only the visible viewport on width/height changes, avoiding scrollback-hostile clear/replay cycles; known host markers and the legacy multiplexer override refine this process-terminal policy.\n- Virtual/headless terminals retain full redraw regardless of inherited host markers for deterministic buffer repair.\n- Viewport/top tracking avoids invalid relative cursor math when content or terminal size changes.\n- Overlay visibility can depend on terminal dimensions (`OverlayOptions.visible`); focus is corrected when overlays become non-visible after resize.\n\n## Streaming and incremental UI updates\n\n`EventController` subscribes to `AgentSessionEvent` and updates UI incrementally:\n\n- `agent_start`: starts loader in `statusContainer`.\n- `message_start` assistant: creates `streamingComponent` and mounts it.\n- `message_update`: updates streaming assistant content; creates/updates tool execution components as tool calls appear.\n- `tool_execution_update/end`: updates tool result components and completion state.\n- `message_end`: finalizes assistant stream, handles aborted/error annotations, marks pending tool args complete on normal stop.\n- `agent_end`: stops loaders, clears transient stream state, flushes deferred model switch, issues terminal completion notification if backgrounded, and runs the user-level completion command hook when configured.\n\nRead-tool grouping is intentionally stateful (`#lastReadGroup`) to coalesce consecutive read tool calls into one visual block until a non-read break occurs.\n\n## Status and loader orchestration\n\nStatus lane ownership:\n\n- `statusContainer` holds transient loaders (`loadingAnimation`, `autoCompactionLoader`, `retryLoader`).\n- `statusLine` renders persistent status/hooks/plan indicators and drives editor top border updates.\n\nLoader behavior:\n\n- `Loader` updates every 80ms via interval and requests render each frame.\n- Escape handlers are temporarily overridden during auto-compaction and auto-retry to cancel those operations.\n- On end/cancel paths, controllers restore prior escape handlers and stop/clear loader components.\n\n## Mode transitions and backgrounding\n\n### Bash/Python input modes\n\nInput text prefixes toggle editor border mode flags:\n\n- `!` -> bash mode\n- `$` (non-template literal prefix) -> python mode\n\nEscape exits inactive mode by clearing editor text and restoring border color; when execution is active, escape aborts the running task instead.\n\n### Plan mode\n\n`InteractiveMode` tracks plan mode flags, status-line state, active tools, and model switching. Enter/exit updates session mode entries and status/UI state, including deferred model switch if streaming is active.\n\n### Suspend/resume (`Ctrl+Z`)\n\n`InputController.handleCtrlZ()`:\n\n1. Registers one-shot `SIGCONT` handler to restart TUI and force render.\n2. Stops TUI before suspend.\n3. Sends `SIGTSTP` to process group.\n\n### Background mode (`/background` or `/bg`)\n\n`handleBackgroundCommand()`:\n\n- Rejects when idle.\n- Switches tool UI context to non-interactive (`hasUI=false`) so interactive UI tools fail fast.\n- Stops loaders/status line and unsubscribes foreground event handler.\n- Subscribes background event handler (primarily waits for `agent_end`).\n- Stops TUI and sends `SIGTSTP` (POSIX job control path).\n\nOn `agent_end` in background with no queued work, controller sends the terminal completion notification and shuts down. The configured `completion.notifyCommand` hook is not limited to background mode; it runs on completed agent turns so local tools such as cmux can receive foreground and background completion events.\n\n## Cancellation paths\n\nPrimary cancellation inputs:\n\n- `Escape` during active stream loader: restores queued messages to editor and aborts agent.\n- `Escape` during bash/python execution: aborts running command.\n- `Escape` during auto-compaction/retry: invokes dedicated abort methods through temporary escape handlers.\n- `Ctrl+C` single press: clear editor; double press within 500ms: shutdown.\n\nCancellation is state-conditional; same key can mean abort, mode-exit, selector trigger, or no-op depending on runtime state.\n\n## Event-driven vs throttled behavior\n\nEvent-driven updates:\n\n- Agent session events (`EventController`)\n- Key input callbacks (`InputController`)\n- terminal resize callback\n- terminal appearance callbacks, SIGWINCH theme reevaluation, and git branch watchers in `InteractiveMode`\n\nThrottled/debounced paths:\n\n- TUI rendering is tick-debounced (`requestRender` coalescing).\n- Loader animation is fixed-interval (80ms), each frame requesting render.\n- Editor autocomplete updates (inside `Editor`) use debounce timers, reducing recompute churn during typing.\n\nThe runtime therefore mixes event-driven state transitions with bounded render cadence to keep interactivity responsive without repaint storms.\n",
140
- "ui-design-visual-qa.md": "# UI design and visual QA workflow\n\nThis is the repo-owned contract for future Sayknow-CLI UI, web, dashboard, terminal, and TUI visual work. It adapts the useful OMO design-reference and visual-QA workflow without vendoring any third-party design corpus.\n\nIt is not a fifth bundled workflow skill. Sayknow-CLI's public workflow surface remains `deep-interview`, `ralplan`, `ultragoal`, and `team`. Frontend UI/UX craft itself is handled by the bundled UI skills under `packages/coding-agent/src/defaults/skc/ui-skills` (`emil-design-eng`, `animate`, and siblings); this document is the SKC-owned visual-QA process for SKC's own TUI/dashboard surfaces, used inside those workflows or direct implementation.\n\n## Required branch before implementation\n\nBefore writing broad UI code, choose and record exactly one workflow branch in the plan, issue update, PR body, or local `DESIGN.md`:\n\n1. **Existing design system** — the repository or product area already has a `DESIGN.md`, component system, theme, or comparable visual grammar. Read it first and update it when the change extends the system.\n2. **Greenfield selected references** — no usable system exists, so pick a small shortlist of design references before implementation. Record the exact references loaded and translate them into first-party project guidance; do not copy raw vendor files into the repo.\n3. **Extract existing system first** — the surface exists but its rules are implicit. The first deliverable is a minimal `DESIGN.md` that extracts the current tokens, layout grammar, component anatomy, and state rules before new product screens are built.\n\nA UI task that skips this branch selection is not ready for implementation.\n\n## `DESIGN.md` source material\n\nNew UI work must create or update the nearest product `DESIGN.md` before broad product-screen implementation. The document must be first-party source material for the implementation, not a screenshot dump or mood board. Include:\n\n- **Tokens** — colors, typography, spacing, radii, borders, iconography, density, terminal color roles, and accessibility contrast constraints.\n- **Layout grammar** — grids, page regions, navigation, hierarchy, rhythm, empty space, alignment, and composition rules.\n- **Component anatomy** — named parts, slots, content rules, affordances, constraints, and when not to use the component.\n- **States** — default, hover, active, focus, disabled, loading, empty, error, selected, expanded/collapsed, and permission/connection failure states where relevant.\n- **Motion and depth** — animation timing/easing, transitions, shadows/elevation, overlays, focus movement, and reduced-motion behavior.\n- **Responsive behavior** — mobile, tablet, desktop, narrow terminal, wide terminal, font scaling, wrapping, overflow, and high-density layouts.\n\nFor greenfield selected references, `DESIGN.md` must name the selected references and explain what was translated from each into the first-party system. It must not embed raw third-party corpus text as the system of record.\n\n## Component showcase before product screens\n\nBuild or update a component showcase/state harness before implementing broad product screens. The harness may be Storybook, a local route, a CLI/TUI fixture, a docs page with runnable examples, or a purpose-built screenshot fixture, but it must expose the component states needed by the product surface.\n\nThe harness must cover:\n\n- all states listed in `DESIGN.md` that the component supports;\n- representative realistic content, including long strings, empty content, error copy, and localization-sensitive text;\n- mobile/tablet/desktop or narrow/medium/wide terminal layouts as applicable;\n- keyboard focus and accessibility-visible states for interactive components.\n\nProduct screens can follow only after the harness proves the component vocabulary is stable enough to reuse.\n\n## Visual QA contract\n\nVisual QA is completion evidence, not decoration. A UI story is not done until it has fresh full-surface evidence from the current branch.\n\nRequired evidence:\n\n- **Fresh capture** — evidence must be generated after the current implementation, not reused from an older branch, design reference, or unrelated run.\n- **Full-surface coverage** — capture every page, route, modal, drawer, tab, breakpoint, component state, and error/empty/loading state in scope. Sampling a few representative screenshots is not enough.\n- **No hidden tails** — scrollable surfaces require evidence for top, middle, bottom, sticky regions, overflow behavior, and any virtualized content boundaries.\n- **CJK semantic line breaks block completion** — Korean, Japanese, Chinese, and mixed CJK/Latin copy must not wrap in semantically broken or visually misleading ways. Bad CJK line breaks are blocking defects, not cosmetic polish.\n- **Independent review before done** — a reviewer or review lane that did not author the implementation must inspect the full evidence set against `DESIGN.md`, the component harness, and acceptance criteria before the work is marked complete.\n- **Evidence references** — PRs should link or attach the current evidence artifacts instead of describing them only in prose.\n\n## Terminal and TUI evidence\n\nTerminal/TUI visual work must preserve terminal semantics in future helper flows. Until Sayknow-CLI has a dedicated helper, terminal visual-QA evidence must document the exact helper requirements and avoid flattening away the data needed for review.\n\nA terminal/TUI evidence helper must produce, at minimum:\n\n- `terminal.txt` with readable plain text;\n- `terminal-ansi.txt` preserving ANSI SGR color/style sequences and terminal control semantics needed for replay/review;\n- `terminal.html` rendering the ANSI-styled output for browser review;\n- optional `terminal.png` generated from the styled rendering when image evidence is useful;\n- `metadata.json` containing command or replay source, terminal size, font/rendering assumptions, capture timestamp, tool version, wrapping/truncation policy, and whether the artifact is from a live PTY, replay, or fixture.\n\nReviewers must reject terminal/TUI evidence that only contains flattened text when the change depends on color, emphasis, cursor state, layout, wrapping, or other ANSI/terminal behavior.\n\n## Provenance boundary\n\nDo not vendor raw third-party design corpora, screenshots, brand guides, prompt packs, or critique/reference material into this repository without an explicit materializer and provenance design.\n\nAllowed in a first PR:\n\n- first-party `DESIGN.md` guidance written for Sayknow-CLI;\n- a small hand-written reference index that names public sources and records why they were consulted;\n- pinned links, citations, or manifests that do not copy raw third-party corpus content.\n\nRequires explicit design before inclusion:\n\n- raw third-party corpus files;\n- copied design-system text, screenshots, or asset packs;\n- submodules or generated materialized corpora;\n- generated screenshots committed as durable source assets.\n\nA future materializer design must define source ownership, license/provenance metadata, pinning strategy, reproducible generation, update review, generated-file boundaries, and what artifacts are safe to attach to GitHub without committing.\n\n## PR checklist\n\nFor UI work, include this checklist in the PR body or equivalent review artifact:\n\n- [ ] UI workflow branch selected: existing `DESIGN.md`, greenfield selected references, or extract existing system first.\n- [ ] `DESIGN.md` created/updated with tokens, layout grammar, component anatomy, states, motion/depth, and responsive behavior.\n- [ ] Component showcase/state harness exists before broad product screens.\n- [ ] Fresh full-surface visual evidence covers every in-scope page/state/breakpoint; no sampling.\n- [ ] CJK semantic line breaks were checked and any defects were fixed before completion.\n- [ ] Terminal/TUI evidence preserves ANSI semantics or documents the exact helper requirements above.\n- [ ] Independent review inspected the evidence before the work was marked done.\n- [ ] No raw third-party corpus was vendored without an explicit materializer/provenance design.\n",
140
+ "ui-design-visual-qa.md": "# UI design and visual QA workflow\n\nThis is the repo-owned contract for future Sayknow-CLI UI, web, dashboard, terminal, and TUI visual work. It adapts the useful OMO design-reference and visual-QA workflow without vendoring any third-party design corpus.\n\nIt is not a fifth bundled workflow skill. Sayknow-CLI's public workflow surface remains `deep-interview`, `ralplan`, `ultragoal`, and `team`. Frontend UI/UX craft itself is handled by the bundled UI skills under `packages/coding-agent/src/defaults/skc/ui-skills` (`stageshow` as the design center, then `emil-design-eng`, `animate`, and siblings); this document is the SKC-owned visual-QA process for SKC's own TUI/dashboard surfaces, used inside those workflows or direct implementation.\n\n## Required branch before implementation\n\nBefore writing broad UI code, choose and record exactly one workflow branch in the plan, issue update, PR body, or local `DESIGN.md`:\n\n1. **Existing design system** — the repository or product area already has a `DESIGN.md`, component system, theme, or comparable visual grammar. Read it first and update it when the change extends the system.\n2. **Greenfield selected references** — no usable system exists, so pick a small shortlist of design references before implementation. Record the exact references loaded and translate them into first-party project guidance; do not copy raw vendor files into the repo.\n3. **Extract existing system first** — the surface exists but its rules are implicit. The first deliverable is a minimal `DESIGN.md` that extracts the current tokens, layout grammar, component anatomy, and state rules before new product screens are built.\n\nA UI task that skips this branch selection is not ready for implementation.\n\n## `DESIGN.md` source material\n\nNew UI work must create or update the nearest product `DESIGN.md` before broad product-screen implementation. The document must be first-party source material for the implementation, not a screenshot dump or mood board. Include:\n\n- **Tokens** — colors, typography, spacing, radii, borders, iconography, density, terminal color roles, and accessibility contrast constraints.\n- **Layout grammar** — grids, page regions, navigation, hierarchy, rhythm, empty space, alignment, and composition rules.\n- **Component anatomy** — named parts, slots, content rules, affordances, constraints, and when not to use the component.\n- **States** — default, hover, active, focus, disabled, loading, empty, error, selected, expanded/collapsed, and permission/connection failure states where relevant.\n- **Motion and depth** — animation timing/easing, transitions, shadows/elevation, overlays, focus movement, and reduced-motion behavior.\n- **Responsive behavior** — mobile, tablet, desktop, narrow terminal, wide terminal, font scaling, wrapping, overflow, and high-density layouts.\n\nFor greenfield selected references, `DESIGN.md` must name the selected references and explain what was translated from each into the first-party system. It must not embed raw third-party corpus text as the system of record.\n\n## Component showcase before product screens\n\nBuild or update a component showcase/state harness before implementing broad product screens. The harness may be Storybook, a local route, a CLI/TUI fixture, a docs page with runnable examples, or a purpose-built screenshot fixture, but it must expose the component states needed by the product surface.\n\nThe harness must cover:\n\n- all states listed in `DESIGN.md` that the component supports;\n- representative realistic content, including long strings, empty content, error copy, and localization-sensitive text;\n- mobile/tablet/desktop or narrow/medium/wide terminal layouts as applicable;\n- keyboard focus and accessibility-visible states for interactive components.\n\nProduct screens can follow only after the harness proves the component vocabulary is stable enough to reuse.\n\n## Visual QA contract\n\nVisual QA is completion evidence, not decoration. A UI story is not done until it has fresh full-surface evidence from the current branch.\n\nRequired evidence:\n\n- **Fresh capture** — evidence must be generated after the current implementation, not reused from an older branch, design reference, or unrelated run.\n- **Full-surface coverage** — capture every page, route, modal, drawer, tab, breakpoint, component state, and error/empty/loading state in scope. Sampling a few representative screenshots is not enough.\n- **No hidden tails** — scrollable surfaces require evidence for top, middle, bottom, sticky regions, overflow behavior, and any virtualized content boundaries.\n- **CJK semantic line breaks block completion** — Korean, Japanese, Chinese, and mixed CJK/Latin copy must not wrap in semantically broken or visually misleading ways. Bad CJK line breaks are blocking defects, not cosmetic polish.\n- **Independent review before done** — a reviewer or review lane that did not author the implementation must inspect the full evidence set against `DESIGN.md`, the component harness, and acceptance criteria before the work is marked complete.\n- **Evidence references** — PRs should link or attach the current evidence artifacts instead of describing them only in prose.\n\n## Terminal and TUI evidence\n\nTerminal/TUI visual work must preserve terminal semantics in future helper flows. Until Sayknow-CLI has a dedicated helper, terminal visual-QA evidence must document the exact helper requirements and avoid flattening away the data needed for review.\n\nA terminal/TUI evidence helper must produce, at minimum:\n\n- `terminal.txt` with readable plain text;\n- `terminal-ansi.txt` preserving ANSI SGR color/style sequences and terminal control semantics needed for replay/review;\n- `terminal.html` rendering the ANSI-styled output for browser review;\n- optional `terminal.png` generated from the styled rendering when image evidence is useful;\n- `metadata.json` containing command or replay source, terminal size, font/rendering assumptions, capture timestamp, tool version, wrapping/truncation policy, and whether the artifact is from a live PTY, replay, or fixture.\n\nReviewers must reject terminal/TUI evidence that only contains flattened text when the change depends on color, emphasis, cursor state, layout, wrapping, or other ANSI/terminal behavior.\n\n## Provenance boundary\n\nDo not vendor raw third-party design corpora, screenshots, brand guides, prompt packs, or critique/reference material into this repository without an explicit materializer and provenance design.\n\nAllowed in a first PR:\n\n- first-party `DESIGN.md` guidance written for Sayknow-CLI;\n- a small hand-written reference index that names public sources and records why they were consulted;\n- pinned links, citations, or manifests that do not copy raw third-party corpus content.\n\nRequires explicit design before inclusion:\n\n- raw third-party corpus files;\n- copied design-system text, screenshots, or asset packs;\n- submodules or generated materialized corpora;\n- generated screenshots committed as durable source assets.\n\nA future materializer design must define source ownership, license/provenance metadata, pinning strategy, reproducible generation, update review, generated-file boundaries, and what artifacts are safe to attach to GitHub without committing.\n\n## PR checklist\n\nFor UI work, include this checklist in the PR body or equivalent review artifact:\n\n- [ ] UI workflow branch selected: existing `DESIGN.md`, greenfield selected references, or extract existing system first.\n- [ ] `DESIGN.md` created/updated with tokens, layout grammar, component anatomy, states, motion/depth, and responsive behavior.\n- [ ] Component showcase/state harness exists before broad product screens.\n- [ ] Fresh full-surface visual evidence covers every in-scope page/state/breakpoint; no sampling.\n- [ ] CJK semantic line breaks were checked and any defects were fixed before completion.\n- [ ] Terminal/TUI evidence preserves ANSI semantics or documents the exact helper requirements above.\n- [ ] Independent review inspected the evidence before the work was marked done.\n- [ ] No raw third-party corpus was vendored without an explicit materializer/provenance design.\n",
141
141
  };
@@ -21,7 +21,7 @@ Explore just enough context, implement the smallest correct change, and leave co
21
21
  - Explore first, ask last. Ask only when progress is impossible or the next decision is destructive, credentialed, external-production, or materially scope-changing.
22
22
  - Use normal repository inspection for file/symbol/pattern lookup. Do not recommend deprecated repository-explore workflows.
23
23
  - Respect repository instructions, especially no new dependencies unless explicitly requested.
24
- - For frontend UI/UX, animation, visual polish, or component-craft work, invoke the matching bundled UI skill (`emil-design-eng`, `animate`, `review-animations`, `improve-animations`, `find-animation-opportunities`, `pick-ui-library`, `prototype`, `mobile-native`, `appllama-app-design-skill` for native Expo/React Native screens, `ask-sonner`, `apple-design`, `animation-vocabulary`) before implementing. Do not ask the user to install these skills.
24
+ - For frontend UI/UX, animation, visual polish, component-craft, or faux product UI work, invoke `stageshow` first (the design center for every frontend surface, real product UI included), then the matching bundled UI skill (`emil-design-eng`, `animate`, `review-animations`, `improve-animations`, `find-animation-opportunities`, `pick-ui-library`, `prototype`, `mobile-native`, `appllama-app-design-skill` for native Expo/React Native screens, `ask-sonner`, `apple-design`, `animation-vocabulary`) before implementing. Do not ask the user to install these skills.
25
25
  </constraints>
26
26
 
27
27
  <execution_loop>
@@ -26,7 +26,7 @@ Optimize for correctness first, maintainability second, and brevity third. Prefe
26
26
  - Clear work with non-trivial architecture or sequencing risk uses `/skill:ralplan --deliberate` and stops pending approval.
27
27
  - Use `/skill:ultragoal` for durable goal ledgers and `/skill:team` for approved coordinated persistent work.
28
28
  - Delegate large implementation slices to `executor`; use `planner`, `architect`, or `critic` for bounded planning and review.
29
- - Frontend UI/UX work (web, dashboard, mobile web, native app screens, animation, visual polish, component craft) MUST invoke the matching bundled UI skill before writing or reviewing that surface: `emil-design-eng` for general UI/UX, `animate` for new motion, `review-animations` / `improve-animations` / `find-animation-opportunities` for motion review/audit/opportunity, `pick-ui-library` for library choice, `prototype` for variant exploration, `mobile-native` for phone-web native feel, `appllama-app-design-skill` for native Expo/React Native app screens, `ask-sonner` for Sonner toasts, `apple-design` for Apple-style motion/materials, `animation-vocabulary` for naming a motion effect. These are bundled; do not ask the user to install them. They are not workflow skills and do not use `skc state`.
29
+ - Frontend UI/UX work (web, dashboard, mobile web, native app screens, animation, visual polish, component craft, faux product UI) MUST invoke `stageshow` first — the design center for every frontend surface, real product UI included — and then the matching bundled UI skill before writing or reviewing that surface: `emil-design-eng` for general UI/UX, `animate` for new motion, `review-animations` / `improve-animations` / `find-animation-opportunities` for motion review/audit/opportunity, `pick-ui-library` for library choice, `prototype` for variant exploration, `mobile-native` for phone-web native feel, `appllama-app-design-skill` for native Expo/React Native app screens, `ask-sonner` for Sonner toasts, `apple-design` for Apple-style motion/materials, `animation-vocabulary` for naming a motion effect. These are bundled; do not ask the user to install them. They are not workflow skills and do not use `skc state`.
30
30
  - Active skills are authoritative: never ignore an invoked skill; read the full skill text and follow it exactly.
31
31
  - Before explicit execution approval, planning and interview workflows NEVER edit product source, run mutating shell commands, commit, push, open PRs, or delegate implementation.
32
32
  </routing>
@@ -415,9 +415,9 @@ import {
415
415
  hasAutoResumeMarkerSinceLastUser,
416
416
  hasVisibleFailedPrefix,
417
417
  INTERRUPTED_TOOL_RESULT_TEXT,
418
+ isAnswerlessFailure,
418
419
  isRestartSafeTool,
419
420
  isSynthesizedResumeResult,
420
- isThinkingOnlyFailure,
421
421
  RESTART_RESUME_MAX_REQUESTS,
422
422
  RESTART_RESUME_WINDOW_MS,
423
423
  resolveAutoResumePolicy,
@@ -943,8 +943,12 @@ type RetryErrorClassification =
943
943
 
944
944
  const BARE_DEFAULT_WATCHDOG_ERROR =
945
945
  /^(?:[A-Za-z][A-Za-z0-9-]*(?: [A-Za-z][A-Za-z0-9-]*){0,3} )stream (?:timed out while waiting for the first event|stalled while waiting for the next event)$/;
946
- /** Server-side overload/unavailability wording. Bare numbers never count: "500 requests per minute" is a throttle. */
947
- const BARE_DEFAULT_SERVER_OVERLOAD_ERROR = /overloaded|service.?unavailable|internal.?server.?error|\bapi_error\b/i;
946
+ /**
947
+ * Server-side failure wording. Bare numbers never count: "500 requests per minute" is a throttle.
948
+ * Covers xAI's code-less "Internal error during token generation" stream error.
949
+ */
950
+ const BARE_DEFAULT_SERVER_OVERLOAD_ERROR =
951
+ /overloaded|service.?unavailable|internal.?(?:server.?)?error|\bapi_error\b/i;
948
952
  /** Throttle or quota wording, in any phrasing a provider uses for it. */
949
953
  const BARE_DEFAULT_THROTTLE_ERROR =
950
954
  /rate.?limit|too many requests|quota|usage.?limit|requests? per (?:second|minute|hour|day)|\b(?:rpm|tpm|rpd)\b|throttl/i;
@@ -999,7 +1003,7 @@ function hasBareDefaultRetryDisqualifyingFacts(message: AssistantMessage): boole
999
1003
 
1000
1004
  function assistantMessageHasVisibleOrToolContent(message: AssistantMessage): boolean {
1001
1005
  return message.content.some(content => {
1002
- if (content.type === "text") return content.text.length > 0;
1006
+ if (content.type === "text") return content.text.trim().length > 0;
1003
1007
  return content.type === "thinking" || content.type === "redactedThinking" || content.type === "toolCall";
1004
1008
  });
1005
1009
  }
@@ -14999,16 +15003,16 @@ export class AgentSession {
14999
15003
  // A text-only tail on a verified serializer continues on the same model;
15000
15004
  // any other public tail (tool calls, images, tainted run) stops with the
15001
15005
  // output preserved for the user to resume explicitly. A failure that streamed
15002
- // only reasoning holds no answer and its signed blocks cannot be replayed: it
15003
- // is dropped and retried like a failure that showed nothing.
15004
- const thinkingOnlyFailure = !managedOutcome && isThinkingOnlyFailure(message);
15006
+ // only reasoning or blank text holds no answer (and signed reasoning cannot be
15007
+ // replayed): it is dropped and retried like a failure that showed nothing.
15008
+ const noAnswerFailure = !managedOutcome && isAnswerlessFailure(message);
15005
15009
  // Tool calls cut off by the failure never ran (see #withoutUnexecutedToolCallFailure):
15006
15010
  // without answer text the attempt is dropped like a reasoning-only failure.
15007
15011
  const unexecutedToolCallFailure =
15008
15012
  !managedOutcome &&
15009
15013
  this.agent.state.messages.findLast(item => item.role === "assistant") === message &&
15010
15014
  this.#withoutUnexecutedToolCallFailure() !== undefined;
15011
- const answerlessFailure = thinkingOnlyFailure || unexecutedToolCallFailure;
15015
+ const answerlessFailure = noAnswerFailure || unexecutedToolCallFailure;
15012
15016
  const visibleFailure = !managedOutcome && !answerlessFailure && assistantMessageHasVisibleOrToolContent(message);
15013
15017
  const visibleContinuation = visibleFailure && this.#canContinueVisibleFailure(message);
15014
15018
  if (visibleFailure && !visibleContinuation) return false;
@@ -15865,7 +15869,7 @@ export class AgentSession {
15865
15869
  placeholders.length === 0 &&
15866
15870
  tailMessage?.role === "assistant" &&
15867
15871
  (tailMessage.stopReason === "error" || tailMessage.stopReason === "aborted") &&
15868
- (isThinkingOnlyFailure(tailMessage) || !assistantMessageHasVisibleOrToolContent(tailMessage))
15872
+ (isAnswerlessFailure(tailMessage) || !assistantMessageHasVisibleOrToolContent(tailMessage))
15869
15873
  ) {
15870
15874
  this.agent.replaceMessages(this.agent.state.messages.slice(0, -1));
15871
15875
  }
@@ -16092,8 +16096,7 @@ export class AgentSession {
16092
16096
  // Explicit retry does not establish the outcome of an interrupted operation
16093
16097
  // and is never permission to erase a prefix already shown to the user. A failure
16094
16098
  // that streamed only reasoning holds no answer and is dropped like an empty one.
16095
- if (!isThinkingOnlyFailure(assistantMsg) && assistantMessageHasVisibleOrToolContent(assistantMsg))
16096
- return false;
16099
+ if (!isAnswerlessFailure(assistantMsg) && assistantMessageHasVisibleOrToolContent(assistantMsg)) return false;
16097
16100
  if (assistantMsg.stopReason !== "error" && assistantMsg.stopReason !== "aborted") return false;
16098
16101
 
16099
16102
  // Remove the empty failed/aborted assistant message before re-attempting.
@@ -58,18 +58,20 @@ export interface AutoResumeMarker {
58
58
  }
59
59
 
60
60
  /**
61
- * A failed attempt that streamed only private reasoning: no answer text, no tool call.
62
- * Nothing in it is part of the answer and its signed blocks can never be replayed, so
63
- * recovery drops it and asks the same model again instead of stopping.
61
+ * A failed attempt that streamed no answer: only private reasoning and/or blank text
62
+ * (e.g. a whitespace decode loop the provider then aborted), no tool call. Nothing in
63
+ * it is part of the answer and its signed blocks can never be replayed, so recovery
64
+ * drops it and asks the same model again instead of stopping.
64
65
  */
65
- export function isThinkingOnlyFailure(message: AgentMessage | undefined): boolean {
66
+ export function isAnswerlessFailure(message: AgentMessage | undefined): boolean {
66
67
  if (message?.role !== "assistant" || message.stopReason !== "error") return false;
67
- let thinking = false;
68
+ let streamed = false;
68
69
  for (const block of message.content) {
69
- if (block.type === "thinking" || block.type === "redactedThinking") thinking = true;
70
+ if (block.type === "thinking" || block.type === "redactedThinking") streamed = true;
70
71
  else if (block.type !== "text" || block.text.trim().length > 0) return false;
72
+ else if (block.text.length > 0) streamed = true;
71
73
  }
72
- return thinking;
74
+ return streamed;
73
75
  }
74
76
 
75
77
  /**
@@ -170,7 +172,7 @@ function hasUnsafeAssistantTail(messages: readonly AgentMessage[]): boolean {
170
172
  if (assistantIndex === -1 || assistantIndex < messages.findLastIndex(message => message.role === "user"))
171
173
  return false;
172
174
  const assistant = messages[assistantIndex] as AssistantMessage;
173
- if ((assistant.stopReason === "error" || assistant.stopReason === "aborted") && !isThinkingOnlyFailure(assistant)) {
175
+ if ((assistant.stopReason === "error" || assistant.stopReason === "aborted") && !isAnswerlessFailure(assistant)) {
174
176
  if (
175
177
  assistant.content.some(
176
178
  block => block.type === "thinking" || block.type === "redactedThinking" || block.type === "toolCall",
@@ -193,7 +195,7 @@ export function hasVisibleFailedPrefix(messages: readonly AgentMessage[]): boole
193
195
  return false;
194
196
  const assistant = messages[assistantIndex] as AssistantMessage;
195
197
  if (assistant.stopReason !== "error" && assistant.stopReason !== "aborted") return false;
196
- return assistant.content.some(block => block.type === "text" && block.text.length > 0);
198
+ return assistant.content.some(block => block.type === "text" && block.text.trim().length > 0);
197
199
  }
198
200
 
199
201
  export interface AutoResumePolicyInput {