@sha3/code 1.0.0

package/AGENTS.md

@@ -0,0 +1,75 @@
+# Agent Entry Point
+
+This repository is AI-first. Always consume standards in this order:
+
+1. `standards/manifest.json` (source of truth)
+2. `standards/*.md` guides
+3. `profiles/default.profile.json`
+4. `resources/ai/templates/*` templates
+5. `ai/constitution.md`
+6. Assistant-specific adapter in `ai/adapters/`
+
+## Mandatory Rules
+
+- Follow `npm run check` before considering work complete.
+- Follow `profiles/schema.json` when updating style profiles.
+- Keep generated projects aligned with `@sha3/code` exports.
+- Use `code-standards profile` to maintain the default AI style profile.
+- Treat generated project-level `AGENTS.md` as blocking policy.
+- Follow `standards/readme.md` when creating or updating README files.
+- Require all generated content to be written in English, including code comments, README files, documentation, examples, and AI instruction files.
+- Treat simplicity as a mandatory rule: no speculative abstractions, no gratuitous indirection, no extra files/layers/wrappers unless they solve a real current problem.
+- Simplicity does not justify removing valid boundaries; keep distinct current responsibilities separated when they serve a real purpose.
+- Let Biome decide the final line wrapping and formatting shape.
+- Keep code compact when writing or refactoring, but do not fight Biome by forcing single-line objects, callbacks, or other constructs that the formatter intentionally keeps multiline.
+
+## Section Ordering
+
+For class-first files, `comment_section_blocks` is not illustrative. Its listed order is the required order for declared `@section` blocks.
+
+Minimal order reference:
+
+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 be immediately followed by the exported class declaration. Do not place JSDoc, block comments, or line comments between them.

package/README.md

