Ting/Jostoph

Watch

Fork 2

Epic: Jostoph estate-wide toolchain lock #116

New issue

Open

opened 2026-09-04 15:54:33 +00:00 by codexo · 0 comments

codexo commented

2026-09-04 15:54:33 +00:00

Contributor

Outcome

Make Ting/Jostoph the authoritative estate-wide toolchain lock and propagation root for shared development tooling.

The estate MUST stop selecting common tool versions independently per repository. Jostoph's locked dependency graph defines the approved revisions of estate-owned tooling; repository devenv.lock files become reproducibility receipts for the Jostoph revision plus genuinely repository-specific inputs.

Ratified architecture

Ting/Jostoph
├─ flake.lock                  # authoritative estate toolchain lock
├─ nix/ting/                   # canonical devenv import
├─ ting-doctor.nix             # canonical ting:* task graph
└─ shared tool inputs
   ├─ nixpkgs
   ├─ OpenSpec
   └─ future estate tooling
          │
          ▼
consumer repository
├─ Jostoph input @ pinned rev
├─ repo-specific inputs only
└─ devenv.lock                 # resolved receipt, not policy

Authority

Jostoph owns common estate tool versions and the public ting:* devenv surface.
Ting/Jostoph/flake.lock is the authoritative lock for estate-owned tooling.
Consumers SHOULD declare only Jostoph plus inputs that are genuinely repository-specific.
Shared direct inputs SHOULD follow Jostoph where a direct handle is required rather than selecting their own revision.
Per-repository devenv.lock remains required for reproducibility, but MUST NOT become an independent source of estate toolchain policy.
ting:doctor MUST detect duplicated or divergent estate-owned dependency roots.

Superseded transitional state

The following commits established the propagation seam but pin OpenSpec at the devenv-project layer and are therefore transitional:

Jostoph: 01d14f89d45ba52dca7544996da591056839454b (devenv: propagate ting tasks with pinned OpenSpec)
Ting/Ting: 41e13d96f844ab2c7456809440ad4f847c68393e (devenv: consume canonical Ting module)

Preserve the canonical nix/ting/ import and ting:config:openspec provenance check, but move OpenSpec ownership into Jostoph's estate toolchain lock.

Sessions

1. Promote Jostoph to estate toolchain flake

Add OpenSpec as a Jostoph flake input and lock it in flake.lock.
Expose the exact OpenSpec package consumed by the Ting devenv module.
Define the stable package/toolchain interface used by nix/ting/.
Decide which other existing shared tools belong in the estate lock now versus later.

Acceptance: changing the OpenSpec revision requires one reviewed Jostoph lock change, not independent consumer edits.

2. Make `nix/ting/` the complete propagation surface

Keep the canonical shared devenv import in Jostoph.
Ensure ting:* tasks and their required packages arrive together.
Remove the transitional direct OpenSpec declaration from Jostoph devenv.yaml once the flake-provided package is wired.
Keep legacy direct imports evaluable long enough to emit a precise migration failure.

Acceptance: a new consumer can declare Jostoph once and receive a complete, internally consistent Ting development surface.

3. Replace pin equality with estate-lock conformance

Refactor ting:config:pin from narrow lock equality checks into semantic conformance:

identify the Jostoph revision used by the consumer;
verify shared tooling resolves from the approved Jostoph graph;
flag duplicate direct roots for estate-owned dependencies;
allow explicit repository-specific inputs;
report intentional overrides separately from accidental drift;
make OpenSpec provenance part of this same model.

Acceptance: doctor answers “is this repo consuming the approved estate toolchain?” rather than merely comparing two nixpkgs hashes.

4. Finish Ting/Ting as the reference consumer

Regenerate devenv.lock against the new Jostoph revision.
Run ting:doctor on a real Nix runner.
Verify OpenSpec resolves from Jostoph, not an ambient/global or repo-selected version.
Remove any no-longer-needed direct shared input declarations.
Record Ting/Ting as the canonical minimal consumer example.

Acceptance: Ting/Ting enters its shell with a green ting:doctor and contains no independent OpenSpec policy.

5. Define the consumer contract

Document and validate the normal shape:

inputs:
  jostoph:
    url: git+https://jo.et0.pw/Ting/Jostoph
    flake: false

