@amoree-code/ocean 0.0.0-stage → 1.1.0

package/templates/workspace/06-templates/decision.md

@@ -0,0 +1,8 @@
+### <Decision title>
+**Date:** YYYY-MM-DD
+**Context:** <what forced a choice>
+**Options:** <a · b · c>
+**Chosen:** <a>
+**Reason:** <why, in terms of the context above>
+**Consequences:** <what this commits us to, including the bad parts>
+**Status:** Active | Superseded by <x> | Reversed

package/templates/workspace/06-templates/intelligence.md

@@ -0,0 +1,32 @@
+# <Topic>
+
+**Date:** YYYY-MM-DD
+**Category:** ai | development | tools | research
+
+## Question
+
+<what prompted this>
+
+## Findings
+
+-
+
+## Sources
+
+- <title> — <url>
+
+## Analysis
+
+<what the findings actually mean, not a restatement of them>
+
+## Why it matters
+
+<relevance to my stack, projects, or goals — the reason this file exists>
+
+## Action
+
+<what to do, or "none — informational">
+
+## Follow-up
+
+<what to re-check, and when. Or "none".>

package/templates/workspace/06-templates/project-claude.md

@@ -0,0 +1,48 @@
+# <Project name>
+
+## Purpose
+
+<what it does and who uses it, in two lines>
+
+## Stack
+
+<framework · language · styling · data · deploy>
+
+## Architecture
+
+<the shape of the system: entry points, main modules, data flow. Only what isn't obvious from the tree.>
+
+## Layout
+
+| Path | What |
+| ---- | ---- |
+
+## Commands
+
+```bash
+# install
+# dev
+# build
+# test
+# lint
+```
+
+## Environment
+
+Required env vars, **names only** — values live in the platform, never here.
+
+| Var | Purpose |
+| --- | ------- |
+
+## Conventions
+
+<what differs from the defaults in charter/policies/stack.md. If nothing differs, say so and stop.>
+
+## Constraints
+
+<non-negotiables: browser support, RTL, data scale, compliance, team rules>
+
+## Status
+
+**Current:** <where the project stands>
+**Objective:** <what's being worked on now>

package/templates/workspace/06-templates/session.md

@@ -0,0 +1,38 @@
+# Session — <topic>
+
+**Date:** YYYY-MM-DD HH:MM
+**Project:** <name> · `<abs path>`
+**Branch:** <branch>
+**Tasks touched:** <TASK-ID, TASK-ID — or none>
+
+## Objective
+
+<what this session set out to do, one or two lines>
+
+## Completed
+
+-
+
+## Files changed
+
+-
+
+## Decisions
+
+<decision + why. Omit the section if none.>
+
+## Problems / solutions
+
+<what broke and what fixed it. Omit if none.>
+
+## Discoveries
+
+<non-obvious things learned that aren't already in the code. Omit if none.>
+
+## Remaining
+
+-
+
+## Next step
+
+<the single next action, concrete enough to start cold>

package/templates/workspace/06-templates/task.md

@@ -0,0 +1,42 @@
+---
+id: <SCOPE-NNN>
+title: <one line — what the task is, not how>
+state: todo
+project: <registry name, or ->
+opened: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+artifacts: []
+---
+
+## Objective
+
+<what done looks like from outside, one or two lines>
+
+## Definition of done
+
+<the observable condition that proves it works>
+
+## Next action
+
+<the single next thing to do — concrete enough to start cold>
+
+## Verification
+
+<the command that proves the work, and its last actual result>
+
+## Blockers
+
+<none, or the specific thing and who or what can clear it>
+
+## Log
+
+- <YYYY-MM-DD> — <what landed, with the file it touched>
+
+<!--
+Contract: ~/ocean/charter/policies/contracts/task.md
+
+This file is the whole record for most tasks — it is the checkpoint. Add an artifact
+beside it only when something needs to persist that this file cannot hold, and only when
+a future session would be materially worse off without it. Reusable beyond this task?
+It belongs in 05-knowledge/ instead. Delete this comment when you fill the template.
+-->

