@tea-agent/loop-agent 0.13.0 → 0.14.0

package/skills/browser-tools/package.json

@@ -1,19 +1,19 @@
-{
-	"name": "browser-tools",
-	"version": "1.0.0",
-	"type": "module",
-	"description": "Minimal CDP tools for collaborative site exploration",
-	"author": "Mario Zechner",
-	"license": "MIT",
-	"dependencies": {
-		"@mozilla/readability": "^0.6.0",
-		"cheerio": "^1.1.2",
-		"jsdom": "^27.0.1",
-		"puppeteer": "^24.31.0",
-		"puppeteer-core": "^23.11.1",
-		"puppeteer-extra": "^3.3.6",
-		"puppeteer-extra-plugin-stealth": "^2.11.2",
-		"turndown": "^7.2.2",
-		"turndown-plugin-gfm": "^1.0.2"
-	}
-}
+{
+	"name": "browser-tools",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "Minimal CDP tools for collaborative site exploration",
+	"author": "Mario Zechner",
+	"license": "MIT",
+	"dependencies": {
+		"@mozilla/readability": "^0.6.0",
+		"cheerio": "^1.1.2",
+		"jsdom": "^27.0.1",
+		"puppeteer": "^24.31.0",
+		"puppeteer-core": "^23.11.1",
+		"puppeteer-extra": "^3.3.6",
+		"puppeteer-extra-plugin-stealth": "^2.11.2",
+		"turndown": "^7.2.2",
+		"turndown-plugin-gfm": "^1.0.2"
+	}
+}

package/skills/code-review-core/SKILL.md

@@ -1,20 +1,20 @@
----
-name: code-review-core
-description: 用于只读 code review 节点，产出带文件与行号引用的优先级 findings。
----
-
-# Code Review Core
-
-本 skill 用于 reviewer 节点。
-
-## Review 重点
-
-- 优先关注 correctness、行为回归、security、数据丢失与缺失验证。
-- findings 须 grounded 在具体文件与行号。
-- 区分 blocking findings 与次要 maintainability 备注。
-- 检查测试是否证明变更行为，文档是否与面向用户的变更一致。
-- 若无 findings，明确说明，并指出 residual test gap（如有）。
-
-## Output
-
-按 severity 排序列出 findings。仅当无 blocking findings 时，才写 `VERDICT: pass`。
+---
+name: code-review-core
+description: 用于只读 code review 节点，产出带文件与行号引用的优先级 findings。
+---
+
+# Code Review Core
+
+本 skill 用于 reviewer 节点。
+
+## Review 重点
+
+- 优先关注 correctness、行为回归、security、数据丢失与缺失验证。
+- findings 须 grounded 在具体文件与行号。
+- 区分 blocking findings 与次要 maintainability 备注。
+- 检查测试是否证明变更行为，文档是否与面向用户的变更一致。
+- 若无 findings，明确说明，并指出 residual test gap（如有）。
+
+## Output
+
+按 severity 排序列出 findings。仅当无 blocking findings 时，才写 `VERDICT: pass`。

package/skills/codebase-scout/SKILL.md

@@ -1,19 +1,19 @@
----
-name: codebase-scout
-description: 用于只读 scout 节点，在实现前定位现有代码、测试、文档与集成点。
----
-
-# Codebase Scout
-
-本 skill 用于 scout 节点。
-
-## 规则
-
-- 从 repo 指令、task source 与邻近测试入手。
-- 可用时优先 CodeGraph；否则用 `rg` 与聚焦文件阅读。
-- 在提议新抽象前，识别现有 helper 与 ownership 边界。
-- 只返回事实，不做编辑。
-
-## Output
-
-列出相关文件、现有模式、风险，以及实现所需的最小 write surface。
+---
+name: codebase-scout
+description: 用于只读 scout 节点，在实现前定位现有代码、测试、文档与集成点。
+---
+
+# Codebase Scout
+
+本 skill 用于 scout 节点。
+
+## 规则
+
+- 从 repo 指令、task source 与邻近测试入手。
+- 可用时优先 CodeGraph；否则用 `rg` 与聚焦文件阅读。
+- 在提议新抽象前，识别现有 helper 与 ownership 边界。
+- 只返回事实，不做编辑。
+
+## Output
+
+列出相关文件、现有模式、风险，以及实现所需的最小 write surface。