imports:
  - jostoph/nix/ting

Where a repository needs a direct handle on a shared input, it MUST follow Jostoph instead of selecting a separate version when the tool supports that topology.

Acceptance: one short canonical recipe covers ordinary consumers; exceptions are explicit.

6. Estate sweep

discover repositories with devenv configuration;
classify direct Jostoph import, canonical nix/ting/ import, or no Ting integration;
migrate eligible repos to the canonical import;
regenerate local receipt locks on a Nix runner;
run ting:doctor after each migration;
leave repo-specific inputs untouched unless they duplicate estate-owned tooling;
report exceptions requiring owner decisions rather than silently forcing them.

Acceptance: every participating estate repo either conforms or has a recorded, justified exception.

7. Toolchain update ceremony

define the Jostoph change used to bump estate tooling;
validate the new lock on representative consumers before rollout;
make consumer lock refresh mechanical;
ensure an estate tool bump is one reviewed authority change followed by receipt propagation;
make rollback equally mechanical by reverting/pinning the Jostoph authority revision.

Acceptance: estate-wide OpenSpec/toolchain upgrades are deliberate, reviewable, and reversible without repository-by-repository version decisions.

Non-goals

One physically shared devenv.lock file across every repository.
Moving repository-specific dependencies into Jostoph.
Making Jostoph's lock a replacement for each repository's reproducibility lock.
Allowing ting:doctor to silently rewrite reviewed lockfiles during shell entry.

Completion criteria

This Epic is complete when:

Jostoph's lock graph is the only source of policy for estate-owned development tooling.
OpenSpec is pinned through Jostoph and propagated with the canonical Ting module.
ting:doctor detects shared-tool drift and duplicate roots.
Ting/Ting is a green reference consumer.
Participating estate repos have been swept and either migrated or explicitly exempted.
Shared tool upgrades and rollbacks occur through one Jostoph authority change plus mechanical consumer receipt refresh.

Governing distinction

Jostoph's lock is policy. Repository locks are receipts.

