xdrs-core 0.50.0 → 0.51.0

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

@@ -62,12 +62,13 @@ When multiple source entries point to the same content (e.g., a web page and its
 
 #### 07-compilation-meta-policy
 
-Before any compilation begins, at least one local meta-policy file named `NNN-core.md` MUST exist in a `[type]/principles/` directory of the target scope (e.g., `adrs/principles/001-core.md`). Compilation tools and agents MUST scan all type folders (`adrs`, `bdrs`, `edrs`) for such meta-policy files; each meta-policy governs compilation for its own type folder.
+Before any compilation begins, at least one local meta-policy file named `NNN-core.md` MUST exist in a `[type]/principles/` directory of the target scope (e.g., `adrs/principles/001-core.md`). Compilation tools and agents MUST scan all type folders (`adrs`, `bdrs`, `edrs`) for such meta-policy files; each meta-policy governs compilation for its own type folder, including every subject compiled under it.
 
 The meta-policy MUST contain the following sections:
 
-- `## Sources` — one bullet per source using the format `- [web] https://...`, `- [git] git@...`, or `- [local] ./path`. Each source entry MAY include an inline description after the URL.
+- `## Sources` — one bullet per source using the format `- [web] name: https://...`, `- [git] name: git@...`, or `- [local] name: ./path`. `name` MUST be a lowercase kebab-case slug (`[a-z0-9-]+`) that meaningfully identifies the source's organisation, project, or content (e.g., `github-official-docs`, `spreadsheet-team-123`). It is used as the folder name under `.assets/sources/` (rule 12) and as the path prefix in `## Source` sections (rule 10). Multiple bullets MAY share the same `name` to list alternate access methods for the same logical source — the preference order in rule 06 picks which one is actually fetched. Each source entry MAY include an inline description after the URL.
 - `## Selectors` — describes which portions of the fetched source to include or exclude, expressed as document sections, filename patterns, topics, or other criteria.
+- `## Sync Settings` — governs re-synchronisation behaviour (rule 13). MUST contain a `Source re-sync period days: N` bullet, where `N` is a positive integer number of days. MAY contain a `Source storage: temporary` bullet; when absent, source storage defaults to persistent (rule 12).
 
 The meta-policy MAY also contain:
 
@@ -85,15 +86,15 @@ There is no fixed position for `compiled`-type scopes in the root `index.md`. Wh
 
 #### 10-source-section
 
-Every compiled policy MUST include a `## Source` section placed after the `## References` section (or after `## Decision Outcome` when no `## References` section is present). The section MUST list the relative file path(s) of the source document(s) used to produce the policy as plain text. Paths MUST NOT be written as markdown links, because the source files exist only inside a temporary local directory that is created during the compilation or review process.
+Every compiled policy MUST include a `## Source` section placed after the `## References` section (or after `## Decision Outcome` when no `## References` section is present). The section MUST list the relative file path(s) of the source document(s) used to produce the policy as plain text, relative to the scope's `.assets/sources/` directory. Paths MUST NOT be written as markdown links: when source storage is temporary, the paths only exist for the duration of the compilation or review process; when source storage is persistent, `.assets/sources/` is exempt from orphan-asset tracking and, per rule 14, MUST NOT be linked to directly — these paths identify compilation inputs, not navigable or citable XDRS resources.
 
 Example:
 
 ```
 ## Source
 
-- source-1/standards/owasp-top-10-2021/A01-broken-access-control.md
-- source-2/docs/security-controls.html
+- owasp-top10/standards/owasp-top-10-2021/A01-broken-access-control.md
+- security-controls-docs/docs/security-controls.html
 ```
 
 #### 11-compilation-notes
@@ -109,6 +110,37 @@ All access control implementations MUST enforce the principle of least privilege
 **compilation-note:** derived from OWASP A01:2021 "How to Prevent", bullet 3 — "Deny by default".
 ```
 
+#### 12-source-storage-and-tracking
+
+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.
+
+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:
+
+```
+# Source
+
+last-fetch-timestamp: YYYY-MM-DD HH:MM:SS
+last-compilation-timestamp: YYYY-MM-DD HH:MM:SS
+```
+
+`last-fetch-timestamp` MUST be updated whenever that source is freshly fetched. `last-compilation-timestamp` MUST be updated only after a compilation cycle consuming that source completes lint and review successfully. If a meta-policy's `Source storage` setting changes between compilation runs, the next compilation MUST reconcile storage accordingly: switching to `temporary` MUST remove any previously persisted bulk content under `.assets/sources/[name]/` while keeping `source.md`; switching away from `temporary` MUST resume persisting bulk content going forward.
+
+#### 13-selective-persistence-and-resync-optimization
+
+Only content matched by `## Selectors` and actually used by at least one compiled policy's `## Source` section MAY be written to `.assets/sources/[name]/`. Content excluded by selectors, or that becomes unused after a re-sync, MUST be removed from persisted storage — `.assets/sources/[name]/` MUST NOT accumulate content beyond what compiled policies currently depend on.
+
+Before fetching, compilation tools and agents MUST evaluate whether a re-sync is necessary: compare the elapsed days since `last-fetch-timestamp` against `Source re-sync period days`, and confirm `last-compilation-timestamp` is not older than `last-fetch-timestamp`. If every source governed by a meta-policy is within its re-sync period and already fully compiled, no fetch or recompilation is required unless explicitly requested. When a re-sync does proceed, newly fetched and selected content MUST be compared against the previous `.assets/sources/[name]/` snapshot (for example, by content hash) to scope which existing compiled policies need re-verification and which can be kept unchanged.
+
+#### 14-source-documents-not-authoritative
+
+By default, content persisted under `.assets/sources/` MUST NOT be treated as a source of truth, cited, or used directly to make architectural, business, or engineering decisions. Only compiled policies — the numbered Policy documents produced from this content — are authoritative for decision-making. Content under `.assets/sources/` exists to support synchronisation, diffing, and recompilation (rules 12 and 13); it is unstructured relative to compiled policies and MAY be misleading, inconsistent, or outdated.
+
+An exception MUST be documented in a dedicated `[type]/principles/NNN-direct-source-usage.md` policy, mirroring the dedicated-file convention of rule 08. That policy MUST explicitly state when and how direct use of source documents is permitted. Absent such a policy, direct use of source documents for decisions is forbidden.
+
+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.
+
 ## References
 
 - [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) — numbered rule format required for all policies in compiled scopes

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

@@ -10,7 +10,7 @@ metadata:
 
 ## Overview
 
-Performs a full compilation cycle for any scope declaring `scope-type: compiled`: discovers compilation meta-policies across all type folders, fetches sources into a temporary directory, plans which policies to create, update, or remove, migrates them one at a time with full source traceability, runs lint and review, and documents any inconsistencies found in the source. Works for both initial compilation and re-compilation (updates). 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 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.
 
 ### Inputs
 
@@ -20,13 +20,13 @@ Performs a full compilation cycle for any scope declaring `scope-type: compiled`
 
 #### Optional
 
-- None.
+- Force-refetch flag to bypass the re-sync short-circuit.
 
 ### Outputs
 
 #### Contents
 
-- Updated compiled scope, linted and reviewed.
+- Updated compiled scope, or a no-op already-in-sync report.
 
 #### Changes
 
@@ -56,39 +56,51 @@ Performs a full compilation cycle for any scope declaring `scope-type: compiled`
 2. Scan ALL type folders (`adrs/`, `bdrs/`, `edrs/`) inside the target scope for local meta-policy files whose filename matches `NNN-core.md` in `[type]/principles/`. Collect every match.
 3. If no meta-policy is found in any type folder, output: `FAIL — Compilation cannot proceed: no local meta-policy NNN-core.md found in any [type]/principles/ folder of [scope-name]. Create it first with ## Sources and ## Selectors sections per _core-adr-policy-019 rule 07.`
 4. Read every found meta-policy fully. For each, extract:
-   - **Sources**: parse all `- [web] ...`, `- [git] ...`, `- [local] ...` bullet entries from the `## Sources` section.
-   - **Selectors**: read the `## Selectors` section content (used in Phase 2).
-   - **Fetch Procedures**: read the `## Fetch Procedures` section if present (used in Phase 1).
-   - **Compilation Notes**: read if present (used in Phase 2–3).
-   - **Review Notes**: read if present (used in Phase 6).
-
-### Phase 1: Fetch Sources
-
-1. Create a temporary directory `.tmp/compilation-[YYYYMMDDHHMMSS]/` in the workspace root.
-2. For each source discovered in Phase 0, 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]/source-N/`. 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]/source-N/`.
-   - **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]/source-N/`.
+   - **Sources**: parse all `- [web] ...`, `- [git] ...`, `- [local] ...` bullet entries from the `## Sources` section, including each source's `name` slug (per `_core-adr-policy-019` rule 07).
+   - **Selectors**: read the `## Selectors` section content (used in Phase 3).
+   - **Sync Settings**: parse `Source re-sync period days` and, if present, `Source storage: temporary` from the `## Sync Settings` section (used in Phase 1 and Phase 9).
+   - **Fetch Procedures**: read the `## Fetch Procedures` section if present (used in Phase 2).
+   - **Compilation Notes**: read if present (used in Phase 3–4).
+   - **Review Notes**: read if present (used in Phase 7).
+
+### Phase 1: Check Sync Necessity
+
+1. For each source `name` extracted in Phase 0, look for `.assets/sources/[name]/source.md` in the governed type folder.
+2. If `source.md` does not exist for a source, that source has never been synced — it is due for Phase 2.
+3. If `source.md` exists, read its `last-fetch-timestamp` and `last-compilation-timestamp`. Compute the elapsed days since `last-fetch-timestamp`. That source is due for Phase 2 if either is true: the elapsed days exceed the meta-policy's `Source re-sync period days`, or `last-compilation-timestamp` is older than `last-fetch-timestamp` (a previous run fetched but never finished compiling).
+4. If the input includes an explicit force-refetch/recompile request (see Inputs > Optional), treat every source as due regardless of timestamps.
+5. If no source across any governed meta-policy is due, output: `OK — [scope-name] is already in sync. No action taken.` and halt — do not proceed to later phases.
+6. Otherwise, proceed to Phase 2, but scope fetching and compilation to only the meta-policies and sources that are due; meta-policies with no due sources MAY be skipped entirely.
+
+### Phase 2: Fetch Sources
+
+1. Create a temporary directory `.tmp/compilation-[YYYYMMDDHHMMSS]/staging/` in the workspace root.
+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]/`.
 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. Convert non-markdown documents found in the fetched source directories. Use only the format converters actually needed:
+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:
    - PDF files: `uvx markitdown[pdf] <file> -o <output>.md`
    - XLSX files: `uvx markitdown[xlsx] <file> -o <output>.md`
    - DOCX files: `uvx markitdown[docx] <file> -o <output>.md`
    - PPTX files: `uvx markitdown[pptx] <file> -o <output>.md`
    - HTML files saved from web scraping: `uvx markitdown <file.html> -o <output>.md`
 
-### Phase 2: Plan Policies
+### Phase 3: Plan Policies
 
-1. For each type folder governed by a meta-policy (from Phase 0), apply the `## Selectors` rules to the fetched content to determine which portions to include.
+1. For each type folder governed by a meta-policy (from Phase 0), apply the `## Selectors` rules to the fetched staging content to determine which portions to include.
 2. List all existing policies in the scope under each governed type folder.
