OMK

English

简体中文

English

简体中文

Appearance

OMK storage layout v2 ​

Scope: the canonical project and machine storage contract. Paths are generated by src/evidence/storage/layout.ts; product modules must not assemble .omk roots themselves. This layout changes storage only and does not change report schemas, scoring, prompts, statistics, or length debiasing.

Principles ​

  • Top-level names follow user-visible product domains: eval, doctor, and observe.
  • One durable measurement record owns one self-contained directory. report.json is authoritative; rebuildable views live in derived/.
  • Lifecycle is visible in the path. Durable evidence, observations, governance, backups, and rebuildable state do not share a flat namespace.
  • Project-bound evidence defaults to <project>/.omk. Machine tools, caches, tunnels, materialized trees, and cross-project indexes exist only under global state/.
  • Identity comes from report IDs and content digests, never from an absolute path. Moving a record does not change its report JSON or digest.

Project layout ​

text
.omk/
├── .gitignore
├── eval/
│   └── <record-id>/
│       ├── manifest.json
│       ├── report.json
│       └── derived/
│           ├── graph.json
│           └── card.md
├── doctor/
│   └── <record-id>/
│       ├── manifest.json
│       ├── report.json
│       └── derived/
│           ├── graph.json
│           └── card.md
├── observe/
│   ├── health/
│   │   └── <record-id>/
│   │       ├── manifest.json
│   │       └── report.json
│   ├── inbox/
│   │   ├── reports/
│   │   ├── captures/
│   │   └── review-state.json
│   ├── drafts/
│   └── archive/
│       └── source-records/
├── governance/
│   └── managed/
├── backups/
│   └── doctor-fix/
└── state/
    ├── jobs/
    ├── locks/
    └── tmp/

<record-id> is the collision-safe filesystem identity of one report bundle. A manifest carries the public report/run identity. Evaluation Core bundles also retain their sealed plan and execution/evaluation/analysis documents beside report.json; those documents remain part of the authenticated bundle.

The directory-skill authoring convention <skill>/.omk/eval-samples.{json,yaml} is intentionally unchanged.

Machine layout ​

OMK_HOME defaults to ~/.oh-my-knowledge and relocates this whole tree:

text
~/.oh-my-knowledge/
├── eval/
├── doctor/
├── observe/
├── governance/
├── backups/
└── state/
    ├── cache/
    ├── tools/
    ├── tunnels/
    ├── trees/
    ├── isolated-cwd/
    │   └── resolved-inputs/
    │       └── content/
    ├── artifact-index/
    ├── jobs/
    ├── locks/
    └── tmp/
        └── resource-leases/

Project and machine durable data use the same domains. Machine-specific material never belongs in project .omk. Resolver-owned input copies live under state/isolated-cwd/resolved-inputs/; run-scoped resource copies and overlays live under state/tmp/resource-leases/ and are removed when their lease closes. Original Codex, Claude, and DSH traces stay at their source; OMK reads them rather than copying them into a project by default.

Lifecycle and Git policy ​

PathMeaningDeleted by default?Project Git policy
eval/A/B evidence and release decisionsNoignored
doctor/skill health reportsNoignored
observe/health/health aggregated from real tracesNoignored
observe/inbox/candidate observations and human review stateNoignored; may be sensitive
observe/drafts/sample drafts derived from observationsNoignored
observe/archive/immutable source-record sidecars referenced by inbox reportsNoignored; may be sensitive
governance/managed/install/evidence/promote/rollback historyNotracked by default
backups/recovery copies made before automatic editsNoignored
state/jobs, locks, temporary files, and global rebuildable cachesYesignored

omk init writes an internal .omk/.gitignore that ignores eval/, doctor/, observe/, backups/, and state/, while leaving .gitignore and governance/ trackable.

Compatibility boundary ​

The v2 tree is the only supported storage layout. OMK neither reads old storage roots nor provides a migration command, and it never moves or deletes old data automatically. Existing old .omk data remains untouched but invisible to v2 readers; users may back it up or remove it explicitly. Evaluation Core bundles use manifest v2 and report.json only.

Why these names ​

There is no top-level runs: it suggests disposable execution state, while evaluation and doctor records are durable evidence. There is no top-level measurements: it obscures the CLI domain users already know. There is no top-level observations: health reports and reviewable observations are sibling pipelines under the shared observe product domain. derived is used instead of projections because the directory holds rebuildable materializations owned by one authoritative report, not a distinct product domain.