@kunolu/dsh-sbtd 0.1.0-rc.1

package/dist/tools/review.js

@@ -0,0 +1,161 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getSession } from "../state.js";
+import { sessionIdFromExec, } from "./plan.js";
+export const SBTD_REVIEW_TOOL_NAME = "sbtd_review";
+export const REVIEW_KINDS = [
+    "legacy",
+    "refactor",
+    "ddd",
+    "ddia",
+    "release",
+];
+export const REVIEW_TITLES = {
+    legacy: "Legacy Change Safety Review",
+    refactor: "Refactoring Review",
+    ddd: "DDD Boundary Review",
+    ddia: "DDIA Data Design Review",
+    release: "Release Readiness Review",
+};
+const MANUAL_ID = {
+    legacy: "book-legacy-change-safety",
+    refactor: "book-refactoring-pass",
+    ddd: "book-ddd-distilled-modeling",
+    ddia: "book-ddia-data-design",
+    release: "book-release-readiness",
+};
+const REVIEW_STATUSES = {
+    legacy: ["characterized", "needs-safety-net", "seam-required", "blocked"],
+    refactor: ["proceed", "refactor-first", "blocked"],
+    ddd: ["confirmed", "needs-clarification", "blocked"],
+    ddia: ["confirmed", "needs-design-change", "blocked"],
+    release: ["ready", "needs-mitigation", "blocked"],
+};
+const PASS_STATUS = {
+    characterized: true,
+    proceed: true,
+    confirmed: true,
+    ready: true,
+};
+const RUNNING_STATUS = {
+    "needs-safety-net": true,
+    "needs-clarification": true,
+    "needs-design-change": true,
+    "needs-mitigation": true,
+    "seam-required": true,
+    "refactor-first": true,
+};
+function isReviewKind(value) {
+    return REVIEW_KINDS.includes(value);
+}
+function mapGateState(status) {
+    if (PASS_STATUS[status] === true) {
+        return "passed";
+    }
+    if (status === "blocked") {
+        return "blocked";
+    }
+    if (RUNNING_STATUS[status] === true) {
+        return "running";
+    }
+    throw new Error(`sbtd_review: unmapped status ${status}`);
+}
+export function loadReviewManual(kind) {
+    const manualsRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "manuals");
+    return readFileSync(join(manualsRoot, MANUAL_ID[kind], "SKILL.md"), "utf8");
+}
+export function sbtdReview(sessionId, input) {
+    if (!isReviewKind(input.kind)) {
+        throw new Error(`sbtd_review: kind must be one of ${REVIEW_KINDS.join(", ")}`);
+    }
+    const kind = input.kind;
+    const allowed = REVIEW_STATUSES[kind];
+    if (!allowed.includes(input.status)) {
+        throw new Error(`sbtd_review: status for ${kind} must be one of ${allowed.join(", ")}`);
+    }
+    const status = input.status;
+    const manual = loadReviewManual(kind);
+    const session = getSession(sessionId);
+    if (session.plan === undefined) {
+        throw new Error("尚未 sbtd_plan，请先调用 sbtd_plan。");
+    }
+    const gate = session.plan.gates[kind];
+    gate.state = mapGateState(status);
+    gate.reviewStatus = status;
+    const conclusions = input.conclusions ?? "";
+    const title = REVIEW_TITLES[kind];
+    const markdown = [
+        `# ${title}`,
+        `Status: ${status}`,
+        `requirement: ${gate.requirement}`,
+        `state: ${gate.state}`,
+        "",
+        conclusions,
+    ].join("\n");
+    return {
+        title,
+        kind,
+        reviewStatus: status,
+        requirement: gate.requirement,
+        state: gate.state,
+        conclusions,
+        markdown,
+        manual,
+    };
+}
+export const SBTD_REVIEW_DESCRIPTION = "Record a book-gate review. kind is legacy|refactor|ddd|ddia|release only (no skill ids or aliases). status is the source-skill reviewer enum. Without a plan, call sbtd_plan first. Does not change requirement.";
+export function createReviewTool() {
+    return {
+        name: SBTD_REVIEW_TOOL_NAME,
+        description: SBTD_REVIEW_DESCRIPTION,
+        parameters: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    enum: [...REVIEW_KINDS],
+                    description: "Book gate kind. Exactly legacy, refactor, ddd, ddia, or release.",
+                },
+                status: {
+                    type: "string",
+                    description: "Reviewer status from the loaded SKILL.md enum for that kind.",
+                },
+                conclusions: {
+                    type: "string",
+                    description: "Review conclusions. Returned only; not written to disk.",
+                },
+            },
+            required: ["kind", "status"],
+        },
+        output: {
+            schema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    title: { type: "string" },
+                    kind: { type: "string" },
+                    reviewStatus: { type: "string" },
+                    requirement: { type: "string" },
+                    state: { type: "string" },
+                    conclusions: { type: "string" },
+                    markdown: { type: "string" },
+                    manual: { type: "string" },
+                },
+            },
+            render(_args, value) {
+                return [{ type: "text", text: `${value.markdown}\n\n${value.manual}` }];
+            },
+        },
+        isConcurrencySafe() {
+            return false;
+        },
+        async execute(args, exec) {
+            return sbtdReview(sessionIdFromExec(exec), args);
+        },
+    };
+}
+export function registerReviewTool(ctx) {
+    ctx.tools.register(createReviewTool());
+}
+//# sourceMappingURL=review.js.map

