xdrs-core 0.54.0 → 0.56.0

package/.xdrs/_core/adrs/index.md

@@ -28,6 +28,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-policy-020](principles/020-media-and-asset-standards.md) - **Media and asset standards** — Canonical diagram format preference order and non-Markdown asset rules for all XDRS document types
 - [_core-adr-policy-021](principles/021-skill-bundling.md) - **Skill bundling** — Optional per-skill Makefile mechanism to stage a self-contained dist/ output for standalone distribution
 - [_core-adr-policy-022](principles/022-scope-activation.md) - **Scope activation** — How installed scopes are listed in the root index, activated, narrowed, or disabled, and when they become read-only
+- [_core-adr-policy-023](principles/023-skill-runtime-standards.md) - **Skill runtime standards** — How skills place work files under .tmp, halt, ask for clarification, and cap generated content
 
 ## Skills
 

package/.xdrs/_core/adrs/principles/003-skill-standards.md

@@ -1,6 +1,6 @@
 ---
 name: _core-adr-policy-003-skill-standards
-description: Defines skill package standards including structure, SKILL.md format, co-location with XDRS packages, and default placement of runtime work files. Use when creating or reviewing skills.
+description: Defines skill package standards including structure, SKILL.md format, script standards, and co-location with XDRS packages. Use when creating or reviewing skills.
 apply-to: All skill packages
 valid-from: 2025-01-01
 ---
@@ -184,45 +184,14 @@ Rules:
 **Script standards**
 
 When a skill includes `scripts/`:
-- Each script MUST declare its runtime/interpreter at the top (shebang or equivalent header comment).
 - SHOULD use the language already used by the consuming project when known, rather than mandating one language repo-wide.
 - MUST avoid non-essential external dependencies, or document install steps in `SKILL.md` when unavoidable.
 - SHOULD support both human-readable and machine-readable (JSON) output when producing analysis or report output.
 - SHOULD stay single-purpose.
 
-**Work files**
+**Runtime behavior**
 
-Files a skill creates while running MUST follow this default unless the skill or user sets another location:
-- `.tmp/[skill-name]-[YYYYMMDDHHMMSS]/` at the workspace root (local start time), created lazily, suffixed `-2`, `-3`... if taken, holds final outputs.
-- Its `.work/` holds intermediate files (caches, staging); `.work/scripts/` holds ad-hoc scripts generated at runtime.
-- Keep it after the run. Workspaces SHOULD gitignore `.tmp/`; skills MUST NOT edit `.gitignore` for it.
-- MUST NOT write secrets there; use environment or harness, or the OS temp dir (deleted after use) when a file is unavoidable.
-- On a read-only workspace, use the same layout under the OS temp dir.
-- When the dir was created, even on halt or failure, end the final chat message with `results-path: [dir]/`.
-- Skills that create files MUST restate the parts of this layout they use in their own `## Instructions`, to run standalone.
-
-**Quality gate**
-
-Before creating a skill, confirm it removes real ambiguity or repetitive effort compared to not having it. Skills that only restate a Policy, or that handle a one-off task unlikely to recur, SHOULD NOT be created.
-
-**Clarify First**
-
-Generative skills — those producing a deliverable document (Policy, Skill, Article, Research, Initiative, Presentation) — SHOULD list the 2-4 inputs they need confirmed (e.g., topic, scope, audience) and ask the user when any is unknown, stopping once those inputs are confirmed rather than over-interrogating. Skills that route, review, or report instead of authoring a new deliverable do not need this pattern.
-
-**Halt behavior**
-
-Skills MUST halt on missing required input, dubious/ambiguous input, or insufficient agent confidence, unless the user explicitly instructs the agent to proceed anyway. This override applies generally; a skill's own `## Halt Conditions` list does not need to restate it.
-
-**Generated content caps**
-
-Every natural-language content a skill generates MUST declare a hard word cap written exactly as `<N words`, whether a human or an agent executes the skill. This covers files, templates, reports, intermediate chat messages, HITL questions, final summaries, and text posted to external systems (e.g., PR comments, commit messages).
-- Exempt, with no marker: code (including its comments), structured data (JSON, YAML, tracking files), verbatim copies, and frontmatter fields already limited in characters by a spec or Policy.
-- Caps MUST be in words; other limits MAY coexist but never replace them.
-- Declare each cap once: in the template placeholder (including templates in `references/` or `.assets/`), else in the Instructions step producing the content, else in its `#### Contents` bullet.
-- A blanket statement MAY cover a content class (e.g., all intermediate messages); a more specific cap overrides it.
-- Write the number inline; a Policy reference is optional.
-- Content whose size cannot be bounded MUST be marked `(uncapped: <reason>)`, the reason explaining why.
-- Caps are hard: condense, or split into another item only where the skill allows it; never split one logical item across messages. An explicit user request lifts the cap for that item only.
+How a skill behaves while running (work files, quality gate, clarifying questions, halting, generated content caps) is defined in [`_core-adr-policy-023`](023-skill-runtime-standards.md).
 
 **Validation**
 
