maurao-method 0.0.0-stage → 0.1.2

package/docs/artifact-contract.md

@@ -0,0 +1,22 @@
+# Artifact contract
+
+The project-local `.maurao/` directory is the durable state of the method. Tool adapters and chat history are transport layers; they are not the source of truth.
+
+## Required artifacts by depth
+
+| Depth | Required artifacts |
+|---|---|
+| L0 | Verification note in the final response |
+| L1 | Specification, implementation plan, test plan, verification report |
+| L2 | System context, change proposal, decision records, test plan, observability plan, verification report |
+| L3 | Product brief, system context, technology inventory, requirements, architecture decisions, delivery increments, threat model, verification and release reports |
+
+## Naming
+
+- Specifications: `.maurao/specifications/<change-id>.md`
+- Decisions: `.maurao/decisions/ADR-<number>-<slug>.md`
+- Plans: `.maurao/plans/<change-id>.md`
+- Reports: `.maurao/reports/<change-id>-<report-type>.md`
+
+Use stable IDs such as `REQ-001`, `AC-001`, `TASK-001`, `TEST-001`, and `THR-001` to preserve traceability.
+

package/docs/commands.md

@@ -0,0 +1,32 @@
+# Maurao commands
+
+These are tool-independent commands. A tool adapter may expose them as slash commands, chat prompts, or task templates, but the semantics remain the same.
+
+| Command | Purpose | Primary mode |
+|---|---|---|
+| `maurao discover` | Understand the problem, users, constraints, and existing context | Greenfield / Brownfield |
+| `maurao map` | Map an existing codebase, system, contracts, and risks | Brownfield |
+| `maurao inspect` | Detect technology evidence and write `.maurao/technology-inventory.md` | Any |
+| `maurao specify` | Create or refine a testable change specification | Any |
+| `maurao design` | Produce architecture, decisions, and trade-offs | L2 / L3 |
+| `maurao plan` | Decompose approved work into ordered, verifiable tasks | Any non-trivial change |
+| `maurao build` | Implement the approved plan using the selected technology pack | Any |
+| `maurao test` | Derive and execute the relevant test strategy | Any |
+| `maurao debug` | Investigate a failure using hypotheses and evidence | Bug fix / incident |
+| `maurao spike` | Answer a bounded technical question through an experiment | Any |
+| `maurao verify` | Map acceptance criteria to executed evidence | Any |
+| `maurao review` | Perform an independent change review | Any reviewable change |
+| `maurao pr` | Prepare a focused pull request | Delivery |
+| `maurao status` | Report artifacts, gate, risks, and remaining work | Any |
+
+## Command contract
+
+Every command must state:
+
+- inputs it read;
+- artifacts it created or changed;
+- decisions it made;
+- validations it executed;
+- blockers and assumptions;
+- the next gate.
+

package/docs/method-overview.md

@@ -0,0 +1,32 @@
+# Method Overview
+
+Maurao Method treats software development as a sequence of explicit decisions and verifiable outcomes.
+
+```text
+Understand → Specify → Plan → Implement → Verify → Review → Deliver
+```
+
+The sequence is adaptive. Small, low-risk changes may use a lightweight path. Ambiguous, risky, or cross-cutting changes should use the complete workflow.
+
+The method first classifies the project as greenfield, brownfield, or hybrid and then discovers the actual technology stack. This prevents the agent from applying a generic workflow or the wrong framework assumptions to the repository.
+
+See [the complete workflow](workflow.md), [project modes](project-modes.md), and [portable commands](commands.md).
+
+## Work modes
+
+- Feature development: deliver new behavior.
+- Bug fixing: restore intended behavior and add regression protection.
+- Debugging: investigate an observed failure before changing implementation.
+- Spike: answer a bounded technical question without pretending the experiment is production code.
+- Refactoring: improve structure while preserving behavior.
+
+## Evidence standard
+
+Every completed work item should identify:
+
+- what was requested;
+- what changed;
+- what was verified;
+- what remains assumed or unverified;
+- which validation commands were executed and their results.
+

package/docs/npm-release.md