package/dist/tools/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../../src/tools/review.ts"],"names":[],"mappings":"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"}

package/manuals/MANIFEST.json

@@ -0,0 +1,67 @@
+{
+  "source": "KunoLu/640-skills",
+  "version": "1.0.13",
+  "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630",
+  "files": [
+    {
+      "sourcePath": "sbtd-workflow-onboard/assets/external-skills/stable/skills/domain-modeling/SKILL.md",
+      "sha256": "327a2b50620e2fd70abc6893cd6965e76b20f8d0adb0dc2c8d5eb3845efb643e",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/assets/external-skills/stable/skills/grill-me/SKILL.md",
+      "sha256": "caaf8b8de1684f96e26b28f3c29189db5c89cce4b73e1c93d86164f66ef88637",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/assets/external-skills/stable/skills/grill-with-docs/SKILL.md",
+      "sha256": "7de372c13488f1ee96cc11cd8907b56b6809cc93eef776eeddd37de6b6cbe3fe",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/assets/external-skills/stable/skills/grilling/SKILL.md",
+      "sha256": "10ff989e7498b23b5acb49d5048f11dcd906757d2f79c5cdf8a00001381296f2",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/assets/external-skills/stable/skills/to-spec/SKILL.md",
+      "sha256": "43ad9cf318e5e7d3d1fa360253a37021796dc87a0c2e595ad262661a10f85088",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/assets/external-skills/stable/skills/to-tickets/SKILL.md",
+      "sha256": "5c9fba69845c2519b9b35b9af42ae5142c21f8ca15ac2123dc2722002c8058ae",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/templates/skills/book-ddd-distilled-modeling/SKILL.md",
+      "sha256": "b8006abc3f2e61c5b62ed7a1a79fad517bbcc614da8156e7157092ebdc20f62a",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/templates/skills/book-ddia-data-design/SKILL.md",
+      "sha256": "87e63a9595d66343ad6e64813b701fbfea74479a7ee986230592664f289a3d2b",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/templates/skills/book-legacy-change-safety/SKILL.md",
+      "sha256": "f3ade56807980d58874bd92694ebd5f26df7e836ace609c65e0aaf355d08fcea",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/templates/skills/book-refactoring-pass/SKILL.md",
+      "sha256": "36a255121e040b962d7019c642fdd9962979a1dd3fc600e5ce0d6cd897faad7f",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/templates/skills/book-release-readiness/SKILL.md",
+      "sha256": "1c572b8c31a0411d4be956ea17fb3a8b709b2d84c66385502092a61399e58fa5",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    },
+    {
+      "sourcePath": "sbtd-workflow-onboard/templates/skills/trellis-workflow/SKILL.md",
+      "sha256": "3d6589cb346649886eed7d2e86be7e2650f2f0dda909d76704284e17f765f77e",
+      "sourceRevision": "f8aa0d7225a26c5e00b81d2f1b05121108e63630"
+    }
+  ]
+}

