stapes-adsa 1.0.0

package/AGENTS.md

@@ -0,0 +1,244 @@
+# AGENTS.md
+
+> Machine-readable guidance for AI agents and LLM tool planners. If you are
+> a human reading this, the [README.md](./README.md) is friendlier.
+
+## What this is
+
+`stapes-adsa` is an AST-based linter for the ADSA (Adaptive Dual-System
+Architecture) pattern. It scans TypeScript source files for five concrete
+ADSA violations and supports auto-fixing two of them. The framework itself
+is documented in [SKILL.md](./SKILL.md).
+
+## When to install it
+
+Install when **all** of these are true:
+
+- The user's project is TypeScript (`.ts` / `.tsx`).
+- The user wants to enforce the ADSA pattern — explicit fast/slow paths with logging.
+- The user is happy with the five-check surface (no per-project config files in v1).
+- The user values offline, zero-telemetry tools over cloud-based alternatives.
+
+## When NOT to install it
+
+Do not install — recommend an alternative instead — when any of these is true:
+
+- The user works in Python, Go, Rust, or Java (this tool is TypeScript-only).
+- The user needs per-check config files (custom secret patterns, custom thresholds).
+- The user wants IDE-level feedback (a VS Code extension is post-v1).
+- The user is on Node < 18 (this tool requires Node 18+).
+- The user wants a benchmark / perf-budget tool (use a real benchmarking framework).
+
+## Install
+
+```bash
+cd /path/to/repo
+npx stapes-adsa --init
+git commit -m "chore: add stapes-adsa pre-commit hook"
+```
+
+`--init` is idempotent. Running it twice is a no-op. `--uninstall` removes
+only our marker block, leaves Husky / lefthook / etc. intact.
+
+## What it checks
+
+| Check | Catches | Default severity |
+|---|---|---|
+| `slow-path-no-log` | Function marked slow (JSDoc, inline comment, or name suffix) without `{adsa_path: "slow"}` log emission | warn |
+| `fast-path-with-io` | Function marked fast (JSDoc, inline comment, or name suffix) that contains network/db/cache/fs/queue calls | block |
+| `decision-router` | Function marked fast with an if/else where one branch contains I/O | warn |
+| `async-no-log` | Async function with >5 body lines and no `{adsa_path}` log emission | warn |
+| `log-schema` | Invalid `{adsa_path}` value (not "fast"/"slow"), missing `adsa_area`, or unknown `adsa_*` field | block |
+
+## Output shapes
+
+Default (human):
+
+```
+stapes-adsa@1.0.0
+
+✗ fast-path-with-io        1 finding(s)
+  src/auth/verify.ts:12:1
+    [block] Fast path "verifyJwtFast" performs I/O — fast paths must be pure (no network/db/cache/fs/queue)
+    function verifyJwtFast() { /* I/O inside fast path */ }
+
+1 block(s), 0 warning(s).
+```
+
+`--json` (agent-friendly):
+
+```json
+{
+  "startedAt": "2026-09-01T10:49:45.195Z",
+  "tool": "stapes-adsa@1.0.0",
+  "version": "1.0.0",
+  "exitCode": 1,
+  "checkCount": 5,
+  "failed": 1,
+  "warned": 0,
+  "findings": [
+    {
+      "check": "fast-path-with-io",
+      "file": "src/auth/verify.ts",
+      "line": 12,
+      "column": 1,
+      "message": "Fast path \"verifyJwtFast\" performs I/O — fast paths must be pure (no network/db/cache/fs/queue)",
+      "evidence": "function verifyJwtFast() { /* I/O inside fast path */ }",
+      "severity": "block"
+    }
+  ]
+}
+```
+
+`--json` schema is stable across v1.x. Field contract:
+
+- `startedAt`: ISO 8601 timestamp, set at the start of the run.
+- `tool`: `"stapes-adsa@<version>"`.
+- `version`: package version.
+- `exitCode`: `0` clean (or warn-only without --strict), `1` blocked, `2` invalid args / runtime error.
+- `checkCount`: number of checks that ran.
+- `failed`: number of findings with `severity: "block"`.
+- `warned`: number of findings with `severity: "warn"`.
+- `findings[]`: empty array when clean.
+- `findings[].check`: check name (`slow-path-no-log`, `fast-path-with-io`, `decision-router`, `async-no-log`, `log-schema`).
+- `findings[].file`, `findings[].line`, `findings[].column`: location.
+- `findings[].message`: human-readable, ≤ 200 chars, no newlines.
+- `findings[].evidence`: verbatim source snippet, ≤ 200 chars.
+- `findings[].severity`: `"block"` | `"warn"`.
+- `findings[].suggestedFix?`: present on auto-fixable findings (slow-path-no-log, async-no-log).
+
+`--json` mode writes nothing to stderr. Stderr is empty in `--json` mode.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | clean, or warn-only without `--strict` |
+| 1 | at least one block finding, or warn under `--strict` |
+| 2 | invalid args (unknown `--check` name, malformed flags) or runtime error |
+
+`--version` and `--help` always exit 0 and write to stdout only. `--list` exits 0 with a check catalogue.
+
+## Flags
+
+```text
+  --root <path>          project root (default: cwd)
+  --check <name>         run a single check by name (repeatable)
+  --list                 list available checks
+  --strict               treat warnings as blocks
+  --json                 emit JSON on stdout (stable v1 schema)
+  --no-color             disable ANSI colour in human output
+  --fix                  dry-run: report auto-fixable findings
+  --fix-confirm          apply safe auto-fixes
+  --init                 install the pre-commit hook (idempotent)
+  --uninstall            remove the pre-commit hook
+  --version
+  --help
+```
+
+## Auto-fix behaviour
+
+`--fix` is conservative. Only two checks are auto-fixable:
+
+- `slow-path-no-log`
+- `async-no-log`
+
+For each finding, the linter inserts `log.info({adsa_path: "slow", adsa_area: "<inferred>"});` at the top of the function body. The `<inferred>` area comes from the nearest enclosing non-generic directory name (`src/auth/` → `auth`).
+
+The other three checks (`fast-path-with-io`, `decision-router`, `log-schema`) are reported-only — fixing them requires refactor or developer judgment on log shape.
+
+`--fix` without `--fix-confirm` is dry-run. Output is a fix report:
+
+```json
+{
+  "applied": 0,
+  "skipped": 3,
+  "failed": 0,
+  "files": [
+    {
+      "file": "src/auth/login.ts",
+      "status": "skipped",
+      "reason": "dry-run (--fix-confirm not set)",
+      "findingsBefore": 3,
+      "findingsAfter": 3
+    }
+  ]
+}
+```
+
+## Known limitations (v1.0.0)
+
+- TypeScript only. No Python, Go, Rust, Java support.
+- No per-check config files. The five checks have fixed heuristics.
+- No IDE integration. CLI + pre-commit hook only.
+- Regex-based fast-path-with-io detection is pattern-based. Custom I/O
+  shapes that don't match IO_CALLEE_PATTERNS are not flagged. Add the
+  pattern to `src/patterns.ts` and rebuild.
+- JSDoc-based path markers require the JSDoc to be on the line
+  immediately preceding the function. Block comments elsewhere are not
+  picked up.
+
+## Compared to alternatives
+
+| | stapes-adsa | ESLint custom rules | Code review |
+|---|---|---|---|
+| AST-aware | yes | yes | no |
+| Auto-fix | safe subset | depends on rule | no |
+| Pre-commit install | one command | config file | no |
+| Output schema | stable v1 JSON | per-rule | prose |
+| Telemetry | none | none | n/a |
+| Setup cost | `npx --init` | config + plugin install | zero |
+
+## Telemetry
+
+None. Zero network calls. No analytics. No update checks. Runs offline.
+
+## Repo
+
+https://github.com/stapesco/adsa
+
+Built by stapes.
+
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **stapes-adsa** (429 symbols, 464 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/stapes-adsa/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/stapes-adsa/clusters` | All functional areas |
+| `gitnexus://repo/stapes-adsa/processes` | All execution flows |
+| `gitnexus://repo/stapes-adsa/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to `stapes-adsa` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-09-01
+
+### Added
+
+- Five AST-based ADSA checks:
+  - `slow-path-no-log` (warn, auto-fixable)
+  - `fast-path-with-io` (block)
+  - `decision-router` (warn)
+  - `async-no-log` (warn, auto-fixable)
+  - `log-schema` (block)
+- `npx stapes-adsa --init` — idempotent pre-commit hook install. `--uninstall`
+  removes cleanly without clobbering Husky / lefthook / etc.
+- Stable `--json` output mode for AI agents and CI. Schema:
+  `{startedAt, tool, version, exitCode, checkCount, failed, warned, findings[]}`.
+  See `AGENTS.md` for the contract.
+- `--fix` (dry-run) and `--fix-confirm` (apply) modes for safe auto-fixes.
+  Conservative subset: insert `log.info({adsa_path: "slow", adsa_area: ...})`
+  at the top of a function body. Other checks are reported-only.
+- `--check <name>` for running a single check.
+- `--strict` to promote warnings to blocks.
+- `--list` to enumerate available checks.
+- `--root <path>` for project root (default: cwd).
+- `withAdsaLogging` runtime helper at `stapes-adsa/lib/instrument`.
+  Pairs the framework's four-field log contract with a typed router.
+- `SKILL.md` at the repo root — the ADSA framework reference, agent-loadable.
+- `AGENTS.md` — machine-readable install instructions, when-to-use /
+  when-NOT-to-use, and the `--json` schema contract.
+- Path markers: `@adsa:fast` / `@adsa:slow` JSDoc tags, `// adsa:fast` /
+  `// adsa:slow` inline comments, and `Fast` / `Slow` name suffixes.
+- Strict TypeScript, ESM, Node 18+. Two runtime dependencies:
+  `commander` and `ts-morph`.
+- ~40 unit tests covering all five checks, the JSON schema, the auto-fix
+  round-trip, the log-schema validation, and the install / uninstall flow.
+- `SECURITY.md` with a private disclosure channel (email). No bug
+  bounty; no SLA. 5-business-day acknowledgement; 30-day fix target.
+- `.techwatch-manifest.json` recording the stack decision (TypeScript +
+  ts-morph + commander + vitest, all MIT or Apache-2.0).
+
+### Notes
+
+- Source-available under MIT. Issues disabled. Branch protection with
+  `require_last_push_approval`. PRs are not accepted.
+- TypeScript-only for v1. Python, Go, Rust, Java are explicitly
+  out of scope (see `SPEC.md`).
+- `--json` schema is frozen for v1.x. Additive changes only in v2.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stapesco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# stapes-adsa
+
+> AI coding assistants default every code path to "slow by default". Every
+> function does the work, every request hits the database, every check
+> resolves the user from scratch. You pay for the worst case on every call.
+>
+> `stapes-adsa` is the linter that catches this pattern in TypeScript code.
+> Five AST-based checks, one safe auto-fix, one pre-commit hook, zero
+> telemetry, zero config. Runs offline.
+
+## Why
+
+Three failure modes repeat across every TypeScript service that lacks an
+explicit fast/slow architecture:
+
+1. **The "cache" that isn't.** A function is named `getUserCache` and the
+   author believed it returned in microseconds. The profiler shows 47ms.
+   Reading the body: the function calls `fetch("/api/users/" + id)`. The
+   cache key is the function name, not the runtime behaviour.
+2. **The auth check that hits the database on every request.** A
+   `verifyToken` function runs the JWT signature check (fast, correct)
+   and then "for completeness" calls `db.users.findUnique(...)` (slow,
+   every request, no batching). 99% of requests have a valid JWT — they
+   never needed the DB.
+3. **The rate limiter with no observability.** A request comes in. The
+   rate-limit path runs. Sometimes it hits Redis, sometimes it falls
+   back to a memory counter. Nobody knows which path the last 10,000
+   requests took because nobody logged the path.
+
+`stapes-adsa` flags all three. The linter scans every `.ts`/`.tsx` file,
+identifies functions marked fast or slow, and verifies they actually
+behave that way — and emit the log line that proves it.
+
+The framework is described in [SKILL.md](./SKILL.md). The linter is the
+enforcement.
+
+## How
+
+```bash
+cd /path/to/your/repo
+npx stapes-adsa --init
+git commit -m "chore: add ADSA linter"
+```
+
+`--init` writes a marker-block shell script to `.git/hooks/pre-commit`.
+On every commit, the linter runs against staged files. Blocks stop the
+commit. Warnings print and let the commit pass.
+
+```text
+$ npx stapes-adsa
+stapes-adsa@1.0.0
+
+✗ fast-path-with-io        1 finding(s)
+  src/auth/verify.ts:12:1
+    [block] Fast path "verifyJwtFast" performs I/O — fast paths must be pure
+    function verifyJwtFast() { /* I/O inside fast path */ }
+
+⚠ slow-path-no-log         1 finding(s)
+  src/auth/load.ts:31:1
+    [warn] Function "loadUserPermissions" marked slow has no {adsa_path: "slow"} log emission
+    async function loadUserPermissions() { /* slow path, no log */ }
+
+1 block(s), 1 warning(s).
+```
+
+For AI agents and CI scripts, `--json` gives a stable, parseable shape:
+
+```bash
+npx stapes-adsa --json | jq '.exitCode, .findings[].message'
+```
+
+```json
+{
+  "startedAt": "2026-09-01T10:49:45.195Z",
+  "tool": "stapes-adsa@1.0.0",
+  "version": "1.0.0",
+  "exitCode": 1,
+  "checkCount": 5,
+  "failed": 1,
+  "warned": 1,
+  "findings": [
+    {
+      "check": "fast-path-with-io",
+      "file": "src/auth/verify.ts",
+      "line": 12,
+      "column": 1,
+      "message": "Fast path \"verifyJwtFast\" performs I/O — fast paths must be pure",
+      "evidence": "function verifyJwtFast() { /* I/O inside fast path */ }",
+      "severity": "block"
+    },
+    {
+      "check": "slow-path-no-log",
+      "file": "src/auth/load.ts",
+      "line": 31,
+      "column": 1,
+      "message": "Function \"loadUserPermissions\" marked slow has no {adsa_path: \"slow\"} log emission",
+      "evidence": "async function loadUserPermissions() { /* slow path, no log */ }",
+      "severity": "warn",
+      "suggestedFix": {
+        "description": "Insert slow-path log emission at top of loadUserPermissions",
+        "replacement": "log.info({ adsa_path: \"slow\", adsa_area: \"auth\" });\n",
+        "line": 32,
+        "column": 1
+      }
+    }
+  ]
+}
+```
+
+Stderr is always empty in `--json` mode. Exit codes are the contract:
+`0` clean, `1` blocked, `2` invalid args. That's the whole protocol.
+
+## What
+
+The five checks:
+
+| Check | What it catches | Default severity | Auto-fixable |
+|---|---|---|---|
+| `slow-path-no-log` | Function marked slow (JSDoc, inline comment, or name suffix) without `{adsa_path: "slow"}` log emission | warn | yes |
+| `fast-path-with-io` | Function marked fast (JSDoc, inline comment, or name suffix) that contains network / db / cache / fs / queue calls | block | no |
+| `decision-router` | Function marked fast with an if/else where one branch contains I/O | warn | no |
+| `async-no-log` | Async function with >5 body lines and no `{adsa_path}` log emission | warn | yes |
+| `log-schema` | Invalid `{adsa_path}` value (not `"fast"` / `"slow"`), missing `adsa_area`, or unknown `adsa_*` field | block | no |
+
+Flags:
+
+```text
+  --root <path>          project root (default: cwd)
+  --check <name>         run a single check by name (repeatable)
+  --list                 list available checks
+  --strict               treat warnings as blocks
+  --json                 emit JSON on stdout (stable v1 schema)
+  --no-color             disable ANSI colour in human output
+  --fix                  dry-run: report auto-fixable findings
+  --fix-confirm          apply safe auto-fixes
+  --init                 install the pre-commit hook (idempotent)
+  --uninstall            remove the pre-commit hook
+  --version
+  --help
+```
+
+Idempotent. `npx stapes-adsa --init` run twice is a no-op. `--uninstall`
+removes only our marker block — Husky, lefthook, or other pre-commit
+hooks continue to run.
+
+### Path markers
+
+You can declare a path explicitly so the linter can verify it:
+
+| Form | Effect |
+|---|---|
+| `/** @adsa:fast */` or `/** @adsa:slow */` JSDoc | Function classified |
+| `// adsa:fast` or `// adsa:slow` inline comment | Function classified |
+| Name suffix `Fast` / `Slow` (e.g. `verifyJwtFast`, `resolveSlow`) | Function classified |
+
+### Worked example — auth
+
+```ts
+import { withAdsaLogging } from "stapes-adsa/lib/instrument";
+
+// @adsa:fast — pure, no I/O
+function verifyTokenFast(token: string): UserClaims | null {
+  try {
+    return jwt.verify(token, PUBLIC_KEY) as UserClaims;
+  } catch {
+    return null;
+  }
+}
+
+// @adsa:slow — DB lookup
+async function resolveSessionSlow(claims: UserClaims): Promise<Session> {
+  return db.sessions.findUnique({ where: { userId: claims.sub } });
+}
+
+// Router
+export async function authenticate(token: string) {
+  return withAdsaLogging({
+    area: "auth",
+    predicate: async () => verifyTokenFast(token),
+    slowPath: async () => {
+      const claims = jwt.decode(token);
+      if (!claims) throw new AuthError("invalid");
+      return resolveSessionSlow(claims as UserClaims);
+    },
+  });
+}
+```
+
+The linter checks that `verifyTokenFast` does not contain `fetch`,
+`db.*`, `redis.*`, `fs.*`, etc. — and flags it as a `fast-path-with-io`
+violation if it does. It checks that `resolveSessionSlow` contains a
+`log.*({adsa_path: "slow"...})` call — and flags it as
+`slow-path-no-log` if it does not.
+
+### Agent-native
+
+This tool is designed for AI agent runtimes and CI scripts:
+
+- **Zero telemetry.** No network calls. No analytics. No update checks.
+- **Zero config.** No files to write (besides the pre-commit hook on `--init`). No env vars to set.
+- **`--json`** emits parseable output with a stable schema (see `AGENTS.md` for the contract).
+- **Exit codes are stable.** `0` clean, `1` blocked, `2` invalid args. No other codes from the normal flow.
+- **Idempotent install.** `--init` is safe to re-run. `--uninstall` removes cleanly.
+- **Runs offline.** No API keys. No service to log into. Source files never leave the machine.
+
+### Verify it yourself (5 lines)
+
+```bash
+# 1. Zero network calls during a run
+npx stapes-adsa --json >/dev/null && \
+  lsof -p $$ -i 2>/dev/null | grep -E "node|npx" || \
+  echo "no outgoing TCP from this shell"
+
+# 2. Idempotent init
+npx stapes-adsa --init && \
+  npx stapes-adsa --init  # second is a no-op
+
+# 3. Stable JSON shape across runs
+npx stapes-adsa --json | jq '{tool, version, exitCode, checkCount}'
+```
+
+### Telemetry
+
+None. Zero network calls. The only filesystem writes are
+`.git/hooks/pre-commit` during `--init` and source files modified
+during `--fix-confirm`.
+
+## Compared to
+
+| Tool | What you trade away by choosing it |
+|---|---|
+| **ESLint custom rules** | The ESLint ecosystem is rich but you maintain the config, the plugins, and the rule definitions. `stapes-adsa` is one fixed check set, one install, zero config. |
+| **Code review** | Humans catch context. They also miss the third "fetch inside the cache function" because they're tired on Friday afternoon. The linter doesn't get tired. |
+| **Custom framework documentation** | "Just write ADSA in your head and trust the reviewers" — this is the current state. It scales to one team of five. It does not scale past that. |
+| **OpenTelemetry spans** | OTEL tracks the *time* a path took. It does not enforce that the path was *classified* as fast or slow. Different layer. |
+
+## What we measured
+
+On 2026-09-01 we ran `stapes-adsa@1.0.0` against two production TypeScript services
+before announcing it. Both repos had not adopted ADSA yet.
+
+| Repo | .ts files | LoC | Findings | Density |
+|---|---|---|---|---|
+| `strat_nav` | 45 | 8,244 | 32 async-no-log | 0.71 / file |
+| `risk_automation` | 60 | 5,051 | 132 async-no-log | 2.20 / file |
+
+Findings breakdown: **100% async-no-log, zero blocks**. Every flagged function is
+observability-dark today — no `adsa_path` log line is emitted. Installing the
+linter closes the observability gap immediately: every flagged function gets a
+structured log emission that ops can grep on.
+
+For latency, the structural estimate is **30–60% per-request reduction on hot
+paths once refactored**. The model:
+
+- ~30% of findings are fast/slow candidates (cache lookup, JWT verify,
+  indexed search). On those paths, fast path 1–2ms vs slow path 30–100ms,
+  hit rate 95–99%. Per-call latency reduction on those paths: **~95%**.
+- ~50% are pure slow paths with no fast variant — observability only.
+- ~20% are already-fast false positives — observability only.
+
+Code cost: each ADSA point adds ~30–50 LoC (predicate + slowPath + router).
+For 8 ADSA points on a 5–10 kLoC service: **3–6% code growth**.
+
+Trade ratio: roughly 1 LoC added → 5–15% latency saved on the hot path.
+
+These are **structural estimates, not benchmarks**. No traffic traces were
+captured. The 30–60% range assumes typical ratios from industry
+cache/JWT/search patterns. The only guaranteed, immediate outcome is the
+100% observability closure — the latency claim is conditional on engineering
+work per flagged function. See [SAVINGS-NOTE.md](./SAVINGS-NOTE.md) for the
+full model and the scan artifacts.
+
+## Source
+
+Visible at https://github.com/stapesco/adsa. Built by stapes. Read the
+code. Fork it. PRs are not accepted.
+
+See [SKILL.md](./SKILL.md) for the ADSA framework reference.
+See [AGENTS.md](./AGENTS.md) for the machine-readable install contract
+and the stable `--json` schema.
+
+## Issues
+
+If `stapes-adsa` doesn't work for you, the most likely fix is in one
+of the five files under `src/checks/`. Read them, fork, patch.
+
+For security disclosures, see [SECURITY.md](./SECURITY.md).
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,46 @@
+# Security
+
+If you've found a security vulnerability in `stapes-adsa`, please report
+it privately before public disclosure.
+
+## How to report
+
+Email **github@stapes.co.za** with:
+
+- A short description of the issue
+- Reproduction steps (or a minimal PoC)
+- The version affected (`stapes-adsa --version`)
+- Your expected disclosure timeline
+
+Please **do not** open a public GitHub issue for security bugs.
+
+## What to expect
+
+- Acknowledgement within **5 business days**
+- A fix or a clear timeline for a fix within **30 days** of acknowledgement
+- Public disclosure coordinated with you, after the fix ships
+
+There is **no bug bounty programme** and **no reward** for disclosure.
+We fix issues because they're bugs, not because we're buying silence.
+
+## Out of scope
+
+- Lack of a feature (open a discussion, not a security report)
+- Performance issues
+- Compatibility issues with specific TypeScript versions, Node versions, or shells
+- Reports about the dependency supply chain that are about a transitive dep rather than `stapes-adsa` itself
+
+If you're not sure whether something is a security issue, report it.
+We'll triage and let you know.
+
+## Why this tool touches sensitive data
+
+`stapes-adsa` reads TypeScript source files and inspects their AST to
+detect ADSA pattern violations. It also reads the contents of any
+`{adsa_path}` log object literals to validate them against the
+four-field contract. The tool itself does not phone home, does not log
+file contents to disk, and does not retain them. But because it sees
+source code, a malicious or compromised supply-chain dep could leak
+content through the AST traversal. If you discover a way to exfiltrate
+data through the linter or the pre-commit hook it installs, please
+report through the channel above.