@xenos1996/usat 1.0.0

package/docs/rule-packs.md

@@ -0,0 +1,278 @@
+# Writing rule packs
+
+A rule pack is one YAML file. Register it in `rules/index.yaml`, and USAT decides at
+audit time whether it applies.
+
+```yaml
+id: stacks/mobile
+title: Mobile (iOS / Android / Cross-platform)
+section: S15
+section_title: Platform-Specific
+description: 'Activated when iOS, Android, React Native, Expo, or Flutter is detected.'
+version: '1.0'
+skip_when: # skip the WHOLE pack when true
+  all:
+    - { fact: 'platform:mobile', op: 'absent' }
+    - { fact: 'platform:ios', op: 'absent' }
+    - { fact: 'platform:android', op: 'absent' }
+provides: ['platform:mobile'] # facts this pack asserts
+rules:
+  - id: MOB-001
+    title: Crash reporting is integrated
+    section: S15
+    section_title: Platform-Specific
+    severity: HIGH
+    class: operations
+    applies_when: { fact: 'maturity:beta' } # optional per-rule gating
+    depths: [standard, deep] # optional
+    check:
+      kind: grep_present
+      pattern: '(Crashlytics|Sentry|BugSnag|Instabug)'
+      include: ['**/*.{ts,tsx,js,json,plist,xml,gradle,swift,kt}']
+      exclude: ['**/node_modules/**', '**/Pods/**']
+      flags: i
+    why: "On mobile you cannot watch the user's screen."
+    evidence: 'Where tokens/PII live: Keychain/Keystore, not AsyncStorage.'
+    remediation: 'Add Crashlytics or Sentry with dSYM upload.'
+    references: ['OWASP-MASVS-STORAGE-2']
+```
+
+## Pack fields
+
+| Field           | Required | Notes                                                 |
+| --------------- | -------- | ----------------------------------------------------- |
+| `id`            | ✅       | Convention: `core/<name>` or `stacks/<name>`          |
+| `title`         | ✅       |                                                       |
+| `section`       |          | Default section for rules that omit one               |
+| `section_title` |          |                                                       |
+| `description`   |          | Shown by `usat rules`                                 |
+| `skip_when`     |          | Predicate; pack is skipped when **true**              |
+| `provides`      |          | Facts to add when the pack applies — lets packs chain |
+| `rules`         | ✅       |                                                       |
+
+## Rule fields
+
+| Field          | Required | Notes                                                    |
+| -------------- | -------- | -------------------------------------------------------- |
+| `id`           | ✅       | Convention: `<PREFIX>-<NNN>`, e.g. `SEC-007`             |
+| `title`        | ✅       | Imperative and specific: "Tokens and sessions expire"    |
+| `section`      | ✅       | `S1`…`S16`                                               |
+| `severity`     | ✅       | `CRITICAL` \| `HIGH` \| `MEDIUM` \| `LOW` \| `FUTURE`    |
+| `class`        | ✅       | See below                                                |
+| `check`        | ✅       | See below                                                |
+| `weight`       |          | Overrides the severity default                           |
+| `applies_when` |          | Predicate over detected facts                            |
+| `depths`       |          | `[quick]` / `[standard]` / `[deep]`; omit for all        |
+| `why`          |          | Shown in the report and the judgement queue              |
+| `evidence`     |          | **Required for `manual` checks** — what proof looks like |
+| `remediation`  |          | The fix                                                  |
+| `references`   |          | Standard IDs: `CWE-89`, `ASVS-5.3.4`, `OWASP-LLM01:2026` |
+| `tags`         |          | Free-form                                                |
+
+### `class` drives dampening
+
+`security` · `supply-chain` · `correctness` · `maintainability` · `operations` ·
+`performance` · `compliance` · `documentation` · `style`
+
+---
+
+## Check kinds
+
+### `manual` — needs a human or an agent
+
+```yaml
+check: { kind: manual }
+```
+
+Produces ❓ NEEDS REVIEW and lands in the judgement queue. Always pair with
+`evidence:` — it is the prompt the reviewer works from.
+
+### `file_exists` / `file_absent`
+
+```yaml
+check: { kind: file_exists, files: ['.gitignore'] }
+check: { kind: file_absent, files: ['.env', '*.pem'] }
+```
+
+`file_absent` fails with locations when something is found.
+
+### `any_file`
+
+```yaml
+check:
+  kind: any_file
+  patterns: ['README.md', 'readme.md', 'README.rst']
+```
+
+### `grep_present` / `grep_absent`
+
+```yaml
+check:
+  kind: grep_present # PASS when found
+  pattern: '(zod|joi|pydantic|class-validator)'
+  include: ['**/*.{ts,tsx,js,jsx,py,go}']
+  exclude: ['**/*.test.*', '**/node_modules/**']
+  flags: i # i = case-insensitive
+```
+
+`grep_absent` inverts it: any hit is a FAIL **with file:line locations** — this is
+the workhorse for "no hardcoded secrets", "no `shell=True`", "no `http://`".
+
+### `grep_wrong` / `grep_deprecated`
+
+```yaml
+check:
+  kind: grep_wrong # hits → ⚠️ WRONG
+  pattern: 'catch\s*\(\s*\w*\s*\)\s*\{\s*\}'
+
+check:
+  kind: grep_deprecated # hits → 💀 DEPRECATED
+  pattern: 'new Buffer\s*\('
+```
+
+Use `grep_wrong` for "present but done incorrectly" — the status auditors most often
+miss (Rule 9).
+
+### `tracked_present` / `tracked_absent`
+
+Asks **git** what is tracked, not what is on disk. Use for committed build output,
+committed `.env`, committed model weights — anything whose presence in the working
+tree is normal but whose presence in git is a bug.
+
+```yaml
+check:
+  kind: tracked_absent
+  patterns: ['dist/**', 'node_modules/**', '.env', '**/*.pt']
+```
+
+### `count_min`
+
+```yaml
+check:
+  kind: count_min
+  patterns: ['**/*.test.{ts,tsx}', '**/test_*.py']
+  min: 5
+```
+
+### `file_lines_max`
+
+```yaml
+check:
+  kind: file_lines_max
+  patterns: ['src/**/*.ts']
+  max_lines: 800
+```
+
+Any hit is ⚠️ WRONG with the line count. A cheap proxy for god objects.
+
+### `json_path`
+
+```yaml
+check:
+  kind: json_path
+  file: 'package.json'
+  path: 'engines.node'
+  equals: '>=20'
+```
+
+`equals` omitted ⇒ PASS when the key is merely set. Works on JSON (JSONC tolerated).
+
+### `command`
+
+```yaml
+check:
+  kind: command
+  run: '! npm audit --production --audit-level=high | grep -qiE "critical|high"'
+  expect_exit: 0
+```
+
+**Skipped unless `--allow-commands`** — reported as ❓ NEEDS REVIEW otherwise.
+USAT never shells out without being asked.
+
+### `info`
+
+Context only, never scored. Useful for explaining a section to a reader.
+
+---
+
+## Predicates
+
+```yaml
+applies_when: { fact: 'has:database' }
+
+applies_when:
+  any:
+    - { fact: 'lang:typescript' }
+    - { fact: 'lang:javascript' }
+
+applies_when:
+  all:
+    - { fact: 'maturity:production' }
+    - { not: { fact: 'project:library' } }
+
+# Numeric facts use metric:
+applies_when: { fact: 'metric:contributors', op: 'gt', value: 2 }
+applies_when: { fact: 'metric:tags', op: 'exists' }
+```
+
+Operators: `exists` (default) · `absent` · `eq` · `neq` · `in` · `includes` · `gt` · `lt` · `matches`
+
+Combinators: `all` · `any` · `not`
+
+### Fail-closed contracts (the engine does not guess)
+
+Malformed input warns at load time and evaluates conservatively — see
+ADR-0009. What to know as an author:
+
+- `in` / `includes` compare **metric** values against the list. On flag
+  facts they are always false: presence alone never satisfies a value
+  comparison.
+- `matches` compiles `value` as a regex; an invalid regex warns and the
+  predicate is false. Unknown operators and unknown predicate keys behave
+  the same way (rule skipped, warning on stderr).
+- An empty grep `pattern` drops the rule with a warning — `new RegExp('')`
+  matches every line, so a missing pattern would otherwise FAIL (or PASS)
+  the whole repo.
+- Duplicate rule IDs across packs: first definition wins, later ones warn.
+- Override `severity` must be on the ladder and `weight` a finite number
+  ≥ 0, or the override is ignored with a warning. Run `node
+scripts/check-docs.mjs`-adjacent `usat rules` after editing: the shipped
+  packs must load with **zero warnings** (enforced by `tests/e2e.test.ts`).
+
+---
+
+## Available facts
+
+Run `usat detect .` on any project to see them. Namespaces:
+
+`lang:*` `pm:*` `fw:*` `project:*` `platform:*` `db:*` `orm:*` `auth:*` `test:*`
+`ci:*` `infra:*` `api:*` `obs:*` `ai:*` `has:*` `doc:*` `practice:*` `maturity:*`
+
+Metrics (use `metric:<name>`): `commits`, `contributors`, `tags`, `branches`,
+`files`, `daysSinceLastCommit`.
+
+Full catalogue: [detectors.md](detectors.md).
+
+---
+
+## Style guide for rule authors
+
+1. **Title = the desired state**, not the defect. "Tokens and sessions expire", not "Missing token expiry".
+2. **`why` earns the rule its place.** If you cannot say why in one sentence, cut the rule.
+3. **`remediation` must be actionable.** "Improve security" is not a fix. "Set `SameSite=Lax` and require a CSRF token" is.
+4. **`evidence` is the deliverable for manual checks.** It tells the reviewer exactly what to produce.
+5. **Exclude tests and docs from security greps.** A rule that fires on its own documentation is a rule people will disable.
+6. **Prefer `grep_wrong` over `grep_absent`** when the _pattern_ is fine but a specific usage is not.
+7. **Cite the standard.** `CWE-89`, `ASVS-5.3.4`, `SLSA-Build-L2`, `OWASP-LLM01:2026`.
+8. **Severity = worst realistic outcome**, not typical. Dampening handles context; the rule should not.
+
+## Testing your pack
+
+```bash
+usat rules --section S15        # did it load?
+usat explain MOB-001            # did it parse as intended?
+usat audit . --include stacks/mobile --depth deep
+```
+
+A pack with a YAML syntax error is skipped with a warning on stderr — the audit never
+crashes because of a bad rule file.

