@lamentis/naome 1.0.0

package/templates/naome-root/docs/naome/first-run.md

@@ -0,0 +1,135 @@
+# NAOME First-Run Protocol
+
+Run this protocol before feature work when `.naome/init-state.json` has
+`"initialized": false`.
+
+<goal>
+Turn this repository into an agent-readable codebase with minimal, accurate
+context.
+</goal>
+
+<rules>
+- Do not implement feature work during first-run intake.
+- Read `.naomeignore` before inspecting repository files.
+- Do not read, summarize, scan, import, or use paths matched by `.naomeignore`.
+- Prefer repository evidence over guesses.
+- Record only facts from this target repository or from the user. Do not mention
+  parent workspaces, outer repositories, chat/system instructions, or unrelated
+  agent instructions unless the files exist in this repository.
+- Ignore external harness names, global skills, previous workspace instructions,
+  parent repository policy, and unrelated project docs unless the user
+  explicitly says they apply to this repository.
+- Ask the user only for critical missing context.
+- Mark assumptions and unknowns explicitly.
+- For important claims, cite local evidence paths.
+- Set `initialized` to `true` only after the required docs are filled and the
+  repository has enough confirmed context for future agents to work safely.
+</rules>
+
+## Intake Steps
+
+1. Read `.naomeignore` and exclude every matched path from intake.
+2. Inspect existing repository instructions and docs, including README,
+   contributing docs, architecture docs, agent instruction files, and CI config.
+3. Detect stack, frameworks, package managers, project layout, entrypoints,
+   test tools, lint/typecheck/build commands, and deployment hints.
+4. Identify risky areas such as auth, billing, secrets, migrations, production
+   config, customer data, generated files, or fragile inherited code.
+5. Build the Proof Harness:
+   - inspect package files, build files, Makefiles, and CI workflows
+   - record real checks in `.naome/verification.json`
+   - mirror the human-readable map in `testing.md`
+   - run the fastest safe check when possible and record the result
+   - preserve the JSON keys and allowed values documented below
+6. Fill `repo-profile.md`, `testing.md`, `architecture.md`, and `security.md`.
+7. Ask the user for critical missing product intent, forbidden zones, or
+   verification commands only if repository evidence is insufficient.
+8. Update `.naome/init-state.json`:
+   - use `intakeStatus: "complete"` and `initialized: true` only when the
+     completion gate is satisfied
+   - use `intakeStatus: "needs_user_context"` and keep `initialized: false`
+     when critical product, repository, or verification context is missing
+   - use `intakeStatus: "partial"` and keep `initialized: false` when some docs
+     are filled but the repository is not ready for normal agent work
+
+## Completion Gate
+
+Initialization is complete only when:
+
+- `repo-profile.md` describes this specific repository.
+- `testing.md` records at least one real verification path.
+- `.naome/verification.json` contains the same durable checks and change-type
+  rules recorded in `testing.md`.
+- `architecture.md` describes observed structure and known or assumed
+  boundaries.
+- `security.md` records sensitive areas or states that none are known yet.
+- remaining unknowns are explicit.
+
+## Verification Contract Schema
+
+`.naome/verification.json` must keep this shape:
+
+- top-level keys: `schema`, `version`, `status`, `lastUpdated`, `checks`,
+  `changeTypes`, `releaseGates`
+- `status`: `uninitialized`, `partial`, or `ready`
+- `lastUpdated` and `lastVerified`: `YYYY-MM-DD` or `null`
+- check `cost`: `fast`, `medium`, `slow`, `expensive`, `ci-only`, or `unknown`
+- check ids: lowercase kebab-case
+- each check needs `id`, `command`, `cwd`, `purpose`, `cost`, `source`,
+  `evidence`, and `lastVerified`
+- each change type needs `id`, `description`, `paths`, `requiredChecks`,
+  `recommendedChecks`, and `humanReview`
+- each release gate needs `checkId` and `requiredWhen`
+
+Rules:
+
+- Do not add new top-level keys.
+- Do not leave `example-*` ids or `replace with` values when marking ready.
+- Every `requiredChecks`, `recommendedChecks`, and release `checkId` must match
+  an existing check id.
+- Set `status` to `ready` only when the contract validates and has at least one
+  real check.
+- This JSON is machine state, not prose context. It is exempt from the
+  200-line instruction-file budget, but must stay bounded: at most 20 checks, 12
+  change types, and 10 release gates.
+- Do not read `.naome/verification.json` as long-form context during normal
+  work. Select the relevant change type or check id, then read only the matching
+  entries needed for proof.
+
+Do not mark initialization complete when:
+
+- the folder is not a Git repository and it is unclear whether it is the real
+  project root
+- the repository has no product code and no confirmed purpose
+- no human-confirmed purpose, owner intent, or verification path is known
+- no verification command can be found or confirmed
+- open questions block safe future code changes
+
+In those cases, fill what can be discovered, set `intakeStatus` to
+`needs_user_context` or `partial`, record `blockedReason`, and ask the user for
+the missing context.
+
+## Evidence Rule
+
+Each required intake document should include an `Evidence` section listing the
+local files or commands that support its important claims. Use relative paths
+from the repository root. Do not cite files outside the target repository.
+Do not cite files matched by `.naomeignore`.
+
+Claims about repo-local agent instructions, skill directories, generated
+artifacts, harness files, or automation policy require explicit evidence paths.
+If the exact file or directory path is not listed in `Evidence`, phrase the item
+as unknown or remove it.
+
+## External Instruction Conflict Check
+
+Before completing intake:
+
+1. List repo-local agent instruction files in `repo-profile.md`.
+2. Treat nested `AGENTS.md` files as task-local evidence for their directory,
+   not as replacements for the root NAOME harness authority.
+3. Do not copy global skill policies, previous workspace policies, or parent
+   repo policies into NAOME docs.
+4. If a global instruction is influencing your work and conflicts with NAOME,
+   ask the user whether it should become local policy.
+5. Record only user-confirmed local policy in `decisions.md`.

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