@@ -239,6 +208,7 @@ skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[skill-name]
 - [skills-ref validation library](https://github.com/agentskills/agentskills/tree/main/skills-ref)
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md)
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
+- [_core-adr-policy-023 - Skill runtime standards](023-skill-runtime-standards.md)
 - [_core-adr-policy-005 - Semantic versioning for XDRS packages](005-semantic-versioning-for-xdrs-packages.md)
 - [_core-adr-policy-006 - Research standards](006-research-standards.md)
 - [_core-adr-policy-021 - Skill bundling](021-skill-bundling.md)

package/.xdrs/_core/adrs/principles/019-compiled-scope-type.md

@@ -114,7 +114,7 @@ All access control implementations MUST enforce the principle of least privilege
 
 Unless a meta-policy declares `Source storage: temporary`, fetched and selected source content (rule 13) MUST be persisted under `[type]/principles/.assets/sources/[name]/`, sibling to the governing meta-policy, where `[name]` is the source's slug from its `## Sources` bullet. This location is shared across every subject compiled under that meta-policy's type folder; it is not duplicated per subject. Persisted source content MUST be committed to version control and MUST NOT be gitignored.
 
-When `Source storage: temporary` is declared, bulk fetched content MUST instead be written only to the compilation execution dir's `.work/staging/` (see Work files in `_core-adr-policy-003`) and MUST NOT be persisted under `.assets/sources/`.
+When `Source storage: temporary` is declared, bulk fetched content MUST instead be written only to `.tmp/compile-scope/.work/staging/[name]/` (see Work files in `_core-adr-policy-023`) and MUST NOT be persisted under `.assets/sources/`.
 
 Regardless of storage mode, a tracking file `.assets/sources/[name]/source.md` MUST always be created and kept up to date, with the following format:
 

package/.xdrs/_core/adrs/principles/023-skill-runtime-standards.md

