create-yss-spec 2.2.10 → 3.0.0

package/template/.codex/skills/product-design/skills/research/SKILL.md

@@ -9,6 +9,13 @@ Run a fresh UX research scan for the product the user specifies.
 
 Focus on current, evidence-backed user problems. Prioritize logged-in product experience, self-serve flows, onboarding, docs/help, developer experience, support friction, and product workflows.
 
+## Modes
+
+- `quick` is the default. It produces a sharp in-chat brief from the best available current evidence.
+- `evidence-audited` is opt-in. Use it only when the user explicitly asks for deep, strict, auditable, or `evidence-audited` research. For consequential product or investment decisions, recommend this mode but do not switch silently.
+
+Both modes remain UX research workflows. Do not import academic-paper writing, peer-review, publication, or multi-agent ceremony.
+
 ## Critical Overrides
 
 - Refer to the Plugin router [$index](../index/SKILL.md) before proceeding.
@@ -25,7 +32,9 @@ Do not inspect every saved reference. Inspect only what the current task needs.
 ## Contract
 
 - Restate the product, audience, time horizon, and research scope before scanning.
+- State the active mode. In `evidence-audited`, also state the planned source classes and inclusion/exclusion criteria before searching.
 - Use public sources by default. Use internal sources when the connectors are available and the user request allows it.
+- Search user-provided or saved material first, apply the same inclusion criteria to it, then search externally to fill material gaps. Never silently omit supplied material; report exclusions or access failures.
 - Cite sources wherever available.
 - Separate observed evidence from inference.
 - Do not overclaim from anecdotes.
@@ -70,6 +79,8 @@ Do not inspect every saved reference. Inspect only what the current task needs.
 
 7. Tell a clear product story.
 
+For `evidence-audited` mode, follow [evidence-audited.md](references/evidence-audited.md) after scope restatement. This adds a reproducible Search Log, an Evidence Ledger, key-claim audit, counter-signal handling, and an explicit failure policy. It does not require sentence-by-sentence auditing.
+
 ## Output
 
 Default to an in-chat research brief unless the user asks for another format.
@@ -81,6 +92,14 @@ Include:
 - Source map: what was searched, what each source contributed, and where signal was weak.
 - Opportunity map: group recommendations into fix this week, fix this quarter, and needs deeper research.
 
+When the user explicitly asks to persist an `evidence-audited` result, create two adjacent files named `<slug>-research-brief.md` and `<slug>-evidence.yaml`. Start from [research-brief-template.md](assets/research-brief-template.md) and [evidence-template.yaml](assets/evidence-template.yaml), then run:
+
+```bash
+node scripts/validate-research-package.mjs <slug>-research-brief.md <slug>-evidence.yaml
+```
+
+Run the command from this skill directory. Do not persist research files merely because `evidence-audited` mode is active.
+
 ## Rules
 
 - Use citations wherever available.
@@ -89,4 +108,7 @@ Include:
 - Separate UX friction from missing features.
 - Separate reliability/performance issues from UX workflow issues.
 - Mark internal-only evidence separately from public evidence.
+- Do not equate source count with frequency. State whether frequency is measured, repeated across independent sources, or anecdotal.
+- In `evidence-audited` mode, audit the key claims for every ranked problem: problem existence, impact, frequency characterization, and the evidence basis for the recommended move. Audit every high-severity key claim; for lower-severity problems include at least one primary supporting item and one counter-signal or an explicit `none-found` search result.
+- Unsupported key claims must use `needs-deeper-research`; partially supported claims must be qualified. Never label a persisted package audited when its validator has not passed.
 - Keep the brief sharp, specific, and easy to consume.

package/template/.codex/skills/product-design/skills/research/assets/evidence-template.yaml

