@thinkingai/ae-cli 6.1.24 → 6.1.26

package/skills/ae-agent/references/create-automation.md

@@ -1,125 +0,0 @@
-# agent +create-automation (Create Automation)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Automations / write**
-
-```text
-Transition status: transitional
-Owning module: te-claude automation
-Current transport: POST /api/sandbox/agent/automations
-Gateway target: TBD (no equivalent Gateway capability is currently registered)
-Review after: 2026-10-07
-Exit condition: Migrate when the Gateway exposes equivalent workspace-scoped automation creation.
-```
-
-## Use Cases
-- Create an Agent automation task that runs on a schedule (hourly / daily / weekly / monthly or cron).
-- Returns the newly created automation object including its `id` and initial `status`.
-- Automations are **enabled by default**; pass `--enabled false` only when the user explicitly asks to create the task without enabling it.
-- Automations create a new conversation for every run by default. Pass `--reuse-conversation true` only when the user explicitly wants future runs to continue in one conversation.
-
-## Mandatory Rules (MUST)
-- `--name` and `--message` are required.
-- A schedule is required: provide either `--cron` or a `--schedule-kind` (with its time/day fields). `--cron` and `--schedule-kind` are mutually exclusive.
-- `--agent-id` and `--agent-name` are mutually exclusive. Obtain a real Agent ID via `+list-agents` — do not guess.
-- In a chat runtime, omitted `--conversation-id`, `--agent-id`, and `--model` values fall back to `TE_AGENT_CONVERSATION_ID`, `TE_AGENT_CURRENT_AGENT_ID`, and `TE_AGENT_CURRENT_MODEL_ID`. Explicit flags always take precedence; `--agent-name` intentionally suppresses the current Agent ID fallback.
-- Workspace selection is independent of Agent selection: `--agent-space-id` explicitly selects the workspace. If omitted, the server inherits the accessible conversation's workspace when available, otherwise the personal default workspace. The CLI intentionally omits `agentSpaceId` in this case to preserve inheritance and compatibility with earlier servers.
-- Workspace-aware servers return `automation.agentSpaceId`. Pass that ID to subsequent `+list-automations` and `+update-automation` calls; those commands otherwise use the personal default workspace, even when invoked from a conversation.
-- On servers without workspace support, omit `--agent-space-id` and keep the original creation flow. If the response lacks `agentSpaceId`, omit the flag in later calls rather than inventing an ID. Older servers may ignore the new parameter; it does not add workspace isolation to them.
-- This command creates Agent automations only. It does not create Agent Team scheduled tasks.
-- JSON flags must be valid JSON strings, usually wrapped in single quotes in shell.
-- This is an ordinary `write` operation and does not require CLI confirmation.
-- Do not surface raw automation IDs, raw JSON, or concrete detail paths in user-facing replies.
-
-## Schedule Kinds
-| `--schedule-kind` | Required fields | Notes |
-|---|---|---|
-| `hourly` | `--minute` (optional, 0–59) | Runs every hour at the given minute |
-| `daily` | `--time HH:mm` | Runs once a day at the given time |
-| `weekly` | `--time HH:mm`, `--weekday 0-6` | `0` = Sunday |
-| `monthly` | `--time HH:mm`, `--day-of-month 1-28` | Day 1–28 only |
-
-## Command
-```bash
-# Enabled daily automation (default)
-ae-cli agent +create-automation \
-  --name "Daily AI Brief" \
-  --schedule-kind daily \
-  --time 09:00 \
-  --message "Summarize yesterday's AI news"
-
-# Create but keep paused when the user explicitly asks not to enable it
-ae-cli agent +create-automation \
-  --name "Daily AI Brief" \
-  --schedule-kind daily \
-  --time 09:00 \
-  --message "Summarize yesterday's AI news" \
-  --enabled false
-
-# Keep future runs in one visible conversation
-ae-cli agent +create-automation \
-  --name "Daily AI Brief" \
-  --schedule-kind daily \
-  --time 09:00 \
-  --message "Summarize yesterday's AI news" \
-  --reuse-conversation true
-
-# Weekly schedule on Sunday
-ae-cli agent +create-automation \
-  --name "Weekly Report" \
-  --schedule-kind weekly \
-  --time 10:00 \
-  --weekday 0 \
-  --message "Generate the weekly report"
-
-# Cron expression
-ae-cli agent +create-automation \
-  --name "Cron Task" \
-  --cron "0 9 * * 1-5" \
-  --message "Weekday morning brief"
-
-# Dry-run to inspect the request before executing
-ae-cli agent +create-automation --dry-run --name "Test" --message "x" --schedule-kind daily --time 09:00
-
-# Select a workspace explicitly
-ae-cli agent +create-automation --name "Daily Report" --message "Prepare the report" \
-  --agent-id <agent-id> --agent-space-id <workspace-id> --schedule-kind daily --time 09:00
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--name` | Yes | Automation task name |
-| `--message` | Yes | Instruction sent to the Agent |
-| `--cron` | No* | Cron expression (mutually exclusive with `--schedule-kind`) |
-| `--schedule-kind` | No* | `hourly` \| `daily` \| `weekly` \| `monthly` |
-| `--time` | No | Time in `HH:mm` for daily/weekly/monthly |
-| `--minute` | No | Minute 0–59 for hourly schedules |
-| `--weekday` | No | Weekday 0–6 for weekly schedules; `0` is Sunday |
-| `--day-of-month` | No | Day 1–28 for monthly schedules |
-| `--agent-id` | No | Agent ID; defaults to current conversation Agent |
-| `--agent-name` | No | Agent name; use only after `+list-agents` discovery |
-| `--model` | No | Model record ID; defaults to current selected model |
-| `--enabled` | No | `true` (default) \| `false` |
-| `--reuse-conversation` | No | `true` to continue in one conversation; `false` (default) to create one per run |
-| `--conversation-id` | No | Conversation ID fallback for resolving the Agent and workspace |
-| `--agent-space-id` | No | Explicit workspace ID; omit to inherit the conversation's workspace, otherwise use the personal default workspace |
-
-\* One of `--cron` or `--schedule-kind` is required.
-
-## Decision Rules
-- If the user provides a natural-language schedule ("every day at 9am"), translate it to `--schedule-kind daily --time 09:00`.
-- If the user wants a cron-only schedule not covered by the kinds, use `--cron`.
-- If no Agent is specified, the automation targets the current conversation's Agent; verify with `+list-agents` when in doubt.
-- Set `--reuse-conversation true` only when the user explicitly requests continuity across runs. The platform may rotate the underlying provider session while retaining the visible conversation history.
-- Use `--dry-run` first to verify the request shape before executing.
-
-## Next Steps on Failure
-- `必须提供 --cron 或 --schedule-kind`: provide one of the schedule flags.
-- `--time 格式必须是 HH:mm`: use 24-hour `HH:mm` (e.g. `09:00`).
-- `--agent-id 与 --agent-name 只能二选一`: pick one and remove the other.
-- After success, capture the returned `automation.id` and, when present, `automation.agentSpaceId` for subsequent list/update calls. Omit the workspace flag when the ID is `null` or absent.
-
-## Recommended Chaining
-- `+list-agents` → `+create-automation` → `+list-automations` (verify) → `+update-automation` (edit)