@@ -0,0 +1,63 @@
+---
+name: _core-adr-policy-023-skill-runtime-standards
+description: Defines how skills behave at runtime - where they place work files, when to halt or ask the user, quality gate before creating a skill, and word caps for generated content. Use when authoring or reviewing skill instructions.
+apply-to: All skill packages
+valid-from: 2026-10-08
+---
+
+# _core-adr-policy-023: Skill runtime standards
+
+## Context and Problem Statement
+
+Skills run for humans and AI agents in many workspaces. Without shared runtime rules, each skill invents its own place for generated files, its own halting behavior, and its own output sizes, which litters workspaces, risks leaking secrets, and makes skills unpredictable.
+
+How should a skill behave while running, so that its files, questions, stops and generated content are consistent across skills?
+
+## Decision Outcome
+
+**A shared runtime contract for every skill, separate from the skill package format**
+
+Package structure, `SKILL.md` format, scripts and validation are defined in [`_core-adr-policy-003`](003-skill-standards.md). This Policy defines only what a skill does while it runs.
+
+### Details
+
+**Work files**
+
+Files a skill creates while running MUST follow this layout unless the skill or the user sets another location:
+- Each skill owns `.tmp/[skill-name]/` at the workspace root, created lazily. Workspaces SHOULD gitignore `.tmp/`; skills MUST NOT edit `.gitignore` for it.
+- Skills MUST NOT store files directly in `.tmp/[skill-name]/`. Final outputs go in one run folder per run, `.tmp/[skill-name]/[run-name]/`.
+- `[run-name]` is a short name describing the run (e.g. `report-anthony`), using only lowercase letters, digits and hyphens. When the run has no natural name, use the local start time `[YYYYMMDDHHMMSS]`. When the name is taken, append `-2`, `-3`...
+- `.tmp/[skill-name]/.work/` holds reusable intermediate files such as caches and staging. It is safe to delete at any time. Skills MUST re-check freshness before reusing its content and MUST namespace content per input (e.g. `.work/staging/[input-name]/`). Clearing and refetching an input is not safe while another run uses the same input.
+- Skills that produce no final outputs use only `.work/`, with no run folder.
+- Temporary scripts and other throwaway files MUST go in the OS temp dir and be deleted when the run ends. Secrets MUST NOT be written anywhere else and MUST always be deleted.
+- A skill that uses another skill's output MUST receive the source run folder path as input, read it in place and never change data there. When changes are needed, it copies the files into its own run folder.
+- On a read-only workspace, use the same layout under the OS temp dir.
+- Keep run folders after the run. When a run folder was created, even on halt or failure, end the final chat message with `results-path: [dir]/`.
+- Skills that create files MUST restate the parts of this layout they use in their own `## Instructions`, to run standalone.
+
+**Quality gate**
+
+Before creating a skill, confirm it removes real ambiguity or repetitive effort compared to not having it. Skills that only restate a Policy, or that handle a one-off task unlikely to recur, SHOULD NOT be created.
+
+**Clarify First**
+
+Generative skills — those producing a deliverable document (Policy, Skill, Article, Research, Initiative, Presentation) — SHOULD list the 2-4 inputs they need confirmed (e.g., topic, scope, audience) and ask the user when any is unknown, stopping once those inputs are confirmed rather than over-interrogating. Skills that route, review, or report instead of authoring a new deliverable do not need this pattern.
+
+**Halt behavior**
+
+Skills MUST halt on missing required input, dubious/ambiguous input, or insufficient agent confidence, unless the user explicitly instructs the agent to proceed anyway. This override applies generally; a skill's own `## Halt Conditions` list does not need to restate it.
+
+**Generated content caps**
+
+Every natural-language content a skill generates MUST declare a hard word cap written exactly as `<N words`, whether a human or an agent executes the skill. This covers files, templates, reports, intermediate chat messages, HITL questions, final summaries, and text posted to external systems (e.g., PR comments, commit messages).
+- Exempt, with no marker: code (including its comments), structured data (JSON, YAML, tracking files), verbatim copies, and frontmatter fields already limited in characters by a spec or Policy.
+- Caps MUST be in words; other limits MAY coexist but never replace them.
+- Declare each cap once: in the template placeholder (including templates in `references/` or `.assets/`), else in the Instructions step producing the content, else in its `#### Contents` bullet.
+- A blanket statement MAY cover a content class (e.g., all intermediate messages); a more specific cap overrides it.
+- Write the number inline; a Policy reference is optional.
+- Content whose size cannot be bounded MUST be marked `(uncapped: <reason>)`, the reason explaining why.
+- Caps are hard: condense, or split into another item only where the skill allows it; never split one logical item across messages. An explicit user request lifts the cap for that item only.
+
+## References
+
+- [_core-adr-policy-003 - Skill standards](003-skill-standards.md)

package/.xdrs/_core/adrs/principles/skills/compile-scope/SKILL.md

