xdrs-core 0.55.0 → 0.56.1

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

@@ -28,6 +28,8 @@ 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
+- [_core-adr-policy-024](principles/024-sync-date-frontmatter.md) - **Sync date frontmatter** — Optional `sync-date` field recording when an element was last verified or reconciled with other entities
 
 ## Skills
 

package/.xdrs/_core/adrs/principles/001-xdrs-standards.md

@@ -91,6 +91,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
     - `apply-to` (required): Declares in which contexts — teams, systems, codebases, or environments — the decisions in this scope are relevant. Max 30 words.
     - `valid-from` (required): ISO date (YYYY-MM-DD) from which this scope became active.
     - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
+    - `sync-date` (optional, opt-in): see `_core-adr-policy-024`.
     - `follows` (optional): Core scope names whose Policies apply as mandatory governance conventions to this scope, beyond `_core`. Last-listed takes precedence on conflicts (e.g., `follows: myarea-core, shared-standards`). A missing scope MUST be fixed in local scopes and makes external scopes READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`).
     - `extends` (optional): Scope names whose **policy documents** (decision records only — not skills, articles, research, or initiatives) are inherited by this scope as if they were authored here. Any scope type except `_local` and `_core` may be referenced. Last-listed extended scope takes precedence on conflicts; the extending scope's own policies always take highest precedence. Depth-first transitive resolution applies: if A extends [B, C] and B extends [D], the effective precedence order is D < B < C < A. `extends:` and `follows:` MUST reference disjoint scope sets. A missing scope MUST be fixed in local scopes and makes external scopes READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`). When an extending scope's policy overrides an inherited policy on the same topic, a `## Conflicts` section MUST document the override. Extended scopes are still linked in the root index; tag them `extends-only` to apply them only via `extends:` (see `_core-adr-policy-022.01-root-index-completeness`). `extends:` takes precedence over root index ordering for conflict resolution between the scopes involved; root index ordering is the fallback for all other scope pairs. See `_core-adr-policy-010` Section D (rules 27–35) and Section E (rule 36) for full normative rules.
     - `extends-only` (optional): See `_core-adr-policy-022.07-extends-only-field`.

package/.xdrs/_core/adrs/principles/002-policy-standards.md

@@ -31,6 +31,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
 | `valid-from` | Yes | ISO date (`YYYY-MM-DD`) indicating from when this decision MUST be enforced. Before this date it SHOULD be used everywhere possible, but compliance is not enforced during reviews until after this date. Defaults to the date the Policy was created. When updating an existing Policy whose `valid-from` date has already passed, preserve the original date—it MUST NOT be updated to the current date. The historical date shows when the policy was originally enabled and is important for understanding policy evolution. |
 | `license` | No | SPDX license expression (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`). Indicates the license under which the document content is shared. If omitted, the license is governed by the repository or package defaults. |
 | `metadata` | No | Arbitrary key-value map for additional properties not defined by this spec. |
+| `sync-date` | No | ISO date (`YYYY-MM-DD`) of the last verification or reconciliation of the Policy with other entities. Opt-in, never added by default, and MUST NOT appear in Policies of `compiled` scopes. See [`_core-adr-policy-024`](024-sync-date-frontmatter.md). |
 | `freeze-reference` | No | Boolean (`true` or `false`, defaults to `false`). When `true`, the policy MUST NOT be renamed, renumbered, or moved because external parties reference it by its current identity (path, number, name, heading). Reference-identity issues are intentionally exempt. See rule [`01-freeze-reference-exemption`](#01-freeze-reference-exemption). |
 
   - Minimal example:
@@ -116,6 +117,7 @@ description: [What this decision is about and when to use it]
 apply-to: [Required. Contexts this decision applies to, <40 words. Use "All scopes" when broadly applicable.]
 valid-from: [Required. ISO date YYYY-MM-DD from when enforcement begins. Defaults to creation date.]
 license: [Optional. SPDX license expression]
+sync-date: [Optional, opt-in. ISO date of the last verification with other entities; see _core-adr-policy-024]
 metadata:
   [optional-key]: [optional-value]
 ---

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
 ---
@@ -104,6 +104,7 @@ metadata:                 # required
   author: <team-or-person>       # required
   version: "1.0.0"                # required: full semantic versioning
   updated: YYYY-MM-DD              # required: date of the last material content change
+  sync-date: YYYY-MM-DD            # optional, opt-in: date of the last verification with other entities (see _core-adr-policy-024)
 ---
 
 ## Overview
@@ -163,6 +164,7 @@ Rules:
 - The `name` field MUST match the folder name exactly (e.g., `code-review`). This keeps skill identifiers simple and aligned with the filesystem hierarchy.
 - The directory name and the `name:` field MUST contain only lowercase alphanumeric characters and hyphens (e.g., `code-review`, `2fa-setup`).
 - `metadata` is REQUIRED. `metadata.version` MUST use full semantic versioning (`MAJOR.MINOR.PATCH`, e.g. `1.0.0`), consistent with [`_core-adr-policy-005`](005-semantic-versioning-for-xdrs-packages.md); `metadata.author` MUST be non-empty; `metadata.updated` MUST be an ISO `YYYY-MM-DD` date, refreshed whenever the skill's content materially changes.
+- `metadata.sync-date` is OPTIONAL and follows [`_core-adr-policy-024`](024-sync-date-frontmatter.md); it is distinct from `metadata.updated`, which records content changes only.
 - `description` SHOULD stay near 250 characters when the activation trigger can be stated that tightly, even though the hard cap remains 1024 characters — it is loaded into context on every activation scan.
 - `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter, and MUST contain nested subsections, in order, for `### Inputs`, `### Outputs`, `### Halt Conditions`, then the optional `### User Interaction` and `### Runtime Requirements`.
 - `### Inputs` MUST contain `#### Required` (the bare minimum needed to invoke the skill) then `#### Optional` (helpful extra context), in that order.
@@ -189,39 +191,9 @@ When a skill includes `scripts/`:
 - 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**
 
@@ -238,6 +210,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/004-article-standards.md

@@ -42,6 +42,7 @@ Articles are Markdown documents placed inside a subject folder alongside policie
 - For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). Articles SHOULD use diagrams to illustrate concepts, overviews, and relationships; draw.io SHOULD be used for conceptual and relationship diagrams (e.g., component maps, context views, architecture overviews) when Mermaid cannot adequately express them.
 - File names MUST be lowercase.
 - MUST NOT use emojis in article content.
