xdrs-core 0.53.1 → 0.54.0

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

@@ -50,7 +50,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
   `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md`
   where `[xdrs-root]` is the XDRS root folder (default: `.xdrs/`).
 - MUST ignore symlinks paths. MUST NOT create or update documents inside symlinked folders.
-- **Files listed in `.filedist.lock` are external XDRs.** A file whose path appears in the workspace root `.filedist.lock` file was distributed from an external source repository. It MUST NOT be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist.lock` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist.lock`. The `.filedist.lock` file can also be used to detect which files changed when bumping an external scope to a newer version: compare the version field in `.filedist.lock` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
+- **Files listed in `.filedist.lock` are external XDRs.** A file whose path appears in the workspace root `.filedist.lock` file was distributed from an external source repository. It MUST NOT be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist.lock` lists managed files under `files:` per output directory, one `<path>|<package>|<version>|...` entry each. A scope is considered external when any of its files appear in `.filedist.lock`. The `.filedist.lock` file can also be used to detect which files changed when bumping an external scope to a newer version: compare the version field in `.filedist.lock` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
 - Optional supporting artifacts under the same subject:
   - `[xdrs-root]/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `[xdrs-root]/[scope]/[type]/[subject]/skills/[skill-name]/SKILL.md`

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

@@ -78,7 +78,9 @@ Policy documents are the authoritative source of truth for their scope, type, an
 - Conflict handling applies to Policy documents:
   - For cross-scope and cross-scope-type overrides, document the decision conflict in the Policy `## Conflicts` section of the Policy that overrides another scope or scope-type policy. Local meta-policies (`NNN-core.md` and companion files) and scope-type definition policies MAY include a `## Conflicts` section for this purpose. See `_core-adr-policy-010` rule 26-conflict-declarations for the required structure.
   - **Within-scope conflicts:** Policies within the same type+scope MUST NOT conflict. If two Policies appear to conflict, one SHOULD be updated, removed, or the conflict resolved through a new Policy.
-- When research exists for a decision, the Policy SHOULD mention the related research documents after the `## Considered Options` list.
+- Policies MUST NOT contain a `## Considered Options` section.
+- When a Research document backs the decision, the Policy SHOULD list it in a `## Related Researches` section. Each entry MUST be a single list item with a link to the research, a ` - ` separator, and a summary of fewer than 20 words (see the template below).
+- Options that MUST NOT be used, with or without a backing Research, MUST be stated as ordinary rules in the Policy (for example in `### Details`), like any other rule.
 - MUST NOT use emojis in contents.
 - File names MUST be lowercase.
 - For diagram and asset rules in Policy documents, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). Rule `02-policy-diagram-restrictions` below summarises the overall stance; the detailed rules are in policy 020.
@@ -129,8 +131,8 @@ Question: In the end, state explicitly the question that needs to be answered. E
 
 ## Decision Outcome
 
-**[Chosen Option Title]**
-[Very short description of what is the decision, aligned with the titles on the Considered Options section]
+**[Decision Title]**
+[Very short description of what is the decision]
 
 [Short description of implementation details for the chosen path]
 