package/skills/frontend-design-review/SKILL.md

@@ -1,66 +1,66 @@
----
-name: frontend-design-review
-description: Use for the frontend plan design gate before any writer runs.
-references:
-  - path: references/review-checklist.md
-    required: true
-    maxChars: 3600
----
-
-# Frontend Design Review
-
-For first/final design review nodes. Read the checklist, then audit contract, scout,
-mock strategy, plan/revision, task constraints/bounds, and traceable design evidence. The knowledge-
-base connector is TODO: never invent results. If absent/failed/unmatched, require
-`<repoRoot>/openSpec/**` search/read evidence before repo conventions.
-
-## Verdict Contract
-
-First non-empty line: exactly `VERDICT: pass` or `VERDICT: request-revision`.
-Any blocker requires request-revision; the shell gate reads this line exactly.
-
-For `frontend-final-design-review-pi`: recheck the original plan when output is
-`PASS_NO_REVISION_NEEDED`; otherwise verify every Required Plan Correction. Reject
-remaining, incomplete, or newly introduced gaps.
-
-## Blocking Conditions
-
-- Any criterion lacks implementation/verification; UI states lack reasons; a
-  dependency lacks permission; confirmed primitives/rules are ignored; design claims
-  lack knowledge-base or required `openSpec/` evidence; paths cross write bounds;
-  commands are missing/non-deterministic; or interaction, responsive, accessibility,
-  data, or failure behavior requires guessing.
-- `MOCK_STRATEGY: blocked`; missing permitted target paths, endpoint/schema-to-fixture
-  mapping, fixed verification, or dev/test-only activation; a second Mock framework;
-  inline fake data; commented real requests; Mock-on production defaults; test-only
-  production imports; or Mock evidence reported as real integration.
-
-Knowledge-base absence is advisory if relevant `openSpec/` rules were searched/read
-and applied. Block skipped fallback, unresolved conflict, or unresolved UI decisions.
-
-## Method And Output
-
-Map criteria to steps/files/states/checks, audit paths/evidence, classify Blocking or
-Advisory, and never edit files.
-
-### Spec Evidence Rules
-
-Run `grep`/`find`, then explicit `read` calls for applicable specs and checklist.
-Only successful paired reads count as “已读取规范文件”; summaries do not. List each
-read path/section in `Checked Items`. If the connector is unavailable, search/read
-`openSpec/` before accepting repository conventions.
-
-```markdown
-VERDICT: pass
-
-## Findings
-- None blocking.
-
-## Required Plan Corrections
-- None.
-
-## Checked Items
-- ...
-```
-
-Each correction names its criterion/section, gap, and exact plan change.
+---
+name: frontend-design-review
+description: Use for the frontend plan design gate before any writer runs.
+references:
+  - path: references/review-checklist.md
+    required: true
+    maxChars: 3600
+---
+
+# Frontend Design Review
+
+For first/final design review nodes. Read the checklist, then audit contract, scout,
+mock strategy, plan/revision, task constraints/bounds, and traceable design evidence. The knowledge-
+base connector is TODO: never invent results. If absent/failed/unmatched, require
+`<repoRoot>/openSpec/**` search/read evidence before repo conventions.
+
+## Verdict Contract
+
+First non-empty line: exactly `VERDICT: pass` or `VERDICT: request-revision`.
+Any blocker requires request-revision; the shell gate reads this line exactly.
+
+For `frontend-final-design-review-pi`: recheck the original plan when output is
+`PASS_NO_REVISION_NEEDED`; otherwise verify every Required Plan Correction. Reject
+remaining, incomplete, or newly introduced gaps.
+
+## Blocking Conditions
+
+- Any criterion lacks implementation/verification; UI states lack reasons; a
+  dependency lacks permission; confirmed primitives/rules are ignored; design claims
+  lack knowledge-base or required `openSpec/` evidence; paths cross write bounds;
+  commands are missing/non-deterministic; or interaction, responsive, accessibility,
+  data, or failure behavior requires guessing.
+- `MOCK_STRATEGY: blocked`; missing permitted target paths, endpoint/schema-to-fixture
+  mapping, fixed verification, or dev/test-only activation; a second Mock framework;
+  inline fake data; commented real requests; Mock-on production defaults; test-only
+  production imports; or Mock evidence reported as real integration.
+
+Knowledge-base absence is advisory if relevant `openSpec/` rules were searched/read
+and applied. Block skipped fallback, unresolved conflict, or unresolved UI decisions.
+
+## Method And Output
+
+Map criteria to steps/files/states/checks, audit paths/evidence, classify Blocking or
+Advisory, and never edit files.
+
+### Spec Evidence Rules
+
+Run `grep`/`find`, then explicit `read` calls for applicable specs and checklist.
+Only successful paired reads count as “已读取规范文件”; summaries do not. List each
+read path/section in `Checked Items`. If the connector is unavailable, search/read
+`openSpec/` before accepting repository conventions.
+
+```markdown
+VERDICT: pass
+
+## Findings
+- None blocking.
+
+## Required Plan Corrections
+- None.
+
+## Checked Items
+- ...
+```
+
+Each correction names its criterion/section, gap, and exact plan change.