+- An article MAY start with a frontmatter block containing only `sync-date`, per [`_core-adr-policy-024`](024-sync-date-frontmatter.md); the title line follows the block.
 
 **Folder layout**
 
@@ -71,6 +72,10 @@ Examples:
 All articles MUST follow this template:
 
 ```markdown
+---
+sync-date: [Optional, opt-in. ISO date of the last verification with other entities; see _core-adr-policy-024. When absent, omit the whole frontmatter block.]
+---
+
 # [scope]-[type]-article-[number]: [Short Title]
 
 <!-- If this article is part of a series, add the line below (omit otherwise): -->

package/.xdrs/_core/adrs/principles/006-research-standards.md

@@ -46,6 +46,7 @@ Research documents are Markdown files placed inside a subject folder alongside p
 - `## Conclusion` MUST summarize the main findings, practical takeaway, applicability boundaries, and important open questions. It MUST stay under 400 words.
 - `## References` MUST list all cited literature, websites, tutorials, documentation, discussions, or related artifacts.
 - In general, research SHOULD roughly follow the proportion `Introduction : Methods : Results : Discussion ≈ 3 : 5 : 6 : 4`.
+- A research document MAY start with a frontmatter block containing only `sync-date`, per [`_core-adr-policy-024`](024-sync-date-frontmatter.md); the title line follows the block.
 - Be strict about the goal of each section. Avoid duplicating the same material across sections and prefer clarity over rhetorical flourishes.
 - Research documents SHOULD stay under 5000 words total. They MAY exceed that only when the `## Introduction` explicitly states that the study will be lengthy because a very detailed analysis is required.
 - Research documents SHOULD link in `## References` to the Policies, skills, articles, discussions, and external references relevant to the subject or that later cite the work.
@@ -83,6 +84,10 @@ Examples:
 All research documents MUST follow this template:
 
 ```markdown
+---
+sync-date: [Optional, opt-in. ISO date of the last verification with other entities; see _core-adr-policy-024. When absent, omit the whole frontmatter block.]
+---
+
 # [scope]-[type]-research-[number]: [Short Title]
 
 ## Abstract

package/.xdrs/_core/adrs/principles/007-initiative-standards.md

@@ -34,6 +34,7 @@ Initiatives are Markdown documents placed inside a subject folder alongside poli
 - Initiatives MUST include an `Expected end date:` field in ISO format (YYYY-MM-DD) inside the `## Proposed Solution` section.
 - File names MUST be lowercase.
 - MUST NOT use emojis in initiative content.
