diff --git a/README.md b/README.md index 2a3cb60..c6d7e41 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@

CI + npm version License: Apache-2.0

@@ -29,10 +30,7 @@ Code, Cursor, OpenCode, Copilot CLI, and other coding agents. | Decisions and fixes disappear into old chats | Useful lessons are proposed as Markdown and carried into future tasks once accepted | | The workflow depends on one coding tool | The core works through a CLI, Markdown, JSON, and a command adapter | -New chats do not require another `init`. Ordinary questions need no Noxroot task. Noxroot stays in -the background until code-changing work needs it. - -Example task brief (illustrative excerpt): +Example task brief:

Example Noxroot task brief: preserve project filters on back navigation, with relevant files, related tests, and checks to run @@ -66,28 +64,29 @@ before it runs with `noxroot verify --plan`. ## Set up once +Requires Node.js `>=22.12 <27` and npm. From your repository directory, inspect the proposed setup: + ```bash -npx noxroot@latest init +npx noxroot@latest preview ``` -Then keep talking to your coding agent normally: +When ready, initialize once: -```text -Fix project filters resetting on back navigation. +```bash +npx noxroot@latest init ``` -For a code-changing task, compatible agents are instructed to use the pinned repository commands -behind the scenes: +Commit the reviewed setup before your first code-changing task; `start` requires a clean Git +baseline. -```bash -npx --yes noxroot@0.1.0 start "fix project filters resetting on back navigation" -# your existing coding agent builds the change -npx --yes noxroot@0.1.0 finish -``` +Then keep talking to your coding agent normally. Ask for your own feature, fix, or refactor. For +code-changing tasks, compatible agents are instructed to run `start` before editing and `finish` +when the change is ready to check, using the version pinned in your repository. Run `init` once per repository. It previews a thin managed entrypoint, preserves existing -documentation, and pins the Noxroot version. The pinned `npx` command needs no global or project -installation. +documentation, and pins the Noxroot version. `npx` downloads the package into npm's cache; no global +installation or clone of Noxroot is needed. The package is available on +[npm](https://www.npmjs.com/package/noxroot). Before setup, preview labels each capability `create`, `reuse`, `adjacent`, `conflict`, or `not-assessed`. Noxroot creates only a confirmed gap. Existing systems stay in place. Missing @@ -97,11 +96,18 @@ review, and learning. A coordination ledger or session journal is reported as ad preserve work across sessions, but Noxroot does not import its log or treat it as a development coordinator. -Questions, explanations, reviews, and other read-only work do not create tasks. If a new -conversation continues the same task in the same repository, branch, and worktree, `start` reuses -the active baseline instead of creating a duplicate. `finish` finds the task when exactly one -matches. If several tasks match, Noxroot lists them and requires `--task ` instead of guessing. -Instruction discovery varies by coding tool, so the commands remain available for manual use. +Read-only work creates no task. In the same repository, branch, and worktree, a repeated `start` +continues the active baseline. `finish` infers a single matching task; several matches require +`--task `. Commands remain available for manual use when an agent does not follow the +instructions. + +When upgrading, inspect the managed instruction changes with +`npx noxroot@latest sync --dry-run --diff`. Apply them with `npx noxroot@latest sync` after review. +Starting a new chat does not require an upgrade or another initialization. See the +[command reference](docs/commands.md) for manual tasks and sync limits. + +For the first change, continuation, and troubleshooting, read +[Getting started](docs/getting-started.md). ### What setup can add @@ -121,10 +127,8 @@ remains discoverable without being copied. Existing `.git/noxroot` records stay in place, without a second store. If an agent cannot write task state, it must stop and request access before continuing. -`SKILL.md` files are portable, on-demand instructions. The generated verification skill tells an -agent how to check a change; the independent-review and optional product/UX skills describe their -reviews. Context loading comes from `AGENTS.md`, the knowledge index, and context routes, not a -generated context skill. Learning comes from `finish` and `learn`, not a generated learning skill. +`SKILL.md` files are portable instructions for verification and review. `AGENTS.md`, the knowledge +index, and routes guide context loading. `finish` and `learn` handle learning proposals. Skills are instructions, not test evidence. Incomplete work cannot become approved. Noxroot does not push, merge, publish, or deploy. @@ -136,7 +140,13 @@ permission to edit. "Do not deploy" remains an exclusion; it never activates dep Large files get bounded line ranges when relevant text is found. Partial context is labelled; agents still inspect the surrounding code. Existing routes stay unchanged. -## Try the read-only diagnosis +## Preview example + +`preview` reports what Noxroot found and what setup would add. Use `preview --diff` to inspect the +proposed patches before writing anything. + +