package/manuals/book-ddd-distilled-modeling/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: book-ddd-distilled-modeling
+description: Guides lightweight domain modeling with ubiquitous language, bounded contexts, and subdomain focus. Always run after every completed grill-with-docs session as an independent second-pass boundary review; also use before PRD, design, or implementation when domain ambiguity exists.
+---
+
+# Book DDD Distilled Modeling
+
+Use this Skill to sharpen domain language before turning a business request into PRD, issues, design, or code.
+
+It is derived from the `mini` rule style of `agent-rules-books` and should run after project evidence is read. It complements `grill-with-docs`, `to-spec`, and Trellis planning.
+
+## Mandatory Post-grill Review
+
+Every fully completed `grill-with-docs` session MUST be followed immediately by this Skill, whether the Agent initiated that session or the user invoked it explicitly. The `domain-modeling` activity embedded in `grill-with-docs` is the active interview-time modeling pass; it does not satisfy or replace this independent second-pass review.
+
+Re-read the completed clarification result and the supporting project facts. Look for boundary errors, hidden term collisions, unsupported invariants, misplaced responsibilities, and unresolved context ownership rather than merely restating the interview.
+
+The review is a gate before requirement confirmation, PRD, design, Trellis task creation, or implementation:
+
+- `confirmed`: no unresolved boundary issue prevents the workflow from advancing.
+- `needs-clarification`: output the findings, return to one-question-at-a-time clarification, and rerun this Skill after resolution.
+- `blocked`: the Skill, required evidence, or relevant context is unavailable; output the exact blocker and do not advance.
+
+Invocation origin, a prior `domain-modeling` pass, or an Agent judgment that the requirement is already clear MUST NOT skip this gate.
+
+## When To Use
+
+- Every completed `grill-with-docs` session, without exception.
+- A requirement uses business terms that may mean different things in different parts of the system.
+- A change touches domain rules, permissions, lifecycle, workflow state, billing, identity, tenancy, inventory, orders, subscriptions, or similar concepts.
+- It is unclear whether two concepts belong in the same model or bounded context.
+- A PRD or design needs stable terminology before implementation.
+
+When `grill-with-docs` was not used, do not use this Skill for purely technical refactors, simple UI copy, mechanical dependency updates, or features with no domain ambiguity.
+
+## Workflow
+
+1. Read existing project facts first: README, domain docs, `.trellis/spec`, ADRs, task artifacts, and relevant code.
+2. List the key terms and their current meanings in the project.
+3. Identify bounded contexts where the same word may have different meanings.
+4. Distinguish core, supporting, and generic subdomains when that affects priority or design.
+5. State invariants and business rules in the language used by the project.
+6. Feed the agreed language into `prd.md`, `design.md`, or `implement.md`.
+
+## Output
+
+Always output the review visibly and separately from the requirement confirmation summary:
+
+```text
+DDD Boundary Review
+Status: confirmed | needs-clarification | blocked
+Ubiquitous language: ...
+Bounded contexts: ...
+Invariants and business rules: ...
+Core / supporting / generic subdomains: ...
+Corrections to the grill-with-docs result: ...
+Open conflicts and questions: ...
+```
+
+Use `not-applicable` for a subdomain classification only when it has no bearing on the current decision; do not omit the field. A post-grill review must explicitly state whether it corrected the earlier result, even when the answer is `none`.
+
+Only stable, cross-task domain decisions should be promoted to `docs/CONTEXT.md`, ADRs, or `.trellis/spec`. Keep the complete review in task-level output or the current `prd.md`, `design.md`, or `implement.md`.
+
+## Guardrails
+
+Outside the mandatory post-grill gate, do not force DDD ceremony into small tasks. During the mandatory gate, keep the second pass concise but complete enough to prove the boundaries were independently checked.

