# Project Context Runtime

> Durable, versioned identity, producer-result, and manifest records for project-context refresh callers

- Skill: `jankneumann/project-context-runtime` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add jankneumann/project-context-runtime`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jankneumann/project-context-runtime/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jankneumann (https://skillmd.com/u/jankneumann)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jankneumann/project-context-runtime

---


# Project Context Runtime

Shared library providing the durable identity, producer-result, semantic-index
reference, and deterministic manifest records used by every project-context
refresh caller (architecture refresh, the refresh orchestrator, branch-local
checkpoints, and main convergence).

This is an infrastructure skill — not user-invocable. Import from
`<skill-base-dir>/scripts/` after resolving this loaded skill directory, or add
`scripts/` to `sys.path` and import the bare module names.

## What it owns

- `scripts/models.py` — strict, versioned dataclasses, enums, typed
  fail-closed exceptions, deterministic operation-identity derivation, and
  offline JSON-Schema validation.
- `scripts/atomic.py` — crash-safe atomic JSON writes (same-directory temp file,
  fsync, atomic replace, parent fsync) and cross-process advisory file locking.
  Private runtime-core; not part of the supported facade.
- `scripts/store.py` — the `OperationStore`, a Git-common-dir–backed durable
  ledger with per-operation locking and a validated state machine.
- `scripts/manifest.py` — deterministic, byte-stable manifest projection and an
  atomic committable writer.
- `install_assets/openspec/schemas/*.schema.json` — the three versioned Draft
  2020-12 contracts (types, operation, manifest).

## Supported facade

```python
from scripts import (
    OperationStore,      # durable create/resume/transition
    write_manifest,      # deterministic committable projection
    OperationRecord, RefreshManifest, ProducerResult,
    derive_operation_id,
)
```

## Boundaries

- Records are durable per **clone**: the store shares state across linked
  worktrees and later processes, not across machines.
- The mutable `operation.json` ledger is never committed; only the deterministic
  manifest projection is a repository artifact.
- Unknown schema versions, malformed records, unsafe paths, duplicate producer
  identities, and illegal transitions fail closed and are never coerced into a
  fresh-looking record.
- Semantic-index state is an opaque external reference; any status other than
  `succeeded` (with `indexed_revision == requested_revision`) requires an
  explicit fallback.

See `docs/project-context-refresh.md` for the full consumer contract.