lazycodex-ai 5.0.0-beta.9 → 5.0.0-beta.90

package/packages/shared-skills/skills/ulw-plan/references/intent-unclear.md

@@ -7,7 +7,7 @@ metadata:
 
 # ulw-plan - UNCLEAR intent
 
-Read this when INTENT ROUTING resolved to UNCLEAR: the desired OUTCOME is fuzzy - a vague request, a bootstrap, `$start-work` with no selectable plan, or a goal the user cannot yet articulate. Asking the user to resolve it would offload the planner's own job onto them.
+Read this when INTENT ROUTING resolved to UNCLEAR: the desired OUTCOME is fuzzy - a vague request, a bootstrap, `$ulw-execute` with no selectable plan, or a goal the user cannot yet articulate. Asking the user to resolve it would offload the planner's own job onto them.
 
 <stance>
 PRIME DIRECTIVE: do NOT interrogate the user. Resolve ambiguity by RESEARCH, not questions. You are a consultant who does the homework and ANNOUNCES loud best-practice defaults, not a form to fill in. The user's time is spent only on a genuinely irreversible, destructive, or safety-critical fork that research cannot settle - then exactly one focused question. Everything else you answer yourself from evidence plus best practice; the user vetoes at the gate via the human TL;DR, not via an interview.
@@ -20,7 +20,7 @@ TOPOLOGY LOCK still applies: enumerate the 1-6 independently-succeed/fail compon
 </research_protocol>
 
 <default_selection>
-For each open decision - including the extrinsic axes the sweep names (budget, mandated stack, expected scale, target audience / compliance) - adopt the defensible best-practice default (industry standard or repo convention), RECORD it in the draft's Open-assumptions ledger with rationale and reversibility, and proceed. NO numeric scoring - the ledger IS the audit trail. The ONLY default escalated to a single focused question is one that is irreversible, destructive, or safety-critical, or commits real spend the user never authorized, and research cannot settle.
+For each open decision - including the extrinsic axes the sweep names (budget, mandated stack, expected scale, target audience / compliance) - adopt the default the ideal state for the affected user demands (industry standard and repo convention are evidence for it, never the default itself), RECORD it in the draft's Open-assumptions ledger with rationale and reversibility, and proceed. NO numeric scoring - the ledger IS the audit trail. The ONLY default escalated to a single focused question is one that is irreversible, destructive, or safety-critical, or commits real spend the user never authorized, and research cannot settle.
 
 Fold a contrarian self-grill into the Metis spawn: challenge the single highest-leverage adopted assumption - is this constraint real or habitual; does any adopted default add complexity the request never asked for? - and return concrete reframes. The grill targets incidental complexity (unneeded abstraction, speculative capacity), NEVER the feature set: reducing, phasing, or deferring part of the request is not a reframe. Fold a reframe into the plan only as a recommended default plus rationale, never as a forced change.
 </default_selection>
@@ -32,13 +32,13 @@ TRIVIAL-TIER GUARD: if Classify sized the work Trivial, the auto-Momus loop is S
 </high_accuracy_auto>
 
 <approval_gate>
