kb-lint

Files (1)

• SKILL.md

SKILL.md (first lines)

# Knowledge Base Lint

Periodic health-check for the project's knowledge base. This is the **lint** operation in the three-operations model (ingest / query / lint), adopted from Karpathy's LLM Wiki gist.

The staleness check that runs in environment validation catches one kind of drift (file changed since last index). Lint catches the other kinds: logical drift, orphan accumulation, missing concepts, contradictions, gaps. Both are needed.

## Arguments

Optional `--scope <pattern>` to limit lint to a subset of library files. Default is the entire library.

Optional `--strict-layer` to fail with a non-zero exit when any library file has a missing or invalid `layer:` frontmatter field. Without this flag, layer violations are reported as warnings only in the Layer Compliance section.

Optional `--strict-confidence` to fail with a non-zero exit when any library file has a missing or invalid `confidence:` field. Without this flag, confidence violations are reported as warnings in the Layer Compliance section.

Optional `--auto-fix` to run the mechanical frontmatter fixer (`kb_lint_fix.py`) before lint. Auto-fix adds missing `layer:`, `confidence:`, and `cross_references:` fields with safe defaults, and creates stub frontmatter (with `confidence: low`, `status: draft`) for files that have no frontmatter at all. After fixing, the shelf-index is rebuilt before lint proceeds.

Examples:
- `--scope dora-*.md` — lint only DORA-related files
- `--scope library/architecture/*.md` — lint a sub-directory
- `--strict-layer` — enforce layer compliance (used by this repo's CI)
- `--strict-layer --scope *.md` — combine both
- `--strict-confidence` — enforce confidence compliance
- `--auto-fix --strict-layer --strict-confidence` — fix mechanics, then enforce both
- (no argument) — lint everything, warnings only

## Preflight

- Verify the knowledge base is configured.
- Verify the shelf-index is fresh: invoke `kb-rebuild-indexes` first if any library files are newer than the index. (The lint output is only meaningful against an up-to-date index.)
- Verify there are at least 3 library files. Linting an empty or near-empty library is not useful.

## Steps

### -1. Auto-fix mechanical issues (only when --auto-fix is passed)

If `--auto-fix` was passed, run the mechanical fixer before any other step:

```bash
python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts', INIT,
        submodule_search_locations=[SCRIPTS])
    if spec and spec.loader:
        mod = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = mod
        spec.loader.exec_module(mod)
from sdlc_knowledge_base_scripts.kb_lint_fix import fix_missing_fields
from pathlib import Path
result = fix_missing_fields(Path('<library_path>'))
print(f'Auto-fix: {result.files_fixed} file(s) fixed, {result.fields_added} field(s) added')
if result.errors:
    print(f'Errors: {result.errors}')
"
```

Replace `<library_path>` with the resolved library path from the KB config.

After fixing, run `kb-rebuild-indexes` to update the shelf-index before proceeding to Step 0.

If `--auto-fix` was NOT passed, skip this step entirely.

### 0. Layer compliance check (always runs)

Run the pure-Python layer compliance check:

```bash
python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts', INIT,
        submodule_search_locations=[SCRIPTS])
    if spec and spec.loader:
        mod = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = mod
        spec.loader.exec_module(mod)
from sdlc_knowledge_base_scripts.kb_config import allowed_layers, check_layer_compliance
from pathlib import Path
layers = allowed_layers(Path('.'))
violations = check_layer_compliance(Path('<library_path>'), layers)
if violations:
    for path, msg in violations:
        print(f'  {path}: {msg}')
    sys.exit(1)
else:
    sys.exit(0)
"
```

Replace `<library_path>` with the resolved library path from the KB config.

If this exits non-zero **AND** `--strict-layer` was passed: stop and report the Layer Compliance violations. Do not proceed to Step 1. Exit non-zero.

If this exits non-zero but `--strict-layer` was NOT passed: record the violations as warnings and continue to Step 1 — include them in the "Layer Compliance" section of the lint report.

If this exits zero: no layer issues. Continue to Step 1.

Also run confidence compliance in the same Step 0 pass:

```bash
python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts', INIT,
        submodule_search_locations=[SCRIPTS])
    if spec and spec.loader:
        mod = importlib.util.module_from_spec(spec)

From SteveGJones/ai-first-sdlc-practices, MIT.

More from SteveGJones/ai-first-sdlc-practices