@lamentis/naome 1.2.1 → 1.3.1

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

@@ -0,0 +1,92 @@
+# Repository World Model
+
+The repository model is the deterministic source for machine-readable facts
+about this repository. It keeps stack and layout facts out of free-form
+Markdown so agents can make repeatable decisions.
+
+## Files
+
+- `.naome/repository-model.json` stores canonical facts.
+- `.naome/verification.json` stores runnable checks and change-type proof
+  policy.
+- Repository-quality and repository-structure policy store quality adapters and
+  layout rules.
+- Markdown documents explain workflow and summarize human context; they are not
+  the primary store for build, stack, or path-role facts.
+
+## Commands
+
+- `naome repo model --write --json` refreshes the model from repository files.
+- `naome repo check --json` verifies the committed model is current.
+- `naome repo explain --path <path> --json` explains the role and language for a
+  path using the canonical model.
+
+## Facts
+
+`naome.repository-model.v2` keeps the backward-compatible flat `facts[]` list
+and adds typed world-model sections. `naome.repository-model.v1` remains
+readable; new writes prefer v2.
+
+Flat facts are deterministic records with stable ids:
+
+- `language:<value>`
+- `packageManager:<value>`
+- `buildSystem:<value>`
+- `sourceRoot:<path>`
+- `testRoot:<path>`
+- `docsRoot:<path>`
+- `generatedRoot:<path>`
+- `artifactRoot:<path>`
+- `verificationCheck:<id>`
+
+Each fact includes evidence paths and a source. Do not hand-edit generated facts
+as normal workflow. Refresh them with the command above.
+
+## World Sections
+
+The v2 model stores typed sections so agents do not need to infer repository
+shape from prose:
+
+- `languages`, `packageManagers`, and `buildSystems`
+- `adapters` detected from deterministic stack signals
+- `roots` for source, test, docs, generated, and artifact paths
+- `entities` for packages, apps, and modules
+- `pathFacts` for significant paths with role, module, entity, language, and
+  generated/artifact flags
+- `verificationChecks` copied from `.naome/verification.json`
+
+These sections are generic and adapter-extensible. Product defaults must not
+contain repository-specific exceptions.
+
+## Agent Rule
+
+When a task depends on the stack, package manager, build system, source roots,
+test roots, generated roots, or verification ids, read or refresh the repository
+model instead of searching broad Markdown files. If the model is stale, update it
+first, then continue with the task.
+
+For a specific path, use:
+
+```text
+naome repo explain --path <path> --json
+```
+
+The explanation returns the canonical role, language, module, entity, matching
+facts, and evidence for that path.
+
+## Drift Gates
+
+NAOME does not silently rewrite `.naome/repository-model.json` during normal
+gates. Instead, stale facts are reported deterministically:
+
+- `naome doctor --json` reports a stale repository model section.
+- `node .naome/bin/check-task-state.js --progress` blocks active work until the
+  model is refreshed.
+- `naome quality check --changed --json` emits `repository-model-stale` as a
+  changed-code finding.
+
+The fix is explicit and idempotent:
+
+```text
+naome repo model --write --json
+```

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

@@ -6,26 +6,90 @@ 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.
+  quality and semantic changed rules before commit.
+- `naome quality check --path <path>` is the early touched-file gate. Run it
+  immediately after editing a file to catch file length, diff growth, function
+  length, top-level symbol count, same-file duplicate regions, structure
+  issues, and stale adapter/model policy before a large task accumulates.
+  Repeat `--path` for a small touched set. This is a fast local feedback gate;
+  the final `--changed` gate still remains required.
+- `naome semantic check --changed` is also exposed as the explicit semantic
+  changed gate. Fresh verification profiles require it next to
+  `repository-quality-check`; `quality check --changed` includes the same
+  semantic changed findings for backward compatibility with older profiles.
+- `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
 path rules at runtime without hard-coding a specific product repository into
 the generic template.
 
+Repository stacks can change after setup. `quality check --changed` and
+`quality report` compare current repository signals with committed
+`enabledAdapters`; when a new stack is present but not enabled, they emit
+`adapter-policy-stale`. Use `naome quality reconcile --json` to inspect the
+delta and `naome quality reconcile --write` to update
+`.naome/repository-quality.json` and `.naome/repository-structure.json`
+deterministically. Do not hand-edit adapter lists as the normal path.
+
+Built-in adapter detection is path/manifest based and deterministic:
+
+- `rust`: `Cargo.toml` or `.rs` files.
+- `javascript-typescript`: `package.json` or JS/TS files.
+- `swift`: `Package.swift` or `.swift` files.
+- `xcode`: `.xcodeproj` or `.xcworkspace` content.
+- `xctest`: Swift test targets such as `Tests`, `*Tests`, or `*UITests`.
+- `swiftui`: SwiftUI-style app/view paths such as `*App.swift`,
+  `*View.swift`, `Views`, or Preview Content.
+- `ios-app-structure`: iOS app entrypoints, `Info.plist`, entitlements, or
+  asset catalogs.
+- `swift-package`: Swift Package Manager `Sources` and `Tests` layout.
+- `ios-resources`: `.xcassets`, `.strings`, `.plist`, `.storyboard`, `.xib`,
+  and entitlements.
+- `generated-ios`: SwiftGen, Sourcery, protobuf, and `*.generated.swift`
+  outputs.
+
 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:
+
+- `PathScoped`: explicitly requested touched files are read fully, with the
+  repository path index used for path/structure context. It avoids fully
+  analyzing unrelated changed files, making it suitable directly after file
+  writes.
+- `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
@@ -39,8 +103,43 @@ path roles, module/layer policy, adapters, and cleanup routing.
 Agents may propose stricter repo-specific rules after inspecting the language
 and stack.
 
