@sha3/code 1.0.0

package/resources/ai/rule-catalog.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sha3.dev/code/rule-catalog.schema.json",
+  "title": "AI Rule Catalog",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "rules"],
+  "properties": {
+    "version": { "type": "string", "const": "v2" },
+    "rules": {
+      "type": "array",
+      "minItems": 8,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "title",
+          "summary",
+          "severity",
+          "kind",
+          "appliesTo",
+          "deterministic",
+          "verificationMode",
+          "verificationSource",
+          "implementedBy",
+          "requiresContext",
+          "confidence",
+          "enforcedBy",
+          "examples",
+          "profileOverrides"
+        ],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+          "title": { "type": "string", "minLength": 3 },
+          "summary": { "type": "string", "minLength": 10 },
+          "severity": { "type": "string", "enum": ["error", "warning", "audit"] },
+          "kind": { "type": "string", "enum": ["style", "architecture", "testing", "documentation", "workflow"] },
+          "appliesTo": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "deterministic": { "type": "boolean" },
+          "verificationMode": { "type": "string", "enum": ["deterministic", "heuristic", "audit"] },
+          "verificationSource": { "type": "string", "enum": ["ast", "text", "filesystem", "package-json", "readme", "git-diff", "combined"] },
+          "implementedBy": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+          "requiresContext": { "type": "string", "enum": ["none", "changed-files", "full-project"] },
+          "confidence": { "type": "string", "enum": ["high", "medium"] },
+          "enforcedBy": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "examples": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["good", "bad"],
+            "properties": { "good": { "type": "array", "items": { "type": "string" } }, "bad": { "type": "array", "items": { "type": "string" } } }
+          },
+          "profileOverrides": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["key"],
+              "properties": { "key": { "type": "string" }, "equals": {}, "oneOf": { "type": "array", "items": {} } }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/resources/ai/templates/adapters/codex.template.md

@@ -0,0 +1,7 @@
+# Codex Adapter
+
+- Read `AGENTS.md` and `ai/contract.json` before implementation.
+- Fix `error` rules, review `warning` rules with judgment, and report `audit` items.
+- Keep `@sha3/code` managed files read-only unless the user explicitly requests a standards update.
+- Rewrite `README.md` as real package documentation and document public exports and public methods after implementation.
+- Run `npm run check` before finalizing and fix any failing rule or type error.

package/resources/ai/templates/adapters/copilot.template.md

@@ -0,0 +1,7 @@
+# GitHub Copilot Adapter
+
+- Read `AGENTS.md` and `ai/contract.json` first.
+- Fix `error` rules first and treat `warning` rules as review signals, not blind rewrite orders.
+- Do not modify managed files unless the user explicitly requests a contract/tooling update.
+- Rewrite `README.md` as real package documentation and document public exports and public methods after implementation.
+- Run `npm run check` and resolve all failures before finalizing.

package/resources/ai/templates/adapters/cursor.template.md

@@ -0,0 +1,7 @@
+# Cursor Adapter
+
+- Read `AGENTS.md` and `ai/contract.json` before editing.
+- Apply `error` rules first, then review `warning` rules without overcorrecting them into worse code.
+- Keep managed files read-only unless the user explicitly asks for a standards update.
+- Rewrite `README.md` as real package documentation and document public exports and public methods after implementation.
+- Run `npm run check` and fix all reported issues before finishing.

package/resources/ai/templates/adapters/windsurf.template.md

@@ -0,0 +1,7 @@
+# Windsurf Adapter
+
+- Treat `AGENTS.md` and `ai/contract.json` as the mandatory local contract.
+- Managed files remain read-only unless the user explicitly requests a standards update.
+- Rewrite `README.md` as real package documentation and document public exports and public methods after implementation.
+- Prefer deterministic fixes that satisfy `npm run check` over ad hoc style guesses.
+- Resolve all failing checks before finalizing.

package/resources/ai/templates/agents.project.template.md