@@ -138,11 +140,11 @@ Question: In the end, state explicitly the question that needs to be answered. E
 
 [Optional section with implementation specifics, applicability boundaries, rules, concise examples, or do/don't guidance. This is the answer to the question in the "Context and Problem Statement". (<1300 words)]
 
-## Considered Options 
-[this section is present ONLY if the user explicitely indicated that there were multiple options to choose from while making this decision or have a backing research document]
+## Related Researches
 
-[Related research, if any]
-- [Research document title](researches/001-example.md) - Brief description of what it informed
+[Optional section, present ONLY if a Research document backs this decision]
+
+- [Research document title](researches/001-example.md) - Brief summary of what it informed (<20 words)
 
 ## Conflicts
 

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, and co-location with XDRS packages. Use when creating or reviewing skills.
+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.
 apply-to: All skill packages
 valid-from: 2025-01-01
 ---
@@ -124,7 +124,7 @@ Brief description of the skill goal.
 - Generated files or chat-delivered results, one bullet per item, or "None" (e.g., `Release notes (<300 words)`).
 
 #### Changes
-- External system mutations that are part of the skill's main objective, one bullet per item, or "None".
+- External system mutations or persistent workspace files changed by the main objective, one bullet per item, or "None". Never list work files under `.tmp/`.
 
 ### Halt Conditions
 - Specific triggers that make the skill stop before completing, one bullet per item, or "None".
@@ -168,7 +168,7 @@ Rules:
 - `### Inputs` MUST contain `#### Required` (the bare minimum needed to invoke the skill) then `#### Optional` (helpful extra context), in that order.
 - `## Instructions` is REQUIRED. It SHOULD state one clearly recommended approach first when multiple are viable, noting alternatives briefly afterward, and SHOULD include verification steps or acceptance criteria at the end of the task or major phases.
 - `## Examples` SHOULD include 2-3 example prompts a user could give as input, alongside a short description of what to expect during execution and as output for each.
-- `### Outputs` covers only end-objective results, not intermediary items, and MUST contain `#### Contents` (generated files or chat-delivered results) then `#### Changes` (external system mutations that are part of the main objective), in that order.
+- `### Outputs` covers only end-objective results, not intermediary items, and MUST contain `#### Contents` (generated files or chat-delivered results) then `#### Changes` (external system mutations or persistent workspace files changed by the main objective, never `.tmp/` work files), in that order. Chat-only skills MUST declare "None".
 - `### Halt Conditions` MUST list this skill's specific stop-before-completing triggers, grounded in at least missing required input, dubious/ambiguous input, and insufficient agent confidence — distinct from `## Edge Cases` (activation/boundary conditions) and `## Anti-Patterns` (execution mistakes). A partial or empty result the skill still finishes and returns belongs in `### Outputs`, not `### Halt Conditions`.
 - `### User Interaction` is OPTIONAL: documents human-in-the-loop (HITL) exchanges during execution — a clarifying question or an approval gate — distinct from `### Halt Conditions` (which stop execution rather than pause-and-resume it) and `### Runtime Requirements` (static prerequisites, not an interactive exchange); omit the section entirely when the skill has none.
 - `### Runtime Requirements` is OPTIONAL: free-form bullets for tooling, network, or environment prerequisites beyond the LLM itself; omit the section entirely when none apply.
@@ -190,6 +190,17 @@ 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**
+
+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.
@@ -221,17 +232,6 @@ Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills
 skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[skill-name]
 ```
 
-## Considered Options
-
-* (REJECTED) **Top-level `skills/` directory separate from XDRS** - Decouples skills from the decisions that govern them.
-  * Reason: Breaks the natural association between a decision (Policy) and the skill that implements it; makes navigation harder.
-* (CHOSEN) **agentskills-compatible packages co-located with XDRS** - Standardized format with scoped discovery and clear ownership.
-  * Reason: Reuses proven agentskills tooling, aligns with the existing XDRS scope/subject hierarchy, and keeps skills close to the decisions they implement.
-* (REJECTED) **Fully self-contained skills, no shared assets** - Every skill package repeats any instruction shared with another skill.
-  * Reason: Duplicates maintenance burden across skills and drifts out of sync over time.
-* (CHOSEN) **Shared `.assets/` modules plus optional bundling** - Keep shared instruction modules DRY in-repo, and offer an optional per-skill bundling mechanism for standalone distribution.
-  * Reason: Preserves DRY authoring for the common case while still allowing a single skill to be distributed as a self-contained artifact when needed ([`_core-adr-policy-021`](021-skill-bundling.md)).
-
 ## References
 
 - [agentskills specification](https://agentskills.io/specification)

package/.xdrs/_core/adrs/principles/004-article-standards.md

@@ -21,6 +21,7 @@ Articles are Markdown documents placed inside a subject folder alongside policie
 
 ### Details
 
+- Articles MUST NOT be kept in a documentation repository separate from the Policies they reference.
 **Human-first writing**
 
 - The primary objective of an article is to make information available and accessible to humans. Good copywriting style, storytelling, clear organization, and clustering of related information are essential. Avoid repetitive content; each sentence SHOULD add new value.
@@ -89,13 +90,6 @@ when referencing an information from those documents.]
 - [Policy id or Skill name](relative/path/to/file.md) - Brief description of relevance
 ```
 
-## Considered Options
-
-* (REJECTED) **Separate documentation repository** - Removes drift risk but decouples docs from decisions.
-  * Reason: Increases maintenance burden and makes it easy for articles to go stale relative to the Policies they reference.
-* (CHOSEN) **Subject-level articles folder co-located with Policies** - Keeps articles alongside the policies and skills they reference, with `principles` as the fallback for cross-subject articles.
-  * Reason: Easy to discover, consistent with where skills are placed, and clearly distinct from the policies themselves.
-
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md)

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