+## 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 detects these with a generic semantic-cleanup layer instead of hard-coding
+product paths or deleting compatibility fixtures opportunistically. The 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 changed/new semantic debt through `quality check --changed` and
+  `semantic check --changed`;
+- 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.
+
+Semantic cleanup is a scout and gate, 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

@@ -36,9 +36,16 @@ 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.
+conventions. Built-in adapters currently include `rust`,
+`javascript-typescript`, `swift`, `xcode`, `xctest`, `swiftui`,
+`ios-app-structure`, `swift-package`, `ios-resources`, and `generated-ios`.
+Future adapters can add source roots, test roots, module roots, and allowed
+root files without changing gate behavior.
+
+If the repository later adds a new stack, `quality check --changed` and
+`quality report` emit `adapter-policy-stale` until
+`naome quality reconcile --write` updates the committed quality and structure
+policy files.
 
 ## Local Policy
 

package/templates/naome-root/docs/naome/task-ledger.md

@@ -0,0 +1,71 @@
+# Task Ledger
+
+NAOME task state is moving from one mutable aggregate file to a canonical task
+ledger. The compatibility file `.naome/task-state.json` remains supported, but
+new deterministic task tooling can use `.naome/tasks/` as the source of truth.
+
+## Layout
+
+```text
+.naome/tasks/
+  active.json
+  <task-id>/
+    task.json
+    events.jsonl
+    mutations.json
+    proofs/
+      <check-id>.json
+```
+
+- `active.json` identifies the primary task and leaves room for future
+  worklanes.
+- `task.json` contains the stable task contract: request, prompt, admission,
+  allowed paths, change types, required checks, and human-review policy.
+- `events.jsonl` is append-only. Status changes, blockers, and later decisions
+  are added as events instead of rewriting the whole task.
+- `mutations.json` records touched paths and mutation ownership.
+- `proofs/<check-id>.json` stores one verification result per check so parallel
+  checks do not rewrite the same file.
+
+## Compatibility
+
+Existing `naome.task-state.v1` and `naome.task-state.v2` files remain valid. If
+`.naome/tasks/active.json` exists, NAOME readers build a canonical task model
+from the ledger and render a `naome.task-state.v2` projection. If no ledger is
+present, readers fall back to `.naome/task-state.json`.
+
+Use this command when an external tool needs the compatibility file refreshed:
+
+```text
+node .naome/bin/naome.js task render-state --write --json
+```
+
+`naome sync` automatically splits an active legacy `task-state` file into the
+ledger layout. The explicit command remains available for repair or tests:
+
+```text
+node .naome/bin/naome.js task migrate-ledger --write --json
+```
+
+After `.naome/tasks/active.json` exists, `.naome/task-state.json` is a rendered
+compatibility projection. NAOME gates reject a stale projection and report the
+render command instead of accepting hand-edited aggregate state.
+
+## Conflict Policy
+
+`.naome/tasks/` is NAOME control state. It is not task feature scope and is not
+required as proof evidence. Gates ignore ledger control files when checking
+whether product changes stay inside `allowedPaths`.
+
+The intended long-term model is:
+
+```text
+task spec + events + mutations + proofs + verification config
+=> canonical task model
+=> generated task-state projection
+=> gates / route / commit / completion
+```
+
+This keeps old repositories backward-compatible while making future parallel
+agents safer: separate agents and checks can write separate event/proof files
+instead of all competing for `.naome/task-state.json`.

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

@@ -9,6 +9,18 @@ Status: Uninitialized
 | NAOME baseline | Built-in harness proof | See Known Checks | Seeded by installer; extend during first-run intake. |
 | Repository-specific work | Unknown | Unknown | Fill during first-run intake. |
 
+## Early Feedback
+
+After writing or heavily editing a file, run
+`node .naome/bin/naome.js quality check --path <path>` for immediate
+touched-file feedback. This catches local size, symbol, duplicate, structure,
+and stale-policy issues before the task grows. It does not replace the final
+`repository-quality-check`; always run the changed-file gate before completion.
+
+Optional Codex hooks can provide the same kind of early feedback during an
+agent run. They are acceleration only; final proof still comes from the
+commands in this document and `.naome/verification.json`.
+
 ## Known Checks
 
 | Check id | Command | Cwd | Cost | Last verified |
@@ -17,6 +29,7 @@ Status: Uninitialized
 | naome-harness-health | `node .naome/bin/check-harness-health.js` | `.` | fast | null |
 | naome-task-state | `node .naome/bin/check-task-state.js` | `.` | fast | null |
 | repository-quality-check | `node .naome/bin/naome.js quality check --changed` | `.` | fast | null |
+| repository-semantic-check | `node .naome/bin/naome.js semantic check --changed` | `.` | fast | null |
 
 ## Verification Phases
 
@@ -57,8 +70,8 @@ phase is failing or missing.
   and 10 release gates.
 - 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, structure, documentation, harness, template, and
-  CI changes.
+- When intake defines change types, include `repository-quality-check` and
+  `repository-semantic-check` as required checks 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.