@@ -4,8 +4,8 @@ description: >
   Compiles or updates any scope declaring `scope-type: compiled` from its configured external sources. Reads compilation meta-policies to discover sources, fetches content (git clone, local copy, or web scrape), plans policy changes, migrates policies one at a time with structured format, `## Source` sections, and `**compilation-note:**` markers, then runs lint and review. Documents source inconsistencies without inventing fixes. Activate when the user asks to compile, update, sync, refresh, or recompile a compiled scope.
 metadata:
   author: flaviostutz
-  version: "1.2.0"
-  updated: 2026-09-30
+  version: "1.3.0"
+  updated: 2026-10-08
 ---
 
 ## Overview
@@ -76,11 +76,11 @@ Keep every question and intermediate message <100 words and the final summary <1
 
 ### Phase 2: Fetch Sources
 
-1. Create the execution dir `.tmp/compile-scope-[YYYYMMDDHHMMSS]/` at the workspace root (local start time; append `-2`, `-3`... if it exists) with a `.work/staging/` folder. Put any other intermediate file in `.work/` and any ad-hoc script you generate in `.work/scripts/`; never write secrets there (pass them via environment, or use the OS temp dir and delete the file after use). If the workspace is read-only, use the same layout under the OS temp dir. Keep the dir after the run.
+1. Use `.tmp/compile-scope/.work/staging/[name]/` at the workspace root as the staging folder of each source (`[name]` is the source slug); this skill has no run folder. Delete that folder before fetching into it, so no stale content is reused. Never write secrets or ad-hoc scripts there; use the OS temp dir for them and delete them when the run ends. If the workspace is read-only, use the same layout under the OS temp dir. Keep staging after the run.
 2. For each due source (from Phase 1), fetch in the following preference order (first available wins; if all equivalent URLs are listed, try each in order):
-   - **Git URL** (`- [git] ...`): run `git clone --depth=1 [url] .tmp/compile-scope-[ts]/.work/staging/[name]/`. If `git` is not available or the clone fails, fall back to the next option.
-   - **Local folder** (`- [local] ...`): copy the folder contents to `.tmp/compile-scope-[ts]/.work/staging/[name]/`.
-   - **Web URL** (`- [web] ...`): before scraping, search the workspace for a skill specialized in fetching content from this URL or website domain (e.g., a skill whose description or name references the domain, the product, or the content type). Some websites require special handling — SSO, client certificates, shadow DOM, iframes, CAPTCHAs, or other quirks. If a specialized fetch skill is found, follow it to retrieve the content. If no specialized skill exists, fall back to `npx --package=@playwright/cli@latest playwright-cli`; run with `--help` to confirm available commands and save output as `.html` file(s) in `.tmp/compile-scope-[ts]/.work/staging/[name]/`.
+   - **Git URL** (`- [git] ...`): run `git clone --depth=1 [url] .tmp/compile-scope/.work/staging/[name]/`. If `git` is not available or the clone fails, fall back to the next option.
+   - **Local folder** (`- [local] ...`): copy the folder contents to `.tmp/compile-scope/.work/staging/[name]/`.
+   - **Web URL** (`- [web] ...`): before scraping, search the workspace for a skill specialized in fetching content from this URL or website domain (e.g., a skill whose description or name references the domain, the product, or the content type). Some websites require special handling — SSO, client certificates, shadow DOM, iframes, CAPTCHAs, or other quirks. If a specialized fetch skill is found, follow it to retrieve the content. If no specialized skill exists, fall back to `npx --package=@playwright/cli@latest playwright-cli`; run with `--help` to confirm available commands and save output as `.html` file(s) in `.tmp/compile-scope/.work/staging/[name]/`.
 3. If any source cannot be fetched via any listed option, report the failure and continue with remaining sources. Do not abort the entire compilation for a single failed source.
 4. Immediately after a source is fetched successfully, create `.assets/sources/[name]/source.md` if absent and update its `last-fetch-timestamp` to the current time — this happens regardless of the `Source storage` setting, since the tracking file always persists per `_core-adr-policy-019` rule 12.
 5. Convert non-markdown documents found in the fetched source directories. Use only the format converters actually needed:
@@ -178,7 +178,6 @@ After writing each policy:
    - Any sources that could not be fetched.
    - Lint and review pass/fail status.
    - Sources persisted, kept temporary, or skipped as already in sync.
-2. Whenever the execution dir was created, including when halting in an earlier phase, end the final message with `results-path: .tmp/compile-scope-[ts]/` (the actual dir).
 
 ## Anti-Patterns
 
@@ -205,4 +204,5 @@ After writing each policy:
 ## References
 
 - [_core-adr-policy-019 - Compiled scope type](../../019-compiled-scope-type.md)
+- [_core-adr-policy-023 - Skill runtime standards](../../023-skill-runtime-standards.md)
 - [_core-adr-policy-008 - Policy structured standards](../../008-policy-structured-standards.md)

package/.xdrs/_core/adrs/principles/skills/review/SKILL.md

@@ -6,8 +6,8 @@ description: >
    Also activate when you identify a need to check compliance with Policies during implementation.
 metadata:
   author: flaviostutz
-  version: "1.2.0"
-  updated: 2026-09-30
+  version: "1.3.0"
+  updated: 2026-10-08
 ---
 
 ## Overview
@@ -81,12 +81,12 @@ Keep every question and intermediate message <100 words.
 ### Phase 3: Diagram Validation
 
 1. For every file in scope, scan for fenced ` ```mermaid ` code blocks.
-2. For each diagram found, extract the content to a `.mmd` file in `.tmp/review-[YYYYMMDDHHMMSS]/.work/` at the workspace root (local start time; create it only when the first diagram is found, append `-2`, `-3`... if it exists, and use the same layout under the OS temp dir if the workspace is read-only) and run:
+2. For each diagram found, extract the content to a `.mmd` file in a temporary folder under the OS temp dir (create it only when the first diagram is found) and run:
    ```bash
    npx -y @mermaid-js/mermaid-cli -i <file>.mmd --quiet 2>&1
    ```
 3. For each diagram that fails validation, report as ERROR: include the file path, approximate location (heading or surrounding text), and the error message from `mmdc`.
-4. Keep the extracted files after the run; if this step created the dir, fill the `results-path` line of the report template.
+4. Delete the temporary folder and its `.mmd` files when the review ends, including when halting.
 
 ### Phase 4: Policy Review
 
@@ -134,8 +134,6 @@ Scope: [scope identifier]
 - Errors: [count]
 - Warnings: [count]
 - Outcome: [PASS|FAIL]
-
-results-path: [.tmp/review-[ts]/ actual dir; include this line only when Phase 3 created it]
 ```
 
 ### Constraints