package/manuals/book-ddia-data-design/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: book-ddia-data-design
+description: Guides data-intensive design checks for consistency, reliability, schema evolution, and data flow risks. Mandatory before design stabilizes or implementation begins when changing persisted/shared data, schemas, migrations, shared/persistent/cross-request/cross-process caches, async or cross-service flows, data ownership, or recovery; otherwise use on demand.
+---
+
+# Book DDIA Data Design
+
+Use this Skill when a change can fail because of data semantics, distributed behavior, or operational reality rather than ordinary code structure.
+
+It is derived from the `mini` rule style of `agent-rules-books` and should complement project architecture, Trellis design, GitNexus impact analysis, tests, and production validation.
+
+## Mandatory Development Gate
+
+Run this Skill before design artifacts become stable or implementation begins when a development task changes any of the following:
+
+- Persisted or shared data, databases, schemas, or migrations.
+- shared, persistent, cross-request, or cross-process caches; queues, events, streams, jobs, ETL, or analytics pipelines.
+- Cross-service data flow or API ownership.
+- Data ownership, source of truth, transaction boundaries, or read / write paths.
+- Backfill, replay, rollback, or recovery behavior.
+
+Emit a separate visible review:
+
+```text
+DDIA Data Design Review
+Status: confirmed | needs-design-change | blocked
+Data owner and source of truth: ...
+Write / read / async / failure paths: ...
+Consistency model: ...
+Idempotency / ordering / retry / deduplication: ...
+Schema / migration / backfill / rollback / replay: ...
+Observability and repair: ...
+Required tests: ...
+```
+
+- `confirmed`: the data design and failure / recovery behavior are explicit enough to implement safely.
+- `needs-design-change`: update the design or task artifacts, then rerun this Skill before implementation.
+- `blocked`: required ownership, contract, environment, migration, or Skill evidence is missing; state the blocker and do not stabilize design or implement the data change.
+
+## When To Use
+
+- Mandatory: every development task matching a persisted/shared-data, shared-cache, async-flow, cross-service-flow, ownership, migration, or recovery trigger above.
+- A change affects databases, schemas, migrations, shared / persistent / cross-request / cross-process caches, queues, streams, jobs, ETL, analytics, or cross-service APIs.
+- The system must handle duplicate messages, retries, partial failure, reordering, eventual consistency, or replay.
+- A feature changes data ownership, source of truth, transactional boundaries, or read/write paths.
+- Backfill, migration, rollback, or recovery behavior matters.
+
+When no mandatory trigger matches, do not use this Skill for purely local UI work, simple in-memory code, or data changes already covered by clear project conventions unless the user requests it or another concrete data-semantics risk warrants it.
+
+## Workflow
+
+1. Identify the source of truth and data owner.
+2. Map the write path, read path, async path, and failure path.
+3. State consistency expectations: strong, eventual, read-your-writes, monotonic reads, or best effort.
+4. Check idempotency, ordering, retry, deduplication, and poison-message handling.
+5. Check schema compatibility, migrations, backfills, rollback, and replay.
+6. Define observability and repair signals for data drift or stuck processing.
+7. Validate with focused tests and project validation commands.
+
+## Output
+
+Always emit the visible `DDIA Data Design Review` for a mandatory gate. For Trellis tasks, also write concise design/check notes:
+
+- Data owner and source of truth.
+- Consistency model.
+- Failure and recovery behavior.
+- Migration/backfill/rollback plan.
+- Required tests and validation.
+
+Promote only long-lived data architecture rules to `.trellis/spec`.
+
+## Guardrails
+
+Do not design a distributed system when a local transaction is enough. A mandatory review may confirm that the existing simple model is sufficient; keep the design as simple as project constraints allow.