# Outcome Make `Ting/Jostoph` the authoritative estate-wide toolchain lock and propagation root for shared development tooling. The estate MUST stop selecting common tool versions independently per repository. Jostoph's locked dependency graph defines the approved revisions of estate-owned tooling; repository `devenv.lock` files become reproducibility receipts for the Jostoph revision plus genuinely repository-specific inputs. ## Ratified architecture ```text Ting/Jostoph ├─ flake.lock # authoritative estate toolchain lock ├─ nix/ting/ # canonical devenv import ├─ ting-doctor.nix # canonical ting:* task graph └─ shared tool inputs ├─ nixpkgs ├─ OpenSpec └─ future estate tooling │ ▼ consumer repository ├─ Jostoph input @ pinned rev ├─ repo-specific inputs only └─ devenv.lock # resolved receipt, not policy ``` ### Authority - Jostoph owns common estate tool versions and the public `ting:*` devenv surface. - `Ting/Jostoph/flake.lock` is the authoritative lock for estate-owned tooling. - Consumers SHOULD declare only Jostoph plus inputs that are genuinely repository-specific. - Shared direct inputs SHOULD follow Jostoph where a direct handle is required rather than selecting their own revision. - Per-repository `devenv.lock` remains required for reproducibility, but MUST NOT become an independent source of estate toolchain policy. - `ting:doctor` MUST detect duplicated or divergent estate-owned dependency roots. ## Superseded transitional state The following commits established the propagation seam but pin OpenSpec at the devenv-project layer and are therefore transitional: - Jostoph: `01d14f89d45ba52dca7544996da591056839454b` (`devenv: propagate ting tasks with pinned OpenSpec`) - Ting/Ting: `41e13d96f844ab2c7456809440ad4f847c68393e` (`devenv: consume canonical Ting module`) Preserve the canonical `nix/ting/` import and `ting:config:openspec` provenance check, but move OpenSpec ownership into Jostoph's estate toolchain lock. # Sessions ## 1. Promote Jostoph to estate toolchain flake - [ ] Add OpenSpec as a Jostoph flake input and lock it in `flake.lock`. - [ ] Expose the exact OpenSpec package consumed by the Ting devenv module. - [ ] Define the stable package/toolchain interface used by `nix/ting/`. - [ ] Decide which other existing shared tools belong in the estate lock now versus later. **Acceptance:** changing the OpenSpec revision requires one reviewed Jostoph lock change, not independent consumer edits. ## 2. Make `nix/ting/` the complete propagation surface - [ ] Keep the canonical shared devenv import in Jostoph. - [ ] Ensure `ting:*` tasks and their required packages arrive together. - [ ] Remove the transitional direct OpenSpec declaration from Jostoph `devenv.yaml` once the flake-provided package is wired. - [ ] Keep legacy direct imports evaluable long enough to emit a precise migration failure. **Acceptance:** a new consumer can declare Jostoph once and receive a complete, internally consistent Ting development surface. ## 3. Replace pin equality with estate-lock conformance Refactor `ting:config:pin` from narrow lock equality checks into semantic conformance: - [ ] identify the Jostoph revision used by the consumer; - [ ] verify shared tooling resolves from the approved Jostoph graph; - [ ] flag duplicate direct roots for estate-owned dependencies; - [ ] allow explicit repository-specific inputs; - [ ] report intentional overrides separately from accidental drift; - [ ] make OpenSpec provenance part of this same model. **Acceptance:** doctor answers “is this repo consuming the approved estate toolchain?” rather than merely comparing two nixpkgs hashes. ## 4. Finish Ting/Ting as the reference consumer - [ ] Regenerate `devenv.lock` against the new Jostoph revision. - [ ] Run `ting:doctor` on a real Nix runner. - [ ] Verify OpenSpec resolves from Jostoph, not an ambient/global or repo-selected version. - [ ] Remove any no-longer-needed direct shared input declarations. - [ ] Record Ting/Ting as the canonical minimal consumer example. **Acceptance:** `Ting/Ting` enters its shell with a green `ting:doctor` and contains no independent OpenSpec policy. ## 5. Define the consumer contract Document and validate the normal shape: ```yaml inputs: jostoph: url: git+https://jo.et0.pw/Ting/Jostoph flake: false imports: - jostoph/nix/ting ``` Where a repository needs a direct handle on a shared input, it MUST follow Jostoph instead of selecting a separate version when the tool supports that topology. **Acceptance:** one short canonical recipe covers ordinary consumers; exceptions are explicit. ## 6. Estate sweep - [ ] discover repositories with devenv configuration; - [ ] classify direct Jostoph import, canonical `nix/ting/` import, or no Ting integration; - [ ] migrate eligible repos to the canonical import; - [ ] regenerate local receipt locks on a Nix runner; - [ ] run `ting:doctor` after each migration; - [ ] leave repo-specific inputs untouched unless they duplicate estate-owned tooling; - [ ] report exceptions requiring owner decisions rather than silently forcing them. **Acceptance:** every participating estate repo either conforms or has a recorded, justified exception. ## 7. Toolchain update ceremony - [ ] define the Jostoph change used to bump estate tooling; - [ ] validate the new lock on representative consumers before rollout; - [ ] make consumer lock refresh mechanical; - [ ] ensure an estate tool bump is one reviewed authority change followed by receipt propagation; - [ ] make rollback equally mechanical by reverting/pinning the Jostoph authority revision. **Acceptance:** estate-wide OpenSpec/toolchain upgrades are deliberate, reviewable, and reversible without repository-by-repository version decisions. # Non-goals - One physically shared `devenv.lock` file across every repository. - Moving repository-specific dependencies into Jostoph. - Making Jostoph's lock a replacement for each repository's reproducibility lock. - Allowing `ting:doctor` to silently rewrite reviewed lockfiles during shell entry. # Completion criteria This Epic is complete when: 1. Jostoph's lock graph is the only source of policy for estate-owned development tooling. 2. OpenSpec is pinned through Jostoph and propagated with the canonical Ting module. 3. `ting:doctor` detects shared-tool drift and duplicate roots. 4. `Ting/Ting` is a green reference consumer. 5. Participating estate repos have been swept and either migrated or explicitly exempted. 6. Shared tool upgrades and rollbacks occur through one Jostoph authority change plus mechanical consumer receipt refresh. ## Governing distinction > **Jostoph's lock is policy. Repository locks are receipts.**

codexo added the

Priority/High

Status/Ready

Meta/Epic

labels

2026-09-04 15:54:33 +00:00