package/docs/standards-mapping.md

@@ -0,0 +1,171 @@
+# Standards mapping — how USAT compares to the state of the art
+
+> _USAT did not invent most of these checks. It reorganised them so one tool can
+> apply them to any project, at any stage, without a certification budget._
+
+## The short version
+
+| Framework                               | What it is                                                                                                                                                      | What USAT takes                                                                             | What USAT adds                                                                                          |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| **OWASP ASVS 5.0**                      | ~350 verification requirements across 17 chapters, levels L1–L3 [1](https://quality.arc42.org/standards/owasp-asvs)                                             | The requirement set behind most `SEC-*` rules; ASVS IDs in `references`                     | Executable versions of the mechanically-checkable subset; level selection replaced by maturity profiles |
+| **OpenSSF Scorecard**                   | 18 automated checks, 0–10, run against public repos [1](https://rywalker.com/research/openssf-scorecard)                                                        | The shape of S3 and S8; score-per-check                                                     | Runs on private repos and monorepos; mixes in code-level checks; adds the other 15 sections             |
+| **NIST SSDF (SP 800-218)**              | Secure-development practice outcomes                                                                                                                            | Practice-level outcomes: protect, produce well-secured software, respond to vulnerabilities | Concrete evidence requirements per outcome                                                              |
+| **SLSA v1.2**                           | Build L0–L3 plus an approved Source track (Nov 2025) [1](https://rywalker.com/research/slsa)                                                                    | Provenance, attestation, and source-integrity requirements                                  | Progressive rules (SBOM now, attestation at production) rather than a level you claim                   |
+| **OWASP LLM Top 10 (2026)**             | LLM01–LLM10 for LLM applications [1](https://www.cybersaint.io/cybersecurity-frameworks-and-standards/glossary/what-is-the-owasp-top-10-for-llm-and-agentic-ai) | The entire S14 section                                                                      | Executable detection of AI stacks so the section self-activates                                         |
+| **OWASP Agentic AI Top 10 (ASI, 2026)** | ASI01–ASI10 for agent systems [2](https://www.trydeepteam.com/docs/frameworks-owasp-top-10-for-agentic-applications)                                            | Excessive agency, tool misuse, memory poisoning, inter-agent trust                          | Rules for `AGENTS.md`/`CLAUDE.md` as executable-ish instructions                                        |
+| **CII Best Practices**                  | Open-source project maturity badge                                                                                                                              | README/LICENSE/SECURITY/CONTRIBUTING baseline                                               | Automated, no self-assessment questionnaire                                                             |
+| **ISO/IEC 5055**                        | Automated code-quality measurement (security, reliability, performance, maintainability)                                                                        | The four quality characteristics behind S4/S5                                               | Free, YAML, and diffable                                                                                |
+| **WCAG 2.2 AA**                         | Accessibility success criteria                                                                                                                                  | S13 checks                                                                                  | Same criteria, expressed as things a reviewer can verify in ten minutes                                 |
+| **EU CRA**                              | Cyber-resilience obligations for products with digital elements                                                                                                 | SBOM, vulnerability handling, provenance expectations                                       | A roadmap toward the obligations, not an audit                                                          |
+| **OWASP SAMM**                          | Organisational assurance programme                                                                                                                              | Maturity-by-dimension thinking                                                              | Applies to a repository, not an org                                                                     |
+
+---
+
+## Where USAT differs from the field
+
+### 1 · It is stage-aware; they are not
+
+ASVS asks you to pick L1/L2/L3 _before_ you start [2](https://www.securecodinghub.com/blog/owasp-asvs-developers-complete-guide).
+Scorecard gives an absolute 0–10. Neither asks "how old is this project, and does
+that matter?"
+
+USAT detects the stage and dampens severity accordingly — while holding a hard floor
+on CRITICAL. [maturity-profiles.md](maturity-profiles.md)
+
+### 2 · It is agent-executable, not just human-readable
+
+Every framework above is a document a human interprets. USAT ships:
+
+- `rules/` — machine-readable versions of the same checks
+- a deterministic engine that settles ~70% of them
+- a **judgement queue** that tells an agent or reviewer exactly what evidence to produce
+
+That split is the whole design. An LLM should not be asked to grep for `eval(`; it
+should be asked whether authorisation is enforced per resource.
+
+### 3 · It separates "absent" from "wrong"
+
+Every framework above has a checkbox. None distinguishes 🚫 MISSING from ⚠️ WRONG —
+yet wrong is worse, because it looks finished. USAT gives WRONG its own status, its
+own check kind (`grep_wrong`), and a score of 0.15 rather than 0.00.
+
+### 4 · It reports confidence alongside score
+
+A 90/100 where only 40% of applicable rules could be verified is not a 90/100. USAT
+prints confidence next to every dimension and marks unverifiable sections
+_"— not verified"_ instead of silently awarding 10/10.
+
+### 5 · It is diffable
+
+Every report embeds a machine-readable trailer so `usat diff` turns the next audit
+into a progress report: fixed, regressed, newly applicable, net movement. None of the
+frameworks above give you a first-class way to show you improved.
+
+### 6 · It covers the AI era as a first-class section
+
+S14 is mapped to the OWASP LLM Top 10 (2026) and the OWASP Agentic AI Top 10 (ASI, 2026) — including risks that did not exist when the other frameworks were written:
+excessive agency, unbounded consumption, RAG tenant leakage, memory/context poisoning,
+and the fact that `AGENTS.md` is executable-ish instruction that commits like code.
+
+---
+
+## Detailed mapping
+
+### USAT section → standards
+
+| USAT                  | ASVS 5.0              | SSDF            | SLSA                | Scorecard                                                                                                       | Other                                                                    |
+| --------------------- | --------------------- | --------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| S1 Repository         | —                     | PO.3, PS.1      | Source L1–L2        | Binary-Artifacts, License, Security-Policy                                                                      | CII                                                                      |
+| S2 Security           | V2–V14 (all chapters) | PW.1–PW.8, RV.1 | —                   | —                                                                                                               | CWE, OWASP Top 10                                                        |
+| S3 Supply Chain       | V14.1, V14.2          | PS.3, PO.3      | Build L1–L3, Source | Pinned-Dependencies, Vulnerabilities, Dangerous-Workflow, Token-Permissions, Signed-Releases, Branch-Protection | CRA Annex I                                                              |
+| S4 Architecture       | V1, V4                | PW.1            | —                   | —                                                                                                               | ISO 5055 Maintainability                                                 |
+| S5 Code Quality       | V5, V7                | PW.7, PW.8      | —                   | —                                                                                                               | ISO 5055 Reliability                                                     |
+| S6 Data               | V8, V5.3              | PW.4            | —                   | —                                                                                                               | GDPR Art. 32                                                             |
+| S7 Testing            | V1.1, V4.2            | RV.1.1, PW.8    | —                   | CI-Tests, Fuzzing                                                                                               | —                                                                        |
+| S8 CI/CD & Infra      | V14.1                 | PO.5, RV.3      | Build L2            | CI-Tests, Branch-Protection                                                                                     | DORA                                                                     |
+| S9 Release            | V1.14                 | PO.5, RV.2      | Build L2, Source L2 | Signed-Releases                                                                                                 | SemVer                                                                   |
+| S10 Dependencies      | V14.2                 | PW.4, RV.1.1    | —                   | Vulnerabilities, Dependency-Update-Tool, Maintained                                                             | SPDX, Criticality Score                                                  |
+| S11 Performance       | V13                   | —               | —                   | —                                                                                                               | ISO 5055 Performance                                                     |
+| S12 Documentation     | —                     | PS.1, PW.1      | —                   | —                                                                                                               | CII                                                                      |
+| S13 A11y & Compliance | V14.4 (partly)        | —               | —                   | —                                                                                                               | WCAG 2.2 AA, GDPR, CCPA, PCI-DSS 4.0                                     |
+| S14 AI / LLM          | —                     | —               | —                   | —                                                                                                               | OWASP LLM Top 10 (2026), OWASP ASI Top 10 (2026), NIST AI RMF, EU AI Act |
+| S15 Platform          | V-per-stack           | —               | —                   | —                                                                                                               | MASVS, CIS Docker/K8s, SCWE                                              |
+| S16 Future            | —                     | —               | —                   | —                                                                                                               | endoflife.date, FinOps                                                   |
+
+### Representative rule → control
+
+| Rule                                        | Control                                                 |
+| ------------------------------------------- | ------------------------------------------------------- |
+| `SEC-001` No hardcoded credentials          | ASVS 2.10.4 · CWE-798 · OWASP A02:2021                  |
+| `SEC-005` SQL not built by concatenation    | ASVS 5.3.4 · CWE-89 · OWASP A03:2021                    |
+| `SEC-011` Modern adaptive password hash     | ASVS 2.4.1 · CWE-916                                    |
+| `SEC-025` Adaptive hash present where auth  | ASVS 2.4.1 · CWE-916                                    |
+| `SEC-015` Authorization per request         | ASVS 4.2.1 · CWE-639 · OWASP A01:2021                   |
+| `SEC-013` No `alg:none`                     | ASVS 3.2.3 · CWE-347                                    |
+| `SUP-001` Lockfile committed                | OpenSSF Pinned-Dependencies · SSDF PS.3.2 · SLSA Source |
+| `SUP-005` Dependency scanning in CI         | OpenSSF Vulnerabilities · SSDF RV.1.1                   |
+| `SUP-008` No workflow script injection      | OpenSSF Dangerous-Workflow · CWE-94                     |
+| `SUP-009` Least-privilege token permissions | OpenSSF Token-Permissions · SLSA Build L2               |
+| `SUP-012` Default branch protected          | OpenSSF Branch-Protection · SLSA Source L2 · SSDF PO.2  |
+| `SUP-014` SBOM published                    | SLSA · SSDF PS.3.2 · EU CRA Annex I                     |
+| `SUP-015` Provenance attestation            | SLSA Build L2 (v1.2)                                    |
+| `TEST-002` Tests run in CI on PRs           | OpenSSF CI-Tests · SSDF RV.1.1                          |
+| `CICD-004` Rollback rehearsed               | DORA time-to-restore · SSDF RV.3                        |
+| `CICD-010` Backups **and** tested restores  | SSDF RV.3 · CIS Control 11                              |
+| `CTNR-001` Container not running as root    | CIS Docker 4.1 · CWE-250                                |
+| `IAC-001` No public buckets / `0.0.0.0/0`   | CIS AWS 2.1.5 · CWE-284                                 |
+| `SOLID-001` Reentrancy protection           | SWC-107 · Consensys best practices                      |
+| `AI-001` Prompt injection                   | OWASP LLM01:2026 · ASI01:2026                           |
+| `AI-003` Least-privilege agents             | OWASP LLM03:2026 · ASI02/ASI03:2026                     |
+| `AI-005` Bounded consumption                | OWASP LLM06:2026 · ASI08:2026                           |
+| `AI-007` RAG tenant isolation               | OWASP LLM09:2026 · ASI06:2026                           |
+| `COMP-001` Keyboard accessibility           | WCAG 2.1.1 · EN 301 549                                 |
+| `COMP-007` Data subject rights              | GDPR Art. 15/17 · CCPA                                  |
+
+---
+
+## Deliberate gaps
+
+Things USAT intentionally does **not** do. An audit tool that oversells is worse than
+none.
+
+| Not done                     | Why                                                | Do this instead                                                |
+| ---------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
+| **Penetration testing**      | No dynamic analysis, no fuzzing, no exploit chains | OWASP ASVS L2/L3 assessment, a pentest                         |
+| **Deep SAST**                | Requires whole-program analysis                    | CodeQL, Semgrep, Snyk Code — USAT checks they are _configured_ |
+| **CVE lookup**               | Needs network + advisory databases                 | `npm audit`, `osv-scanner`, `trivy`, Dependabot                |
+| **Compliance certification** | Only an accredited auditor certifies               | Use USAT as the evidence checklist, then certify               |
+| **Runtime/DAST**             | Nothing is executed                                | OWASP ZAP, Burp, your staging environment                      |
+| **Formal verification**      | Out of scope for a checklist                       | Certora, Halmos, Kani                                          |
+| **Org-level maturity**       | USAT audits repositories                           | OWASP SAMM for programmes                                      |
+
+### On Scorecard specifically
+
+Scorecard is excellent and USAT's S3/S8 borrow its shape. Two honest caveats, both
+documented by its own users: it measures **process hygiene, not code quality**, and
+peer-reviewed research found **no clean correlation** between high scores and fewer
+vulnerabilities [1](https://rywalker.com/research/openssf-scorecard). Scorecard also
+needs a public repo and network access. USAT is the offline, code-level,
+private-repo complement — run both.
+
+### On SARIF
+
+SARIF 2.1.0 is the right interchange format for static-analysis _results_, and most
+SAST tools emit it. USAT reports are prose-oriented — a scored, prioritised document
+for humans and agents, not a machine-ingestible findings stream. If you need to feed
+results into a dashboard, that is a small renderer away
+(`src/report/`); the internal model already carries file, line, severity, and rule
+identity for every finding. Contributions welcome.
+
+---
+
+## Sources
+
+- [1](https://quality.arc42.org/standards/owasp-asvs) OWASP ASVS — version history, 17 chapters, cumulative L1–L3
+- [2](https://www.securecodinghub.com/blog/owasp-asvs-developers-complete-guide) OWASP ASVS 5.0 — choosing a verification level
+- [1](https://rywalker.com/research/openssf-scorecard) OpenSSF Scorecard — 18 checks, v5.5.0 (April 2026), and the caveats on what scores mean
+- [1](https://rywalker.com/research/slsa) SLSA — spec v1.2 (Nov 2025), Build L0–L3, Source track approved
+- [1](https://www.cybersaint.io/cybersecurity-frameworks-and-standards/glossary/what-is-the-owasp-top-10-for-llm-and-agentic-ai) OWASP Top 10 for LLM Applications, 2026 (LLM01–LLM10)
+- [3](https://blog.ogwilliam.com/post/owasp-top-10-llm-applications-2026-whats-new) OWASP LLM Top 10 — 2025 vs 2026 changes
+- [2](https://www.trydeepteam.com/docs/frameworks-owasp-top-10-for-agentic-applications) OWASP Top 10 for Agents, 2026 (ASI01–ASI10)
+- [1](https://github.com/addyosmani/agent-skills/blob/main/CLAUDE.md) Agent Skills convention — `SKILL.md` + `references/`

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@xenos1996/usat",
+  "version": "1.0.0",
+  "description": "Universal Software Audit Template — an open-source, self-adapting audit framework for any project, any stack, any stage",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "usat": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./rules": "./rules/index.yaml"
+  },
+  "files": [
+    "dist",
+    "rules",
+    "templates",
+    "schema",
+    "docs",
+    "USAT.md",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "audit",
+    "software-audit",
+    "security-audit",
+    "code-audit",
+    "code-review",
+    "openssf",
+    "owasp-asvs",
+    "slsa",
+    "sast",
+    "agent",
+    "llm",
+    "template",
+    "tech-debt",
+    "quality-gate"
+  ],
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Er-Sajan-PLG/software-auditing-template.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Er-Sajan-PLG/software-auditing-template/issues"
+  },
+  "homepage": "https://github.com/Er-Sajan-PLG/software-auditing-template#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "usat": "node --experimental-strip-types src/cli.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "self-audit": "npm run build && node dist/cli.js audit . --out AUDIT.md",
+    "prepublishOnly": "npm run build"
+  },
+  "lint-staged": {
+    "*.{js,ts,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yaml,yml}": [
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.4.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "eslint": "^10.10.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.5.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0",
+    "vitest": "^5.0.0"
+  }
+}