@@ -0,0 +1,141 @@
+# AI Coding Contract
+
+Project: {{projectName}}
+Contract format: `{{contractVersion}}`
+Generated by `@sha3/code`: `{{generatedByVersion}}`
+
+`ai/contract.json` is the machine-readable source of truth for active rules. This file is the always-on human-readable entrypoint. `SKILLS.md` lists specialized workflows that should be loaded only when the task requires them.
+
+## Active Profile
+
+{{profileSummary}}
+
+## Rule Hierarchy
+
+1. `ai/contract.json`
+2. `AGENTS.md`
+3. `SKILLS.md`
+4. `skills/*`
+5. `ai/*.md`
+6. Local project configs (`package.json`, `biome.json`, `tsconfig.json`)
+7. Existing source code and tests
+
+If rules conflict, the higher item wins. Existing code has no grandfathered exceptions.
+
+## Deterministic Rules
+
+{{deterministicRules}}
+
+## Heuristic Rules
+
+{{heuristicRules}}
+
+## Audit Rules
+
+{{auditRules}}
+
+## Deterministic Checks Run By Tooling
+
+- `npm run standards:check` validates project structure, README sections, managed files, metadata sync, and AI contract presence.
+- `npm run lint` uses Biome for baseline linting and formatting rules.
+- `npm run standards:check` also enforces AST-level project rules such as single return outside `src/http/`, async/await-only, section ordering, identifier quality, and naming rules.
+- `npm run check` is the final blocking gate.
+- Let Biome decide the final line wrapping. Do not force single-line layouts that the formatter keeps multiline.
+- `verify` MUST NOT enforce a visual layout that Biome can rewrite.
+- Fix every `error`.
+- Review every `warning` with judgment; do not rewrite code blindly if the result is less simple or less readable.
+- Report `audit` items explicitly, but they do not fail the default verification flow.
+
+## Section Ordering
+
+For class-first files, the `comment_section_blocks` list in `ai/contract.json` is the required order, not a suggested order.
+
+Required order:
+
+1. `imports:externals`
+2. `imports:internals`
+3. `consts`
+4. `types`
+5. `class`
+6. `private:attributes`
+7. `protected:attributes`
+8. `public:properties`
+9. `constructor`
+10. `static:properties`
+11. `factory`
+12. `private:methods`
+13. `protected:methods`
+14. `public:methods`
+15. `static:methods`
+
+Minimal example:
+
+```ts
+/**
+ * @section types
+ */
+
+type UserServiceOptions = { isEnabled: boolean };
+
+/**
+ * @section class
+ */
+export class UserService {
+  /**
+   * @section constructor
+   */
+  public constructor(private readonly options: UserServiceOptions) {}
+
+  /**
+   * @section public:methods
+   */
+  public readStatus(): boolean {
+    return this.options.isEnabled;
+  }
+}
+```
+
+`@section class` must sit directly above `export class`. Do not place JSDoc, block comments, or line comments between them.
+
+## README Rule
+
+- Rewrite `README.md` as package-quality integration documentation once real behavior exists.
+- Document every public export from `src/index.ts`.
+- If a public export is a class, document each public method with purpose, return value, and behavior notes.
+- Use a structure inspired by high-quality package READMEs such as `ky`: short value proposition, practical examples first, exhaustive API reference after.
+- Do not leave scaffold-placeholder API descriptions once implementation is real.
+
+## Simplicity Rule
+
+Simplicity is mandatory, not stylistic preference.
+
+- Use the simplest correct design for the current requirement.
+- Do not add speculative abstractions, wrappers, helper layers, extension points, or extra files without immediate justification.
+- If a solution can be made smaller and more direct without losing correctness, that simpler version MUST be preferred.
+- Simplicity does not justify removing valid boundaries.
+- Keep distinct current responsibilities separated when they serve a real purpose.
+- Keep code compact, but do not fight Biome over final wrapping decisions.
+- Templates are the canonical simplicity baseline. If a rule seems to require a more complex template, the rule is suspect.
+- Do not keep helper functions at module scope inside class-oriented feature files; move that logic into the class as private or static methods.
+- If a class starts accumulating unrelated responsibilities or growing into a very large file, you MUST split it into smaller cohesive units with explicit roles.
+
+## Managed Files
+
+{{managedFiles}}
+
+Do not edit managed files during normal feature work unless the user explicitly requests a standards update. Use `npx @sha3/code refactor --yes` when the package contract changes.
+Biome ignores managed files by default so contract docs and prompts do not create lint or format noise during normal implementation work.
+
+## Bootstrap Prompt
+
+Before writing code:
+
+1. Read `AGENTS.md`, `SKILLS.md`, `ai/contract.json`, and `ai/<assistant>.md`.
+2. For init-based work, open `skills/init-workflow/SKILL.md`, `skills/feature-shaping/SKILL.md`, `skills/simplicity-audit/SKILL.md`, and `skills/change-synchronization/SKILL.md`.
+3. For refactor work, open `skills/refactor-workflow/SKILL.md`, `skills/feature-shaping/SKILL.md`, `skills/simplicity-audit/SKILL.md`, and `skills/change-synchronization/SKILL.md`.
+4. Open `skills/test-scope-selection/SKILL.md` for meaningful behavior changes, `skills/readme-authoring/SKILL.md` whenever `README.md` changes, and `skills/http-api-conventions/SKILL.md` whenever HTTP endpoints exist or change.
+5. Summarize the `error` rules you will follow and the `warning` rules you will review carefully.
+6. Run `npm run standards:check` before and after implementation when feasible, then fix every `error`, review every `warning`, and report every `audit` item it reports.
+7. Implement the task without editing managed files unless the user explicitly asked for a standards update.
+8. Run `npm run check` and fix all issues before finishing.
+9. Prefer guard clauses and early returns inside `src/http/` transport adapters when they make request validation or response handling clearer; keep stricter single-return style in domain code.