-Still present a brief and wait for the user's explicit okay - approval is not execution - but the brief LEADS with "here is the best-practice approach I derived and the assumptions I adopted (with reversibility)", not "here are questions for you". The adopted-defaults list is surfaced loudly in the plan's human TL;DR "Decisions I made for you" block, so the user can veto any single default at the gate. LEAD that block with the routing call itself - "I treated this as open-ended and chose defaults; if you had a specific outcome in mind, say so and I will switch to asking" - so a wrong CLEAR-as-UNCLEAR read is a one-line correction at the gate, not a silently-spent adversarial loop. Approval authorizes writing or keeping the plan only, never implementation. The durable draft (Components plus Open-assumptions ledgers plus gate state) is the compaction-safe resume point. ($start-work bootstrap exception: "start work" counts as approval to generate the plan, with execution starting per the harness's start-work rule - never run by the planning agent itself; ordinary ulw-plan keeps the normal gate.)
+Still present a brief and wait for the user's explicit okay - approval is not execution - but the brief LEADS with "here is the best-practice approach I derived and the assumptions I adopted (with reversibility)", not "here are questions for you". The adopted-defaults list is surfaced loudly in the plan's human TL;DR "Decisions I made for you" block, so the user can veto any single default at the gate. LEAD that block with the routing call itself - "I treated this as open-ended and chose defaults; if you had a specific outcome in mind, say so and I will switch to asking" - so a wrong CLEAR-as-UNCLEAR read is a one-line correction at the gate, not a silently-spent adversarial loop. Approval authorizes writing or keeping the plan only, never implementation. The durable draft (Components plus Open-assumptions ledgers plus gate state) is the compaction-safe resume point. ($ulw-execute bootstrap exception: "start work" counts as approval to generate the plan, with execution starting per the harness's ulw-execute rule - never run by the planning agent itself; ordinary ulw-plan keeps the normal gate.)
 </approval_gate>
 
 <worked_example>
 Request: "make auth better".
 1. Research waves -> current auth at `src/auth/*` and evidence for the requested improvement; best-practice baselines via librarian.
-2. Topology lock as an ANNOUNCEMENT, not a question: components refine the evidenced auth intent in full, such as session hardening, brute-force protection, and password policy when the repository supports them. MFA is an adjacent capability and stays in Scope OUT unless the user asks for it or evidence establishes it as part of the requested outcome.
+2. Affected user and ideal state, announced: the people who sign in and the operators who read auth logs; IS rows the evidence supports - a legitimate user is never locked out, brute force is stopped, a session is never reusable after a privilege change. Topology lock as an ANNOUNCEMENT, not a question: components refine the evidenced auth intent in full, such as session hardening, brute-force protection, and password policy when the repository supports them. MFA is an adjacent capability and stays in Scope OUT unless the user asks for it or evidence establishes it as part of the requested outcome.
 3. Adopted-defaults table (assumption | default | rationale | reversible?): bcrypt rounds 8 -> 12 (reversible), add 5/min-per-IP login limit (reversible), rotate session id on privilege change (reversible).
 4. Metis folded -> auto dual review (fix eligible gaps under the bounded convergence contract) -> brief LEADING with the approach and the defaults, surfaced in the human TL;DR for veto.
 </worked_example>

package/packages/shared-skills/skills/ulw-plan/scripts/plan-templates.mjs

@@ -0,0 +1,180 @@
+// plan-templates.mjs - the draft and plan skeleton text that scaffold-plan.mjs emits.
+//
+// Text only: no filesystem access, no path policy (scaffold-plan.mjs owns the write
+// boundary). Zero external dependencies so it runs byte-identically under `node` and `bun`.
+
+// The canonical AI-plan section headers, in order. references/full-workflow.md
+// documents this exact list; the two must never drift.
+export const PLAN_SECTION_HEADERS = [
+	"## TL;DR (For humans)",
+	"## Scope",
+	"## Verification strategy",
+	"## Execution strategy",
+	"## Todos",
+	"## Final verification wave",
+	"## Commit strategy",
+	"## Success criteria",
+];
+
+export const FINAL_VERIFICATION_ITEMS = [
+	"F1. Plan compliance audit",
+	"F2. Code quality review",
+	"F3. Real manual QA",
+	"F4. Ideal-state fidelity",
+];
+
+export function buildDraft(slug, intent, { reviewRequired = false } = {}) {
+	const assumptionsNote =
+		intent === "unclear"
+			? "Intent is UNCLEAR: research resolves ambiguity, defaults are adopted (not asked), and each is surfaced in the plan's human TL;DR for veto."
+			: "Record any default you adopt instead of asking, so the user can veto it at the gate.";
+	const reviewState = reviewRequired
+		? `review_required: true
+plan_path: .omo/plans/${slug}.md
+plan_sha256: null
+review_round_id: null
+pending-action: write and review .omo/plans/${slug}.md
+review:
+  momus:
+    status: pending
+    workspace_root: null
+    runtime_home: null
+    target: .omo/plans/${slug}.md
+    round_id: null
+    plan_sha256: null
+    launch_id: null
+    session: null
+    result: null
+  independent:
+    status: pending
+    workspace_root: null
+    runtime_home: null
+    target: .omo/plans/${slug}.md
+    round_id: null
+    plan_sha256: null
+    launch_id: null
+    session: null
+    result: null`
+		: `review_required: false
+pending-action: write .omo/plans/${slug}.md`;
+	return `---
+slug: ${slug}
+status: drafting
+intent: ${intent}
+${reviewState}
+approach: <fill: the approach you intend to plan>
+---
+
+# Draft: ${slug}
+
+## Affected user and ideal state
+<!-- Who this output touches (a customer, another programmer, a program or agent consuming it - often more than one) and how each uses it today and will use it after. -->
+<!-- IS-n | property of the ideal state: nothing snags, feels odd, regresses, or degrades for them | reason -->
+<!-- GAP-n | difference between IS-n and today | reason | closed by todo(s) -->
+
+## Components (topology ledger)
+<!-- Lock the SHAPE before depth. One row per top-level component that can succeed or fail independently. -->
+<!-- id | outcome (one line) | status: active|deferred | evidence path -->
+
+## Open assumptions (announced defaults)
+<!-- ${assumptionsNote} -->
+<!-- assumption | adopted default | rationale | reversible? -->
+
+## Findings (cited - path:lines)
+
+## Decisions (with rationale)
+
+## Scope IN
+
+## Scope OUT (Must NOT have)
+
+## Open questions
+
+## Approval gate
+status: drafting
+<!-- When exploration is exhausted and unknowns are answered, set status: awaiting-approval. -->
+<!-- That durable record is the loop guard: on a later turn read it and resume at the gate instead of re-running exploration. -->
+`;
+}
+
+export function buildPlanSkeleton(slug, intent) {
+	const decisionsLine =
+		intent === "unclear"
+			? "**Decisions I made for you:** <fill last - the best-practice defaults you adopted; the user vetoes any here>"
+			: "**Decisions to sanity-check:** <fill last - the few choices worth a human glance>";
+	return `# ${slug} - Work Plan
+
+## TL;DR (For humans)
+<!-- Fill this LAST, after the detailed plan below is written, so it summarizes the REAL plan. -->
+<!-- Plain English for a non-engineer: NO file paths, NO todo numbers, NO wave/agent/tool names. -->
+
+**Who this is for and what changes for them:** <fill last - the affected user and their experience after, 1-2 sentences>
+
+**What you'll get:** <fill last - deliverables in human terms, 1-2 sentences>
+
+**Why this approach:** <fill last - the one or two load-bearing decisions and why>
+
+**What it will NOT do:** <fill last - 1-3 plain lines mirroring Must NOT have>
+
+**Effort:** <Quick | Short | Medium | Large | XL>
+<!-- Effort is exactly ONE band, never hours/days. Quick = single edit, minutes of agent work; Short = one focused change, a few files; Medium = multi-file feature in one session; Large = several waves, one long session; XL = multi-session or architectural work. A written duration is rewritten to a band. -->
+**Risk:** <Low | Medium | High> - <one-line driver>
+${decisionsLine}
+
+Your next move: <fill - e.g. approve, or run a high-accuracy review>. Full execution detail follows below.
+
+---
+
+> TL;DR (machine): <1 line - effort, risk, deliverables>
+
+## Scope
+### Affected user and ideal state
+<!-- From the draft ledger: who this touches and how they use the result, then one IS row per property with its reason, then one GAP row per difference with its reason. Every todo below closes a GAP row; ## Success criteria proves every IS row. -->
+**Affected user:** <who, and how they use it today and after>
+
+| Row | Statement | Reason |
+| --- | --- | --- |
+| IS-1 | <what the user does, sees, or never has break> | <why this is the ideal for them> |
+| GAP-1 | <how today differs from IS-1> | <why it matters to them> |
+
+### Must have
+### Must NOT have (guardrails, anti-slop, scope boundaries)
+
+## Verification strategy
+> Zero human intervention - all verification is agent-executed.
+- Test decision: <TDD | tests-after | none> + framework
+- Evidence: <attemptDir>/task-<N>-${slug}.<ext> (attemptDir = currentAttemptDir from the ulw-loop status operation - on Senpi the eval SDK import, const { agentToolkit } = await import(\`\${env("OMO_AGENT_TOOLKIT_SDK_ROOT")}/sdk.js\`) then agentToolkit.status(), on Codex the omo-agent-toolkit CLI, .omo/evidence/ulw/<session>/<goalId>/a<attempt>; outside ulw-loop use .omo/evidence/)
+
+## Execution strategy
+### Parallel execution waves
+> Target 5-8 todos per wave. Fewer than 3 (except the final) means you under-split.
+
+### Dependency matrix
+| Todo | Depends on | Blocks | Can parallelize with |
+| --- | --- | --- | --- |
+
+## Todos
+> Implementation + Test = ONE todo. Never separate.
+<!-- APPEND TASK BATCHES BELOW THIS LINE WITH edit/apply_patch - never rewrite the headers above. -->
+- [ ] 1. <title>
+  What to do / Must NOT do: <...>
+  Closes: GAP-<n>
+  Parallelization: Wave <N> | Blocked by: <...> | Blocks: <...>
+  References (executor has NO interview context - be exhaustive): <src/path:lines>
+  Acceptance criteria (agent-executable): <exact command or assertion>
+  QA scenarios (name the exact tool + invocation): happy + failure, Evidence <attemptDir>/task-1-${slug}.<ext>
+  Commit: <Y/N> | <type>(<scope>): <summary>
+
+## Final verification wave
+> Runs in parallel after ALL todos. ALL must APPROVE. Surface results and wait for the user's explicit okay before declaring complete.
+${FINAL_VERIFICATION_ITEMS.map((item) => `- [ ] ${item}`).join("\n")}
+
+## Commit strategy
+
+## Success criteria
+> One row per IS row. The plan is complete only when every IS row has a delivering todo and a proving QA scenario; F4 checks the delivered behavior against these rows 1:1, and a shortfall becomes new \`- [ ] N.\` rows, never a note.
+| IS | Delivering todo(s) | Proving QA scenario | Evidence |
+| --- | --- | --- | --- |
+| IS-1 | <N> | <scenario name from todo N> | <attemptDir>/task-<N>-${slug}.<ext> |
+`;
+}

package/packages/shared-skills/skills/ulw-plan/scripts/scaffold-plan.mjs

@@ -23,26 +23,10 @@
 import { lstat, mkdir, writeFile, readFile, realpath } from "node:fs/promises";
 import { dirname, join, relative, resolve, isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
+import { FINAL_VERIFICATION_ITEMS, PLAN_SECTION_HEADERS, buildDraft, buildPlanSkeleton } from "./plan-templates.mjs";
 
-// The canonical AI-plan section headers, in order. references/full-workflow.md
-// documents this exact list; a build-time test asserts the two never drift.
-export const PLAN_SECTION_HEADERS = [
-	"## TL;DR (For humans)",
-	"## Scope",
-	"## Verification strategy",
-	"## Execution strategy",
-	"## Todos",
-	"## Final verification wave",
-	"## Commit strategy",
-	"## Success criteria",
-];
-
-export const FINAL_VERIFICATION_ITEMS = [
-	"F1. Plan compliance audit",
-	"F2. Code quality review",
-	"F3. Real manual QA",
-	"F4. Scope fidelity",
-];
+// The emitted text lives in plan-templates.mjs; re-exported so importers keep one entry point.
+export { FINAL_VERIFICATION_ITEMS, PLAN_SECTION_HEADERS, buildDraft, buildPlanSkeleton };
 
 const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,79}$/;
 
@@ -151,140 +135,6 @@ export function isUlwArtifact(content) {
 	return isPlan || isDraft;
 }
 
-export function buildDraft(slug, intent, { reviewRequired = false } = {}) {
-	const assumptionsNote =
-		intent === "unclear"
-			? "Intent is UNCLEAR: research resolves ambiguity, defaults are adopted (not asked), and each is surfaced in the plan's human TL;DR for veto."
-			: "Record any default you adopt instead of asking, so the user can veto it at the gate.";
-	const reviewState = reviewRequired
-		? `review_required: true
-plan_path: .omo/plans/${slug}.md
-plan_sha256: null
-review_round_id: null
-pending-action: write and review .omo/plans/${slug}.md
-review:
-  momus:
-    status: pending
-    workspace_root: null
-    runtime_home: null
-    target: .omo/plans/${slug}.md
-    round_id: null
-    plan_sha256: null
-    launch_id: null
-    session: null
-    result: null
-  independent:
-    status: pending
-    workspace_root: null
-    runtime_home: null
-    target: .omo/plans/${slug}.md
-    round_id: null
-    plan_sha256: null
-    launch_id: null
-    session: null
-    result: null`
-		: `review_required: false
-pending-action: write .omo/plans/${slug}.md`;
-	return `---
-slug: ${slug}
-status: drafting
-intent: ${intent}
-${reviewState}
-approach: <fill: the approach you intend to plan>
----
-
-# Draft: ${slug}
-
-## Components (topology ledger)
-<!-- Lock the SHAPE before depth. One row per top-level component that can succeed or fail independently. -->
-<!-- id | outcome (one line) | status: active|deferred | evidence path -->
-
-## Open assumptions (announced defaults)
-<!-- ${assumptionsNote} -->
-<!-- assumption | adopted default | rationale | reversible? -->
-
-## Findings (cited - path:lines)
-
-## Decisions (with rationale)
-
-## Scope IN
-
-## Scope OUT (Must NOT have)
-
-## Open questions
-
-## Approval gate
-status: drafting
-<!-- When exploration is exhausted and unknowns are answered, set status: awaiting-approval. -->
-<!-- That durable record is the loop guard: on a later turn read it and resume at the gate instead of re-running exploration. -->
-`;
-}
-
-export function buildPlanSkeleton(slug, intent) {
-	const decisionsLine =
-		intent === "unclear"
-			? "**Decisions I made for you:** <fill last - the best-practice defaults you adopted; the user vetoes any here>"
-			: "**Decisions to sanity-check:** <fill last - the few choices worth a human glance>";
-	return `# ${slug} - Work Plan
-
-## TL;DR (For humans)
-<!-- Fill this LAST, after the detailed plan below is written, so it summarizes the REAL plan. -->
-<!-- Plain English for a non-engineer: NO file paths, NO todo numbers, NO wave/agent/tool names. -->
-
-**What you'll get:** <fill last - deliverables in human terms, 1-2 sentences>
-
-**Why this approach:** <fill last - the one or two load-bearing decisions and why>
-
-**What it will NOT do:** <fill last - 1-3 plain lines mirroring Must NOT have>
-
-**Effort:** <Quick | Short | Medium | Large | XL>
-**Risk:** <Low | Medium | High> - <one-line driver>
-${decisionsLine}
-
-Your next move: <fill - e.g. approve, or run a high-accuracy review>. Full execution detail follows below.
-
----
-
-> TL;DR (machine): <1 line - effort, risk, deliverables>
-
-## Scope
-### Must have
-### Must NOT have (guardrails, anti-slop, scope boundaries)
-
-## Verification strategy
-> Zero human intervention - all verification is agent-executed.
-- Test decision: <TDD | tests-after | none> + framework
-- Evidence: <attemptDir>/task-<N>-${slug}.<ext> (attemptDir = currentAttemptDir from 'omo-agent-toolkit ulw-loop status --json', .omo/evidence/ulw/<session>/<goalId>/a<attempt>; outside ulw-loop use .omo/evidence/)
-
-## Execution strategy
-### Parallel execution waves
-> Target 5-8 todos per wave. Fewer than 3 (except the final) means you under-split.
-
-### Dependency matrix
-| Todo | Depends on | Blocks | Can parallelize with |
-| --- | --- | --- | --- |
-
-## Todos
-> Implementation + Test = ONE todo. Never separate.
-<!-- APPEND TASK BATCHES BELOW THIS LINE WITH edit/apply_patch - never rewrite the headers above. -->
-- [ ] 1. <title>
-  What to do / Must NOT do: <...>
-  Parallelization: Wave <N> | Blocked by: <...> | Blocks: <...>
-  References (executor has NO interview context - be exhaustive): <src/path:lines>
-  Acceptance criteria (agent-executable): <exact command or assertion>
-  QA scenarios (name the exact tool + invocation): happy + failure, Evidence <attemptDir>/task-1-${slug}.<ext>
-  Commit: <Y/N> | <type>(<scope>): <summary>
-
-## Final verification wave
-> Runs in parallel after ALL todos. ALL must APPROVE. Surface results and wait for the user's explicit okay before declaring complete.
-${FINAL_VERIFICATION_ITEMS.map((item) => `- [ ] ${item}`).join("\n")}
-
-## Commit strategy
-
-## Success criteria
-`;
-}
-
 // Resume-safe write: plain re-run on an existing ulw-plan artifact is a no-op
 // success; --reset overwrites but refuses to discard a hand-edited file unless
 // --force is also passed.

package/packages/shared-skills/skills/ulw-research/AGENTS.md

@@ -0,0 +1,63 @@
+# ulw-research — Research Orchestration + report-tools Runtime
+
+## OVERVIEW
+
+`SKILL.md` is the research orchestration contract (team-first saturation, claim graph, convergence, delivery). `scripts/` is the deliverable runtime that contract calls: `report-tools.mjs`, a zero-dependency Node CLI for the deliverable phase (outcome manifest, static and layout gates, bounded repair, format extraction). `references/` holds the edition-neutral deliverable contract and the defect glossary. Earned this file: the only shared skill whose runtime is overlaid into a second, separately authored edition (the senpi native skill) at sync time.
+
+## STRUCTURE
+
+```
+ulw-research/
+├── SKILL.md                         # shared-edition prose contract (router to the references)
+├── references/
+│   ├── deliverable-phase.md         # lanes, state, destination defaults, interview, memory episodes, design spec, gates, repair, manifest, command reference
+│   ├── report-gates.md              # one row per defect code: severity, integrity, what it detects, how to fix
+│   └── latex-report.md
+└── scripts/
+    ├── report-tools.mjs             # CLI entry + dispatcher (COMMANDS, run, main)
+    ├── report-tools-commands.mjs    # one function per subcommand
+    ├── cli-support.mjs / entry-guard.mjs   # flags, CliError, exit codes, atomic JSON, symlink-safe entry check
+    ├── contracts.mjs                # frozen vocabulary: DEFECT_CODES (severity lives only here), enums, manifest + repair-state validators
+    ├── outcome.mjs                  # outcome.json manifest, deliverable state, verify, closing briefing
+    ├── repair-tracker.mjs           # bounded repair decisions (attempts, plateau, oscillation, wall clock, integrity codes)
+    ├── html-lite.mjs / entities.mjs # HTML tokenizer, selector paths, prose text
+    ├── css-lite.mjs / design-spec.mjs      # CSS scanning, palette + lineage parsing, design-spec rendering
+    ├── gates-static.mjs + gates-text.mjs / gates-figures.mjs / gates-structure.mjs   # static gates G1-G15
+    ├── layout-probe.mjs / gates-layout.mjs # in-page probe source + layout gates L1-L5 over its output
+    ├── format-extract.mjs / format-extract-css.mjs   # design-spec draft from a pointed-at HTML or Markdown document
+    ├── *.test.ts                    # co-located bun tests, one per module (unshipped)
+    └── tests/fixtures/              # good/bad reports, boxes.json, reference docs (unshipped)
+```
+
+## SURFACE
+
+`node "$SKILL_DIR/scripts/report-tools.mjs" <command>`: `check`, `layout-probe`, `repair decide`, `outcome init`, `outcome set`, `outcome gate`, `outcome render`, `outcome state`, `outcome verify`, `outcome finish`, `outcome briefing`, `format-extract`, `--help --json`. Exit codes: `0` pass, `1` semantic failure (blockers, a failed verify, a blocked repair), `2` usage or IO. JSON on stdout, one summary line on stderr. Flags per command: `references/deliverable-phase.md` section 10.
+
+## CONVENTIONS
+
+- Zero runtime dependencies: plain ESM `.mjs`, `node:` builtins and sibling imports only, no `Bun.*`. Runs under Node >= 20 or Bun 1.4 (global `fetch` for `format-extract --from-url`).
+- Each `.mjs` stays at or under 250 lines; split by responsibility, never by size.
+- The CLI never launches a browser. The layout probe is printed as one async expression; the orchestrator evaluates it through the browser skill's owned headless engine and passes the result back with `check --layout`.
+- Time is always injected (`--now`, `startedAt`); no module reads the clock inside a decision.
+- Tests are co-located given/when/then bun tests; CLI tests spawn `node` with bun removed from `PATH`. Fixtures live only under `scripts/tests/fixtures/`, are depersonalized, and never ship.
+- The senpi source dir (`packages/omo-senpi/skills/ulw-research/`) intentionally has no `scripts/`, `references/report-gates.md`, or `references/deliverable-phase.md`: the senpi sync overlays them from here byte-for-byte (`sharedAssets` in `packages/omo-senpi/plugin/scripts/native-skill-sources.mjs`), and both editions' sync suites assert the shipped copies equal these sources.
+- References and scripts carry no Hangul (Korean match strings are `\u` escapes) and never three consecutive newlines (the senpi sync normalizes those and would break byte equality).
+
+## ANTI-PATTERNS
+
+- NEVER hand-edit a shipped copy under `packages/omo-senpi/plugin/skills/` or the packaged plugin tree; edit here and re-sync.
+- NEVER add a severity override or a caller-supplied severity. The only sanctioned exception is `unsourced_number` following the design spec's `Lineage:` mode.
+- Never let a gate or the repair loop silently skip: an unrunnable gate is recorded `not_run`, and an integrity code blocks delivery.
+- Never name a browser library in the references or `SKILL.md`; route through the browser skill.
+- Never test prose: pin machine-consumed values (CLI JSON, exit codes, extractor output, tracker decisions, defect-code vocabulary) and shipped-copy equality only.
+
+## COMMANDS
+
+```bash
+# from the repository root
+bun test --timeout 20000 packages/shared-skills/skills/ulw-research/scripts
+node packages/shared-skills/skills/ulw-research/scripts/report-tools.mjs --help --json
+node packages/omo-senpi/plugin/scripts/sync-skills.mjs && bun test packages/omo-senpi/src/skills-sync.test.ts
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).