@@ -0,0 +1,68 @@
+# npm CI/CD
+
+The repository has three GitHub Actions workflows:
+
+- `ci.yml`: validates pushes and pull requests.
+- `publish.yml`: provides an optional manual OIDC publish path.
+- `release-on-main.yml`: increments the patch version, publishes, tags, and creates a GitHub Release after package changes reach `main`.
+
+## One-time setup
+
+1. Create or confirm the npm package name.
+2. Ensure the package metadata points to this GitHub repository.
+3. Create an npm access token with permission to publish this package.
+4. In GitHub, open `Settings → Secrets and variables → Actions` and create:
+
+   ```text
+   Name: NPM_TOKEN
+   Value: <the npm access token>
+   ```
+
+5. Create the GitHub environment named `npm`.
+6. If you prefer tokenless publishing, configure npm Trusted Publishing instead. On npmjs.com, open the package settings and add a GitHub Actions Trusted Publisher.
+7. Configure:
+   - owner: `luismpenholato`;
+   - repository: `maurao-method`;
+   - workflow filename: `publish.yml`;
+   - environment: `npm`.
+8. Add approval rules to the `npm` environment if you want a human gate before publication.
+
+The automatic `release-on-main.yml` workflow uses `NPM_TOKEN`. The tag-based `publish.yml` workflow uses OIDC Trusted Publishing and does not require `NPM_TOKEN`.
+
+## Release process
+
+For automatic releases, merge a package change into `main`. The workflow will:
+
+1. Validate the package and run tests.
+2. Increment the patch version.
+3. Publish the package using `NPM_TOKEN`.
+4. Commit the new `package.json` and `package-lock.json`.
+5. Create a `vX.Y.Z` tag.
+6. Create a GitHub Release with generated notes.
+
+For a controlled manual release, update the version and create a tag:
+
+```powershell
+npm version patch
+git push origin main --follow-tags
+```
+
+For a minor or major release:
+
+```powershell
+npm version minor
+npm version major
+```
+
+The release workflow pushes an annotated version tag and creates the GitHub Release after publication. The tag does not trigger a second npm publication.
+
+For the optional tokenless path, run `publish.yml` manually after configuring npm Trusted Publishing for the repository and workflow.
+
+## Local checks
+
+```powershell
+npm run validate
+npm pack --dry-run
+```
+
+Do not place npm tokens in the repository, workflow file, or `.npmrc` committed to source control.

package/docs/portable-adapters.md

@@ -0,0 +1,26 @@
+# Portable adapters
+
+Maurao Method has one canonical source and thin tool adapters.
+
+## Canonical source
+
+- Instructions: `AGENTS.md`
+- Skills: `skills/**/SKILL.md`
+- Technology packs: `technology-packs/` (Node.js, .NET, Python, Java, and extensible stacks)
+- Templates: `templates/`
+- Commands: `commands/`
+
+## Supported entry points
+
+| Tool | Repository entry point | Skills location |
+|---|---|---|
+| OpenAI Codex / ChatGPT Codex | `AGENTS.md` | Repository skills, installed as needed |
+| Claude Code | `CLAUDE.md` | `.claude/skills/` or shared Agent Skills directory |
+| Cursor | `.cursor/rules/maurao-method.mdc` | Rules can point to canonical skills |
+| GitHub Copilot | `.github/copilot-instructions.md` | `.github/skills/` or `.agents/skills/` |
+| Gemini CLI | `GEMINI.md` | Context file points to canonical skills |
+| Cline | `.clinerules/maurao-method.md` | Workspace rules point to canonical skills |
+| VS Code agents | `AGENTS.md`, `CLAUDE.md` | Depends on the selected agent |
+
+The adapters intentionally stay short. They establish discovery and delegate to the canonical files so behavior does not fork between tools. The installer materializes native skill directories where a tool requires them.
+

package/docs/project-modes.md