@@ -21,6 +21,7 @@ Research documents are Markdown files placed inside a subject folder alongside p
 
 ### Details
 
+- Research MUST NOT be written inline inside a Policy; Policies only link to it.
 - Research is evidence and exploration, not the adopted decision. When a research document and a Policy disagree, the Policy takes precedence.
 - `Research` is the artifact name. `researches/` is only the folder name used alongside `skills/` and `articles/`.
 - Research documents MUST live under `researches/` inside the relevant subject folder:
@@ -121,15 +122,6 @@ Prefer tables and bullet lists for simple comparisons; for diagrams see _core-ad
 - [Another related Policy if this research informed multiple decisions](relative/path.md) - Why it matters
 ```
 
-## Considered Options
-
-- Related research: `001-research-and-decision-lifecycle` (workspace-local research)
-
-* (REJECTED) **Inline long-form analysis inside the Policy** - Put all research and decision text in one file.
-  * Reason: Makes Policies too long, mixes evidence with the adopted rule set, and hurts fast retrieval by humans and AI agents.
-* (CHOSEN) **IMRAD-based subject-level research beside XDRS** - Keep exploratory material beside the decisions, skills, and articles it informs, using an IMRAD-inspired structure adapted to company work.
-  * Reason: Preserves lifecycle context, keeps the Policy concise, gives readers a predictable structure, and raises evidence quality without demanding full academic rigor.
-
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md)

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

@@ -21,6 +21,7 @@ Initiatives are Markdown documents placed inside a subject folder alongside poli
 
 ### Details
 
+- Initiatives MUST NOT be embedded inside Policies.
 - Initiatives describe a problem (why), what we will do to solve the problem, and the approach and activities needed to solve it (how).
 - Initiatives are NOT the source of truth. When an initiative and a Policy disagree, the Policy takes precedence.
 - Initiatives are ephemeral. They MUST be deleted after full implementation. The lasting outputs of an initiative are actual actions or Decisions, Skills, Articles, Research documents, and other artifacts that result from execution.
@@ -125,13 +126,6 @@ Due date: YYYY-MM-DD
 - [Related Policy or artifact](relative/path.md) - Brief description of relevance
 ```
 