package/manuals/book-legacy-change-safety/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: book-legacy-change-safety
+description: Guides safe changes to legacy or weakly tested code by characterizing behavior before editing. Mandatory before the first behavior-changing edit for existing-behavior bug fixes or existing code with unclear behavior, low coverage, hidden dependencies, or high regression risk; otherwise use on demand.
+---
+
+# Book Legacy Change Safety
+
+Use this Skill when the main risk is not the requested change itself, but the uncertainty around existing behavior.
+
+It is derived from the `mini` rule style of `agent-rules-books` and is intended to complement `diagnosing-bugs`, `tdd`, GitNexus impact analysis, and project validation.
+
+## Mandatory Development Gate
+
+Run this Skill before the first behavior-changing edit when either condition is true:
+
+- The task fixes a bug in existing observable behavior.
+- Existing target code has weak / missing tests, unclear or undocumented behavior, hidden dependencies, or high regression risk.
+
+Emit a separate visible review:
+
+```text
+Legacy Change Safety Review
+Status: characterized | needs-safety-net | seam-required | blocked
+Behavior to change: ...
+Behavior to preserve: ...
+Current reproduction evidence: ...
+Safety net: ...
+Hidden dependencies / seam: ...
+Validation plan: ...
+Review mode: normal | safety-seam-only
+```
+
+- `characterized`: current behavior was reproduced or otherwise established, preserved behavior is explicit, and an adequate safety net exists.
+- `needs-safety-net`: the safety net can be added without production-code edits; add or select the smallest characterization / regression check, then rerun this Skill.
+- `seam-required`: current and preserved behavior are established, but the safety net cannot be installed without a production seam. Record the exact seam scope, invoke `book-refactoring-pass` in `safety-seam-only` mode, implement and validate only that behavior-preserving seam, then return here to establish the safety net and reach `characterized`.
+- `blocked`: current behavior, required dependencies, the Skill, or a safe reproduction path is unavailable; state the blocker and do not change behavior.
+
+When `book-refactoring-pass` is also mandatory, this gate normally reaches `characterized` first. `seam-required` is the only exception and authorizes no feature / fix behavior or unrelated cleanup.
+
+## When To Use
+
+- Mandatory: every existing-behavior bug fix and every existing-code change matching a listed uncertainty or regression-risk signal.
+- The target code has weak or missing tests.
+- The current behavior is unclear, accidental, or undocumented.
+- Dependencies are hidden behind globals, singletons, network calls, files, time, randomness, or external services.
+- A bug fix could change behavior that other callers rely on.
+
+When neither mandatory condition matches, do not use this Skill for cleanly tested new code, docs-only work, or simple isolated edits with obvious behavior and low blast radius unless the user requests it or another concrete legacy risk warrants it.
+
+## Workflow
+
+1. State the exact behavior to change.
+2. State the behavior that must be preserved.
+3. Reproduce the current behavior before editing.
+4. Add the smallest useful safety net, such as a characterization test, focused unit test, integration check, or manual script. If this requires a production seam, emit `seam-required` before editing.
+5. Introduce a seam only through the `safety-seam-only` loop above, then rerun this Skill and complete the safety net.
+6. Make the smallest behavior change that satisfies the task only after `characterized`.
+7. Run focused tests first, then the project validation required by the changed area.
+
+## Output
+
+Always emit the visible `Legacy Change Safety Review` for a mandatory gate. When used inside a Trellis task, also record:
+
+- Current observed behavior.
+- Preserved behavior.
+- Added or chosen safety net.
+- Dependency seam, if introduced.
+- Validation command and result.
+
+If a lesson is learned because a regression, tool mistake, or workflow error occurred, use `lessons-record`; otherwise do not create a lesson.
+
+## Guardrails
+
+Do not rewrite legacy code just to make it nicer. Stabilize first, change second, improve only where the current task needs it; a mandatory review may conclude `characterized` without introducing a new seam when the existing safety net is sufficient.

