KB Scoring System

Five dimensions scored independently, then combined into a composite.

1. Quality

Does each artifact meet its rubric? Weighted gates per artifact type.

Card Quality (max 11 points)

Gate	Weight	Pass Condition
Function coverage	2	Every non-static function in table
Line numbers	1	Match current source (+/-10 tolerance)
Call graph	2	ASCII call graph present and correct
Algorithm	2	Numbered steps describing core logic
Constants	1	All thresholds listed with actual values
Cross-references	1	Dependencies link to other cards by ID
Frontmatter	1	All required YAML fields present
No placeholders	1	No TODO/TBD/??? remaining

\[Q_\text{card} = \sum(w_i \cdot g_i) \;/\; 11\]

API Documentation Quality (max 8 points)

Applies to Doxygen (C/C++) or Sphinx (Python) depending on project-config.md -> docs_tool.

Gate	Weight	Doxygen (C/C++)	Sphinx (Python)
Coverage	3	Every non-static function has a block	Every public function/method has a docstring
Parameters	2	Every param annotated with direction	Every param has :param: + :type:
Cross-refs	1	@see links with card IDs	.. seealso:: with card IDs
Site generated	1	HTML output exists and is not stale	HTML output exists and is not stale
Call graphs	1	Caller/callee graphs render	Call graph artifacts exist

Math Quality (max 4 points)

Gate	Weight	Pass Condition
Builds	1	LaTeX compiles without errors
Card refs	1	Card IDs reference existing cards
Code refs	2	Constants/thresholds match source

Aggregation

\[Q_\text{file} = \text{mean}(\text{applicable artifact scores})\]

Missing artifacts score 0 but count toward the denominator.

\[Q_\text{total} = \text{mean}(Q_\text{file} \text{ for all IDs})\]

2. Coverage

\[C_\text{total} = 0.6 \times \overline{C_\text{file}} + 0.4 \times \overline{C_\text{func}}\]

where \(C_\text{file}\) is the fraction of applicable artifacts present per file, and \(C_\text{func}\) is the fraction of non-static functions documented.

Math applicability is configurable per category in project-config.md.

3. Consistency

Pairwise checks, each pass/fail:

Check	Description
Card-Doxy	Function purposes align with @brief
Card-Math	Constants/thresholds match
Bidirectional refs	A refs B implies B refs A
INDEX links	All links resolve to existing files
SYNCLOG	Entries match actual artifacts
Library citations	[library:{key}] refs resolve to library INDEX entries
Library integrity	Every INDEX entry has a file; every file has an entry
INDEX docs links	Docs column links resolve to existing HTML files
Card-docs call graph	Card Call Graph consistent with generated call graph

\[K_\text{total} = \frac{\text{passing checks}}{\text{total checks}}\]

4. Freshness

\[F_\text{tag} = 1 - \frac{n_\text{pending}}{n_\text{documented}}, \quad F_\text{git} = 1 - \frac{n_\text{stale}}{n_\text{documented}}\]

\[F_\text{total} = \min(F_\text{tag},\; F_\text{git})\]

Uses a 7-day staleness threshold (configurable in project-config.md).

5. Transfer

Measured by shadow validation — how well the KB enables reimplementation. See Shadow Validation for the full protocol.

Per module:

\[T_\text{module} = 0.50 \times T_\text{test} + 0.25 \times T_\text{api} + 0.25 \times T_\text{algo}\]

\[T_\text{total} = \overline{T_\text{module}}\]

Gap classification: Missing, Ambiguous, Incorrect, Implicit.

When no shadow runs exist: Transfer is excluded from the composite and the remaining four dimensions use their original weights (0.30/0.30/0.20/0.20).

Composite

\[\text{Composite} = 0.25 Q + 0.25 C + 0.15 K + 0.15 F + 0.20 T\]

Without Transfer data:

\[\text{Composite} = 0.30 Q + 0.30 C + 0.20 K + 0.20 F\]

Range	Grade
90-100%	A
75-89%	B
50-74%	C
25-49%	D
0-24%	F