+See a sample preview and run it from source To try Noxroot from source, use Node.js `>=22.12 <27`: @@ -175,8 +185,9 @@ Next npx --yes noxroot@0.1.0 preview --diff ``` -Use `preview --diff` to inspect every proposed setup patch. The intended beta entry point is -`npx noxroot@latest preview`. +
+ +For local development and validation commands, see [Development](docs/development.md). ## Portable by design @@ -184,8 +195,7 @@ Noxroot's universal interface is the CLI plus generated Markdown and JSON. Any a command or read a task package can use it. The generic adapter accepts an explicit executable and literal arguments. It does not guess vendor flags or use shell interpolation. -Instruction discovery varies by client. Some tools read `AGENTS.md`, others use their own files, and -some require manual invocation. Noxroot does not claim equal native integration everywhere. +Instruction discovery varies by client. Native integration is not identical across tools. Application-agent frameworks are detected project architectures, not competitors or dependencies. Their tests and evals can become approved repository checks. Noxroot does not install or control @@ -204,9 +214,9 @@ Python, Go, Rust, and other stacks. CI covers Windows, macOS, and Linux. `learn --task ID` shows confirmable durable proposals. Data commands support `--json`, with progress and diagnostics on standard error. -Read the [command reference](docs/commands.md), [configuration](docs/configuration.md), -[architecture](docs/architecture.md), [adapter protocol](docs/adapters.md), and -[security boundaries](docs/security.md). +Read [Getting started](docs/getting-started.md), the [command reference](docs/commands.md), +[configuration](docs/configuration.md), [architecture](docs/architecture.md), +[adapter protocol](docs/adapters.md), and [security boundaries](docs/security.md). Noxroot is an experimental v0.1 MVP. Apache-2.0; see [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [LICENSE](LICENSE). diff --git a/docs/adapters.md b/docs/adapters.md index 873d73b..c977ece 100644 --- a/docs/adapters.md +++ b/docs/adapters.md @@ -1,5 +1,10 @@ # Agent and verification adapters +You do not need to configure an adapter to use Noxroot with your existing coding agent. After setup, +compatible agents follow the repository instructions and call the CLI themselves. Command adapters +let Noxroot launch optional delegated workers through `run` or automated reviewers through `run` and +`finish`. + ## Manual The default adapter emits the complete task package for use in any agent or chat. It reports zero @@ -14,6 +19,10 @@ receives one JSON line on standard input: { "role": "worker", "taskPackage": { "task": "..." } } ``` +The executable must understand this protocol. A vendor CLI name alone does not make it compatible; +use documented arguments or a wrapper that translates the task package. Install and authenticate +that tool separately. Noxroot does not supply provider accounts, credentials, or model access. + Roles are `worker`, `repair`, and `reviewer`. An automated reviewer must write exactly one JSON object to standard output with `decision`, `summary`, `findings`, and `learningCandidates`. Findings require severity, evidence, and required outcome; optional paths are repository-relative. Prose, diff --git a/docs/architecture.md b/docs/architecture.md index b9ce4d2..cdfd5b7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -3,8 +3,13 @@ Noxroot is one Node.js/TypeScript package. The CLI layer parses input and keeps machine output separate from diagnostics. Core functions return typed values and do not write implicitly. Detection uses bounded filesystem APIs, groups repeated monorepo evidence, and never runs project code or an -LLM. Proposal generation produces complete file contents and unified creation patches. -Initialization is the only component that applies those proposals. +LLM. Proposal generation produces complete file contents and unified creation patches. The shared +setup writer applies those proposals for `init` and `sync`. + +The npm package runs locally; distribution does not add a hosted service or a second agent. In the +normal workflow, an existing coding agent invokes `start` and `finish` through repository +instructions. The optional `run` adapter is a separate delegated workflow, not an onboarding +requirement. New CLI versions do not silently migrate task state or replace repository-owned rules. Root `AGENTS.md` and `CLAUDE.md` remain instruction evidence when Git ignores them. Explicit sensitive-path exclusions and symlink protections still apply. Ordinary ignored files stay excluded. diff --git a/docs/commands.md b/docs/commands.md index 610feed..f771155 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -1,5 +1,14 @@ # Command reference +## Run from npm + +From your repository directory, run `npx noxroot@latest preview` to inspect setup without writing +files, then `npx noxroot@latest init` when ready. Requires Node.js `>=22.12 <27` and npm. + +Commands below use `noxroot` as shorthand. Without a global installation, use +`npx --yes noxroot@0.1.0` in its place, or the version pinned in your repository instructions. +Compatible agents handle `start` and `finish`; you do not need to type them for each conversation. + ## Global behavior `noxroot --help`, `noxroot --help`, and `noxroot --version` are stable discovery surfaces. @@ -38,9 +47,10 @@ to one contained project with `--root` before initialization. ## `init` and `sync` -`init` creates only files in the reviewed proposal. It checks every target again before writing, -writes each file through a same-directory temporary file, and rolls back files it created if the -operation fails. Existing files are never overwritten. +`init` applies only reviewed file creations and managed patches. It checks every target before +writing, guards patches with the reviewed content hash, and writes through same-directory temporary +files. On failure it attempts to restore patched files and remove newly created files. Unmanaged +content is preserved; setup is not a transaction against concurrent filesystem changes. Explicitly referenced project knowledge, task routes, Agent Skills, and documented verification wrappers are reused rather than copied. Noxroot does not integrate with or replace an existing @@ -70,11 +80,15 @@ does not broadly rewrite the repository. ## `context` -`context "task"` shows the outcome, a bounded selection of paths, likely source and tests, approved -checks with their working directories, an exclusion count, and estimated tokens. Exclusions and -conflicts remain visible. `--verbose` adds every selected path, selection reasons, individual +`context "task"` shows the outcome, a bounded selection of paths, relevant files and related tests, +approved checks with their working directories, an exclusion count, and estimated tokens. Exclusions +and conflicts remain visible. `--verbose` adds every selected path, selection reasons, individual exclusions, unknowns, and byte counts. JSON retains the complete bounded context package. +The human headings are `Relevant files`, `Related tests`, and `Checks to run`. Selection is +advisory; listed checks have not run. JSON keeps the existing `likelyOwningSource`, `likelyTests`, +and `requiredVerification` fields. + Large source and test files can be selected as up to three line ranges rather than whole files. Human output labels these as partial. JSON adds `lineRanges` (one-based, inclusive) and `sourceBytes`; `bytes` counts only the selected ranges. These are reading hints, not embedded code diff --git a/docs/configuration.md b/docs/configuration.md index ba9db3b..4f635ac 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -3,6 +3,10 @@ `.noxroot/config.yml` uses schema version 1. Invalid values produce a file and field path. Versions other than 1 are rejected instead of guessed. +Start with the configuration proposed by `init`; do not replace it with this reference example. +Schema version `1` is separate from the npm package version. Updating the CLI does not authorize new +checks or rewrite your task routes. + ```yaml version: 1 modules: @@ -20,7 +24,7 @@ autonomy: merge: 0 delivery: 0 agents: - default: local-agent + default: manual adapters: manual: type: manual @@ -49,6 +53,12 @@ browser: - { name: mobile, width: 390, height: 844 } ``` +The optional `local-agent` entry illustrates the adapter shape, not working flags for a particular +coding tool. Leave `manual` selected for the normal workflow where your existing agent calls +Noxroot. Command adapters are optional for delegated workers or automated review; see the +[adapter protocol](adapters.md). The sample `browser-e2e` id must refer to a check you actually +approved before enabling `browser`. + Autonomy is enforced, never descriptive-only: level 0 permits read-only diagnosis/context/plans; implementation level 1 permits guided records; implementation level 2 permits a configured worker; review level 3 permits independent reviewer and bounded repair calls. Higher configured values are diff --git a/docs/development.md b/docs/development.md index bbfbb0e..063bcf5 100644 --- a/docs/development.md +++ b/docs/development.md @@ -38,8 +38,13 @@ Before adding a dependency, explain why a platform API is insufficient. Producti limited to command parsing, schema validation, and YAML. Before claiming a new project shape or adapter, add a realistic fixture and failure-path coverage. -Publication is not part of ordinary development. The owner must first create the npm package, -configure npm trusted publishing for the exact GitHub repository/workflow on a GitHub-hosted runner, -and authorize adding a publish workflow with `id-token: write`. Do not create or store a long-lived -npm publication token. Trusted publishing automatically supplies provenance for eligible public -packages. +When working inside the Noxroot source checkout, use `node dist/cli.js` after building. `npx` can +resolve this checkout's package instead of the registry package, without an installed command shim. + +`noxroot@0.1.0` is published on npm. Publication is not part of ordinary development. Future +automated releases require the owner to configure npm trusted publishing for the exact GitHub +repository and workflow, and authorize a publish workflow with `id-token: write` on a GitHub-hosted +runner. That workflow is not configured yet. Do not create or store a long-lived npm publication +token. Trusted publishing supplies provenance for eligible public packages; the first manual release +does not have that provenance. npm's displayed README updates only when a new package version is +published. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..c465103 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,93 @@ +# Getting started + +Use Noxroot in a repository you already work on, with your usual coding agent. You need Node.js +`>=22.12 <27`, npm, and a Git repository with a committed baseline for code-changing tasks. No +global Noxroot installation is required. + +## 1. Preview your repository + +Open a terminal in your project directory: + +```bash +npx noxroot@latest preview --diff +``` + +Noxroot shows what it found, what it would reuse, and the exact files setup would change. Preview +does not modify the project or run its commands. npm may download the CLI first. + +Check that it found your existing instructions and documentation. Look at proposed verification +commands and their working directories. Missing evidence should remain visible, not become a guessed +command. For a repository of independent examples, select one project with `--root`. + +## 2. Confirm setup once + +```bash +npx noxroot@latest init +``` + +Review the patches and approve only what belongs in this repository. Existing documentation stays in +place. Compatible agent instructions receive a pinned Noxroot command. + +Review and commit the accepted setup changes before the first code-changing task. `start` requires a +clean committed Git baseline. Keep unrelated edits separate; do not discard them to make the working +tree clean. + +If another coordinator owns development work, Noxroot can offer companion setup for context and +verification. It does not take over that coordinator's lifecycle, reviews, or learning. + +## 3. Ask your agent for a real change + +Choose a small feature, fix, or refactor you already need. Describe it normally, including anything +the agent must not change. You do not need a Noxroot-specific prompt. + +In full mode, compatible agents are instructed to: + +1. Run `start` before editing to record a baseline and receive the task brief. +2. Inspect the relevant files and project rules, then make the change. +3. Run `finish` to check the actual diff and report remaining gaps or required review. + +Noxroot does not install native client hooks. Instructions guide agents; they cannot guarantee +compliance. For your first task, check the agent's command history for `start` and `finish`. If they +are missing, ask it to follow the repository instructions. See the [command reference](commands.md) +for manual use. + +## 4. Check the result + +The handoff should name the changed files, commands that ran, failures, and anything unverified. +Passing checks do not satisfy a required review. A task with incomplete verification is not +approved. + +Useful lessons can be proposed for documentation after the task. Review those proposals before +applying them. No learning candidate is a valid outcome; every change does not need another +document. + +For your first few tasks, ask: + +- Did the brief surface a relevant rule or file without loading unrelated material? +- Did the checks catch a problem or provide evidence you can inspect? +- Was useful knowledge reused next time, without duplicating existing docs? + +These are usefulness checks, not a requirement to keep a session journal. + +## Continue later + +Open the same repository, branch, and worktree and keep working with your agent. Repeating `start` +for the same active task continues its baseline. A new chat needs neither another `init` nor a task +for ordinary questions. Local task state is not chat restoration or cross-machine synchronization. + +## If something looks wrong + +Use the pinned version from your repository instructions. For the first release: + +```bash +npx --yes noxroot@0.1.0 doctor +npx --yes noxroot@0.1.0 status +``` + +`doctor` checks configuration; it does not prove your agent follows instructions. `status` shows +active tasks and next actions. If task-state writes are blocked, stop before editing and approve +only the required access. Do not disable the sandbox. If several tasks match, select the intended +task instead of guessing. + +For upgrades, review the [sync procedure](commands.md#init-and-sync). For Noxroot's own source +checkout, use the [development instructions](development.md). diff --git a/docs/security.md b/docs/security.md index 4c32d1f..e220605 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,7 +1,7 @@ # Security and privacy model -Repository contents and agent output are untrusted. Detection follows neither symlinks nor -repository instructions, skips built-in generated/vendor directories, applies common `.gitignore` +Repository contents and agent output are untrusted. Detection does not follow symlinks or execute +repository instructions. It skips built-in generated/vendor directories, applies common `.gitignore` rules, and never reads suspected secret files. Paths proposed for reads, writes, and process working directories are resolved against the selected repository. Ordinary source and documentation remain data; only designated Noxroot configuration and repository instruction files receive semantics. @@ -9,8 +9,10 @@ data; only designated Noxroot configuration and repository instruction files rec Preview has no injected write, process, agent, network, telemetry, or local-state capability. Its implementation uses canonical path resolution and bounded filesystem inspection only. Tests hash the full fixture tree before and after preview, use scripts that would leave a marker if executed, block -symlink escapes, and assert secret values never reach output. Package-manager retrieval, when a user -chooses it after publication, occurs outside the runtime preview boundary. +symlink escapes, and assert secret values never reach output. `npx` may contact npm to download the +CLI and its dependencies before Noxroot starts. That retrieval is outside the runtime preview +boundary; the full `npx` invocation is not guaranteed offline. Generated lifecycle instructions pin +the package version. Review `sync --dry-run --diff` before changing that pin. Mutating setup shows complete patches, rechecks target absence or the reviewed content hash, and refuses symbolic links and junctions at write destinations or their ancestors. It checks all diff --git a/tests/acceptance/npm-readme-review-2026-09-04.json b/tests/acceptance/npm-readme-review-2026-09-04.json new file mode 100644 index 0000000..fc92f3a --- /dev/null +++ b/tests/acceptance/npm-readme-review-2026-09-04.json @@ -0,0 +1,6 @@ +{ + "decision": "approved", + "summary": "Re-reviewed the docs-only corrections. README and Getting started now require reviewed setup changes to be committed before the first task, explicitly preserving unrelated edits. Adapter documentation correctly includes automated review during finish while keeping manual mode the normal default. The generic onboarding, npm-download versus runtime-preview boundary, uncertainty disclosures, and safety limits remain accurate. All 8 focused documentation tests and git diff --check passed. Both previous findings are resolved. No reviewer edits or publication actions were performed.", + "findings": [], + "learningCandidates": [] +} diff --git a/tests/documentation.test.ts b/tests/documentation.test.ts index 5a88a77..9ff7cc7 100644 --- a/tests/documentation.test.ts +++ b/tests/documentation.test.ts @@ -4,6 +4,8 @@ import { describe, expect, it } from "vitest"; import { previewRepository } from "../src/core/preview.js"; import { renderPreview } from "../src/output.js"; import { fixtures } from "./helpers.js"; +import { parse } from "yaml"; +import { noxrootConfigSchema, verificationConfigSchema } from "../src/config/schema.js"; describe("documentation examples", () => { it("keeps the README opening and preview excerpt synchronized with a real fixture", async () => { @@ -17,7 +19,7 @@ describe("documentation examples", () => { expect(readme).toContain( "A CLI for project memory, focused task briefs, approved checks, and reusable documentation.", ); - expect(readme).toContain("Then keep talking to your coding agent normally:"); + expect(readme).toContain("Then keep talking to your coding agent normally."); expect(readme).toContain("actions/workflows/ci.yml/badge.svg?branch=main"); expect(readme).toContain("license-Apache--2.0-blue.svg"); const output = renderPreview(await previewRepository(path.join(fixtures, "typescript"))); @@ -35,9 +37,66 @@ describe("documentation examples", () => { } }); + it("offers generic npm onboarding without a copyable project-specific task", async () => { + const readme = await readFile(path.resolve("README.md"), "utf8"); + const setup = readme.split("## Set up once")[1]!.split("### What setup can add")[0]!; + expect(readme).toContain('href="https://www.npmjs.com/package/noxroot"'); + expect(readme).toContain("https://img.shields.io/npm/v/noxroot"); + expect(setup).toContain("Node.js `>=22.12 <27`"); + expect(setup).toContain("npx noxroot@latest preview"); + expect(setup).toContain("npx noxroot@latest init"); + expect(setup).toContain("Commit the reviewed setup"); + expect(setup).not.toMatch(/filters|restaurants|```text/); + expect(setup).toContain("compatible agents are instructed"); + expect(readme).not.toMatch(/not published to npm yet|intended beta entry point/); + }); + + it("keeps reference configuration valid and delegated agents opt-in", async () => { + const documentation = await readFile(path.resolve("docs/configuration.md"), "utf8"); + const examples = [...documentation.matchAll(/```yaml\n([\s\S]*?)\n```/g)]; + const config = noxrootConfigSchema.parse(parse(examples[0]![1]!)); + expect(config.agents.default).toBe("manual"); + expect(config.agents.adapters.manual).toEqual({ type: "manual" }); + expect(verificationConfigSchema.parse(parse(examples[1]![1]!)).commands[0]?.cwd).toBe("."); + expect(documentation).toContain("not working flags for a particular"); + }); + + it("keeps the linked guides navigable and explains npm and adapter boundaries", async () => { + for (const name of [ + "getting-started", + "commands", + "configuration", + "architecture", + "adapters", + "security", + "development", + ]) { + const documentation = await readFile(path.resolve(`docs/${name}.md`), "utf8"); + for (const match of documentation.matchAll(/!?\[[^\]]*\]\(([^)]+)\)/g)) { + if (/^(?:https?:|mailto:|#)/.test(match[1]!)) continue; + await expect( + access(path.resolve("docs", match[1]!.split("#")[0]!)), + ).resolves.toBeUndefined(); + } + } + const commands = await readFile(path.resolve("docs/commands.md"), "utf8"); + expect(commands).toContain("npx --yes noxroot@0.1.0"); + expect(commands).toContain("`Relevant files`, `Related tests`, and `Checks to run`"); + const security = await readFile(path.resolve("docs/security.md"), "utf8"); + expect(security).toContain("the full `npx` invocation is not guaranteed offline"); + const adapters = await readFile(path.resolve("docs/adapters.md"), "utf8"); + expect(adapters).toContain("You do not need to configure an adapter"); + expect(adapters).toContain("automated reviewers"); + const guide = await readFile(path.resolve("docs/getting-started.md"), "utf8"); + const setupStep = guide.split("## 2. Confirm setup once")[1]!.split("## 3.")[0]!; + expect(setupStep).toContain("commit the accepted setup changes"); + expect(setupStep).toContain("Keep unrelated edits separate"); + }); + it("labels the terminal illustration without inventing a successful run", async () => { const readme = await readFile(path.resolve("README.md"), "utf8"); - expect(readme).toContain("Example task brief (illustrative excerpt):"); + expect(readme).toContain("Example task brief:"); + expect(readme).not.toContain("(illustrative excerpt)"); expect(readme).toContain( '`context ""` is read-only. It does not start a task or run checks.', );