@@ -170,3 +168,4 @@ results-path: [.tmp/review-[ts]/ actual dir; include this line only when Phase 3
 - [_core-adr-policy-002 - Policy standards](../../002-policy-standards.md)
 - [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
 - [_core-adr-policy-020 - Media and asset standards](../../020-media-and-asset-standards.md)
+- [_core-adr-policy-023 - Skill runtime standards](../../023-skill-runtime-standards.md)

package/.xdrs/_core/adrs/principles/skills/write-skill/SKILL.md

@@ -6,13 +6,13 @@ description: >
   Activate this skill when the user asks to create, add, or write a new skill, agent skill, or SKILL.md file.
 metadata:
   author: flaviostutz
-  version: "1.2.0"
-  updated: 2026-09-30
+  version: "1.3.0"
+  updated: 2026-10-08
 ---
 
 ## Overview
 
-Guides the creation of a well-structured skill package by following `_core-adr-policy-003` skill standards, consulting `xdrs-core` for every core element definition, checking existing skills to avoid duplication, and producing a complete SKILL.md ready to activate in VS Code.
+Guides the creation of a well-structured skill package by following `_core-adr-policy-003` skill standards and `_core-adr-policy-023` runtime standards, consulting `xdrs-core` for every core element definition, checking existing skills to avoid duplication, and producing a complete SKILL.md ready to activate in VS Code.
 
 ### Inputs
 
@@ -57,7 +57,7 @@ Keep every question and intermediate message <100 words and the final summary <1
 
 ### Phase 1: Understand the Skill Goal
 
-1. Read `.xdrs/_core/adrs/principles/003-skill-standards.md` in full to internalize the SKILL.md format and folder layout.
+1. Read `.xdrs/_core/adrs/principles/003-skill-standards.md` and `.xdrs/_core/adrs/principles/023-skill-runtime-standards.md` in full to internalize the SKILL.md format, folder layout and runtime rules.
 2. Read `.xdrs/_core/adrs/principles/001-xdrs-standards.md` in full before defining any core element for the skill package. Treat it as the canonical source for type, scope, subject, naming constraints, and folder placement rules.
 3. Identify what the skill must do, the concrete outcome it should produce, and the exact conditions under which an agent should activate it. Do NOT proceed without a clear goal, outcome, and activation trigger.
 
@@ -170,9 +170,9 @@ Rules:
 - The `description` field must state both *what* the skill does and *when* to activate it.
 - Keep the skill task-oriented. It should have a clear starting trigger and a concrete ending result.
 - Mention tools or prerequisites when they are required to complete the task reliably.
-- Declare a "<N words" cap, or "(uncapped: <reason>)", exactly once for every natural-language content the skill generates, per **Generated content caps** in `_core-adr-policy-003`.
+- Declare a "<N words" cap, or "(uncapped: <reason>)", exactly once for every natural-language content the skill generates, per **Generated content caps** in `_core-adr-policy-023`.
 - Do not duplicate content from referenced Policies — link instead.
-- If the skill creates files at runtime (outputs, intermediate files, ad-hoc scripts), restate in `## Instructions`, next to the steps writing them, the parts of **Work files** in `_core-adr-policy-003` it uses: `.tmp/[skill-name]-[YYYYMMDDHHMMSS]/`, `.work/`, `.work/scripts/`, and the final `results-path:` line. This restatement is the one exception to the no-duplication rule, so the skill runs standalone.
+- If the skill creates files at runtime (outputs, intermediate files, ad-hoc scripts), restate in `## Instructions`, next to the steps writing them, the parts of **Work files** in `_core-adr-policy-023` it uses: `.tmp/[skill-name]/[run-name]/` (never files directly in `.tmp/[skill-name]/`), `.work/`, the OS temp dir for throwaway files, and the final `results-path:` line when a run folder is created. This restatement is the one exception to the no-duplication rule, so the skill runs standalone.
 - Do not present the skill itself as policy; mandatory behavior must come from referenced Policies or other policy artifacts.
 - When the skill depends on Policies, make the activation logic and instructions consistent with the Policy metadata so the skill does not operationalize inactive or out-of-scope decisions.
 - For diagrams and non-Markdown assets, follow `_core-adr-policy-020`: prefer plain Markdown tables/lists first, then ASCII art for very simple cases, then Mermaid.js (sequence, state, activity, entity diagrams) for complex ones, then draw.io when Mermaid is insufficient — save as Editable Vector (File → Save As → Editable Vector) and store as `.svg` in the sibling `.assets/` folder.
@@ -193,7 +193,7 @@ Before writing files, verify:
 7. **Required sections**: Does `## Overview` contain nested `### Inputs` (Required/Optional bullets), `### Outputs` (Contents/Changes bullets), and `### Halt Conditions` listing this skill's specific stop triggers — each bullet under 20 words or a single "None"?
 8. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `skill`.
 9. **Output caps**: Does every natural-language content the skill generates (files, messages, questions, summaries, external posts) have exactly one "<N words" cap or "(uncapped: <reason>)" marker, with code and structured data unmarked?
-10. **Work files**: If the skill creates files at runtime, do its Instructions restate the default execution dir, `.work/`, `.work/scripts/`, and `results-path:` line from `_core-adr-policy-003`, or an explicit alternative location?
+10. **Work files**: If the skill creates files at runtime, do its Instructions restate the run folder, `.work/`, OS temp dir and `results-path:` rules from `_core-adr-policy-023`, or an explicit alternative location?
 
 If any check fails, revise before continuing.
 
@@ -261,6 +261,7 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 ## References
 
 - [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
+- [_core-adr-policy-023 - Skill runtime standards](../../023-skill-runtime-standards.md)
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
 - [_core-adr-policy-021 - Skill bundling](../../021-skill-bundling.md)
 - [write-policy skill](../write-policy/SKILL.md)

package/.xdrs/_core/adrs/principles/skills/write-xdrs-doc/SKILL.md

@@ -5,8 +5,8 @@ description: >
   Activate this skill when the user asks to create or write any XDRS element.
 metadata:
   author: flaviostutz
-  version: "1.2.0"
-  updated: 2026-09-30
+  version: "1.3.0"
+  updated: 2026-10-08
 ---
 
 ## Overview
@@ -81,12 +81,12 @@ Read the full content of the skill file for the inferred type, then follow all i
 ### Phase 3: Validate Mermaid Diagrams
 
 1. After the delegated skill completes, scan all files written in this session for fenced ` ```mermaid ` code blocks.
-2. For each diagram found, extract the content to a `.mmd` file in `.tmp/write-xdrs-doc-[YYYYMMDDHHMMSS]/.work/` at the workspace root (local start time; create it only when the first diagram is found, append `-2`, `-3`... if it exists, and use the same layout under the OS temp dir if the workspace is read-only) and run:
+2. For each diagram found, extract the content to a `.mmd` file in a temporary folder under the OS temp dir (create it only when the first diagram is found) and run:
    ```bash
    npx -y @mermaid-js/mermaid-cli -i <file>.mmd --quiet 2>&1
    ```
 3. For each diagram that fails validation, report the error to the user and ask them to correct the diagram before saving.
-4. Keep the extracted files after the run; if this step created the dir, end the final summary with `results-path: .tmp/write-xdrs-doc-[ts]/` (the actual dir), including when halting.
+4. Delete the temporary folder and its `.mmd` files when the run ends, including when halting.
 
 ### Constraints
 

package/.xdrs/_core/index.md

@@ -32,7 +32,7 @@ Each artifact type has its own writing standard:
 
 - **Policy documents** follow [_core-adr-policy-002](adrs/principles/002-policy-standards.md), which defines the mandatory template, frontmatter metadata, applicability rules, conflict handling, and word limits that keep decisions concise and authoritative.
 - **Structured Policies** with individually referenceable rules follow the extension [_core-adr-policy-008](adrs/principles/008-policy-structured-standards.md), adding numbered rule blocks and a dot-notation citation syntax.
-- **Skills** follow [_core-adr-policy-003](adrs/principles/003-skill-standards.md), using the agentskills format so they work for both humans and AI agents on an automation gradient from fully manual to fully automated.
+- **Skills** follow [_core-adr-policy-003](adrs/principles/003-skill-standards.md) and [_core-adr-policy-023](adrs/principles/023-skill-runtime-standards.md), using the agentskills format so they work for both humans and AI agents on an automation gradient from fully manual to fully automated.
 - **Articles** follow [_core-adr-policy-004](adrs/principles/004-article-standards.md), providing synthetic views that combine and link multiple Policies, research, and skills without replacing them as the source of truth.
 - **Research** follows [_core-adr-policy-006](adrs/principles/006-research-standards.md), using an IMRAD-based structure for studies that back decisions with reproducible evidence.
 - **Initiatives** follow [_core-adr-policy-007](adrs/principles/007-initiative-standards.md), capturing ephemeral execution initiatives with problem context, proposed solutions, milestones, and deliverables that are deleted after implementation.

package/lib/lint.js

@@ -50,7 +50,6 @@ const SKILL_OPTIONAL_RUNTIME_SECTION = '### Runtime Requirements';
 const SKILL_OPTIONAL_USER_INTERACTION_SECTION = '### User Interaction';
 const SKILL_ANTI_PATTERNS_MIN_ENTRIES = 3;
 const SKILL_BUNDLING_MAKEFILE_TARGETS = ['build', 'test', 'clean'];
-const SCRIPT_HEADER_RE = /^(#!|#|\/\/|\/\*|<!--|--|;)/;
 
 // Subject number block ranges per _core-adr-policy-017
 const SUBJECT_NUMBER_RANGES = {
@@ -1264,10 +1263,6 @@ function lintSkillsDirectory(xdrsRoot, scopeName, skillsPath, errors, externalSc
         }
       }
 
-      if (packageEntry.name === 'scripts') {
-        lintSkillScriptHeaders(packageEntryPath, errors);
-      }
-
       if (SKILL_PACKAGE_OPTIONAL_DIRS.has(packageEntry.name)) {
         continue;
       }
@@ -1637,24 +1632,6 @@ function lintSkillAntiPatternsCount(content, filePath, errors) {
   }
 }
 
-/**
- * Validates that each file inside a skill's scripts/ directory declares its runtime or
- * interpreter at the top (shebang or header comment) per _core-adr-policy-003.
- */
-function lintSkillScriptHeaders(scriptsPath, errors) {
-  const entries = safeReadDir(scriptsPath, errors, `read scripts directory ${toDisplayPath(scriptsPath)}`);
-  for (const entry of entries) {
-    if (!entry.isFile()) {
-      continue;
-    }
-    const scriptPath = path.join(scriptsPath, entry.name);
-    const content = fs.readFileSync(scriptPath, 'utf8');
-    if (!SCRIPT_HEADER_RE.test(firstNonEmptyLine(content))) {
-      errors.push(`Script must declare its runtime/interpreter at the top (shebang or header comment): ${toDisplayPath(scriptPath)} [_core-adr-policy-003]`);
-    }
-  }
-}
-
 /**
  * Validates an optional skill bundling Makefile per _core-adr-policy-021: it must expose
  * build/test/clean targets, and its dist/ output must be covered by a .gitignore.

package/lib/lint.test.js

@@ -866,7 +866,7 @@ test('passes when skill bundling Makefile dist output is covered by a local .git
   expect(result.errors.join('\n')).not.toContain('is not covered by any .gitignore');
 });
 
-test('reports scripts/ file missing a shebang or header comment', () => {
+test('does not require a shebang or header comment in scripts/ files', () => {
   const workspaceRoot = createWorkspace('skill-script-missing-header', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
@@ -881,26 +881,7 @@ test('reports scripts/ file missing a shebang or header comment', () => {
 
   const result = lintWorkspace(workspaceRoot);
 
-  expect(result.errors.join('\n')).toContain('Script must declare its runtime/interpreter at the top');
-});
-
-test('passes when scripts/ file declares a shebang', () => {
-  const workspaceRoot = createWorkspace('skill-script-with-shebang', {
-    '.xdrs/index.md': rootIndex(),
-    '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
-    ]),
-    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Test instructions.'),
-    '.xdrs/_local/adrs/principles/skills/check-links/scripts/run.sh': [
-      '#!/bin/bash',
-      'echo "has a shebang"',
-      ''
-    ].join('\n'),
-  });
-
-  const result = lintWorkspace(workspaceRoot);
-
-  expect(result.errors.join('\n')).not.toContain('Script must declare its runtime/interpreter at the top');
+  expect(result.errors.join('\n')).not.toContain('scripts/run.sh');
 });
 
 test('accepts skill package names containing digits, including as a prefix', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "XDRS (eXtensible Decision Record System): a framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",