@@ -0,0 +1,33 @@
+# Project modes
+
+## Greenfield
+
+Use when the product or subsystem does not have a reliable implementation baseline.
+
+1. Define the problem, users, value, and non-goals.
+2. Identify the smallest useful product slice.
+3. Define domain concepts, user journeys, and acceptance criteria.
+4. Choose architecture and technology only after constraints are known.
+5. Create the first vertical slice with tests and operational signals.
+6. Validate with real feedback before expanding scope.
+
+Do not create a large platform architecture before the first useful slice proves the important assumptions.
+
+## Brownfield
+
+Use when an existing product, codebase, API, database, or operational system must be changed.
+
+1. Map the current system before proposing a target design.
+2. Identify ownership, boundaries, dependencies, data flows, and undocumented behavior.
+3. Write invariants: behavior that MUST remain unchanged.
+4. Define the delta between current and desired state.
+5. Choose a migration and rollback strategy.
+6. Implement in reversible increments.
+7. Verify both the new behavior and compatibility with the existing behavior.
+
+Brownfield work must never treat the specification as the only source of truth. The running system, tests, telemetry, contracts, and user behavior are evidence too.
+
+## Hybrid
+
+Use when a new product is being introduced into an existing organization or platform. Apply greenfield product framing and brownfield integration mapping together.
+

package/docs/specification-standard.md

@@ -0,0 +1,25 @@
+# Specification standard
+
+## Required sections
+
+Every non-trivial change should define:
+
+1. Context and problem.
+2. Desired outcome.
+3. Scope and non-goals.
+4. Constraints and invariants.
+5. Behavioral requirements.
+6. Acceptance criteria.
+7. Risks and open decisions.
+8. Verification plan.
+
+## Requirement quality
+
+Requirements must be observable, testable, and independent of implementation details unless the implementation constraint is intentional.
+
+Use MUST for mandatory behavior, SHOULD for a justified default, and MAY for optional behavior.
+
+## Traceability
+
+Use stable identifiers such as `REQ-001`, `AC-001`, and `TEST-001`. Verification should map acceptance criteria to tests, checks, inspection, or explicit human review.
+

package/docs/tool-support.md

@@ -0,0 +1,24 @@
+# Tool and model support
+
+## GPT and Codex
+
+GPT is the model. Codex is the coding-agent environment that reads the repository, edits files, runs commands, and applies project instructions.
+
+Maurao Method supports Codex through the root `AGENTS.md`. It can be used with GPT models selected by Codex because the method is expressed as Markdown skills and repository artifacts, not as model-specific API calls.
+
+ChatGPT or the GPT API by itself does not automatically inspect a local repository or execute the method. It needs a host application, agent harness, or integration that provides the repository files and exposes the relevant skills and commands.
+
+## Support matrix
+
+| Environment | Entry point | Level |
+|---|---|---|
+| OpenAI Codex / ChatGPT Codex | `AGENTS.md` | Native repository instructions |
+| GPT through another agent host | Host-specific adapter | Supported when the host loads the files |
+| Claude Code | `CLAUDE.md`, `.claude/skills/` | Native adapter and skills |
+| Cursor | `.cursor/rules/` | Native rules adapter |
+| GitHub Copilot | `.github/copilot-instructions.md`, `.agents/skills/` | Native instructions and skills |
+| Gemini CLI | `GEMINI.md` | Native context adapter |
+| Cline | `.clinerules/` | Native workspace rules adapter |
+
+The portable contract is the same in every environment: read the repository contract, discover the project technology, select the workflow, load only the required skills, and report evidence.
+

package/docs/workflow.md