-## Considered Options
-
-* (REJECTED) **Inline planning in Policies** — Embed planning details inside policies.
-  * Reason: Initiatives are ephemeral execution documents while Policies are lasting decisions. Mixing them bloats Policies and creates confusion about what to delete after execution.
-* (CHOSEN) **Subject-level initiatives folder co-located with Policies** — Keeps initiatives alongside the decisions they implement, with clear lifecycle expectations.
-  * Reason: Consistent with how skills, articles, and research are organized. The explicit deletion requirement after implementation keeps the document base clean.
-
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Framework elements: types, scopes, subjects, folder structure

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 ephemeral compilation working directory and removed at the end of the compilation run.
+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/`.
 
 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/articles/001-xdrs-overview.md

@@ -85,7 +85,7 @@ The framework is easiest to understand as a lifecycle rather than a static folde
   later support more than one decision record.
 2. **Decide** — Once a direction is chosen, a Policy captures the final answer in concise,
   authoritative form. The Policy should make clear when the decision applies, and may link back to
-  the Research that informed its considered options.
+  the Research that informed it.
 3. **Execute** — If the decision affects daily work, a Skill explains how to apply it in practice.
    The Skill operationalizes the decision without turning the Policy into a procedure manual.
 4. **Explain** — When the topic becomes broad or cross-cutting, an Article synthesizes the Policy,

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

@@ -4,13 +4,13 @@ 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.1.0"
-  updated: 2026-09-24
+  version: "1.2.0"
+  updated: 2026-09-30
 ---
 
 ## Overview
 
-Performs a full compilation cycle for any scope declaring `scope-type: compiled`: discovers compilation meta-policies across all type folders, checks whether each governed source is already in sync before doing any work, fetches due sources into a temporary staging directory, plans which policies to create, update, or remove, migrates them one at a time with full source traceability, runs lint and review, persists selected source content and updates sync tracking, and documents any inconsistencies found in the source. Works for both initial compilation and re-compilation (updates). By default, fetched source content used to compile policies is persisted under `.assets/sources/[name]/` in the scope (see `_core-adr-policy-019` rules 12–13); this content is never authoritative for decisions (rule 14). Requires `_core-adr-policy-019-compiled-scope-type` to be present in the workspace.
+Performs a full compilation cycle for any scope declaring `scope-type: compiled`: discovers compilation meta-policies across all type folders, checks whether each governed source is already in sync before doing any work, fetches due sources into a staging directory under `.tmp/`, plans which policies to create, update, or remove, migrates them one at a time with full source traceability, runs lint and review, persists selected source content and updates sync tracking, and documents any inconsistencies found in the source. Works for both initial compilation and re-compilation (updates). By default, fetched source content used to compile policies is persisted under `.assets/sources/[name]/` in the scope (see `_core-adr-policy-019` rules 12–13); this content is never authoritative for decisions (rule 14). Requires `_core-adr-policy-019-compiled-scope-type` to be present in the workspace.
 
 ### Inputs
 
@@ -76,11 +76,11 @@ Keep every question and intermediate message <100 words and the final summary <1
 
 ### Phase 2: Fetch Sources
 
-1. Create a temporary directory `.tmp/compilation-[YYYYMMDDHHMMSS]/staging/` in the workspace root.
+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.
 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/compilation-[ts]/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/compilation-[ts]/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/compilation-[ts]/staging/[name]/`.
+   - **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]/`.
 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:
@@ -170,15 +170,15 @@ After writing each policy:
 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.
 
-### Phase 10: Cleanup
+### Phase 10: Report
 
-1. Remove the temporary staging directory `.tmp/compilation-[ts]/` created in Phase 2. Never remove or modify persisted content under `.assets/sources/` — that is governed solely by Phase 9.
-2. Report a compilation summary:
+1. Report a compilation summary:
    - Policies created, updated, removed.
    - Inconsistencies documented (with file path).
    - 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
 
@@ -190,10 +190,6 @@ After writing each policy:
   **Why it happens:** Momentum from prior compilations makes the plan feel obviously correct.
   **Instead:** Always present the TODO list and wait for explicit confirmation before Phase 4.
 
-- **Mistake:** Leaving the temporary `.tmp/compilation-[ts]/` directory behind after a run.
-  **Why it happens:** Phase 10 cleanup is easy to forget once the summary is reported.
-  **Instead:** Always remove the temporary directory as the first Phase 10 step, even on partial failures.
-
 - **Mistake:** Persisting every fetched file under `.assets/sources/[name]/`, including content excluded by selectors or no longer used by any compiled policy.
   **Why it happens:** It feels safer to keep everything "just in case" rather than compute what is actually still used.
   **Instead:** Persist only Selector-matched content actually referenced by a compiled policy's `## Source` section, per `_core-adr-policy-019` rule 13; remove the rest during Phase 9.

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.1.0"
-  updated: 2026-09-24
+  version: "1.2.0"
+  updated: 2026-09-30
 ---
 
 ## 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 temporary `.mmd` file and run:
+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:
    ```bash
-   npx -y @mermaid-js/mermaid-cli -i <tempfile>.mmd --quiet 2>&1
+   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. Delete all temporary files created in this step.
+4. Keep the extracted files after the run; if this step created the dir, fill the `results-path` line of the report template.
 
 ### Phase 4: Policy Review
 
@@ -134,6 +134,8 @@ 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

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.1.0"
-  updated: 2026-09-24
+  version: "1.2.0"
+  updated: 2026-09-30
 ---
 
 ## Overview
@@ -156,7 +156,7 @@ valid-from: [Required. ISO date YYYY-MM-DD. Defaults to today's date when not sp
 ### Details
 [Rules, applicability boundaries, concise examples, and optional do/don't guidance — <1300 words]
 
-## Considered Options (only if the user explicitly indicated multiple options)
+## Related Researches (only if a backing Research exists; one list item per Research: link + summary <20 words)
 
 ## Conflicts (mandatory if conflicts found in Phase 3)
 
@@ -172,7 +172,7 @@ Mandatory rules to apply while drafting:
 - Do not duplicate content already in referenced Policies — link instead.
 - Keep the decision itself authoritative in the Policy. Supporting artifacts may elaborate, but they should not restate the full decision when a short reference is enough.
 - Make clear when the decision applies and any important exception boundaries.
-- Keep exploratory option analysis in a related Research document when it would distract from the final decision text.
+- Keep exploratory option analysis in a related Research document; never add a `## Considered Options` section. State options that must not be used as ordinary rules in the Policy.
 - 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.
 - If the Policy genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
@@ -199,7 +199,7 @@ If any check fails, revise and re-run this phase before proceeding.
 1. Create the Policy file at `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md` (default root: `.xdrs/`).
 2. Add an entry to `[xdrs-root]/[scope]/[type]/index.md` (create the file if it does not exist); keep its description <15 words.
 3. Add or verify the scope entry in the Policy root `index.md` (exactly one link per scope; when the scope index declares `extends-only: true`, append the tag `` `extends-only` `` right after the link and make sure the legend line is present, see `_core-adr-policy-022`).
-4. If significant research was produced or already exists, link it from the Policy `## Considered Options` section.
+4. If significant research was produced or already exists, link it from the Policy `## Related Researches` section with a summary under 20 words.
 5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Details` without turning the Policy into a long procedure.
 6. Evaluate whether the scope index at `[xdrs-root]/[scope]/index.md` should be updated to reflect the new content. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
 

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

@@ -6,8 +6,8 @@ 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.1.0"
-  updated: 2026-09-24
+  version: "1.2.0"
+  updated: 2026-09-30
 ---
 
 ## Overview
@@ -172,6 +172,7 @@ Rules:
 - 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`.
 - 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.
 - 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.
@@ -192,6 +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?
 
 If any check fails, revise before continuing.
 

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.1.0"
-  updated: 2026-09-24
+  version: "1.2.0"
+  updated: 2026-09-30
 ---
 
 ## 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 temporary `.mmd` file and run:
+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:
    ```bash
-   npx -y @mermaid-js/mermaid-cli -i <tempfile>.mmd --quiet 2>&1
+   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. Delete all temporary files created in this step.
+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.
 
 ### Constraints
 

package/README.md

@@ -320,7 +320,7 @@ flowchart LR
 The published package exposes the `xdrs-core` CLI.
 
 - `npx -y xdrs-core` (or `install`) installs or updates the managed XDRS files; `npx -y xdrs-core check` fails if managed files drifted from the package. Both are delegated to [filedist](https://github.com/flaviostutz/filedist) (run `--help` for all options).
-- `npx -y xdrs-core lint [path]` validates the XDRS tree. Scopes listed in the workspace `.filedist.lock` are treated as external and skipped; use `--all` to include them.
+- `npx -y xdrs-core lint [path]` validates the XDRS tree. Scopes whose files are listed in the `.filedist.lock` written by filedist are treated as external and skipped; use `--all` to include them.
 
 The `lint` command reads `.xdrs/**` (or `[path]` directly when it contains an `index.md`) and reports errors citing the violated Policy rule. It checks:
 

package/lib/lint.js

@@ -40,6 +40,7 @@ const SLIDE_FILE_RE = /^.+-slides(?:-[a-z0-9-]+)?\.md$/;
 const SLIDE_MAX_NAME_LENGTH = 64;
 const EMOJI_RE = /\p{Extended_Pictographic}/u;
 const POLICY_MAX_WORDS = 2600;
+const POLICY_RESEARCH_SUMMARY_MAX_WORDS = 20;
 const ARTICLE_MAX_WORDS = 8000;
 const RESEARCH_MAX_WORDS = 5000;
 const SKILL_MAX_WORDS = 7000;
@@ -1135,6 +1136,7 @@ function lintXdrsElementFile(xdrsRoot, scopeName, typeName, subjectName, filePat
     lintCompiledPolicySourceSection(content, filePath, errors);
   }
   lintRequiredSections(content, filePath, XDRS_REQUIRED_SECTIONS, 'Policy', errors);
+  lintPolicyResearchSections(content, filePath, errors);
   lintNoEmojis(content, filePath, 'Policy', errors);
   lintWordCount(content, filePath, 'Policy', POLICY_MAX_WORDS, errors);
   lintDocumentLinks(filePath, xdrsRoot, scopeName, errors, externalScopes);
@@ -1907,6 +1909,45 @@ function lintNoEmojis(content, filePath, docType, errors) {
   }
 }
 
+/**
+ * Validates Policy research sections per _core-adr-policy-002: "## Considered Options" is forbidden and
+ * "## Related Researches" entries must be a link plus a summary of fewer than POLICY_RESEARCH_SUMMARY_MAX_WORDS words.
+ */
+function lintPolicyResearchSections(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const headingLines = findHeadingLines(lines, ignoredLines);
+
+  for (const index of headingLines) {
+    if (/^##\s+considered\s+options\s*$/i.test(lines[index].trim())) {
+      errors.push(`Policy must not contain a "## Considered Options" section; state options that must not be used as rules and list backing research under "## Related Researches": ${toDisplayPath(filePath)}:${index + 1} [_core-adr-policy-002]`);
+    }
+  }
+
+  const sectionIndex = headingLines.find((index) => /^##\s+related\s+researches\s*$/i.test(lines[index].trim()));
+  if (sectionIndex === undefined) {
+    return;
+  }
+  const nextHeading = headingLines.find((index) => index > sectionIndex);
+  const sectionEnd = nextHeading === undefined ? lines.length : nextHeading;
+
+  let entries = 0;
+  for (let i = sectionIndex + 1; i < sectionEnd; i += 1) {
+    const line = lines[i].trim();
+    if (!line || ignoredLines[i]) continue;
+    entries += 1;
+    const match = line.match(/^[-*]\s+\[[^\]]+\]\([^)\s]+\)\s+[-\u2013\u2014]\s+(.+)$/);
+    if (!match) {
+      errors.push(`Policy "## Related Researches" entries must be list items formatted as "- [Research title](link.md) - Summary": ${toDisplayPath(filePath)}:${i + 1} [_core-adr-policy-002]`);
+    } else if (countWords(match[1]) >= POLICY_RESEARCH_SUMMARY_MAX_WORDS) {
+      errors.push(`Policy "## Related Researches" summary must have fewer than ${POLICY_RESEARCH_SUMMARY_MAX_WORDS} words: ${toDisplayPath(filePath)}:${i + 1} [_core-adr-policy-002]`);
+    }
+  }
+  if (entries === 0) {
+    errors.push(`Policy "## Related Researches" section must not be empty; remove it when no Research backs the decision: ${toDisplayPath(filePath)}:${sectionIndex + 1} [_core-adr-policy-002]`);
+  }
+}
+
 function lintWordCount(content, filePath, docType, maxWords, errors) {
   const body = stripFrontmatter(content);
   const wordCount = countWords(body);
@@ -2622,21 +2663,64 @@ function existsFile(filePath) {
   }
 }
 