+- An initiative MAY start with a frontmatter block containing only `sync-date`, per [`_core-adr-policy-024`](024-sync-date-frontmatter.md); the title line follows the block.
 - For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
 
 **Folder layout**
@@ -63,6 +64,10 @@ Examples:
 All initiatives MUST follow this template:
 
 ```markdown
+---
+sync-date: [Optional, opt-in. ISO date of the last verification with other entities; see _core-adr-policy-024. When absent, omit the whole frontmatter block.]
+---
+
 # [scope]-[type]-initiative-[number]: [Short Title]
 
 ## Executive Summary

package/.xdrs/_core/adrs/principles/010-scope-governance.md

@@ -83,7 +83,7 @@ A scope-type definition policy MAY declare a parent scope type by including a ru
 
 A `scope-type` value in a scope `index.md` is valid if and only if a policy file whose name ends with `{scope-type}-scope-type` exists in the `principles` subject of any `core`-type scope in the workspace. When `scope-type` is an array, this applies to every element.
 
-When a scope declares a `scope-type` but any corresponding `{scope-type}-scope-type.md` policy is absent from the workspace or defined only in a `disabled` scope, the scope MUST be treated as READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`). Missing or disabled-only types MUST be fixed in local scopes.
+When a scope declares a `scope-type` but any corresponding `{scope-type}-scope-type.md` policy is absent from the workspace or defined only in a `disabled` scope, the scope MUST be treated as READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`). Missing or disabled-only types MUST be fixed in local scopes, unless the scope is itself disabled.
 
 #### 11-def-scope-type-must-be-structured
 
@@ -213,7 +213,7 @@ A scope `extends:` declaration MUST NOT reference the declaring scope itself. To
 
 #### 32-extends-mandatory-presence
 
-Every scope listed in a scope's `extends:` field MUST exist in the workspace with an accessible `index.md`. If any referenced scope is absent or its `index.md` cannot be read, the extending scope MUST be fixed when local and is READ-ONLY when external (`_core-adr-policy-022.06-read-only-dependencies`).
+Every scope listed in a scope's `extends:` field MUST exist in the workspace with an accessible `index.md`. If any referenced scope is absent or its `index.md` cannot be read, the extending scope MUST be fixed when local and is READ-ONLY when external, unless it is itself disabled (`_core-adr-policy-022.06-read-only-dependencies`).
 
 #### 33-extends-content-precedence
 

package/.xdrs/_core/adrs/principles/011-core-scope-type.md

@@ -65,7 +65,7 @@ A `core`-type scope MAY be distributed to consumers alongside the companion cons
 
 #### 08-unavailable-core-read-only
 
-A `-core` scope referenced via `follows:` in a companion scope's `index.md` may not be present in the workspace of a consumer of that companion scope. When the referenced `-core` scope is absent or tagged `disabled` in the root index, the companion scope MUST be treated as READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`): content in it MUST NOT be added, changed, or removed. The scope lacks the meta governance that defines how its content MUST be authored, and modifications without those standards would produce non-compliant content. Tools and agents MUST NOT propose or apply changes to a READ-ONLY scope and MUST surface the read-only status to the user when the scope is accessed.
+A `-core` scope referenced via `follows:` in a companion scope's `index.md` may not be present in the workspace of a consumer of that companion scope. When the referenced `-core` scope is absent or tagged `disabled` in the root index, the companion scope MUST be treated as READ-ONLY, unless the companion scope is itself tagged `disabled` (see `_core-adr-policy-022.06-read-only-dependencies`): content in it MUST NOT be added, changed, or removed. The scope lacks the meta governance that defines how its content MUST be authored, and modifications without those standards would produce non-compliant content. Tools and agents MUST NOT propose or apply changes to a READ-ONLY scope and MUST surface the read-only status to the user when the scope is accessed.
 
 #### 09-distribution-advisable
 

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:
 