@@ -0,0 +1,67 @@
+# NAOME Index
+
+NAOME keeps repository context small and task-routed. Load only the files needed
+for the current step.
+
+## Read Order
+
+1. `.naomeignore`
+2. `.naome/init-state.json`
+3. `.naome/task-state.json`
+4. `.naome/upgrade-state.json`
+5. `node .naome/bin/check-harness-health.js`
+6. `execution.md`, before accepting or completing feature work
+7. `first-run.md`, only when `initialized` is `false`
+8. `upgrade.md`, only when upgrade `status` is `needs_agent_upgrade`
+9. `repo-profile.md`
+10. `architecture.md`
+11. `testing.md`
+12. `.naome/verification.json`
+13. `security.md`
+14. `agent-workflow.md`
+15. `decisions.md`, when changing durable project policy
+
+## Source Types
+
+- Discovered facts come from repository files and commands.
+- Confirmed facts were explicitly confirmed by a human or existing
+  authoritative documentation.
+- Assumptions must be marked as assumptions and revisited when they matter.
+- Unknowns should stay visible until resolved.
+
+## Context Rule
+
+Do not load every NAOME document by default. Start from this index, then open the
+smallest set of files needed for the task.
+
+## Proof Rule
+
+Use `testing.md` and `.naome/verification.json` before claiming completion.
+Choose the required check for the changed paths, run it when available, and
+report the exact command and result.
+
+## Task Control Rule
+
+Use `naome status` or `node .naome/bin/naome.js status` to get the
+machine-generated next decision. Use `execution.md` and `.naome/task-state.json`
+before starting new work and before claiming completion. First run
+`node .naome/bin/check-harness-health.js`, then run
+`node .naome/bin/check-task-state.js --admission` before accepting feature work.
+If either check fails, do not accept a new feature task until the user resolves
+the listed action.
+
+## Harness Health Rule
+
+Machine-owned harness files are listed in `.naome/manifest.json`. Agents may
+repair those files with `naome sync`; project-owned files require user or
+task-specific edits. Do not continue if the health checker reports missing
+files, symlinks, integrity drift, or a missing `.naome/archive/` ignore rule.
+
+## Ignore Rule
+
+`.naomeignore` is a hard read boundary for agents. Treat patterns as
+repository-root-relative, gitignore-like paths. Blank lines and lines starting
+with `#` are comments. Do not read, summarize, scan, import, or use files and
+directories matched by `.naomeignore` as context or evidence. If a task appears
+to require an ignored path, ask the user to remove that path from `.naomeignore`
+before proceeding.

package/templates/naome-root/docs/naome/repo-profile.md

@@ -0,0 +1,51 @@
+# Repository Profile
+
+Status: Uninitialized
+
+## Purpose
+
+- Unknown.
+
+## Stack
+
+- Unknown.
+
+## Project Layout
+
+- Unknown.
+
+## Package And Tooling
+
+- Package manager: Unknown.
+- Build command: Unknown.
+- Test command: Unknown.
+- Lint command: Unknown.
+- Typecheck command: Unknown.
+
+## CI And Deployment
+
+- CI: Unknown.
+- Deployment: Unknown.
+
+## Existing Instructions
+
+- Unknown.
+
+## Nested Agent Instructions
+
+- Unknown.
+
+## Evidence
+
+- Unknown.
+
+## Evidence Requirements
+
+- Claims about agent instructions, skill directories, generated artifacts,
+  harness files, or automation policy require exact local evidence paths.
+
+## Open Questions
+
+- What is the product or repository purpose?
+- Which commands should agents trust for verification?
+- Is this folder the real project root?

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