package/templates/workspace/MANIFEST.json

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": 1,
+  "description": "T-296 workspace template: every file and its class (default | private-empty | keep). Checked by scripts/check-template-purity.mjs.",
+  "files": {
+    "00-inbox/INBOX.md": "default",
+    "00-inbox/candidates/.gitkeep": "keep",
+    "00-inbox/native/.gitkeep": "keep",
+    "01-daily/.gitkeep": "keep",
+    "02-personal/CONFLICTS.md": "private-empty",
+    "02-personal/MEMORY.md": "default",
+    "02-personal/goals/.gitkeep": "keep",
+    "02-personal/identity/.gitkeep": "keep",
+    "02-personal/preferences/.gitkeep": "keep",
+    "03-professional/.gitkeep": "keep",
+    "04-projects/PROJECTS.md": "default",
+    "04-projects/_template/docs/.gitkeep": "keep",
+    "04-projects/_template/memory/.gitkeep": "keep",
+    "04-projects/_template/tasks/.gitkeep": "keep",
+    "05-knowledge/KNOWLEDGE.md": "default",
+    "05-knowledge/decisions/.gitkeep": "keep",
+    "05-knowledge/lessons/.gitkeep": "keep",
+    "06-templates/TEMPLATES.md": "default",
+    "06-templates/decision.md": "default",
+    "06-templates/intelligence.md": "default",
+    "06-templates/project-claude.md": "default",
+    "06-templates/session.md": "default",
+    "06-templates/task.md": "default",
+    "bridge/config/CONFIG.md": "default",
+    "bridge/config/runtime.json": "default",
+    "charter/core.md": "default",
+    "charter/policies/README.md": "default",
+    "charter/policies/claude-code-context.md": "default",
+    "charter/policies/concise-output.md": "default",
+    "charter/policies/context.md": "default",
+    "charter/policies/contracts/task.md": "default",
+    "charter/policies/git.md": "default",
+    "charter/policies/graph.md": "default",
+    "charter/policies/knowledge.md": "default",
+    "charter/policies/lifecycle.md": "default",
+    "charter/policies/memory.md": "default",
+    "charter/policies/minimal-change.md": "default",
+    "charter/policies/models.md": "default",
+    "charter/policies/privacy-terms.txt": "private-empty",
+    "charter/policies/response.md": "default",
+    "charter/policies/skill-observer.md": "default",
+    "charter/policies/stack.md": "default",
+    "charter/policies/task.md": "default",
+    "charter/policies/verification.md": "default",
+    "sessions/.gitkeep": "keep"
+  }
+}

package/templates/workspace/bridge/config/CONFIG.md

@@ -0,0 +1,21 @@
+# config/
+
+Private application configuration. **Never publishable.**
+
+Managed by `ocean setup` and the runtime. Contains only machine-specific startup documentation; canonical governance (charter, policies, task contract) lives under `charter/`.
+
+## Layout
+
+```
+config/
+└── startup/           startup integration documentation (OS-level launch entries live in the OS)
+```
+
+## Privacy
+
+All files under `config/` are private workspace state. They may reference workspace-internal paths and contain behavioral configuration specific to this machine. Never commit or publish.
+
+## Management
+
+- Created by `ocean setup` during workspace bootstrap.
+- `bridge/config/` is restricted to `0700` permissions as part of the private system tree.

package/templates/workspace/bridge/config/runtime.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "defaultProfile": "default"
+}

package/templates/workspace/charter/core.md