package/resources/ai/templates/examples/demo/src/billing/billing.service.ts

@@ -0,0 +1,73 @@
+/**
+ * @section imports:internals
+ */
+
+import config from "../config.ts";
+import type { InvoiceService } from "../invoice/invoice.service.ts";
+import type { InvoiceSummary } from "../invoice/invoice.types.ts";
+
+/**
+ * @section types
+ */
+
+export type BillingSnapshot = { customerId: string; invoiceCount: number; totalAmount: number; formattedTotal: string; statusServiceUrl: string };
+
+/**
+ * @section class
+ */
+
+export class BillingService {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly invoiceService: InvoiceService;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(invoiceService: InvoiceService) {
+    this.invoiceService = invoiceService;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static create(invoiceService: InvoiceService): BillingService {
+    const service = new BillingService(invoiceService);
+    return service;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private formatCurrency(amount: number): string {
+    const formattedAmount = `${config.BILLING_CURRENCY_SYMBOL}${amount.toFixed(2)}`;
+    return formattedAmount;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public async snapshot(customerId: string): Promise<BillingSnapshot> {
+    const summary: InvoiceSummary = await this.invoiceService.summarizeForCustomer(customerId);
+    const snapshot: BillingSnapshot = {
+      customerId,
+      invoiceCount: summary.count,
+      totalAmount: summary.totalAmount,
+      formattedTotal: this.formatCurrency(summary.totalAmount),
+      statusServiceUrl: config.STATUS_SERVICE_URL,
+    };
+    return snapshot;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/demo/src/config.ts

@@ -0,0 +1,3 @@
+const config = { MINIMUM_INVOICE_AMOUNT: 0, BILLING_CURRENCY_SYMBOL: "$", STATUS_SERVICE_URL: "https://status.example.com/health" } as const;
+
+export default config;

package/resources/ai/templates/examples/demo/src/invoice/invoice.errors.ts

@@ -0,0 +1,51 @@
+/**
+ * @section types
+ */
+
+// empty
+
+/**
+ * @section class
+ */
+
+export class InvalidInvoiceCommandError extends Error {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly reason: string;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(reason: string) {
+    super(`Invalid invoice command: ${reason}`);
+    this.name = "InvalidInvoiceCommandError";
+    this.reason = reason;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static forReason(reason: string): InvalidInvoiceCommandError {
+    const error = new InvalidInvoiceCommandError(reason);
+    return error;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public getReason(): string {
+    const value = this.reason;
+    return value;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/demo/src/invoice/invoice.service.ts

@@ -0,0 +1,96 @@
+/**
+ * @section imports:externals
+ */
+
+import { randomUUID } from "node:crypto";
+
+/**
+ * @section imports:internals
+ */
+
+import config from "../config.ts";
+import { InvalidInvoiceCommandError } from "./invoice.errors.ts";
+import type { CreateInvoiceCommand, Invoice, InvoiceSummary } from "./invoice.types.ts";
+
+/**
+ * @section types
+ */
+
+// empty
+
+/**
+ * @section class
+ */
+
+export class InvoiceService {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly invoicesById: Map<string, Invoice>;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor() {
+    this.invoicesById = new Map<string, Invoice>();
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceService {
+    const service = new InvoiceService();
+    return service;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private validate(command: CreateInvoiceCommand): void {
+    if (!command.customerId.trim()) {
+      throw InvalidInvoiceCommandError.forReason("customerId is required");
+    }
+
+    if (command.amount <= config.MINIMUM_INVOICE_AMOUNT) {
+      throw InvalidInvoiceCommandError.forReason("amount must be greater than zero");
+    }
+  }
+
+  private toInvoice(command: CreateInvoiceCommand): Invoice {
+    const invoice: Invoice = { id: randomUUID(), customerId: command.customerId, amount: command.amount, issuedAt: new Date() };
+    return invoice;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public async create(command: CreateInvoiceCommand): Promise<Invoice> {
+    this.validate(command);
+    const createdInvoice: Invoice = this.toInvoice(command);
+    this.invoicesById.set(createdInvoice.id, createdInvoice);
+    return createdInvoice;
+  }
+
+  public async summarizeForCustomer(customerId: string): Promise<InvoiceSummary> {
+    const allInvoices: Invoice[] = Array.from(this.invoicesById.values());
+    const invoices: Invoice[] = allInvoices.filter((invoice) => {
+      return invoice.customerId === customerId;
+    });
+    const totalAmount = invoices.reduce((sum, invoice) => {
+      return sum + invoice.amount;
+    }, 0);
+    const summary: InvoiceSummary = { count: invoices.length, totalAmount };
+    return summary;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/demo/src/invoice/invoice.types.ts

@@ -0,0 +1,9 @@
+export type InvoiceId = string;
+
+export type CustomerId = string;
+
+export type Invoice = { id: InvoiceId; customerId: CustomerId; amount: number; issuedAt: Date };
+
+export type CreateInvoiceCommand = { customerId: CustomerId; amount: number };
+
+export type InvoiceSummary = { count: number; totalAmount: number };

package/resources/ai/templates/examples/rules/async-bad.ts

@@ -0,0 +1,52 @@
+/**
+ * @section types
+ */
+
+type SyncInvoicesCommand = { accountId: string };
+type Invoice = { id: string; accountId: string };
+type SyncResult = { saved: number };
+type InvoiceSource = { fetch(accountId: string): Promise<Invoice[]> };
+type InvoiceWriter = { persist(invoices: Invoice[]): Promise<SyncResult> };
+
+export class InvoiceSyncService {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly source: InvoiceSource;
+  private readonly writer: InvoiceWriter;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(source: InvoiceSource, writer: InvoiceWriter) {
+    this.source = source;
+    this.writer = writer;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static create(source: InvoiceSource, writer: InvoiceWriter): InvoiceSyncService {
+    const service = new InvoiceSyncService(source, writer);
+    return service;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public execute(command: SyncInvoicesCommand): Promise<SyncResult> {
+    return this.source.fetch(command.accountId).then((invoices: Invoice[]) => {
+      return this.writer.persist(invoices);
+    });
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/async-good.ts

@@ -0,0 +1,56 @@
+/**
+ * @section types
+ */
+
+type SyncInvoicesCommand = { accountId: string };
+type Invoice = { id: string; accountId: string };
+type SyncResult = { saved: number };
+type InvoiceSource = { fetch(accountId: string): Promise<Invoice[]> };
+type InvoiceWriter = { persist(invoices: Invoice[]): Promise<SyncResult> };
+
+/**
+ * @section class
+ */
+
+export class InvoiceSyncService {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly source: InvoiceSource;
+  private readonly writer: InvoiceWriter;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(source: InvoiceSource, writer: InvoiceWriter) {
+    this.source = source;
+    this.writer = writer;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static create(source: InvoiceSource, writer: InvoiceWriter): InvoiceSyncService {
+    const service = new InvoiceSyncService(source, writer);
+    return service;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public async execute(command: SyncInvoicesCommand): Promise<SyncResult> {
+    const invoices: Invoice[] = await this.source.fetch(command.accountId);
+    const result: SyncResult = await this.writer.persist(invoices);
+    return result;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/class-first-bad.ts

@@ -0,0 +1,36 @@
+/**
+ * @section types
+ */
+
+type CreateInvoiceCommand = { customerId: string; amount: number };
+type Invoice = { id: string; customerId: string; amount: number };
+
+export class InvoiceService {
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceService {
+    const service = new InvoiceService();
+    return service;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public async create(command: CreateInvoiceCommand): Promise<Invoice> {
+    if (!command.customerId) {
+      return Promise.reject(new Error("invalid command"));
+    }
+
+    const invoice: Invoice = { id: "1", customerId: command.customerId, amount: command.amount };
+    return invoice;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}