wb-flow 1.0.0-r01

package/templates/commands/wbLicense/wbLicense_template.md

@@ -0,0 +1,148 @@
+# /wbLicense: Execution Template
+
+
+<!-- HELP_GATE_START -->
+## Help intercept (handle FIRST — before any other action)
+
+**If `$ARGUMENTS` contains `--help`, `-h`, or `--h`** (case-insensitive, anywhere in the args), DO NOT execute the command's normal procedure. Instead:
+
+1. Output the **HELP BLOCK** below verbatim (rendered as markdown).
+2. Stop. Do not perform any file reads, writes, or other tool calls.
+3. Do not generate any reports under `.wb/workflows/reports/`.
+
+Otherwise, ignore this section and proceed to the rest of the template.
+
+### HELP BLOCK — `/wbLicense`
+
+## Two modes
+
+```
+/wbLicense <file>        # inject __WBC_PRO__ gate + emit pro-required event
+/wbLicense <folder>      # audit package for tier leaks and pattern drift
+```
+
+## When to run each
+
+**File mode:** immediately after shipping a new premium feature. Before `/wbGit`. Before any consumer imports the unguarded export.
+
+**Folder mode:** periodically (monthly is fine) and always before `/wbRelease` on packages that have Pro features.
+
+## The gate pattern this project uses
+
+```js
+if (typeof __WBC_PRO__ === 'undefined' || !__WBC_PRO__) {
+  this.$emit('pro-required', { feature: '<name>' });
+  return;
+}
+// premium logic here
+```
+
+Always `typeof` check first — `__WBC_PRO__` is undefined in dev without the define plugin, and ReferenceError kills the flow. The `pro-required` event is the project's convention for surfacing upgrade CTAs to the parent.
+
+If you find a different pattern in existing code (global `window.__WBC_PRO__`, env var `VITE_WBC_PRO`, silent fallback), it's drift. Audit mode flags this.
+
+## The security caveat
+
+`__WBC_PRO__` is **client-side**. Anyone with DevTools can flip it. This is by design — the wbc-ui2 model is:
+
+- **Client gate** (`__WBC_PRO__`) = convenience barrier. Stops honest users from wandering into Pro features by accident.
+- **Server gate** (in your API) = actual security. Stops adversarial users.
+
+`/wbLicense` handles the first. `/wbSecure` + your backend handle the second. Don't confuse them.
+
+## Reading the audit output
+
+Three finding classes, ranked:
+
+- **LEAK** = Pro code runs for Free users. High priority.
+- **INCONSISTENT** = gate works but pattern differs from convention. Medium priority.
+- **OK** = correctly gated. Just reassurance.
+
+Every audit also names what it didn't check (notably: runtime bypass, server-side enforcement, business logic).
+
+## The one mistake to avoid
+
+**Treating `/wbLicense` as security.** It's not. If someone bypasses the gate and accesses a Pro feature, the worst case should be: they use a nice-to-have for free. The *data* should never be at risk because the server should enforce the same tier check independently. If your Pro feature leaks sensitive data when the client gate is bypassed, the feature is designed wrong, not the gate.
+
+## When /wbLicense is the wrong command
+
+- Pure security / vulnerability scan → `/wbSecure`.
+- Generic code quality review → `/wbAudit`.
+- Finding leaks in existing ungated code you haven't tier-decided yet → `/wbVision` first (what's Pro?), then `/wbLicense`.
+
+> For deeper reading: [`docs_claude/commands/wbLicense/wbLicense_practical_claude.md`](../../docs/docs_claude/commands/wbLicense/wbLicense_practical_claude.md) (or the `_eli5_`, `_expert_`, `_examples_` siblings).
+
+<!-- FLAGS_TABLE_START -->
+## Flags & shortcuts
+
+Both forms are equivalent — pass either:
+
+| Long form | Shortcut |
+|---|---|
+| `--scope` | `-s` |
+
+`-h` / `--help` / `--h` (any command) prints this help block instead of executing.
+## Self-correct mode (dual-mode invocation)
+
+```
+/wbLicense <scope_folder>           # normal mode — produce a fresh output file
+/wbLicense <previous_output_file>   # self-correct mode — verify & repair the file in place
+```
+
+When the first arg is an existing output file from a prior `/wbLicense` run (detected by its first H1 — see this template's **Detection** section), the command runs in **verify-and-repair** mode: gap-fills missing fields, normalizes links, ticks done/valid checkboxes whose reports exist, never rewrites authored content. See [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3.
+
+<!-- FLAGS_TABLE_END -->
+<!-- HELP_GATE_END -->
+
+<!-- FLAG_NORMALIZE_START -->
+## Flag normalization (apply BEFORE parsing args)
+
+Before processing `$ARGUMENTS`, normalize these short-form flags to their long equivalents:
+
+- `-s` → `--scope`
+
+The rest of this template documents only the long forms; the substitution above is the only place short forms are mentioned.
+<!-- FLAG_NORMALIZE_END -->
+
+
+
+**ROLE:** The Gatekeeper
+**TARGET:** The provided component or application path.
+**Read first:** [`../_shared/output_conventions.md`](../_shared/output_conventions.md) — applies to the verification report (relative links, full-syntax commands, self-correct mode).
+
+---
+
+## ━━━ DETECTION (Self-Correct Mode) ━━━
+
+Trigger self-correct when the input file's first H1 matches:
+`# License: <scope> — <YYYY-MM-DD>` *(if a report file is produced).*
+
+Behavior is defined in [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3.
+
+License-specific gap-fills:
+
+- Plain-text component file references → relative markdown links per §1.
+- Missing tier coverage (Free / Pro / Dev) in the verification table → fill from current `monorepo_rules.md`.
+
+---
+
+## ━━━ OBJECTIVE ━━━
+Your job is to enforce the business logic of the monorepo. Ensure that premium components are properly gated behind Pro/Dev tier checks and that licensing mock mechanisms are safely implemented.
+
+## ━━━ PHASE 1: CONTEXT SYNC ━━━
+1. Read the local `context.md`.
+2. Strictly review the global `core2/.wb/workflows/monorepo_rules.md` (specifically the Licensing and Tier logic section).
+
+## ━━━ PHASE 2: IMPLEMENTATION ━━━
+1. Analyze the target component. Does it expose premium features to Free users?
+2. Inject the standard licensing wrapper or API key simulation logic as defined in the monorepo rules.
+3. Ensure there is a graceful fallback UI for users who do not have the Pro license (e.g., a "Upgrade to Pro" overlay).
+
+## ━━━ PHASE 3: VERIFICATION ━━━
+Provide a short summary report confirming that the component now correctly handles `Free`, `Pro`, and `Dev` environments. Apply output_conventions.md §1 (relative links to every file changed) and §2 (full-syntax for any /wb* command cited).
+
+End the report with:
+
+## 🧭 What's Next?
+
+Run `/wbNext <target_folder>` to get a current, ranked list of next actions (typically `/wbTest <target> --scope=licensing` to verify the gate works in all 3 tiers).

package/templates/commands/wbMonetize/wbMonetize_template.md

@@ -0,0 +1,113 @@
+# /wbMonetize: Execution Template
+
+
+<!-- HELP_GATE_START -->
+## Help intercept (handle FIRST — before any other action)
+
+**If `$ARGUMENTS` contains `--help`, `-h`, or `--h`** (case-insensitive, anywhere in the args), DO NOT execute the command's normal procedure. Instead:
+
+1. Output the **HELP BLOCK** below verbatim (rendered as markdown).
+2. Stop. Do not perform any file reads, writes, or other tool calls.
+3. Do not generate any reports under `.wb/workflows/reports/`.
+
+Otherwise, ignore this section and proceed to the rest of the template.
+
+### HELP BLOCK — `/wbMonetize`
+
+## One command, three verdicts (auto-detected)
+
+```
+/wbMonetize <package-path>                  # detect → bootstrap or maintenance
+/wbMonetize <package-path> "<split spec>"   # bootstrap with explicit split, no prompt
+```
+
+The mode is **detected**, not flagged. The detection is hybrid:
+
+- **Marker:** `package.json::wbMonetize` — authoritative.
+- **Heuristic:** scan source for `__WBC_DEV__`, `isWb[Pkg]Pro`, `_wb_[pkg]_auth`, the `created()` hook.
+
+| Marker | Heuristic | Verdict |
+|---|---|---|
+| absent | no gating | **BOOTSTRAP** — inject full tier system once |
+| present | gating present | **MAINTENANCE** — verify & repair plumbing |
+| absent | partial gating | **ABORT** — ask user; manual gating exists outside the convention |
+
+## When to run each
+
+**Bootstrap** is one-shot per package, ideally on a feature branch with a clean working tree, before the package has any consumers depending on tier assumptions.
+
+**Maintenance** can run periodically — monthly is fine, or after any change to `monorepo_rules.md`. It will not move features between tiers; that's your manual call after bootstrap.
+
+## What bootstrap touches
+
+- Source: injects `__WBC_DEV__` reads, `isWb[Pkg]Pro` getter consumption, simulation-key support, cookie persistence (`_wb_[pkg]_auth`), the `created()` license hook from monorepo_rules.md §4, and free-fallback slots.
+- `package.json`: writes the `wbMonetize` marker with `version`, `tier`, `bootstrappedAt`, `rulesVersion`, `lastVerifiedAt`.
+- Tests: **flagged but not fixed.** Existing tests written against the open API will break. Fix them manually or via `/wbTest`.
+
+## What maintenance touches
+
+- Plumbing only (cookie names, hook structure, getter wiring) when `rulesVersion` shows drift.
+- Marker (`lastVerifiedAt`, `rulesVersion`).
+- **Never** feature placement. Never moves a feature from Free to Pro or vice versa. That's your call.
+
+## The advisory section
+
+Maintenance runs include an advisory pass: "feature X could be promoted to Pro", "feature Y might be over-gated". These are suggestions, never patches. The whole point of the bootstrap-once design is that you control the monetization surface after the initial setup.
+
+## When `/wbMonetize` is the wrong command
+
+- Per-component gate injection on an already-monetized package → `/wbLicense`.
+- Producing dev/free/pro **build artifacts** → not yet a command; for now, handled by your build config.
+- Coverage report across the whole monorepo → not yet a command; consider running `/wbMonetize` per-package and aggregating manually.
+- Moving a single feature between tiers → manual edit. Not in scope.
+
+## The one mistake to avoid
+
+**Re-running bootstrap by editing the marker out.** If you want to re-bootstrap a package (rare), do it intentionally: revert the package, delete the marker, run `/wbMonetize` again. Don't half-strip the marker and hope the heuristic catches it — that's the abort case, and you'll have to confirm the override anyway.
+
+> For deeper reading: [`docs_claude/commands/wbMonetize/wbMonetize_practical_claude.md`](../../docs/docs_claude/commands/wbMonetize/wbMonetize_practical_claude.md) (or the `_eli5_`, `_expert_`, `_examples_` siblings).
+<!-- HELP_GATE_END -->
+
+**ROLE:** The Monetization Bootstrapper
+**TARGET:** A package path (e.g., `packages/wb-dataviewer`).
+
+## ━━━ OBJECTIVE ━━━
+Convert a tier-unaware package into a tier-aware one (first run), or verify and repair the monetization plumbing of an already-monetized package (subsequent runs). This command sets up keys, simulation logic, cookie persistence, and the initial Free / Pro / Dev split — once. After bootstrap, feature movement between tiers is the user's manual decision; this command only maintains the verification logic.
+
+## ━━━ PHASE 1: CONTEXT SYNC ━━━
+1. Read the local `context.md` and `dev.md` of the target package.
+2. Strictly review the global `core2/.wb/workflows/monorepo_rules.md` — sections 3 (Tier System) and 4 (Licensing Flow).
+3. Detect the package's monetization state using **the hybrid mechanism (option 3)**:
+   - **Authoritative marker:** look for `wbMonetize` field in the package's `package.json` (or `.wb-monetized.json` in the package root). If present, package is monetized.
+   - **Heuristic safety check:** independently scan the source for any of `__WBC_DEV__`, `isWb[Pkg]Pro`, `userTier`, `WB[Pkg]_SIMULATE_PRO`, the `created()` license hook, or `_wb_[pkg]_auth` cookies.
+   - **Reconcile:** marker present + heuristic finds gating → MAINTENANCE mode. Marker absent + heuristic finds no gating → BOOTSTRAP mode. Marker absent + heuristic finds gating → ABORT and ask the user (manual gating exists; bootstrapping would corrupt it).
+
+## ━━━ PHASE 2: BOOTSTRAP MODE (first run) ━━━
+Run only if Phase 1 detected a tier-unaware package.
+
+1. **Propose the feature split.** Read the package's source. Categorize each public-facing feature/component/composable as Free, Pro, or Dev candidate. Surface the proposal in a table and pause for user confirmation. If the user passed a description argument, use it to govern the split and skip the prompt.
+2. **Inject the gating constants.** Add `__WBC_DEV__` reads, `isWb[Pkg]Pro` store-getter consumption, and `userTier` resolution per monorepo_rules.md §3.
+3. **Wire simulation keys.** Implement support for `WB[Pkg]_SIMULATE_PRO` and `WBC_SIMULATE_PRO` per monorepo_rules.md §3.
+4. **Set up cookie persistence.** Use `_wb_[pkg]_auth` per the established convention.
+5. **Implement the `created()` license hook** in the appropriate root component(s), copied from monorepo_rules.md §4.
+6. **Add free-fallback UI scaffolding** for premium features (e.g., "Upgrade to Pro" overlay slot).
+7. **Update `package.json`** — add the `wbMonetize` field with `{ "version": "1.0", "tier": "premium", "bootstrappedAt": "<ISO date>", "rulesVersion": "<monorepo_rules.md version or hash>" }`.
+8. **Flag test impact.** List existing tests that will break; do not fix them — surface them so the user can update tests intentionally.
+
+## ━━━ PHASE 3: MAINTENANCE MODE (subsequent runs) ━━━
+Run only if Phase 1 detected an already-monetized package.
+
+1. **Report current state.** Output the existing Free / Pro / Dev split as a table. No changes proposed to feature placement.
+2. **Verify plumbing.** Check each of: gating constants present and named per current monorepo_rules.md, simulation keys wired to current store shape, cookie name matches `_wb_[pkg]_auth` convention, `created()` hook matches canonical form, free-fallback UI hooks intact.
+3. **Repair drift.** If monorepo_rules.md has evolved since the bootstrap (the marker's `rulesVersion` is older than current), patch the verification logic to match. Do **not** touch feature placement.
+4. **Advisory pass on features.** Optionally suggest moves ("feature X is heavy and could be promoted to Pro"; "feature Y has minimal value, consider keeping Free"). Output as advice; do not patch.
+5. **Update marker.** Refresh `bootstrappedAt` (no — keep this immutable) but update `lastVerifiedAt` and `rulesVersion`.
+
+## ━━━ PHASE 4: VERIFICATION & REPORT ━━━
+Write a report at `reports/<YYYY>/<MM>/<DD>/monetize/monetize_<pkg>_<HHMMSS>.md` with: mode (bootstrap/maintenance), feature split, plumbing checklist, drift repairs applied, advisory suggestions, test-impact list, and the final state of the marker. End with recommended next commands (`/wbLicense` per-component, `/wbTest` for the breakage, `/wbRelease` if shipping).
+
+## ━━━ ABORT CONDITIONS ━━━
+- Marker absent but heuristic finds partial gating → abort, ask user.
+- Working tree dirty → abort, ask user to commit or stash first (bootstrap rewrites source).
+- Target is not a package directory (no `package.json`) → abort.
+- Target is on `main` branch and bootstrap mode → abort, recommend a feature branch.

package/templates/commands/wbNext/wbNext_template.md

@@ -0,0 +1,270 @@
+# wbNext Template v1.0 — Dynamic "What Should I Do Next?"
+
+
+<!-- HELP_GATE_START -->
+## Help intercept (handle FIRST — before any other action)
+
+**If `$ARGUMENTS` contains `--help`, `-h`, or `--h`** (case-insensitive, anywhere in the args), DO NOT execute the command's normal procedure. Instead:
+
+1. Output the **HELP BLOCK** below verbatim (rendered as markdown).
+2. Stop. Do not perform any file reads, writes, or other tool calls.
+3. Do not generate any reports under `.wb/workflows/reports/`.
+
+Otherwise, ignore this section and proceed to the rest of the template.
+
+### HELP BLOCK — `/wbNext`
+
+## When to run it
+
+- **You sat down and don't know what to do.** This is the entire job of `/wbNext`.
+- **End of a logical unit of work** — you finished a thing; what's the next thing?
+- **After a long absence** — back from vacation, no idea what state the repo is in.
+
+Do NOT run it:
+
+- When you already have a `/wbPlan` open. Execute the next unchecked row instead.
+- When you have a clear priority. The command's job is to break ties; don't ask it to override your judgment.
+- More than once per session. Re-running it produces the same answer 95% of the time.
+
+## The two forms
+
+```
+/wbNext                   # whole-monorepo scan, single recommendation
+/wbNext <package-path>    # narrowed to one package
+```
+
+## What it does, in order
+
+1. **Reads recent `reports/`** (default: `--since=7d`). Looks for the latest `audit`, `plan`, `debug`, `standup`, `review`.
+2. **Reads `git status`** and the last 3 commits. Has anything been started but not committed?
+3. **Reads `dev.md`** for the target package(s). Are there refusals that flag work?
+4. **Computes a single recommendation** with three things: *what* to run, *why* it's the best next move, and *what other options were considered and rejected*.
+
+## The output shape
+
+```text
+Recommendation: /wbAudit packages/wb-core/
+
+Why:
+- Last /wbAudit on wb-core was 14 days ago.
+- 8 commits since then; 3 touch the public API.
+- /wbTest passed yesterday, so the gate is green for an audit.
+- /wbStandup last week flagged "wb-core context drift" — audit will catch it.
+
+Considered and rejected:
+- /wbContext: stale-but-not-blocking; audit covers more ground.
+- /wbDebug: no open errors in reports/.
+- /wbRefactor: refactor without audit is the #1 mistake (see playbook).
+```
+
+The "considered and rejected" section is the real value. Without it, you're trusting a black box. With it, you can disagree if your judgment differs.
+
+## When `/wbNext` will refuse to recommend
+
+- **Working tree is dirty with uncommitted, unrelated changes.** First clean up; mixed states make every recommendation noisy.
+- **No `reports/` exist for the target.** Run `/wbContext` first; `/wbNext` needs at least one prior signal.
+- **Conflicting signals** (e.g., audit says ship, secure says don't). The command names the conflict and asks you to resolve it before recommending.
+
+## When `/wbNext` is the wrong command
+
+- You want a roadmap, not a single step → `/wbPlan` or `/wbVision`.
+- You want a list of *everything* in flight → `/wbStandup`, not `/wbNext`.
+- You want the AI to *do* the work instead of recommending it → describe the task directly.
+
+## The one mistake to avoid
+
+**Running `/wbNext` and then ignoring its recommendation because you "had a feeling."** Either run what it suggests, or take 60 seconds to articulate why your alternative is better. The articulation often reveals you were going to make the second-best choice for vibes-based reasons.
+
+That said: `/wbNext` doesn't know about external pressure (deadlines, support tickets, what your boss said this morning). Override is fine when you have outside information; override is dangerous when you have only intuition.
+
+> For deeper reading: [`docs_claude/commands/wbNext/wbNext_practical_claude.md`](../../docs/docs_claude/commands/wbNext/wbNext_practical_claude.md) (or the `_eli5_`, `_expert_`, `_examples_` siblings).
+
+<!-- FLAGS_TABLE_START -->
+## Flags & shortcuts
+
+Both forms are equivalent — pass either:
+
+| Long form | Shortcut |
+|---|---|
+| `--scope` | `-s` |
+| `--since` | `-S` |
+
+`-h` / `--help` / `--h` (any command) prints this help block instead of executing.
+## Self-correct mode (dual-mode invocation)
+
+```
+/wbNext <scope_folder>           # normal mode — produce a fresh output file
+/wbNext <previous_output_file>   # self-correct mode — verify & repair the file in place
+```
+
+When the first arg is an existing output file from a prior `/wbNext` run (detected by its first H1 — see this template's **Detection** section), the command runs in **verify-and-repair** mode: gap-fills missing fields, normalizes links, ticks done/valid checkboxes whose reports exist, never rewrites authored content. See [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3.
+
+<!-- FLAGS_TABLE_END -->
+<!-- HELP_GATE_END -->
+
+<!-- FLAG_NORMALIZE_START -->
+## Flag normalization (apply BEFORE parsing args)
+
+Before processing `$ARGUMENTS`, normalize these short-form flags to their long equivalents:
+
+- `-s` → `--scope`
+- `-S` → `--since`
+
+The rest of this template documents only the long forms; the substitution above is the only place short forms are mentioned.
+<!-- FLAG_NORMALIZE_END -->
+
+
+
+> **Purpose:** When the user is stuck, mid-flow, or returning to a project, `/wbNext` analyzes the current state and produces a **ranked, actionable** list of suggestions — tailored to *this* project at *this* moment, not a static template.
+> **How to use**: Copy the prompt below, replace `__PLACEHOLDERS__`, paste to any AI agent.
+> Read [`../_shared/output_conventions.md`](../_shared/output_conventions.md) before producing output. Includes §9 **Action Type Tagging** — every suggested next-step row MUST carry a `Requires` tag (🧠/✅/🔨/📋, plain text) and the file MUST declare `type:` + `emits:` in YAML front-matter and include a `## 🔗 Action Types` legend.
+
+---
+
+## Filename & Folder Convention
+
+**Path:** `<target_folder>/.wb/workflows/reports/<YYYY>/<MM>/<DD>/nexts/next_<target>_<YYYYMMDD>.md`
+
+- No args → `<target_folder>` is the **monorepo root** (`core2/`).
+- `<folder_scope>` arg → `<target_folder>` is that folder.
+- `<existing_file>` arg (matches the next-output schema) → **self-correct mode** (see [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3): re-rank, fill missing fields, do not change structure.
+
+**Cumulative behavior:**
+- Same day → if `next_<target>_<YYYYMMDD>.md` exists, **append a new section** `## 🔁 Run @ <HH:MM>` rather than overwriting.
+- New day → new file.
+
+---
+
+## Detection (Self-Correct Mode)
+
+Trigger self-correct when the input file's first H1 matches:
+`# Next: <scope> — <YYYY-MM-DD>`
+
+In self-correct mode, the command:
+- Re-ranks suggestions based on the current state of the project (some may now be done, blockers may have cleared).
+- Fills missing `Origin`, `Verify`, `Est. Time`, `Suggested Worker` cells.
+- Converts plain-text file references to relative markdown links per [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §1.
+- Does **not** delete or reorder rows the user has annotated.
+- Appends one trailing line: `> _Self-corrected: <YYYY-MM-DD HH:MM> by <model>_`
+
+---
+
+## 🚀 The Suggestion Prompt (copy from here ↓)
+
+```
+━━━━━━━━━━━━━ /wbNext v1.0 ━━━━━━━━━━━━━
+
+📁 SCOPE: __TARGET_FOLDER_OR_MONOREPO_ROOT__
+📅 DATE: __TODAY__
+🤖 MODEL: __YOUR_MODEL_NAME__
+🖥️ CLIENT: __YOUR_CLIENT__
+📂 OUTPUT FILE: __TARGET_FOLDER__/.wb/workflows/reports/__YYYY__/__MM__/__DD__/nexts/next___TARGET_NAME_____YYYYMMDD__.md
+
+━━━ INPUT ━━━
+
+If invoked with no args → analyze the monorepo root.
+If invoked with a folder → analyze that folder.
+If invoked with a file matching the next-output schema → SELF-CORRECT MODE
+  (see ../_shared/output_conventions.md §3).
+
+━━━ CONTEXT TO SCAN ━━━
+
+1. Most recent files under `<scope>/.wb/workflows/reports/`:
+   - `plans/plan_*.md` — what tasks are pending? Which are blocked? Which Done-but-not-Valid?
+   - `audits/audit_*.md` — any P1 findings without a corresponding plan task?
+   - `reviews/review_*.md` — any unresolved review comments?
+   - `tasks_reports/task_*.md` — any tasks claiming Done but the report is missing or empty?
+2. Read `<scope>/.wb/workflows/context.md` for project state.
+3. Check `../model_recommendations.md` for worker/validator suggestions.
+4. Look for stale TODOs in code (>30 days), unresolved merge conflicts, broken tests in CI.
+
+━━━ OUTPUT FORMAT ━━━
+
+Produce a markdown file at the OUTPUT FILE path above with this exact structure:
+
+# Next: <scope> — <YYYY-MM-DD>
+
+> **Target:** <relative-link-to-scope-folder>
+> **Created by:** <model> via <client>
+> **Time:** <YYYY-MM-DD HH:MM>
+
+---
+
+## 🧭 Situation Summary
+
+<2–4 sentences: where the project stands right now, what just happened, what is blocked.>
+
+## 🎯 Suggested Next Actions (ranked)
+
+| # | Requires | Suggestion | Target | Why now | Origin | Verify | Est. Time | Suggested Worker | Blockers |
+|---|---|-----------|--------|---------|--------|--------|-----------|------------------|----------|
+| 1 | 🔨 Worker | <short imperative, e.g. "Validate task 1 of today's plan"> | <relative-link to file/folder> | <1 sentence: why this is the most valuable next move> | <full /wbX command that surfaced this, OR `—` if /wbNext-native> | <full /wbX command to confirm done> | <e.g. 15m, 2h, 0.5d> | <e.g. Opus 4.7 / Gemini 3.1 Pro / human> | <relative-link or `—`> |
+| 2 | ✅ Validator | ... | ... | ... | ... | ... | ... | ... | ... |
+
+**Column rules:**
+- **Requires**: plain-text action-type tag (`🧠 Planner` / `✅ Validator` / `🔨 Worker` / `📋 Mechanical`) per `_shared/output_conventions.md` §9.3. Mandatory; the file MUST also include a `## 🔗 Action Types` legend before the Generated Files footer. Self-correct mode (§3) MUST insert this column on legacy files.
+- **Target**: relative markdown link from THIS file's directory (per output_conventions.md §1). Apply §1.1 link beautification: basename label, full relative href.
+- **Origin**: full invocable command (per output_conventions.md §2). Use `—` when the suggestion is /wbNext-native (no upstream command surfaced it).
+- **Verify**: always fillable — the command that proves the action is done.
+- **Suggested Worker**: pull from model_recommendations.md; include `human` when the action requires judgment beyond an AI agent.
+- **Blockers**: relative link to the blocking file/issue, or `—` if none.
+
+## 💡 Tips & Warnings
+
+| Type | Note |
+|---|---|
+| 💡 Tip | <optional: a non-obvious observation, e.g. "Task 3 has the same fix pattern as last week's task 7 — reuse that worker."> |
+| ⚠️ Warning | <optional: a risk, e.g. "Plan file has 4 Done-but-not-Valid tasks older than 24h — validation drift risk."> |
+
+---
+
+> _Generated by /wbNext at <YYYY-MM-DD HH:MM> via <model>._
+
+━━━ RULES ━━━
+
+1. Suggestions must be SPECIFIC. "Run tests" is bad. "Run /wbTest apps/wb-core/md.wbc-ui.com/ --scope=task-1 to verify ARCH-1 fix" is good.
+2. Rank by VALUE × URGENCY, not by ease. The #1 suggestion should unblock the most downstream work.
+3. Maximum 7 suggestions. If you need more, the project is too broad — split the scope.
+4. Always include at least one Verify command per row.
+5. Apply relative-link rule (output_conventions.md §1) to EVERY local file mention.
+6. If self-correcting an existing file, preserve user-authored notes verbatim; only fill cells that are blank or stale.
+━━━ AUTO-APPEND FOOTER ━━━
+
+At the VERY END of the file (after "What's Next?"), you MUST append the `## 📂 Generated Files (__YYYYMMDD__)` cross-link footer. Do NOT use simple tables. You MUST use the rich "Tier 1" layout from `_shared/output_conventions.md` §5.
+
+Format required:
+```markdown
+---
+## 📂 Generated Files (__YYYYMMDD__)
+> Auto-appended per `_shared/output_conventions.md` §5. Same-level snapshot of top-level command outputs at write time.
+
+### 📚 Base Reference Files
+| Type | File | Description |
+|---|---|---|
+| Foundational | [context.md](../../../../../context.md) | Permanent Identity and Architecture (Source of Truth) |
+| Snapshot | [context_<scope>_<date>.md](../contexts/context_<scope>_<date>.md) | Daily snapshot used for current session context |
+| Foundational | [dev.md](../../../../../dev.md) | Permanent Development Commands and Status |
+
+### Global Files (`core2/` monorepo root)
+| Category | File | Source Command |
+|---|---|---|
+| Reports | [audit_core2_<date>.md](../../../../../../../../../../.wb/workflows/reports/<YYYY>/<MM>/<DD>/audits/audit_core2_<date>.md) | `/wbAudit core2/` |
+| Reports | [plan_core2_<date>.md](../../../../../../../../../../.wb/workflows/reports/<YYYY>/<MM>/<DD>/plans/plan_core2_<date>.md) | `/wbPlan core2/` |
+| Tracks | [track_core2_<date>.md](../../../../../../../../../../.wb/workflows/tracks/<YYYY>/<MM>/<DD>/track_core2_<date>.md) | `/wbTrack core2/` |
+
+<details>
+  <summary>📂 Sub-Package: [Active Package Name]</summary>
+
+| Category | File | Source Command |
+|---|---|---|
+| Reports | [audit_subpkg_<date>.md](../../../../../../../../../../apps/wb-core/subpkg/.wb/workflows/reports/<YYYY>/<MM>/<DD>/audits/audit_subpkg_<date>.md) | `/wbAudit` |
+
+</details>
+```
+```
+
+---
+
+## Worked Example
+
+See [`wbNext_examples_claude.md`](../../docs/docs_claude/commands/wbNext/wbNext_examples_claude.md) (or the gemini edition) for full input/output samples.