Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): keep hidden-path documents out of the project problems plane (PRD-8143) (#3674)

serafin-garciaac2e02dfa6c1
diff --git a/.changeset/hidden-docs-out-of-problems-plane.md b/.changeset/hidden-docs-out-of-problems-plane.md
new file mode 100644
index 000000000..1fd959fef
--- /dev/null
+++ b/.changeset/hidden-docs-out-of-problems-plane.md
@@ -0,0 +1,7 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Link problems are no longer reported for skill documents: files in a skills folder (`.claude/skills`, `.agents/skills`, `.github/skills`, and the like) and the skill documents you open from the Skills panel. Skills routinely link to files they create only when they run, so those links were flagged as broken when nothing was wrong. This covers the Problems panel in both scopes and the link diagnostics in source mode. The unresolved-link chips the editor draws as you type, the Links panel, and `links({ kind: "dead" })` still show these targets.
+
+The exclusion is scoped to the skills folder, not to the dot directory containing it, so a document like `.github/CI_RUNBOOK.md` keeps its link findings, as do folder templates under `.ok/templates`. A skills folder you added yourself at a visible path, such as `team/skills`, is ordinary content and is still checked. Links from your other documents into a skill still validate.
diff --git a/docs/content/advanced/content-rules/overview.mdx b/docs/content/advanced/content-rules/overview.mdx
index 381852a9c..1682ca14c 100644
--- a/docs/content/advanced/content-rules/overview.mdx
+++ b/docs/content/advanced/content-rules/overview.mdx
@@ -18,6 +18,10 @@ This page covers what's the same whatever linter runs; each linter's page covers
- **This doc** — live diagnostics for the open document, in both WYSIWYG and source mode. Click a problem to jump to it: source mode lands on the exact line and column, WYSIWYG scrolls to the block it falls in.
- **Project** — an on-demand audit of every in-scope document. It runs when you first open the scope and on the refresh button — never in the background. Results group per file with error/warning totals; configuration problems (a malformed config file, a broken `extends`) surface at the top. Clicking a problem opens the offending doc at that position.
+Skill documents are excluded from link checking: files in a skills folder (`.claude/skills`, `.agents/skills`, `.github/skills`, and the like) and the skill documents you open from the Skills panel. A skill's links routinely name files it creates only when it runs, so they report as broken by construction. What goes quiet is the Problems panel in both scopes, and with it the squiggles and gutter marks the panel drives. What stays is the link styling the editor resolves on its own as you type, so a wiki link to a file the skill has not created yet still renders as unresolved, and the Links panel still lists it under Missing. In short: the skill's Problems tab reads clean while the link itself may still look broken in the text. `links({ kind: "dead" })` and `GET /api/dead-links` list them too.
+
+The exclusion is scoped to the skills folder itself, not to the dot-directory containing it, so ordinary documents that happen to live under a dot directory (`.github/CI_RUNBOOK.md`, a `.changeset` entry) keep their link findings. So do folder templates under `.ok/templates`, which you author like any document. A skills folder you added yourself at a visible path, such as `team/skills`, is ordinary content and is still checked. Links from your other documents to a skill still validate normally.
+
In both scopes, each row tags the validator that produced it in uppercase — for example `MARKDOWNLINT`, `FRONTMATTER`, or `LINKS` — next to the rule code, and a finding that repeats collapses into one row with an instance count you can expand to reach the individual lines.
The panel is also available in [single-file sessions](/docs/features/editor#open-a-single-file) (`ok <file>`).
@@ -154,7 +158,7 @@ Unlike `ok lint`, `ok audit` needs the project's server running (`ok start` or O
}
```
-Broken links are warnings by default. The project's `validation.links` setting — **Settings ▸ This project ▸ Content rules** — decides both whether they appear and at what severity: `warning` (the default), `error` to gate CI on them with `--errors-only`, or `off` to drop them from the plane entirely. Content-rule findings keep their own severities, so `--errors-only` covers both planes at once.
+Broken links are warnings by default. The project's `validation.links` setting — **Settings ▸ This project ▸ Content rules** — decides both whether they appear and at what severity: `warning` (the default), `error` to gate CI on them with `--errors-only`, or `off` to drop them from the plane entirely. Content-rule findings keep their own severities, so `--errors-only` covers both planes at once. Skill documents are the one exception: their link findings are always excluded, whatever this setting says, because a skill's links name files it creates only at runtime.
## AI agents
diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdx
index bd6ec995b..77059cf77 100644
--- a/docs/content/reference/mcp.mdx
+++ b/docs/content/reference/mcp.mdx
@@ -18,9 +18,9 @@ To point an MCP client at this server, locally or over a tunnel from another mac
| --- | --- |
| `exec` | Read-only shell (`cat`, `ls`, `grep`, `find`, `head`, `tail`, `wc`, `sort`, `uniq`, `cut`); reads return frontmatter, backlinks, recent history, and any unresolved [comments](/docs/features/comments) left on the doc. When the [frontmatter schemas](/docs/advanced/content-rules/frontmatter) plugin is on, doc and folder entries also carry `schemas: …` naming the JSON Schema files that govern them — the contract to read before writing. Fs-direct; works without the server. |
| `search` | Ranked workspace search (title boost + body BM25 + recency; same engine the cmd-K palette uses). `intent: "omnibar"` narrows to fast title/path matching (`full_text`, the default, includes the body); `scopes` filters hit kinds; `limit` caps rows (default 20, max 100). When [semantic search](/docs/reference/configuration#semantic-search) is enabled, an embeddings signal is additionally fused into `full_text` ranking (opt-in, content egress) — pass `semantic: false` to force pure-lexical. Right after boot, an empty result set with `ready: false` means the index is still building — retry after a couple of seconds rather than treating it as no matches. |
-| `links` | Wiki-link graph. `kind` selects: `backlinks`, `forward`, `dead`, `orphans`, `hubs`, or `suggest`. Accepts an array (e.g. `["dead", "orphans", "hubs"]`) to fetch several views in one call; each view nests under its own key in the response |
+| `links` | Wiki-link graph. `kind` selects: `backlinks`, `forward`, `dead`, `orphans`, `hubs`, or `suggest`. Accepts an array (e.g. `["dead", "orphans", "hubs"]`) to fetch several views in one call; each view nests under its own key in the response. `dead` is the raw graph view: unlike `audit`, it still lists unresolved links whose source is a skill document |
| `lint` | Report content-rule problems (markdownlint style rules + frontmatter schema validation) for one `document` or a whole-project audit (`path` scopes it); each finding carries `source`/`code`/`message`/`range`/`severity`, audit capped at 10 files × 10 diagnostics with accurate totals; configuration problems (e.g. a broken schema file) ride a separate `warnings` channel. Pass `fix: true` with `document` to auto-fix fixable rules in place — the fix lands through the collaborative document (attributed, live preview), not a shell edit; the rest need `edit`/`write`. Example output: [content rules overview](/docs/advanced/content-rules/overview#ai-agents) |
-| `audit` | Unified read-only validation audit: every content problem — content-rule violations (markdownlint + frontmatter schemas) **and** broken internal links — in one call, grouped by the file to fix (`path` scopes to a folder or doc). Each finding is tagged with its validator; broken links report under the source doc that contains them, at the offending line, as warnings by default (the project's `validation.links` setting can raise them to errors or hide them). Same 10 × 10 output cap as `lint`'s audit, with accurate totals. No fix shape — lint fixes go through `lint`, link repairs through `edit`/`write` |
+| `audit` | Unified read-only validation audit: every content problem — content-rule violations (markdownlint + frontmatter schemas) **and** broken internal links — in one call, grouped by the file to fix (`path` scopes to a folder or doc). Each finding is tagged with its validator; broken links report under the source doc that contains them, at the offending line, as warnings by default (the project's `validation.links` setting can raise them to errors or hide them). Skill documents are excluded from the broken-link half: a skill's links routinely name files it creates only at runtime (use `links({ kind: "dead" })` to see them; links from other documents to a skill still validate; documents that merely sit under a dot directory, such as `.github/CI_RUNBOOK.md`, keep their findings). Same 10 × 10 output cap as `lint`'s audit, with accurate totals. No fix shape — lint fixes go through `lint`, link repairs through `edit`/`write` |
| `history` | Version timeline for a `document`, `folder`, or `skill`. Each entry carries a `version` (commit SHA) you pass to `restore_version`. Filter with `kind` (`checkpoint` / `wip` / `upstream`), `author` / `excludeAuthor`, and `branch`; paginate with `limit` / `offset` (default 50, max 200). `folder: ""` selects the project-root timeline |
| `skills` | Find skills. Pass `query` to search skills.sh and return import-ready rows (`name`, `source`, installs, publisher); omit `name` to list every managed skill across Project + Global (rows carry `installed` + `hosts`); pass `name` to read one (addressed by `name`+`scope`, never by path); pass `name` + `file` to read one bundle file's text — the read path for `references/` and `scripts/` content |
| `config` | Read the effective merged config (`config({ key: "appearance.theme" })` for a sub-tree; omit `key` for the whole config) |
diff --git a/packages/app/tests/integration/audit-skill-doc-scope.test.ts b/packages/app/tests/integration/audit-skill-doc-scope.test.ts
new file mode 100644
index 000000000..3e28d9de5
--- /dev/null
+++ b/packages/app/tests/integration/audit-skill-doc-scope.test.ts
@@ -0,0 +1,103 @@
+/**
+ * Skill-bundle scoping for the unified validation plane (`GET /api/audit`),
+ * against a real server boot. The end-to-end case: a skill bundle whose
+ * relative links name artifacts it only creates at runtime, admitted by the
+ * boot-time in-place scan, projects no diagnostics, while an ordinary doc's
+ * findings survive. The gate's contract lives on `isProblemsPlaneExcludedDoc`
+ * (server `cc1-broadcast.ts`), whose closed-table unit test pins every name
+ * shape, including the dot-dir docs that deliberately keep their findings.
+ */
+
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+ type ValidationAuditResponse,
+ ValidationAuditResponseSchema,
+} from '@inkeep/open-knowledge-core';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { awaitBacklinkIndexed, createTestServer, type TestServer } from './test-harness.ts';
+
+let server: TestServer;
+let contentDir: string;
+
+const SKILL_MD = `---
+name: record-a-decision
+description: Skill bundle whose relative links name runtime artifacts.
+---
+
+# Record a decision
+
+\tThis hard-tab line trips MD010 when markdownlint runs on this file.
+
+Runtime artifact link: [example decision](decisions/0007-use-rest-api.md)
+
+Also see [[control]].
+`;
+
+beforeAll(async () => {
+ // Pre-create the contentDir so the boot-time in-place skill scan admits the
+ // bundle without depending on live re-scan timing.
+ contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-audit-skill-scope-')));
+ const skillDir = join(contentDir, '.claude', 'skills', 'record-a-decision');
+ mkdirSync(skillDir, { recursive: true });
+ writeFileSync(join(skillDir, 'SKILL.md'), SKILL_MD, 'utf-8');
+ // Control doc: an ordinary content doc with a dead link that SHOULD appear.
+ writeFileSync(
+ join(contentDir, 'control.md'),
+ '# Control\n\n\ttabbed line for MD010\n\nSee [[audit-skill-scope-ghost]].\n',
+ 'utf-8',
+ );
+ // The harness only seeds config for fresh contentDirs; this dir is
+ // caller-owned, so seed markdownlint enablement directly.
+ mkdirSync(join(contentDir, '.ok'), { recursive: true });
+ writeFileSync(
+ join(contentDir, '.ok', 'config.yml'),
+ 'contentRules:\n markdownlint:\n enabled: true\n',
+ 'utf-8',
+ );
+ server = await createTestServer({ contentDir });
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+ rmSync(contentDir, { recursive: true, force: true });
+});
+
+// Outer budget exceeds awaitBacklinkIndexed's inner timeout so the helper's
+// targeted error surfaces before the runner's generic timeout.
+const BACKLINK_SEED_TIMEOUT_MS = 45_000;
+
+describe('GET /api/audit — skill documents in the project problems plane', () => {
+ test(
+ 'skill bundle docs surface no diagnostics in the project audit plane',
+ async () => {
+ // Wait for the control doc's dead link so the plane is provably seeded.
+ await awaitBacklinkIndexed(server, 'audit-skill-scope-ghost', 'control');
+ // Precondition: the skill doc IS an admitted link-index source — proven
+ // by its own edge into the control doc — so the emptiness assertions
+ // below cannot pass vacuously. A silently de-admitted bundle would
+ // satisfy them while breaking the backlinks-keep-their-edges promise.
+ await awaitBacklinkIndexed(server, 'control', '.claude/skills/record-a-decision/SKILL');
+
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/audit`);
+ expect(res.status).toBe(200);
+ const body: ValidationAuditResponse = ValidationAuditResponseSchema.parse(await res.json());
+
+ // Control: the ordinary doc's dead link AND lint finding ARE reported —
+ // the scope gate must not overshoot into suppressing real findings.
+ const control = body.files.find((f) => f.file === 'control.md');
+ expect(control?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+ expect(control?.diagnostics.some((d) => d.code === 'MD010')).toBe(true);
+
+ // The invariant: no rows of ANY source on the skill doc. The link half is
+ // what this gate carries; the MD010-triggering tab pins that the two
+ // validators agree on scope, since the walk's own hidden-segment skip
+ // (not this gate) is what keeps markdownlint off these paths. The exact
+ // file set also catches the gate over-reaching onto other docs.
+ expect(body.files.map((f) => f.file)).toEqual(['control.md']);
+ },
+ BACKLINK_SEED_TIMEOUT_MS,
+ );
+});
diff --git a/packages/server/src/cc1-broadcast.test.ts b/packages/server/src/cc1-broadcast.test.ts
index 5121c7d56..674b03381 100644
--- a/packages/server/src/cc1-broadcast.test.ts
+++ b/packages/server/src/cc1-broadcast.test.ts
@@ -24,6 +24,7 @@ import {
isConfigDoc,
isEditableTextDoc,
isLinkIndexExcludedDoc,
+ isProblemsPlaneExcludedDoc,
isSystemDoc,
} from './cc1-broadcast.ts';
import { registerDocExtension } from './doc-extensions.ts';
@@ -613,6 +614,66 @@ describe('isLinkIndexExcludedDoc', () => {
});
});
+describe('isProblemsPlaneExcludedDoc', () => {
+ // Closed table, matching the convention its siblings follow: a doc class
+ // added to the validation plane must get a row here and in the predicate.
+
+ test('excludes skill bundles under any skills root', () => {
+ expect(isProblemsPlaneExcludedDoc('.claude/skills/record-a-decision/SKILL')).toBe(true);
+ expect(isProblemsPlaneExcludedDoc('.agents/skills/write-a-spec/references/patterns')).toBe(
+ true,
+ );
+ expect(isProblemsPlaneExcludedDoc('.github/skills/record-a-decision/SKILL')).toBe(true);
+ expect(isProblemsPlaneExcludedDoc('.ok/skills/record-a-decision/SKILL')).toBe(true);
+ // `scripts/**` members are not graph nodes, so a predicate keyed on the
+ // SKILL/references doc shapes would miss them.
+ expect(isProblemsPlaneExcludedDoc('.claude/skills/record-a-decision/scripts/notes')).toBe(true);
+ });
+
+ test('keeps admitted content that merely sits under a dot dir', () => {
+ // Scoped to the skills ROOT, never the host dotdir. Segment-matching
+ // `.github` would bury ordinary prose that is admitted content whose broken
+ // links are real defects — the discipline content-filter.ts states and pins
+ // for the sibling admission axis.
+ expect(isProblemsPlaneExcludedDoc('.github/CI_RUNBOOK')).toBe(false);
+ expect(isProblemsPlaneExcludedDoc('.changeset/wide-bug-report-dialog')).toBe(false);
+ expect(isProblemsPlaneExcludedDoc('.vscode/notes')).toBe(false);
+ expect(isProblemsPlaneExcludedDoc('.obsidian/scratch')).toBe(false);
+ });
+
+ test('excludes managed artifact names, which carry no dot segment', () => {
+ expect(isProblemsPlaneExcludedDoc('__skill__/global/record-a-decision')).toBe(true);
+ expect(
+ isProblemsPlaneExcludedDoc('__skill__/global/record-a-decision/references/patterns'),
+ ).toBe(true);
+ expect(isProblemsPlaneExcludedDoc('__extskill__/record-a-decision')).toBe(true);
+ // Inert rather than a third class: the shared managed-artifact predicate
+ // matches this tombstone prefix, but no doc is ever stored under it, so the
+ // branch never fires on a real source.
+ expect(isProblemsPlaneExcludedDoc('__template__/docs/my-template')).toBe(true);
+ });
+
+ test('keeps folder-local templates, which are authored content under a dot dir', () => {
+ // A broken link in a template is copied into every doc created from it,
+ // where it does report. Silencing the source would send the reader chasing
+ // the copies. The sibling suite above pins these as link-index sources.
+ expect(isProblemsPlaneExcludedDoc('.ok/templates/daily')).toBe(false);
+ expect(isProblemsPlaneExcludedDoc('docs/.ok/templates/meeting')).toBe(false);
+ expect(isProblemsPlaneExcludedDoc('a/b/c/.ok/templates/note')).toBe(false);
+ });
+
+ test('keeps ordinary documents, including a visible-path skills root', () => {
+ expect(isProblemsPlaneExcludedDoc('docs/getting-started')).toBe(false);
+ expect(isProblemsPlaneExcludedDoc('readme')).toBe(false);
+ // A dot INSIDE a segment is not a hidden segment.
+ expect(isProblemsPlaneExcludedDoc('notes/v1.2/release')).toBe(false);
+ // A custom root the user typed at a visible path is ordinary content. Note
+ // a GLOBAL skill installed at such a root still resolves through the
+ // managed branch above and is excluded.
+ expect(isProblemsPlaneExcludedDoc('team/skills/record-a-decision/SKILL')).toBe(false);
+ });
+});
+
describe('isEditableTextDoc', () => {
test('admits text-extension docNames and defers to a registered markdown twin', () => {
expect(isEditableTextDoc('src/util.ts')).toBe(true);
diff --git a/packages/server/src/cc1-broadcast.ts b/packages/server/src/cc1-broadcast.ts
index ad2b2249c..0225fc725 100644
--- a/packages/server/src/cc1-broadcast.ts
+++ b/packages/server/src/cc1-broadcast.ts
@@ -19,6 +19,7 @@ import {
isExcalidrawDocFile,
isManagedArtifactDocName,
isMermaidDocFile,
+ isProjectSkillBundlePath,
SYSTEM_DOC_NAME,
} from '@inkeep/open-knowledge-core';
import { isRegisteredMarkdownDocName } from './doc-extensions.ts';
@@ -153,6 +154,62 @@ export function isLinkIndexExcludedDoc(documentName: string): boolean {
return isSystemDoc(documentName) || isConfigDoc(documentName);
}
+/**
+ * True when a doc name is excluded AS A DIAGNOSTIC SOURCE from the validation
+ * problems plane (`GET /api/audit` behind the Problems panel, MCP `audit`, and
+ * the doc-scoped requests that feed the open doc's Problems tab and the
+ * source-mode link diagnostics).
+ *
+ * Skill bundles only. A skill's links routinely name runtime artifacts it
+ * creates when it runs, so they read as broken by construction and projecting
+ * them is noise. Both shapes qualify: a bundle under a skills ROOT
+ * (`.claude/skills/<name>/…`, `.github/skills/…`, `.ok/skills/…`, `scripts/**`
+ * included) and the managed live-doc names (`__skill__/…`, `__extskill__/…`).
+ * `__template__/…` matches too, through the shared managed-artifact predicate.
+ * That branch is inert rather than a third class: the prefix is a tombstone no
+ * doc is ever seeded or stored under, so it never reaches the index as a
+ * source.
+ *
+ * Scoped to the skills root, never the host dotdir — the discipline
+ * `content-filter.ts` states for the sibling axis and pins with a test:
+ * segment-matching `.github` would bury `.github/CI_RUNBOOK.md`, ordinary prose
+ * that is admitted content, body-link-indexed, and whose broken links are real
+ * defects a reader can open and fix. The same holds for `.changeset/…`,
+ * `.vscode/…`, `.obsidian/…`, and folder-local templates
+ * (`<folder>/.ok/templates/<name>`), all of which keep their findings. A dot in
+ * the path is not the question; being a skill bundle is.
+ *
+ * The lint and OKF validators reach a similar scope by a different route (their
+ * walk skips hidden segments outright), so the two planes do not agree
+ * name-for-name: `.github/CI_RUNBOOK` gets link findings but no markdownlint
+ * rows. That asymmetry is inherited, not introduced here.
+ *
+ * A skills root at a VISIBLE path (a custom root such as `team/skills/…`) keeps
+ * its findings, since nothing marks it as OK-managed. A GLOBAL skill installed
+ * at such a root is still excluded, through the managed branch.
+ *
+ * On write/edit responses, `brokenLinks` is a byte scan
+ * (`write-advisory-links.ts`) that never consults this gate. The channel that
+ * does is `warnings[kind='lint-violation']` (`computeLintViolations`), pre-gated
+ * only on `isLinkIndexExcludedDoc`: a dot-segment name cannot reach it (the
+ * write schema applies `validateDocName`), but the managed prefixes pass that
+ * schema and ARE suppressed there.
+ *
+ * Excluded docs stay link-indexed — backlinks, the graph, and rename
+ * propagation keep their edges. The gate keys on the SOURCE doc only: an
+ * ordinary doc's dead link whose TARGET names a skill still reports. The raw
+ * graph view (`GET /api/dead-links`, MCP `links({ kind: "dead" })`)
+ * deliberately stays un-gated — each derived view owns its own scope, and it is
+ * where unresolved links from these sources remain visible.
+ *
+ * The call sites are the links validator's projection loops in
+ * `lint/validation-audit.ts`; a future validator projecting index-derived
+ * findings needs the same gate.
+ */
+export function isProblemsPlaneExcludedDoc(documentName: string): boolean {
+ return isProjectSkillBundlePath(documentName) || isManagedArtifactDocName(documentName);
+}
+
/**
* True when a doc name is excluded from the markdown L1 store spine
* (`storeDocumentNow`) because its persistence flows through a dedicated
diff --git a/packages/server/src/lint/validation-audit.test.ts b/packages/server/src/lint/validation-audit.test.ts
index 5cba46b68..e6c801c3d 100644
--- a/packages/server/src/lint/validation-audit.test.ts
+++ b/packages/server/src/lint/validation-audit.test.ts
@@ -837,3 +837,217 @@ describe('toValidationCountsPlane', () => {
});
});
});
+
+describe('skill-bundle doc scoping', () => {
+ // The gate's contract — what it covers and its recorded boundaries — is
+ // `isProblemsPlaneExcludedDoc`'s JSDoc (`cc1-broadcast.ts`), with the closed
+ // name table in `cc1-broadcast.test.ts`. These tests pin the shapes end to
+ // end through the validator: bundles under a skills root (`scripts/**`
+ // included) and the managed aliases, plus the boundaries — source-keyed only,
+ // doc scope included, raw graph view un-gated, and both a visible-path skills
+ // root and a dot-dir doc outside any skills root still reported.
+
+ const LIVE_SKILL_MD =
+ '# Live skill\n\nSee [[live-skill-ghost]] and [artifact](artifacts/output.md).\n';
+
+ /**
+ * Index a live skill doc (`__skill__/global/...` managed artifact or
+ * `__extskill__/...` editable-unmanaged external): live-indexed, never on
+ * disk at a content-root path.
+ *
+ * The markdown link in the seeded body is load-bearing, not redundant with
+ * the wiki link: `BacklinkIndex` registers these docs node-only and never
+ * ingests their body links, so the graph plane carries nothing for them and
+ * the local-target plane is the only one that can produce a finding.
+ */
+ function seedLiveSkillDoc(docName: string): void {
+ index.updateDocumentFromMarkdown(docName, LIVE_SKILL_MD);
+ localTargets.setSource(docName, LIVE_SKILL_MD);
+ admitted.add(docName);
+ }
+
+ test('project skill bundle docs project no findings into the plane', async () => {
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+ // Both link forms the validator projects: a wiki dead link (graph plane)
+ // and a relative markdown link to an absent file (local-target plane).
+ seedDoc(
+ '.claude/skills/record-a-decision/SKILL',
+ '# Record a decision\n\nSee [[skill-ghost]] and [artifact](decisions/0007-use-rest-api.md).\n',
+ );
+ seedDoc(
+ '.claude/skills/record-a-decision/references/patterns',
+ '# Patterns\n\nSee [[skill-ref-ghost]].\n',
+ );
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ // Control: the ordinary doc's dead link survives the gate. The exact file
+ // set additionally catches an over-broad predicate reaching other docs.
+ const control = result.files.find((f) => f.file === 'control.md');
+ expect(control?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+
+ expect(result.files.map((f) => f.file)).toEqual(['control.md']);
+ });
+
+ test('global skill bundle docs project no findings into the plane', async () => {
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+ seedLiveSkillDoc('__skill__/global/record-a-decision');
+ seedLiveSkillDoc('__skill__/global/record-a-decision/references/patterns');
+
+ // Positive control. The graph plane cannot carry these: `BacklinkIndex`
+ // registers global skill bundle docs node-only and never ingests their body
+ // links, so the wiki link contributes no edge and only the local-target
+ // plane can produce a finding here. Prove it holds one, or the emptiness
+ // assertion below would pass against a source that never had anything.
+ const assessed = await localTargets.getAssessmentsForSources([
+ '__skill__/global/record-a-decision',
+ ]);
+ expect(
+ assessed.some(({ assessments }) => assessments.some((a) => a.status === 'missing')),
+ ).toBe(true);
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const control = result.files.find((f) => f.file === 'control.md');
+ expect(control?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+
+ expect(result.files.map((f) => f.file)).toEqual(['control.md']);
+ });
+
+ test('project skill bundle scripts docs project no findings into the plane', async () => {
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+ // `scripts/**` members are not graph nodes, so a predicate keyed on the
+ // SKILL/references doc shapes would miss them. The gate matches the whole
+ // bundle dir under the skills root, so they are covered.
+ seedDoc(
+ '.claude/skills/record-a-decision/scripts/notes',
+ '# Notes\n\nSee [[skill-script-ghost]] and [artifact](fixtures/sample-output.md).\n',
+ );
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const control = result.files.find((f) => f.file === 'control.md');
+ expect(control?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+
+ expect(result.files.map((f) => f.file)).toEqual(['control.md']);
+ });
+
+ test('external skill live docs project no findings into the plane', async () => {
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+ seedLiveSkillDoc('__extskill__/record-a-decision');
+ seedLiveSkillDoc('__extskill__/record-a-decision/references/patterns');
+
+ // Positive control, as in the global-skill case above: prove the plane that
+ // can carry a finding for this shape actually holds one.
+ const assessed = await localTargets.getAssessmentsForSources([
+ '__extskill__/record-a-decision',
+ ]);
+ expect(
+ assessed.some(({ assessments }) => assessments.some((a) => a.status === 'missing')),
+ ).toBe(true);
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const control = result.files.find((f) => f.file === 'control.md');
+ expect(control?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+
+ expect(result.files.map((f) => f.file)).toEqual(['control.md']);
+ });
+
+ test('doc-scoped audit of a skill bundle file also answers empty', async () => {
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+ seedDoc(
+ '.claude/skills/record-a-decision/SKILL',
+ '# Record a decision\n\nSee [[skill-ghost]] and [artifact](decisions/0007-use-rest-api.md).\n',
+ );
+
+ // The exclusion is total across scopes: the open doc's Problems tab and
+ // the source-mode link diagnostics ride this same doc-scoped request, so
+ // scoping to the file itself must not reintroduce what the project scope
+ // withholds.
+ const result = await runValidationAudit(createProjectValidators(deps()), {
+ targetPath: '.claude/skills/record-a-decision/SKILL.md',
+ });
+
+ expect(result.files).toEqual([]);
+ });
+
+ test('folder templates keep their link findings', async () => {
+ // Templates sit under `.ok/` but are not a skill bundle, so the gate never
+ // reaches them. Pinned through the projection loops, not just the
+ // predicate: an inverted `continue` guard would suppress them while the
+ // name-level unit test stayed green. A broken link here is copied into
+ // every doc created from the template.
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+ seedDoc('.ok/templates/daily', '# Daily\n\nSee [[template-ghost]].\n');
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const template = result.files.find((f) => f.file === '.ok/templates/daily.md');
+ expect(template?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+ });
+
+ test('a dot-dir doc outside any skills root keeps its link findings', async () => {
+ // The gate is scoped to the skills root, not the host dotdir. Prose like
+ // `.github/CI_RUNBOOK` is admitted content whose broken links are real
+ // defects, so it stays in the plane. Note the lint walk skips it on its own
+ // axis, so this doc gets link findings but no markdownlint rows.
+ seedDoc('control', '# Control\n\nSee [[ghost]].\n');
+ seedDoc('.github/CI_RUNBOOK', '# Runbook\n\nSee [[runbook-ghost]].\n');
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const runbook = result.files.find((f) => f.file === '.github/CI_RUNBOOK.md');
+ expect(runbook?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+ const control = result.files.find((f) => f.file === 'control.md');
+ expect(control?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+ });
+
+ test('a skill bundle at a visible custom root stays in the plane', async () => {
+ // A custom skill root need not be dot-rooted. Such bundles are addressable
+ // and read as ordinary content on every sibling axis (file-tree rows,
+ // hidden-doc classification), so the plane keeps their findings — the rule
+ // holding at its boundary, not an uncovered case.
+ seedDoc('team/skills/record-a-decision/SKILL', '# Custom root\n\nSee [[custom-root-ghost]].\n');
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const skill = result.files.find((f) => f.file === 'team/skills/record-a-decision/SKILL.md');
+ expect(skill?.diagnostics.some((d) => d.code === 'dead-link')).toBe(true);
+ });
+
+ test('dead links from an ordinary doc INTO a skill bundle are still reported', async () => {
+ // The gate keys on the SOURCE doc. A user-authored doc whose broken link
+ // NAMES a skill path is an ordinary finding and must survive — common
+ // right after a skill is renamed or uninstalled.
+ seedDoc(
+ 'control',
+ '# Control\n\nWiki: [[.claude/skills/absent/SKILL]]\n\nMd: [skill](.claude/skills/absent/SKILL.md)\n',
+ );
+
+ const result = await runValidationAudit(createProjectValidators(deps()));
+
+ const control = result.files.find((f) => f.file === 'control.md');
+ expect(control?.diagnostics.filter((d) => d.code === 'dead-link').length).toBeGreaterThan(0);
+ });
+
+ test('the raw graph dead-links view keeps skill-bundle sources the plane suppresses', async () => {
+ seedDoc(
+ '.claude/skills/record-a-decision/SKILL',
+ '# Record a decision\n\nSee [[skill-ghost]].\n',
+ );
+
+ // The gate lives at the validator's projection point, not in the index:
+ // `GET /api/dead-links` / MCP `links({ kind: "dead" })` stay the raw graph
+ // view over every indexed edge, hidden sources included.
+ const raw = await index.getDeadLinks([...admitted]);
+ expect(
+ raw.some(({ sources }) =>
+ sources.some((o) => o.source === '.claude/skills/record-a-decision/SKILL'),
+ ),
+ ).toBe(true);
+
+ const plane = await runValidationAudit(createProjectValidators(deps()));
+ expect(plane.files).toEqual([]);
+ });
+});
diff --git a/packages/server/src/lint/validation-audit.ts b/packages/server/src/lint/validation-audit.ts
index 54e50006b..e06cb2d1a 100644
--- a/packages/server/src/lint/validation-audit.ts
+++ b/packages/server/src/lint/validation-audit.ts
@@ -19,6 +19,7 @@ import {
type ValidationDiagnostic,
type ValidationDocCounts,
} from '@inkeep/open-knowledge-core';
+import { isProblemsPlaneExcludedDoc } from '../cc1-broadcast.ts';
import type { DerivedDocumentIndexApiPort } from '../derived-document-index.ts';
import {
buildLocalTargetEvidence,
@@ -294,6 +295,7 @@ function createLinksValidator(deps: ValidationAuditDeps): ProjectValidator {
const assessed =
await deps.derivedDocumentIndex.getLocalTargetAssessmentsForSources(sourceFilter);
for (const { source, assessments } of assessed) {
+ if (isProblemsPlaneExcludedDoc(source)) continue;
const file = deps.docFilePathFor(source) ?? `${source}.md`;
for (const assessment of assessments) {
const diagnostic = toLocalTargetDiagnostic(assessment, severity);
@@ -326,6 +328,7 @@ function createLinksValidator(deps: ValidationAuditDeps): ProjectValidator {
for (const { target, sources } of deadLinks) {
for (const occurrence of sources) {
+ if (isProblemsPlaneExcludedDoc(occurrence.source)) continue;
const key = `${occurrence.source}\0${target}`;
// Already reported with richer evidence by the canonical classifier,
// or proven by it to exist and therefore not a dead link at all.