-3. Analyse the selected content and produce a TODO list showing for each expected policy:
+3. If `.assets/sources/[name]/` already holds a previous persisted snapshot, diff the newly selected staging content against it (for example, by content hash per file) to pre-seed which policies are likely unaffected.
+4. Analyse the selected content and produce a TODO list showing for each expected policy:
    - **CREATE** — new policy to be compiled from source (does not yet exist in scope)
    - **UPDATE** — existing policy whose source content has changed
    - **REMOVE** — existing policy whose source content no longer exists or is excluded by selectors
-   - **KEEP** — existing policy that is up to date; no action needed
-4. Present the TODO list to the user and wait for confirmation before proceeding to Phase 3.
+   - **KEEP** — existing policy that is up to date; no action needed (default for policies whose source content is unchanged per the step 3 diff)
+5. Present the TODO list to the user and wait for confirmation before proceeding to Phase 4.
 
-### Phase 3: Migrate Policies (one at a time)
+### Phase 4: Migrate Policies (one at a time)
 
 For each TODO item marked CREATE or UPDATE, in sequence:
 
@@ -99,21 +111,21 @@ For each TODO item marked CREATE or UPDATE, in sequence:
 
 2. **Add a `**compilation-note:**` marker** inside a rule body only when the mapping from source to rule is not obvious — for example: indirect references, conclusions drawn by connecting multiple source sections, interpretations that required judgment, or cases where the same source passage could be read differently. Do NOT add a marker when the rule is a direct, literal transcription of a single source statement. Place the marker as a new sentence at the end of the rule body. Example:
    ```
-   All API keys MUST be rotated every 90 days. **compilation-note:** derived from [source-1/security/api-guidelines.md section 4.2] — "Keys should be invalidated and replaced quarterly"; frequency inferred as 90 days from the term "quarterly".
+   All API keys MUST be rotated every 90 days. **compilation-note:** derived from [api-guidelines/security/api-guidelines.md section 4.2] — "Keys should be invalidated and replaced quarterly"; frequency inferred as 90 days from the term "quarterly".
    ```
 
