@lamentis/naome 1.2.0 → 1.3.0

package/templates/naome-root/docs/naome/repository-quality.md

@@ -7,15 +7,26 @@ NAOME keeps legacy debt visible without blocking unrelated feature work.
 - `naome quality check --changed` blocks only on files changed in the current
   diff. If a legacy file is touched, that file must satisfy the configured
   quality rules before commit.
-- `naome quality report` scans the repository and reports debt without failing
-  normal feature work.
+- `naome quality report` scans the repository with normal budgets and reports
+  debt without failing feature work. Full repository duplicate,
+  near-duplicate, and semantic grouping checks are deep-only.
+- `naome quality report --deep` runs the intentionally expensive full
+  repository checks.
 - `naome cleanup plan` groups report findings into deterministic cleanup tasks.
 - `naome cleanup route --path <path>` returns agent instructions for one file.
+  Structure findings include rule-specific guidance such as moving misplaced
+  tests, pairing source with nearby tests, splitting dumping-ground folders, or
+  resolving case collisions.
 
 ## Configuration
 
 Repository-specific rules live in `.naome/repository-quality.json`.
 
+`quality init` writes only policy files and an empty baseline placeholder. It
+does not deep-scan the repository. To record existing debt intentionally, run
+`quality init --baseline`; use `quality init --deep-baseline` only when broad
+duplicate and semantic grouping checks are expected.
+
 `quality init` selects deterministic built-in adapters from repository files.
 Adapters are plug-and-play profiles such as `rust` or
 `javascript-typescript`. They add stack-specific ignored/generated paths and
@@ -26,6 +37,20 @@ Local `pathRules` are project overrides, not product defaults. They may document
 repo-specific debt or special file roles, but loosening a rule to pass a feature
 diff requires human review.
 
+The scanner has three modes:
+
+- `ChangedFast`: changed files are read fully; unchanged files may contribute
+  cached facts for duplicate comparison.
+- `Report`: repository-wide, budgeted debt visibility. If budgets are hit, JSON
+  sets `summary.truncated` and includes stable `reasonCodes`.
+- `DeepReport`: explicit expensive scan for full duplicate, near-duplicate, and
+  semantic grouping work.
+
+Per-file analysis facts are cached under `.naome/cache/quality/`. Cache entries
+are local-only, keyed by NAOME version, config hash, adapter version, path, and
+content hash. Cache corruption or misses cause a rescan, not a gate failure.
+Use `quality cache status --json` and `quality cache clear` for maintenance.
+
 The default scanner is language-agnostic and uses text plus symbol heuristics:
 file length, diff growth, function or component length, top-level symbol count,
 duplicate regions, and near-duplicate functions. Duplicate regions are grouped
@@ -33,11 +58,48 @@ to avoid overlapping window spam and include repeated regions inside the same
 file. Near-duplicate function checks compare functions/components, not
 container symbols against their own children.
 
+Structure checks run through the same gate. See `repository-structure.md` for
+path roles, module/layer policy, adapters, and cleanup routing.
+
 Agents may propose stricter repo-specific rules after inspecting the language
 and stack.
 
+## Planned Semantic Cleanup
+
+Some maintainability debt is semantic rather than purely syntactic. Examples
+include inline legacy compatibility fixtures, copied config objects, stale test
+builders, hand-written schema snapshots, and helper data that should move into a
+shared factory after enough call sites accumulate.
+
+NAOME should detect these with a generic semantic-cleanup layer instead of
+hard-coding product paths or deleting compatibility fixtures opportunistically.
+The planned model is:
+
+- detect repeated object shapes, schema literals, fixture builders, and config
+  snapshots across changed and report-mode files;
+- classify each finding as `legacy fixture`, `duplicated fixture`,
+  `schema snapshot`, `generated metadata`, or `inline builder`;
+- keep existing report-mode debt visible without blocking unrelated work;
+- block only changed/new semantic debt unless local policy marks it report-only;
+- route cleanup to extract a shared fixture, builder, schema writer, or generated
+  metadata refresh command;
+- preserve behavior by requiring tests before removing or consolidating legacy
+  compatibility fixtures.
+
+The first implementation exposes this as a scout, not an auto-fixer:
+
+- `naome semantic report --json` runs a budgeted semantic report.
+- `naome semantic report --deep --json` runs repo-wide semantic grouping.
+- `naome semantic check --changed --json` checks only changed semantic debt for
+  gate use.
+- `naome semantic route --finding <id> --json` gives an agent the complete
+  affected path list, cleanup intent, and required checks for one finding group.
+- `naome semantic loop --json` selects the next deterministic cleanup action:
+  changed-code findings first, then report-only legacy debt.
+
 ## Baseline
 
 Existing debt is recorded in `.naome/repository-quality-baseline.json` by
-`naome quality init`. Baseline debt remains visible in reports, but only changed
-files are blocking during feature work.
+`naome quality init --baseline` or `naome quality init --deep-baseline`.
+Baseline debt remains visible in reports, but only changed files are blocking
+during feature work.

package/templates/naome-root/docs/naome/repository-structure.md

@@ -0,0 +1,51 @@
+# Repository Structure
+
+NAOME checks whether new and changed files land in a maintainable directory
+structure. Existing structure debt stays visible in reports and cleanup routes,
+but normal feature work is blocked only by relevant changed paths.
+
+## Model
+
+The structure model classifies each path as:
+
+`path -> role -> module -> layer -> language -> generated/debt/changed`
+
+Generic roles are `source`, `test`, `docs`, `config`, `script`, `generated`,
+`artifact`, `dependency/vendor`, and `unknown`.
+
+## Gates
+
+- `naome quality check --changed` includes structure checks.
+- `naome quality report` shows structure debt with other quality findings.
+- `naome structure report --json` returns only structure findings.
+- `naome structure explain --path <path> --json` explains one path's role,
+  module, layer, language, generated flag, debt flag, and changed flag.
+- `naome cleanup plan` and `naome cleanup route --path <path>` include
+  structure findings when a cleanup task should move or split files.
+
+## Checks
+
+Structure checks include directory role mixing, misplaced file roles,
+root-level file sprawl, dumping-ground directories, directory size, path depth,
+case-insensitive path collisions, and source/test pairing hints.
+
+Dumping-ground names such as `utils`, `helpers`, `common`, `shared`, `misc`,
+and `lib` are not banned. New feature logic there is reported when a named
+module location is more appropriate.
+
+## Adapters
+
+The core is language-independent. Adapters add deterministic signals for stack
+conventions. Built-in adapters currently include `rust` and
+`javascript-typescript`; future adapters can add source roots, test roots,
+module roots, and allowed root files without changing gate behavior.
+
+## Local Policy
+
+Rules live in `.naome/repository-structure.json`. Product defaults contain no
+repository-specific paths. Local policy may add source roots, test roots,
+generated roots, allowed root files, directory role rules, and layer rules.
+
+Use local policy to document real repository conventions, not to grant special
+rights to one product or hide cleanup work. Loosening a structure rule to pass a
+feature diff requires human review.

package/templates/naome-root/docs/naome/testing.md

@@ -58,6 +58,7 @@ phase is failing or missing.
 - Store long command output as a compact summary that preserves command, cwd,
   exit code, relevant lines, affected paths, and artifacts.
 - When intake defines change types, include `repository-quality-check` as a
-  required check for source, documentation, harness, template, and CI changes.
+  required check for source, structure, documentation, harness, template, and
+  CI changes.
 - Before completion, select proof from the Verification Map when possible.
 - Report exact commands and results. Do not claim proof that did not run.