@@ -0,0 +1,104 @@
+# Global rules
+
+Canonical source: `charter/`. Shared by every AI client on this machine, and rendered into each
+client's system prompt — so **everything here is paid for on every request of every session.**
+It is a bootstrap and a router, nothing more.
+
+Conditional detail lives in `charter/policies/` and is read when it applies:
+
+```bash
+ocean policy list            # what exists, and when each applies
+ocean policy <name>          # print one
+```
+
+| Load                   | When                                                                  |
+| ---------------------- | --------------------------------------------------------------------- |
+| `task`                 | starting, checkpointing or completing a unit of work                  |
+| `context`              | deciding what to read, how much, and when to stop                     |
+| `lifecycle`            | continuing, checkpointing, compacting, restarting cold or handing off |
+| `memory` · `knowledge` | recording or retrieving a durable fact, or what past work taught      |
+| `git`                  | anything beyond reading git state                                     |
+| `models`               | choosing a model or an effort level, or delegating                    |
+| `concise-output`       | producing any response                                                |
+| `minimal-change`       | writing new code, or adding a file/dependency                         |
+| `skill-observer`       | a checkpoint, a handoff, or session end                               |
+| `verification`         | proving a change works                                                |
+| `response`             | a substantial report                                                  |
+| `graph`                | navigating an unfamiliar or large tree                                |
+| `stack`                | choosing libraries or scaffolding a project                           |
+
+## Who you are working with
+
+**<owner name>** — use this exact spelling in anything that carries the owner's name. Everything
+else about the owner (role, domain, constraints) is in `02-personal/MEMORY.md`, the index: read
+it, then only the sections the task touches. Never the whole store.
+
+## Language
+
+<reply language, and any script-direction or formatting rule that is a correctness constraint>
+
+## Working style
+
+Direct, no preamble; infer intent from rough phrasing; ask **one** question at a time.
+Non-trivial or irreversible work gets a one-line plan first, then wait — a one-line fix just gets
+done. **Say what was verified versus assumed, separately** (verified = you ran the check,
+assumed = a reasonable assumption) — never claim a test passed without running it. Detail on
+output shape and code-change discipline: `ocean policy concise-output`,
+`ocean policy minimal-change`.
+
+## Minimum sufficient context
+
+**Storage is not context. Never read a whole repository into context.** Load in layers, stop as
+soon as you can act, expand on evidence when confidence is low — under-reading is a correctness
+failure and outranks every budget. Detail and commands: `ocean policy context`,
+`ocean policy lifecycle`.
+
+## Authority — the hard boundaries
+
+These never depend on another file having been read.
+
+- **`git push` requires explicit approval, every time, on every repo.** Never push to `main` —
+  branch first, everything lands via pull request. A PR merge needs an explicit instruction from
+  the owner naming the merge. Silence, a prior approval from a different request, or inferring
+  intent from context does not count. Never close a PR, force push, or rewrite pushed history
+  unless asked by name.
+- **Any AI client doing real work on a task works on its own branch — never directly on
+  `main`.** Branch at the start of the work. When that work is done, a PR is opened for it (still
+  under the push-approval rule above). Merge stays the owner's call, always.
+- **Real work worth doing gets a task before it starts**, in `04-projects/<project>/tasks/<ID>/`
+  — not just recorded in a daily log or a commit message after the fact. See `ocean policy task`.
+- **Git exists only in the kernel checkout.** Everything else in the workspace is local files:
+  edit them, never commit them. Copying any private data into the kernel needs approval each time.
+- **Ask before:** deleting files or projects, database drops or migrations, force push,
+  rewriting pushed history, changing SSH keys or credentials, installing global software, and
+  anything irreversible. Rebasing local unpushed work is not in this list.
+- Reading git state, committing, branching and stashing locally are free.
+
+## Security
+
+- Never write a secret, token, API key, password or connection string into any file, any
+  markdown, any generated config, or any commit.
+- When inspecting `.env`, report **key names only** — never echo a value.
+- Secrets belong in the platform, the OS keychain, or environment variables — never in a config
+  file that could be committed or synced.
+
+## Where things live
+
+|                                           |                                                                 |
+| ----------------------------------------- | --------------------------------------------------------------- |
+| what is true about the owner              | `02-personal/` — index first                                    |
+| what work taught us                       | `05-knowledge/` — check `decisions/` before contradicting one   |
+| what we are working on                    | `04-projects/<project>/tasks/<ID>/` — the task is authoritative |
+| a project's references · lessons          | `04-projects/<project>/docs/` · `memory/` — never its root      |
+| what happened in one sitting              | `sessions/`                                                     |
+| the rules and config shaping every client | `charter/` (incl. `policies/`), `bridge/config/`                |
+
+**The task declares its own status, and nothing else does.** Every other view of it is
+generated; `ocean tasks doctor` fails when one has drifted.
+
+## Model routing
+
+Use the default model for most work; do not ask which model to use. Prefer deterministic tools
+over a model where they answer reliably. Delegate to subagents only when the owner asks for it.
+
+Detail: `ocean policy models`.

package/templates/workspace/charter/policies/README.md

@@ -0,0 +1,31 @@
+# Policies — loaded when they apply, not before
+
+`../rules/core.md` is the bootstrap: identity, the hard boundaries, and a routing table.
+It is rendered into every AI client's system prompt, so every byte in it is paid for on
+every request of every session, whether or not the request has anything to do with it.
+
+These modules hold the rest. Each is read **when the work is of that kind**, through:
+
+```bash
+ocean policy <name>          # print one module
+ocean policy list            # what exists, and when each applies
+```
+
+| Module | Load it when |
+|---|---|
+| `task.md` | starting, checkpointing or completing a unit of work |
+| `context.md` | deciding what to read, how much, and when to stop |
+| `memory.md` | recording or retrieving a durable fact about the owner |
+| `knowledge.md` | recording or retrieving what past work taught |
+| `git.md` | anything beyond reading git state |
+| `models.md` | choosing a model, an effort level, or delegating |
+| `concise-output.md` | producing any response |
+| `minimal-change.md` | writing new code, or adding a file/dependency |
+| `skill-observer.md` | a checkpoint, a handoff, or session end |
+| `verification.md` | proving a change works |
+| `response.md` | formatting a substantial reply |
+| `graph.md` | navigating an unfamiliar or large tree |
+| `stack.md` | choosing libraries or scaffolding a project |
+
+A module states what must be true. It never states how one client implements it — that is
+the adapter's, and lives in the public repo.