@@ -0,0 +1,554 @@
+# @sha3/code
+
+Scaffold TypeScript projects, rebuild them with `refactor`, and enforce repository policy with `verify`.
+
+## TL;DR
+
+Create a new project:
+
+```bash
+npx @sha3/code init --template node-service --yes
+```
+
+Realign an existing repo:
+
+```bash
+npx @sha3/code refactor --yes
+```
+
+Run verification for humans:
+
+```bash
+npx @sha3/code verify
+```
+
+Run verification for automation:
+
+```bash
+npx @sha3/code verify --report json
+```
+
+Explain a deterministic rule:
+
+```bash
+npx @sha3/code verify --explain single-return
+```
+
+## Installation
+
+Use it directly with `npx`:
+
+```bash
+npx @sha3/code --help
+```
+
+Or install it in a repo:
+
+```bash
+npm install -D @sha3/code
+```
+
+## Compatibility
+
+- Node.js 20.11+
+- ESM package runtime
+- TypeScript-first projects
+- Biome as the baseline formatter and linter
+
+## What It Does
+
+`@sha3/code` manages 3 different concerns:
+
+- `init`: creates a standards-managed TypeScript scaffold
+- `refactor`: snapshots an existing repo and rebuilds it onto the managed scaffold
+- `verify`: enforces repository policy that generic tooling does not cover well
+
+That last part matters: `verify` is not another formatter or typechecker. It is the package-specific policy engine for generated repos.
+Generated scaffolds are also expected to ship package-grade README files rather than placeholder docs.
+
+## Non-Negotiables
+
+Simplicity is mandatory.
+
+- choose the simplest correct implementation for the current requirement
+- avoid speculative abstractions, helper layers, wrappers, and extension points without immediate need
+- if two solutions are both correct, prefer the smaller and more direct one
+- do not remove valid responsibility boundaries in the name of simplicity
+- simplicity means avoiding gratuitous complexity, not reducing structure blindly
+- let Biome decide final wrapping; prefer compact code, but do not force single-line layouts that the formatter keeps multiline
+
+## Public API
+
+### CLI commands
+
+```txt
+code-standards init
+code-standards refactor
+code-standards profile
+code-standards verify
+```
+
+### Package exports
+
+```txt
+@sha3/code/biome
+@sha3/code/tsconfig/base.json
+@sha3/code/tsconfig/node-lib.json
+@sha3/code/tsconfig/node-service.json
+```
+
+### `verify` options
+
+```txt
+code-standards verify [--report text|json] [--only <rule-id[,rule-id...]>] [--files <path[,path...]>] [--strict]
+code-standards verify --explain <rule-id>
+```
+
+Behavior notes:
+
+- `init` always works in the current directory and creates a fresh scaffold.
+- `refactor` always works in the current directory and never accepts a remote or local source argument.
+- `refactor` snapshots the previous repo state under `.code-standards/refactor-source/` before rebuilding managed files.
+- `verify` is the project-policy checker. It complements Biome and TypeScript instead of replacing them.
+- `verify --report json` is intended for CI, PR automation, and scripts.
+- default `verify` fails only on `error` severity; `--strict` also fails on `warning`.
+- `verify --explain <rule-id>` prints operational documentation for a rule without checking the repo.
+- `code-standards verify --help` prints the same option surface shown above.
+
+### What `verify` checks
+
+`verify` covers project policy that is specific to `@sha3/code`, including:
+
+- contract presence and validity for `AGENTS.md` and `ai/contract.json`
+- metadata sync between `package.json.codeStandards` and `ai/contract.json`
+- required managed files from the active template
+- required README sections
+- README documentation for public exports and public class methods
+- HTTP API documentation for service templates
+- TypeScript-only source policy in `src/` and `test/`
+- deterministic AST rules such as `single-return`, `async-await-only`, `canonical-config-import`, and file naming rules
+- `single-return` stays strict in `src/` except for `src/http/**`, where transport handlers may use early returns when that keeps request flow clearer
+
+### What `verify` does not check
+
+`verify` does not replace the generic toolchain:
+
+- formatting, line wrapping, and generic lint rules stay in Biome
+- type correctness stays in TypeScript
+- runtime behavior stays in tests
+
+### When to use `verify`
+
+Use the tools together, not interchangeably:
+
+- run Biome when you want style, formatting, and baseline lint feedback
+- run TypeScript when you want type-safety feedback
+- run `verify` when you want to enforce repository contract, scaffold integrity, and project-policy rules
+
+## Integration Guide
+
+### Create a new project
+
+```bash
+mkdir my-service
+cd my-service
+npx @sha3/code init --template node-service --yes
+```
+
+### `init` step by step
+
+Use `init` when you are starting a new repo from the managed scaffold.
+
+1. Create and enter the target directory.
+2. Run `init` with the template you want.
+3. Review the generated contract files before asking an LLM to write code.
+4. Fill `PROMPT.md` and give only that file to the LLM.
+5. Make the LLM execute `npm run check` itself and fix any failures before it finishes.
+
+Minimal flow:
+
+```bash
+mkdir my-service
+cd my-service
+npx @sha3/code init --template node-service --yes
+```
+
+What `init` generates for you:
+
+- `AGENTS.md` as the repo policy entrypoint
+- `SKILLS.md` as the index of specialized workflows that should only be loaded when relevant
+- `ai/contract.json` as the deterministic standards contract
+- `ai/rules.md` as the concise human-readable implementation rules file for the LLM
+- `skills/*` workflow guides such as init, refactor, feature shaping, simplicity audit, change synchronization, test scope selection, HTTP API conventions, and README authoring
+- `ai/<assistant>.md` adapter files when AI adapters are enabled
+- `PROMPT.md` in the project root as the single user-authored request file and LLM entrypoint
+- `prompts/init.prompt.md`, `prompts/init-phase-2-implement.md`, and `prompts/init-phase-3-verify.md` as internal workflow prompts the LLM should load by itself
+- the managed `src/`, `test/`, config, and package surface for the selected template
+- a README scaffold that is meant to be rewritten into package-grade integration documentation once real behavior exists
+- a root `SCAFFOLD-FEEDBACK.md` handoff requirement in the generated workflow so the LLM leaves scaffold/process feedback after implementation
+
+The CLI also prints the minimal next step after `init`, so the user does not have to infer the LLM workflow manually.
+
+Recommended LLM workflow after `init`:
+
+1. Open `PROMPT.md`.
+2. Complete the final `User Request` section.
+3. Paste only `PROMPT.md` into the LLM.
+4. Let the LLM read `prompts/init.prompt.md`, `prompts/init-phase-2-implement.md`, and `prompts/init-phase-3-verify.md` by itself.
+5. Let the LLM load optional skills only when the workflow actually triggers them.
+
+Minimal request example for `PROMPT.md`:
+
+```txt
+Task:
+- Build the first HTTP endpoint for service health.
+- Keep the generated scaffold structure intact.
+- Add tests for the new behavior.
+```
+
+The final phase must explicitly require the LLM to execute:
+
+```bash
+npm run check
+```
+
+The final phase must also require the LLM to fix any failing checks, rewrite `README.md` when behavior changes, and create or update `SCAFFOLD-FEEDBACK.md`.
+
+### Regenerate an existing repo
+
+Run this from the project root:
+
+```bash
+npx @sha3/code refactor --yes
+```
+
+`refactor` will:
+
+1. analyze the current repository
+2. capture preservation decisions
+3. write `.code-standards/refactor-source/latest/`
+4. write `public-contract.json`, `preservation.json`, and `analysis-summary.md`
+5. rebuild the managed scaffold
+6. generate the LLM workflow pack, with `PROMPT.md` as the single user entrypoint
+
+### `refactor` step by step
+
+Use `refactor` when you already have a repo and want to rebuild it onto the managed scaffold without losing the contracts you choose to preserve.
+
+1. Go to the root of the existing project.
+2. Run `refactor`.
+3. Answer the preservation questions if you are in interactive mode.
+4. Let the command move the legacy code into `.code-standards/refactor-source/latest/` and rebuild the managed surface.
+5. Open `PROMPT.md` and complete the request section.
+6. Paste only `PROMPT.md` into the LLM and let it load the refactor artifacts and phase prompts itself.
+7. Require the LLM to execute `npm run check` itself and fix any failures before it finishes.
+8. Require the LLM to finish by creating or updating `SCAFFOLD-FEEDBACK.md` with concrete scaffold/process feedback.
+
+Typical command:
+
+```bash
+npx @sha3/code refactor --yes
+```
+
+If you want dependencies installed as part of the run:
+
+```bash
+npx @sha3/code refactor --yes --install
+```
+
+After `refactor`, these files matter most:
+
+- `PROMPT.md`
+- `AGENTS.md`
+- `SKILLS.md`
+- `skills/feature-shaping/SKILL.md`
+- `skills/simplicity-audit/SKILL.md`
+- `skills/change-synchronization/SKILL.md`
+- `skills/test-scope-selection/SKILL.md`
+- `skills/http-api-conventions/SKILL.md`
+- `ai/contract.json`
+- `ai/rules.md`
+- `skills/refactor-workflow/SKILL.md`
+- `.code-standards/refactor-source/public-contract.json`
+- `.code-standards/refactor-source/preservation.json`
+- `.code-standards/refactor-source/analysis-summary.md`
+- `.code-standards/refactor-source/latest/`
+- `prompts/refactor.prompt.md`
+- `prompts/refactor-phase-2-rebuild.md`
+- `prompts/refactor-phase-3-verify.md`
+
+The CLI prints the single LLM entry file after `refactor` completes. The normal flow is: run `refactor`, complete `PROMPT.md`, and give only that file to the LLM.
+
+Important behavior note:
+
+- `refactor` does not run `npm run fix` or `npm run check` against the intermediate refactor state.
+- `refactor` does not run the final `npm run check` against the pre-refactor codebase.
+- The old implementation is moved to `.code-standards/refactor-source/latest/` as reference material.
+- The final validation belongs to the rewritten `src/` and `test/` produced after the LLM handoff.
+
+Recommended LLM workflow after `refactor`:
+
+1. Run `refactor` and wait for it to complete.
+2. Open `PROMPT.md` and complete the `User Request` section.
+3. Paste only `PROMPT.md` into the LLM.
+4. Let the LLM read `prompts/refactor.prompt.md`, `prompts/refactor-phase-2-rebuild.md`, and `prompts/refactor-phase-3-verify.md` by itself.
+5. Let the LLM rebuild, verify, and close the task end to end.
+
+Minimal request example for `PROMPT.md`:
+
+```txt
+Task:
+- Rebuild the application behavior inside the fresh scaffold under src/ and test/.
+- Preserve the public API and HTTP contracts captured in the refactor artifacts.
+- Do not edit managed files unless a standards update is explicitly required.
+```
+
+6. Make the final phase rewrite `README.md` as package-grade integration documentation for the rebuilt public API and runtime behavior when needed.
+7. In the final phase, explicitly require the LLM to execute:
+
+```bash
+npm run check
+```
+
+8. Require the LLM to fix any failing checks and rerun the command until it passes.
+
+Practical rule: `refactor` prepares the repo and the context pack; the user only fills `PROMPT.md`, and the LLM consumes the rest of the workflow pack autonomously.
+
+### Verify a project
+
+Human-readable verification:
+
+```bash
+npx @sha3/code verify
+```
+
+Machine-readable verification:
+
+```bash
+npx @sha3/code verify --report json
+```
+
+Focused verification by rule:
+
+```bash
+npx @sha3/code verify --only single-return,canonical-config-import
+```
+
+Focused verification by files:
+
+```bash
+npx @sha3/code verify --files src/user/user.service.ts,test/user.test.ts
+```
+
+Strict verification:
+
+```bash
+npx @sha3/code verify --strict
+```
+
+Combined scope control:
+
+```bash
+npx @sha3/code verify --report json --only single-return --files src/user/user.service.ts
+```
+
+Rule explanation:
+
+```bash
+npx @sha3/code verify --explain single-return
+```
+
+`verify` is the command generated projects use behind `npm run standards:check`.
+
+## Configuration
+
+Generated projects centralize runtime constants in `src/config.ts`.
+
+This package centralizes standards through:
+
+- [`standards/manifest.json`](/Users/jc/Documents/GitHub/code-standards/standards/manifest.json) as the canonical standards manifest
+- [`profiles/default.profile.json`](/Users/jc/Documents/GitHub/code-standards/profiles/default.profile.json) as the default AI profile
+- [`biome.json`](/Users/jc/Documents/GitHub/code-standards/biome.json) as the shared Biome config export
+
+Profile-driven behavior can be customized with:
+
+```bash
+npx @sha3/code profile --profile ./profiles/team.profile.json
+```
+
+Then applied during `init` or `refactor` with `--profile`.
+
+## Scripts
+
+Repository-level scripts:
+
+- `npm run check`: standards validation, profile validation, AI resource validation, Biome lint, Biome format check, typecheck, tests
+- `npm run fix`: Biome write + format write
+- `npm run lint`: `biome check .`
+- `npm run format:check`: `biome format .`
+- `npm run typecheck`: TypeScript validation
+- `npm run test`: smoke fixtures plus Node test runner
+
+Generated project scripts:
+
+- `npm run standards:check`: `code-standards verify`
+- `npm run check`: standards + lint + format + typecheck + tests
+- `npm run fix`: Biome autofix + format write
+
+## Structure
+
+Key repository paths:
+
+- `bin/code-standards.mjs`: CLI entrypoint
+- `lib/cli/run-init.mjs`: project initialization flow
+- `lib/cli/run-refactor.mjs`: in-place refactor flow
+- `lib/cli/run-verify.mjs`: deterministic verification flow
+- `lib/verify/`: issue model, explain mode, renderers, project checks, and AST-level source rules
+- `templates/`: `node-lib` and `node-service` managed scaffolds
+- `prompts/`: starter prompts for `init` and `refactor`
+- `resources/ai/`: AI contract templates, adapters, examples, and rule catalog
+
+## Troubleshooting
+
+### `biome: command not found`
+
+Install dependencies in the current workspace:
+
+```bash
+npm install
+```
+
+### `refactor` says `package.json` was not found
+
+Run `code-standards refactor` from the root of the target project.
+
+### Verify Modes
+
+`verify` has 5 useful modes:
+
+- default text mode: human-readable errors to `stderr`
+- `--report json`: structured output to `stdout`
+- `--only`: execute only selected rule ids
+- `--files`: limit file-oriented checks to a subset of files
+- `--strict`: fail on warnings as well as errors
+- `--explain`: print documentation for one rule instead of verifying the repo
+
+Important behavior:
+
+- project-wide contract checks still run even when `--files` is used
+- file-oriented checks such as AST source rules and TypeScript-only checks are scoped by `--files`
+- `--explain` cannot be combined with `--report`, `--only`, or `--files`
+- `text` remains the default output mode to preserve human-friendly local usage
+
+### Verify Output
+
+Example text output:
+
+```txt
+- ERROR [single-return] src/user/user.service.ts: functions and methods outside src/http/ must use a single return statement
+- WARNING [large-class-heuristic/heuristic] src/user/user.service.ts: very large classes should be decomposed into smaller cohesive units
+Verification failed with 1 error(s) and 1 warning(s).
+```
+
+Example JSON output:
+
+```json
+{
+  "ok": false,
+  "hasWarnings": true,
+  "issues": [
+    {
+      "ruleId": "single-return",
+      "category": "source-rule",
+      "severity": "error",
+      "message": "functions and methods outside src/http/ must use a single return statement",
+      "relativePath": "src/user/user.service.ts",
+      "enforcedBy": "verify"
+    }
+  ],
+  "summary": {
+    "issueCount": 1,
+    "errorCount": 1,
+    "warningCount": 0,
+    "auditCount": 0,
+    "checkedRuleIds": ["single-return"],
+    "checkedFiles": ["src/user/user.service.ts"]
+  }
+}
+```
+
+Exit code behavior:
+
+- exit code `0`: verification passed at the requested severity threshold
+- exit code non-zero: verification found blocking severities for the current mode or arguments were invalid
+
+### Using verify in CI
+
+Save a structured report:
+
+```bash
+npx @sha3/code verify --report json > verify-report.json
+```
+
+Fail a script based on the result:
+
+```bash
+node -e 'const fs=require("node:fs"); const report=JSON.parse(fs.readFileSync("verify-report.json","utf8")); if(!report.ok) process.exit(1)'
+```
+
+Run a targeted CI check for a narrow rule:
+
+```bash
+npx @sha3/code verify --report json --only single-return
+```
+
+### Troubleshooting verify
+
+If `verify` fails, first decide what kind of failure it is:
+
+- contract/metadata/layout problem: check `AGENTS.md`, `ai/contract.json`, `package.json.codeStandards`, or missing scaffold files
+- source-rule problem: use the reported `ruleId`, file path, and `verify --explain <rule-id>`
+- README problem: restore the required sections
+
+Common cases:
+
+- unknown rule id in `--only`: use `code-standards verify --explain <rule-id>` or inspect `resources/ai/rule-catalog.json`
+- too much output: narrow the run with `--only` or `--files`
+- Biome and TypeScript pass but `verify` fails: expected, because `verify` checks product policy and contract rules that generic tooling does not cover, but line-wrapping disputes should now be treated as Biome territory
+
+### Required README headings in generated projects
+
+Keep these headings in generated projects, at minimum:
+
+- for both templates: `## TL;DR`, `## Why`, `## Main Capabilities`, `## Installation`, `## Usage`, `## Examples`, `## Public API`, `## Configuration`, `## Compatibility`, `## Scripts`, `## Structure`, `## Troubleshooting`, `## AI Workflow`
+- for `node-service` also: `## Running Locally` and `## HTTP API`
+
+### VS Code formatting conflicts
+
+Use the `biomejs.biome` extension as the default formatter for generated projects.
+
+## AI Workflow
+
+Generated projects treat these files as the local AI contract:
+
+1. `ai/contract.json`
+2. `AGENTS.md`
+3. `SKILLS.md`
+4. `skills/*`
+5. `ai/rules.md`
+6. `ai/<assistant>.md`
+
+Recommended bootstrap prompt:
+
+```txt
+Before generating code:
+- Read AGENTS.md, SKILLS.md, ai/contract.json, ai/rules.md, and ai/<assistant>.md.
+- Load `skills/init-workflow/SKILL.md`, `skills/feature-shaping/SKILL.md`, `skills/simplicity-audit/SKILL.md`, and `skills/change-synchronization/SKILL.md` for init-based implementation.
+- Load `skills/refactor-workflow/SKILL.md`, `skills/feature-shaping/SKILL.md`, `skills/simplicity-audit/SKILL.md`, and `skills/change-synchronization/SKILL.md` for refactor work.
+- Load `skills/test-scope-selection/SKILL.md` for meaningful behavior changes, `skills/readme-authoring/SKILL.md` whenever README changes, and `skills/http-api-conventions/SKILL.md` whenever HTTP endpoints exist or change.
+- Summarize the `error` rules and the `warning` rules you will review carefully.
+- Implement the task without editing managed files unless this is a standards update.
+- Run npm run check and fix all failures before finishing.
+```
+
+For a standards migration on an existing repo, run `refactor` first and then use the generated files under `.code-standards/refactor-source/` as reference context for the rewrite.