package/skills/ae-agent/references/list-automations.md

@@ -1,56 +0,0 @@
-# agent +list-automations (List Automations)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Automations / read**
-
-```text
-Transition status: transitional
-Owning module: te-claude automation
-Current transport: GET /api/sandbox/agent/automations
-Gateway target: TBD (no equivalent Gateway capability is currently registered)
-Review after: 2026-10-07
-Exit condition: Migrate when the Gateway exposes equivalent workspace-scoped automation listing.
-```
-
-## Use Cases
-- List the current user's Agent automation tasks in one workspace.
-- Returns `items` containing automation summaries; key fields include `id`, `name`, `status`, `cronExpression`, `agentSpaceId`, and `agentSpaceName`.
-- Agent Team scheduled tasks shown alongside automations in the workspace UI are a separate resource and are not returned by this command.
-- Use this to discover a real automation ID before `+update-automation`.
-
-## Mandatory Rules (MUST)
-- Do not guess automation IDs. Always call `+list-automations` first when an automation ID is needed.
-- Pass `--agent-space-id` for a non-default workspace. Omitting it lists the personal default workspace, including legacy tasks without a workspace ID; it does not list all workspaces or infer the current conversation's workspace.
-- Keep the same workspace ID when calling `+update-automation`. An automation created from a conversation may belong to a non-default workspace; use the returned `automation.agentSpaceId` when verifying creation.
-- On servers without workspace support, omit `--agent-space-id`. Listing retains its original user-scoped behavior and responses may lack `agentSpaceId`/`agentSpaceName`; neither field is required by the CLI. Older servers do not enforce the new workspace filter.
-- Do not surface raw automation IDs, raw JSON, or concrete detail paths in user-facing replies — use the ID only internally for subsequent commands.
-
-## Command
-```bash
-ae-cli agent +list-automations
-ae-cli agent +list-automations --status active
-ae-cli agent +list-automations --q "daily" --limit 20 --format table
-ae-cli agent +list-automations --agent-space-id <workspace-id>
-ae-cli agent +list-automations --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--agent-space-id` | No | Workspace ID; omitted means the personal default workspace |
-| `--q` | No | Keyword for automation name or instruction |
-| `--status` | No | `active` \| `paused` |
-| `--limit` | No | Maximum number of automations to return, 1–10000 |
-
-## Decision Rules
-- When the user wants to pause, resume, rename, or edit an automation, call this first to find the target ID.
-- `--status active` lists only enabled automations; `--status paused` lists paused ones.
-- If many automations are returned, summarize by `name` and `status` to help the user pick the right one.
-
-## Next Steps on Failure
-- Empty result: check the active AE host and workspace ID before concluding there are no automations. This command does not include Agent Team scheduled tasks.
-- Auth error: run `ae-cli auth login`.
-
-## Recommended Chaining
-- `+list-automations` → confirm `id` → `+update-automation`