@@ -0,0 +1,45 @@
+# Maurao Method workflow
+
+Maurao is an adaptive SDD method. It does not force the same ceremony on a landing page, a payment flow, and a distributed migration.
+
+## Lifecycle
+
+```text
+Discover → Frame → Specify → Design → Plan → Build → Verify → Review → Deliver → Learn
+```
+
+Each phase has an output and a gate. The agent may move forward only when the gate is satisfied or the remaining uncertainty is explicitly accepted.
+
+Choose the lowest level that honestly covers the risk. Increase the level when ambiguity, blast radius, security impact, data migration, or operational consequence increases. Never reduce the level only to avoid creating required evidence.
+
+## Depth levels
+
+### L0 — Trivial
+
+Use for isolated, low-risk changes with obvious behavior. Read the relevant code, make the change, run a focused check, and report evidence.
+
+### L1 — Focused change
+
+Use for a normal feature or bug fix. Create a short change specification, acceptance criteria, implementation plan, tests, and verification report.
+
+### L2 — Complex change
+
+Use for cross-module behavior, public APIs, persistence, integrations, security, or operational impact. Add system context, architecture decisions, risk analysis, observability, migration/rollback planning, and independent review.
+
+### L3 — Product or system initiative
+
+Use for a new product, major subsystem, platform, or high-risk change. Add product framing, domain model, user journeys, non-functional requirements, threat model, delivery increments, and explicit human approval gates.
+
+## Gates
+
+| Gate | Question | Minimum evidence |
+|---|---|---|
+| Frame | Are we solving the right problem? | Problem, users, outcome, non-goals |
+| Specify | Is the desired behavior unambiguous? | Requirements and acceptance criteria |
+| Design | Is the solution compatible with the system? | Architecture and decisions |
+| Plan | Can the work be implemented and verified incrementally? | Ordered tasks and test plan |
+| Build | Was only the approved scope changed? | Diff and implementation notes |
+| Verify | Does evidence support each acceptance criterion? | Executed checks and verification matrix |
+| Review | Can another engineer challenge the result? | Independent review and findings |
+| Deliver | Can this be released and operated safely? | Rollout, rollback, and observability plan |
+

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "maurao-method",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Portable specification-driven engineering method and skills for AI coding agents",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/luismpenholato/maurao-method.git"
+  },
+  "homepage": "https://github.com/luismpenholato/maurao-method#readme",
+  "bugs": {
+    "url": "https://github.com/luismpenholato/maurao-method/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "bin": {
+    "maurao": "bin/maurao.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    ".clinerules",
+    ".cursor",
+    ".github",
+    ".maurao",
+    "bin",
+    "commands",
+    "docs",
+    "skills",
+    "technology-packs",
+    "templates"
+  ],
+  "scripts": {
+    "validate": "node bin/maurao.mjs validate",
+    "list": "node bin/maurao.mjs list",
+    "test": "node --test"
+  },
+  "license": "MIT"
+}

package/skills/core/architecture/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: architecture
+description: Make proportionate architecture decisions grounded in the existing codebase and constraints.
+---
+
+# Architecture
+
+1. Determine project mode and map the current boundaries, dependencies, data flow, and extension points.
+2. Find existing patterns before introducing a new one.
+3. State constraints, alternatives, trade-offs, and rejected options.
+4. Prefer the smallest design that preserves testability, operability, and future change.
+5. Consider security, privacy, accessibility, reliability, performance, operability, and cost as architecture concerns.
+6. Record decisions that affect public interfaces, persistence, deployment, security, or ownership.
+
+Do not create abstractions only to avoid a small amount of repetition.
+

package/skills/core/brownfield-analysis/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: brownfield-analysis
+description: Analyze an existing codebase and running system to identify behavior, boundaries, invariants, risks, and safe change seams.
+---
+
+# Brownfield Analysis
+
+Inspect before editing:
+
+- repository and module structure;
+- build, test, lint, and deployment paths;
+- entry points and public interfaces;
+- persistence, migrations, queues, and external integrations;
+- configuration and environment boundaries;
+- tests, telemetry, recent changes, and known failures.
+
+Use evidence to distinguish intended behavior, tested behavior, observed behavior, and accidental behavior. Record contradictions instead of resolving them silently.
+
+Produce `templates/brownfield-map.md` and identify the smallest safe change seam.
+

package/skills/core/debugging/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: debugging
+description: Investigate failures using reproduction, hypotheses, evidence, and regression protection.
+---
+
+# Debugging
+
+Do not modify production code until the failure is understood well enough to state a reproducible symptom.
+
+## Workflow
+
+1. Restate the observed problem and expected behavior.
+2. Reproduce it with the smallest reliable case.
+3. List three to seven plausible hypotheses.
+4. Prioritize the one or two most likely hypotheses using available evidence.
+5. Collect targeted evidence from code, tests, logs, network, or runtime state.
+6. Identify the root cause and explain the causal chain.
+7. Apply the smallest safe fix.
+8. Add or update a regression test.
+9. Re-run the related validation and remove temporary diagnostics.
+
+## Report
+
+End with:
+
+- symptom;
+- root cause;
+- fix;
+- regression protection;
+- validations executed;
+- remaining uncertainty.
+

