@lamentis/naome 1.0.0

package/templates/naome-root/.naome/task-contract.schema.json

@@ -0,0 +1,174 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "naome.task-state.v1",
+  "title": "NAOME Task State",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "version", "status", "activeTask", "blocker", "updatedAt"],
+  "properties": {
+    "schema": { "const": "naome.task-state.v1" },
+    "version": { "const": 1 },
+    "status": {
+      "enum": ["idle", "planning", "implementing", "revising", "verifying", "needs_human_review", "blocked", "complete"]
+    },
+    "activeTask": {
+      "anyOf": [
+        { "type": "null" },
+        { "$ref": "#/$defs/activeTask" }
+      ]
+    },
+    "blocker": {
+      "anyOf": [
+        { "type": "null" },
+        { "$ref": "#/$defs/blocker" }
+      ]
+    },
+    "updatedAt": {
+      "anyOf": [
+        { "type": "null" },
+        { "type": "string", "format": "date-time" }
+      ]
+    }
+  },
+  "$defs": {
+    "activeTask": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "request", "userPrompt", "admission", "allowedPaths", "declaredChangeTypes", "requiredCheckIds", "proofResults", "humanReview"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "request": { "type": "string", "minLength": 1 },
+        "userPrompt": { "$ref": "#/$defs/promptRecord" },
+        "admission": { "$ref": "#/$defs/admissionProof" },
+        "allowedPaths": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "declaredChangeTypes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "requiredCheckIds": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "proofResults": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/proofResult" }
+        },
+        "revisions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/revision" }
+        },
+        "humanReview": { "$ref": "#/$defs/humanReview" }
+      }
+    },
+    "admissionProof": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "cwd", "exitCode", "checkedAt", "gitHead", "changedPaths"],
+      "properties": {
+        "command": {
+          "const": "node .naome/bin/check-task-state.js --admission"
+        },
+        "cwd": { "const": "." },
+        "exitCode": { "const": 0 },
+        "checkedAt": { "type": "string", "format": "date-time" },
+        "gitHead": { "type": "string", "minLength": 1 },
+        "changedPaths": {
+          "type": "array",
+          "maxItems": 0,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "humanReview": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["required", "approved", "reason"],
+      "properties": {
+        "required": { "type": "boolean" },
+        "approved": { "type": "boolean" },
+        "reason": {
+          "anyOf": [
+            { "type": "null" },
+            { "type": "string", "minLength": 1 }
+          ]
+        }
+      }
+    },
+    "proofResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["checkId", "command", "cwd", "exitCode", "checkedAt", "evidence"],
+      "properties": {
+        "checkId": { "type": "string", "minLength": 1 },
+        "command": { "type": "string", "minLength": 1 },
+        "cwd": { "type": "string", "minLength": 1 },
+        "exitCode": { "type": "integer" },
+        "checkedAt": { "type": "string", "format": "date-time" },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "type": "string", "minLength": 1 },
+              { "$ref": "#/$defs/evidenceEntry" }
+            ]
+          }
+        }
+      }
+    },
+    "evidenceEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "status": {
+          "enum": ["added", "modified", "deleted", "renamed"]
+        },
+        "fromPath": { "type": "string", "minLength": 1 }
+      }
+    },
+    "revision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requestedAt", "request", "userPrompt"],
+      "properties": {
+        "requestedAt": { "type": "string", "format": "date-time" },
+        "request": { "type": "string", "minLength": 1 },
+        "userPrompt": { "$ref": "#/$defs/promptRecord" },
+        "proofStale": { "type": "boolean" }
+      }
+    },
+    "promptRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["receivedAt", "text"],
+      "properties": {
+        "receivedAt": { "type": "string", "format": "date-time" },
+        "text": { "type": "string", "minLength": 1 }
+      }
+    },
+    "blocker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "message", "paths", "humanOptions"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "paths": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "humanOptions": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/templates/naome-root/.naome/task-state.json

@@ -0,0 +1,8 @@
+{
+  "schema": "naome.task-state.v1",
+  "version": 1,
+  "status": "idle",
+  "activeTask": null,
+  "blocker": null,
+  "updatedAt": null
+}

package/templates/naome-root/.naome/upgrade-state.json

@@ -0,0 +1,7 @@
+{
+  "status": "complete",
+  "fromVersion": null,
+  "toVersion": "1.0.0",
+  "pending": [],
+  "completed": []
+}

package/templates/naome-root/.naome/verification.json