package/skills/frontend-design-review/references/review-checklist.md

@@ -1,58 +1,58 @@
-# Frontend Design Review Checklist
-
-## Requirement And State Coverage
-
-- Target route/page/component and non-goals are clear.
-- Every acceptance criterion maps to steps, files, UI behavior, and verification.
-- Assumptions and unresolved ambiguity are explicit.
-- Applicable success, error, loading, empty, disabled, permission, retry, stale-response, and boundary states are handled or marked N/A.
-
-## Project And Knowledge Fit
-
-- Existing components, hooks, API helpers, mocks, schemas, router patterns, templates, tokens, and theme rules were considered.
-- Component/design choices cite knowledge-base or `openSpec/`; failed/empty knowledge-base queries recurse through `<repoRoot>/openSpec/**` first.
-- Evidence records source status, query terms, paths/headings, and conflicts.
-- Dependencies are authorized; paths fit allowed/write scope and avoid forbidden/generated files.
-- A required Mock-backed strategy reuses native support when proven, otherwise an
-  existing browser-intercept/request-adapter seam; it maps endpoint/states to fixtures,
-  stays in writer scope, and is off in production. `not-needed` adds none.
-
-## Interaction And Quality
-
-- Actions, feedback, validation timing, navigation, persistence, and recovery are unambiguous.
-- Responsive and overflow behavior covers target environments.
-- Keyboard, focus, semantics, contrast, reduced motion, data lifecycle, cancellation, and error recovery are addressed when applicable.
-
-## Verification
-
-- Static and behavior commands are exact, discoverable, and deterministic.
-- Tests prove changed state logic and flows at repository-supported levels.
-- Browser/visual checks are required only by task intent or existing gates.
-- Every missing verification path is a blocker or disclosed risk.
-- Verification entrypoints are frozen; any Mock-specific command is generated only
-  from trusted sources, and behavior separately proves page consumption.
-
-## Mock Strategy Safety
-
-- The strategy protocol is valid and not `MOCK_STRATEGY: blocked`.
-- For Mock strategies, API fields and fixture states trace to contract evidence; gaps are explicit.
-- Selection follows repository capability: native mock first, browser interception
-  for existing e2e, request adapter/injection for local preview.
-- The real request remains enabled by default; activation is explicit, reversible,
-  local/test-only, and excluded from production behavior.
-- Verification uses only shell entrypoints fixed when the DAG was generated; the
-  plan does not invent commands that shell nodes cannot execute.
-- Mock strategies include a production/default-real-path build with Mock off and
-  Mock-backed behavior evidence. `not-needed` instead needs applicable real or
-  no-remote behavior evidence.
-- Mock-backed checks prove frontend states only. Real integration remains pending
-  until the actual backend path has fresh evidence.
-
-## Verdict Matrix
-
-- Coverage gap, unsafe scope, unauthorized dependency, unresolved required interaction, or missing required verification: request revision.
-- Missing knowledge-base evidence and skipped `openSpec/` fallback: request revision.
-- No relevant knowledge-base or `openSpec/` rule for a required decision: request revision.
-- Unsafe/missing mock strategy or mock evidence presented as real integration: request revision.
-- Knowledge-base unavailable but relevant `openSpec/` rules were applied: advisory connection gap, not a specification gap.
-- Optional cleanup that cannot affect acceptance: advisory.
+# Frontend Design Review Checklist
+
+## Requirement And State Coverage
+
+- Target route/page/component and non-goals are clear.
+- Every acceptance criterion maps to steps, files, UI behavior, and verification.
+- Assumptions and unresolved ambiguity are explicit.
+- Applicable success, error, loading, empty, disabled, permission, retry, stale-response, and boundary states are handled or marked N/A.
+
+## Project And Knowledge Fit
+
+- Existing components, hooks, API helpers, mocks, schemas, router patterns, templates, tokens, and theme rules were considered.
+- Component/design choices cite knowledge-base or `openSpec/`; failed/empty knowledge-base queries recurse through `<repoRoot>/openSpec/**` first.
+- Evidence records source status, query terms, paths/headings, and conflicts.
+- Dependencies are authorized; paths fit allowed/write scope and avoid forbidden/generated files.
+- A required Mock-backed strategy reuses native support when proven, otherwise an
+  existing browser-intercept/request-adapter seam; it maps endpoint/states to fixtures,
+  stays in writer scope, and is off in production. `not-needed` adds none.
+
+## Interaction And Quality
+
+- Actions, feedback, validation timing, navigation, persistence, and recovery are unambiguous.
+- Responsive and overflow behavior covers target environments.
+- Keyboard, focus, semantics, contrast, reduced motion, data lifecycle, cancellation, and error recovery are addressed when applicable.
+
+## Verification
+
+- Static and behavior commands are exact, discoverable, and deterministic.
+- Tests prove changed state logic and flows at repository-supported levels.
+- Browser/visual checks are required only by task intent or existing gates.
+- Every missing verification path is a blocker or disclosed risk.
+- Verification entrypoints are frozen; any Mock-specific command is generated only
+  from trusted sources, and behavior separately proves page consumption.
+
+## Mock Strategy Safety
+
+- The strategy protocol is valid and not `MOCK_STRATEGY: blocked`.
+- For Mock strategies, API fields and fixture states trace to contract evidence; gaps are explicit.
+- Selection follows repository capability: native mock first, browser interception
+  for existing e2e, request adapter/injection for local preview.
+- The real request remains enabled by default; activation is explicit, reversible,
+  local/test-only, and excluded from production behavior.
+- Verification uses only shell entrypoints fixed when the DAG was generated; the
+  plan does not invent commands that shell nodes cannot execute.
+- Mock strategies include a production/default-real-path build with Mock off and
+  Mock-backed behavior evidence. `not-needed` instead needs applicable real or
+  no-remote behavior evidence.
+- Mock-backed checks prove frontend states only. Real integration remains pending
+  until the actual backend path has fresh evidence.
+
+## Verdict Matrix
+
+- Coverage gap, unsafe scope, unauthorized dependency, unresolved required interaction, or missing required verification: request revision.
+- Missing knowledge-base evidence and skipped `openSpec/` fallback: request revision.
+- No relevant knowledge-base or `openSpec/` rule for a required decision: request revision.
+- Unsafe/missing mock strategy or mock evidence presented as real integration: request revision.
+- Knowledge-base unavailable but relevant `openSpec/` rules were applied: advisory connection gap, not a specification gap.
+- Optional cleanup that cannot affect acceptance: advisory.