@@ -141,9 +141,14 @@ An exception MUST be documented in a dedicated `[type]/principles/NNN-direct-sou
 
 This rule governs reasoning and usage, not the document-link graph. Independently of this rule, and regardless of whether a `NNN-direct-source-usage.md` policy exists, no document MAY hyperlink directly into `.assets/sources/`; that restriction is enforced mechanically and addresses a separate, structural concern.
 
+#### 15-scope-sync-date
+
+Compilation tools and agents MUST maintain `sync-date` in the scope `index.md` as defined in [`_core-adr-policy-024.07-compiled-scopes`](024-sync-date-frontmatter.md), setting it only after lint and review pass for the cycle.
+
 ## References
 
 - [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) — numbered rule format required for all policies in compiled scopes
 - [_core-adr-policy-010 - Scope governance](010-scope-governance.md) — scope-type definition convention and local meta-policy mechanism
 - [_core-adr-policy-002 - Policy standards](002-policy-standards.md) — policy document format and frontmatter requirements
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) — scope structure and `scope-type` field definition
+- [_core-adr-policy-024 - Sync date frontmatter](024-sync-date-frontmatter.md) — `sync-date` field set on the scope index after each completed compilation

package/.xdrs/_core/adrs/principles/022-scope-activation.md

@@ -39,12 +39,14 @@ Policies of a scope tagged `extends-only` MUST be applied only through the `exte
 
 #### 05-disabled
 
-All content of a scope tagged `disabled` MUST be ignored by agents: its policies, skills, articles, research, and initiatives are not applied, and nothing is inherited from it through `extends:` or `follows:`. The scope is still validated and MAY be edited; a disabled local scope follows rule 06 like any other local scope. Skills of a disabled scope that are symlinked into `.agents/skills` (see `_core-adr-policy-018`) stay loaded by tools and MUST be removed by the consumer.
+All content of a scope tagged `disabled` MUST be ignored by agents: its policies, skills, articles, research, and initiatives are not applied, and nothing is inherited from it through `extends:` or `follows:`. The scope is still validated and MAY be edited; a disabled scope is exempt from the dependency causes of rule 06. Skills of a disabled scope that are symlinked into `.agents/skills` (see `_core-adr-policy-018`) stay loaded by tools and MUST be removed by the consumer.
 
 #### 06-read-only-dependencies
 
 A scope MUST be treated as READ-ONLY when a scope it follows or extends, or the scope that defines one of its scope types (including parent types), is missing, disabled, or invalid, or when it is an external scope and its own `index.md` is invalid. Content in a READ-ONLY scope MUST NOT be added, changed, or removed.
 
+A scope tagged `disabled` is treated as not present, so it is exempt from every dependency cause above, whether the scope is local or external: it MAY follow or extend disabled, missing, or invalid scopes, or use a scope type defined only in disabled scopes. An enabled scope keeps all causes: it cannot extend or follow a disabled scope because it needs access to that scope. The exemption does not propagate along `extends:` chains.
+
 - **Local scope** (not tracked in `.filedist.lock`, including `_local` and disabled scopes): a read-only local scope is frozen and cannot be maintained, so each cause is invalid and MUST be fixed.
 - **External scope** (tracked in `.filedist.lock`): the scope is READ-ONLY; agents MUST tell the user when they skip a change because of it, naming the cause and fix.
 

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/024-sync-date-frontmatter.md

