add GENERATED FILE notice

davidabram · davidabram · commit 2cccba32b4e0 · 2026-02-28T14:53:47.000+01:00
diff --git a/config/.claude/agents/shared-context-code.md b/config/.claude/agents/shared-context-code.md
@@ -6,6 +6,8 @@ color: green
 tools: ["Read", "Glob", "Grep", "Edit", "Write", "Skill", "AskUserQuestion", "Task", "Bash"]
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 You are the Shared Context Code agent.
 
 Mission
diff --git a/config/.claude/agents/shared-context-drift.md b/config/.claude/agents/shared-context-drift.md
@@ -6,6 +6,8 @@ color: orange
 tools: ["Read", "Glob", "Grep", "Edit", "Write", "Skill", "AskUserQuestion", "Task", "Bash"]
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 You are the Shared Context Drift agent.
 
 Mission
diff --git a/config/.claude/agents/shared-context-plan.md b/config/.claude/agents/shared-context-plan.md
@@ -6,6 +6,8 @@ color: blue
 tools: ["Read", "Glob", "Grep", "Edit", "Write", "Skill", "AskUserQuestion", "Task", "Bash"]
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 You are the Shared Context Plan agent.
 
 Mission
diff --git a/config/.claude/commands/change-to-plan.md b/config/.claude/commands/change-to-plan.md
@@ -3,6 +3,8 @@ description: "Create or update an SCE plan from a change request"
 allowed-tools: Task, Read, Glob, Grep, Edit, Write, Question, Skill
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-plan-authoring` skill.
 
 Input change request:
diff --git a/config/.claude/commands/drift-detect.md b/config/.claude/commands/drift-detect.md
@@ -3,6 +3,8 @@ description: "Analyze and report drift between context and code"
 allowed-tools: Task, Read, Glob, Grep, Edit, Write, Question, Skill, Bash
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-drift-analyzer` skill.
 
 Behavior:
diff --git a/config/.claude/commands/fix-drift.md b/config/.claude/commands/fix-drift.md
@@ -3,6 +3,8 @@ description: "Resolve code-context drift using SCE rules"
 allowed-tools: Task, Read, Glob, Grep, Edit, Write, Question, Skill, Bash
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-drift-fixer` skill.
 
 Audit the `context/` and ensure it correctly describes the system as implemented
diff --git a/config/.claude/commands/handover.md b/config/.claude/commands/handover.md
@@ -3,6 +3,8 @@ description: "Create a structured SCE handover of the current task"
 allowed-tools: Task, Read, Glob, Grep, Edit, Write, Question, Skill
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-handover-writer` skill.
 
 Input:
diff --git a/config/.claude/commands/next-task.md b/config/.claude/commands/next-task.md
@@ -3,6 +3,8 @@ description: "Review a plan and execute one SCE task from an approved plan"
 allowed-tools: Task, Read, Glob, Grep, Edit, Write, Question, Skill, Bash
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow `sce-plan-review`, then `sce-task-execution`, then `sce-context-sync`.
 
 Input:
diff --git a/config/.claude/commands/validate.md b/config/.claude/commands/validate.md
@@ -3,6 +3,8 @@ description: "Run final validation and cleanup for an SCE plan"
 allowed-tools: Task, Read, Glob, Grep, Edit, Write, Question, Skill, Bash
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-validation` skill.
 
 Input:
diff --git a/config/.claude/lib/drift-collectors.js b/config/.claude/lib/drift-collectors.js
@@ -1,3 +1,6 @@
+// GENERATED FILE: DO NOT EDIT DIRECTLY.
+// Update canonical sources under config/pkl/ and regenerate.
+
 const fs = require("node:fs/promises");
 const path = require("node:path");
 
diff --git a/config/.claude/skills/sce-bootstrap-context/SKILL.md b/config/.claude/skills/sce-bootstrap-context/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Bootstrap SCE baseline context directory whe
 compatibility: claude
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## When to use
 - Use only when `context/` is missing.
 - Ask for human approval before creating files.
diff --git a/config/.claude/skills/sce-context-sync/SKILL.md b/config/.claude/skills/sce-context-sync/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Synchronize context files to match current c
 compatibility: claude
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## Principle
 - Context is durable AI memory and must reflect current-state truth.
 - If context and code diverge, code is source of truth.
diff --git a/config/.claude/skills/sce-drift-analyzer/SKILL.md b/config/.claude/skills/sce-drift-analyzer/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to analyze drift between context and code using
 compatibility: claude
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## What I do
 - Collect context and code signals with pure JavaScript collectors.
 - Analyze semantic drift between documented state and implemented state.
diff --git a/config/.claude/skills/sce-drift-fixer/SKILL.md b/config/.claude/skills/sce-drift-fixer/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to audit and repair code-context drift in conte
 compatibility: claude
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## What I do
 - Audit `context/` and verify it matches the implemented system.
 - Treat code as the source of truth when context and code disagree.
diff --git a/config/.claude/skills/sce-handover-writer/SKILL.md b/config/.claude/skills/sce-handover-writer/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to create a structured SCE handover for the cur
 compatibility: claude
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## What I do
 - Create a new handover file in `context/handovers/`.
 - Capture:
diff --git a/config/.claude/skills/sce-plan-authoring/SKILL.md b/config/.claude/skills/sce-plan-authoring/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Create or update an SCE implementation plan
 compatibility: claude
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## Goal
 Turn a human change request into `context/plans/{plan_name}.md`.
 
diff --git a/config/.claude/skills/sce-plan-review/SKILL.md b/config/.claude/skills/sce-plan-review/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to review an existing plan and prepare the next
 compatibility: claude
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## What I do
 - Continue execution from an existing plan in `context/plans/`.
 - Read the selected plan and identify the next task from the first unchecked checkbox.
diff --git a/config/.claude/skills/sce-task-execution/SKILL.md b/config/.claude/skills/sce-task-execution/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Execute one approved task with explicit scop
 compatibility: claude
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## Scope rule
 - Execute exactly one task per session by default.
 - If multi-task execution is requested, confirm explicit human approval.
diff --git a/config/.claude/skills/sce-validation/SKILL.md b/config/.claude/skills/sce-validation/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Run final plan validation and cleanup with e
 compatibility: claude
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## When to use
 - Use for the plan's final validation task.
 
diff --git a/config/.opencode/agent/Shared Context Code.md b/config/.opencode/agent/Shared Context Code.md
@@ -29,6 +29,8 @@ permission:
     "sce-validation": allow
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 You are the Shared Context Code agent.
 
 Mission
diff --git a/config/.opencode/agent/Shared Context Drift.md b/config/.opencode/agent/Shared Context Drift.md
@@ -27,6 +27,8 @@ permission:
     "sce-drift-fixer": allow
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 You are the Shared Context Drift agent.
 
 Mission
diff --git a/config/.opencode/agent/Shared Context Plan.md b/config/.opencode/agent/Shared Context Plan.md
@@ -27,6 +27,8 @@ permission:
     "sce-plan-authoring": allow
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 You are the Shared Context Plan agent.
 
 Mission
diff --git a/config/.opencode/command/change-to-plan.md b/config/.opencode/command/change-to-plan.md
@@ -3,6 +3,8 @@ description: "Create or update an SCE plan from a change request"
 agent: "Shared Context Plan"
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-plan-authoring` skill.
 
 Input change request:
diff --git a/config/.opencode/command/drift-detect.md b/config/.opencode/command/drift-detect.md
@@ -3,6 +3,8 @@ description: "Analyze and report drift between context and code"
 agent: "Shared Context Drift"
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-drift-analyzer` skill.
 
 Behavior:
diff --git a/config/.opencode/command/fix-drift.md b/config/.opencode/command/fix-drift.md
@@ -3,6 +3,8 @@ description: "Resolve code-context drift using SCE rules"
 agent: "Shared Context Drift"
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-drift-fixer` skill.
 
 Audit the `context/` and ensure it correctly describes the system as implemented