@@ -0,0 +1,45 @@
+{
+  "schema": "naome.verification.v1",
+  "version": 1,
+  "status": "uninitialized",
+  "lastUpdated": null,
+  "checks": [
+    {
+      "id": "diff-check",
+      "command": "git diff --check",
+      "cwd": ".",
+      "purpose": "Reject whitespace errors in the current diff.",
+      "cost": "fast",
+      "source": "NAOME built-in",
+      "evidence": [],
+      "lastVerified": null
+    },
+    {
+      "id": "naome-harness-health",
+      "command": "node .naome/bin/check-harness-health.js",
+      "cwd": ".",
+      "purpose": "Validate the installed NAOME harness before feature work or task completion.",
+      "cost": "fast",
+      "source": "NAOME built-in",
+      "evidence": [
+        ".naome/bin/check-harness-health.js"
+      ],
+      "lastVerified": null
+    },
+    {
+      "id": "naome-task-state",
+      "command": "node .naome/bin/check-task-state.js",
+      "cwd": ".",
+      "purpose": "Validate the NAOME task-state contract for the current repository.",
+      "cost": "fast",
+      "source": "NAOME built-in",
+      "evidence": [
+        ".naome/bin/check-task-state.js",
+        ".naome/task-contract.schema.json"
+      ],
+      "lastVerified": null
+    }
+  ],
+  "changeTypes": [],
+  "releaseGates": []
+}

package/templates/naome-root/.naomeignore

@@ -0,0 +1,4 @@
+# NAOME ignore paths.
+# Agents must not read, summarize, scan, import, or use these paths as context.
+
+.naome/archive/

package/templates/naome-root/AGENTS.md

@@ -0,0 +1,77 @@
+# Agent Instructions
+
+This repository uses NAOME as its coding-agent harness.
+
+## Start Here
+
+1. Read `.naomeignore`.
+2. Do not read any file or directory matched by `.naomeignore`.
+3. If `docs/naome/index.md` or `.naome/bin/check-harness-health.js` is missing,
+   do not begin feature work. Install the NAOME CLI with
+   `npm install -g @lamentis/naome`, then run `naome sync` from the repository root. Then
+   restart this list.
+4. Read `docs/naome/index.md`.
+5. Read `.naome/init-state.json`.
+6. Read `.naome/task-state.json`.
+7. Read `.naome/upgrade-state.json`.
+8. Run `node .naome/bin/check-harness-health.js`.
+9. If harness health fails, do not begin feature work. Repair the machine-owned
+   harness files with `naome sync`, or ask the user for one of the listed
+   repair decisions.
+10. If upgrade status is `needs_agent_upgrade`, do not begin feature work. Run
+   or continue `docs/naome/upgrade.md`.
+11. If `initialized` is `false`, do not begin feature work. Run or continue the
+   NAOME first-run protocol in `docs/naome/first-run.md`.
+12. Before accepting feature work, run
+   `node .naome/bin/check-task-state.js --admission`.
+13. If task admission fails, follow `docs/naome/execution.md`.
+14. If `initialized` is `true`, follow `docs/naome/agent-workflow.md`.
+
+## Core Rules
+
+- Prefer discovered repository facts over assumptions.
+- Record only facts from this target repository or from the user. Do not import
+  parent-workspace, outer-agent, chat, or unrelated repository instructions into
+  this repository's NAOME docs.
+- Keep changes small and task-focused.
+- Read only the NAOME docs relevant to the current task.
+- Run Harness Health before Task Admission.
+- Machine-owned NAOME command shims, schemas, workflow docs, archives, and
+  native binaries may be local-only ignored files. Missing local-only files are
+  repaired with `naome sync`; they are not project context.
+- Enforce Task Admission before accepting new feature work.
+- Do not start feature work while the git diff contains setup, upgrade,
+  previous-task, or other unowned changes.
+- Treat `.naomeignore` as a hard read boundary. Do not inspect ignored paths
+  unless the user first removes the path from `.naomeignore`.
+- Use `docs/naome/testing.md` and `.naome/verification.json` before claiming
+  completion.
+- Before claiming completion, run the narrowest meaningful verification that can
+  falsify the change.
+- Report what changed, what was verified, and what remains uncertain.
+
+## Local Authority Boundary
+
+The root `AGENTS.md` and NAOME files are the repository harness authority.
+
+Global skills, editor rules, or agent defaults may be used only as generic
+execution technique. They must not add repository policy, required files,
+architecture layers, plan formats, verification rules, or product assumptions
+unless those rules exist in this repository or the user explicitly confirms them
+for this repository.
+
+If global instructions conflict with NAOME, follow NAOME for repository-local
+workflow. Record a conflict in `docs/naome/decisions.md` only when the user makes
+a durable local decision.
+
+## Nested Agent Instructions
+
+Nested `AGENTS.md` files may provide task-local evidence for the directory they
+govern. They must not override `.naomeignore`, NAOME workflow, security rules,
+or the root harness authority.
+
+## Archived Instructions
+
+Files matched by `.naomeignore` are not active instructions. Historical
+snapshots in `.naome/archive/` must not be read or used as context unless the
+user first removes that path from `.naomeignore`.