+// Finds the nearest .filedist.lock starting at startDir and walking up, since filedist may be run from a parent of the XDRS root.
+function findFiledistLock(startDir) {
+  let dir = startDir;
+  for (;;) {
+    const candidate = path.join(dir, '.filedist.lock');
+    if (existsFile(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function unquoteYamlScalar(value) {
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+// Returns absolute paths of all files tracked in the nearest .filedist.lock. Supports the YAML lockfile written by filedist
+// (files: { <outputDir>: ["<path>|<package>|<version>|..."] }, paths relative to <outputDir>) and the legacy format
+// with one "<path>|<package>|<version>" entry per line (paths relative to the lockfile directory).
 function loadFiledist(repoRoot) {
-  const filedistPath = path.join(repoRoot, '.filedist.lock');
-  if (!existsFile(filedistPath)) {
+  const filedistPath = findFiledistLock(repoRoot);
+  if (!filedistPath) {
     return new Set();
   }
+  const lockDir = path.dirname(filedistPath);
   const content = fs.readFileSync(filedistPath, 'utf8');
   const paths = new Set();
+  let inFiles = false;
+  let outputDir = '.';
   for (const line of content.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed) {
+    if (!line.trim()) {
+      continue;
+    }
+    if (/^files:\s*$/.test(line)) {
+      inFiles = true;
       continue;
     }
-    const parts = trimmed.split('|');
+    if (/^\S/.test(line)) {
+      inFiles = false;
+    }
+    if (inFiles) {
+      const dirMatch = line.match(/^ {2}(\S.*?):\s*$/);
+      if (dirMatch) {
+        outputDir = unquoteYamlScalar(dirMatch[1]);
+        continue;
+      }
+    }
+    const entry = unquoteYamlScalar(line.trim().replace(/^-\s+/, ''));
+    const parts = entry.split('|');
     if (parts.length >= 2) {
-      paths.add(normalizePath(path.join(repoRoot, parts[0])));
+      const baseDir = inFiles ? path.join(lockDir, outputDir) : lockDir;
+      paths.add(normalizePath(path.join(baseDir, parts[0])));
     }
   }
   return paths;

package/lib/lint.test.js

@@ -2276,6 +2276,57 @@ test('does not report a missing extends target of an external scope [022.06]', (
   expect(result.errors.join('\n')).not.toContain('ghost-lib');
 });
 
+const yamlFiledistLock = (outputDir, entries) => [
+  'version: 1',
+  'packages:',
+  '  some-package: 1.0.0',
+  'files:',
+  `  ${outputDir}:`,
+  ...entries.map((e) => `    - ${e}|some-package|1.0.0|file|abc123|0`),
+  'checksum: abc',
+  '',
+].join('\n');
+
+const missingFollowsFiles = (prefix) => ({
+  [`${prefix}.xdrs/index.md`]: rootIndex(['[myteam](myteam/index.md)']),
+  [`${prefix}.xdrs/myteam/index.md`]: '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nfollows: nonexistent-core\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+  [`${prefix}.xdrs/myteam/adrs/index.md`]: teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
+  [`${prefix}.xdrs/myteam/adrs/principles/001-team.md`]: teamXdrDocument('Team decision.'),
+});
+
+test('detects external scope from YAML .filedist.lock written by filedist [022.06]', () => {
+  const workspaceRoot = createWorkspace('follows-missing-scope-yaml-lock', {
+    ...missingFollowsFiles(''),
+    '.filedist.lock': yamlFiledistLock('.', ['.xdrs/myteam/index.md', '.xdrs/myteam/adrs/index.md']),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('nonexistent-core');
+});
+
+test('detects external scope from YAML .filedist.lock with a custom output dir and quoted entries [022.06]', () => {
+  const workspaceRoot = createWorkspace('follows-missing-scope-yaml-lock-outdir', {
+    ...missingFollowsFiles('output/'),
+    '.filedist.lock': yamlFiledistLock('output', ['.xdrs/myteam/index.md']).replace(/    - (.*)\n/, "    - '$1'\n"),
+  });
+
+  const result = lintWorkspace(path.join(workspaceRoot, 'output'));
+
+  expect(result.errors.join('\n')).not.toContain('nonexistent-core');
+});
+
+test('still reports missing follows target of a scope absent from the YAML .filedist.lock', () => {
+  const workspaceRoot = createWorkspace('follows-missing-scope-yaml-lock-local', {
+    ...missingFollowsFiles(''),
+    '.filedist.lock': yamlFiledistLock('.', ['.xdrs/other/index.md']),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('follows references scope "nonexistent-core" which does not exist in the workspace');
+});
+
 test('accepts follows scope that exists in workspace', () => {
   const workspaceRoot = createWorkspace('follows-existing-scope', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[myarea-core](myarea-core/index.md)']),
@@ -4442,6 +4493,69 @@ test('does not report emoji inside a code block in XDRS element documents', () =
   expect(result.errors.join('\n')).not.toContain('must not contain emojis');
 });
 
+// ─── Policy research section checks ───────────────────────────────────────────
+
+function lintPolicyBody(name, body) {
+  const workspaceRoot = createWorkspace(name, {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument(body),
+  });
+  return lintWorkspace(workspaceRoot).errors.join('\n');
+}
+
+test('reports a Considered Options section in a Policy', () => {
+  const errors = lintPolicyBody('policy-considered-options', 'Context.\n\n## Considered Options\n\n* (CHOSEN) **A** - reason');
+
+  expect(errors).toContain('Policy must not contain a "## Considered Options" section');
+});
+
+test('does not report Considered Options inside a code block in a Policy', () => {
+  const errors = lintPolicyBody('policy-considered-options-code', '```markdown\n## Considered Options\n```');
+
+  expect(errors).not.toContain('Considered Options');
+});
+
+test('accepts a valid Related Researches section in a Policy', () => {
+  const errors = lintPolicyBody('policy-related-researches-valid', 'Context.\n\n## Related Researches\n\n- [Options study](https://example.com/study) - Compares three storage engines by cost and latency');
+
+  expect(errors).not.toContain('Related Researches');
+});
+
+test('reports a Related Researches entry without a summary', () => {
+  const errors = lintPolicyBody('policy-related-researches-no-summary', 'Context.\n\n## Related Researches\n\n- [Options study](https://example.com/study)');
+
+  expect(errors).toContain('entries must be list items formatted as');
+});
+
+test('reports a Related Researches entry that is not a list item', () => {
+  const errors = lintPolicyBody('policy-related-researches-prose', 'Context.\n\n## Related Researches\n\nSee the options study.');
+
+  expect(errors).toContain('entries must be list items formatted as');
+});
+
+test('reports a Related Researches summary with 20 or more words', () => {
+  const summary = Array.from({ length: 20 }, (_, i) => `w${i}`).join(' ');
+  const errors = lintPolicyBody('policy-related-researches-long', `Context.\n\n## Related Researches\n\n- [Options study](https://example.com/study) - ${summary}`);
+
+  expect(errors).toContain('summary must have fewer than 20 words');
+});
+
+test('accepts a Related Researches summary with 19 words', () => {
+  const summary = Array.from({ length: 19 }, (_, i) => `w${i}`).join(' ');
+  const errors = lintPolicyBody('policy-related-researches-19', `Context.\n\n## Related Researches\n\n- [Options study](https://example.com/study) - ${summary}`);
+
+  expect(errors).not.toContain('Related Researches');
+});
+
+test('reports an empty Related Researches section in a Policy', () => {
+  const errors = lintPolicyBody('policy-related-researches-empty', 'Context.\n\n## Related Researches\n');
+
+  expect(errors).toContain('"## Related Researches" section must not be empty');
+});
+
 test('reports emoji in SKILL.md', () => {
   const workspaceRoot = createWorkspace('skill-emoji', {
     '.xdrs/index.md': rootIndex(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.53.1",
+  "version": "0.54.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",