@@ -0,0 +1,76 @@
+---
+name: _core-adr-policy-024-sync-date-frontmatter
+description: Defines the optional `sync-date` frontmatter field that records when an XDRS element was last verified, checked, reconciled or aligned with other entities, internal or external. Use when a document depends on information that degrades over time, when adding or updating `sync-date`, or when a mechanism needs a refresh hint.
+apply-to: All XDRS elements (Policies, skills, articles, research, initiatives, scope indexes) and every tool, skill or agent that syncs them
+valid-from: 2026-11-04
+---
+
+# _core-adr-policy-024: Sync date frontmatter
+
+## Context and Problem Statement
+
+Some XDRS elements hold content whose quality degrades over time unless it is periodically checked against other entities: other scopes, external sources, APIs, URLs, scripts or people. Version control records when a file changed, but not when its content was last verified, nor that a verification ended with a decision to change nothing.
+
+How should an element declare when it was last checked or reconciled, so that humans, tools and agents can decide when a refresh is worth doing?
+
+## Decision Outcome
+
+**An optional, opt-in `sync-date` frontmatter field holding the date of the last sync**
+
+The field is a refresh hint. It is not a status, not a change date, and carries no enforcement semantics.
+
+### Details
+
+#### 01-sync-date-meaning
+
+`sync-date` MUST contain the ISO date (`YYYY-MM-DD`) on which the element content was last verified, checked, reconciled or aligned with one or more other entities. The other entity MAY be internal (another scope, element or review) or external (an API, URL, repository, script, skill or person). A sync that ended with no change, or with a deliberate decision to change nothing, still counts and MUST update the date.
+
+#### 02-not-a-change-date
+
+`sync-date` MUST NOT be used as a last-modified date or to record content changes, which are already available from version control. It MUST NOT be updated when the content was edited without any verification against another entity.
+
+#### 03-opt-in
+
+`sync-date` is OPTIONAL and MUST NOT be added by default. It MUST be added only when a compiled scope requires it (rule 07), or when the user or a skill explicitly requests it for a specific sync purpose.
+
+#### 04-purpose-check
+
+Before adding `sync-date`, the author or agent MUST identify the concrete sync process that will use it (for example a periodic review, a source re-sync, or a cross-scope reconciliation). When no such process exists, the field MUST NOT be added. An existing `sync-date` that no process uses SHOULD be removed.
+
+#### 05-placement-and-format
+
+The value MUST be an unquoted ISO date. Placement per element:
+
+| Element | Placement |
+|---|---|
+| Policy, scope `index.md` | Top-level frontmatter field `sync-date` |
+| Article, research, initiative | Top-level `sync-date` in an optional frontmatter block placed before the title line; the block MUST contain no other field |
+| Skill (`SKILL.md`) | Nested field `metadata.sync-date`, keeping the top-level frontmatter compatible with the agentskills spec |
+
+Slide presentations MUST NOT carry `sync-date`.
+
+Example:
+
+```yaml
+---
+sync-date: 2026-11-04
+---
+```
+
+#### 06-who-updates
+
+The date MUST be updated by whoever performs the sync (human, tool or agent), only after the sync completed. A failed or partial sync MUST NOT update it.
+
+#### 07-compiled-scopes
+
+In a scope declaring `scope-type: compiled`, `sync-date` MUST be present only in the scope `index.md`, never in individual Policies. Compilation tools and agents MUST set it to the current date at the end of every completed compilation or re-sync cycle, including cycles where no source content changed and no Policy was modified. It MUST NOT be updated when the cycle was skipped because every source was still within its re-sync period. Placing it only in the scope index avoids touching every Policy when nothing changed.
+
+#### 08-consumers
+
+Mechanisms that refresh or check content (compilation, reviews, scheduled syncs, scripts) SHOULD read `sync-date` as a hint to prioritize or skip refreshes, and MUST NOT treat a missing `sync-date` as an error. How old a date must be before a refresh is worthwhile is decided by each mechanism.
+
+## References
+
+- [_core-adr-policy-002 - Policy standards](002-policy-standards.md) - Policy frontmatter fields
+- [_core-adr-policy-003 - Skill standards](003-skill-standards.md) - SKILL.md frontmatter and metadata
+- [_core-adr-policy-019 - Compiled scope type](019-compiled-scope-type.md) - Compilation and re-sync process

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.4.0"
+  updated: 2026-11-04
 ---
 
 ## Overview
@@ -31,6 +31,7 @@ Performs a full compilation cycle for any scope declaring `scope-type: compiled`
 #### Changes
 
 - Policy files created, updated, or removed.
+- Scope `index.md` `sync-date` refreshed.
 
 ### Halt Conditions
 
@@ -76,11 +77,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:
@@ -107,7 +108,7 @@ Keep every question and intermediate message <100 words and the final summary <1
 For each TODO item marked CREATE or UPDATE, in sequence:
 
 1. **Write the policy file** (<2600 words, per `_core-adr-policy-002`) following `_core-adr-policy-019` and `_core-adr-policy-008`:
-   - Use standard policy frontmatter: `name`, `description`, `apply-to` (<40 words), `valid-from`. Generate these from the source text; they are exempt from the no-invented-content rule per policy-019 rule 05.
+   - Use standard policy frontmatter: `name`, `description`, `apply-to` (<40 words), `valid-from`. Generate these from the source text; they are exempt from the no-invented-content rule per policy-019 rule 05. Do NOT add `sync-date` to compiled policies; it lives only in the scope `index.md` (`_core-adr-policy-024.07-compiled-scopes`).
    - Use structured numbered rule blocks for all claims (per `_core-adr-policy-008`).
    - Transcribe source content faithfully. Do NOT invent, infer beyond what the source states, or fill gaps. Preserve ambiguities as-is.
 
