I made stale coding-agent context fail CI instead of failing silently

A coding agent with no context usually hesitates, searches, or asks a question.

A coding agent with stale context can be much more confident.

That is the dangerous case.

The file still exists. The instructions look deliberate. The generated JSON is
valid. The agent follows it exactly — into a package that stopped owning the
feature two weeks ago.

Nothing looks broken until the edit is already in the wrong place.

I wanted repository context to have an expiration signal that CI could verify,
not a date someone had to remember to check.

The failure is not missing documentation

Imagine a monorepo where packages/auth owns token validation. The repository
publishes a machine-readable handoff:

{
  "startHere": "docs/for-agents/packages/auth.md",
  "editRoots": ["packages/auth"],
  "checks": ["pnpm --filter @example/auth test"]
}

Later, token validation moves to packages/security. A maintainer updates the
source documentation but forgets to regenerate the handoff index.

There are now two internally consistent answers in the same repository:

• the source documentation says packages/security;
• the generated agent context still says packages/auth.

The old answer is not malformed. That is precisely why it is risky.

I reproduced the drift with one edit

I tested this against the public fixture in
Doc Bridge, using version 1.2.6.
The first index and freshness check passed:

Index is fresh
expected: 359355e5...
actual:   359355e5...

Then I changed one agent-facing source document:

 - Package: packages/os-core
 - Layer: L1
+
+Token validation now belongs to packages/security.

I did not touch the generated index. The next check returned exit code 1:

ak-docs gate run index-freshness

Index is stale. Run: ak-docs index
expected: b099695d...
actual:   359355e5...

After I ran ak-docs index, reviewed the generated change, and ran the gate
again, both hashes matched and the check passed.

The hashes are not trying to prove that the documentation is true. No checksum
can do that. They prove a narrower and useful fact: the committed agent context
was generated from the current configured inputs.

Why CI should not repair the evidence it is checking

There is an easy way to make every freshness check green:

- run: ak-docs index
- run: ak-docs gate run index-freshness

It is also a good way to hide the drift.

If CI rebuilds the index before checking it, the generated files in the branch
are no longer the evidence being tested. The job proves that a fresh index can
be generated in the runner. It does not prove that reviewers saw or committed
the changed routing context.

For a fail-closed pull-request check, the order should be:

1. check out the branch;
2. install the pinned tool version;
3. verify the committed index before changing it;
4. fail if the configured inputs produce a different hash.

The fix happens locally:

1. run ak-docs index;
2. inspect the diff under .doc-bridge/ and llms.txt;
3. confirm that ownership, starting documents, and checks changed intentionally;
4. commit the generated artifacts;
5. let CI verify that committed state.

Doc Bridge's GitHub Action
follows that model:

name: Documentation gate
on: [pull_request]

permissions:
  contents: read

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: AgentsKit-io/doc-bridge@v1.2.6
        with:
          config-path: doc-bridge.config.json

The Action checks committed state before rebuilding anything. A stale index
becomes a visible PR failure instead of a silent repair inside the runner.

Fresh does not mean correct

This distinction matters enough to state twice.

A fresh index can faithfully encode a bad ownership decision. A broken check
can be freshly indexed. A human guide can be current and still be unclear.

Freshness answers:

Was this generated context derived from the repository inputs we are reviewing?

It does not answer:

Are those inputs the right description of the system?

That second question still belongs in code review, architecture decisions, and
tests. The value of the gate is that reviewers are no longer evaluating an
invisible mismatch between source and generated context.

The smallest useful contract

I do not think every repository needs a giant knowledge system before it can
give agents safer context. A small deterministic contract is enough to start:

• where the agent should begin reading;
• which paths the task owns;
• which checks provide evidence;
• which human-facing document describes the same area;
• whether that contract was generated from the current inputs.

Search and RAG remain useful after that. They can find related design notes,
migrations, and call sites. But semantic relevance should not silently override
an ownership boundary the repository already knows.

My preferred sequence is:

verify freshness
  → resolve the ownership handoff
  → read the starting documents
  → search for implementation context
  → edit the declared scope
  → run the declared checks

If the ownership answer is ambiguous or the change legitimately crosses
packages, that should trigger a wider handoff or human decision. A gate should
surface uncertainty, not manufacture confidence.

What it costs

Committing generated context creates review work. Maintainers have to inspect
diffs. Tool versions need to be pinned. Ownership inputs need to be maintained.
Large documentation corpora may need caching so validation stays fast.

That cost is real.

The alternative is also a cost: agents confidently acting on context that no
longer describes the repository, with no visible signal that anything drifted.

For repositories where agents can change production code, I would rather pay
for a small, explicit diff than debug a correct implementation placed behind
the wrong boundary.

Try the failure before trusting the claim

The deterministic layer does not need a model or API key:

npm install --save-dev @agentskit/doc-bridge@1.2.6
npx ak-docs init
npx ak-docs index
npx ak-docs gate run index-freshness

Then change one configured agent document without reindexing and run the gate
again. The useful demonstration is not the green check. It is watching the
repository refuse yesterday's context.

I am Emerson Braun, the creator and maintainer of Doc Bridge, so I have an
obvious interest in the approach. The commands, fixture, gate implementation,
and tests are public. If you can make the freshness check pass while the inputs
and committed index disagree, that counterexample is more valuable than a
compliment.

Preparation disclosure: I used AI tools to help organize and critique this
draft. I ran the commands, reproduced the red-to-green gate behavior, checked
the claims against the public source, and reviewed the final text.