package/skills/ae-agent/references/update-automation.md

@@ -1,107 +0,0 @@
-# agent +update-automation (Update Automation)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Automations / write**
-
-```text
-Transition status: transitional
-Owning module: te-claude automation
-Current transport: PATCH /api/sandbox/agent/automations/:id
-Gateway target: TBD (no equivalent Gateway capability is currently registered)
-Review after: 2026-10-07
-Exit condition: Migrate when the Gateway exposes equivalent workspace-scoped automation updates.
-```
-
-## Use Cases
-- Update an existing Agent automation task's name, instruction, schedule, enabled state, or conversation mode.
-- Used to pause (`--enabled false`) or resume (`--enabled true`) an automation, or to change its schedule/message.
-- Obtain the automation `id` via `+list-automations` — never guess.
-
-## Mandatory Rules (MUST)
-- `--id` is required. Obtain the real ID via `+list-automations` — do not guess.
-- Pass the same `--agent-space-id` used to discover the task, or the `automation.agentSpaceId` returned by creation. Omitting it targets the personal default workspace, including legacy tasks with no workspace ID.
-- The workspace ID is sent as a query parameter to select the task's existing workspace. It is not an update field and cannot move an automation between workspaces; providing it alone is not a valid update.
-- On servers without workspace support, omit `--agent-space-id` and update by the original task ID. Missing workspace fields in older responses do not prevent updates; do not invent an ID or rely on older servers to enforce the new workspace query parameter.
-- Agent Team scheduled task IDs are not automation IDs and cannot be used with this command.
-- At least one update field must be provided (`--name`, `--message`, `--enabled`, `--reuse-conversation`, `--cron`, or a `--schedule-kind` with its time/day fields).
-- `--cron` and `--schedule-kind` are mutually exclusive.
-- This is an ordinary `write` operation and does not require CLI confirmation.
-- Do not surface raw automation IDs, raw JSON, or concrete detail paths in user-facing replies.
-
-## Schedule Kinds (when updating schedule)
-| `--schedule-kind` | Required fields | Notes |
-|---|---|---|
-| `hourly` | `--minute` (optional, 0–59) | Runs every hour at the given minute |
-| `daily` | `--time HH:mm` | Runs once a day at the given time |
-| `weekly` | `--time HH:mm`, `--weekday 0-6` | `0` = Sunday |
-| `monthly` | `--time HH:mm`, `--day-of-month 1-28` | Day 1–28 only |
-
-## Command
-```bash
-# Pause an automation
-ae-cli agent +update-automation --id <automation-id> --enabled false
-
-# Pause an automation in a specific workspace
-ae-cli agent +update-automation --id <automation-id> --agent-space-id <workspace-id> --enabled false
-
-# Resume an automation
-ae-cli agent +update-automation --id <automation-id> --enabled true
-
-# Reuse the most recent valid conversation on future runs
-ae-cli agent +update-automation --id <automation-id> --reuse-conversation true
-
-# Return to creating a new conversation for every run
-ae-cli agent +update-automation --id <automation-id> --reuse-conversation false
-
-# Rename and change the instruction
-ae-cli agent +update-automation \
-  --id <automation-id> \
-  --name "Daily AI Brief v2" \
-  --message "Summarize yesterday's AI news and trends"
-
-# Change the schedule to weekly on Sunday
-ae-cli agent +update-automation \
-  --id <automation-id> \
-  --schedule-kind weekly \
-  --time 10:00 \
-  --weekday 0
-
-# Switch to a cron expression
-ae-cli agent +update-automation --id <automation-id> --cron "0 9 * * 1-5"
-
-# Dry-run to inspect the request before executing
-ae-cli agent +update-automation --dry-run --id <automation-id> --enabled false
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--id` | Yes | Automation task ID from `+list-automations` |
-| `--agent-space-id` | No | Existing workspace ID; omitted means the personal default workspace. Does not move the task |
-| `--name` | No | New automation task name |
-| `--message` | No | New instruction sent to the Agent |
-| `--enabled` | No | `true` to enable, `false` to pause |
-| `--reuse-conversation` | No | `true` to reuse one conversation, `false` to create one per run; omit to keep unchanged |
-| `--cron` | No | Cron expression (mutually exclusive with `--schedule-kind`) |
-| `--schedule-kind` | No | `hourly` \| `daily` \| `weekly` \| `monthly` |
-| `--time` | No | Time in `HH:mm` for daily/weekly/monthly |
-| `--minute` | No | Minute 0–59 for hourly schedules |
-| `--weekday` | No | Weekday 0–6 for weekly schedules; `0` is Sunday |
-| `--day-of-month` | No | Day 1–28 for monthly schedules |
-
-## Decision Rules
-- If the user wants to pause/resume, use `--enabled false` / `--enabled true` (no other fields needed).
-- If the user wants future runs to share one conversation, use `--reuse-conversation true`; use `false` to restore one conversation per run.
-- If the user wants to change the schedule, provide `--schedule-kind` with its required time/day fields, or `--cron`.
-- At least one update field is required; a bare `--id` is rejected.
-- Use `--dry-run` first to verify the request shape before executing.
-
-## Next Steps on Failure
-- `AUTOMATION_NOT_FOUND`: verify the task ID and workspace ID together. Do not retry across other workspaces automatically.
-- `至少提供一个更新字段`: add at least one of `--name` / `--message` / `--enabled` / `--reuse-conversation` / `--cron` / `--schedule-kind`.
-- `必须提供 --cron 或 --schedule-kind`: if schedule detail flags (`--time` / `--minute` / `--weekday` / `--day-of-month`) are present, a `--schedule-kind` (or `--cron`) must accompany them.
-- `--time 格式必须是 HH:mm`: use 24-hour `HH:mm` (e.g. `09:00`).
-
-## Recommended Chaining
-- `+list-automations` → `+update-automation`