-3. **Add a `## Source` section** as the LAST section of the policy (after `## References` if present, otherwise after `## Decision Outcome`). List the relative file path(s) of the source document(s) as plain text — NOT as markdown links. Paths are relative to the temporary source directory (e.g., `source-1/docs/chapter-3.md`).
+3. **Add a `## Source` section** as the LAST section of the policy (after `## References` if present, otherwise after `## Decision Outcome`). List the relative file path(s) of the source document(s) as plain text — NOT as markdown links. Paths are relative to `.assets/sources/` and use the source's `name` slug as their first segment (e.g., `api-guidelines/standards/section-4/api-security.md`), regardless of whether storage is currently persistent or temporary.
    ```
    ## Source
 
-   - source-1/standards/section-4/api-security.md
+   - api-guidelines/standards/section-4/api-security.md
    ```
 
 4. For REMOVE items: delete the policy file and remove its entry from the type's `index.md`.
 
-5. Note any content in the source that is inconsistent, contradictory, or cannot be faithfully expressed as a valid XDRS policy. Record these for Phase 7.
+5. Note any content in the source that is inconsistent, contradictory, or cannot be faithfully expressed as a valid XDRS policy. Record these for Phase 8.
 
-### Phase 4: Verify Each Policy
+### Phase 5: Verify Each Policy
 
 After writing each policy:
 
@@ -121,25 +133,25 @@ After writing each policy:
 2. Confirm the policy uses structured numbered rule blocks (`_core-adr-policy-008`).
 3. Confirm `**compilation-note:**` markers are present for every rule whose mapping from source is non-obvious (indirect references, multi-source conclusions, interpretations requiring judgment). Direct literal transcriptions do not require a marker.
 4. Confirm no normative statements are present that cannot be traced to the listed source file.
-5. Add any new inconsistencies found to the list for Phase 7.
+5. Add any new inconsistencies found to the list for Phase 8.
 
-### Phase 5: Lint
+### Phase 6: Lint
 
 1. Run `npx xdrs-core lint` from the workspace root (or `make lint` if a `Makefile` is present with a `lint` target).
 2. Review all reported errors and warnings.
 3. Fix only mechanical and structural errors (missing required frontmatter fields, naming violations, index link mismatches). Do NOT invent content to satisfy content-level findings.
 4. Re-run lint after fixes until it passes or only unfixable findings remain.
 
-### Phase 6: Review
+### Phase 7: Review
 
 1. Read and follow `.xdrs/_core/adrs/principles/skills/review/SKILL.md` fully, scoped to the compiled scope.
 2. Apply any review notes from the meta-policy's `## Review Notes` section as additional mandatory conventions during this review.
 3. Fix only mechanical and structural findings from the review. Do NOT invent content to resolve content-level findings.