package/manuals/book-refactoring-pass/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: book-refactoring-pass
+description: Guides behavior-preserving refactoring with small, reversible steps. Mandatory before the first implementation edit to existing production code; otherwise use on demand when structural friction, duplication, long functions, tangled responsibilities, or unsafe cleanup could affect the change.
+---
+
+# Book Refactoring Pass
+
+Use this Skill as a focused refactoring check before or during implementation.
+
+It is derived from the `mini` rule style of `agent-rules-books`. It is a mandatory development gate for existing-production-code edits and an on-demand engineering lens in other structural-risk scenarios; it does not replace project rules, tests, Trellis artifacts, GitNexus, or code review.
+
+## Mandatory Development Gate
+
+Whenever a development task will modify existing production code, run this Skill before the first implementation edit to existing production code, even when the expected result is that no refactoring is needed.
+
+Emit a separate visible review:
+
+```text
+Refactoring Review
+Status: proceed | refactor-first | blocked
+Review mode: normal | safety-seam-only
+Existing-code scope: ...
+Behavior that must remain unchanged: ...
+Structural friction: ...
+Decision and smallest safe step: ...
+Safety net and validation: ...
+Deferred refactors: ...
+```
+
+- `proceed`: in normal mode, the existing structure is safe enough for the requested edit; `no refactor needed` is a valid explicit conclusion.
+- `refactor-first`: perform only the smallest behavior-preserving structural change allowed by the current review mode, validate it, and rerun the required gate before feature or fix edits.
+- `blocked`: required behavior evidence, a safety net plan, or the Skill is unavailable; state the blocker and do not edit production behavior.
+
+If `book-legacy-change-safety` is also mandatory, its review normally reaches `characterized` before this gate runs. Controlled exception: a legacy `seam-required` result may invoke this Skill in `safety-seam-only` mode. That mode may design and implement only the recorded behavior-preserving test seam, must validate observational equivalence, and must return to legacy review to establish the safety net. After legacy reaches `characterized`, rerun this Skill in normal mode before feature / fix edits.
+
+## When To Use
+
+- Mandatory: every development task that modifies existing production code.
+- Existing code structure is making a requested change risky or awkward.
+- A change mixes behavior changes with cleanup.
+- Duplication, long functions, feature envy, primitive obsession, or tangled responsibilities are blocking clarity.
+- A review needs to decide whether a refactor should happen now or be deferred.
+
+When existing production code will not be modified, do not use this Skill for simple text, docs, config-only edits, broad rewrites, speculative architecture changes, or code that is already easy to change safely unless the user explicitly requests the review or another concrete structural risk warrants it.
+
+## Workflow
+
+1. Identify the observable behavior that must remain unchanged.
+2. Confirm the available safety net: tests, characterization checks, manual repro, snapshots, or focused inspection.
+3. Separate structural refactoring from behavior changes.
+4. Prefer the smallest reversible move that lowers the current task risk.
+5. Preserve public contracts unless the task explicitly changes them.
+6. In `safety-seam-only` mode, reject feature behavior, bug-fix behavior, broad cleanup, or any structural change not required by the recorded test seam.
+7. Run the project validation appropriate to the touched code.
+
+## Output
+
+Always emit the visible `Refactoring Review` for a mandatory gate. When used inside a Trellis task, also write only task-specific conclusions to `implement.md`, `design.md`, or the check summary:
+
+- Current friction.
+- Behavior that must not change.
+- Proposed refactoring steps or explicit `no refactor needed`.
+- Safety net and validation command.
+- Deferred refactors, if any.
+
+Only long-term conventions belong in `.trellis/spec`.
+
+## Stop Conditions
+
+Stop refactoring when the requested change is safe and clear enough. The mandatory review does not require a refactor; never invent cleanup merely to produce `refactor-first`, and do not keep improving code outside the task boundary.