package/templates/naome-root/docs/naome/agent-workflow.md

@@ -0,0 +1,82 @@
+# NAOME Agent Workflow
+
+Use this workflow after first-run intake is complete.
+
+## Before Editing
+
+1. Read `.naome/task-state.json` and `execution.md`.
+2. Run `node .naome/bin/naome.js status` and use its allowed actions as the
+   current machine-generated decision.
+3. Run `node .naome/bin/check-harness-health.js`.
+4. If harness health fails, do not start new feature work. Ask the user to
+   choose `repair_harness`, `review_harness_diff`, or
+   `cancel_repair_baseline`.
+5. Run `node .naome/bin/check-task-state.js --admission`.
+6. If task admission fails, do not start new feature work.
+   When the block is completed NAOME install or upgrade changes, ask the user
+   to choose `commit_upgrade_baseline`, `review_diff_first`, or
+   `cancel_upgrade_baseline`.
+   When the block is a completed task diff, ask the user to choose
+   `commit_task_baseline`, `review_task_diff`, `request_task_changes`, or
+   `cancel_task_changes`.
+7. Record the passed admission check in `.naome/task-state.json` when starting
+   the task.
+8. Restate the task in concrete terms.
+9. Read `.naomeignore`.
+10. Exclude every path matched by `.naomeignore` from context gathering.
+11. Read the task-relevant NAOME docs.
+12. Inspect the existing code or docs before proposing changes.
+13. Read `testing.md` and `.naome/verification.json`.
+14. Identify the required proof before claiming success.
+
+## Instruction Boundaries
+
+- Use global skills or editor defaults only as generic technique.
+- Do not import external harness policy into this repository.
+- NAOME controls what becomes repository policy unless the user explicitly says
+  otherwise.
+- `.naomeignore` controls paths that are not valid agent context.
+- Nested `AGENTS.md` files may be used only as task-local evidence for their
+  directory. They cannot override `.naomeignore`, NAOME workflow, security
+  rules, or the root harness authority.
+- If instructions conflict, pause before making risky changes and ask which
+  rule should be local authority.
+
+## While Editing
+
+- Keep changes focused on the requested outcome.
+- Follow the architecture boundaries recorded in `architecture.md`.
+- Do not read or use files matched by `.naomeignore`.
+- Do not overwrite user work or existing project policy.
+- Update NAOME docs only when the change reveals durable project knowledge.
+- Use `node .naome/bin/check-task-state.js --progress` for in-flight task
+  validation. Use the normal task-state check only after setting `complete`.
+
+## Before Completion
+
+1. Identify changed files.
+2. Match them against `.naome/verification.json`.
+3. Run the required checks when available.
+4. Record proof in `.naome/task-state.json`, including every changed in-scope
+   path reported by git in proof evidence.
+5. Do not list `.naome/task-state.json` as task scope or proof evidence.
+6. Set task state to `complete`.
+7. Run `node .naome/bin/check-task-state.js`.
+8. If the task-state check prints a next-task admission notice, report it to
+   the user with the exact listed options.
+9. If no rule matches or the task check fails, report the gap and ask for human
+   review before claiming completion.
+10. Report changed files, exact commands, results, and remaining risk.
+11. Do not say there are no open gaps while the completed task diff still needs
+    a user baseline decision.
+
+## Commit And Push
+
+- Prefer `naome commit -m "type(scope): summary"` for task baselines.
+- If `naome` is not on `PATH`, run
+  `node .naome/bin/naome.js commit -m "type(scope): summary"`.
+- Manual `git commit` and IDE commits are guarded by local `.git/hooks` shims,
+  but agents must still reconcile Git state because hooks can be bypassed.
+- If a user already committed the diff, compare current `HEAD`, task proof, and
+  remaining working-tree changes before deciding whether to mark the task
+  complete, revise it, or start a new task.

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