package/skills/frontend-implementation/SKILL.md

@@ -1,49 +1,49 @@
----
-name: frontend-implementation
-description: >-
-  Use for frontend contract, scout, mock strategy, plan, and implementation DAG nodes.
-references:
-  - path: references/node-contracts.md
-    required: true
-    # Compact contract index must stay under skill total budget (~10k with body + other refs).
-    # Headroom above current ~4k file; do not raise alone without checking totalMaxChars.
-    maxChars: 6000
-  - path: references/design-spec.md
-    required: true
-    maxChars: 3000
-  - path: references/code-standards.md
-    required: true
-    maxChars: 3000
----
-
-# Frontend Implementation
-
-Read all required references before running any listed frontend node.
-
-## Source And Evidence Rules
-
-Use task sources/references, constraints, then `task.json`. Follow `design-spec.md`:
-knowledge base; `<repoRoot>/openSpec/**` after unavailable/failed/empty; then repo
-evidence. Cite tight paths/symbols, label gaps/conflicts, and never invent APIs,
-rules, commands, or retrievals. Scout/planners locate and explicitly read applicable
-specs; only successful paired reads count. Lockfile-only, fixture-only, or unread
-search hits do not prove a reusable Mock service.
-
-## Implementation Discipline
-
-- Reuse confirmed specs, components, tokens, helpers, APIs, mocks, schemas, and tests.
-- Keep real requests enabled by default; never comment them out for a mock.
-- Prefer native Mock support; otherwise use existing browser interception for e2e or
-  a reversible request adapter/DI seam for local preview.
-- Trace fixtures to API/schema evidence. Activation is explicit, dev/test-only,
-  production-off; Mock evidence never proves real API integration.
-- Add dependencies only when approved. Cover applicable success/loading/empty/error/
-  permission/boundary states and justify N/A.
-- Keep state testable. Stay in `writeSet`, preserve behavior, and update tests.
-- Never relax lint/type/test/build config or write unauthorized generated output.
-
-## Output And Failure Rules
-
-- Follow `node-contracts.md`; read-only nodes never edit. Missing input blocks work
-  when proceeding would guess behavior, bounds, or verification.
-- Preserve tokens, commands, paths, IDs, and language. Completion needs fresh shell evidence.
+---
+name: frontend-implementation
+description: >-
+  Use for frontend contract, scout, mock strategy, plan, and implementation DAG nodes.
+references:
+  - path: references/node-contracts.md
+    required: true
+    # Compact contract index must stay under skill total budget (~10k with body + other refs).
+    # Headroom above current ~4k file; do not raise alone without checking totalMaxChars.
+    maxChars: 6000
+  - path: references/design-spec.md
+    required: true
+    maxChars: 3000
+  - path: references/code-standards.md
+    required: true
+    maxChars: 3000
+---
+
+# Frontend Implementation
+
+Read all required references before running any listed frontend node.
+
+## Source And Evidence Rules
+
+Use task sources/references, constraints, then `task.json`. Follow `design-spec.md`:
+knowledge base; `<repoRoot>/openSpec/**` after unavailable/failed/empty; then repo
+evidence. Cite tight paths/symbols, label gaps/conflicts, and never invent APIs,
+rules, commands, or retrievals. Scout/planners locate and explicitly read applicable
+specs; only successful paired reads count. Lockfile-only, fixture-only, or unread
+search hits do not prove a reusable Mock service.
+
+## Implementation Discipline
+
+- Reuse confirmed specs, components, tokens, helpers, APIs, mocks, schemas, and tests.
+- Keep real requests enabled by default; never comment them out for a mock.
+- Prefer native Mock support; otherwise use existing browser interception for e2e or
+  a reversible request adapter/DI seam for local preview.
+- Trace fixtures to API/schema evidence. Activation is explicit, dev/test-only,
+  production-off; Mock evidence never proves real API integration.
+- Add dependencies only when approved. Cover applicable success/loading/empty/error/
+  permission/boundary states and justify N/A.
+- Keep state testable. Stay in `writeSet`, preserve behavior, and update tests.
+- Never relax lint/type/test/build config or write unauthorized generated output.
+
+## Output And Failure Rules
+
+- Follow `node-contracts.md`; read-only nodes never edit. Missing input blocks work
+  when proceeding would guess behavior, bounds, or verification.
+- Preserve tokens, commands, paths, IDs, and language. Completion needs fresh shell evidence.

