@su-record/vibe 3.2.1 → 3.2.3

package/skills/{commit-push-pr → vibe.commit-push-pr}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: commit-push-pr
-invocation: [auto, chain]
+name: vibe.commit-push-pr
+invocation: [auto]
 tier: optional
 description: "Commit, push, and create PR in one go. Auto-activates on commit, PR, push keywords."
 triggers: [commit, push, PR, pull request, merge]

package/skills/{context7-usage → vibe.context7-usage}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: context7-usage
+name: vibe.context7-usage
 invocation: [auto]
 tier: optional
 description: "Context7 plugin for latest library documentation. Auto-activates when docs, documentation, latest version, official docs, API reference, or library help is needed."

package/skills/vibe.contract/SKILL.md

@@ -30,7 +30,7 @@ A contract = any **interface shape** that external consumers (clients, other ser
 
 ## Process
 
-Load skill `contract` with subcommand: `$ARGUMENTS`
+Execute the bundled implementation below with subcommand: `$ARGUMENTS`
 
 **Core steps**:
 
@@ -105,3 +105,164 @@ Right after `/vibe.spec` finishes writing the SPEC, auto-invoke `/vibe.contract
 ---
 
 ARGUMENTS: $ARGUMENTS
+
+## Bundled implementation
+
+
+# vibe.contract — API Contract Drift Detection
+
+**Purpose**: catch divergence between the SPEC's external contract and the actual implementation. Passing tests ≠ contract preserved.
+
+## Why this exists
+
+Hidden vibe-coding weakness: as the implementation grows, response shapes drift away from what the SPEC documents. Scenario tests still pass — but **external consumers break**. Manual SPEC-vs-code review is high-friction, so mechanize it.
+
+## Storage Contract
+
+```
+.vibe/contracts/
+  <feature>.md             # contract SSOT (extracted from SPEC)
+  <feature>.snapshot.md    # implementation snapshot (last check)
+```
+
+### Contract frontmatter schema
+
+```yaml
+---
+feature: string
+extracted-from: .vibe/specs/<feature>.md
+extracted-at: ISO-8601
+source-spec-hash: sha256  # for change detection
+endpoints:
+  - id: unique-kebab-id         # e.g. get-user-by-id
+    kind: http | graphql | event | function
+    # http
+    method: GET | POST | PUT | DELETE | PATCH
+    path: /users/:id
+    request:
+      params: { name: type, ... }
+      query: { name: type, ... }
+      body: { field: type, ... } | null
+      required: [field, ...]
+    response:
+      statusCodes:
+        200: { schema }
+        404: { error: string }
+      required-fields:
+        200: [id, email]
+    # graphql
+    operation: query | mutation
+    name: string
+    args: { ... }
+    returns: { ... }
+    # event
+    topic: string
+    payload: { ... }
+    # function
+    signature: "(a: string, b: number) => Promise<User>"
+    module: path/to/file.ts
+---
+```
+
+## Subcommands
+
+### 1. `extract <feature>` — pull contract out of the SPEC
+
+**Steps**:
+1. Load SPEC file (single file or split folder)
+2. Search sections in this order:
+   - `## API` / `## Endpoints` / `## Interface` / `## Contract`
+   - Markdown tables (method/path/request/response headers)
+   - OpenAPI/JSON Schema snippets inside code blocks
+3. Extraction failure (no such section) → **exit cleanly with `no-contract` state**. Not every feature has an API.
+4. Success → convert to the frontmatter structure
+5. `source-spec-hash`: sha256 of SPEC content (for next extract to detect change)
+6. Save to `.vibe/contracts/<feature>.md` (no-op if file exists with the same hash)
+
+**Caveat**: extraction is LLM-driven. Mark low-confidence fields with `# unconfirmed` so the user can review.
+
+### 2. `check <feature>` — contract vs implementation
+
+**Steps**:
+1. Load `.vibe/contracts/<feature>.md`. If missing → **suggest extract first**.
+2. For each endpoint, find implementation:
+   - http: detect framework (Express, Fastify, Next.js API routes, Hono, ...)
+   - graphql: locate resolver files
+   - event: producer/consumer code
+   - function: module export
+3. Extract implementation signature/schema → compare against contract
+4. Classify drift (severity table in command file)
+5. Persist snapshot at `.vibe/contracts/<feature>.snapshot.md` (current implementation state)
+
+### 3. `diff <feature>` — changes since last snapshot
+
+**Steps**:
+1. If `.snapshot.md` does not exist → say "first run" and exit
+2. Re-extract current implementation; compare to existing snapshot
+3. Output **only changed fields** in ASCII diff form:
+   ```
+   endpoints/get-user-by-id/response/200:
+     - email: string
+     + email: string | null   ← nullability added (P1 breaking)
+     + phoneNumber: string    ← new field (P3 safe)
+   ```
+4. On any drift, auto-call `/vibe.regress register --from-contract`
+
+## Drift Severity Matrix
+
+(matches command file — keep both in sync on edits)
+
+## Integration Points
+
+### From /vibe.spec
+
+Auto-invoke right after the SPEC is written:
+```
+Load skill `vibe.contract` with: extract <feature>
+```
+Failure does not stop `/vibe.spec` (extraction is optional). On success, `/vibe.run` references this contract.
+
+### From /vibe.verify
+
+After all scenarios pass:
+```
+Load skill `vibe.contract` with: check <feature>
+```
+- no drift → verify still passes
+- P1 drift → demote verify to fail; auto-register
+- P2 / P3 drift → warning only; verify still passes
+
+### To /vibe.regress
+
+On P1 drift:
+```
+Load skill `vibe.regress` with:
+  subcommand: register --from-contract
+  feature: <feature>
+  symptom: "Contract drift: <endpoint-id> <drift-type>"
+  root-cause-tag: integration
+```
+
+## Framework Detection Rules
+
+HTTP framework detection order:
+1. `package.json` dependencies: `next` → Next.js API routes
+2. `fastify` → Fastify
+3. `express` → Express
+4. `hono` → Hono
+5. `@nestjs/core` → NestJS
+6. None detected → ask user for manual mapping
+
+After detection, grep for each framework's **route definition pattern** to map endpoints:
+- Next.js: `pages/api/**` or `app/api/**/route.ts`
+- Express: `app.get|post|put|delete|patch\(`
+- Fastify: `fastify.get|post|...` or route configuration
+- Hono: `app.get|post|...`
+
+## Done Criteria
+
+- [ ] `extract` does not error on SPEC without an API section
+- [ ] `source-spec-hash`-based re-extract is a no-op when unchanged
+- [ ] `check` reports each drift with severity + location (file:line)
+- [ ] P1 drift always invokes `/vibe.regress`
+- [ ] On framework detection failure, ask the user — do not silently skip

package/skills/{create-prd → vibe.create-prd}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: create-prd
+name: vibe.create-prd
 invocation: [auto, chain]
 tier: standard
 description: "Create a Product Requirements Document using a comprehensive 8-section template covering problem, objectives, segments, value propositions, solution, and release planning."
 triggers: [prd, product requirements, feature spec, requirements document]
 priority: 60
-chain-next: [user-personas, prioritization-frameworks]
+chain-next: [vibe.user-personas, vibe.prioritization]
 ---
 
 # Create a Product Requirements Document

package/skills/{design-refine → vibe.design-refine}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: design-refine
+name: vibe.design-refine
 user-invocable: true
 invocation: [command, auto]
 tier: standard

package/skills/{design-review → vibe.design-review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: design-review
+name: vibe.design-review
 user-invocable: true
 invocation: [command, auto]
 tier: standard

package/skills/{design-teach → vibe.design-teach}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: design-teach
+name: vibe.design-teach
 user-invocable: false
 invocation: [auto]
 tier: standard

package/skills/{devlog → vibe.devlog}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: devlog
+name: vibe.devlog
 invocation: [auto]
 tier: standard
 description: "Auto-generate devlog posts from git commit history. Triggers every N commits, writes markdown to configured target repo."

package/skills/vibe.docs/SKILL.md

@@ -32,6 +32,261 @@ Generate or update project documentation by analyzing the actual codebase.
 
 ---
 
-Load skill `docs` — subcommand에 따라 해당 섹션 실행
+Execute the bundled implementation below — subcommand에 따라 해당 섹션 실행
 
 ARGUMENTS: $ARGUMENTS
+
+## Bundled implementation
+
+
+# vibe.docs — Project Documentation Generator
+
+Generate or update project documentation by analyzing the actual codebase.
+
+## Subcommands
+
+### `/vibe.docs readme` — README Generation
+
+Analyze the codebase and generate a complete README.md:
+
+1. **Detect project nature**: Read package.json, CLAUDE.md, existing README
+2. **Extract key info**: Tech stack, installation, usage, API surface
+3. **Generate sections**:
+
+```markdown
+# Project Name
+> One-line description from package.json
+
+## What is this?
+[2-3 sentences explaining the problem and solution]
+
+## Quick Start
+[Installation + minimal usage example]
+
+## Features
+[Auto-detected from codebase — exported functions, CLI commands, API endpoints]
+
+## Architecture
+[High-level module diagram if 5+ source directories]
+
+## Configuration
+[Detected config files and their purposes]
+
+## Development
+[Build, test, lint commands from package.json scripts]
+
+## License
+```
+
+**Analysis approach:**
+```
+Read: package.json → name, description, scripts, dependencies
+Glob: src/**/*.ts → module structure
+Grep: pattern="export (function|class|const)" → public API surface
+Grep: pattern="(app|router)\.(get|post|put|delete)" → API endpoints
+Read: CLAUDE.md → project conventions
+```
+
+### `/vibe.docs guide` — User Guide
+
+Generate a step-by-step user guide:
+
+1. **Installation**: Detect package manager, prerequisites
+2. **Configuration**: Find all config files, document each option
+3. **Usage**: Extract CLI commands or API usage patterns
+4. **FAQ**: Common issues from error handling patterns
+5. **Troubleshooting**: Known edge cases from test files
+
+Output: `docs/GUIDE.md`
+
+**Analysis approach:**
+```
+Read: package.json → bin, scripts, peerDependencies
+Glob: src/cli/commands/*.ts → CLI command list
+Grep: pattern="throw new|Error\(" → common error scenarios
+Grep: pattern="(process\.env|config)\.\w+" → configuration options
+```
+
+### `/vibe.docs arch` — Architecture Documentation
+
+Generate architecture overview with diagrams:
+
+1. **Module map**: Directory structure → responsibility mapping
+2. **Dependency graph**: Import analysis → Mermaid diagram
+3. **Data flow**: Entry points → processing → output
+4. **Key decisions**: Extract from CLAUDE.md and code comments
+
+Output: `docs/ARCHITECTURE.md`
+
+**Mermaid diagram generation:**
+```
+Glob: src/**/ → module list
+Grep: pattern="^import .+ from" → dependency edges
+Read: CLAUDE.md → architecture notes
+
+Generate:
+graph TD
+    CLI[CLI Commands] --> Core[Core Logic]
+    Core --> Infra[Infrastructure]
+    Infra --> DB[(Database)]
+    Infra --> API[External APIs]
+```
+
+### `/vibe.docs agent` — Agent Instruction Files (CLAUDE.md / AGENTS.md)
+
+**CLI ↔ file mapping:**
+
+| CLI | File | Support |
+|---|---|---|
+| Claude Code | `CLAUDE.md` | 100% (Primary) |
+| Codex | `AGENTS.md` | 100% (Primary) |
+| Antigravity CLI | `GEMINI.md` | 100% |
+
+Cursor is not supported — do not generate or check Cursor-specific context files.
+
+**Source of truth:**
+- **`CLAUDE.md` is the content SSOT.** Always edit it first; `AGENTS.md` is a regenerated derivative.
+- Behavioral block: `skills/vibe.docs/templates/behavioral-principles.md` (4 Karpathy principles, wrapped in `<!-- VIBE-BEHAVIORAL:START/END -->` markers).
+
+**Procedure (applies to both creation and modification):**
+
+1. **Detect state** — check which of `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` exist in project root. **`CLAUDE.md` is always the SSOT**; if missing, create it first (never derive from AGENTS.md).
+2. **For `AGENTS.md`**:
+   - **If missing** → create by cloning `CLAUDE.md` + applying CLI substitution (below).
+   - **If exists** → regenerate from current `CLAUDE.md` + substitution, preserving user-specific additions outside the VIBE block.
+3. **For `GEMINI.md`**:
+   - **If missing** → create by cloning `CLAUDE.md` + applying Antigravity substitution.
+   - **If exists** → regenerate from current `CLAUDE.md` + substitution, preserving user-specific additions outside the VIBE block.
+4. **CLI substitution for `AGENTS.md`** (Codex): `Claude Code` → `Codex` · `~/.claude/` → `~/.codex/` · `.claude/` → `.codex/` · `CLAUDE.md` → `AGENTS.md`. `CLAUDE.md` itself gets no substitution.
+5. **CLI substitution for `GEMINI.md`** (Antigravity): `Claude Code` → `Antigravity CLI` · `~/.claude/` → `~/.gemini/` · `.claude/` → `.gemini/` · `CLAUDE.md` → `GEMINI.md`.
+6. **Validate every touched file (whether newly created or modified)** via the `agents-md` skill — see validation block below. **Never write or save without running this step.**
+7. Report per file: created / updated / skipped / validation warnings.
+
+**Idempotent:** Re-running re-syncs the behavioral block and re-applies substitutions without duplication.
+
+**Mandatory validation (every create & every update) — Load skill `vibe.agents-md`:**
+
+- Size target 60–150 lines (Optimal). Warn at 200+, force split/trim at 300+.
+- 4-question check per line (outside `VIBE-BEHAVIORAL` block):
+  - Would the agent make a mistake without this? (No → delete)
+  - Needed every session? (No → move to SPEC/plan)
+  - Can a linter/hook replace it? (Yes → move)
+  - Discoverable from code? (Yes → delete)
+- Lost-in-the-Middle: critical rules at top, frequently-violated rules at bottom.
+- Addy Osmani test: "Can the agent discover this by reading the code?" → Yes = delete.
+- Strip tech-stack name-drops already stated in `package.json`.
+
+Report line ranges to trim per file. Do not auto-delete; surface findings for user approval before finalizing.
+
+**When to run:**
+- After `vibe init` / `vibe update` if `CLAUDE.md` or `AGENTS.md` is missing or out of sync.
+- After upgrading `@su-record/vibe` when the behavioral template changes.
+- Whenever the SSOT file is edited — re-sync `AGENTS.md`.
+- User explicitly asks to refresh agent instructions.
+
+### `/vibe.docs release` — Release Notes
+
+Generate release notes from git history:
+
+1. **Collect**: `git log` since last tag
+2. **Classify**: feat/fix/refactor/docs/chore from commit messages
+3. **Group**: By category with breaking changes highlighted
+4. **Format**: Semantic versioning suggestion
+
+Output: `RELEASE_NOTES.md` or append to `CHANGELOG.md`
+
+**Output format:**
+```markdown
+## [x.y.z] - YYYY-MM-DD
+
+### Breaking Changes
+- ...
+
+### Features
+- feat: description (#PR)
+
+### Bug Fixes
+- fix: description (#PR)
+
+### Other
+- refactor/docs/chore items
+```
+
+### `/vibe.docs diagram` — Diagram Generation
+
+Generate Mermaid diagrams for architecture, ERD, flowchart, or sequence
+visualization directly (native capability — no dedicated agent). Ground the
+diagram in sources first: folder structure and imports for architecture;
+`models/`, `migrations/`, `schema.*`, ORM definitions for ERDs; the real
+branch/return structure of the code for flowcharts.
+
+**Options:**
+- `/vibe.docs diagram` (default): Architecture overview
+- `/vibe.docs diagram --er`: Entity-Relationship Diagram
+- `/vibe.docs diagram --flow`: Flowchart
+- `/vibe.docs diagram --seq`: Sequence Diagram
+
+> Read `references/diagram-spec.md` for the full output conventions (Mermaid syntax per diagram type, save location, accuracy constraints).
+
+**Example:**
+```
+/vibe.docs diagram --er
+```
+
+### `/vibe.docs codemaps` — Codemaps Generation
+
+Generate auto-documentation from codebase structure directly (native
+capability — no dedicated agent).
+
+**Output Location:** `docs/CODEMAPS/`
+
+> Read `references/codemaps-output.md` for the full generated-files tree, per-file contents, and tools used.
+
+**Example:**
+```
+/vibe.docs codemaps
+```
+
+## Pipeline Integration
+
+`/vibe.docs` completes the development pipeline:
+
+```
+/vibe.spec    → Design (what to build)
+/vibe.run     → Implement (build it)
+/vibe.trace   → Verify (prove it works)
+/vibe.docs    → Document (explain it)
+```
+
+### Auto-trigger after `/vibe.trace`
+
+When `/vibe.trace` completes with all scenarios passing, suggest:
+> "All scenarios verified. Run `/vibe.docs readme` to update documentation?"
+
+## Guidelines
+
+### DO
+- Read the actual codebase before generating — never guess
+- Preserve existing documentation that's still accurate
+- Include concrete code examples from the actual project
+- Keep language consistent with project (Korean/English based on CLAUDE.md)
+- For `/vibe.docs release` (changelog mode), follow `references/api-docs-changelog.md` natively — no dedicated agent
+- For API-heavy projects (api-docs mode), follow `references/api-docs-changelog.md` natively
+- For `/vibe.docs arch` and `/vibe.docs diagram` Mermaid generation, follow `references/diagram-spec.md` natively
+- Use the `agents-md` skill for `/vibe.docs agent` — applies equally to CLAUDE.md and AGENTS.md
+
+### DON'T
+- Don't generate placeholder text ("Lorem ipsum", "TODO: fill in")
+- Don't document internal implementation details in user-facing docs
+- Don't create files without reading existing ones first
+- Don't assume features — verify by reading code
+
+## Quality Checklist
+
+Before finalizing any document:
+
+- [ ] All code examples are runnable (copy-paste ready)
+- [ ] Installation steps tested against package.json
+- [ ] Links and paths are valid
+- [ ] No placeholder text remaining
+- [ ] Consistent with project language (Korean/English)

package/skills/{e2e-commerce → vibe.e2e-commerce}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: e2e-commerce
+name: vibe.e2e-commerce
 invocation: [auto]
 tier: core
 description: "E2E test scenarios for commerce checkout and payment flows. Provides ready-made Playwright test templates for cart→checkout→payment→confirmation flows, including PG sandbox testing (Toss/Stripe), error scenarios (payment failure, timeout, stock exhaustion), and idempotency verification. Use when writing E2E tests for any e-commerce feature — checkout, payment, order status, or refund flows."

package/skills/vibe.educational-content/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: vibe.educational-content
+description: Create evidence-backed educational content from a subject, curriculum, source document, repository, product, expert interview, or demonstration. Use when Codex needs to research, design, script, verify, assess, or repurpose a lesson, course, tutorial, workshop, explainer, screencast, teaching article, presentation, worksheet, microlearning unit, or educational social content for any domain, including development and technical education. Especially useful when content needs observable learning outcomes, audience-appropriate scaffolding, practice and feedback, valid assessment, source traceability, or clear separation between verified facts and inference.
+user-invocable: false
+---
+
+# Create Educational Content
+
+Turn a subject into a publishable learning experience whose outcome can be observed. Design the learning before polishing the presentation.
+
+## Set the contract
+
+Infer missing low-risk details and state the assumptions. Ask only when audience, format, or publication constraints would materially change the result.
+
+Capture:
+
+- outcome: what the learner can do afterward
+- audience: age or role, prior knowledge, motivation, language, accessibility needs
+- context: self-study, classroom, onboarding, reference, campaign, or performance support
+- format: lesson, article, workshop, video, course, worksheet, assessment, or short-form
+- source: curriculum, document, URL, repository, expert input, dataset, or user notes
+- constraints: duration, length, standards, platform, brand, deadline
+- proof bar: demonstration, explanation, performance, artifact, quiz, rubric, or observation
+
+Do not begin with a broad topic such as “teach climate change” or “teach Docker.” Rewrite it as an observable outcome such as “a learner distinguishes weather from climate using three examples” or “a frontend developer deploys a two-service Compose app and verifies health checks.”
+
+Read [references/learning-design.md](references/learning-design.md) when selecting objectives, activities, scaffolding, or assessments.
+
+## Choose a teaching path
+
+Prefer a progression from concrete experience to independent performance:
+
+1. Activate relevant prior knowledge or expose a meaningful problem.
+2. Model the target performance with a concrete example.
+3. Guide practice with prompts, hints, or worked steps.
+4. Give feedback against explicit criteria.
+5. Remove support and require independent application or transfer.
+
+For technical tool education, the progression may be easy surface → inspectable implementation → power-user surface → automation. Use a different order when prerequisites, domain practice, or safety require it. Avoid fact or feature tours; organize around learner performance.
+
+## Research the claim surface
+
+Build a claim ledger before drafting. For each consequential claim record:
+
+| Claim | Evidence | Status | Content use |
+|---|---|---|---|
+| What the tool does | primary docs or observed run | verified | state directly |
+| Why it behaved that way | code, docs, or controlled test | verified/inferred | label inference |
+| What may vary | version, OS, account, UI, network | uncertain | add caveat |
+
+Prefer primary, authoritative, and current sources. Use multiple credible perspectives for contested subjects. Inspect target materials in full before explaining them. Never invent quotations, citations, commands, settings, UI labels, research findings, statistics, benchmark numbers, or results.
+
+For source-video-derived work, read [references/source-method.md](references/source-method.md) to preserve the method without copying the source presentation.
+
+## Build the learning evidence
+
+Create the smallest realistic activity that elicits the promised outcome.
+
+1. Record environment and prerequisites.
+2. Establish the initial state.
+3. Model one successful performance or worked example.
+4. Give the learner a meaningful action, decision, explanation, or creation task.
+5. Capture evidence with a criterion-aligned check.
+6. Record one likely misconception and corrective feedback path.
+
+For code, tools, experiments, or procedures, keep demonstrations reproducible where possible and verify actual results. For conceptual subjects, require explanation, classification, comparison, prediction, or application instead of relying only on recall. Separate paid, destructive, medical, legal, physical, or external actions from harmless learning checks and require appropriate authorization or supervision.
+
+## Design the narrative
+
+Use this spine:
+
+1. **Promise** — show the concrete end state.
+2. **Mental model** — explain only the concepts needed for the next action.
+3. **Setup** — connect prior knowledge and define prerequisites.
+4. **Model** — demonstrate the target thinking or performance.
+5. **Practice** — progress through small, observable attempts.
+6. **Feedback** — address a realistic misconception or failure.
+7. **Assess** — elicit independent evidence of learning.
+8. **Extend** — transfer the idea to a new context.
+9. **Recap** — map the evidence back to the learning outcome.
+
+Pair every explanation with evidence:
+
+- explanation establishes what and why
+- example or demonstration shows how
+- learner activity elicits performance
+- assessment shows whether the outcome was reached
+
+Do not confuse exposure with learning. Watching, reading, or clicking is not sufficient evidence unless the stated objective only requires recognition. Explain decisions, relationships, constraints, and changes in understanding.
+
+## Draft the production package
+
+Produce only artifacts the requested format needs. Use the schemas in [references/output-patterns.md](references/output-patterns.md).
+
+At minimum include:
+
+- title and one-sentence learner promise
+- audience and prerequisites
+- outline with estimated pacing
+- model, guided practice, and independent practice
+- assessment, answer guidance, or scoring rubric
+- evidence or capture plan
+- safety and uncertainty notes
+- final quality checklist
+
+For video, add scene intent, narration, visual action, learner prompt, and evidence shot. For articles, add reflection or practice prompts and expected reasoning; add runnable code and expected output when technical. For workshops, add checkpoints, facilitator moves, and misconception recovery.
+
+## Apply gates
+
+Stop and repair the artifact when a gate fails.
+
+### Accuracy gate
+
+- Every consequential claim is verified or explicitly labeled as inference.
+- Version-sensitive facts are current and sourced.
+- Commands and code match the stated environment.
+
+### Learning-evidence gate
+
+- The activity elicits the behavior named in the objective.
+- Practice includes timely, actionable feedback.
+- Independent assessment does not give away the answer.
+- Expected evidence and evaluation criteria are explicit.
+
+### Teaching gate
+
+- Each section advances the learner toward the promise.
+- New concepts appear immediately before use.
+- Jargon is defined once and then used consistently.
+- Cognitive load fits the audience and format.
+- Examples are inclusive, relevant, and free of avoidable stereotypes.
+
+### Safety gate
+
+- External writes, destructive actions, and high-stakes activities have an approval or supervision boundary.
+- Secrets, personal data, and account details are absent from captures.
+- Minor learners and sensitive subjects receive appropriate privacy and safeguarding treatment.
+
+### Production gate
+
+- Claims, narration, captions, visuals, activities, and assessments agree.
+- No placeholder, fabricated output, or unsupported superlative remains.
+- The final artifact names limitations and the next useful action.
+
+## Handle failure
+
+- If the source cannot be accessed, report the missing evidence and request an artifact or alternate source; do not fabricate an analysis.
+- If a live tool is unavailable, use a recorded fixture and label it as simulated.
+- If a technical demonstration fails, reproduce once, state one root-cause hypothesis, add a failing check, then fix.
+- If learners cannot complete an activity, distinguish missing prerequisite knowledge, unclear instruction, excessive load, and a flawed assessment before adding more explanation.
+- If behavior is nondeterministic, show the invariant acceptance criteria instead of promising identical output.
+- If evidence is contested or culturally situated, present the source context and credible disagreement rather than manufacturing certainty.
+- If the requested scope exceeds the format, preserve the core learning outcome and move depth into a follow-up resource.
+
+## Finish
+
+Return the production-ready artifact, the verification evidence, and a short list of assumptions or unresolved uncertainties. Keep research notes out of the final content unless they help the learner judge a claim.