@@ -0,0 +1,37 @@
+# Architecture
+
+Status: Uninitialized
+
+## Observed Structure
+
+- Unknown.
+
+## Known Boundaries
+
+- Unknown.
+
+## Assumed Boundaries
+
+- Unknown.
+
+## Dependency Rules
+
+- Unknown.
+
+## Generated Or External Code
+
+- Unknown.
+
+## Evidence
+
+- Unknown.
+
+## Evidence Requirements
+
+- Claims about generated artifacts, harness files, skill directories, or
+  automation policy require exact local evidence paths.
+
+## Open Architecture Questions
+
+- Which modules or directories are authoritative boundaries?
+- Which shortcuts should agents avoid?

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

@@ -0,0 +1,18 @@
+# Decisions
+
+Record durable project decisions that future agents should preserve.
+
+Only record decisions that apply to this target repository. Do not copy global
+skills, previous workspace rules, or unrelated harness policy into this file
+unless the user explicitly confirms that they should become local policy.
+
+## Template
+
+```md
+## YYYY-MM-DD: Decision title
+
+- Decision:
+- Reason:
+- Applies to:
+- Verification or follow-up:
+```

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

@@ -0,0 +1,192 @@
+# NAOME Task Execution
+
+Use this protocol before starting or completing normal feature work.
+
+## Task Admission
+
+Read `.naome/task-state.json` before accepting a new user task.
+
+Before accepting feature work, run:
+
+```sh
+node .naome/bin/check-harness-health.js
+```
+
+Then run:
+
+```sh
+node .naome/bin/check-task-state.js --admission
+```
+
+You may start new feature work only when harness health and admission both pass.
+If health fails, ask the user to choose `repair_harness`,
+`review_harness_diff`, or `cancel_repair_baseline`.
+
+Harness health is a deterministic lifecycle gate, not an agent judgment call.
+When machine-owned harness files are unhealthy, normal task admission,
+progress, completion, commit, and push gates are blocked. Only status, health,
+review, and repair-baseline flows may continue until health is restored.
+
+Also read `.naome/upgrade-state.json`. If upgrade status is
+`needs_agent_upgrade`, do not start feature work. Finish `upgrade.md` first.
+
+Task Control validates the real git diff. After installing or upgrading NAOME,
+ask the user to choose `commit_upgrade_baseline`, `review_diff_first`, or
+`cancel_upgrade_baseline` before starting normal feature work. Admission also
+fails for previous-task, setup, upgrade, or other unowned changes in the git
+diff.
+
+When admission fails because the git diff is dirty, use the exact options it
+prints:
+
+- Harness repair diff: `commit_repair_baseline`, `review_repair_diff`,
+  `cancel_repair_baseline`.
+- Completed task diff: `commit_task_baseline`, `review_task_diff`,
+  `request_task_changes`, `cancel_task_changes`.
+- Install or upgrade diff: `commit_upgrade_baseline`, `review_diff_first`,
+  `cancel_upgrade_baseline`.
+
+Do not commit NAOME install or upgrade changes unless the user explicitly
+chooses `commit_upgrade_baseline`. If they choose it, commit only NAOME install
+or upgrade files.
+
+If `status` is `planning`, `implementing`, `revising`, `verifying`,
+`needs_human_review`, or `blocked`, do not start the new task. Explain the
+active blocker, list the exact human options from `blocker.humanOptions`, and
+ask the user to resolve it first.
+
+Allowed meta-actions while blocked:
+
+- show the blocker
+- approve a listed human option
+- request a smaller diff
+- cancel or mark the active task blocked
+
+## Revisions
+
+Use one task for follow-up corrections that belong to the same unbaselined
+work. If the user chooses `request_task_changes` or asks for a small correction
+while the completed task diff is still open:
+
+- set `status` to `revising`
+- keep the same `activeTask.id`
+- append an `activeTask.revisions[]` entry with `requestedAt`, summarized
+  `request`, exact `userPrompt`, and `proofStale: true`
+- clear or rerun proof before returning to `complete`
+
+If the request expands scope beyond `allowedPaths`, move to
+`needs_human_review` and ask whether to approve the scope change or start a new
+task.
+
+## Start A Task
+
+When starting work, update `.naome/task-state.json`:
+
+- set `status` to `planning`
+- set `activeTask.id` to a short kebab-case id
+- summarize the user request in `activeTask.request`
+- copy the exact task-starting user prompt into `activeTask.userPrompt.text`
+  with `activeTask.userPrompt.receivedAt`
+- record the passed admission check in `activeTask.admission`, including the
+  exact command, exit code, current git HEAD, and empty changed path list
+- set `allowedPaths` to the narrowest expected path list
+- set `declaredChangeTypes` from `.naome/verification.json`
+- set `requiredCheckIds` from the matching change types
+- set `proofResults` to an empty array
+- set `humanReview.required` when matching rules require review
+
+Use exact changed paths, not guessed shortcuts. If the user asks for `README.md`
+but the repository only has `packages/next/README.md`, use the real path or ask
+before editing. If a requested path is a symlink, use the path reported by git
+diff for `allowedPaths` and proof evidence.
+
+Then set `status` to `implementing` only after scope and proof are known.
+Do not include `.naome/task-state.json` in task scope or proof evidence; it is
+NAOME control state, not task work.
+
+## Progress Check
+
+While a task is `planning`, `implementing`, `revising`, or `verifying`, use:
+
+```sh
+node .naome/bin/check-task-state.js --progress
+```
+
+This validates the active task shape, admission record, check IDs, existing
+proof entries, and current diff scope without requiring completion proof. Use
+the normal task-state check only when moving the task to `complete`.
+
+## Human Review
+
+Set `status` to `needs_human_review` when:
+
+- changed files are outside `allowedPaths`
+- required proof is missing or failed
+- human review is required but not approved
+- change type is unknown
+- instructions conflict
+- a risky path or security boundary is touched
+
+Write a short `blocker.message`, affected `blocker.paths`, and concrete
+`blocker.humanOptions`. Run `node .naome/bin/check-task-state.js` after setting
+human review. If it reports missing blocker paths or invalid proof evidence,
+fix the task state before asking the human to choose an option.
+
+## Completion
+
+Before claiming completion:
+
+1. Record every required proof in `activeTask.proofResults`.
+2. Ensure proof evidence includes every changed in-scope path.
+3. Ensure `.naome/task-state.json` is not listed in `allowedPaths` or evidence.
+4. Set `status` to `complete`.
+5. Run `node .naome/bin/check-task-state.js` from the repository root.
+6. If the check fails, move back to `needs_human_review`, `verifying`, or
+   `implementing` as appropriate.
+
+Completion is valid only when the task-state check passes.
+
+Do not reset `.naome/task-state.json` to idle just to hide the completed task.
+The completed task state is part of the task baseline and should be committed
+with the task diff. The next admitted task may overwrite it after the working
+tree is clean.
+
+Deleted-file proof remains valid after baseline when the file was deleted
+between `activeTask.admission.gitHead` and current `HEAD`. The checker uses
+that historical task diff after the working tree is clean, so completed task
+state can stay committed without requiring the deleted file to exist.
+
+If the check passes but prints a next-task admission notice, include that notice
+in the handoff. Ask the user to choose exactly one:
+
+- `commit_task_baseline`: run `naome commit` or
+  `node .naome/bin/naome.js commit` to commit the completed task and NAOME
+  task-state diff.
+- `review_task_diff`: summarize the completed task diff and wait.
+- `request_task_changes`: keep the task open for follow-up changes.
+- `cancel_task_changes`: leave the diff unresolved and do not start new work.
+
+Do not start another feature task until one option is resolved.
+
+## Git Reconciliation
+
+Git is the durable baseline. NAOME task state is working memory. If a user
+commits or pushes outside NAOME, do not assume the harness is broken:
+
+- if `HEAD` changed after admission and the task is now clean and complete,
+  treat the task as externally baselined after proof review
+- if `HEAD` changed while a task is still active, reconcile before continuing
+- prefer a follow-up revision commit over rewriting user commits unless the
+  user explicitly asks to amend or rewrite history
+
+The installed git hooks run commit and push gates, but hooks are guardrails, not
+the source of truth. Checks must still recover from manual Git operations.
+
+## Prompt Records
+
+`request` is a compact working summary. `userPrompt.text` is the exact user
+input that started the task or revision, so task intent survives context
+compaction and agent handoff. Store only user-provided task input. Do not store
+system prompts, developer prompts, outer-agent instructions, or unrelated chat
+history. If the user prompt contains secrets, pause for human review before
+committing task state.