@projectplaceholders/context-docs

The part of the gate that checks the documentation, not the code.

pkit check                        # includes the doc checks below
pkit context stale                # how far each module has drifted from its CONTEXT.md
pkit context template module      # a starting document worth filling in

Why documentation is a build step here

An agent reads before it writes. Whatever CONTEXT.md says about a module becomes the agent's model of that module, and it will act on that model without checking it against the code. That makes a stale doc worse than a missing one: a missing doc makes the agent read the source, while a wrong doc makes it confidently build on a description of a system that no longer exists.

Nothing about that failure is visible. No test breaks, no type is wrong, no lint fires. The document simply starts lying, quietly, and keeps being trusted. So the only way it stays true is if something keeps asking.

What is checked

We cannot decide whether a paragraph is true, so we check the things that are decidable and leave the judgement where it belongs.

| Finding | Severity | Meaning | |---|---|---| | missing-context | error | A module under src/features/ has no CONTEXT.md. | | missing-section | error | The document omits a required heading (Purpose, Public API, Invariants). | | too-long | error | It has grown past 120 lines, which is past the point anyone reads it. | | stale | warning | The module has changed by more than 150 lines since the document was last touched. |

Staleness is a warning and the others are errors, and the split is deliberate. The first three are facts about a file. Staleness is an inference from churn — a large refactor that genuinely did not change the module's contract is a false positive, and a check that blocks on a guess teaches people to route around it.

Headings inside fenced code blocks do not count. Otherwise a document could satisfy the section check by quoting the template it never filled in, and the check would confirm exactly the failure it exists to catch.

How staleness is measured

For each module: find the commit that last touched its CONTEXT.md, then count the lines added and deleted in that module since — excluding the document itself, so editing the doc never counts as drift away from it.

Two things follow from that, both on purpose:

• The working tree counts, not just commits. An agent that has just rewritten a module is told now, while it still has the context to fix the doc, rather than in review.
• Updating the document resets the clock. The signal is not "this text is wrong", it is "nobody has looked at this in a while". Looking is the fix.

The one blind spot is untracked files: git cannot diff what it has never seen, so a brand new file in a module adds nothing to the count until it is staged.

Thresholds

maxLines: 120 and maxChangedLinesSinceUpdate: 150 are judgement calls, not physics. They are set where a document stops being read and where a module stops resembling its description, and they are meant to be tuned against a real codebase.