package/skills/core/planning/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: planning
+description: Convert an approved specification into small, ordered, independently verifiable implementation tasks.
+---
+
+# Planning
+
+- Read the specification, system context, technology inventory, and decisions.
+- Order work by dependency and risk, not by file order.
+- Prefer vertical slices that can be tested and reviewed independently.
+- Give every task a clear change boundary and completion condition.
+- Include migration, compatibility, observability, documentation, and rollback work when applicable.
+- Keep discovery or unresolved decisions out of implementation tasks; route them to a spike or decision record.
+
+## Task contract
+
+Each task must include: purpose, files or boundary likely to change, dependencies, test or evidence required, and a definition of done.
+

package/skills/core/product-discovery/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: product-discovery
+description: Turn a product idea into a testable problem, user outcome, smallest useful slice, and measurable success criteria.
+---
+
+# Product Discovery
+
+1. Identify the user, context, pain, and desired outcome.
+2. Separate observed evidence from assumptions.
+3. Define non-goals and constraints.
+4. Describe the smallest end-to-end slice that can test the central assumption.
+5. Define success measures and how they will be observed.
+6. Record unanswered questions and propose spikes when uncertainty is technical.
+
+## Output
+
+Create or update `.maurao/product-brief.md`. Do not create implementation tasks until the problem, smallest useful slice, and success measures are explicit enough to evaluate.
+
+Do not turn an unvalidated idea into a large technical backlog. Product discovery must precede architecture for new products unless a hard constraint requires the reverse.
+

package/skills/core/project-discovery/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: project-discovery
+description: Build a reliable project baseline before changing a new or existing software product.
+---
+
+# Project Discovery
+
+## Greenfield
+
+Inspect the repository and product brief when present, then identify the smallest useful slice, assumptions, constraints, risks, and required technology decisions. If no repository exists, record that fact instead of inventing a baseline.
+
+## Brownfield
+
+Inspect the repository, history when useful, build system, tests, runtime configuration, public contracts, data flows, and operational evidence before proposing a change.
+
+## Required baseline
+
+- project mode: greenfield, brownfield, or hybrid;
+- product or system purpose;
+- repository map;
+- technology inventory from `technology-discovery`;
+- entry points and important boundaries;
+- commands for build, test, lint, and run;
+- invariants and compatibility constraints;
+- unknowns, risks, and recommended next step.
+
+## Output
+
+Create or update `.maurao/system-context.md` and coordinate with `technology-discovery`, which creates `.maurao/technology-inventory.md`.
+
+Do not produce a confident implementation plan when this baseline is missing material information.
+

package/skills/core/requirements/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: requirements
+description: Elicit, structure, prioritize, and validate functional and non-functional requirements for software products.
+---
+
+# Requirements
+
+Capture functional behavior, quality attributes, constraints, integrations, data, security, accessibility, operations, and compatibility.
+
+For each requirement, record source, priority, rationale, measurable acceptance criteria, and dependencies.
+
+Challenge requirements that conflict, are not observable, or prescribe implementation without a justified constraint. Preserve unresolved decisions explicitly instead of silently choosing on behalf of the product owner.
+

