added checks for pkl generation

Author: davidabram

.github/workflows/pkl-generated-parity.yml

@@ -0,0 +1,23 @@
+name: Pkl generated parity
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  generated-parity:
+    name: Generated files match Pkl
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+
+      - name: Run dev-shell generated parity check
+        run: nix develop -c ./config/pkl/check-generated.sh

config/pkl/README.md

@@ -61,12 +61,16 @@ git status --short config/.opencode config/.claude
 
 If regeneration is deterministic and current, there should be no diff after a clean re-run.
 
-5. Run stale-output detection (fails if generated files drift from committed outputs):
+5. Run Nix dev-shell integration stale-output test (fails if generated files drift from committed outputs):
 
 ```bash
 nix develop -c ./config/pkl/check-generated.sh
 ```
 
+This test intentionally exits non-zero when run outside `nix develop`.
+
+GitHub CI also runs this same command in `.github/workflows/pkl-generated-parity.yml` on `push` and `pull_request`.
+
 ## Troubleshooting
 
 - `pkl: command not found`: run commands via `nix develop -c ...` exactly as shown.

config/pkl/check-generated.sh

@@ -4,13 +4,28 @@ set -euo pipefail
 repo_root="$(git rev-parse --show-toplevel)"
 cd "$repo_root"
 
+if [[ -z "${IN_NIX_SHELL:-}" ]]; then
+  cat <<'EOF'
+This integration check must run in the Nix dev shell.
+
+Run with:
+  nix develop -c ./config/pkl/check-generated.sh
+EOF
+  exit 1
+fi
+
+if ! command -v pkl >/dev/null 2>&1; then
+  printf 'pkl is not available in PATH. Enter the dev shell with: nix develop\n' >&2
+  exit 1
+fi
+
 tmp_dir="$(mktemp -d)"
 cleanup() {
   rm -rf "$tmp_dir"
 }
 trap cleanup EXIT
 
