cabloy 5.1.200 → 5.1.201

package/.cabloy-version

@@ -1 +1 @@
-5.1.200
+5.1.201

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 5.1.201
+
+### Features
+
+- Support scoped spec traceability exceptions.
+
+### Bug Fixes
+
+- Fix the CabloyJS Admin SSR video.
+
+### Improvements
+
+- Add the CabloyJS Admin SSR video to the demonstrations.
+- Refine the spec parser.
+
 ## 5.1.200
 
 ### Features

package/README.md

@@ -36,6 +36,12 @@ For Cabloy Start, clone the [Cabloy Start repository](https://github.com/cabloy/
 
 See the [AI Spec-Driven Development](https://cabloy.com/ai/ai-spec-driven-development).
 
+## Demonstrations(Videos)
+
+### 1. Can an Admin Site Use SSR? CabloyJS in Three Practical Demos (Duration: 1:16)
+
+[![CabloyJS Admin SSR video](./repo-docs/assets/img/cabloy-admin-ssr-cover-en.png)](https://youtu.be/786IQhRdr1I)
+
 ## Editions
 
 Cabloy is available through two complete project baselines, each maintained in its own repository:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.200",
+  "version": "5.1.201",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-agent-governance/managed-assets.json

@@ -221,7 +221,7 @@
     {
       "adapter": "codex",
       "category": "skill",
-      "sha256": "2b59a2f5322befbef51690e77c19d55de2cf690572d5159ca946290b0ec7319e",
+      "sha256": "df49ea0a8485de0ea6cf345199481836924eed0b68608abf4e6ed829f620b72e",
       "source": "skills/cabloy-spec-generation/references/canonical-spec-input.md",
       "target": ".agents/skills/cabloy-spec-generation/references/canonical-spec-input.md"
     },
@@ -235,14 +235,14 @@
     {
       "adapter": "codex",
       "category": "skill",
-      "sha256": "772e83aea0d7a3ad3d5a91d4ecedd09f6cd24ae9eb146399f0834ded3f074185",
+      "sha256": "95fb6ad6f1f85373a6565442e4f0f50582acafd2bef5c8f1f0056123b0996bc8",
       "source": "skills/cabloy-spec-generation/references/repo-specs-document-set.md",
       "target": ".agents/skills/cabloy-spec-generation/references/repo-specs-document-set.md"
     },
     {
       "adapter": "codex",
       "category": "skill",
-      "sha256": "242d3b7dd6f9266fa836918443c06add6bf9d2308d7f4288112412ee3a6224f5",
+      "sha256": "45b83917c079306fb56e0c2cf406a894f7c18c9fd8732f97f9902ed02cf32594",
       "source": "skills/cabloy-spec-generation/references/traceability-and-status-rules.md",
       "target": ".agents/skills/cabloy-spec-generation/references/traceability-and-status-rules.md"
     },
@@ -557,7 +557,7 @@
     {
       "adapter": "claude",
       "category": "skill",
-      "sha256": "2b59a2f5322befbef51690e77c19d55de2cf690572d5159ca946290b0ec7319e",
+      "sha256": "df49ea0a8485de0ea6cf345199481836924eed0b68608abf4e6ed829f620b72e",
       "source": "skills/cabloy-spec-generation/references/canonical-spec-input.md",
       "target": ".claude/skills/cabloy-spec-generation/references/canonical-spec-input.md"
     },
@@ -571,14 +571,14 @@
     {
       "adapter": "claude",
       "category": "skill",
-      "sha256": "772e83aea0d7a3ad3d5a91d4ecedd09f6cd24ae9eb146399f0834ded3f074185",
+      "sha256": "95fb6ad6f1f85373a6565442e4f0f50582acafd2bef5c8f1f0056123b0996bc8",
       "source": "skills/cabloy-spec-generation/references/repo-specs-document-set.md",
       "target": ".claude/skills/cabloy-spec-generation/references/repo-specs-document-set.md"
     },
     {
       "adapter": "claude",
       "category": "skill",
-      "sha256": "242d3b7dd6f9266fa836918443c06add6bf9d2308d7f4288112412ee3a6224f5",
+      "sha256": "45b83917c079306fb56e0c2cf406a894f7c18c9fd8732f97f9902ed02cf32594",
       "source": "skills/cabloy-spec-generation/references/traceability-and-status-rules.md",
       "target": ".claude/skills/cabloy-spec-generation/references/traceability-and-status-rules.md"
     },
@@ -907,7 +907,7 @@
     {
       "adapter": "cursor",
       "category": "skill",
-      "sha256": "2b59a2f5322befbef51690e77c19d55de2cf690572d5159ca946290b0ec7319e",
+      "sha256": "df49ea0a8485de0ea6cf345199481836924eed0b68608abf4e6ed829f620b72e",
       "source": "skills/cabloy-spec-generation/references/canonical-spec-input.md",
       "target": ".cursor/skills/cabloy-spec-generation/references/canonical-spec-input.md"
     },
@@ -921,14 +921,14 @@
     {
       "adapter": "cursor",
       "category": "skill",
-      "sha256": "772e83aea0d7a3ad3d5a91d4ecedd09f6cd24ae9eb146399f0834ded3f074185",
+      "sha256": "95fb6ad6f1f85373a6565442e4f0f50582acafd2bef5c8f1f0056123b0996bc8",
       "source": "skills/cabloy-spec-generation/references/repo-specs-document-set.md",
       "target": ".cursor/skills/cabloy-spec-generation/references/repo-specs-document-set.md"
     },
     {
       "adapter": "cursor",
       "category": "skill",
-      "sha256": "242d3b7dd6f9266fa836918443c06add6bf9d2308d7f4288112412ee3a6224f5",
+      "sha256": "45b83917c079306fb56e0c2cf406a894f7c18c9fd8732f97f9902ed02cf32594",
       "source": "skills/cabloy-spec-generation/references/traceability-and-status-rules.md",
       "target": ".cursor/skills/cabloy-spec-generation/references/traceability-and-status-rules.md"
     },

package/repo-agent-governance/skills/cabloy-spec-generation/references/canonical-spec-input.md

@@ -17,6 +17,8 @@ References in matrices, related-record lists, progress, evidence, templates, wil
 
 Use exact instantiated IDs in declaration-body Traceability. A wildcard or abbreviated range is an aggregate summary, not an exact association or substitute for missing definitions. Keep associations explicit even if a downstream summary matrix repeats them. The audit must derive associations from the declaration body, not nearby unrelated sections.
 
+For a genuinely cross-cutting engineering contract without a product requirement, an atomic SRS bullet may carry `Traceability exception: technical-only — <record-specific rationale>` on its definition line. This exempts only the incoming PRD association; its outgoing WBS mapping remains required. For a documentary planning or release gate with no independent executable scenario, a WBS task may carry `Traceability exception: authority-only — <record-specific rationale>` in its declaration body. This exempts only the outgoing ATP association; its incoming SRS mapping remains required. Use exactly one well-formed field on the correct definition and explain the alternative authority or retained documentary checks. The auditor rejects malformed, empty, duplicated, or wrong-kind exceptions. Neither classification waives the underlying contract, delivery checks, applicable ATPs, revision-scoped evidence, or release approval; never use one merely to silence a missing real link.
+
 ## Minimal connected example
 
 These are neutral **syntax examples**, not business requirements to copy into a real suite. All four IDs are exact and unique. Production bodies must describe the approved domain.

package/repo-agent-governance/skills/cabloy-spec-generation/references/repo-specs-document-set.md

@@ -137,7 +137,7 @@ Every WBS entry should state:
 - primary source areas or ownership boundaries;
 - bounded tasks;
 - acceptance/completion checks;
-- linked PRD, SRS, and ATP identifiers;
+- linked PRD, SRS, and ATP identifiers where a real adjacent-authority association exists; a genuine documentary planning/release gate without an independent ATP uses the explicit `authority-only` classification and retains its SRS association and review evidence as specified in `canonical-spec-input.md`;
 - whether it is planned, implemented, or awaiting evidence.
 
 Begin with a documentation/decision implementation gate before feature work. For differing Web/Admin strategies, split shared-site integration and independent-site delivery into separate frontend tasks when their source facts, dependencies, or proof differ. An unresolved strategy or exact runtime identifier may block only the affected implementation task; preserve runnable discovery work and unaffected backend or audience work as accurately actionable. Prefer vertical, verifiable increments. Include migration and release hardening as explicit work. Keep `implementation-complete` distinct from `verified`.

package/repo-agent-governance/skills/cabloy-spec-generation/references/traceability-and-status-rules.md

@@ -47,7 +47,7 @@ Minimum cardinality for a material in-scope requirement:
 - at least one ATP scenario;
 - zero evidence records before execution, and at least one retained evidence record before `verified`.
 
-A single ATP may prove several related requirements, but the matrices must make the relationship explicit. A WBS item may cover several contracts, but it still needs bounded completion checks.
+A single ATP may prove several related requirements, but the matrices must make the relationship explicit. A WBS item may cover several contracts, but it still needs bounded completion checks. The full-chain minimum applies to material in-scope product requirements; a separately sourced engineering obligation or a documentary coordination gate need not invent a product parent or an executable ATP. Use the narrowly scoped declaration-local `Traceability exception` classifications in `canonical-spec-input.md` only for those genuine cases. The unaffected direction still needs an exact-ID link, and review/closure still needs applicable retained proof. An exception is not a deferred status, evidence waiver, acceptance result, or release approval.
 
 ## Authority-first updates
 

package/repo-agent-governance/tests/spec-audit.test.mjs

@@ -99,6 +99,176 @@ test('ordinary co-occurrence and wildcard matrices cannot manufacture traceabili
   );
 });
 
+test('technical-only SRS exempts its PRD parent, not its WBS successor', async t => {
+  const records = {
+    ...BASELINE,
+    'srs.md':
+      '# Contracts\n\n- **SRS-DEMO-01**: Test hygiene. Traceability exception: technical-only — Repository fixture policy owns cleanup.\n\nTraceability: `WBS-DEMO-10-01`\n\n- **SRS-DEMO-02**: Product contract. Traceability: `PRD-DEMO-01`, `WBS-DEMO-10-01`.\n',
+    'prd.md': BASELINE['prd.md'].replace('`SRS-DEMO-01`', '`SRS-DEMO-02`'),
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.deepEqual(result.diagnostics, []);
+  const withoutException = {
+    ...records,
+    'srs.md': records['srs.md'].replace(
+      ' Traceability exception: technical-only — Repository fixture policy owns cleanup.',
+      '',
+    ),
+  };
+  const missingParent = await auditPlanning(await fixture(t, withoutException));
+  assert.ok(
+    missingParent.diagnostics.some(
+      diagnostic => diagnostic.id === 'SRS-DEMO-01' && diagnostic.code === 'traceability-incoming',
+    ),
+  );
+  const missingSuccessor = await auditPlanning(
+    await fixture(t, {
+      ...records,
+      'srs.md': records['srs.md'].replace('Traceability: `WBS-DEMO-10-01`\n', ''),
+      'pdp-wbs.md': records['pdp-wbs.md'].replace('`SRS-DEMO-01`, ', ''),
+    }),
+  );
+  assert.ok(
+    missingSuccessor.diagnostics.some(
+      diagnostic => diagnostic.id === 'SRS-DEMO-01' && diagnostic.code === 'traceability-outgoing',
+    ),
+  );
+});
+
+test('authority-only WBS exempts its ATP successor, not its SRS parent', async t => {
+  const records = {
+    ...BASELINE,
+    'pdp-wbs.md': `${BASELINE['pdp-wbs.md']}\n#### WBS-DEMO-10-02: Review baseline\n\nTraceability exception: authority-only — Retain the baseline review disposition.\n\nTraceability: \`SRS-DEMO-01\`.\n`,
+    'progress.md': `${BASELINE['progress.md']}| WBS-DEMO-10-02 | Review | not-started |\n`,
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.deepEqual(result.diagnostics, []);
+  const withoutException = {
+    ...records,
+    'pdp-wbs.md': records['pdp-wbs.md'].replace(
+      'Traceability exception: authority-only — Retain the baseline review disposition.\n\n',
+      '',
+    ),
+  };
+  const missingSuccessor = await auditPlanning(await fixture(t, withoutException));
+  assert.ok(
+    missingSuccessor.diagnostics.some(
+      diagnostic =>
+        diagnostic.id === 'WBS-DEMO-10-02' && diagnostic.code === 'traceability-outgoing',
+    ),
+  );
+  const missingParent = await auditPlanning(
+    await fixture(t, {
+      ...records,
+      'pdp-wbs.md': records['pdp-wbs.md'].replace('Traceability: `SRS-DEMO-01`.\n', ''),
+    }),
+  );
+  assert.ok(
+    missingParent.diagnostics.some(
+      diagnostic =>
+        diagnostic.id === 'WBS-DEMO-10-02' && diagnostic.code === 'traceability-incoming',
+    ),
+  );
+});
+
+test('malformed, repeated and wrong-kind exceptions fail closed', async t => {
+  const invalid = [
+    'Traceability exception: technical-only —',
+    'Traceability exception: technical-only — !',
+    'Traceability exception: unknown — Rationale.',
+    'Traceability exception: authority-only — Rationale.',
+    'Traceability exception: technical-only — Rationale. Traceability exception: technical-only — Again.',
+  ];
+  for (const field of invalid) {
+    const records = {
+      ...BASELINE,
+      'srs.md': BASELINE['srs.md'].replace(
+        '### SRS-DEMO-01: Contract\n',
+        `- **SRS-DEMO-01**: Contract. ${field}\n`,
+      ),
+    };
+    const result = await auditPlanning(await fixture(t, records));
+    assert.ok(
+      result.diagnostics.some(diagnostic => diagnostic.code === 'traceability-exception'),
+      field,
+    );
+  }
+  const wrongWbs = {
+    ...BASELINE,
+    'pdp-wbs.md': BASELINE['pdp-wbs.md'].replace(
+      'Completion checks:',
+      'Traceability exception: technical-only — Not an SRS.\n\nCompletion checks:',
+    ),
+  };
+  assert.ok(
+    codes(await auditPlanning(await fixture(t, wrongWbs))).includes('traceability-exception'),
+  );
+});
+
+test('an exception outside its own declaration cannot exempt a missing link', async t => {
+  const records = {
+    ...BASELINE,
+    'srs.md':
+      '# Contracts\n\nTraceability exception: technical-only — Preamble.\n\n- **SRS-DEMO-02**: Unmapped contract.\n- **SRS-DEMO-01**: Contract. Traceability exception: technical-only — Different record.\n\nTraceability: `PRD-DEMO-01`, `WBS-DEMO-10-01`\n',
+    'pdp-wbs.md': `${BASELINE['pdp-wbs.md'].replace(
+      'Dependencies: none.',
+      'Dependencies: none.\n\nTraceability exception: authority-only — Phase preamble.',
+    )}\n#### WBS-DEMO-10-02: Unmapped task\n`,
+    'progress.md': `${BASELINE['progress.md']}| WBS-DEMO-10-02 | Unmapped | not-started |\n`,
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  for (const [id, code] of [
+    ['SRS-DEMO-02', 'traceability-incoming'],
+    ['WBS-DEMO-10-02', 'traceability-outgoing'],
+  ]) {
+    assert.ok(
+      result.diagnostics.some(diagnostic => diagnostic.id === id && diagnostic.code === code),
+    );
+  }
+  assert.ok(result.diagnostics.some(diagnostic => diagnostic.code === 'traceability-exception'));
+});
+
+test('classified gates retain reference and completed-prerequisite checks', async t => {
+  const records = {
+    ...BASELINE,
+    'pdp-wbs.md': `${BASELINE['pdp-wbs.md']}\n#### WBS-DEMO-10-02: Review gate\n\nDependencies: WBS-DEMO-10-01.\n\nTraceability exception: authority-only — Retain the review disposition.\n\nTraceability: \`SRS-DEMO-01\`.\n\nReview \`SRS-MISSING-01\`.\n`,
+    'progress.md': `${BASELINE['progress.md']}| WBS-DEMO-10-02 | Review | verified |\n`,
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.ok(
+    result.diagnostics.some(
+      diagnostic => diagnostic.code === 'undefined-reference' && diagnostic.id === 'SRS-MISSING-01',
+    ),
+  );
+  assert.ok(
+    result.diagnostics.some(
+      diagnostic => diagnostic.code === 'dependency-state' && diagnostic.id === 'WBS-DEMO-10-02',
+    ),
+  );
+  assert.ok(
+    !result.diagnostics.some(
+      diagnostic =>
+        diagnostic.code === 'traceability-outgoing' && diagnostic.id === 'WBS-DEMO-10-02',
+    ),
+  );
+});
+
+test('fences and comments cannot annotate a definition', async t => {
+  const records = {
+    ...BASELINE,
+    'pdp-wbs.md': `${BASELINE['pdp-wbs.md']}\n#### WBS-DEMO-10-02: Review gate\n\nTraceability: \`SRS-DEMO-01\`.\n\n\`\`\`md\nTraceability exception: authority-only — Example only.\n\`\`\`\n\n<!-- Traceability exception: authority-only — Not authority. -->\n`,
+    'progress.md': `${BASELINE['progress.md']}| WBS-DEMO-10-02 | Review | not-started |\n`,
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.ok(
+    result.diagnostics.some(
+      diagnostic =>
+        diagnostic.code === 'traceability-outgoing' && diagnostic.id === 'WBS-DEMO-10-02',
+    ),
+  );
+  assert.ok(!codes(result).includes('traceability-exception'));
+});
+
 test('lightweight records do not require absent baseline files or charts', async t => {
   const directory = await fixture(t, {
     'README.md': '# Lightweight\n',

package/repo-agent-governance/tools/spec-audit/audit.mjs

@@ -71,6 +71,46 @@ function addMapping(groups, edges, definitions) {
   }
 }
 
+function traceabilityException(definition, report, annotatedLines) {
+  const fields = markdownLines(definition.body ?? '').flatMap(({ text, line }) =>
+    Array.from(text.matchAll(/\bTraceability\s+exception\b/gi), match => ({
+      text,
+      line,
+      start: match.index,
+    })),
+  );
+  if (!fields.length) return null;
+  for (const field of fields) {
+    const line = definition.line + field.line - (definition.kind === 'WBS' ? 0 : 1);
+    annotatedLines.add(`${definition.file}:${line}`);
+  }
+  const field = fields[0];
+  const value =
+    definition.kind === 'bullet' && field.line === 1
+      ? field.text.slice(field.start).trim()
+      : field.text.trim();
+  const match = value.match(/^Traceability exception:\s*(technical-only|authority-only)\s+—\s+/i);
+  const exception = match?.[1].toLowerCase();
+  const rationale = match && value.slice(match[0].length);
+  const validOwner =
+    (exception === 'technical-only' &&
+      definition.id.startsWith('SRS-') &&
+      definition.kind === 'bullet' &&
+      field.line === 1) ||
+    (exception === 'authority-only' && definition.id.startsWith('WBS-'));
+  if (fields.length !== 1 || !validOwner || !/[\p{L}\p{N}]/u.test(rationale ?? '')) {
+    report(
+      'traceability-exception',
+      definition.file,
+      definition.line + field.line - (definition.kind === 'WBS' ? 0 : 1),
+      'Invalid Traceability exception: use one declaration-local technical-only SRS or authority-only WBS field with a rationale.',
+      definition.id,
+    );
+    return null;
+  }
+  return exception;
+}
+
 function collectMappings(records, definitions) {
   const edges = new Map(Array.from(definitions.keys(), id => [id, new Set()]));
   for (const definition of definitions.values()) {
@@ -271,8 +311,22 @@ export async function auditPlanning(
       report('declaration', file, 1, error.message);
     }
   }
+  const exceptions = new Map();
+  const annotatedLines = new Set();
+  for (const definition of definitions.values()) {
+    const exception = traceabilityException(definition, report, annotatedLines);
+    if (exception) exceptions.set(definition.id, exception);
+  }
   for (const [file, markdown] of records) {
     for (const { text, line } of markdownLines(markdown)) {
+      if (/\bTraceability\s+exception\b/i.test(text) && !annotatedLines.has(`${file}:${line}`)) {
+        report(
+          'traceability-exception',
+          file,
+          line,
+          'Traceability exception must be in its own formal declaration.',
+        );
+      }
       for (const prefix of OWNERS.keys()) {
         for (const id of findIdentifiers(referenceText(text), prefix)) {
           if (!definitions.has(id)) {
@@ -347,7 +401,7 @@ export async function auditPlanning(
     const incoming = new Set([...edges.values()].flatMap(values => [...values]));
     for (const [id, definition] of definitions) {
       if (definition.status === 'deferred' || definition.deferred) continue;
-      if (!id.startsWith('PRD-') && !incoming.has(id)) {
+      if (!id.startsWith('PRD-') && !incoming.has(id) && exceptions.get(id) !== 'technical-only') {
         report(
           'traceability-incoming',
           definition.file,
@@ -356,7 +410,11 @@ export async function auditPlanning(
           id,
         );
       }
-      if (!id.startsWith('ATP-') && !edges.get(id).size) {
+      if (
+        !id.startsWith('ATP-') &&
+        !edges.get(id).size &&
+        exceptions.get(id) !== 'authority-only'
+      ) {
         report(
           'traceability-outgoing',
           definition.file,

package/repo-docs/index.md

@@ -30,6 +30,12 @@ features:
     details: Organize capabilities for SSR, SPA, Web, and Admin applications with shared conventions.
 ---
 
+## Demonstrations(Videos)
+
+### 1. Can an Admin Site Use SSR? CabloyJS in Three Practical Demos (Duration: 1:16)
+
+[![CabloyJS Admin SSR video](./assets/img/cabloy-admin-ssr-cover-en.png)](https://youtu.be/786IQhRdr1I)
+
 ## Choose a reading path
 
 ### Start a project