-4. Any review findings that require inventing or guessing content MUST be recorded as inconsistencies in Phase 7.
+4. Any review findings that require inventing or guessing content MUST be recorded as inconsistencies in Phase 8.
 
-### Phase 7: Document Inconsistencies
+### Phase 8: Document Inconsistencies
 
-1. Collect all inconsistencies noted during Phases 3, 4, and 6.
+1. Collect all inconsistencies noted during Phases 4, 5, and 7.
 2. If any inconsistencies exist:
    - Determine the next available policy number in the `001–100` principles block for the relevant type folder.
    - Create or update `[type]/principles/NNN-inconsistencies-from-source.md` in the scope.
@@ -148,25 +160,46 @@ After writing each policy:
    - Do NOT propose or include fixes.
 3. If no inconsistencies exist, report that the compilation is clean.
 
-### Phase 8: Cleanup
+### Phase 9: Persist Sources and Update Tracking
 
-1. Remove the temporary directory `.tmp/compilation-[ts]/` created in Phase 1.
+1. For each meta-policy and source processed in this run, check its `Source storage` setting.
+2. If storage is persistent (the default): replace the contents of `.assets/sources/[name]/` (excluding `source.md`) with the staged content actually selected and used in Phase 3–4 — remove any previously persisted file that is no longer selected or used, per `_core-adr-policy-019` rule 13.
+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.
+
+### Phase 10: Cleanup
+
+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:
    - 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.
 
 ## Anti-Patterns
 
 - **Mistake:** Inventing content to fill gaps when source material is incomplete or ambiguous.
   **Why it happens:** The agent wants to produce a "complete" policy and fills gaps with plausible-sounding text.
-  **Instead:** Transcribe faithfully, preserve ambiguities as-is, and record inconsistencies in Phase 7 instead of guessing.
+  **Instead:** Transcribe faithfully, preserve ambiguities as-is, and record inconsistencies in Phase 8 instead of guessing.
 
-- **Mistake:** Skipping the Phase 2 confirmation and migrating policies before the user approves the CREATE/UPDATE/REMOVE plan.
+- **Mistake:** Skipping the Phase 3 confirmation and migrating policies before the user approves the CREATE/UPDATE/REMOVE plan.
   **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 3.
+  **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 8 cleanup is easy to forget once the summary is reported.
-  **Instead:** Always remove the temporary directory as the first Phase 8 step, even on partial failures.
+  **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.
+
+- **Mistake:** Skipping Phase 1 and always re-fetching and recompiling, even when every source is well within its re-sync period.
+  **Why it happens:** Re-running the full cycle unconditionally feels more thorough or "safe".
+  **Instead:** Always check `.assets/sources/[name]/source.md` timestamps against `Source re-sync period days` first, and short-circuit with a no-op report when nothing is due.
+
+- **Mistake:** Reading or citing content under `.assets/sources/` as if it were an authoritative policy, or adding a markdown link to it from another document.
+  **Why it happens:** The raw source content is readily available and often more detailed than the compiled policy.
+  **Instead:** Treat only compiled policies as authoritative per `_core-adr-policy-019` rule 14; source content exists solely to support fetch/diff/recompilation, and linking to it is also forbidden mechanically by lint.

package/README.md

@@ -90,13 +90,18 @@ Every scope declares a `scope-type` in its `index.md` frontmatter. The six built
 ```yaml
 # .xdrs/owasp-top10/adrs/principles/001-core.md  (compilation meta-policy)
 ## Sources
-- [web] https://owasp.org/Top10/
-- [git] https://github.com/OWASP/Top10.git
+- [web] owasp-top10-web: https://owasp.org/Top10/
+- [git] owasp-top10-git: https://github.com/OWASP/Top10.git
 
 ## Selectors
 Include A01–A10 risk entries only.
+
+## Sync Settings
+- Source re-sync period days: 30
 ```
 
+By default, fetched and selected source content persists under `.assets/sources/[name]/` so later compilations can re-sync incrementally instead of always refetching; set `Source storage: temporary` in `## Sync Settings` to discard the bulk content after each run instead (only the per-source tracking file persists in that mode). Either way, `.assets/sources/` content is never authoritative on its own — only the compiled policies are.
+
 **`standard` scopes** are the default. Use them for team, product, or business-area scopes that do not fit the other types.
 
 **`_local` scopes** hold workspace-specific content such as local tooling decisions, transition overrides, or temporary decisions. This content is never packaged or distributed.

package/lib/lint.js

@@ -25,6 +25,8 @@ const SKILL_DIR_RE = /^[a-z0-9-]+$/;
 const REQUIRED_ROOT_INDEX_TEXT = 'XDRS scopes listed last override the ones listed first';
 const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches', 'initiatives']);
 const RESOURCE_DIR_NAME = '.assets';
+const SOURCE_SNAPSHOT_DIR_NAME = 'sources';
+const SOURCE_TRACKING_FILE_NAME = 'source.md';
 const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_DIR_NAME, 'dist']);
 
 const POLICY_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'freeze-reference']);
@@ -770,19 +772,58 @@ function lintLocalMetaPolicies(xdrsRoot, scopeName, errors, isCompiledScope = fa
         errors.push(`Local meta-policy companion "${path.basename(companion.filePath)}" requires a primary "NNN-core.md" in the same type folder "${typeName}": ${toDisplayPath(companion.filePath)} [_core-adr-policy-010.10b-local-primary-required]`);
       }
     }