diff --git a/config/.opencode/command/handover.md b/config/.opencode/command/handover.md
@@ -3,6 +3,8 @@ description: "Create a structured SCE handover of the current task"
 agent: "Shared Context Code"
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-handover-writer` skill.
 
 Input:
diff --git a/config/.opencode/command/next-task.md b/config/.opencode/command/next-task.md
@@ -3,6 +3,8 @@ description: "Review a plan and execute one SCE task from an approved plan"
 agent: "Shared Context Code"
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow `sce-plan-review`, then `sce-task-execution`, then `sce-context-sync`.
 
 Input:
diff --git a/config/.opencode/command/validate.md b/config/.opencode/command/validate.md
@@ -3,6 +3,8 @@ description: "Run final validation and cleanup for an SCE plan"
 agent: "Shared Context Code"
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 Load and follow the `sce-validation` skill.
 
 Input:
diff --git a/config/.opencode/lib/drift-collectors.js b/config/.opencode/lib/drift-collectors.js
@@ -1,3 +1,6 @@
+// GENERATED FILE: DO NOT EDIT DIRECTLY.
+// Update canonical sources under config/pkl/ and regenerate.
+
 const fs = require("node:fs/promises");
 const path = require("node:path");
 
diff --git a/config/.opencode/skills/sce-bootstrap-context/SKILL.md b/config/.opencode/skills/sce-bootstrap-context/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Bootstrap SCE baseline context directory whe
 compatibility: opencode
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## When to use
 - Use only when `context/` is missing.
 - Ask for human approval before creating files.
diff --git a/config/.opencode/skills/sce-context-sync/SKILL.md b/config/.opencode/skills/sce-context-sync/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Synchronize context files to match current c
 compatibility: opencode
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## Principle
 - Context is durable AI memory and must reflect current-state truth.
 - If context and code diverge, code is source of truth.
diff --git a/config/.opencode/skills/sce-drift-analyzer/SKILL.md b/config/.opencode/skills/sce-drift-analyzer/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to analyze drift between context and code using
 compatibility: opencode
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## What I do
 - Collect context and code signals with pure JavaScript collectors.
 - Analyze semantic drift between documented state and implemented state.
diff --git a/config/.opencode/skills/sce-drift-fixer/SKILL.md b/config/.opencode/skills/sce-drift-fixer/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to audit and repair code-context drift in conte
 compatibility: opencode
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## What I do
 - Audit `context/` and verify it matches the implemented system.
 - Treat code as the source of truth when context and code disagree.
diff --git a/config/.opencode/skills/sce-handover-writer/SKILL.md b/config/.opencode/skills/sce-handover-writer/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to create a structured SCE handover for the cur
 compatibility: opencode
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## What I do
 - Create a new handover file in `context/handovers/`.
 - Capture:
diff --git a/config/.opencode/skills/sce-plan-authoring/SKILL.md b/config/.opencode/skills/sce-plan-authoring/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Create or update an SCE implementation plan
 compatibility: opencode
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## Goal
 Turn a human change request into `context/plans/{plan_name}.md`.
 
diff --git a/config/.opencode/skills/sce-plan-review/SKILL.md b/config/.opencode/skills/sce-plan-review/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to review an existing plan and prepare the next
 compatibility: opencode
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## What I do
 - Continue execution from an existing plan in `context/plans/`.
 - Read the selected plan and identify the next task from the first unchecked checkbox.
diff --git a/config/.opencode/skills/sce-task-execution/SKILL.md b/config/.opencode/skills/sce-task-execution/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Execute one approved task with explicit scop
 compatibility: opencode
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## Scope rule
 - Execute exactly one task per session by default.
 - If multi-task execution is requested, confirm explicit human approval.
diff --git a/config/.opencode/skills/sce-validation/SKILL.md b/config/.opencode/skills/sce-validation/SKILL.md
@@ -4,6 +4,8 @@ description: Use when user wants to Run final plan validation and cleanup with e
 compatibility: opencode
 ---
 
+<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->
+
 ## When to use
 - Use for the plan's final validation task.
 
diff --git a/config/pkl/README.md b/config/pkl/README.md
@@ -15,6 +15,11 @@ Generated by `config/pkl/generate.pkl`:
 - `config/.claude/skills/*/SKILL.md`
 - `config/.claude/lib/drift-collectors.js`
 
+Generated-file safety markers:
+
+- Generated Markdown outputs include an HTML marker comment directly after frontmatter.
+- Generated JavaScript library outputs include a leading `// GENERATED FILE` marker header.
+
 Not generated by this pipeline (manual/runtime-managed):
 
 - dependency artifacts (for example `node_modules`)
diff --git a/config/pkl/renderers/common.pkl b/config/pkl/renderers/common.pkl
@@ -3,7 +3,8 @@ class RenderedTargetDocument {
   title: String
   frontmatter: String
   body: String
-  rendered: String = "\(frontmatter)\n\n\(body)\n"
+  generatedMarker: String = "<!-- GENERATED FILE: DO NOT EDIT DIRECTLY. Update canonical sources under config/pkl/ and regenerate. -->"
+  rendered: String = "\(frontmatter)\n\n\(generatedMarker)\n\n\(body)\n"
 }
 
 commandDescriptions = new Mapping {
diff --git a/context/architecture.md b/context/architecture.md
@@ -35,6 +35,7 @@ Renderer modules apply target-specific metadata/frontmatter rules while reusing
 - Metadata key coverage is enforced by `config/pkl/renderers/metadata-coverage-check.pkl`, which resolves all required lookup keys for both targets and fails evaluation on missing entries.
 - 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.
 
 Generated authored classes:
 
diff --git a/context/patterns.md b/context/patterns.md
@@ -21,6 +21,7 @@
 - Keep per-target metadata tables in dedicated modules (`opencode-metadata.pkl`, `claude-metadata.pkl`) and import them into target renderer modules.
 - Add and run `config/pkl/renderers/metadata-coverage-check.pkl` as a fail-fast metadata completeness guard whenever shared slugs or metadata tables change.
 - In renderer modules, produce per-item document objects with explicit `frontmatter`, `body`, and combined `rendered` fields to keep formatting deterministic and easy to map in a later output stage.
+- Keep generated-file safety markers in the renderer contract (`config/pkl/renderers/common.pkl`) so every generated Markdown artifact receives the same warning text.
 - Validate each renderer module directly with `nix develop -c pkl eval <module-path>` before wiring output emission.
 
 ## Multi-file generation entrypoint
@@ -31,3 +32,4 @@
 - 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.
 - 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.
diff --git a/context/plans/pkl-config-generation.md b/context/plans/pkl-config-generation.md