package/skills/frontend-implementation/references/code-standards.md

@@ -1,32 +1,32 @@
-# Frontend Code Standards
-
-Discover rules from task constraints, `design-spec.md` source order, config, code,
-tests, manifests, and generated types. After knowledge-base failure, applicable
-`<repoRoot>/openSpec/**` rules are normative. Preferences are not rules, and docs do
-not override installed APIs without an explicit compatibility decision.
-
-## Discover And Cite
-
-- Find routing and server/client boundaries; state, forms, data/cache, and errors;
-  API/mock/UI/schema/test locations and naming; supported tests; dependency rules.
-
-Cite representative files/config for each convention. Describe conflicts instead of
-silently selecting one.
-
-## Plan And Implement
-
-- Map criteria to code and checks. Define placement, state ownership, request
-  lifecycle, validation/failures, API compatibility, mocks, and fixtures.
-- Trace fixtures to API evidence; label gaps. Prefer native mocks, then browser
-  interception for existing e2e, then a reversible request adapter/DI preview seam.
-- Real API stays default; mock activation is explicit, local/test-only,
-  non-production, and removable.
-- Reuse helpers/public APIs and preserve out-of-contract behavior. Keep rendering,
-  transitions, validation, and side effects testable; cover lifecycle races/bounds
-  when relevant. Update supported tests; stay in `writeSet`.
-
-## Prohibited
-
-- Do not relax checks, add unapproved dependencies, comment real requests, hardcode
-  fixtures in production UI, import test mocks into production, store fixture
-  secrets, equate mock evidence with real integration, or report unrun checks as verified.
+# Frontend Code Standards
+
+Discover rules from task constraints, `design-spec.md` source order, config, code,
+tests, manifests, and generated types. After knowledge-base failure, applicable
+`<repoRoot>/openSpec/**` rules are normative. Preferences are not rules, and docs do
+not override installed APIs without an explicit compatibility decision.
+
+## Discover And Cite
+
+- Find routing and server/client boundaries; state, forms, data/cache, and errors;
+  API/mock/UI/schema/test locations and naming; supported tests; dependency rules.
+
+Cite representative files/config for each convention. Describe conflicts instead of
+silently selecting one.
+
+## Plan And Implement
+
+- Map criteria to code and checks. Define placement, state ownership, request
+  lifecycle, validation/failures, API compatibility, mocks, and fixtures.
+- Trace fixtures to API evidence; label gaps. Prefer native mocks, then browser
+  interception for existing e2e, then a reversible request adapter/DI preview seam.
+- Real API stays default; mock activation is explicit, local/test-only,
+  non-production, and removable.
+- Reuse helpers/public APIs and preserve out-of-contract behavior. Keep rendering,
+  transitions, validation, and side effects testable; cover lifecycle races/bounds
+  when relevant. Update supported tests; stay in `writeSet`.
+
+## Prohibited
+
+- Do not relax checks, add unapproved dependencies, comment real requests, hardcode
+  fixtures in production UI, import test mocks into production, store fixture
+  secrets, equate mock evidence with real integration, or report unrun checks as verified.