-    // For compiled scopes: primary meta-policy must include ## Sources and ## Selectors
+    // For compiled scopes: primary meta-policy must include ## Sources, ## Selectors, and ## Sync Settings
     if (isCompiledScope && primaryInFolder) {
       let metaContent;
       try { metaContent = fs.readFileSync(primaryInFolder.filePath, 'utf8'); } catch { /* will be caught elsewhere */ }
       if (metaContent !== undefined) {
         const metaLines = metaContent.split(/\r?\n/);
         const metaIgnored = findIgnoredMarkdownLines(metaLines);
-        if (findHeadingLine(metaLines, metaIgnored, '## Sources') === -1) {
+        const metaHeadingLines = findHeadingLines(metaLines, metaIgnored);
+
+        const sourcesHeadingIdx = findHeadingLine(metaLines, metaIgnored, '## Sources');
+        if (sourcesHeadingIdx === -1) {
           errors.push(`Compiled scope meta-policy must include a "## Sources" section: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
+        } else {
+          const [sourcesStart, sourcesEnd] = sectionBodyRange(metaLines, metaHeadingLines, sourcesHeadingIdx);
+          for (let i = sourcesStart; i < sourcesEnd; i += 1) {
+            if (metaIgnored[i]) continue;
+            const trimmed = metaLines[i].trim();
+            if (!trimmed.startsWith('-')) continue;
+            if (!/^-\s+\[(web|git|local)\]\s+[a-z0-9-]+:\s+.+$/.test(trimmed)) {
+              errors.push(`Compiled scope "## Sources" bullet must include a NAME slug in the format "- [web|git|local] name: value": ${toDisplayPath(primaryInFolder.filePath)}:${i + 1} [_core-adr-policy-019.07-compilation-meta-policy]`);
+            }
+          }
         }
+
         if (findHeadingLine(metaLines, metaIgnored, '## Selectors') === -1) {
           errors.push(`Compiled scope meta-policy must include a "## Selectors" section: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
         }
+
+        const syncHeadingIdx = findHeadingLine(metaLines, metaIgnored, '## Sync Settings');
+        if (syncHeadingIdx === -1) {
+          errors.push(`Compiled scope meta-policy must include a "## Sync Settings" section: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
+        } else {
+          const [syncStart, syncEnd] = sectionBodyRange(metaLines, metaHeadingLines, syncHeadingIdx);
+          let hasValidResyncPeriod = false;
+          for (let i = syncStart; i < syncEnd; i += 1) {
+            if (metaIgnored[i]) continue;
+            const trimmed = metaLines[i].trim();
+            if (!trimmed.startsWith('-')) continue;
+            const periodMatch = trimmed.match(/^-\s+Source re-sync period days:\s*(\d+)\s*$/);
+            if (periodMatch) {
+              hasValidResyncPeriod = Number(periodMatch[1]) > 0;
+              continue;
+            }
+            const storageMatch = trimmed.match(/^-\s+Source storage:\s*(.+)$/);
+            if (storageMatch && storageMatch[1].trim() !== 'temporary') {
+              errors.push(`Compiled scope "## Sync Settings" "Source storage" value must be "temporary" if present: ${toDisplayPath(primaryInFolder.filePath)}:${i + 1} [_core-adr-policy-019.07-compilation-meta-policy]`);
+            }
+          }
+          if (!hasValidResyncPeriod) {
+            errors.push(`Compiled scope "## Sync Settings" section must include a "Source re-sync period days: N" bullet with a positive integer: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
+          }
+        }
       }
     }
     // Check qualifier uniqueness across all type folders
@@ -884,7 +925,7 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNu
 
   const subjectAssetsDir = path.join(subjectPath, RESOURCE_DIR_NAME);
   const xdrsDocsInSubject = artifacts.filter((p) => path.dirname(p) === subjectPath);
-  lintOrphanAssets(subjectAssetsDir, xdrsDocsInSubject, xdrsRoot, errors);
+  lintOrphanAssets(subjectAssetsDir, xdrsDocsInSubject, xdrsRoot, errors, isCompiledScope);
 
   return artifacts;
 }
@@ -1833,11 +1874,16 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors, externalScopes =
   }
 }
 