@@ -0,0 +1,65 @@
+{
+  "schema_version": 1,
+  "mode": "evidence-audited",
+  "scope": {
+    "product": "<product>",
+    "audience": "<audience>",
+    "time_horizon": "<time horizon>",
+    "research_questions": ["<question>"],
+    "inclusion_criteria": ["<criterion>"],
+    "exclusion_criteria": ["<criterion>"]
+  },
+  "search_log": [
+    {
+      "id": "search-001",
+      "channel": "<channel or corpus>",
+      "query_or_corpus": "<query or inspected material>",
+      "searched_at": "YYYY-MM-DD",
+      "result": "results-found"
+    },
+    {
+      "id": "search-002",
+      "channel": "<channel searched for disconfirming evidence>",
+      "query_or_corpus": "<counter-signal query>",
+      "searched_at": "YYYY-MM-DD",
+      "result": "none-found"
+    }
+  ],
+  "evidence_items": [
+    {
+      "id": "evidence-001",
+      "visibility": "public",
+      "source_level": "primary",
+      "source_class": "<issue, forum, review, metric, docs, interview, support>",
+      "source_ref": "<URL or internal reference>",
+      "locator": "<section, issue comment, timestamp, or other precise locator>",
+      "stance": "support",
+      "observed_at": "YYYY-MM-DD",
+      "evidence_date": "YYYY-MM-DD",
+      "observation": "<what the source directly shows>",
+      "freshness": "current",
+      "limitations": []
+    }
+  ],
+  "claims": [
+    {
+      "id": "claim-001",
+      "problem_id": "problem-001",
+      "claim_kind": "problem-exists",
+      "statement": "<decision-bearing claim>",
+      "severity": "high",
+      "frequency_signal": "anecdotal",
+      "confidence": "medium",
+      "evidence_refs": ["evidence-001"],
+      "counter_signal_refs": ["search-002"],
+      "audit_status": "supported",
+      "disposition": "publish"
+    }
+  ],
+  "source_gaps": [],
+  "audit_summary": {
+    "status": "complete",
+    "audited_claim_ids": ["claim-001"],
+    "notes": []
+  }
+}

package/template/.codex/skills/product-design/skills/research/assets/research-brief-template.md

@@ -0,0 +1,33 @@
+# <Product> UX Research Brief
+
+## Research Scope
+
+- Mode: `evidence-audited`
+- Audience:
+- Time horizon:
+- Scope:
+- Access limitations:
+
+## Executive Read
+
+Summarize the product story in 5–7 sentences.
+
+## Ranked UX Problems
+
+For each problem, cover the user goal, surface, breakage, evidence, severity, frequency signal, confidence, recommended move, and its key claim IDs (`claim-*`).
+
+## Source Map
+
+Explain what was searched, what each source class contributed, exclusions, failed access, and weak-signal areas.
+
+## Opportunity Map
+
+### Fix This Week
+
+### Fix This Quarter
+
+### Needs Deeper Research
+
+## Evidence Limitations
+
+State coverage gaps, conflicting evidence, counter-signals, and conclusions that were narrowed or withheld.

package/template/.codex/skills/product-design/skills/research/references/evidence-audited.md