package/skills/frontend-implementation/references/design-spec.md

@@ -1,46 +1,46 @@
-# Frontend Design And Component Specification
-
-## Required Source Sequence
-
-1. Attempt the configured component/design knowledge-base query first.
-2. If unavailable, failed, timed out, or unmatched, recursively search the project root's exact `openSpec/` directory.
-3. Treat relevant matches as the current project's specification for this run.
-4. Only then use component source, tokens, stories, tests, and pages as non-normative repository fallback.
-
-Never skip `openSpec/` directly to neighboring-code conventions. Report source
-conflicts instead of combining them. Explicit task requirements remain the contract;
-flag conflicts with knowledge-base or `openSpec/` rules.
-
-## Knowledge Base Connection — TODO
-
-Request format is undecided. TODO: define connector/owner, namespaces, secret-free
-auth, query fields, result identity/version/time, and failure behavior.
-
-Attempt only a connector actually available in the execution environment. Otherwise
-record `not-configured` and run the `openSpec/` fallback; never invent a connection.
-
-## `openSpec/` Fallback Procedure
-
-- Confirm whether `<repoRoot>/openSpec/` exists and enumerate its files recursively.
-- Read indexes first, then search names/content using task, route, component, interaction, theme, token, and state terms.
-- Read relevant matches in context; do not treat a filename-only hit as a rule.
-- Record search terms, inspected/matched paths, headings or tight line ranges, applied rules, and conflicts.
-- If the directory or relevant rules are absent, record that fact before using repository fallback.
-
-## Retrieval Evidence
-
-Record source as `knowledge-base`, `openSpec fallback`, `repository fallback`, or
-`unavailable`. Knowledge-base evidence includes query, source ID/version/time, rules,
-and conflicts. `openSpec fallback` includes terms, paths/headings/lines, rules, and conflicts.
-
-## Rules To Retrieve Or Discover
-
-- Components, variants, props, composition, accessibility, deprecations, placement, forms, overlays, navigation, and state patterns.
-- Tokens, typography, color, layout, breakpoints, motion, focus/keyboard/contrast, exceptions, design debt, and forbidden patterns.
-
-## Gate Expectations
-
-- Reuse confirmed primitives unless a new pattern is authorized.
-- Define applicable states and responsive behavior before implementation.
-- Cite knowledge-base or `openSpec/` evidence for component/token choices; label weaker repository fallback.
-- Make deviations and unresolved gaps explicit.
+# Frontend Design And Component Specification
+
+## Required Source Sequence
+
+1. Attempt the configured component/design knowledge-base query first.
+2. If unavailable, failed, timed out, or unmatched, recursively search the project root's exact `openSpec/` directory.
+3. Treat relevant matches as the current project's specification for this run.
+4. Only then use component source, tokens, stories, tests, and pages as non-normative repository fallback.
+
+Never skip `openSpec/` directly to neighboring-code conventions. Report source
+conflicts instead of combining them. Explicit task requirements remain the contract;
+flag conflicts with knowledge-base or `openSpec/` rules.
+
+## Knowledge Base Connection — TODO
+
+Request format is undecided. TODO: define connector/owner, namespaces, secret-free
+auth, query fields, result identity/version/time, and failure behavior.
+
+Attempt only a connector actually available in the execution environment. Otherwise
+record `not-configured` and run the `openSpec/` fallback; never invent a connection.
+
+## `openSpec/` Fallback Procedure
+
+- Confirm whether `<repoRoot>/openSpec/` exists and enumerate its files recursively.
+- Read indexes first, then search names/content using task, route, component, interaction, theme, token, and state terms.
+- Read relevant matches in context; do not treat a filename-only hit as a rule.
+- Record search terms, inspected/matched paths, headings or tight line ranges, applied rules, and conflicts.
+- If the directory or relevant rules are absent, record that fact before using repository fallback.
+
+## Retrieval Evidence
+
+Record source as `knowledge-base`, `openSpec fallback`, `repository fallback`, or
+`unavailable`. Knowledge-base evidence includes query, source ID/version/time, rules,
+and conflicts. `openSpec fallback` includes terms, paths/headings/lines, rules, and conflicts.
+
+## Rules To Retrieve Or Discover
+
+- Components, variants, props, composition, accessibility, deprecations, placement, forms, overlays, navigation, and state patterns.
+- Tokens, typography, color, layout, breakpoints, motion, focus/keyboard/contrast, exceptions, design debt, and forbidden patterns.
+
+## Gate Expectations
+
+- Reuse confirmed primitives unless a new pattern is authorized.
+- Define applicable states and responsive behavior before implementation.
+- Cite knowledge-base or `openSpec/` evidence for component/token choices; label weaker repository fallback.
+- Make deviations and unresolved gaps explicit.