package/ai/adapters/codex.md

@@ -0,0 +1,7 @@
+# Codex Adapter
+
+- Read `AGENTS.md` first.
+- Use `npm run check` as the final quality gate.
+- Fix `error` rules first and treat `warning` rules as review signals, not blind rewrite orders.
+- Prefer implementation over speculative planning when execution is requested.
+- If `npm run check` reports TypeScript errors, fix code and rerun checks.

package/ai/adapters/copilot.md

@@ -0,0 +1,7 @@
+# GitHub Copilot Adapter
+
+- Keep generated snippets aligned with `@sha3/code` tooling exports.
+- Use ESM imports/exports by default.
+- Include tests under `test/` for new behavior.
+- Do not overcorrect warnings into more complex code when a simpler implementation already satisfies the contract.
+- If TypeScript fails in `npm run check`, update code and rerun checks.

package/ai/adapters/cursor.md

@@ -0,0 +1,7 @@
+# Cursor Adapter
+
+- Load `standards/manifest.json` before generating code.
+- Favor direct edits to existing files instead of broad rewrites.
+- Respect Biome as the only authority for final code layout.
+- Run `npm run check` locally after modifications.
+- Fix TypeScript errors before considering work complete.

package/ai/adapters/windsurf.md

@@ -0,0 +1,8 @@
+# Windsurf Adapter
+
+- Treat this repo as an AI policy package plus reusable tooling.
+- Use `npx @sha3/code init` for new project bootstraps.
+- Prefer local deterministic checks (`npm run check`) over remote assumptions.
+- Treat Biome as the final authority for formatting and layout.
+- Generate assistant files (`AGENTS.md`, `ai/*.md`) unless explicitly disabled.
+- If TypeScript fails in `npm run check`, fix code and rerun checks.

package/ai/constitution.md

@@ -0,0 +1,12 @@
+# AI Constitution
+
+These rules apply to all assistants using this repository.
+
+- Treat `standards/manifest.json` as normative.
+- Prefer deterministic and repeatable commands.
+- Keep changes small, explicit, and testable.
+- Let Biome decide the final line wrapping. Keep code compact, but do not fight formatter-preserved multiline layouts.
+- Do not turn formatter preferences into verifier failures.
+- Treat warnings as review signals, not mandatory rewrites, unless the user explicitly asks for a stricter pass.
+- Run `npm run check` before finalizing edits.
+- Use project templates for new projects unless explicitly overridden.