-nix develop -c pkl eval -m "$tmp_dir" config/pkl/generate.pkl >/dev/null
+pkl eval -m "$tmp_dir" config/pkl/generate.pkl >/dev/null
 
 paths=(
   "config/.opencode/agent"

context/architecture.md

@@ -22,7 +22,8 @@ Current target renderer helper modules:
 - `config/pkl/renderers/claude-metadata.pkl`
 - `config/pkl/renderers/metadata-coverage-check.pkl`
 - `config/pkl/generate.pkl` (single multi-file generation entrypoint)
-- `config/pkl/check-generated.sh` (stale-output detection against committed generated files)
+- `config/pkl/check-generated.sh` (dev-shell integration stale-output detection against committed generated files)
+- `.github/workflows/pkl-generated-parity.yml` (CI wrapper that runs the parity check on `push` and `pull_request`)
 
 The scaffold provides stable canonical content-unit identifiers and reusable target-agnostic text primitives for all planned authored generated classes (agents, commands, skills, shared library file).
 
@@ -36,6 +37,7 @@ Renderer modules apply target-specific metadata/frontmatter rules while reusing
 - Both renderers expose per-class rendered document objects (`agents`, `commands`, `skills`) consumed by `config/pkl/generate.pkl`.
 - `config/pkl/generate.pkl` emits deterministic `output.files` mappings for all authored generated targets: OpenCode/Claude agents, commands, skills, and `lib/drift-collectors.js` in both trees.
 - Generated-file safety markers are part of emitted artifacts: Markdown outputs include an HTML warning comment after frontmatter, and the shared library output carries a leading JS generated warning header.
+- `config/pkl/check-generated.sh` is intentionally dev-shell scoped (`nix develop -c ...`): it requires `IN_NIX_SHELL`, runs `pkl eval -m <tmp> config/pkl/generate.pkl`, and fails when generated-owned paths drift.
 
 Generated authored classes:
 

context/patterns.md

@@ -29,7 +29,8 @@
 - Use `config/pkl/generate.pkl` as the single generation module for authored config outputs.
 - Use `config/pkl/README.md` as the contributor-facing runbook for prerequisites, ownership boundaries, regeneration steps, and troubleshooting.
 - Run multi-file generation with `nix develop -c pkl eval -m . config/pkl/generate.pkl` to emit to repository-root mapped paths.
-- Run stale-output detection with `nix develop -c ./config/pkl/check-generated.sh`; it regenerates into a temporary directory and fails if generated-owned paths differ from committed outputs.
+- Run stale-output detection with `nix develop -c ./config/pkl/check-generated.sh`; the script is a dev-shell integration test, exits non-zero outside `nix develop`, regenerates into a temporary directory, and fails if generated-owned paths differ from committed outputs.
+- Keep CI parity enforcement aligned with local workflow by running the same command in `.github/workflows/pkl-generated-parity.yml` on both `push` and `pull_request`.
 - For non-destructive verification during development, run `nix develop -c pkl eval -m context/tmp/t04-generated config/pkl/generate.pkl` and inspect emitted paths under `context/tmp/`.
 - Keep `output.files` limited to generated-owned paths only (`config/{opencode_root}/{agent,command,skills,lib}` and `config/{claude_root}/{agents,commands,skills,lib}` where roots map to `.opencode` and `.claude`).
 - Keep the shared drift library generated warning marker in `config/.opencode/lib/drift-collectors.js` (the canonical copied source) so both target library outputs inherit a stable, non-duplicating safety header.

context/plans/pkl-config-generation.md

@@ -132,7 +132,7 @@ Create a deterministic Pkl-based generation workflow that produces both configur
     - Regenerated all generated-owned outputs with `nix develop -c pkl eval -m . config/pkl/generate.pkl` and verified clean-state determinism via `nix develop -c ./config/pkl/check-generated.sh`.
     - Ran task-level checks and light build gate: `nix develop -c pkl eval config/pkl/renderers/metadata-coverage-check.pkl`, `nix develop -c pkl eval config/pkl/generate.pkl`, and `nix flake check --no-build`.
 
-- [ ] T08: Validation and cleanup (status:todo)
+- [x] T08: Validation and cleanup (status:done)
   - Task ID: T08
   - Goal: Run final end-to-end validation, ensure docs and generated outputs are aligned, and clean temporary artifacts.
   - Boundaries (in/out of scope):
@@ -144,6 +144,15 @@ Create a deterministic Pkl-based generation workflow that produces both configur
     - Temporary planning/execution artifacts are cleaned.
   - Verification notes (commands or checks):
     - Run full planned validation checks and capture evidence in the plan update.
+  - Evidence:
+    - Added Nix dev-shell integration parity behavior to `config/pkl/check-generated.sh`: the check now requires `IN_NIX_SHELL`, evaluates `config/pkl/generate.pkl` with `pkl` directly inside the shell, and diffs generated-owned paths against committed outputs.
+    - Updated `config/pkl/README.md` command guidance to describe `nix develop -c ./config/pkl/check-generated.sh` as the Nix dev-shell integration stale-output test and documented the outside-shell non-zero expectation.
+    - Captured clean-state parity evidence with `nix develop -c ./config/pkl/check-generated.sh` (pass: "Generated outputs are up to date.").
+    - Re-ran generator and metadata validations: `nix develop -c pkl eval config/pkl/generate.pkl` and `nix develop -c pkl eval config/pkl/renderers/metadata-coverage-check.pkl`.
+    - Validation report (commands, exit codes, key outputs): `nix develop -c ./config/pkl/check-generated.sh` (exit 0; output includes `Generated outputs are up to date.`), `nix develop -c pkl eval config/pkl/generate.pkl` (exit 0), `nix develop -c pkl eval config/pkl/renderers/metadata-coverage-check.pkl` (exit 0), `nix flake check --no-build` (exit 0), and `nix flake check` (exit 0).
+    - Lint/format validation note: this repository currently defines no separate global lint/format gate beyond the Nix-based checks above for this scope.
+    - Confirmed temporary artifact cleanliness for this task: `context/tmp/` contains only `.gitignore`.
+    - Residual risk: full multi-platform flake validation remains host-scoped; Nix reported incompatible systems omitted (`aarch64-darwin`, `aarch64-linux`, `x86_64-darwin`).
 
 ## 5) Open questions
 - None. Scope choice confirmed: shared canonical source with authored-file generation only.