package/skills/ae-project-semantic/SKILL.md

@@ -1,193 +0,0 @@
----
-name: ae-project-semantic
-description: "Use when generating, testing, submitting, reviewing, or publishing governed project semantic candidates from AE project asset packages. This skill owns progressive asset-scope consent, recommendation quality gates, evidence authority, topic-domain grouping, candidate JSON generation, CLI closed-loop validation, and frontend review acceptance. Do not use it for ordinary analysis questions that only consume already published semantics."
----
-
-# ae-project-semantic
-
-Project semantics are governed L2 project-wide business concepts, rules, calculation conventions, and default asset-selection methods. They sit above dashboards and reports. Dashboards, reports, events, properties, and metrics are L1 evidence and execution assets; they are not project semantics by themselves.
-
-Use `ae-cli` only. Do not write the database directly for recommendations, approvals, or releases.
-
-## Boundary
-
-- Use this skill to generate or evaluate project semantic recommendations.
-- Use `ae-analysis` to consume already published project semantics during analysis tasks.
-- Frontend can review, edit, approve, reject, and publish candidates; it must not generate recommendations.
-- Start with governed authenticated dashboards/reports. Broader project assets may be inspected only after explicit user consent and must retain their lower authority in evidence and confidence. Events, properties, metrics, background documents, and notes can provide supporting evidence only, never the primary L2 candidate subject.
-
-## Required Workflow
-
-1. Resolve the project and host.
-2. Read both recommendation references before inspecting candidates:
-   - [`references/recommendation-quality.md`](references/recommendation-quality.md) for the governed L2 quality bar;
-   - [`references/query-routing-v5.md`](references/query-routing-v5.md) for the current query-routing, recall-shortcut, and analysis-playbook discovery protocol.
-3. Check existing published project semantics:
-
-```bash
-ae-cli project-semantic list --project-id <project_id>
-```
-
-4. Export governed authenticated project assets and semantic snapshot context by default:
-
-```bash
-ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force
-```
-
-When `--host` points directly to a locally started Common service instead of the deployed analysis gateway, scope the empty gateway domain to that command so the request uses Common's native `/api/cli/v1` route. Do not export this override globally:
-
-```bash
-AE_CLI_CAPABILITY_GATEWAY_DOMAIN= ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force --host http://127.0.0.1:8992
-```
-
-5. Inspect `asset_scope`, `exported_asset_count`, `authenticated_asset_count`, `unauthenticated_asset_count`, `truncated`, work-unit count, and definition-family count before scanning. If `truncated=true`, warn that the package hit a compatibility limit. If the governed package is too sparse to support useful problem frames, report the actual counts and ask whether to re-export active collaborative assets. Do not broaden automatically:
-
-```bash
-ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope collaborative --output <tmp>/project-semantic-assets --force
-```
-
-If that package is still too sparse, report its counts and ask separately whether to export all valid project dashboards/reports and their referenced metadata:
-
-```bash
-ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope all_visible --output <tmp>/project-semantic-assets --force
-```
-
-`governed` is authenticated + collaborative + active in the recent 90-day window. `collaborative` removes only the authentication requirement. `all_visible` removes authentication, collaboration, and recency filters while still excluding deleted, frozen, hidden, offline, or otherwise invalid assets. Export is project-administrator-only; no per-user visibility filtering is required inside `all_visible`. Asset authentication is a separate governance write and must never be changed implicitly by scanning.
-
-6. Read the package in this order:
-   - `manifest.json`, `.asset-package.json`, `catalog/published.jsonl`, `catalog/disabled.jsonl` when present, `catalog/active-candidates.jsonl`, and `catalog/rejected-candidates.jsonl` to build the exclusion and revision context;
-   - `indexes/work-units.jsonl` as the dashboard-first investigation queue, preserving its usage-priority order while rotating across distinct business themes;
-   - `indexes/definition-families.jsonl` and compact dashboard/report records to compare reusable definition variants;
-   - `indexes/asset-directory.jsonl` and `indexes/governance-coverage.jsonl` for supporting evidence;
-   - `details/normalized/**` only for candidate-bearing or conflicting families, and `details/raw/**` only when the normalized definition is insufficient.
-
-   The service owns deterministic parsing, key-field normalization, definition signatures, usage ordering, and catalog assembly. The Agent owns business topic discovery, evidence interpretation, counterexample review, and candidate wording. Display names, descriptions, and notes remain evidence for interpretation, but they never make two otherwise identical definitions distinct. Do not load every detail file into context up front or delegate business judgment to a project-specific keyword table or deterministic template generator.
-
-7. Compare the proposed behavior against published, disabled, active-candidate, and rejected catalogs. Disabled semantics are suppression context: do not consume, recreate, or update them through recommendation generation. A project administrator can explicitly enable them later. Produce `CREATE` only for a genuinely new semantic, `UPDATE` when an active semantic needs a material revision, and no candidate when the package is already covered. Zero new candidates is a valid successful recommendation result.
-
-8. Validate the Agent-authored file against the exact exported package. This command checks only deterministic contract rules such as required fields, supported enums, catalog conflicts, duplicate fingerprints, and resolvable evidence references. `passed=true` is not a semantic-quality approval:
-
-```bash
-ae-cli project-semantic candidate validate --asset-package <tmp>/project-semantic-assets --submit-file <tmp>/project-semantic-candidates.json
-```
-
-9. Perform a separate Agent quality-review pass over the unchanged candidate file and the evidence it cites. Apply the Hard Quality Bar and `references/recommendation-quality.md`; do not rely on the generation pass to approve its own wording. For every candidate, record `PASS`, `REVISE`, or `INSUFFICIENT_EVIDENCE` with concrete findings and evidence references. Revise and repeat both deterministic validation and Agent review until every submitted candidate is `PASS`. A successful empty recommendation is preferable to weak filler.
-
-10. Submit the unchanged validated and Agent-reviewed file. Use `.asset-package.json.snapshot_hash`, or the `snapshot_hash` returned by `candidate validate`:
-
-```bash
-ae-cli project-semantic candidate submit --project-id <project_id> --submit-file <tmp>/project-semantic-candidates.json --snapshot-hash <snapshot_hash>
-```
-
-11. Review and enable through CLI when validating the full closed loop:
-
-```bash
-ae-cli project-semantic candidate list --project-id <project_id>
-ae-cli project-semantic candidate get --project-id <project_id> --candidate-id <candidate_id>
-ae-cli project-semantic candidate enable --project-id <project_id> --candidate-ids '["candidate_1"]'
-ae-cli project-semantic get --project-id <project_id> --id <semantic_id> --mark-used
-```
-
-Lifecycle management is deliberately separate from recommendation review:
-
-```bash
-ae-cli project-semantic disable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
-ae-cli project-semantic list --project-id <project_id> --status disabled
-ae-cli project-semantic delete-impact --project-id <project_id> --semantic-id <semantic_id>
-ae-cli project-semantic delete --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
-ae-cli project-semantic enable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
-```
-
-Disable means “do not consume and do not recommend again.” From disabled state, either enable the same semantic or inspect impact and physically delete it. Physical deletion means the semantic is absent and may be rediscovered by a future scan. Never delete merely to regenerate recommendations.
-
-## Hard Quality Bar
-
-A candidate file is not acceptable unless all of these are true:
-
-- It starts from governed evidence, or records the explicitly approved broader scope and lowers confidence for claims that depend on unauthenticated assets.
-- It groups by L2 business topic domain before generating candidates.
-- Every topic group includes the submit-contract fields `topic_domain_key`, `topic_domain_title`, `topic_group_key`, and `topic_group_title`.
-- It does not create one candidate per asset.
-- It does not promote an event/property/metric name into a project semantic title.
-- Each candidate binds `resource_refs` with real asset names/types/ids or names from the package.
-- Each candidate explains what it means, where it applies, how to use it, and what it excludes.
-- Each candidate body covers business definition, applicable questions, decision or calculation rules, Agent usage, and boundaries or exceptions in the project's natural language. Exact headings are not a machine contract.
-- The concrete business judgment belongs in the decision or calculation content; asset names and counts belong in `resource_refs`, `evidence`, and `recommendation_reason`, not in the semantic body.
-- A batch fails review when candidates reuse the same body with only asset names or counts changed.
-- Each candidate includes evidence excerpts or source titles that show why it was recommended.
-- Each candidate changes how the Agent interprets a business question, selects default assets, or applies a project-wide rule.
-- Each candidate declares one of the evidence-backed recommendation kinds in `query-routing-v5.md`: `QUERY_ROUTING`, `RECALL_SHORTCUT`, or `ANALYSIS_PLAYBOOK`.
-- A formula, threshold, state, event, property, report, or asset name is supporting L1 evidence, never a standalone candidate.
-- A route must contain a meaningful asset-choice branch; a shortcut must contain a minimal bundle plus stop and fallback; a playbook must be note-backed or explicitly labeled as a structure-inferred recommended path.
-- Existing published and disabled semantics are checked before submission; disabled semantics suppress recreation.
-- An unauthenticated asset may support a route, shortcut, or playbook only when definitions, work-unit structure, usage, or notes provide corroboration. Never present it as a certified project rule solely because it was exported.
-- Sparse evidence is either skipped or marked lower confidence; do not inflate weak recommendations.
-
-## Generic Extraction Protocol
-
-The protocol must work unchanged for games, retail, finance, SaaS, operations, and unknown project domains.
-
-1. Inventory evidence without deciding themes. Separate authenticated and unauthenticated dashboards/reports, record the export scope and selection reason, and keep existing governed semantics and supporting L1 metadata distinct.
-2. Discover semantic families only from evidence that was actually read. Use these cross-domain dimensions as questions, not as prefilled answers:
-   - business object, state, and alias;
-   - analysis subject and deduplication grain;
-   - measure, aggregation, numerator, denominator, and transformation;
-   - inclusion, exclusion, and filter scope;
-   - query range, cohort window, observation window, and freshness;
-   - unit, currency, normalization, and attribution;
-   - default asset selection and relationships between assets;
-   - applicability, exception, and conflict boundaries.
-3. Compare definition variants inside each family. A candidate may state a default only when evidence shows one authoritative variant. Conflicting variants require a disambiguation rule or a warning, not an invented standard.
-4. Form a topic domain after the semantic families are understood. The domain title must come from the project's natural business language and explain why its candidates are reviewed together.
-5. Generate a candidate only when removing it would make a future Agent more likely to choose the wrong business object, asset, grain, formula, scope, unit, window, or exception.
-6. For every claim in the body, identify direct supporting evidence. Keep asset names and excerpts in `resource_refs`, `evidence`, and `recommendation_reason`; keep reusable business knowledge in `content`.
-7. Compare candidates by resulting Agent behavior. Merge candidates that lead to the same interpretation and execution; split candidates that answer independently searchable questions.
-8. Run a counterexample pass: inspect minority definitions and assets that may violate the proposed rule. Narrow or drop unsupported conclusions.
-9. Before wording candidates, form evidence-backed problem frames and assign asset roles. Use `query-routing-v5.md`; do not optimize for candidate count or one-candidate-per-asset coverage.
-10. Keep a decision ledger for discovered problem frames, including routed, shortcut, playbook, definition-only, and evidence-insufficient dispositions.
-
-## Anti-Overfitting Rule
-
-- Never encode a customer, project name, project ID, asset ID, expected topic title, expected candidate title, or expected candidate count in this skill or CLI generation code.
-- Never start from a fixed industry taxonomy or keyword dictionary. Keywords may locate evidence only after a semantic family is discovered; they must not determine the result.
-- A test package is an evaluation sample, not a source of reusable rules. Tune the protocol only when the change is defensible across unrelated domains.
-- Quality is measured by evidence support and changed Agent behavior, not by matching a previously approved list of topics.
-
-## User-Facing Recommendation Display
-
-When showing CLI recommendation results to a user, never flatten candidates into a single numbered list. The user-facing answer must use the same hierarchy as the candidate JSON and frontend review UI:
-
-```text
-Project semantic recommendation scan completed
-
-Summary:
-- Topic domains: <N>
-- Candidate semantics: <N>
-- Validation: passed | failed
-
-Topic domain: <topic_domain_title> (<candidate_count> semantics)
-- [<semantic_type>] <candidate title>
-  <one-sentence summary>
-  Evidence: <asset title 1>, <asset title 2>, ...
-```
-
-Rules:
-
-- Show topic domains first, then candidates under each domain.
-- Include each domain's semantic count.
-- Include each candidate's semantic type, title, short summary, and primary evidence asset titles.
-- If the CLI command returns `topic_groups`, use that field directly for the display order and counts.
-- Keep the full JSON path or submit command separate from the human summary.
-- Do not present a flat list like `1. semantic A 2. semantic B ...` unless the user explicitly asks for raw candidate order.
-
-## Output Discipline
-
-When reporting recommendation results, include:
-
-- commands run;
-- asset scope, exported/authenticated/unauthenticated asset counts, and snapshot hash;
-- topic domains, semantic counts per domain, and candidate titles grouped under each domain;
-- evidence assets per candidate;
-- quality warnings, if any;
-- problem-frame coverage and rejected shallow-opportunity warnings;
-- submit/review/release IDs after writes.