@@ -0,0 +1,60 @@
+# Security And Risk
+
+Status: Uninitialized
+
+## Sensitive Areas
+
+- Unknown.
+
+## Secrets And Credentials
+
+- Unknown.
+
+## High-Risk Changes
+
+- Unknown.
+
+## Human Review Required
+
+- Unknown.
+
+## Evidence
+
+- Unknown.
+
+## Evidence Requirements
+
+- Claims about credentialed automation, agent instruction files, skill
+  directories, generated artifacts, or harness files require exact local
+  evidence paths.
+- Claims must not cite files matched by `.naomeignore`.
+
+## NAOME Ignore Boundary
+
+`.naomeignore` defines repository paths that agents must not read. The default
+entry is `.naome/archive/` so historical snapshots never become active context.
+
+Rules:
+
+- Read `.naomeignore` before inspecting repository files.
+- Treat patterns as repository-root-relative, gitignore-like paths.
+- Do not read, summarize, scan, import, or use ignored files as evidence.
+- If ignored content seems necessary, ask the user to remove the path from
+  `.naomeignore` before continuing.
+
+## Harness Integrity Boundary
+
+Machine-owned files in `.naome/manifest.json` are active harness controls.
+Before feature work, run `node .naome/bin/check-harness-health.js`. Stop if it
+reports missing files, symlinks, integrity drift, or a missing archive ignore
+boundary. Git commits do not bless harness drift; machine-owned files must match
+the packaged hashes embedded in the health checker. Repair only with the
+installer or an explicit human decision.
+
+## Agent Rules
+
+- Do not expose secrets.
+- Do not inspect paths matched by `.naomeignore`.
+- Do not modify production credentials.
+- Do not weaken auth, authorization, billing, data retention, or encryption
+  without explicit user direction and verification.

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

@@ -0,0 +1,51 @@
+# Testing And Verification
+
+Status: Uninitialized
+
+## Verification Map
+
+| Change type | Required proof | Command | Notes |
+|---|---|---|---|
+| 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. |
+
+## Known Checks
+
+| Check id | Command | Cwd | Cost | Last verified |
+|---|---|---|---|---|
+| diff-check | `git diff --check` | `.` | fast | null |
+| naome-harness-health | `node .naome/bin/check-harness-health.js` | `.` | fast | null |
+| naome-task-state | `node .naome/bin/check-task-state.js` | `.` | fast | null |
+
+## Change Type Rules
+
+| Change type | Paths | Required checks |
+|---|---|---|
+| Unknown | Unknown | Unknown |
+
+## Release Gates
+
+| Check id | Required when |
+|---|---|
+| Unknown | Before release, when applicable. |
+
+## Evidence
+
+- `.naome/verification.json`
+- `.naome/bin/check-harness-health.js`
+- `.naome/bin/check-task-state.js`
+- `.naome/task-contract.schema.json`
+
+## Rules
+
+- Mirror durable entries in `.naome/verification.json`.
+- Use only commands proven by repository files, CI, or user confirmation.
+- Preserve the JSON keys from `.naome/verification.json`.
+- When intake is complete, set verification `status` to `ready`.
+- Use only costs: `fast`, `medium`, `slow`, `expensive`, `ci-only`, `unknown`.
+- Use dates as `YYYY-MM-DD` or `null`.
+- Keep instruction files under 200 lines. `.naome/verification.json` is machine
+  state instead; keep it schema-valid and bounded to 20 checks, 12 change types,
+  and 10 release gates.
+- Before completion, select proof from the Verification Map when possible.
+- Report exact commands and results. Do not claim proof that did not run.

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

@@ -0,0 +1,20 @@
+# NAOME Upgrade Policy
+
+NAOME supports controlled in-place upgrades from supported older installed
+harness versions.
+
+The supported upgrade floor is NAOME v0.6.1, the first Rust-backed harness
+baseline. If `naome sync` sees `.naome/manifest.json` with a supported
+`harnessVersion` lower than the package version and at or above v0.6.1, it may
+refresh machine-owned harness files, install current local binaries, and update
+`.naome/manifest.json` and `.naome/upgrade-state.json`.
+
+Pre-Rust harness versions below v0.6.1 must stop without mutating repository
+files. Create a clean NAOME baseline instead.
+
+Same-version installs may be repaired with `naome sync`. Newer installed
+harness versions must never be downgraded.
+
+Agents must not start feature work while an unsupported pre-Rust harness or
+pending upgrade state is present. Ask the user to create a clean baseline,
+reinstall NAOME, or finish the upgrade after reviewing the local diff.