package/skills/core/specification/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: specification
+description: Define a clear, testable software change before implementation.
+---
+
+# Specification
+
+Use this skill when a request changes product behavior, architecture, data, APIs, user experience, or operational behavior.
+
+## Outcomes
+
+Produce a specification at the depth selected by the workflow. It must contain:
+
+1. Context, problem, users, and desired outcome.
+2. Project mode and scope: greenfield, brownfield, or hybrid.
+3. Explicit non-goals and constraints.
+4. Actors, inputs, outputs, states, and boundaries.
+5. Functional behavior and edge cases.
+6. Non-functional requirements: security, privacy, accessibility, performance, reliability, and operations when relevant.
+7. Acceptance criteria that can be verified.
+8. Compatibility, migration, rollout, and rollback when changing an existing system.
+9. Open decisions, assumptions, risks, and a verification plan.
+
+## Rules
+
+- Read the existing code and project conventions before proposing implementation details.
+- Separate requirements from solutions.
+- Use observable language; avoid vague terms such as "works correctly".
+- Do not invent production data or undocumented behavior.
+- For brownfield work, describe current behavior and invariants before desired behavior.
+- Prefer vertical slices and incremental delivery over a large speculative design.
+- If an ambiguity materially changes the implementation, record it as an open decision.
+
+## Acceptance criteria format
+
+```text
+Given <precondition>
+When <action>
+Then <observable result>
+```
+

package/skills/core/spike/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: spike
+description: Answer a bounded technical question through a time-boxed, evidence-based experiment.
+---
+
+# Spike
+
+A spike reduces uncertainty. It is not permission to build production code without a decision.
+
+## Required inputs
+
+- question to answer;
+- success criteria;
+- constraints;
+- time or effort budget;
+- alternatives to compare.
+
+## Workflow
+
+1. State the question and what is out of scope.
+2. Define the smallest experiment that can produce useful evidence.
+3. Record setup, inputs, observations, and limitations.
+4. Compare alternatives against the stated criteria.
+5. Produce a decision, recommendation, or explicit inconclusive result.
+6. Create a follow-up specification if implementation is approved.
+
+## Prohibited outcome
+
+Do not present prototype code as production-ready implementation without separate verification and delivery work.
+

package/skills/core/technology-discovery/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: technology-discovery
+description: Discover the project's languages, frameworks, tools, runtime, and validation commands from repository evidence before selecting technology-specific skills.
+---
+
+# Technology Discovery
+
+Run this skill before implementation when the stack is unknown, mixed, or likely to affect the solution.
+
+## Rules
+
+- Inspect repository evidence; do not infer technology from the user's wording alone.
+- Prefer manifests, lockfiles, build files, source layout, CI, and documented commands over directory names.
+- Treat a repository as polyglot when multiple production stacks are active.
+- Separate production technologies from test, tooling, generated, and example code.
+- Never install dependencies or execute arbitrary project code during discovery without authorization.
+
+## Evidence map
+
+| Evidence | Likely technology or tool |
+|---|---|
+| `package.json`, `tsconfig.json`, lockfiles | Node.js, TypeScript, frontend or backend framework |
+| `.sln`, `.csproj`, `global.json` | .NET / C# |
+| `pom.xml`, `build.gradle`, `build.gradle.kts`, `gradlew` | Java or Kotlin; Maven or Gradle |
+| `pyproject.toml`, `requirements*.txt`, `poetry.lock`, `uv.lock` | Python |
+| `go.mod`, `Cargo.toml`, `composer.json`, `Gemfile`, `Package.swift` | Go, Rust, PHP, Ruby, Swift |
+| `Dockerfile`, compose files, CI workflows | Runtime and delivery environment |
+| test configuration and scripts | Validation tools and project conventions |
+
+## Output
+
+Create `templates/technology-inventory.md` containing:
+
+- detected languages and versions;
+- frameworks and important libraries;
+- package/build/test/lint commands;
+- runtime and deployment clues;
+- active technology packs;
+- confidence and evidence for every conclusion;
+- unknowns that must be resolved before implementation.
+
+If the project is a monorepo, produce one inventory per application or package and a shared infrastructure section.
+

package/skills/practices/code-review/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: code-review
+description: Review a change for correctness, regressions, security, maintainability, and missing verification.
+---
+
+# Code Review
+
+Review the diff and relevant surrounding code, not only the changed lines.
+
+Check, in order:
+
+1. Intended behavior and acceptance criteria.
+2. Correctness and edge cases.
+3. Regression and compatibility risk.
+4. Error handling and security boundaries.
+5. Data integrity and concurrency.
+6. Tests and observability.
+7. Maintainability and unnecessary complexity.
+
+Report findings by severity with file, location, impact, and a concrete recommendation. If there are no findings, state what was reviewed and what was not verified.
+