@lamentis/naome 1.3.9 → 1.3.10

package/templates/naome-root/docs/naome/architecture-fitness.md

@@ -0,0 +1,97 @@
+# Architecture Fitness
+
+NAOME architecture fitness validates repository structure with deterministic
+rules before agent changes are accepted. The rule layer is language-agnostic:
+language-specific extractors feed a normalized graph, and rules evaluate graph
+facts instead of prompt text.
+
+## Commands
+
+- `naome arch init` writes a starter `naome.arch.yaml`.
+- `naome arch explain` prints inferred layers, contexts, rules, and extractors.
+- `naome arch scan --json` emits the normalized graph.
+- `naome arch scan --write` writes `.naome/architecture-graph.json`.
+- `naome arch validate` runs architecture rules with human output.
+- `naome arch validate --json` emits stable machine-readable output.
+- `naome arch validate --agent-feedback` emits compact repair instructions.
+- `naome arch validate --changed-only` uses changed paths when available and
+  safely degrades to a full scan for graph-level soundness.
+
+## Graph Model
+
+The foundation graph uses stable IDs and normalized node and edge kinds. Nodes
+cover repositories, directories, files, layers, bounded contexts, modules,
+symbols, packages, and external dependencies. Edges cover containment and the
+dependency edge kinds required by later extractor slices.
+
+Each node and edge carries path, language, source range when known, confidence,
+extractor name, raw origin data, stable ID, and a human-readable label.
+
+## Configuration
+
+`naome.arch.yaml` defines layers, bounded contexts, rules, and ignored paths.
+Ignored paths require a reason so agents cannot silently suppress architecture
+ownership.
+
+```yaml
+layers:
+  domain:
+    paths:
+      - "src/domain/**"
+  infrastructure:
+    paths:
+      - "src/infrastructure/**"
+
+contexts:
+  billing:
+    paths:
+      - "src/billing/**"
+    public_api:
+      - "src/billing/index.ts"
+
+rules:
+  max_file_lines:
+    enabled: true
+    value: 400
+    severity: warning
+  generated_manual_boundary:
+    enabled: true
+    severity: error
+
+ignore:
+  - path: "generated/**"
+    reason: "Generated code is not architecture-owned."
+```
+
+## Current Rules
+
+- `arch.max_file_lines` enforces the configured file line budget.
+- `arch.generated_manual_boundary` prevents changed files under explicitly
+  ignored generated paths from being accepted without regeneration or a config
+  change.
+
+## Agent Integration
+
+Agents should run `naome arch validate --changed-only --json` after changing
+source or template files. JSON output includes status, severity counts,
+violations, concrete suggestions, and `agentFeedback` entries optimized for
+repair loops.
+
+## CI Integration
+
+Use `node .naome/bin/naome.js arch validate --changed-only` as a fast gate.
+The first foundation release reports warnings for existing file-size debt and
+fails only on configured error rules.
+
+## Language Support
+
+The v1.3.10 foundation classifies TypeScript, JavaScript, Rust, Python, Go,
+Java, Kotlin, and Swift files by path extension. Import extractors, resolver
+rules, cycle detection, layer dependency rules, and manifest extraction are
+planned follow-up slices before v1.4.0.
+
+## Limitations
+
+This release intentionally starts with path extraction, graph construction,
+file budgets, generated/manual boundaries, JSON output, human output, and CLI
+integration. It does not yet resolve imports or validate cross-layer imports.

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

@@ -22,9 +22,10 @@ for the current step.
 15. `testing.md`
 16. `repository-quality.md`, when repository-quality checks or cleanup are relevant
 17. `repository-structure.md`, when path roles or structure cleanup are relevant
-18. `security.md`
-19. `agent-workflow.md`
-20. `decisions.md`, when changing durable project policy
+18. `architecture-fitness.md`, when architecture graph or rule feedback matters
+19. `security.md`
+20. `agent-workflow.md`
+21. `decisions.md`, when changing durable project policy
 
 ## Source Types
 

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

@@ -26,6 +26,7 @@ and stale-policy issues before the task grows. It does not replace the final
 | 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 |
+| architecture-fitness-check | `node .naome/bin/naome.js arch validate --changed-only` | `.` | fast | null |
 
 ## Verification Phases
 
@@ -52,6 +53,7 @@ phase is failing or missing.
 - `.naome/bin/check-harness-health.js`
 - `.naome/bin/check-task-state.js`
 - `.naome/task-contract.schema.json`
+- `docs/naome/architecture-fitness.md`
 
 ## Rules
 
@@ -66,8 +68,9 @@ phase is failing or missing.
   and 12 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` and
-  `repository-semantic-check` as required checks for source, structure,
-  documentation, harness, template, and CI changes.
+- When intake defines change types, include `repository-quality-check`,
+  `repository-semantic-check`, and `architecture-fitness-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.