O'CodingNavigator (OCN)

Local-first, MCP-first, state-machine-driven AI coding workflow operating system. CLI: ocn · MCP: ocn-mcp · License: Apache-2.0 Phase: SOP profile 0.9.0 mainline (Outcome Backbone, AM-017/DEC-043) + optional Auto Mode (AM-009) + optional Contract Backbone (AM-012) · Status: pre-GA beta · Public: on npm as latest and @beta → 0.9.0-beta.1 · GitHub pre-release: v0.9.0-beta.1

📑 This README has two parts: Part 1 — English (sections 1 – 11) · Part 2 — 中文版 (§§ A – K) 本 README 分两部分阅读：先看英文（§§ 1–11），中文从下方 §A 开始。

Part 1 · English

OCN turns AI coding from continuous-chat improvisation into a navigable, gated, auditable, reviewable systems-engineering process. It is a navigator, not an IDE, not a SaaS, not a project-management board.

Table of contents (English)

Understand OCN

1. What OCN is
2. Why OCN exists
3. Current status
   • 3.1 Two-stage product model

Use OCN 4. Install 5. First 5 minutes

• 5.4 Full walkthrough: how it looks inside Claude Code
• 5.5 Adopting OCN mid-project
• 5.6 Post-plan execution flow

6. Core CLI commands
   • 6.1 Planning Gatekeeper commands
   • 6.2 Execution Navigator commands
7. MCP tools

Reference 8. Documentation map 9. Development 10. Roadmap 11. License

Understand OCN

1. What OCN is

OCN is the local discipline layer for AI coding. It runs on your machine, persists everything to plain files (Markdown + JSON + JSONL + YAML), exposes a small CLI for humans, and a small MCP server for agents. There is no cloud component.

OCN sells discipline — productized as:

• a state machine (DISCOVERY → SPEC → DESIGN → PLAN → BUILD → VERIFY → SHIP → REFLECT) with forward-only transitions,
• a Step Artifact Gate that blocks advancement when the current step's required sections are missing,
• a dual-track audit trail (.ocoding/audit/audit-events.jsonl + docs/22-audit-trail.md),
• a Logic Backbone (SOP 0.3.0) — a DESIGN-phase artifact whose computation/decision graph is machine-validated; ocn check blocks on orphan scores, dangling references, cycles, and unbound triggers, so the system's logic is wired before BUILD,
• a Readiness Backbone (SOP 0.4.0) — a role-based cross-cutting readiness gate: 55 falsifiable checks derived from 54 curated IT roles (developer, QA, DevOps, CISO, service desk, …) run inside ocn check / ocn gate / ocn advance on every step; open-world semantics mean both FAIL and UNKNOWN block (silence is not a pass), catching role-blind completion before SHIP,
• a Task Backbone (new in SOP 0.5.0) — build plans carry machine-parseable Task Spec blocks (goal / traces / touches / verify / DoD); the build-plan gate validates six hard defects and freezes each task's verify-command hash into .ocoding/task-ledger.json; a task is done only when ocn task check reruns the frozen command and it exits 0, and ocn advance out of BUILD is blocked while tasks are pending — closing the fourth false-completion class, receipt-only completion,
• an Acceptance Backbone (new in SOP 0.8.0) — docs/03-acceptance-criteria.md carries a machine-parseable ## Acceptance Specs｜验收规格 section (### AC-<DOMAIN>-<n> blocks); the acceptance gate runs at step_acceptance_criteria, hard-blocks four structural defects (no_specs, duplicate_id, invalid_id, missing_field), and on pass freezes .ocoding/acceptance-specs.json — the canonical machine source of AC ids that build-plan traces bind to, closing the hole where AC written in a table silently didn't register,
• a safe MCP surface that lets agents read, prepare, and create artifacts but never advance state, capture decisions, reset the project, or force-release the lock.

OCN is not a code generator, an IDE, a SaaS, a project-management tool, a notes app, or a scaffold-only doc factory.

2. Why OCN exists

Working with an AI coding agent for any non-trivial task tends to fail in four ways:

| Failure | Symptom | |---|---| | lost | Nobody — human or AI — knows which step the project is on. | | drift | The agent keeps generating, but each new chunk is further from the original requirement. | | amnesia | A new chat starts and the agent re-derives what the previous chat already decided. | | false-completion | A document exists on disk, but it's missing a required section. The agent declares "done" anyway. |

OCN treats these as the same problem: the AI coding loop has no rigorous notion of "where we are" and "what counts as done". OCN supplies both as code, not as exhortation.

3. Current status (SOP 0.8.0 (Acceptance Backbone) mainline)

| | | |---|---| | Phase | SOP 0.8.0 (Acceptance Backbone) mainline — Plan → Build → Verify, with the machine-verified DESIGN logic-backbone gate, a role-based cross-cutting readiness gate (55 checks) on every step, a frozen-verify task ledger that gates BUILD exit, and a SPEC-phase acceptance gate that freezes the canonical AC ids; plan-to-verify smoke covers all 20 steps | | Tests | full vitest suite green on Node 20 + Node 22 | | Coverage | meets the publish-time gate | | npm | latest → 0.9.0-beta.1; beta → 0.9.0-beta.1; alpha → 0.1.0-alpha.2 (historical; preserved) | | Maturity | pre-GA beta — not stable, not GA, beta only (for controlled testing / dogfood) | | External host validation | Validated with Claude Desktop on Windows with WSL2. Cursor and Cline are not yet verified. | | MCP transport | stdio only (HTTP/SSE not started) |

2026-05-04 republish note: Republished as 0.2.0-beta.2 to ship the Execution Navigator commands (exec status, github analyze-pr, evidence map, next-prompt, verify status, verdict draft) that were merged after 0.2.0-beta.1 was packaged. The README documentation and the published CLI binary now match.

3.1 Two-stage product model

OCN now works in two connected phases:

1. Planning Gatekeeper — define scope, architecture, acceptance, and build plan before implementation. Drives state_discovery → state_plan, gates artifact completion, and is the surface covered by §6.1.
2. Execution Evidence Navigator — read git, GitHub PR, acceptance evidence, and verification signals during implementation. Six new read-only commands (§6.2) summarise that evidence and draft the next agent prompt, the verification readiness signal, and the final verdict. They never mutate state, never call an LLM, never run npm/gh mutating commands.

The two stages are connected: planning artifacts (00–10) must pass their gates before the execution stage's evidence map, verify status, and verdict draft can read meaningful inputs. Authoritative reframe: DEC-024. Series closure report: docs/reports/2026-05-04-execution-navigator-verdict-draft.md.

Implemented