-function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
+function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors, isCompiledScope = false) {
   if (!existsDirectory(assetsDir)) {
     return;
   }
 
+  const sourcesDir = path.join(assetsDir, SOURCE_SNAPSHOT_DIR_NAME);
+  if (isCompiledScope) {
+    lintSourceSnapshotTracking(sourcesDir, errors);
+  }
+
   const assetTree = collectAssetTree(assetsDir, errors);
   if (assetTree.files.length === 0 && assetTree.directories.length === 0) {
     return;
@@ -1859,6 +1905,9 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
   }
 
   for (const assetPath of assetTree.files) {
+    if (isCompiledScope && isPathInside(sourcesDir, assetPath)) {
+      continue;
+    }
     if (!referencedAssets.has(assetPath)) {
       errors.push(`Orphan asset file not referenced by any document: ${toDisplayPath(assetPath)} [_core-adr-policy-001]`);
     }
@@ -1866,6 +1915,9 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
 
   // Lint slide/presentation files inside .assets
   for (const assetPath of assetTree.files) {
+    if (isCompiledScope && isPathInside(sourcesDir, assetPath)) {
+      continue;
+    }
     const fileName = path.basename(assetPath);
     if (SLIDE_FILE_RE.test(fileName)) {
       lintSlideFile(assetPath, documentPaths, xdrsRoot, errors);
@@ -1873,6 +1925,47 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
   }
 }
 
+function lintSourceSnapshotTracking(sourcesDir, errors) {
+  if (!existsDirectory(sourcesDir)) {
+    return;
+  }
+
+  const entries = safeReadDir(sourcesDir, errors, `read source snapshot directory ${toDisplayPath(sourcesDir)}`);
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const trackingFilePath = path.join(sourcesDir, entry.name, SOURCE_TRACKING_FILE_NAME);
+    if (!existsFile(trackingFilePath)) {
+      errors.push(`Compiled source snapshot folder must contain a "${SOURCE_TRACKING_FILE_NAME}" tracking file: ${toDisplayPath(trackingFilePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+      continue;
+    }
+    validateSourceTrackingFile(trackingFilePath, errors);
+  }
+}
+
+function validateSourceTrackingFile(filePath, errors) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split(/\r?\n/);
+
+  if (firstNonEmptyLine(content) !== '# Source') {
+    errors.push(`Source tracking file must start with a "# Source" heading: ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+  }
+
+  const timestampRe = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+  for (const field of ['last-fetch-timestamp', 'last-compilation-timestamp']) {
+    const fieldLine = lines.find((line) => line.trim().startsWith(`${field}:`));
+    if (!fieldLine) {
+      errors.push(`Source tracking file must include a "${field}:" line: ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+      continue;
+    }
+    const value = fieldLine.trim().slice(`${field}:`.length).trim();
+    if (!timestampRe.test(value)) {
+      errors.push(`Source tracking file "${field}" must match "YYYY-MM-DD HH:MM:SS": ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+    }
+  }
+}
+
 function lintSlideFile(filePath, documentPaths, xdrsRoot, errors) {
   const fileName = path.basename(filePath);
 
@@ -1983,6 +2076,10 @@ function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors, externalSc
       if (isResourceLink && !isPathInside(resourceDir, link.resolvedPath)) {
         errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget} [_core-adr-policy-001]`);
       }
+
+      if (isSourceSnapshotPath(link.resolvedPath)) {
+        errors.push(`Document must not link directly to compiled-source snapshot content, which is not authoritative (see _core-adr-policy-019 rule 14) in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget} [_core-adr-policy-019.14-source-not-authoritative]`);
+      }
     }
   }
 }
@@ -2069,6 +2166,11 @@ function shouldValidateResourceLink(rawTarget) {
     || IMAGE_EXTENSIONS.has(extension);
 }
 
+function isSourceSnapshotPath(resolvedPath) {
+  const normalized = normalizePath(resolvedPath).split(path.sep).join('/');
+  return normalized.includes(`/${RESOURCE_DIR_NAME}/${SOURCE_SNAPSHOT_DIR_NAME}/`);
+}
+
 function extractDescriptionText(block) {
   const lines = block.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {

package/lib/lint.test.js

@@ -3122,11 +3122,15 @@ function validCompiledMetaPolicy() {
     '',
     '## Sources',
     '',
-    '- [web] https://example.com/standards',
+    '- [web] example-standards: https://example.com/standards',
     '',
     '## Selectors',
     '',
     '- Include all requirement sections.',
+    '',
+    '## Sync Settings',
+    '',
+    '- Source re-sync period days: 30',
     ''
   ].join('\n');
 }
@@ -3416,6 +3420,331 @@ test('reports compiled scope meta-policy missing ## Selectors section', () => {
   expect(result.errors.join('\n')).toContain('019.07-compilation-meta-policy');
 });
 
+test('reports compiled scope meta-policy missing ## Sync Settings section', () => {
+  const workspaceRoot = createWorkspace('compiled-meta-missing-sync-settings', {
+    '.xdrs/index.md': rootIndex(['[my-compiled](my-compiled/index.md)']),
+    '.xdrs/my-compiled/index.md': compiledScopeIndex(),
+    '.xdrs/my-compiled/adrs/index.md': compiledAdrIndex([
+      '- [001-core](principles/001-core.md) - meta-policy',
+      '- [002-a01](principles/002-a01.md) - A01'
+    ]),
+    '.xdrs/my-compiled/adrs/principles/001-core.md': [
+      '---',
+      'name: my-compiled-adr-policy-001-core',
+      'description: Compilation meta-policy.',
+      'apply-to: Compilation process',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# my-compiled-adr-policy-001: core',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Defines compilation config.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Use configured sources.',
+      '',
+      '### Details',
+      '',
+      '#### 01-rule',
+      '',
+      'MUST use configured sources.',
+      '',
+      '## Sources',
+      '',
+      '- [web] example-standards: https://example.com/standards',
+      '',
+      '## Selectors',
+      '',
+      '- Include requirement sections.',
+      ''
+    ].join('\n'),
+    '.xdrs/my-compiled/adrs/principles/002-a01.md': [
+      '---',
+      'name: my-compiled-adr-policy-002-a01',
+      'description: Compiled test policy.',
+      'apply-to: All teams',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# my-compiled-adr-policy-002: A01',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'External source.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Follow rule.',
+      '',
+      '### Details',
+      '',
+      '#### 01-rule',
+      '',
+      'MUST comply.',
+      '',
+      '## Source',
+      '',
+      '- source-1/a01.md',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('"## Sync Settings" section');
+  expect(result.errors.join('\n')).toContain('019.07-compilation-meta-policy');
+});
+
+test('reports missing Source re-sync period days in ## Sync Settings', () => {
+  const workspaceRoot = createWorkspace('compiled-meta-missing-resync-period', {
+    '.xdrs/index.md': rootIndex(['[my-compiled](my-compiled/index.md)']),
+    '.xdrs/my-compiled/index.md': compiledScopeIndex(),
+    '.xdrs/my-compiled/adrs/index.md': compiledAdrIndex([
+      '- [001-core](principles/001-core.md) - meta-policy',
+      '- [002-a01](principles/002-a01.md) - A01'
+    ]),
+    '.xdrs/my-compiled/adrs/principles/001-core.md': [
+      '---',
+      'name: my-compiled-adr-policy-001-core',
+      'description: Compilation meta-policy.',
+      'apply-to: Compilation process',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# my-compiled-adr-policy-001: core',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Defines compilation config.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Use configured sources.',
+      '',
+      '### Details',
+      '',
+      '#### 01-rule',
+      '',
+      'MUST use configured sources.',
+      '',
+      '## Sources',
+      '',
+      '- [web] example-standards: https://example.com/standards',
+      '',
+      '## Selectors',
+      '',
+      '- Include requirement sections.',
+      '',
+      '## Sync Settings',
+      '',
+      '- Source storage: temporary',
+      ''
+    ].join('\n'),
+    '.xdrs/my-compiled/adrs/principles/002-a01.md': [
+      '---',
+      'name: my-compiled-adr-policy-002-a01',
+      'description: Compiled test policy.',
+      'apply-to: All teams',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# my-compiled-adr-policy-002: A01',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'External source.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Follow rule.',
+      '',
+      '### Details',
+      '',
+      '#### 01-rule',
+      '',
+      'MUST comply.',
+      '',
+      '## Source',
+      '',
+      '- source-1/a01.md',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('"Source re-sync period days: N" bullet with a positive integer');
+  expect(result.errors.join('\n')).toContain('019.07-compilation-meta-policy');
+});
+
+test('reports invalid Source storage value in ## Sync Settings', () => {
+  const workspaceRoot = createWorkspace('compiled-meta-invalid-storage-value', {
+    '.xdrs/index.md': rootIndex(['[my-compiled](my-compiled/index.md)']),
+    '.xdrs/my-compiled/index.md': compiledScopeIndex(),
+    '.xdrs/my-compiled/adrs/index.md': compiledAdrIndex([
+      '- [001-core](principles/001-core.md) - meta-policy',
+      '- [002-a01](principles/002-a01.md) - A01'
+    ]),
+    '.xdrs/my-compiled/adrs/principles/001-core.md': [
+      '---',
+      'name: my-compiled-adr-policy-001-core',
+      'description: Compilation meta-policy.',
+      'apply-to: Compilation process',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# my-compiled-adr-policy-001: core',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Defines compilation config.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Use configured sources.',
+      '',
+      '### Details',
+      '',
+      '#### 01-rule',
+      '',
+      'MUST use configured sources.',
+      '',
+      '## Sources',
+      '',
+      '- [web] example-standards: https://example.com/standards',
+      '',
+      '## Selectors',
+      '',
+      '- Include requirement sections.',
+      '',
+      '## Sync Settings',
+      '',
+      '- Source re-sync period days: 30',
+      '- Source storage: permanent',
+      ''
+    ].join('\n'),
+    '.xdrs/my-compiled/adrs/principles/002-a01.md': [
+      '---',
+      'name: my-compiled-adr-policy-002-a01',
+      'description: Compiled test policy.',
+      'apply-to: All teams',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# my-compiled-adr-policy-002: A01',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'External source.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Follow rule.',
+      '',
+      '### Details',
+      '',
+      '#### 01-rule',
+      '',
+      'MUST comply.',
+      '',
+      '## Source',
+      '',
+      '- source-1/a01.md',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('"Source storage" value must be "temporary" if present');
+  expect(result.errors.join('\n')).toContain('019.07-compilation-meta-policy');
+});
+
+test('reports compiled scope ## Sources bullet missing NAME slug', () => {
+  const workspaceRoot = createWorkspace('compiled-meta-sources-missing-name', {
+    '.xdrs/index.md': rootIndex(['[my-compiled](my-compiled/index.md)']),
+    '.xdrs/my-compiled/index.md': compiledScopeIndex(),
+    '.xdrs/my-compiled/adrs/index.md': compiledAdrIndex([
+      '- [001-core](principles/001-core.md) - meta-policy',
+      '- [002-a01](principles/002-a01.md) - A01'
+    ]),
+    '.xdrs/my-compiled/adrs/principles/001-core.md': [
+      '---',
+      'name: my-compiled-adr-policy-001-core',
+      'description: Compilation meta-policy.',
+      'apply-to: Compilation process',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# my-compiled-adr-policy-001: core',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Defines compilation config.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Use configured sources.',
+      '',
+      '### Details',
+      '',
+      '#### 01-rule',
+      '',
+      'MUST use configured sources.',
+      '',
+      '## Sources',
+      '',
+      '- [web] https://example.com/standards',
+      '',
+      '## Selectors',
+      '',
+      '- Include requirement sections.',
+      '',
+      '## Sync Settings',
+      '',
+      '- Source re-sync period days: 30',
+      ''
+    ].join('\n'),
+    '.xdrs/my-compiled/adrs/principles/002-a01.md': [
+      '---',
+      'name: my-compiled-adr-policy-002-a01',
+      'description: Compiled test policy.',
+      'apply-to: All teams',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# my-compiled-adr-policy-002: A01',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'External source.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Follow rule.',
+      '',
+      '### Details',
+      '',
+      '#### 01-rule',
+      '',
+      'MUST comply.',
+      '',
+      '## Source',
+      '',
+      '- source-1/a01.md',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('must include a NAME slug');
+  expect(result.errors.join('\n')).toContain('019.07-compilation-meta-policy');
+});
+
 test('accepts valid compiled scope meta-policy with required sections', () => {
   const workspaceRoot = createWorkspace('compiled-meta-valid', {
     '.xdrs/index.md': rootIndex(['[my-compiled](my-compiled/index.md)']),
@@ -3476,6 +3805,88 @@ test('skips ## Source check for local meta-policy files in compiled scope', () =
   expect(result.errors.join('\n')).not.toContain('Compiled policy must include a "## Source" section');
 });
 
+test('does not report orphan asset errors for files under .assets/sources in a compiled scope', () => {
+  const workspaceRoot = createWorkspace('compiled-sources-orphan-exempt', {
+    '.xdrs/index.md': rootIndex(['[my-compiled](my-compiled/index.md)']),
+    '.xdrs/my-compiled/index.md': compiledScopeIndex(),
+    '.xdrs/my-compiled/adrs/index.md': compiledAdrIndex([
+      '- [001-core](principles/001-core.md) - meta-policy'
+    ]),
+    '.xdrs/my-compiled/adrs/principles/001-core.md': validCompiledMetaPolicy(),
+    '.xdrs/my-compiled/adrs/principles/.assets/sources/example-standards/source.md': [
+      '# Source',
+      '',
+      'last-fetch-timestamp: 2026-01-01 10:00:00',
+      'last-compilation-timestamp: 2026-01-01 10:05:00',
+      ''
+    ].join('\n'),
+    '.xdrs/my-compiled/adrs/principles/.assets/sources/example-standards/raw-standard.md': '# Raw fetched content\n',
+    '.xdrs/my-compiled/adrs/principles/.assets/unused.png': Buffer.alloc(0),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('raw-standard.md');
+  expect(result.errors.join('\n')).not.toContain('019.12-source-storage-tracking');
+  expect(result.errors.join('\n')).toContain('Orphan asset file');
+  expect(result.errors.join('\n')).toContain('unused.png');
+});
+
+test('reports missing source.md tracking file in a compiled source snapshot folder', () => {
+  const workspaceRoot = createWorkspace('compiled-sources-missing-tracking-file', {
+    '.xdrs/index.md': rootIndex(['[my-compiled](my-compiled/index.md)']),
+    '.xdrs/my-compiled/index.md': compiledScopeIndex(),
+    '.xdrs/my-compiled/adrs/index.md': compiledAdrIndex([
+      '- [001-core](principles/001-core.md) - meta-policy'
+    ]),
+    '.xdrs/my-compiled/adrs/principles/001-core.md': validCompiledMetaPolicy(),
+    '.xdrs/my-compiled/adrs/principles/.assets/sources/example-standards/raw-standard.md': '# Raw fetched content\n',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('must contain a "source.md" tracking file');
+  expect(result.errors.join('\n')).toContain('019.12-source-storage-tracking');
+});
+
+test('reports malformed source.md tracking file content', () => {
+  const workspaceRoot = createWorkspace('compiled-sources-malformed-tracking-file', {
+    '.xdrs/index.md': rootIndex(['[my-compiled](my-compiled/index.md)']),
+    '.xdrs/my-compiled/index.md': compiledScopeIndex(),
+    '.xdrs/my-compiled/adrs/index.md': compiledAdrIndex([
+      '- [001-core](principles/001-core.md) - meta-policy'
+    ]),
+    '.xdrs/my-compiled/adrs/principles/001-core.md': validCompiledMetaPolicy(),
+    '.xdrs/my-compiled/adrs/principles/.assets/sources/example-standards/source.md': [
+      'last-fetch-timestamp: not-a-date',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('must start with a "# Source" heading');
+  expect(result.errors.join('\n')).toContain('must include a "last-compilation-timestamp:" line');
+  expect(result.errors.join('\n')).toContain('must match "YYYY-MM-DD HH:MM:SS"');
+  expect(result.errors.join('\n')).toContain('019.12-source-storage-tracking');
+});
+
+test('reports document linking directly into a compiled-source snapshot path', () => {
+  const workspaceRoot = createWorkspace('source-snapshot-link-forbidden', {
+    '.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('See [raw source](.assets/sources/example-standards/raw-standard.md).'),
+    '.xdrs/_local/adrs/principles/.assets/sources/example-standards/raw-standard.md': '# Raw fetched content\n',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('must not link directly to compiled-source snapshot content');
+  expect(result.errors.join('\n')).toContain('019.14-source-not-authoritative');
+});
+
 test('enforces compiled scope checks when scope-type is comma-separated with compiled', () => {
   const workspaceRoot = createWorkspace('compiled-multi-type-checks', {
     '.xdrs/index.md': rootIndex(['[my-compiled-scope](my-compiled-scope/index.md)']),

package/package.json

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