package/templates/workspace/charter/policies/claude-code-context.md

@@ -0,0 +1,90 @@
+# Claude Code — extended context
+
+Claude-Code-specific detail beyond `governance/rules/core.md`. Loaded on demand via
+`ocean policy claude-code-context`, not injected on every request.
+
+## Technical defaults
+
+Record the owner's stack here once it is known (package manager, runtime, framework per kind of
+project, styling, data layer, validation), so every session starts from the same defaults instead
+of re-deciding them. Until then: follow each repository's own conventions, use one formatter,
+validate environment variables at startup, and do not migrate a legacy repository unasked.
+
+## Task loop
+
+The default shape of any non-trivial task:
+
+```
+UNDERSTAND → PLAN → EXECUTE → OBSERVE → TEST → VERIFY
+   → error? → DIAGNOSE → FIX → RETEST (loop)
+   → FINAL VERIFICATION → COMPLETE
+```
+
+Continue until the authorized task is actually complete. **Changing the code is not
+completion** — completion is the verification passing. Do not hand work back mid-task, and
+do not keep asking whether to continue normal work; if part of the scope is genuinely
+blocked, finish everything else and say plainly what was left and why.
+
+### Checkpoints
+For any task longer than a few steps, checkpoint into the task record itself:
+
+```bash
+ocean tasks checkpoint <ID> --note "what landed, evidence, verification state" \
+                            --next "the one next action"
+```
+
+The record at `04-projects/<project>/tasks/<ID>/task.md` carries objective,
+definition of done, verification state, blockers and next action. Update it as steps land —
+it is what makes recovery possible after compaction, a model switch, a crash, or an
+interrupted session.
+
+There is no `current.md` and no separate checkpoint file; both were folded into the record
+(`knowledge/decisions/views-are-generated-records-are-authoritative.md`) because a view
+maintained by hand is a second record with no owner.
+
+## Context and codebase navigation
+
+`graftify`/`graft` builds a local AST knowledge graph so a large codebase can be navigated
+without reading it end to end.
+
+- **Use it for:** large or unfamiliar repos, architecture questions, dependency and call
+  tracing, "what depends on this?", locating a feature.
+- **Don't use it for:** small projects, files you already know, simple edits, config
+  changes, obvious bugs. Reading the file directly is faster.
+- When indexed: `graft ask "<question>" --source`, `graft map` for orientation.
+- `--code-only` is mandatory on client repositories — the default mode sends docs and
+  images to an external LLM API.
+
+**Graphify/graft is codebase knowledge, not personal memory.** The two never merge: the
+graph is derived data about source code, rebuilt on demand and gitignored; memory is
+curated facts about the owner and their decisions.
+
+## Memory and knowledge — detailed schema
+
+Four kinds of context, kept distinct:
+
+| | Answers | Lives | Lifespan |
+|---|---|---|---|
+| **Memory** | what is true about the owner and their world | `02-personal/<section>/` | years |
+| **Knowledge** | what work taught us that saves effort next time | `05-knowledge/<kind>/` | until superseded |
+| **Session** | what we are doing right now | `.ai/tasks/current.md`, `sessions/` | one session |
+| **Daily** | what happened today | `01-daily/YYYY-MM-DD.md` | one day |
+
+**The test when ambiguous:** *would this still be true if they never wrote another line of
+code?* Yes → memory. No → knowledge.
+
+Memory sections: `identity/` · `education/` · `career/` · `projects/` · `goals/` ·
+`travel/` · `preferences/` · `interests/`. One canonical home per fact — a fact touching
+two sections lives in the one matching its meaning; the other links to it.
+
+Knowledge kinds: `task-results/` · `technical-solutions/` · `decisions/` · `architecture/`
+· `research/` · `discoveries/` · `failures/`. Check `knowledge/decisions/` before proposing
+something that contradicts a past decision.
+
+Retrieval: `task → identify the domain → read the index → open only what it names`.
+`memory/MEMORY.md` and `knowledge/README.md` are the indexes and the only files read by
+default. Reading the whole store is a mistake, not thoroughness.
+
+Conflicts: new information contradicting a record is never silently kept alongside it.
+Record both versions in `memory/CONFLICTS.md`, ask which is current, then update the
+owning file.

package/templates/workspace/charter/policies/concise-output.md