@@ -169,6 +170,7 @@ After writing each policy:
 3. If storage is `temporary`: do not copy any bulk staged content into `.assets/sources/[name]/`; only `source.md` lives there.
 4. For every source processed in this run, update `.assets/sources/[name]/source.md`'s `last-compilation-timestamp` to the current time — this step only runs after Phase 6 (Lint) and Phase 7 (Review) both pass for the policies depending on that source.
 5. If a source's `Source storage` setting changed since its last run, reconcile per `_core-adr-policy-019` rule 12: switching to `temporary` removes previously persisted bulk content (keeping `source.md`); switching away from `temporary` begins persisting bulk content from this run onward.
+6. After lint and review pass for the cycle, set `sync-date` in the scope `index.md` frontmatter to today's date (`YYYY-MM-DD`), adding the field when absent, even when no source changed and no policy was modified (`_core-adr-policy-024.07-compiled-scopes`). Skip this step when the run halted or ended at the Phase 1 no-op.
 
 ### Phase 10: Report
 
@@ -178,7 +180,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 +206,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-article/SKILL.md

@@ -4,8 +4,8 @@ description: >
    Creates a new article document following XDRS article standards: selects scope, type, subject, and number; then writes a focused synthetic text that combines and links multiple Policies, Research documents, and Skills around a topic. Activate this skill when the user asks to create, add, or write a new article, guide, or overview document within an XDRS project.
 metadata:
   author: flaviostutz
-  version: "1.1.0"
-  updated: 2026-09-24
+  version: "1.1.1"
+  updated: 2026-11-04
 ---
 
 ## Overview
@@ -103,7 +103,7 @@ If the article spans more than one subject, place it in `principles`.
 
 ### Phase 5: Write the Article
 
-Use the mandatory template from `004-article-standards`:
+Use the mandatory template from `004-article-standards`. Omit the optional `sync-date` frontmatter unless the user explicitly asks for it for a specific sync purpose (`_core-adr-policy-024`):
 
 ```
 # [scope]-[type]-article-[number]: [Short Title]

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

@@ -6,8 +6,8 @@ description: >
   Activate this skill when the user asks to create, add, or write an initiative, plan, project plan, roadmap, or execution plan within an XDRS project.
 metadata:
   author: flaviostutz
-  version: "1.1.0"
-  updated: 2026-09-24
+  version: "1.1.1"
+  updated: 2026-11-04
 ---
 
 ## Overview
@@ -93,7 +93,7 @@ Consult `001-xdrs-standards` while making each choice in this phase. The summari
 
 ### Phase 5: Write the Initiative
 
-Use the mandatory template from `007-initiative-standards`:
+Use the mandatory template from `007-initiative-standards`. Omit the optional `sync-date` frontmatter unless the user explicitly asks for it for a specific sync purpose (`_core-adr-policy-024`):
 
 ```markdown
 # [scope]-[type]-initiative-[number]: [Short Title]

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

@@ -5,8 +5,8 @@ description: >
   Activate this skill when the user asks to create, add, or write a new Policy (ADR, BDR, or EDR).
 metadata:
   author: flaviostutz
-  version: "1.2.0"
-  updated: 2026-09-30
+  version: "1.2.1"
+  updated: 2026-11-04
 ---
 
 ## Overview
@@ -107,7 +107,7 @@ Choose a title that clearly states the question this Policy answers, not the ans
 
 ### Phase 6: Write the First Draft
 
-Use the mandatory template from `002-policy-standards`:
+Use the mandatory template from `002-policy-standards`. Omit the optional `sync-date` field unless the user explicitly asks for it for a specific sync purpose (`_core-adr-policy-024`); never add it to Policies of `compiled` scopes:
 
 **Check if the decision requires a structured set of rules:**
 If the decision defines strong rules or policies that must be stated explicitly, or if other documents, skills, or agents have a clear need to reference individual rules, you MUST apply the structured rule format from `_core-adr-policy-008-policy-structured-standards`. This means:

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

@@ -6,8 +6,8 @@ description: >
   Activate this skill when the user asks to create, add, or write a research document that backs a decision.
 metadata:
   author: flaviostutz
-  version: "1.5.0"
-  updated: 2026-09-24
+  version: "1.5.1"
+  updated: 2026-11-04
 ---
 
 ## Overview
@@ -124,7 +124,7 @@ If the results contain competing interpretations or the intended audience for th
 
 ### Phase 7: Write the Research Document
 
-Use the mandatory template from `006-research-standards`:
+Use the mandatory template from `006-research-standards`. Omit the optional `sync-date` frontmatter unless the user explicitly asks for it for a specific sync purpose (`_core-adr-policy-024`):
 
 ```markdown
 # [scope]-[type]-research-[number]: [Short Title]