• CLI: init, status, brief, doc create, check, gate, advance (full list in §6).
• State machine: 8 states, forward-only transitions; DISCOVERY → PLAN have stable-ID steps wired (BUILD / VERIFY / SHIP / REFLECT have state IDs only — steps deferred).
• Step Artifact Gate: required-section detection with NFKC-normalised heading match for bilingual Title｜标题 headings.
• State safety: .ocoding/.lock (5 s timeout + stale recovery), state.json.bak rolling backup, atomic temp-rename writes; concurrent-advance race fixed (post-Codex P1).
• Audit: dual-track persistence, 16 event types, correlationId threading across the entire ocn advance event chain.
• MCP safe tools: 7 read/prepare/create/log tools over stdio; 4 forbidden tools never registered (full list in §7); projectRoot validator + threat model (docs/security/mcp-threat-model.md).
• Real MCP Host validation: Claude Desktop on Windows with WSL2 validated end-to-end (DEC-017, report). Cursor and Cline remain unverified.
• Executable example: examples/discovery-to-plan/ walks all 10 v1.0 SOP steps end-to-end via scripts/smoke.sh. Bundled fixtures derived verbatim from src/core/templates/*.ts so they cannot drift.
• npm publish discipline: published as [email protected] (per DEC-039 the npm package version and the SOP profile version are unified and move in lockstep — both 0.8.0) under strict pre-publish checklists, prepublishOnly gate, and files allowlist. latest and beta both point to 0.9.0-beta.1; alpha is preserved at 0.1.0-alpha.2 for historical use. Annotated git tags and matching GitHub pre-releases published per beta.

Not implemented (deliberately deferred — see §10)

ocn doctor, ocn reset, ocn baseline, SOP versioning / upgrade, production / full tiers, mini-CRM dogfood, real-Host validation for Cursor / Cline (DEC-019), remote MCP transport, MCP auth.

Use OCN

4. Install

4.1 Recommended: install from npm

npm install -g o-coding-navigation

As of v0.9.0-beta.1, npm latest and beta both point to the SOP profile 0.8.0 release (Acceptance Backbone, AM-015/DEC-041) plus optional Auto Mode (AM-009) and optional Contract Backbone (AM-012). Note: per DEC-039 the npm package version and the SOP profile version are now unified and move in lockstep (both 0.8.0); SOP profile 0.8.0 adds the Acceptance Backbone on top of 0.7.0, and older profiles stay frozen + importable.

Verify:

ocn --version       # 0.9.0-beta.1
ocn --help
ocn-mcp             # starts the MCP stdio server; press Ctrl+C to exit

Use @beta when you want to pin the prerelease channel explicitly:

npm install -g o-coding-navigation@beta

To uninstall: npm uninstall -g o-coding-navigation.

4.2 Currently published channels

| Channel | Version | npm tag | Notes | |---|---|---|---| | latest (recommended) | 0.9.0-beta.1 | latest | SOP profile 0.8.0 mainline (Acceptance Backbone) + optional Auto Mode (AM-009). | | Beta (explicit prerelease pin) | 0.9.0-beta.1 | beta | Same artifact as latest; use @beta when you want to pin the prerelease channel explicitly. | | Alpha (still available) | 0.1.0-alpha.2 | alpha | Prior pre-GA channel; preserved for historical use only. |

Package home: https://www.npmjs.com/package/o-coding-navigation

Prerequisites: Node.js ≥ 20 (see engines in package.json).

Pre-GA caveat: this is a pre-GA beta release — beta only, intended for controlled testing / dogfood, not GA. Validated with Claude Desktop on Windows with WSL2. Cursor and Cline are not yet verified.

4.3 Alternative: local development from source

For contributing or local development:

git clone https://github.com/UncleTIM-GZ/O-CodingNavigation.git
cd O-CodingNavigation
npm install
npm run build
npm link              # exposes `ocn` and `ocn-mcp` on PATH

To uninstall the global links: cd O-CodingNavigation && npm unlink -g ocn ocn-mcp.

If you prefer not to npm link, run the CLI in-place via node /path/to/O-CodingNavigation/dist/cli/index.js ….

5. First 5 minutes

5.1 The minimal happy path

mkdir ocn-demo && cd ocn-demo

ocn init                        # creates .ocoding/ and docs/
ocn status                      # state_discovery / step_project_brief

ocn doc create project-brief    # creates docs/00-project-brief.md (template)
# Now edit docs/00-project-brief.md and fill in the 4 required sections:
#   Problem · Goal · Users · Success Criteria

ocn gate                        # read-only — confirms the gate now passes
ocn advance                     # gate + state mutation + audit trail
ocn status                      # state_discovery / step_scope (advanced)

ocn brief                       # session brief for an AI coding agent

5.2 What each command produces

• init writes .ocoding/state.json, .ocoding/sop.yaml, the dual-track audit files, and a docs/ skeleton.
• status reports currentStateId: state_discovery / currentStepId: step_project_brief.
• doc create writes docs/00-project-brief.md with bilingual section headings already in place.
• gate returns OK (exit 0) once the 4 required sections are filled in, or ERR_GATE_FAILED (exit 1) with a bilingual list of missing sections.
• advance writes a correlationId-tagged chain of audit events: advance_started → artifact_gate_run → artifact_gate_passed → state_transitioned → state_write_succeeded → advance_succeeded.
• brief prints the current-step required sections + AI governance reminders so a coding agent can resume without re-reading docs.

A more detailed walkthrough lives in docs/quickstart.md, including the expected file tree and common errors.

5.3 Try the executable example

For an end-to-end example that walks all 10 v1.0 SOP steps against a hermetic temp project, see examples/discovery-to-plan/ and run:

npm run build
bash examples/discovery-to-plan/scripts/smoke.sh

The smoke prints the final state and exits with Discovery-to-plan smoke completed. It does not modify your environment.

5.4 Full walkthrough: how it looks inside Claude Code

OCN is MCP-first by design. Inside Claude Code (or any other MCP host wired to ocn-mcp — Claude Desktop is the validated path per §7.1), you almost never need to remember an OCN command. You speak natural language; the AI calls the right OCN MCP tool; the flow runs itself. The one and only step that must be typed by you in a terminal is the state-advance step — that is OCN's design guardrail, not a bug.

Prerequisite: ocn-mcp wired into your MCP host as in §7.1. The validated host is Claude Desktop on Windows + WSL2 (DEC-017); other MCP hosts behave the same but are not yet validated (DEC-019).

Below is the full flow in 8 steps. For each step you get three things: what you say → what the AI does behind the scenes → what you see back.

Phase 1: one-time setup (do once per project)

Step 1. Initialise OCN

• You say: "Initialise OCN in the current directory."
• AI does: shells out via Bash to run ocn init (init is not an MCP tool — it must be a shell call).
• You see: .ocoding/ and docs/ created; project initialised at state_discovery / step_project_brief.

Step 2. Confirm location

• You say: "Which step is OCN on?"
• AI does: calls MCP tool navigator.where_am_i.
• You see: current state, current step, artifact path, suggested next action.

Phase 2: the per-step loop (repeat for every step)

Assume you're sitting on step_project_brief. Steps 3–8 close out one step; the next step uses the same loop.

Step 3. Pull this step's brief

• You say: "Tell me what to do for the current step."
• AI does: calls MCP tool navigator.brief.
• You see: required sections, governance reminders, uncertainty policy. These enter the AI's context so it follows the rules when writing the artifact.

Step 4. Create the artifact template

• You say: "Create the template for the current step's artifact."
• AI does: calls MCP tool navigator.create_artifact with type project-brief.
• You see: docs/00-project-brief.md written from the bundled template, with bilingual section headings in place.

Step 5. Fill out the artifact

• You say: "Fill out the artifact according to the brief. Our project is [your description]."
• AI does: based on the brief's required sections + your description, edits docs/00-project-brief.md directly via its Edit tool to fill Problem / Goal / Users / Success Criteria.
• You see: a filled-in markdown. Iterate until you're satisfied.

Step 6. Verify the artifact

• You say: "Check whether the current artifact passes the gate."
• AI does: calls MCP tool navigator.run_gate.
• You see: pass → AI says "gate passed"; fail → AI lists the missing sections and offers to fix them. On fail, return to Step 5.

Step 7. You type ocn advance yourself

⚠️ This is the one step in the entire flow that you must do yourself. The AI cannot do it for you.

After Step 6 passes, a disciplined AI will tell you:

"Gate passed. To advance, please run ocn advance in your terminal."

Why won't the AI just run it? Two reasons, both load-bearing:

1. MCP does not expose advance. navigator.advance_phase is one of the four tools in §7.3 that is never registered. From the MCP path, the AI literally has no advance tool.
2. OCN's AI governance rules reserve advance for humans. State advancement = project milestone = the sentence "we are now in the next phase" must be spoken by a human. Letting the AI say it would degrade OCN into one more autonomous scaffolder — exactly the failure mode OCN exists to prevent.

So open a terminal and run:

ocn advance

advance re-runs the gate internally, and on pass writes state.json under a lock with rolling backup and emits the full correlationId-tagged audit chain.

If you don't want to switch to a terminal, you can explicitly ask the AI to run it for you: "Run ocn advance for me." That still counts as your decision — the AI is just pressing the button on your behalf. The crucial difference: the AI cannot auto-run advance the moment Step 6 passes. It must wait until you say so.

Step 8. Loop back to Step 3

• You say: "Where is OCN now?"
• AI does: calls navigator.where_am_i.
• You see: the new step (e.g., step_scope).

Then return to Step 3 for the new step: pull its brief, create its artifact, write, verify, advance. Every step uses this same loop until OCN reports the project has run out of steps.

Cheat sheet: what you say → which tool runs

| What you say | What the AI uses | Mutates state.json? | |---|---|---| | "Where is OCN?" | navigator.where_am_i (MCP, read-only) | No | | "Pull the current step's brief" | navigator.brief (MCP, read-only) | No | | "Create the artifact template" | navigator.create_artifact (MCP) | No (writes docs/) | | "Fill out the artifact" | AI's own Edit tool on docs/ | No | | "Verify the artifact" | navigator.run_gate (MCP, read-only) | No | | "I'll run ocn advance myself" | ocn advance CLI (Bash, you trigger) | ✅ Yes |

Two hard rules

(1) navigator.run_gate passing ≠ state advancement. run_gate is read-only; a pass result does not move OCN to the next step. Only ocn advance (CLI) advances. If an AI runs run_gate and then claims "we're in the next step", it is lying — state.json is unchanged.

(2) The AI never advances on its own initiative. By design. After Step 6 passes, a disciplined Claude Code will say only "Gate passed; please run ocn advance". If it goes ahead and runs ocn advance without you asking, it has bypassed OCN's discipline guardrail — exactly the drift failure mode OCN exists to prevent.

This is the discipline OCN sells.

5.5 Adopting OCN mid-project

Scenario: your project is already running — half the code is written, the PRD lives on Notion, ACs are scattered across Slack threads, decisions exist only in your memory. You want to retrofit OCN's discipline now.

The fact you have to accept first: OCN does not start from "where you actually are"

OCN's state machine always starts at state_discovery / step_project_brief. The current release does not ship --skip-to, --start-at, or an --override flag on advance.

This is by design, not a limitation. OCN's value is forcing you to explicitly answer "what are we building?" and "what counts as done?". Skipping to BUILD makes brief, gate, and audit groundless — you might as well not install it.

So the only right path for mid-project adoption is backfill. The good news: you already have the content. You're just routing it into OCN's structure.

ocn init and existing files: hard guarantees

The most common worry when adopting OCN mid-project: "will ocn init overwrite my existing code or docs?"

Answer: no. Two source-level guarantees (verified against src/core/init.ts and src/core/artifact/template-writer.ts):

1. ocn init only writes OCN's own state files under .ocoding/ (state.json, sop.yaml, gates.yaml, artifacts.yaml, config.yaml) and mkdirs docs/. It does not write any docs/XX-*.md artifact templates, and it does not touch src/, README.md, or any other path.
2. If the project is already initialised (.ocoding/state.json exists), ocn init refuses to run and returns exit 4 (ERR_IO_OR_CONFIG) with the message "OCN is already initialized in this directory. / 当前目录已经初始化过 OCN。" — never overwrites your existing OCN state.

Similarly, ocn doc create <type> refuses to overwrite by default: on a name collision it returns exit 4 with "<type> already exists at <path>. Use --overwrite to replace it." You must explicitly pass --overwrite to replace.

So you can safely run them in an existing project root. Worst case: you already have a docs/00-project-brief.md — ocn doc create project-brief will refuse to write. Two options:

• Manually merge your existing content into the OCN template (preserve OCN's bilingual section headings Title｜标题 — they are the gate's match anchors).
• Rename your file as backup (e.g. docs/00-project-brief.legacy.md), let ocn doc create project-brief write the fresh template, then paste your content back into the OCN-shaped sections.

Recommended path: backfill early steps using material you already have

Step 1. Initialise in your project root

• You say: "Initialise OCN in this directory."
• AI does: runs ocn init via Bash.
• You see: .ocoding/ created (docs/ is mkdir-ed); state at state_discovery / step_project_brief. Your existing code and docs are untouched.

Step 2. Feed the AI your project context in one shot

• You say: "Here's the project context. The PRD is at [Notion URL / file path]. ACs pasted below. Code is in src/; [X module] is done, [Y] still pending. Architecture: [brief]. I want to backfill this into OCN's early steps."
• AI does: ingests the context for use across all subsequent steps.
• You see: the AI restates the situation to confirm it has the picture.

Step 3. Backfill the steps one at a time

Each step uses the §5.4 Steps 3–8 loop (pull brief → create template → AI fills using your material → run_gate → you type ocn advance). The difference from a greenfield project: because the content already exists, the AI mostly reorganises and aligns formats rather than inventing.

SOP 0.5.0 ships doc create templates for all 20 steps. The table below maps every step to its artifact path and where to mine the content from your existing project:

DISCOVERY phase

| Step | Artifact | Where to mine it from your existing project | |---|---|---| | step_project_brief | docs/00-project-brief.md | Original project pitch, Notion landing page, the one-pager you sent investors / leadership | | step_scope | docs/01-scope.md | Roadmap, Linear / Jira epic list, internal "what v1 / v2 will not do" doc |

SPEC phase

| Step | Artifact | Where to mine it from your existing project | |---|---|---| | step_prd | docs/02-prd.md | The PRD on Notion / Lark / Confluence — reorganise it into OCN's section structure | | step_acceptance_criteria | docs/03-acceptance-criteria.md | Slack AC threads, "should…" lines in bug tickets, QA test-case descriptions — convert to Given/When/Then |

DESIGN phase

| Step | Artifact | Where to mine it from your existing project | |---|---|---| | step_technical_architecture | docs/04-technical-architecture.md | package.json / requirements.txt / go.mod, deployment diagrams, tech-selection notes | | step_information_architecture | docs/05-information-architecture.md | Existing sitemap, URL routing tables, menu hierarchy, product screenshots | | step_data_model | docs/06-data-model.md | schema.sql, Prisma schema, ORM models, ER diagrams, DB migration files | | step_api_contract | docs/07-api-contract.md | OpenAPI / Swagger spec, Postman collections, router code, @RestController annotations | | step_test_strategy | docs/08-test-strategy.md | tests/ directory layout, CI config (.github/workflows/), coverage targets, E2E framework choice | | step_logic_backbone | docs/07-logic-backbone.md | Existing scoring/decision/rules logic, formula definitions, signal→action mappings |

PLAN phase

| Step | Artifact | Where to mine it from your existing project | |---|---|---| | step_mvp_plan | docs/09-mvp-plan.md | Existing roadmap, kanban, Linear/Jira epics, Phase 0/1/2 split | | step_build_plan | docs/10-build-plan.md | Current sprint plan, todo list, near-term PR plan |

BUILD phase (typically retroactive backfill)

| Step | Artifact | Where to mine it from your existing project | |---|---|---| | step_implementation_log | docs/11-implementation-log.md | git log, merged PR titles and summaries | | step_change_evidence | docs/12-change-evidence.md | Deployed changes, CHANGELOG.md, draft release notes | | step_integration_notes | docs/13-integration-notes.md | Third-party integration notes, SDK call samples, integration test results |

VERIFY phase

| Step | Artifact | Where to mine it from your existing project | |---|---|---| | step_verification_report | docs/14-verification-report.md | Past QA reports, performance test results, user acceptance records | | step_acceptance_mapping | docs/15-acceptance-mapping.md | AC-to-code/test mapping table (often needs fresh assembly) | | step_failure_fix_log | docs/16-failure-fix-log.md | Bug fix records, incident reports, postmortems | | step_regression_evidence | docs/17-regression-evidence.md | Regression test results, CI green-history records | | step_final_build_verdict | docs/18-final-build-verdict.md | Final release verdict (typically newly written) |

Step 4. Once you reach the step you're "actually" on, snap to it

When backfill catches up to your real position (say you've written half the code and you're at step_implementation_log), you don't start from a blank — your already-written code and merged PRs are the source material for that step. From here on, new work goes through OCN's discipline: every new feature gets a step, an artifact, then code.

The pre-OCN "anarchy period" is preserved as a faithful historical snapshot inside the backfilled artifacts.

Three common "can I…" questions

Q: Can I skip the early steps and start at BUILD? A: The current release does not expose a skip mechanism. Two options:

• Honest backfill (recommended) — fill the early steps from material you already have.
• Thin placeholder (not recommended) — write minimal content that just satisfies the required sections so the gate passes. This makes the gate rubber-stamp anything, which defeats the point of installing OCN.

Q: Will my existing docs/ numbering collide with OCN's? A: OCN reserves 00-project-brief.md through 18-final-build-verdict.md. On a name collision, ocn doc create refuses to write and returns exit 4 — your existing content is never overwritten. Recommended fix: rename your existing file as backup (e.g. docs/02-prd.legacy.md), run ocn doc create prd, then merge your content into the OCN template. The bilingual section headings (Title｜标题) in the OCN template are the gate's match anchors and must be preserved.

Q: Can I have the AI run all the early steps in one go? A: Technically yes. You can say:

"Backfill step_project_brief through step_technical_architecture from the material I provided. After each gate passes, tell me; I'll type ocn advance myself."

The AI will loop through doc create → fill → run_gate. After each step's run_gate passes, it stops and waits for you to type ocn advance (or to explicitly tell it to). Every advance remains your decision — by design, bulk backfill cannot replace the human "we are now in the next phase" call.

A minimal backfill example

Suppose you have:

• A 3-month-old React + Node.js project with code in src/
• A half-page Notion project pitch
• Scattered AC discussions in Slack

Bringing this into OCN looks like (real conversation will be denser; this shows the skeleton):

You: "Initialise OCN in this directory." AI: runs ocn init. State: state_discovery / step_project_brief. src/ and your existing files are untouched.

You: "Project context: [paste the Notion pitch]. Fill docs/00-project-brief.md per the brief." AI: calls navigator.brief → gets required sections (Problem / Goal / Users / Success Criteria) → edits docs/00-project-brief.md.

You: "Verify." AI: calls navigator.run_gate → pass. AI (disciplined): "Gate passed. Please run ocn advance."

You (terminal): ocn advance.

You: "Scope: v1 has shipped [X/Y/Z], [A] is in progress, explicitly out of scope: [B/C]. Fill docs/01-scope.md." AI: loop…

You: "Reorganise the Notion PRD into docs/02-prd.md: [link]." AI: loop…

You: "ACs from these Slack excerpts: [paste], converted to Given/When/Then." AI: loop…

(DESIGN phase: data-model from prisma/schema.prisma, api-contract from router code, technical-architecture from package.json + deployment diagram.)

(BUILD phase: implementation-log assembled from git log, change-evidence from merged PRs.)

Once the backfill catches up, all new work comes in through OCN's next step — every new feature has a brief, a gate, and an audit trail.

5.6 Post-plan execution flow

After your planning artifacts (00–10) pass their gates and the project enters implementation, the Execution Navigator commands take over. They are read-only summarisers — they help you and the agent see what is actually true in the repo, the PR, the acceptance evidence, and the verification signals.

1. Build the planning artifacts (steps above) — your state_plan artifacts (00–10) gate the implementation.
2. Start implementation in your normal repo workflow (your IDE, agents, etc.).
3. During implementation, use the Execution Navigator commands (§6.2) to read evidence:

   ocn exec status                              # local git + OCN state snapshot
   ocn github analyze-pr <n>                    # GitHub PR analysis (when a PR exists)
   ocn evidence map --pr <n>                    # acceptance criteria coverage
   ocn next-prompt --agent claude               # next agent brief
   ocn verify status --mode combined --pr <n>   # verification readiness
   ocn verdict draft --mode combined --pr <n>   # evidence-derived verdict

4. Review the evidence and verdict draft before merge — the verdict is conservative; ready-to-merge requires every signal aligned (verification ready, PR clean, acceptance covered, no failed checks, no changes-requested).

6. Core CLI commands

All commands accept --json to emit a machine-readable CommandResult envelope. Exit codes are stable:

| Exit code | Meaning | |---|---| | 0 | OK | | 1 | gate failed | | 2 | artifact missing or invalid | | 3 | state machine error | | 4 | config / lock / IO error | | 5 | SOP version incompatibility |

6.1 Planning Gatekeeper commands

| Command | Purpose | Reads / writes | Audit emission | |---|---|---|---| | ocn init [--tier minimal] [--json] | Initialise an OCN project in the current directory. | Writes .ocoding/, docs/, the dual-track audit files. | project_initialized + state-write events | | ocn status [--json] | Show current state, current step, the relative path of the current step's artifact, and the next-action hint. | Read-only. | None (avoids log spam — pull-mode) | | ocn brief [--json] | Print the current-step brief for an AI coding session: required sections, governance reminders, uncertainty policy. | Read-only. | None (pull-mode) | | ocn doc create <type> [--overwrite] [--json] | Create one of the 20 supported artifacts from its bundled template (refuses to overwrite an existing file unless --overwrite is passed). | Writes the artifact under docs/. | artifact_created | | ocn check [--json] | Check the current step's artifact against its required sections. | Read-only. | artifact_gate_run + artifact_gate_passed / artifact_gate_blocked | | ocn gate [--json] | Read-only artifact gate aggregation for the current step. Same emission as check; never mutates state. | Read-only. | artifact_gate_* (no correlationId) | | ocn advance [--json] | Run gate, then advance to the next step on pass. Lock-protected; never partial. | Writes state.json (atomic). | Full advance chain with shared correlationId | | ocn auto on --phase <1|2|all> / off [--phase] / resume / status / trace [--json] | Auto Mode switch (AM-009 / DEC-034) — delegate gate-green advances to the AI agent per phase (phase 1 = DISCOVERY→PLAN, phase 2 = BUILD→VERIFY incl. task check + the milestone rewind). The switch itself is human-only and refuses OCN_ACTOR=ai_agent; manual mode stays the default. status/trace are pull-mode (no audit); trace replays every ai_agent decision (rationale + engine-recorded context). | Writes the automation: block in config.yaml (comment-preserving) + .ocoding/automation-runtime.json (circuit breaker). | auto_mode_changed (on/off/resume/suspend) | | ocn sop upgrade [--target <version>] [--plan] [--json] | Move the project's pinned SOP profile forward to a newer bundled version (forward-only; config.yaml preserved). --plan is a read-only dry-run. | Apply rewrites .ocoding/ snapshots + state.json (atomic, lock-protected); --plan writes nothing. | sop_upgraded (apply) / sop_version_diff_detected (plan) | | ocn rewind --to <stepId> --reason <text> [--json] | Move the cursor back to a strictly-earlier step in this round (DEC-033 / AM-008). --reason is mandatory; docs/ artifacts are untouched; no gate exemption — every advance after a rewind re-runs the full gate stack. Milestone loop (phased projects, e.g. P0→P4 with per-phase go/no-go): after each milestone's verdict, rewind to step_build_plan, APPEND the next phase's Task Specs (keep finished specs verbatim — verify-command text unchanged ⇒ hash unchanged ⇒ done preserved), re-gate — the ledger becomes the project's cumulative progress account. Human-only — never exposed over MCP. | Writes state.json (atomic, lock-protected; latestGateResult cleared). | cursor_rewind (success and failed) | | ocn cycle new --yes [--json] | Archive this round's runtime state to .ocoding/cycles/<n>-<ts>/ and restart at the first step (DEC-033 / AM-008). docs/ are kept so next-round gates fast-forward; the pin and user-owned config.yaml stay; the audit JSONL is never archived — one continuous log spans all rounds. --yes is mandatory. Use it when the round's completion boundary (01-scope) is reached — per-milestone iteration inside one round is ocn rewind's job. Human-only — never exposed over MCP. | Moves .ocoding runtime files into the archive; rewrites snapshots + state.json. | cycle_started (success and failed) | | ocn stop --yes [--reason <text>] [--json] | Terminate OCN for this project (DEC-042 / AM-016) — one-way. Marks state.json with a stoppedAt timestamp so every runtime surface goes quiet (brief / next-prompt / status stop driving; advance refuses; the Stop hook stops forcing the AI onward) AND uninstalls the injected Claude Code wiring (.claude/ocn.md, /ocn-next, OCN's hooks + OCN_ACTOR in .claude/settings.json, the @.claude/ocn.md import in CLAUDE.md) — user content is preserved. Use it once planning is done to move to free self-development (works from any state). No built-in re-attach — re-wire with ocn agent setup. --yes mandatory. Human-only — never exposed over MCP. | Writes state.json (atomic, lock-protected); deletes/strips the wiring files. | project_stopped (success and failed) | | ocn readiness list [--json] | Evaluate all readiness checks for the current state/tier and print the verdict table (PASS/WAIVED/FAIL/UNKNOWN/NA counts + blocking items). | Read-only. | None (pull-mode — avoids audit spam) | | ocn readiness waive <checkId> --reason <r> --probe <cmd> [--json] | Grant a conditional waiver ("waive-with-probe"): the probe must pass at grant time, is re-verified on every gate run, and the waiver expires when the project leaves the current state. Human-only — never exposed over MCP. | Writes the waiver into .ocoding/readiness.json. | readiness_waived | | ocn task list [--json] | Show the build-plan task ledger: per-task status (pending/done), the frozen verify command, and dependency/phase info. | Read-only. | None (pull-mode) | | ocn task check [<id>] [--json] | Run the task's frozen verify command — exit 0 marks the task done; a verify command that drifted from its frozen hash is refused. Human/agent CLI only — never exposed over MCP. | Writes .ocoding/task-ledger.json. | task_completed | | ocn agent setup [--force] [--json] | One-command Claude Code wiring (AM-006): Stop/PostToolUse hooks in .claude/settings.json (merge-only, command -v ocn guarded), .claude/ocn.md governance contract, CLAUDE.md import (append-once), /ocn-next slash command. Idempotent; human-only. | Writes/merges the four .claude surfaces; never overwrites user entries. | agent_setup_completed | | ocn hook stop / ocn hook post-edit | Machine-facing Claude Code hook handlers (called by the agent host, not humans): stop re-runs the gate when the agent ends a turn and blocks with fix hints; post-edit runs commands.lint/commands.typecheck for fast feedback. Fail-open by design. | Raw hook-contract IO (stdin JSON in; block JSON / exit 2 + stderr out). | gate-run events via the reused check engine |

<type> for doc create (SOP 0.5.0 ships templates for all 20 steps): project-brief, scope, prd, acceptance-criteria, technical-architecture, information-architecture, data-model, api-contract, test-strategy, logic-backbone, mvp-plan, build-plan, implementation-log, change-evidence, integration-notes, verification-report, acceptance-mapping, failure-fix-log, regression-evidence, final-build-verdict.

--tier for init accepts minimal, production, full — only minimal is enforced today (production / full are accepted but their artifact sets are not yet differentiated).

6.2 Execution Navigator commands

Beyond the planning gate, OCN now reads execution-time evidence (git, GitHub PR, acceptance criteria, package scripts) and produces deterministic summaries — no LLM calls, no mutation, no npm run from inside the implementation. These commands are useful during implementation and review, after state_plan is closed. Authoritative reframe: DEC-024. Series closure: docs/reports/2026-05-04-execution-navigator-verdict-draft.md.

| Command | Purpose | Typical use | |---|---|---| | ocn exec status [--json] | Read local git evidence and OCN project state. | Snapshot of branch, head, dirty/clean, changed files, recent commits, current state/step. | | ocn github analyze-pr <n> [--json] | Read-only GitHub PR evidence analysis via gh CLI. | PR metadata, files changed, commits, checks, reviews — no mutation. | | ocn evidence map [--json] [--pr <n>] | Map acceptance criteria to available evidence. | Per-criterion status: evidence-found / evidence-candidate / missing-evidence / needs-human-review. | | ocn next-prompt [--json] [--agent ...] [--mode ...] [--pr <n>] [--issue ...] | Generate the next deterministic agent task brief. | 9 fixed sections — objective, evidence, allowed work, forbidden actions, verification commands, stop conditions. | | ocn verify status [--json] [--mode ...] [--pr <n>] | Summarise verification readiness and missing signals. | Status ready / partial / blocked / pending / no-verification-data plus required commands and risk flags. | | ocn verdict draft [--json] [--mode ...] [--pr <n>] | Draft an evidence-derived final judgment. | Category continue-work / request-changes / ready-for-review / ready-to-merge / hold-for-manual-review, with sorted supports / blocks / warnings. |

All six commands are read-only by design: no writes to .ocoding/, docs/, or any project file; no git mutation; no gh mutation (only pr view / auth status); no LLM call. --mode accepts local | pr | combined where applicable; --pr <n> enables GitHub evidence in pr and combined modes. Per-MVP implementation reports live under docs/reports/2026-05-02-execution-navigator-*.md and the closure report linked above.

6.3 Claude Code integration — one command (AM-006 / DEC-031)

ocn agent setup      # idempotent; commit .claude/ + CLAUDE.md to share with the team

Wires the whole phase-2 runbook mechanically: a Stop hook re-runs ocn check whenever the agent tries to end its turn (blocked → fix hints are fed back and the agent keeps working; loop-protected, fail-open), a PostToolUse hook runs your configured commands.lint/commands.typecheck (from .ocoding/config.yaml) after every Edit/Write, the .claude/ocn.md governance contract loads into every session via a CLAUDE.md import, and /ocn-next pulls ocn brief + ocn next-prompt and starts the task. Hook commands are guarded with command -v ocn, so teammates without ocn installed are unaffected. After setup, the human workflow per task is two actions: /ocn-next in Claude Code → review + ocn advance in the terminal.

6.4 Auto Mode — optional, off by default (AM-009 / DEC-034)

ocn auto on --phase 1     # delegate the planning pipeline (DISCOVERY→PLAN)
ocn auto on --phase all   # full auto: planning + BUILD/VERIFY loop + milestone rewinds
ocn auto status           # current grant + circuit-breaker state
ocn auto trace            # replay every AI decision: rationale + machine context
ocn auto off              # back to fully manual (the default)

Auto Mode delegates the trigger, never the judgement: every advance still runs the full gate stack, task completion is still decided only by the frozen verify command's exit 0. The AI must sign each call (OCN_ACTOR=ai_agent, injected by ocn agent setup) and justify it (--rationale — background / evidence / action); the engine independently records machine context on the audit trail. Safety net: N consecutive gate failures on one step (default 5) trip a circuit breaker that suspends automation until a human runs ocn auto resume — humans are never affected. Hard human-only zones in every mode: readiness waive, cycle new, sop upgrade, overrides, any non-milestone rewind, ocn stop, and ocn auto itself. The MCP surface is unchanged (7 tools, test-pinned). With phase 2 on, multi-P build plans complete end-to-end: after each milestone's verdict the agent rewinds to step_build_plan, appends the next P's Task Specs, re-gates (done tasks carry over), and continues — stopping only when every milestone is done.

7. MCP tools

OCN's MCP server (ocn-mcp) exposes 7 tools over stdio transport. Wire it into Claude Desktop on Windows with WSL2 — that is the validated Host (per DEC-017 and docs/reports/2026-04-30-mcp-external-host-validation-report.md). Cursor and Cline are MCP-aware but are not yet verified for OCN — see DEC-019 for the support boundary; do not treat them as supported until each has its own validation report.

7.1 Wire into Claude Desktop on Windows + WSL2

Add the OCN entry to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "ocn": {
      "command": "wsl.exe",
      "args": ["-e", "ocn-mcp"]
    }
  }
}

If ocn-mcp is not on the WSL2 PATH, replace "ocn-mcp" with the absolute path printed by which ocn-mcp inside WSL2 (typically the npm global bin, e.g. /home/<user>/.npm-global/bin/ocn-mcp). Save the config, fully quit Claude Desktop (system tray included), and reopen — the seven navigator.* tools should appear in the tools panel.

Full wiring guidance + per-tool envelopes: docs/mcp-usage.md. The validation transcript that proved this exact path works lives in docs/reports/2026-04-30-mcp-external-host-validation-report.md.

7.2 Allowed (7)

| Tool | Purpose | Mutates? | |---|---|---| | navigator.where_am_i | State snapshot. | No | | navigator.brief | Current-step brief. | No | | navigator.run_gate | Read-only gate aggregation. | No | | navigator.create_artifact | Create from the full template registry (20 types: 00–19, logic-backbone at 07). | Filesystem only | | navigator.capture_log | Append to docs/19-dev-log.md (type=dev) or docs/18-research-log.md (type=research). type=decision is hard-rejected. | Filesystem only | | navigator.detect_sop_version | Drift between locked profile and bundled OCN SOP. | No | | navigator.generate_next_prompt | Required sections + governance reminder + uncertainty policy + self-check rule. | No |

7.3 Forbidden (4) — NEVER exposed

| Tool | Why kept off MCP | |---|---| | navigator.advance_phase | State advancement is human-only via the CLI. | | navigator.capture_decision | Decisions reflect human intent. The exposed capture_log rejects type=decision. | | navigator.reset_project | Destructive; twice-confirm flow is human-only. | | navigator.force_release_lock | Bypasses state-safety invariants; operator-only. |

Enforced by tests/unit/mcp-tool-registry.test.ts (ALLOWED ∩ FORBIDDEN = ∅).

An MCP agent connected to OCN can read project state, render the next-step brief, prepare artifacts, run the read-only gate, create from the template registry, and capture dev / research logs. It cannot advance state, capture decisions, reset the project, or force-release the lock.

Full surface + wiring instructions: docs/mcp-usage.md.

Reference

8. Documentation map

OCN ships its own design baseline under docs/. Two governance points worth knowing before reading:

• Canonical decision log: docs/20-decision-log.md. Some historical references say docs/19-decision-log.md — those refer to the same file before the path move recorded in AM-002.
• Amendment index: docs/amendments/README.md. Active divergences from the frozen docs/00-08 design baseline are recorded as amendments rather than inline edits (DEC-004).
• Frozen design baseline: docs/00-project-brief.md through docs/08-mvp-plan.md are Phase-2 design contracts, treated as historical artifacts. New projects initialised via ocn init get the SOP v1.1 step layout from the bundled default profile; the OCN repository itself runs against a project-level override per DEC-003.
• Reports: docs/reports/ — Phase 2 closure, post-alpha P1 fix train (4 reports), Claude Desktop MCP Host validation, alpha.0 / alpha.1 / alpha.2 / beta.0 publish reports, examples F2/F3, beta release marker, bilingual install flow, doc audits, final Codex full-repo audit, post-Codex P1/P2 fix report. Phase 2 baseline lives in docs/reports/2026-04-28-phase2-completion-report.md.
• Plans: docs/plans/ holds the planning artifacts for each PR. The active GA Prep plan is docs/plans/2026-04-28-ga-prep-gap-review-plan.md.
• MCP usage: docs/mcp-usage.md.

9. Development

npm install
npm run lint           # ESLint (TypeScript-eslint)
npm run typecheck      # tsc --noEmit
npm run test           # vitest run — 459 tests, ~24 s
npm run test:coverage  # adds coverage report
npm run build          # tsc + chmod +x on bin entries

The pre-commit hook (Husky 9) runs lint + typecheck + test on every commit. CI runs the same checks plus build and reports coverage. Hard limits per CLAUDE.md: file ≤ 300 lines, function ≤ 50 lines, params ≤ 4, nesting ≤ 3, no raw any in exported APIs.

10. Roadmap

The GA Prep phase was a documentation, packaging, and operational-readiness audit that ran from Phase 2 closure through the beta candidate preparation track. Most GA Prep PRs are now complete; their evidence lives in docs/reports/ and docs/20-decision-log.md. Original plan: docs/plans/2026-04-28-ga-prep-gap-review-plan.md.

GA Prep PRs (status)

• PR A — Docs numbering reconciliation + amendments index. Complete.
• PR B — README first-5-minutes + CLI help copy audit. Iterated through multiple passes; latest bilingual install-flow refresh: docs/reports/2026-05-02-readme-install-flow-completion.md.
• PR C — MCP projectRoot path-traversal audit + threat-model doc. docs/security/mcp-threat-model.md is in the repo; projectRoot validator hardened by P1-001 (validateInitializedProjectRoot).
• PR D — External MCP Host validation. Claude Desktop on Windows with WSL2 validated (see docs/reports/2026-04-30-mcp-external-host-validation-report.md and DEC-017). Cursor and Cline remain unverified in separate future work.
• PR E — npm publish gating plan + CI stability audit. Publish discipline: DEC-008 / DEC-012 / DEC-015 / DEC-016 / DEC-021 / DEC-022. CI matrix expanded to Node 20 + Node 22 (report). Lock-observability flake hardened (report).
• PR F — examples/ directory plan. F1 + F2 + F3 complete: examples/discovery-to-plan/ is an executable smoke that walks all 10 v1.0 SOP steps (report). F4 (top-level "Try the example" link) is the example reference under §5.
• Post-Codex audit fix train — final full-repo Codex audit (report) and P1/P2 closure (report). Two P3 polish items remain.

Execution Navigator MVP series (post-DEC-024)

• MVP 1–6 complete — the six Execution Navigator commands (§6.2) shipped in PRs #63–#68 and merged to main. Cross-cutting review fixes landed in PR #69 (report). Series closure: docs/reports/2026-05-04-execution-navigator-verdict-draft.md.
• Current external package: 0.9.0-beta.1 — Planning Gatekeeper (§6.1) + Execution Evidence Navigator (§6.2) + the Logic Backbone DESIGN gate + the Readiness Backbone cross-cutting gate + the Task Backbone BUILD task ledger + the Acceptance Backbone SPEC gate + optional Auto Mode (§6.4, AM-009) + optional Contract Backbone (AM-012) — a BUILD/VERIFY gate that cross-checks frontend call sites against the declared API contract.
• Acceptance Backbone shipped in 0.9.0-beta.1 — SOP 0.8.0 (AM-015 / DEC-041): docs/03-acceptance-criteria.md now carries a machine-parseable ## Acceptance Specs｜验收规格 section (### AC-<DOMAIN>-<n> blocks with desc required + optional priority/given/when/then/trace). The acceptance gate runs at step_acceptance_criteria after the section gate, hard-blocks four structural defects (no_specs, duplicate_id, invalid_id, missing_field → ERR_ARTIFACT_INVALID, exit 2), and on pass freezes .ocoding/acceptance-specs.json — the canonical machine source of AC ids that build-plan traces bind to. Closes the false-completion hole where AC written in a table silently didn't register; reads are staleness-guarded (frozen projection while docs/03 is unchanged, else the live parse). Runtime default cut over to 0.8.0 per DEC-039 (npm/SOP lockstep → npm 0.9.0-beta.1); 0.7.0 and earlier stay frozen + importable; ocn sop upgrade migrates. See docs/acceptance-backbone-proposal.md.
• Task Backbone shipped in 0.5.0-beta.0 — SOP 0.5.0 (AM-007 / DEC-032): build plans carry machine-parseable Task Spec blocks (## Task Specs｜任务规格: goal/traces/touches/verify/dod + optional depends/phase/timeout). The build-plan gate validates six hard defects (duplicate/invalid id, missing field, dangling traces → AC ids, dangling touches → logic-graph nodes, dangling/cyclic depends, zero tasks) and freezes each task's verify-command hash into .ocoding/task-ledger.json. Completion is decided only by ocn task check rerunning the frozen command (exit 0 → done + task_completed audit; drift → refused); /ocn-next dispatches the first pending task in state_build; ocn advance out of BUILD is blocked while tasks are pending. Closes the fourth false-completion class — receipt-only completion (honest-but-empty BUILD receipts that pass every gate; discovered via the Lattice dogfood). Runtime default cut over to 0.5.0 per DEC-032; ocn sop upgrade migrates existing projects.
• Claude Code integration shipped in 0.4.0-beta.2 — AM-006 / DEC-031: ocn agent setup wires hooks + governance contract + /ocn-next in one idempotent command; ocn hook stop|post-edit carry the enforcement logic inside OCN (fail-open, loop-protected).
• Readiness Backbone shipped in 0.4.0-beta.1 — SOP 0.4.0 (AM-004 / DEC-028) adds a role-based cross-cutting readiness gate: 55 falsifiable checks derived from 54 curated IT roles run inside ocn check / ocn gate / ocn advance after the section + logic gates. Open-world semantics (FAIL and UNKNOWN block); verdict ledger persisted to .ocoding/readiness.json; ocn readiness list / ocn readiness waive (waive-with-probe) commands; ocn sop upgrade migrates existing projects; runtime default cut over to 0.4.0 per DEC-030.
• Logic Backbone shipped in 0.3.0-beta.1 — SOP 0.3.0 adds the DESIGN-phase docs/07-logic-backbone.md artifact; ocn check machine-validates its computation/decision graph (blocks on missing role, duplicate node id, dangling reference, dependency cycle, orphan node, unbound trigger) and on pass writes .ocoding/logic-graph.json, which ocn brief summarises as execution order + trigger bindings.
• Still beta, not GA. Validated with Claude Desktop on Windows with WSL2; Cursor and Cline remain unverified.
• Next gate: real external-repo dogfood pass before any further release sync; GA promotion remains gated on its own DEC.

Beyond GA Prep — not in any current plan; each requires its own DEC entry first

• ocn doctor, ocn reset, ocn baseline
• SOP versioning / upgrade tooling
• Production / full tier artifact-set enforcement
• Mini-CRM dogfood (Tier 2 GA success criterion)
• HTTP / SSE MCP transport, MCP auth, MCP session management
• Cursor / Cline real-Host validation (each Host needs its own DEC-017-style report)
• GA promotion DEC (final gate tying together Host scope, multi-OS / Node 24+ CI, dogfood evidence)

11. License

Apache-2.0

Part 2 · 中文版

OCN（O'CodingNavigator）是一套本地优先、MCP 优先、状态机驱动的 AI 编程工作流操作系统。它把 AI 编程从"持续聊天式发挥"重塑成可导航、有门禁、可审计、可复盘的系统工程过程。它是一个 navigator，不是 IDE，不是 SaaS，不是项目管理工具。

CLI：ocn；MCP server：ocn-mcp；许可：Apache-2.0。

中文目录

理解 OCN

• §A. OCN 是什么
• §B. OCN 解决什么问题
• §C. 当前状态
  • §C.1 两阶段产品模型

使用 OCN

• §D. 安装
• §E. 5 分钟上手
  • §E.4 完整操作流程：在 Claude Code 里走完一遍
  • §E.5 把 OCN 加入一个进行中的项目
  • §E.6 实现阶段：执行证据流
• §F. 核心 CLI 命令
  • §F.1 Planning Gatekeeper 命令
  • §F.2 Execution Navigator 命令
• §G. MCP 工具

参考资料

• §H. 文档地图
• §I. 开发
• §J. 路线图
• §K. 许可

理解 OCN

A. OCN 是什么

OCN 是 AI 编程的本地纪律层。所有数据都跑在你自己的机器上，落到纯文本（Markdown + JSON + JSONL + YAML）。它对人提供一个小型 CLI，对 agent 提供一个小型 MCP server，没有任何云端组件。

OCN 把"纪律"产品化：

• 状态机：DISCOVERY → SPEC → DESIGN → PLAN → BUILD → VERIFY → SHIP → REFLECT，单向推进，不可回退；
• 步骤产物门禁（Step Artifact Gate）：当前 step 的必填章节缺失时，状态推进被阻断；
• 双轨审计链：.ocoding/audit/audit-events.jsonl（机器源）+ docs/22-audit-trail.md（人类可读）；
• 逻辑主干（Logic Backbone，SOP 0.3.0）：一个 DESIGN 阶段产物，其计算/决策图由机器校验；ocn check 会在出现孤儿分值、悬空引用、循环依赖、未绑定触发器时阻断，让系统逻辑在 BUILD 之前就连通；
• 就绪主干（Readiness Backbone，SOP 0.4.0）：基于角色的横切就绪门禁——从 54 个精选 IT 角色（开发、QA、DevOps、CISO、服务台……）提炼出 55 条可证伪检查，在每个 step 的 ocn check / ocn gate / ocn advance 中运行；采用开放世界语义，FAIL 和 UNKNOWN 都会阻断（沉默不算通过），在 SHIP 之前拦住"角色盲区式完成"；
• 任务主干（Task Backbone，SOP 0.5.0 新增）：build plan 携带机器可解析的任务规格块（goal / traces / touches / verify / DoD）；build-plan 门禁校验六类硬缺陷，并把每个任务的验收命令哈希冻结进 .ocoding/task-ledger.json；任务只有在 ocn task check 重跑冻结命令且退出码为 0 时才算完成，台账未清时 ocn advance 不准离开 BUILD——封堵第四类假完成："只有回执的完成"（receipt-only completion）；
• 验收主干（Acceptance Backbone，SOP 0.8.0 新增）：docs/03-acceptance-criteria.md 携带机器可解析的 ## Acceptance Specs｜验收规格 章节（### AC-<DOMAIN>-<n> 块）；验收门禁在 step_acceptance_criteria 运行，硬拦四类结构缺陷（no_specs、duplicate_id、invalid_id、missing_field），通过后冻结 .ocoding/acceptance-specs.json——作为 build-plan traces 绑定的权威 AC id 机器源，封堵"AC 写在表格里却悄悄没登记"的假完成漏洞；
• 安全的 MCP 工具面：agent 可读、可准备、可创建产物，但不能推进状态、记录决策、重置项目、强制释放锁。

OCN 不是：代码生成器、IDE、SaaS、项目管理工具、笔记应用，也不是只会铺脚手架的"文档工厂"。

B. OCN 解决什么问题

任何稍微复杂的任务，AI 编程 agent 都倾向于踩四类坑：

| 失效模式 | 表现 | |---|---| | 迷路（lost） | 没人——人或 AI——清楚项目当前在哪一步。 | | 失控（drift） | Agent 一直在产出，但每一段都离最初需求更远。 | | 失忆（amnesia） | 一开新对话，agent 又把上一个对话已经决定的东西重新推一遍。 | | 假完成（false-completion） | 文档存在，但缺关键章节；agent 还是宣布"完成"。 |

OCN 把这四个问题视为同一个问题：AI 编程闭环缺乏严肃的"我们在哪"和"什么算完成"。OCN 用代码而不是嘴上嘱咐去回答这两个问题。

C. 当前状态（SOP 0.8.0（验收主干）主干）

| 项目 | 状态 | |---|---| | 阶段 | SOP 0.8.0（验收主干）主干——Plan → Build → Verify，含机器校验的 DESIGN 逻辑主干门禁、覆盖每个 step 的基于角色的横切就绪门禁（55 条检查）、把守 BUILD 出口的冻结验收任务台账，以及在 SPEC 阶段冻结权威 AC id 的验收门禁；plan-to-verify smoke 覆盖全部 20 步 | | 测试 | 完整 vitest 套件在 Node 20 + Node 22 全部通过 | | 覆盖率 | 满足发布门 | | npm | latest → 0.9.0-beta.1；beta → 0.9.0-beta.1；alpha → 0.1.0-alpha.2（历史保留） | | 成熟度 | pre-GA beta——非稳定、非 GA、仅 beta（用于受控测试 / dogfood） | | 已验证 Host | 已在 Claude Desktop on Windows + WSL2 验证。Cursor 与 Cline 暂未验证。 | | MCP 传输 | 仅 stdio（HTTP/SSE 尚未启动） |

2026-05-04 republish 说明：以 0.2.0-beta.2 重新发布，目的是把 0.2.0-beta.1 打包之后才合入的 Execution Navigator 命令（exec status、github analyze-pr、evidence map、next-prompt、verify status、verdict draft）真正包进 npm artifact。README 文档与已发布的 CLI 现在保持一致。

C.1 两阶段产品模型

OCN 现在分为两个衔接阶段：

1. Planning Gatekeeper：在实现前锁定范围、架构、验收与 build plan。驱动 state_discovery → state_plan，把守 artifact 完整度，对应 §F.1 的命令面。
2. Execution Evidence Navigator：在实现过程中读取 git、GitHub PR、验收证据与验证信号。新加 6 条只读命令（§F.2）汇总这些证据，并产出下一条 agent prompt、验证就绪信号与最终 verdict 草稿。这些命令永不写状态、永不调 LLM、永不跑 mutating 的 npm / gh 命令。

两个阶段是衔接的：planning 阶段的 artifact（00–10）必须先过门禁，execution 阶段的 evidence map、verify status、verdict draft 才能读到有意义的输入。权威 reframe：DEC-024。系列收口报告：docs/reports/2026-05-04-execution-navigator-verdict-draft.md。

已实现

• CLI：init、status、brief、doc create、check、gate、advance（完整列表见 §F）。
• 状态机：8 个状态，单向推进；DISCOVERY → PLAN 已挂上稳定 ID 的 step，BUILD/VERIFY/SHIP/REFLECT 仅有 state ID。
• 步骤产物门禁：基于 NFKC 标准化的双语 Title｜标题 标题匹配。
• 状态安全：.ocoding/.lock（5 秒超时 + 陈旧锁回收）、state.json.bak 滚动备份、临时文件 + atomic rename 写入；并发 advance 竞态已在 post-Codex P1 修复中关闭。
• 审计：双轨持久化、16 种事件类型、correlationId 串联整条 ocn advance 事件链。
• MCP 安全工具：stdio 上 7 个只读/准备/创建/日志类工具，4 个禁用工具不会被注册（详见 §G）；projectRoot 校验器 + 威胁模型（docs/security/mcp-threat-model.md）。
• 真实 Host 验证：Claude Desktop on Windows + WSL2 已完成端到端验证（DEC-017、报告）。
• 可执行示例：examples/discovery-to-plan/，scripts/smoke.sh 跑完 v1.0 SOP 全部 10 个 step；fixture 直接来源于 src/core/templates/*.ts，避免漂移。
• npm 发布纪律：以 [email protected] 形式发布（按 DEC-039，npm 包版本与 SOP profile 版本统一、步调一致——均为 0.8.0），遵循严格的预发布清单与 prepublishOnly 门，files allowlist 收敛到 dist/ + LICENSE + README + docs/quickstart.md + docs/mcp-usage.md；latest 与 beta 都指向 0.9.0-beta.1，alpha 仍保留在 0.1.0-alpha.2；v0.9.0-beta.1 为带注释的 git tag + GitHub pre-release。

尚未实现（刻意延后，详见 §J）

ocn doctor、ocn reset、ocn baseline、SOP 版本/升级工具、production/full tier、mini-CRM dogfood、Cursor/Cline 真实 Host 验证（DEC-019）、远程 MCP 传输、MCP 鉴权。

使用 OCN

D. 安装

D.1 推荐：从 npm 安装

npm install -g o-coding-navigation

从 v0.9.0-beta.1 开始，npm latest 与 beta 均指向 SOP 0.8.0（验收主干）版本 + 可选自动模式（AM-009）。注：按 DEC-039，npm 包版本与 SOP profile 版本统一、步调一致——均为 0.8.0；SOP profile 0.8.0 在 0.7.0 基础上新增验收主干，旧 profile 保持冻结且可导入。

安装后验证：

ocn --version       # 0.9.0-beta.1
ocn --help
ocn-mcp             # 启动 MCP stdio server；按 Ctrl+C 退出

如果希望明确固定在 beta 预发布通道，可以使用 @beta：

npm install -g o-coding-navigation@beta

卸载：npm uninstall -g o-coding-navigation。

D.2 当前已发布的渠道

| 渠道 | 版本 | npm tag | 说明 | |---|---|---|---| | latest（推荐） | 0.9.0-beta.1 | latest | SOP 0.8.0（验收主干）主干 + 可选自动模式（AM-009）。 | | Beta（显式预发布通道） | 0.9.0-beta.1 | beta | 与 latest 同一份产物；想明确固定在预发布通道时使用 @beta。 | | Alpha（仍可用） | 0.1.0-alpha.2 | alpha | 之前的 pre-GA 通道；仅作历史保留。 |

包主页：https://www.npmjs.com/package/o-coding-navigation

前置依赖：Node.js ≥ 20（参见 package.json 的 engines）。

pre-GA 警告：当前是 pre-GA beta——仅 beta，用于受控测试 / dogfood，非 GA。已在 Claude Desktop on Windows + WSL2 验证。Cursor 与 Cline 暂未验证。

D.3 备选：从源码本地开发

git clone https://github.com/UncleTIM-GZ/O-CodingNavigation.git
cd O-CodingNavigation
npm install
npm run build
npm link              # 把 `ocn` 和 `ocn-mcp` 暴露到 PATH

卸载本地链接：cd O-CodingNavigation && npm unlink -g ocn ocn-mcp。

不想用 npm link 也可以直接 node /path/to/O-CodingNavigation/dist/cli/index.js …。

E. 5 分钟上手

E.1 最小可行流程

mkdir ocn-demo && cd ocn-demo

ocn init                        # 创建 .ocoding/ 与 docs/
ocn status                      # state_discovery / step_project_brief

ocn doc create project-brief    # 写出 docs/00-project-brief.md（模板）
# 然后编辑该文件，把 4 个必填章节填好：
#   Problem · Goal · Users · Success Criteria

ocn gate                        # 只读校验，确认门禁通过
ocn advance                     # 跑门禁 + 改状态 + 写审计链
ocn status                      # 已推进到 state_discovery / step_scope

ocn brief                       # 给接管的 AI agent 输出当前 step brief

E.2 每条命令的预期产出

• init 写入 .ocoding/state.json、.ocoding/sop.yaml、双轨审计文件，以及 docs/ 骨架。
• status 报告 currentStateId: state_discovery / currentStepId: step_project_brief。
• doc create 写出 `docs/00-project-