@lamentis/naome 1.3.0 → 1.3.1

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

@@ -6,7 +6,17 @@ 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.
+  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.
@@ -33,12 +43,41 @@ Adapters are plug-and-play profiles such as `rust` or
 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
@@ -64,29 +103,30 @@ 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
+## 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:
+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 only changed/new semantic debt unless local policy marks it report-only;
+- 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.
 
-The first implementation exposes this as a scout, not an auto-fixer:
+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.

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.