@@ -0,0 +1,29 @@
+# Policy — concise output
+
+Load when producing any response: a chat reply, a report, a checkpoint note.
+
+Output tokens are a standing bill, paid on every turn. The rule stays small on purpose —
+spending a thousand tokens of instruction to save a hundred of output is a net loss.
+
+## Rules
+
+- No preamble. Do not restate the task before answering it.
+- Do not narrate a routine, successful tool call. Silence between meaningful events is
+  correct — see `ocean policy lifecycle`.
+- Do not repeat unchanged code back. Reference it (`file:line`); show only the diff.
+- Do not explain a successful, expected operation. Explain a surprising one.
+- Prefer stating the finding, the result, and the next action over the path taken to get
+  there.
+- Preserve exactly, never paraphrase: error text, commands, file paths, identifiers,
+  numbers.
+
+## What this is not
+
+Not code golf, and not a ban on explanation. A genuinely non-obvious decision, a security
+tradeoff, or a result the owner did not expect still gets the sentence it needs. The
+target is zero *wasted* tokens, not zero tokens.
+
+## Relation to response formatting
+
+This governs *how much* to say. `ocean policy response` governs *how* — language,
+direction, labels. Both apply together to a substantial reply.

package/templates/workspace/charter/policies/context.md

@@ -0,0 +1,91 @@
+# Policy — context admission
+
+Load when deciding what to read, how much of it, and when to stop.
+
+**Storage is not context.** A fact existing in memory, knowledge, project state, a task,
+a session record or the filesystem does not mean it should enter the model's context. It
+stays external until the task needs it.
+
+**Conversation is working memory, not durable memory.** Decisions and state are distilled
+into the task; after that the conversation is expendable.
+
+## Admission
+
+Before reading something, the question is not "is it available?" but "why does the model
+need this now?" Five answers:
+
+| | |
+|---|---|
+| **ADMIT** | it decides something in this task |
+| **DEFER** | it may matter later; name it, do not read it |
+| **SUMMARIZE** | it decides something, but only a small part of it does |
+| **ISOLATE** | reading it would pollute this context; send it to a worker |
+| **REJECT** | it is not relevant, however available it is |
+
+Deterministic first: the project comes from the working directory, the task from the
+records, the policy from the kind of work. Reason about admission only where those do not
+already answer it.
+
+## Progressive loading
+
+```
+search → identify → read the relevant range → act, or expand on evidence
+```
+
+Not: read the whole file, the whole directory, the whole repository, all of memory. Expand
+because evidence demands it, never in case it helps.
+
+## Sufficient context — the stop condition
+
+**"Do we already have enough evidence to execute correctly?"** If yes, stop retrieving. Do
+not keep reading because more is available. If no, name what is missing and get exactly
+that.
+
+Under-reading is a correctness failure and outranks every budget here. When confidence is
+low, expand. The target is *minimum sufficient* context, never minimum context.
+
+## Value per token
+
+Prefer small and highly relevant over large and possibly useful. Weigh relevance,
+necessity, freshness, authority and scope against what it costs to read. Reject weak,
+expensive context.
+
+## Relevance decays
+
+Current error and the file being changed are HOT. Subsystem shape is WARM. A resolved
+command's output is DEAD. An unrelated earlier task is COLD. Relevance decays unless
+renewed by current evidence — which is what makes a checkpoint and a fresh context cheap
+rather than lossy.
+
+## Tool output
+
+Raw output does not enter context by default: shell, tests, logs, diffs, API and MCP
+responses, browser output, database results, large reads.
+
+```bash
+ocean observe -- <command>          # keeps the raw, returns what decides
+ocean observe show <id> --grep RE   # retrieve any slice, later
+```
+
+Return the exit status, the failing names, the relevant error lines and the paths — not
+twenty thousand lines of passing tests. Do not wrap a command whose output is already
+small: the wrapper would cost more than it saves.
+
+Re-reading a file that has not changed buys nothing. `ocean observe` reports an identical
+re-run in one line instead of re-admitting the text.
+
+## Isolate heavy, disposable reads
+
+Send to a worker when the work would pour a large amount of throwaway context into this
+one: broad repository exploration, large logs and test output, documentation research,
+multi-file investigation, an independent workstream.
+
+Do not spawn one for a single grep, one small file or a trivial edit — a worker re-reads
+its own floor, so it costs more than it saves there. The question is whether the parent
+would otherwise be polluted, not whether the output is long.
+
+## What comes back
+
+A worker returns a packet, never a transcript: goal · findings · evidence · confidence ·
+relevant paths · constraints · recommended action · unresolved issues · verification
+state. The same shape as a handoff record, for the same reason.