package/skills/ae-project-semantic/references/query-routing-v5.md

@@ -1,165 +0,0 @@
-# Project Semantic Query Routing V5
-
-Use this protocol when project asset packages contain asset definitions, work-unit membership, recent usage, authentication provenance, and optional notes, but do not contain historical user questions, query failures, or execution traces. Never claim that a structure-inferred path is a proven historical best practice.
-
-The only recommendation kinds are:
-
-- `QUERY_ROUTING`: choose the right dashboard/report for a question and distinguish nearby assets;
-- `RECALL_SHORTCUT`: reduce broad asset search to a minimal ordered bundle with stop and fallback conditions;
-- `ANALYSIS_PLAYBOOK`: execute a multi-step or branching analysis path supported by notes or strong complementary asset structure.
-
-Submission semantic types remain unchanged: routing and shortcuts normally use `asset_semantics`; playbooks normally use `business_rule`.
-
-## Evidence roles
-
-- Dashboard/report membership and work units show which assets jointly address a problem.
-- Normalized/raw definitions determine what each asset computes, filters, groups, and returns.
-- Display names, descriptions, notes, and dashboard memo text explain intended questions and explicit instructions, but never make otherwise identical definitions different.
-- Recent usage and recency may prioritize a default entry among otherwise suitable assets; they never establish a formula, causal rule, or business priority.
-- Definition families and conflicts distinguish alternatives, duplicates, misleading titles, and exception variants.
-- Published, active, and rejected catalogs provide exclusion and revision context.
-
-## Discover problem frames before candidates
-
-For every inspected work unit, create zero or more evidence-backed `problem_frames`. Do not require every work unit or asset to produce a candidate. Each frame records:
-
-- natural-language problem intent;
-- triggers and constraints;
-- business object and expected answer grain;
-- available assets and their roles;
-- decision points that change asset choice;
-- explicit note/memo guidance, when present;
-- usage/recency priority;
-- evidence gaps.
-
-Assign relevant assets one of these roles for the frame:
-
-- `DEFAULT_OVERVIEW`;
-- `CONDITIONAL_BRANCH`;
-- `DETAIL_DRILLDOWN`;
-- `COMPARISON_OR_COUNTEREXAMPLE`;
-- `FALLBACK`;
-- `UNSUITABLE_FOR_FRAME`.
-
-An asset may have different roles in different frames. Every role assignment must cite exact definition or note evidence.
-
-## QUERY_ROUTING gate
-
-Generate only when all are true:
-
-1. At least two plausible assets could be confused or selected for related questions.
-2. Object, grain, formula, scope, time, parameter, or output differences determine the correct asset.
-3. The candidate states:
-   - triggering question types;
-   - default asset or entry dashboard;
-   - branch conditions and target assets;
-   - assets that must not substitute for one another;
-   - required parameters or filters;
-   - drilldown and fallback.
-4. Removing the route would materially increase wrong-asset selection.
-
-A formula may explain why a branch is selected, but it is not a routing semantic by itself.
-
-## RECALL_SHORTCUT gate
-
-Generate only when all are true:
-
-1. A broad work unit contains more assets than a recurring query needs.
-2. Evidence supports a minimal ordered subset.
-3. The candidate states the first asset, continuation conditions, stop condition, safe fallback, and unrelated asset groups that can be skipped.
-4. Usage may prioritize between evidence-equivalent suitable entries, but cannot override definition fit.
-5. Search-space reduction is stated from package membership only; never claim measured latency improvement without runtime evidence.
-
-## ANALYSIS_PLAYBOOK gate
-
-### High-confidence playbook
-
-Requires an explicit note or memo stating an analysis goal, sequence, decision, or caveat, plus executable assets supporting the steps. If any required asset is unauthenticated, label the playbook lower confidence and require project-administrator review; do not present the path as certified.
-
-### Medium-confidence recommended analysis path
-
-Allowed without explicit notes only when all are true:
-
-- at least three complementary roles form an overview-to-branch-to-drilldown or measure-to-diagnose-to-verify path;
-- exact definitions establish branch conditions and prevent interchangeable use;
-- no causal claim, business priority, or mandatory sequence is invented;
-- the output is labeled `RECOMMENDED_ANALYSIS_PATH`;
-- boundaries state that the path is structurally inferred and requires review.
-
-Reject paths supported only by co-location, similar titles, independent metrics, or usage ranking.
-
-## Reject shallow candidates
-
-Reject a candidate that only provides:
-
-- one formula, threshold, state, event, property, report, dashboard, or asset name;
-- an inventory of related assets;
-- a topic summary without asset-choice decisions;
-- a broad umbrella listing measures without branches;
-- an inferred maturity hierarchy, causal explanation, or best practice absent from notes;
-- a route that does not reduce ambiguity or search.
-
-Simple formulas and states remain evidence inside routes and playbooks. They do not become standalone project semantics.
-
-## Candidate fields
-
-In addition to the governed submission fields, retain:
-
-- `candidate_kind`;
-- `problem_triggers`;
-- `default_route`;
-- `branch_rules`;
-- `do_not_use`;
-- `drilldown_path`;
-- `fallback`;
-- `asset_roles`;
-- `search_space_reduction`;
-- `evidence_strength`: `HIGH_NOTE_BACKED` or `MEDIUM_STRUCTURE_BACKED`;
-- `confidence_limit`;
-- `problem_frame_ids`.
-
-The candidate body must cover business definition, applicable questions, decision or calculation rules, Agent usage, and boundaries or exceptions. Use headings natural to the project's language when headings improve readability; exact localized wording is not part of the machine contract.
-
-Reusable decision knowledge belongs in `content`. Asset names, ids, counts, and excerpts belong in route fields, `resource_refs`, `evidence`, and `recommendation_reason`.
-
-## Decision ledger
-
-When producing recommendation artifacts, record:
-
-- work units and notes actually inspected;
-- discovered problem frames;
-- asset-role assignments and evidence;
-- routing/shortcut/playbook decisions;
-- rejected shallow opportunities and reasons;
-- candidate-to-frame mappings;
-- dispositions: `ROUTED`, `SHORTCUT`, `PLAYBOOK`, `DEFINITION_ONLY`, or `EVIDENCE_INSUFFICIENT`.
-
-Coverage is measured over supported problem frames, not raw asset or definition-signature counts. Every discovered frame needs a disposition, but not every work unit or asset needs a candidate.
-
-## Acceptance
-
-Candidate count and average prose score are not success metrics. Evaluate with evidence-grounded future-query probes and report:
-
-- primary asset or entry selection;
-- conditional branch selection;
-- prevention of plausible wrong-asset substitution;
-- minimal asset bundle;
-- stop and fallback completeness;
-- search-space reduction versus the work unit;
-- playbook step support;
-- unsupported causal or order claims;
-- problem-frame coverage;
-- formula-only or inventory-only candidate count, which must be zero.
-
-Before submit, require:
-
-- CLI validator `passed=true`;
-- no shallow formula/state-only candidate;
-- every route has a meaningful branch;
-- every shortcut has stop and fallback;
-- every playbook is note-backed or explicitly labeled structure-backed;
-- candidates materially choose or narrow assets better than an undifferentiated work-unit scan.
-
-## Anti-overfitting
-
-Never encode project names, project ids, asset ids, event names, expected topics, expected titles, expected routes, expected counts, or fixed industry dictionaries. The reusable mechanism is problem framing, asset-role classification, decision branching, minimal bundles, and evidence-bounded paths.