xdrs-core 0.28.0 → 0.28.1

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

@@ -40,7 +40,7 @@ Policies can be of different kinds, depending on the nature of the decision:
   `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md`
   where `[xdrs-root]` is the XDRS root folder (default: `.xdrs/`).
 - ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
-- **Files listed in `.filedist` are external XDRs.** A file whose path appears in the workspace root `.filedist` file was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist`, and tools (such as `xdrs-core lint`) will skip external scopes by default. The `.filedist` 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` 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 NEVER 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`, and tools (such as `xdrs-core lint`) will skip external scopes by default. 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/[number]-[skill-name]/SKILL.md`

package/.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md

@@ -181,7 +181,7 @@ Follow [_core-adr-policy-001](../001-xdrs-core.md) and [_core-adr-policy-002](..
 1. **Install** — add the scope package as a dependency and run `npx xdrs-core extract` (or
    `pnpm exec xdrs-core extract`) to unpack XDRS files into `.xdrs/` in your workspace.
 2. **Pins and upgrades** — update the npm dependency version to pull in the latest decisions
-   for a scope. The `filedist` mechanism tracks managed files in `.filedist` and keeps
+   for a scope. The `filedist` mechanism tracks managed files in `.filedist.lock` and keeps
   `.xdrs/index.md` in `keepExisting` mode so local edits are preserved.
 3. **Multi-scope** — list multiple scope packages as dependencies. Edit `.xdrs/index.md` to
    add each scope's canonical index link; place more specific scopes below broader ones.

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

@@ -35,7 +35,7 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 - **EDR**: specific tool/library, coding practice, testing strategy, project structure
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Subject** — pick one from the allowed list for the chosen type (from `001-xdrs-core`):
 - ADR: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
@@ -187,7 +187,7 @@ If any check fails, revise and re-run this phase before proceeding.
 - MUST NOT create a Policy that duplicates a decision already captured in another Policy — extend or reference instead.
 - MUST prefer links and short references over repeating the same decision content across related documents.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 
 ## References
 

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

@@ -36,7 +36,7 @@ Quick test:
 - "How to execute a business process or policy?" → BDR
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Subject** — pick the most specific match for the chosen type (required list per type is in `_core-adr-policy-001`):
 - ADR subjects: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
@@ -131,11 +131,9 @@ If any check fails, revise before continuing.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST NOT create a skill that duplicates an existing one — extend or reference it instead.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST include a References section linking to `003-skill-standards`.
 
-## Examples
-
 **Input**: "Create a skill to help debug CI pipelines"
 - Type: EDR (engineering workflow)
 - Scope: `_local`

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

@@ -41,7 +41,7 @@ Do NOT proceed to Phase 1 until you have at minimum a clear **topic** and **audi
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of the XDRS elements the article primarily synthesizes (`adrs`, `bdrs`, or `edrs`).
 If the topic spans multiple types, use `adrs`. Use the same rules as `002-write-policy` Phase 2:
@@ -140,11 +140,9 @@ Rules to apply while drafting:
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST follow the article template and placement rules from `004-article-standards`.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST defer to active and applicable Policies when article synthesis conflicts with them.
 
-## References
-
 - [_core-adr-policy-004 - Article standards](../../004-article-standards.md)
 - [_core-adr-policy-006 - Research standards](../../006-research-standards.md)
 - [_core-adr-policy-001 - XDRS core](../../001-xdrs-core.md)

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

@@ -36,7 +36,7 @@ If the answers from Phase 1 leave scope, type, or subject ambiguous, use `vscode
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail matters, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`). Use the same rules as `002-write-policy` Phase 2:
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -278,6 +278,5 @@ If any check fails, revise before continuing.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST follow the research template and section-goal rules from `006-research-standards`.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).
 - MUST keep the document as research rather than turning it into a final decision.
-ing it into a final decision.

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

@@ -33,7 +33,7 @@ Guides the creation of a well-structured plan document by following `_core-adr-p
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of the Policies the plan primarily implements or relates to (`adrs`, `bdrs`, or `edrs`).
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -164,4 +164,4 @@ Rules to apply while drafting:
 - MUST follow the plan template and section-goal rules from `007-plan-standards`.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
-- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist.lock`).

package/README.md

@@ -166,7 +166,7 @@ Multiple scope packages can be combined in the same workspace by listing them as
 The published package exposes the `xdrs-core` CLI.
 
 - Bootstrap or extract managed XDRS files with the existing `filedist`-backed commands such as `npx -y xdrs-core extract` and `npx -y xdrs-core check`.
-- Lint a Policy tree with `npx -y xdrs-core lint .`. By default, scopes whose files are listed in the workspace root `.filedist` file are treated as external and skipped; use `--all` to include them.
+- Lint a Policy tree with `npx -y xdrs-core lint .`. By default, scopes whose files are listed in the workspace root `.filedist.lock` file are treated as external and skipped; use `--all` to include them.
 
 The `lint` command reads `./.xdrs/**` from the given workspace path and checks common consistency rules, including:
 

package/lib/lint.js

@@ -64,7 +64,7 @@ function printHelp() {
   console.log('Usage: xdrs-core lint [options] [path]\n');
   console.log('Lint the XDRS tree rooted at [path] when [path] contains an index.md, or at [path]/.xdrs by default.');
   console.log('\nOptions:');
-  console.log('  --all    Check all files, including files from external scopes distributed via .filedist (default: skip external scopes)');
+  console.log('  --all    Check all files, including files from external scopes distributed via .filedist.lock (default: skip external scopes)');
   console.log('\nAll other commands continue to be delegated to the bundled filedist CLI.');
 }
 
@@ -991,7 +991,7 @@ function isExternalScopeLink(resolvedPath, xdrsRoot, externalScopes) {
   if (parts.length === 0 || !parts[0]) return false;
   const scopeName = parts[0];
 
-  // Treat as external if explicitly listed via .filedist OR if the scope directory
+  // Treat as external if explicitly listed via .filedist.lock OR if the scope directory
   // doesn't exist locally (e.g. hasn't been extracted from an external package yet)
   return externalScopes.has(scopeName) || !existsDirectory(path.join(xdrsRoot, scopeName));
 }
@@ -1192,7 +1192,7 @@ function existsFile(filePath) {
 }
 
 function loadFiledist(repoRoot) {
-  const filedistPath = path.join(repoRoot, '.filedist');
+  const filedistPath = path.join(repoRoot, '.filedist.lock');
   if (!existsFile(filedistPath)) {
     return new Set();
   }

package/lib/lint.test.js

@@ -91,7 +91,7 @@ test('skips external scopes by default and checks them when ignoreExternal is fa
       'See [Missing](002-missing.md).',
       ''
     ].join('\n'),
-    '.filedist': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
+    '.filedist.lock': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
   });
 
   const defaultResult = lintWorkspace(workspaceRoot);
@@ -160,7 +160,7 @@ test('skips entire external scope when only some of its files are in filedist',
       'See [Missing](003-missing.md).',
       ''
     ].join('\n'),
-    '.filedist': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
+    '.filedist.lock': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
   });
 
   const result = lintWorkspace(workspaceRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "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",