@@ -0,0 +1,80 @@
+# Evidence-Audited UX Research
+
+Use this protocol only when the caller explicitly selects `evidence-audited` mode. The goal is an auditable UX brief, not an academic literature review.
+
+## 1. Search plan
+
+Before searching, declare:
+
+- product, audience, time horizon, geography or platform boundaries, and research questions;
+- source classes likely to carry direct user or product evidence;
+- inclusion and exclusion criteria;
+- known access limits, including unavailable internal sources.
+
+Search user-provided and saved material first. Apply the same inclusion and exclusion criteria to supplied and externally discovered material. Search externally to fill gaps, check recency, and seek disconfirming evidence. Record unsuccessful searches and access failures; they bound the conclusion.
+
+## 2. Search Log
+
+Record every material search with its channel, query or inspected corpus, execution date, scope, and result. A zero-result search is still a result. Do not claim that a channel was searched when only an aggregator snippet was inspected.
+
+## 3. Evidence Ledger
+
+Create one evidence item per independently locatable observation. Each item records:
+
+- a stable ID;
+- public or internal visibility, source class, and source level (`primary`, `direct-experience`, `near-primary`, `secondary`, or `lead-only`);
+- source URL or internal reference plus a precise locator;
+- observation date and publication/event date when available;
+- whether the item supports or counters the mapped claim;
+- the observed evidence, without interpretation;
+- freshness and access limitations.
+
+Keep inference in claims, not in evidence observations. Short quotations may support location and meaning, but respect source quotation limits.
+
+## 4. Key-claim audit
+
+Audit the decision-bearing claims for each ranked problem rather than every sentence:
+
+1. the problem exists;
+2. the asserted impact;
+3. the frequency characterization;
+4. the evidence basis for the recommended product move.
+
+For every high-severity problem, audit all four claim kinds. For lower-severity problems, audit at least one `primary` supporting item and one counter-signal. `lead-only` items may guide discovery but cannot support a claim. When no counter-signal is found, reference a Search Log entry whose result is `none-found`; absence of a found counter-signal is not proof that none exists.
+
+Use these audit outcomes:
+
+- `supported`: cited evidence directly supports the claim as worded;
+- `partially-supported`: evidence supports a narrower or qualified claim;
+- `unsupported`: evidence does not support the claim;
+- `not-audited`: allowed only before the audit is complete.
+
+Every evidence reference must resolve to a ledger item. The audit checks support, not merely citation existence.
+
+## 5. Frequency and confidence
+
+Describe frequency as one of:
+
+- `measured`: backed by a relevant dataset or metric;
+- `repeated-independent`: repeated across independent sources, without a population-rate claim;
+- `anecdotal`: one or a small number of reports;
+- `unknown`: the available evidence cannot characterize frequency.
+
+Rank confidence from source directness, independence, recency, access quality, and counter-signals. Do not raise confidence merely because several posts repeat the same upstream report.
+
+## 6. Failure and downgrade policy
+
+- Ordinary access gaps or conflicting evidence do not block the brief. Surface the gap and lower confidence.
+- A partially supported claim must be narrowed and use disposition `qualify`.
+- An unsupported key claim, fabricated or mismatched citation, or unverified source identity must not be presented as certain. Use disposition `needs-deeper-research`.
+- A persisted package fails when its structure is invalid, references do not resolve, lower-severity problems lack primary support, a high-severity claim was not audited, or the report claims completion while an audit remains `not-audited`.
+
+## 7. Persistence
+
+Persist only on explicit request. Use adjacent `<slug>-research-brief.md` and `<slug>-evidence.yaml` files. The evidence file uses JSON syntax, which is valid YAML 1.2, so the bundled validator can parse it without an external YAML dependency.
+
+The Markdown brief must mention every key-claim ID and contain the headings required by the template. The evidence file remains the source of truth for search execution, claim-to-evidence mapping, audit state, gaps, and counter-signals.
+
+## Design provenance
+
+This protocol adapts two engineering patterns from [Academic Research Skills](https://github.com/Imbad0202/academic-research-skills): its Material Passport-style provenance chain and claim-to-reference alignment audit. The UX workflow deliberately omits academic writing, publication, agent-team, and cross-model review machinery.

package/template/.codex/skills/product-design/skills/research/scripts/validate-research-package.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const SOURCE_LEVELS = ["primary", "direct-experience", "near-primary", "secondary", "lead-only"];
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function requireString(value, label) {
+  if (typeof value !== "string" || !value.trim()) fail(`${label} must be a non-empty string`);
+}
+
+function requireArray(value, label, { nonEmpty = false } = {}) {
+  if (!Array.isArray(value) || (nonEmpty && value.length === 0)) fail(`${label} must be ${nonEmpty ? "a non-empty" : "an"} array`);
+}
+
+function uniqueIds(items, label) {
+  const ids = new Set();
+  items.forEach((item, index) => {
+    requireString(item?.id, `${label}[${index}].id`);
+    if (ids.has(item.id)) fail(`${label} contains duplicate id: ${item.id}`);
+    ids.add(item.id);
+  });
+  return ids;
+}
+
+function requireChoice(value, choices, label) {
+  if (!choices.includes(value)) fail(`${label} must be one of: ${choices.join(", ")}`);
+}
+
+function parseEvidence(file) {
+  let value;
+  try {
+    value = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    fail(`${path.basename(file)} must use JSON-compatible YAML 1.2 syntax: ${error.message}`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("evidence root must be an object");
+  return value;
+}
+
+function validate(briefFile, evidenceFile) {
+  if (!briefFile || !evidenceFile) fail("usage: validate-research-package.mjs <brief.md> <evidence.yaml>");
+  const briefPath = path.resolve(briefFile);
+  const evidencePath = path.resolve(evidenceFile);
+  if (path.dirname(briefPath) !== path.dirname(evidencePath)) fail("brief and evidence files must be adjacent");
+  if (!briefPath.endsWith("-research-brief.md") || !evidencePath.endsWith("-evidence.yaml")) fail("expected <slug>-research-brief.md and <slug>-evidence.yaml");
+  const briefSlug = path.basename(briefPath, "-research-brief.md");
+  const evidenceSlug = path.basename(evidencePath, "-evidence.yaml");
+  if (!briefSlug || briefSlug !== evidenceSlug) fail("brief and evidence files must use the same non-empty slug");
+
+  const brief = readFileSync(briefPath, "utf8");
+  const headings = ["Research Scope", "Executive Read", "Ranked UX Problems", "Source Map", "Opportunity Map", "Evidence Limitations"];
+  headings.forEach((heading) => {
+    if (!brief.includes(`## ${heading}`)) fail(`brief is missing heading: ## ${heading}`);
+  });
+
+  const evidence = parseEvidence(evidencePath);
+  if (evidence.schema_version !== 1) fail("schema_version must be 1");
+  if (evidence.mode !== "evidence-audited") fail("mode must be evidence-audited");
+  ["product", "audience", "time_horizon"].forEach((field) => requireString(evidence.scope?.[field], `scope.${field}`));
+  ["research_questions", "inclusion_criteria", "exclusion_criteria"].forEach((field) => requireArray(evidence.scope?.[field], `scope.${field}`, { nonEmpty: true }));
+
+  requireArray(evidence.search_log, "search_log", { nonEmpty: true });
+  const searchIds = uniqueIds(evidence.search_log, "search_log");
+  const searchesById = new Map(evidence.search_log.map((entry) => [entry.id, entry]));
+  evidence.search_log.forEach((entry, index) => {
+    ["channel", "query_or_corpus", "searched_at"].forEach((field) => requireString(entry[field], `search_log[${index}].${field}`));
+    requireChoice(entry.result, ["results-found", "none-found", "access-failed", "excluded"], `search_log[${index}].result`);
+  });
+
+  requireArray(evidence.evidence_items, "evidence_items", { nonEmpty: true });
+  const evidenceIds = uniqueIds(evidence.evidence_items, "evidence_items");
+  const evidenceById = new Map(evidence.evidence_items.map((item) => [item.id, item]));
+  evidence.evidence_items.forEach((item, index) => {
+    requireChoice(item.source_level, SOURCE_LEVELS, `evidence_items[${index}].source_level`);
+    requireChoice(item.visibility, ["public", "internal"], `evidence_items[${index}].visibility`);
+    requireChoice(item.stance, ["support", "counter"], `evidence_items[${index}].stance`);
+    ["source_class", "source_ref", "locator", "observed_at", "observation", "freshness"].forEach((field) => requireString(item[field], `evidence_items[${index}].${field}`));
+    requireArray(item.limitations, `evidence_items[${index}].limitations`);
+  });
+
+  requireArray(evidence.claims, "claims", { nonEmpty: true });
+  const claimIds = uniqueIds(evidence.claims, "claims");
+  const highKinds = new Map();
+  const lowerSeverityPrimary = new Map();
+  evidence.claims.forEach((claim, index) => {
+    ["problem_id", "statement"].forEach((field) => requireString(claim[field], `claims[${index}].${field}`));
+    requireChoice(claim.claim_kind, ["problem-exists", "impact", "frequency", "recommended-move"], `claims[${index}].claim_kind`);
+    requireChoice(claim.severity, ["low", "medium", "high", "critical"], `claims[${index}].severity`);
+    requireChoice(claim.frequency_signal, ["measured", "repeated-independent", "anecdotal", "unknown"], `claims[${index}].frequency_signal`);
+    requireChoice(claim.confidence, ["low", "medium", "high"], `claims[${index}].confidence`);
+    requireChoice(claim.audit_status, ["supported", "partially-supported", "unsupported", "not-audited"], `claims[${index}].audit_status`);
+    requireChoice(claim.disposition, ["publish", "qualify", "needs-deeper-research"], `claims[${index}].disposition`);
+    requireArray(claim.evidence_refs, `claims[${index}].evidence_refs`, { nonEmpty: true });
+    requireArray(claim.counter_signal_refs, `claims[${index}].counter_signal_refs`, { nonEmpty: true });
+    const supporting = claim.evidence_refs.map((ref) => {
+      if (!evidenceIds.has(ref)) fail(`${claim.id} has unresolved evidence ref: ${ref}`);
+      const item = evidenceById.get(ref);
+      if (item.stance !== "support") fail(`${claim.id} support ref is not marked support: ${ref}`);
+      if (item.source_level === "lead-only") fail(`${claim.id} uses lead-only evidence as support: ${ref}`);
+      return item;
+    });
+    claim.counter_signal_refs.forEach((ref) => {
+      if (!evidenceIds.has(ref) && !searchIds.has(ref)) fail(`${claim.id} has unresolved counter-signal ref: ${ref}`);
+      if (evidenceIds.has(ref) && evidenceById.get(ref).stance !== "counter") fail(`${claim.id} counter-signal evidence is not marked counter: ${ref}`);
+      if (searchIds.has(ref) && searchesById.get(ref).result !== "none-found") fail(`${claim.id} counter-signal search must have result none-found: ${ref}`);
+    });
+    if (claim.audit_status === "unsupported" && claim.disposition !== "needs-deeper-research") fail(`${claim.id} is unsupported and must use needs-deeper-research`);
+    if (claim.audit_status === "partially-supported" && claim.disposition !== "qualify") fail(`${claim.id} is partially supported and must use qualify`);
+    if (["high", "critical"].includes(claim.severity)) {
+      const kinds = highKinds.get(claim.problem_id) ?? new Set();
+      kinds.add(claim.claim_kind);
+      highKinds.set(claim.problem_id, kinds);
+    } else {
+      lowerSeverityPrimary.set(claim.problem_id, (lowerSeverityPrimary.get(claim.problem_id) ?? false) || supporting.some((item) => item.source_level === "primary"));
+    }
+    if (!brief.includes(claim.id)) fail(`brief does not reference key claim: ${claim.id}`);
+  });
+
+  const requiredHighKinds = ["problem-exists", "impact", "frequency", "recommended-move"];
+  highKinds.forEach((kinds, problemId) => {
+    const missing = requiredHighKinds.filter((kind) => !kinds.has(kind));
+    if (missing.length) fail(`${problemId} is high severity but is missing audited claim kinds: ${missing.join(", ")}`);
+  });
+  lowerSeverityPrimary.forEach((hasPrimary, problemId) => {
+    if (!hasPrimary) fail(`${problemId} is lower severity but has no primary supporting evidence`);
+  });
+
+  requireArray(evidence.source_gaps, "source_gaps");
+  if (evidence.audit_summary?.status !== "complete") fail("audit_summary.status must be complete");
+  requireArray(evidence.audit_summary.audited_claim_ids, "audit_summary.audited_claim_ids", { nonEmpty: true });
+  const audited = new Set(evidence.audit_summary.audited_claim_ids);
+  audited.forEach((id) => { if (!claimIds.has(id)) fail(`audit_summary has unknown claim: ${id}`); });
+  claimIds.forEach((id) => { if (!audited.has(id)) fail(`audit_summary is missing claim: ${id}`); });
+  evidence.claims.forEach((claim) => { if (claim.audit_status === "not-audited") fail(`${claim.id} remains not-audited`); });
+  requireArray(evidence.audit_summary.notes, "audit_summary.notes");
+  return { claims: claimIds.size, evidence_items: evidenceIds.size, searches: searchIds.size };
+}
+
+try {
+  const result = validate(process.argv[2], process.argv[3]);
+  process.stdout.write(`research package valid (${result.claims} claims, ${result.evidence_items} evidence items, ${result.searches} searches)\n`);
+} catch (error) {
+  process.stderr.write(`research package invalid: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/.codex/skills/product-design/skills/research/tests/run-scenarios.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const validator = path.join(root, "scripts/validate-research-package.mjs");
+const template = JSON.parse(readFileSync(path.join(root, "assets/evidence-template.yaml"), "utf8"));
+const directory = mkdtempSync(path.join(tmpdir(), "product-design-research-"));
+const brief = path.join(directory, "sample-research-brief.md");
+const evidence = path.join(directory, "sample-evidence.yaml");
+const requiredHeadings = ["Research Scope", "Executive Read", "Ranked UX Problems", "Source Map", "Opportunity Map", "Evidence Limitations"];
+
+function run(payload, expectedStatus, expectedText) {
+  writeFileSync(brief, `${requiredHeadings.map((heading) => `## ${heading}`).join("\n\n")}\n\n${payload.claims.map((claim) => claim.id).join(" ")}\n`);
+  writeFileSync(evidence, `${JSON.stringify(payload, null, 2)}\n`);
+  const result = spawnSync(process.execPath, [validator, brief, evidence], { encoding: "utf8" });
+  if (result.status !== expectedStatus || !`${result.stdout}${result.stderr}`.includes(expectedText)) {
+    throw new Error(`expected status ${expectedStatus} containing ${expectedText}, got ${result.status}: ${result.stdout}${result.stderr}`);
+  }
+}
+
+try {
+  template.scope.product = "Example";
+  template.scope.audience = "Administrators";
+  template.scope.time_horizon = "Last 90 days";
+  template.scope.research_questions = ["Where does onboarding fail?"];
+  template.scope.inclusion_criteria = ["Direct experience in scope"];
+  template.scope.exclusion_criteria = ["Unverifiable reposts"];
+  template.search_log[0].channel = "GitHub Issues";
+  template.search_log[0].query_or_corpus = "onboarding failure";
+  template.search_log[0].searched_at = "2026-09-03";
+  template.search_log[1].channel = "GitHub Issues";
+  template.search_log[1].query_or_corpus = "onboarding completed successfully";
+  template.search_log[1].searched_at = "2026-09-03";
+  template.evidence_items[0].source_class = "issue";
+  template.evidence_items[0].source_ref = "https://example.com/issues/1";
+  template.evidence_items[0].locator = "comment-1";
+  template.evidence_items[0].observed_at = "2026-09-03";
+  template.evidence_items[0].evidence_date = "2026-09-01";
+  template.evidence_items[0].observation = "A user reports that setup stopped before completion.";
+  template.claims[0].severity = "medium";
+  template.claims[0].statement = "At least one user encountered an onboarding blocker.";
+  run(template, 0, "research package valid");
+
+  const unsupported = structuredClone(template);
+  unsupported.claims[0].audit_status = "unsupported";
+  unsupported.claims[0].disposition = "publish";
+  run(unsupported, 1, "must use needs-deeper-research");
+
+  const unresolved = structuredClone(template);
+  unresolved.claims[0].evidence_refs = ["evidence-missing"];
+  run(unresolved, 1, "unresolved evidence ref");
+
+  const falseCounter = structuredClone(template);
+  falseCounter.claims[0].counter_signal_refs = ["search-001"];
+  run(falseCounter, 1, "counter-signal search must have result none-found");
+
+  const incompleteHighSeverity = structuredClone(template);
+  incompleteHighSeverity.claims[0].severity = "high";
+  run(incompleteHighSeverity, 1, "high severity but is missing audited claim kinds");
+
+  const lowerSeverityWithoutPrimary = structuredClone(template);
+  lowerSeverityWithoutPrimary.evidence_items[0].source_level = "secondary";
+  run(lowerSeverityWithoutPrimary, 1, "lower severity but has no primary supporting evidence");
+
+  process.stdout.write("research package scenarios passed (6)\n");
+} finally {
+  rmSync(directory, { recursive: true, force: true });
+}

package/template/.codex/skills/wayfinder/SKILL.md

@@ -74,7 +74,7 @@ The answer isn't part of the body — it's recorded on resolution (see [Work thr
 
 Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/research` **subagent**. Use when knowledge outside the current working directory is required.
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/yss-research` **subagent** (`/research` is a deprecated alias). Use when knowledge outside the current working directory is required.
 - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
 - **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
 - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
@@ -112,7 +112,7 @@ User invokes with a loose idea.
 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
 4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket.
+5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/yss-research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. `/research` remains only as a deprecated compatibility alias.
 6. Stop — charting is one session's work; it hand-resolves nothing.
 
 ### Work through the map

package/template/.codex/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -28,7 +28,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 2. 优先运行 `node scripts/generate_and_verify_scaffold.mjs`，在同一个受控工作流中生成骨架并执行真实 Maven 验证。`generate_scaffold.mjs` 只是底层生成原语，单独返回 0 不代表脚手架完成。
 3. 检查生成的模块名、POM、机械启动入口、基础配置文件和包路径。
 4. 受控工作流必须在生成项目根目录实际执行 `./mvnw validate`、`./mvnw test` 和 `./mvnw package`；三条命令全部返回 0 后才能报告完成。
-5. 三条 Wrapper 命令通过只得到 `empty-scaffold-verified`。如需声称已满足下游技能的首切片就绪条件，必须再通过 golden first slice，得到 `first-slice-verified`。
+5. 三条 Wrapper 命令通过只得到 `empty-scaffold-verified`。如需声称已满足下游技能的首切片就绪条件，必须使用 `node scripts/run_first_slice_verification.mjs` 校验批准且版本当前的 Slice Implementation Contract、完整分层产物、skill tree digest 与根 Wrapper；只有验证器成功更新 Manifest 后才得到 `first-slice-verified`。
 
 受控验证命令由本 skill 的 `node scripts/run_scaffold_verification.mjs` 固定执行；验证器先检查 `.yss/scaffold-generation.json` 的合同元数据和 Wrapper、Java、项目级 Maven settings/profile、仓库凭据是否就绪，再在指定 evidence 目录写入每条命令的 stdout/stderr、`exit_code`、`failure_category`、耗时、执行时间和 `scaffold-verification.json`。仓库或凭据失败归为 `repository-access`，与 `project-model`、`compilation`、`bootstrap-entrypoint`、`test-failure`、`packaging` 分开；任何一条命令失败或未执行都必须阻断。
 
@@ -55,6 +55,15 @@ node scripts/generate_and_verify_scaffold.mjs \
   --evidence-dir /path/to/evidence/scaffold
 ```
 
+完成批准的 golden first slice 后运行：
+
+```bash
+node scripts/run_first_slice_verification.mjs \
+  --project-root /path/to/implementation-repo/my-service \
+  --slice-contract-file /path/to/approved-slice-contract.json \
+  --evidence-dir /path/to/evidence/first-slice
+```
+
 ## 生成结果应包含
 
 - 父工程 POM
@@ -75,7 +84,7 @@ node scripts/generate_and_verify_scaffold.mjs \
 - Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。生成器必须先调用 `gitSubmoduleScaffoldViolation`，再在 exists / `--force` / rename 之前调用 `refuseGitlinkAsRegularDirectory`。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
-- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller` 等行为 skill；各 skill 的 `references/*-layer-guide.md` 承载分层开发规范。
+- 生成时的静态依赖由技能注册表与 Router 共同约束为 `yss-backend-scaffold-parent`、`alibaba-java-code-style`。生成后必须回到 Router，并按批准切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等实际命中的行为 skill。
 - 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
@@ -83,7 +92,8 @@ node scripts/generate_and_verify_scaffold.mjs \
 - 新脚手架合同只接受 schema v2，必须分别携带 `project_name`、`base_package` 和 `maven_coordinates`；后者包含项目 `group_id` / `project_version`、父 POM GAV 与 `yss_components_version`，并由 CLI 原样传入。schema v1 为 `unsupported`，直接拒绝且不自动升级。
 - 合同 `profiles` 只支持 `target-domain-model`、`mybatis-plus`、`mysql`、`spring-boot-2.7-jdk8`、`javax`、`web`、`yss-internal`。普通 MyBatis、Boot 3、独立 client module、client-in-domain 和其他旧架构均为 `unsupported`，不提供回退分支。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation`、实际输出路径和固定三条验证命令，不接受仅凭任意字符串引用的放行。
-- 生成项目必须写入 Manifest v2 `.yss/scaffold-generation.json`，记录合同 digest、Target Profile、模板 digest、下游 skill hash、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 Router。
+- 生成项目必须写入 Manifest v2 `.yss/scaffold-generation.json`，记录合同 digest、Target Profile、模板 digest、下游完整 skill tree digest、脚手架父合同与 Router 合同 digest、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 Router。
+- `first-slice-verified` 只能由 `run_first_slice_verification.mjs` 写入。手工改 Manifest、只生成 Controller、只通过局部模块测试或仅有结构扫描都不能升级完成等级。
 - 严禁把领域规则、状态机、权限、事务、复杂查询、错误映射、业务字段或用户可见行为塞进脚手架生成步骤。`./mvnw validate`、输出目录存在或“生成成功”都不等于生命周期批准、架构放行或 `ready-for-agent`。
 - 生命周期脚手架生成必须关闭 `--with-example`，不得把 User CRUD 或业务字段当作样板。生成器严格 `initialize-only`：非空目标、`--force`、旧项目迁移和当前模板升级一律 `unsupported`。未来若支持同一 Target Profile 内的模板升级，必须另行设计和批准，当前不预留可执行承诺。
 - 脚手架完成后，所有后续生成的后端代码必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract 和对应 YSS skill；业务行为使用 `behavior-tdd`，机械生成才使用 `controlled-generation`。
@@ -98,6 +108,7 @@ node scripts/generate_and_verify_scaffold.mjs \
 - 主脚本：`scripts/generate_scaffold.mjs`
 - 推荐的一键生成验证入口：`scripts/generate_and_verify_scaffold.mjs`
 - 受控验证器：`scripts/run_scaffold_verification.mjs`
+- 首切片验证器：`scripts/run_first_slice_verification.mjs`
 - 模板目录：`assets/templates/`
 - 分层细化参考：`references/yss-backend-scaffold-parent/` 及其子 skill
 

package/template/.codex/skills/yss-ddd-scaffold-generator/references/ARCHITECTURE.md

@@ -104,13 +104,13 @@ Domain Error -> Application propagation/translation -> Web Exception Translator
 
 - Scaffold 只生成机械模块、POM、Wrapper、配置、架构规则和 Manifest，不生成生产业务 CRUD。
 - 初始生成器为 `initialize-only`，非空目标失败。
-- Manifest v2 记录模板/合同/downstream skill digest 与 generator-owned 文件 hash。
+- Manifest v2 记录模板、脚手架父合同、Router 合同、downstream 完整 skill tree digest 与 generator-owned 文件 hash。
 - 当前不支持模板升级，不得重跑初始生成器覆盖业务工程。未来如需支持同一 Target Profile 内的模板版本升级，必须另行设计、批准并验证。
 
 ## 5. 完成等级
 
 - `generated`：文件已原子生成，尚未完成 Wrapper 验证。
 - `empty-scaffold-verified`：根目录 `./mvnw validate/test/package` 全部通过。
-- `first-slice-verified`：golden first slice 的 Domain、Application、Repository/MyBatis、DTO/Web、Exception、Wire 与架构负例全部通过。
+- `first-slice-verified`：批准且版本当前的 golden first slice 已具备 Domain 模型/Gateway、Application Service 实现/事务/Query Port、Repository/Mapper/GatewayImpl/QueryAdapter、DTO/Web/Exception 与分层测试；下游完整 skill tree digest 无漂移，且根 Wrapper 全部通过。该状态只能由 `scripts/run_first_slice_verification.mjs` 写入。
 
-只有最后一级可以声明已满足下游 YSS skills 的首切片就绪条件。
+只有首切片验证器可以把 Manifest 从 `empty-scaffold-verified` 升级到最后一级；手工写值、局部测试或结构扫描均无效。只有最后一级可以声明已满足下游 YSS skills 的首切片就绪条件。

package/template/.codex/skills/yss-ddd-scaffold-generator/references/USAGE_EXAMPLES.md

@@ -102,7 +102,18 @@ metadata-service/
 
 ## 4. 后续路由
 
-`empty-scaffold-verified` 不等于业务切片可实现。后续必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract，再按影响面加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-dto`、`yss-exception`、`yss-web-controller` 等 skill，并使用 `behavior-tdd` 实现业务行为。只有 golden first slice 全部通过才能标记 `first-slice-verified`。
+`empty-scaffold-verified` 不等于业务切片可实现。后续必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract，再按影响面加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等 skill，并使用 `behavior-tdd` 实现业务行为。
+
+完成 golden first slice 后，必须运行：
+
+```bash
+node .agents/skills/yss-ddd-scaffold-generator/scripts/run_first_slice_verification.mjs \
+  --project-root /path/to/implementation-repo/metadata-service \
+  --slice-contract-file /path/to/approved-slice-contract.json \
+  --evidence-dir /path/to/evidence/first-slice
+```
+
+只有该验证器确认合同、全层产物、skill tree digest 与根 Wrapper 全部通过，并更新 Manifest 后，才能标记 `first-slice-verified`。
 
 目标目录必须不存在。`--force`、旧项目迁移和当前模板升级均为 `unsupported`。旧项目继续按原工程维护；现代化改造必须单独立项、先评估再逐切片迁移。
 

package/template/.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

@@ -45,7 +45,7 @@ infrastructure-+
 - Maven 内部仓库通过命名 profile `yss-internal` 与环境变量注入；共享模板不写内部 URL 或凭据。
 - Wrapper 必须带 checksum；DEBUG 和 MyBatis stdout SQL 只允许在 `application-local.yml`。
 - `./mvnw validate`、`./mvnw test`、`./mvnw package` 全部成功只得到 `empty-scaffold-verified`。
-- 只有 golden first slice 真实组合 Domain/Application/Infrastructure/Web 并通过根 Wrapper，才能得到 `first-slice-verified`。
+- 只有批准且版本当前的 golden first slice 真实组合 Domain/Application/Infrastructure/Web、通过下游 skill tree drift 校验与根 Wrapper，才能由 `run_first_slice_verification.mjs` 写入 `first-slice-verified`。
 
 ## 下游权威技能
 
@@ -53,5 +53,6 @@ infrastructure-+
 - Application：`yss-application`
 - Persistence：`yss-repository` + `yss-mybatis`
 - Web：`yss-web-controller` + `yss-dto` + `yss-exception`
+- 横切实现约束：`yss-validation` + `mapstruct` + `lombok` + `alibaba-java-code-style`
 
 业务代码必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract，并采用 `behavior-tdd`；脚手架只生成机械工程资产。