package/manuals/book-release-readiness/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: book-release-readiness
+description: Reviews production readiness for services, APIs, jobs, queues, integrations, and deployment-sensitive changes. Mandatory after all applicable testing-tool gates and project validation, and before completion or release, when production-path runtime or deployment behavior changes; otherwise use on demand.
+---
+
+# Book Release Readiness
+
+Use this Skill as a production-readiness pass before considering a service or integration change complete.
+
+It is derived from the `mini` rule style of `agent-rules-books` and complements project validation, Playwright, Maestro, Chrome DevTools diagnostics, Trellis check, and human release review.
+
+## Mandatory Development Gate
+
+Run this Skill after all applicable testing-tool gates and project validation, and before the task is declared complete, the final release decision, or Channel preflight when a development task changes any production-path:
+
+- Service, API, auth, billing, or notification behavior.
+- Background job, queue, scheduler, or data pipeline.
+- External integration.
+- Deployment, rollout, migration, or runtime operational behavior.
+
+Emit a separate visible review:
+
+```text
+Release Readiness Review
+Status: ready | needs-mitigation | blocked
+Production path and affected users / systems: ...
+Failure modes and safeguards: ...
+Capacity / backpressure / limits: ...
+Observability / alerts / runbook: ...
+Rollout / migration / rollback / cleanup: ...
+Required validation and result: ...
+Optional checks, accountable owner acceptance, and residual risk: ...
+```
+
+- `ready`: all required validation ran and passed; applicable production risks, rollout, rollback, and observability are addressed. An optional check may remain skipped only when an explicit accountable owner accepts the documented residual risk.
+- `needs-mitigation`: implement the required mitigation or update the release plan, rerun every affected required validation and testing-tool gate, and rerun this Skill.
+- `blocked`: any required validation, environment, operational evidence, or rollback path is missing or failed, or the Skill is unavailable. Required checks cannot be waived or converted to residual risk; state the blocker and do not declare the task complete or release-ready.
+
+## When To Use
+
+- Mandatory: every development task matching a production-path runtime or deployment trigger above.
+- The change affects APIs, background jobs, queues, schedulers, external services, auth, billing, notifications, data pipelines, or deployment behavior.
+- Failure modes include timeouts, retries, overload, partial outage, data corruption, duplicate work, or user-visible degradation.
+- The task is ready for `$trellis-check` or release review.
+
+When no mandatory trigger matches, do not use this Skill for docs-only changes, local-only scripts, simple UI polish, or code paths that are not production-facing unless the user requests it or another concrete release risk warrants it.
+
+## Workflow
+
+1. Identify the production path and the users or systems affected.
+2. Check timeouts, retry limits, backoff, cancellation, and duplicate-work safety.
+3. Check fallback, graceful degradation, circuit breaking, or isolation where relevant.
+4. Check capacity, backpressure, rate limits, and queue growth behavior.
+5. Check logs, metrics, traces, alerts, dashboards, and runbook expectations.
+6. Check rollout, rollback, feature flag, migration, and cleanup paths.
+7. Confirm that all required validation and applicable testing-tool gates ran; separate them from optional checks, and record any optional-check acceptance by an explicit accountable owner.
+
+## Output
+
+Always emit the visible `Release Readiness Review` for a mandatory gate. When used inside a Trellis task, also record:
+
+- Production risk summary.
+- Failure modes covered.
+- Observability and alerting notes.
+- Rollout and rollback path.
+- Validation performed and skipped checks.
+- Residual risk.
+
+Only recurring release standards belong in `.trellis/spec`.
+
+## Guardrails
+
+Do not block completion with theoretical production risks that do not apply to the current project. A mandatory review must still inspect every applicable category and may mark irrelevant checks `not-applicable`; required validation cannot be skipped, while an optional check needs explicit accountable-owner acceptance and a documented residual risk.