xdrs-core 0.15.0 → 0.15.2

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

@@ -36,6 +36,7 @@ Collectively, these are referred to as XDRs.
 - ALWAYS use the following folder structure for XDR documents:
   `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
 - ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
+- **Readonly files are external XDRs.** A file with read-only permissions (e.g., `444` set by a distribution tool such as filedist) 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.
 - Optional supporting artifacts under the same subject:
   - `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`

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

@@ -77,12 +77,14 @@ Choose a title that clearly states the question this XDR answers, not the answer
 Use the mandatory template from `002-xdr-standards`:
 
 ```
-# [scope]-[type]-[number]: [Short Title]
+---
+name: [scope]-[type]-[number]-[short-title]
+description: [What this decision is about and when to use it]
+applied-to: [Optional. Contexts this decision applies to, under 40 words]
+valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
+---
 
-## Metadata
-[Optional. Include only when at least one metadata field is present]
-Valid: [Optional. Use from YYYY-MM-DD to set a convergence date for adoption]
-Applied to: [Optional short applicability scope, under 40 words]
+# [scope]-[type]-[number]: [Short Title]
 
 ## Context and Problem Statement
 [background, who is impacted, and the explicit question being answered - under 40 words]
@@ -103,10 +105,10 @@ Applied to: [Optional short applicability scope, under 40 words]
 ```
 
 Mandatory rules to apply while drafting:
-- Include `## Metadata` only when `Valid:` and/or `Applied to:` adds value; omit the whole section when none of those fields is defined.
-- When present, place `## Metadata` immediately before `## Context and Problem Statement`.
-- Keep `Applied to:` under 40 words and use `Valid:` only with `from YYYY-MM-DD` format.
-- When metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `Valid:` sets a convergence date for adoption, `Applied to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
+- Include frontmatter `applied-to:` only when it adds value by narrowing the decision scope; omit it when the decision applies broadly.
+- Include frontmatter `valid-from:` only when there is a specific future enforcement date; omit it when the decision is immediately effective.
+- Keep `applied-to:` under 40 words and use `valid-from:` only with `YYYY-MM-DD` ISO format.
+- When frontmatter metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `valid-from:` sets a convergence date for adoption, `applied-to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
 - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
 - Do not duplicate content already in referenced XDRs — link instead.
 - Keep the decision itself authoritative in the XDR. Supporting artifacts may elaborate, but they should not restate the full decision when a short reference is enough.
@@ -122,7 +124,7 @@ Mandatory rules to apply while drafting:
 Check every item before finalizing:
 
 1. **Length**: Is it under 1300 words? Trim verbose explanations. Move detailed skills to a separate file and link.
-2. **Metadata**: If metadata exists, is it directly before Context, limited to `Valid:` / `Applied to:`, omitted entirely when both are absent, and specific enough for a reader to decide whether the XDR is currently valid and applicable?
+2. **Frontmatter**: Are `applied-to:` and `valid-from:` present only when they add value, omitted entirely when not needed, and specific enough for a reader to decide whether the XDR is currently valid and applicable?
 3. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
 4. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
 5. **Redundancy**: Is the XDR the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?

package/lib/lint.js

@@ -31,8 +31,10 @@ function runLintCli(args) {
     return 0;
   }
 
-  const targetPath = args[0] || '.';
-  const result = lintWorkspace(targetPath);
+  const all = args.includes('--all');
+  const pathArgs = args.filter((a) => !a.startsWith('--'));
+  const targetPath = pathArgs[0] || '.';
+  const result = lintWorkspace(targetPath, { ignoreReadOnly: !all });
 
   if (result.errors.length === 0) {
     console.log(`Lint passed for ${toDisplayPath(result.xdrsRoot)}`);
@@ -48,12 +50,15 @@ function runLintCli(args) {
 }
 
 function printHelp() {
-  console.log('Usage: xdrs-core lint [path]\n');
+  console.log('Usage: xdrs-core lint [options] [path]\n');
   console.log('Lint the XDR tree rooted at [path]/.xdrs or at [path] when [path] already points to .xdrs.');
-  console.log('All other commands continue to be delegated to the bundled filedist CLI.');
+  console.log('\nOptions:');
+  console.log('  --all    Check all files, including read-only files from other scopes (default: skip read-only files)');
+  console.log('\nAll other commands continue to be delegated to the bundled filedist CLI.');
 }
 
-function lintWorkspace(targetPath) {
+function lintWorkspace(targetPath, options = {}) {
+  const { ignoreReadOnly = true } = options;
   const resolvedTarget = path.resolve(targetPath);
   const xdrsRoot = path.basename(resolvedTarget) === '.xdrs'
     ? resolvedTarget
@@ -76,7 +81,7 @@ function lintWorkspace(targetPath) {
   }
 
   for (const scopeEntry of scopeEntries) {
-    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes);
+    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes, ignoreReadOnly);
   }
 
   const rootIndexPath = path.join(xdrsRoot, 'index.md');
@@ -124,9 +129,13 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
   }
 }
 
-function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes) {
+function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreReadOnly) {
   const scopePath = path.join(xdrsRoot, scopeName);
 
+  if (ignoreReadOnly && isReadOnly(scopePath)) {
+    return;
+  }
+
   if (!isValidScopeName(scopeName)) {
     errors.push(`Invalid scope name: ${toDisplayPath(scopePath)}`);
   }
@@ -744,6 +753,15 @@ function existsFile(filePath) {
   }
 }
 
+function isReadOnly(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.W_OK);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
 function displayPath(indexPath, targetPath) {
   return `${toDisplayPath(indexPath)} -> ${toDisplayPath(targetPath)}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "A standard way to organize Decision Records (XDRs) across scopes, subjects, and teams so that AI agents can reliably query and follow them.",
   "repository": {
     "type": "git",