@thinkingai/ae-cli 6.1.17 → 6.1.18

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

@@ -0,0 +1,193 @@
+---
+name: ae-project-semantic
+description: "Use when generating, testing, submitting, reviewing, or publishing governed project semantic candidates from AE/TE 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

@@ -0,0 +1,165 @@
+# 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.

package/skills/ae-project-semantic/references/recommendation-quality.md

@@ -0,0 +1,68 @@
+# Project Semantic Recommendation Quality
+
+## Business Goal
+
+The Agent should turn a certified project snapshot into a small, reviewable L2 semantic system. The output should help future analysis interpret business terms, choose the right dashboards/reports, and apply project-wide rules consistently.
+
+It should not produce a checklist of assets to approve one by one.
+
+## Extraction Method
+
+1. Start with `manifest.json`, `.asset-package.json`, and all catalog files. Published semantics and active candidates form the duplicate/update exclusion set. Disabled semantics form a strict suppression set and must not be recreated by the scan. Rejected candidates require a documented material change before reconsideration.
+2. Treat `indexes/work-units.jsonl` as the primary investigation queue. Follow its recent-90-day usage order, but rotate across distinct evidence-backed business themes before adding more candidates for a dominant theme.
+3. Start with authenticated, active dashboards and reports as primary evidence. When the user explicitly approved a broader export scope, preserve each asset's authentication and selection provenance. Unauthenticated dashboards/reports may support discovery only when corroborated by definitions, work-unit relationships, usage, or notes, and any resulting claim must carry a lower confidence boundary. Events, properties, metrics, notes, and background text are supporting evidence only. Open `details/normalized/**` and `details/raw/**` through `detail_locator` only for assets that may support a candidate.
+4. Use normalized key fields to establish definition families. Display names, descriptions, and notes remain available as interpretation evidence, but differences in those fields alone must not split a family. Discover semantic families with cross-domain questions: business object/state, analysis subject and grain, formula and denominator, inclusion/exclusion, time roles, units and normalization, asset-selection priority, applicability and exceptions. These are inspection dimensions, not topic names.
+5. Name L2 topic domains only after the evidence families are understood. Use the project's own natural business language; do not start from a fixed industry taxonomy or known test-package themes.
+6. For every cluster, ask what reusable project meaning it implies:
+   - business concept: a named business object or state;
+   - business rule: inclusion/exclusion logic;
+   - asset semantics: default asset set for a question type;
+   - calculation convention: denominator, numerator, window, attribution, currency, deduplication.
+7. Create candidates only when the semantic is reusable across future questions and changes Agent behavior.
+8. Return a successful empty recommendation when published or active semantics already cover every supported behavior change.
+9. Apply [`query-routing-v5.md`](query-routing-v5.md) after evidence-family discovery. Prefer reusable query routing, recall shortcuts, and evidence-bounded analysis paths over standalone formula or state descriptions.
+
+## Reject These Candidates
+
+- One candidate per asset.
+- Candidate title merely copies an event/property/report name.
+- Candidate title is an L1 metadata object, for example an event, property, metric, tag, or field name.
+- Candidate has fewer than two related evidence assets unless one asset is a high-authority certified dashboard/report with detailed notes.
+- Candidate claims a calculation rule not present in asset names, descriptions, definitions, notes, or inspected reports.
+- Candidate mixes unrelated lifecycle domains to raise evidence count.
+- Candidate treats an unauthenticated asset as a certified or authoritative project default without corroboration and an explicit confidence limit.
+- Candidate is a duplicate of a published or disabled semantic by title, alias, or equivalent behavior.
+- Candidate is a generic lifecycle template that ignores the project domain discovered in the snapshot.
+- Candidate only restates one formula, threshold, state, event, property, report, dashboard, or asset name.
+- Candidate is a broad topic summary with no asset-choice branch, stop condition, or wrong-asset exclusion.
+
+## Candidate Shape
+
+Each topic group should explain why the assets belong together. Each candidate should include:
+
+- `candidate_kind`: `QUERY_ROUTING`, `RECALL_SHORTCUT`, or `ANALYSIS_PLAYBOOK`;
+- `semantic_type`;
+- `title`;
+- `summary`;
+- `content` with definition, scope, usage, and exclusions;
+- `keywords`;
+- `resource_refs` with asset type, id/name, display name, and description when available;
+- `work_unit_coverage` for the snapshot work units it covers;
+- `recommendation_reason`;
+- `evidence` with source titles and excerpts.
+- the V5 route fields required for its candidate kind, including branches, exclusions, stop/fallback behavior, asset roles, evidence strength, and problem-frame ids.
+
+The candidate body must read as governed business knowledge, not as an asset inventory. Use this review order:
+
+1. **Business definition**: what the concept, rule, or convention means in this project.
+2. **Applicable questions**: which future questions should activate it.
+3. **Decision or calculation rule**: the concrete inclusion, exclusion, grain, denominator, time-window, or asset-selection rule proven by evidence.
+4. **Agent usage rule**: how the Agent changes interpretation or execution after adopting it.
+5. **Boundaries and exceptions**: what must not be inferred, merged, or substituted.
+6. **Evidence assets**: keep dashboards/reports in `resource_refs` and evidence sections; do not make their names the semantic body.
+
+Reject a batch when multiple candidates differ only by asset names or counts while reusing the same definition, usage, and exclusion prose. A recommendation reason must name the business claim supported by the evidence, not merely state that dashboards/reports were bound.
+
+## Evaluation Packages
+
+Evaluate the unchanged protocol on at least two unrelated asset packages when tuning recommendation quality. Do not add project names, asset IDs, expected titles, expected domains, or expected counts to the skill or CLI code after seeing a test result. A sparse governed package should trigger explicit, sequential consent before re-exporting `collaborative` and then `all_visible`; a sparse broad package should still produce fewer candidates or explicit insufficiency warnings rather than generic filler.

package/dist/chunk-QGM4M3NI.js

@@ -1,37 +0,0 @@
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-var __commonJS = (cb, mod) => function __require2() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-
-export {
-  __require,
-  __commonJS,
-  __toESM
-};