Project Context Refresh

Project Context Refresh

Shared registry of deterministic context producers. Each producer regenerates one class of derived project context and, in check mode, reports precise drift without touching the checkout — never using file modification times. Every producer returns the canonical ri-06 ProducerResult (project-context-runtime), so the refresh orchestrator (ri-07) records results with no translation.

This is an infrastructure skill — not user-invocable. Add scripts/ to sys.path and import the bare module names, or drive it through scripts/cli.py.

Producers

Modes

• generate — write a producer's declared managed outputs (byte-stable for a fixed revision, inputs, and producer version).
• check — render in memory / a tempdir and byte-compare; never writes. Drift is reported as degraded with a failed validation, remediation, and a custom fallback stating no write occurred. A clean check is fresh.

openspec.projection is projection-only: canonical spec merges are sync-point mutations owned by cleanup-feature, so both modes are read-only.

Orchestration (ri-07)

scripts/orchestrator.py drives all configured producers into one durable ri-06 operation per (repository, revision) and emits the manifest:

• generate(...) — reuse/create the canonical operation, run every configured producer, record each result before attempting the degradable semantic index (ri-02), finalize succeeded/degraded/failed, then write and record the manifest. A repeat run at the same revision reuses a succeeded operation verbatim (no re-attempt, no repository diff).
• check(...) — fully read-only drift assessment (no store or working-tree writes).

The semantic index is the one degradable producer: unavailable or errored → a non-succeeded SemanticIndexReference with an exact-search fallback (never fatal, deterministic output preserved). Architecture (ri-04) is collected via its canonical owner; the manifest is written to the gitignored .git-context/context-refresh-manifest.json so reruns never dirty the tree.

The proposal's capability producer has no canonical owner and is not configured — tracked as an ri-07 follow-up (coordinator issue dced1d51, candidate change add-capability-context-producer). Once such a producer registers in registry.py, the orchestrator picks it up automatically.

CLI

From the repository root, the Makefile wraps the registry and the orchestrator:

make context-refresh          # generate every producer's managed output (ri-05)
make context-refresh-check    # read-only per-producer drift check (0 fresh · 2 drift · 1 failed)
make refresh-project-context        # orchestrate all producers + emit the manifest (ri-07)
make refresh-project-context-check  # read-only orchestrated drift check (0/2/1)

The underlying entry point is cli.py in this skill's resolved scripts/ directory, with subcommands list, generate <producer_id>, check <producer_id>, generate-all, check-all, refresh [--producer ID], and refresh-check [--producer ID]. Resolve the loaded skill directory first rather than hardcoding an install path.

Sync-point flags (ri-11)

refresh carries two opt-in flags for the main-convergence sync point. Both default to off, so every existing invocation behaves exactly as before, and refresh-check accepts neither — it writes nothing and never indexes.

--sync-point is a caller decision and is never inferred from the environment: an environment sniff would re-open shared-checkout writes for every skill that happens to run on main, which is the property the guard exists to protect. It authorizes the checkout classification only — the caller must still enforce its own clean-tree and active-agent guards, and its own pre-push compare-and-swap.

--defer-semantic-index exists because a sync point refreshes a revision that is never main's final state: the convergence commit follows it, so an inline index would be stale on arrival and a correct system would then index a second time. The caller enqueues exactly one index for the final pushed revision instead. Deferral only ever weakens the recorded claim — pending is not a currency claim, so a deferred run degrades (exit 2) rather than reporting success, and deterministic producer output is byte-identical to a non-deferred run.

# What the convergence driver runs, on main, after the merges have landed.
python3 <agent-skills-dir>/project-context-refresh/scripts/cli.py \
  refresh --sync-point --defer-semantic-index

--revision must name the revision that is actually checked out: every producer reads the live working tree, so accepting another SHA would persist artifacts under a revision they did not come from. Use a worktree at the target revision instead.

Configuration

All optional — with none of it set, refresh still runs every deterministic producer and degrades the semantic index to not-configured with an exact-search fallback.

The embedding contract is complete-or-absent: a DSN without a model and a dimension is treated as unconfigured rather than dispatched. Indexing runs the index_repo console script from packages/code-search as a subprocess — it pins asyncpg<0.31 against the coordinator's >=0.31, so it cannot be imported in-process. Every non-ready outcome degrades the refresh; it never fails it.

What it owns / does not own

• Owns: producer registration, fail-closed invocation, generate/check protocol, the domain adapters, and (ri-07) cross-producer orchestration — driving every configured producer into one ri-06 operation and emitting the aggregate manifest.
• Does not own: the result/manifest/operation models or durable storage (ri-06 project-context-runtime); CI/merge drift gates (ri-10/ri-11); the architecture analysis (refresh-architecture, ri-04) or semantic indexing (ri-01…ri-03) themselves — orchestration collects their results but each remains owned and regenerated by its canonical owner.
• Does not keep architecture artifacts fresh for anyone else. They are a regenerable local analysis cache whose freshness is a property of the checkout that last regenerated them, so an orchestration run here cannot observe — let alone guarantee — the freshness of the checkout a reader is about to read from. The reader ensures instead: the six consumer skills call refresh-architecture/scripts/run_architecture.py --ensure at the top of their artifact-reading step, and that call writes nothing when the check is fresh. This skill's architecture producer reports; it does not ensure on their behalf, and its result is informational drift in the gate.
• scripts/checkpoint.py is the same posture, deliberately. It records architecture freshness and the merge-base delta as findings and never invokes --ensure: a branch-local report of what a branch invalidated has to be reproducible, and here regenerating would also rewrite tracked committed-tier artifacts on any stale branch.

Tests

skills/tests/project-context-refresh/ — run with skills/.venv/bin/python -m pytest skills/tests/project-context-refresh -q.