Dariusz Newecki

Posted on Apr 4

I Spent a Saturday Cleaning My Own Repo. CORE Made Me.

#cli #codequality #devjournal #documentation

Not because I wanted to.

Because the system I built demands that everything it touches is defensible. And when I looked honestly at my own repository — the README, the docs, the .gitignore — they weren't.

So I fixed them.

The broken command nobody noticed

It started with a README.

The Quick Start section told anyone who cloned CORE to run:

poetry run core-admin check audit

That command doesn't exist. The correct command is:

poetry run core-admin code audit

One word difference. But anyone who followed that instruction would get an error on their very first interaction with the project. First impression: broken.

The CLI had evolved. The legacy verb-first pattern (check audit) was purged months ago when CORE's command structure was redesigned around resource-first architecture. The README hadn't kept up. It was documenting a command that no longer existed.

"If the docs lie, the system lies."

This is the thing about building a governance runtime: you can't enforce standards on AI-generated code while your own documentation ships broken commands.

CORE's entire thesis is:

Never produce software you cannot defend.

Not rhetorically. Technically, legally, epistemically, historically.

If I can't defend my own README — if the first thing someone tries doesn't work — then I'm not living by the standard I built into the system.

That's not a philosophical problem. It's a credibility problem. And a consistency problem. And those are exactly the problems CORE exists to solve.

What a Saturday of self-governance looks like

Here's what actually got done:

README:

Fixed the broken audit command (check → code)
Removed a stale metric (0 blocking violations) that may or may not have been current
Removed an acknowledgment that no longer reflected the project's direction
Replaced a buried, collapsible workflow diagram with a cleaner conceptual flow — visible immediately, no click required

CONTRIBUTING.md:

Updated the CI description (it had said "smoke testing" — it does more than that now)
Added the audit command so contributors know how to verify compliance locally before opening a PR

.gitignore:

Found that logs/* was missing — only !logs/.gitkeep existed, with no corresponding exclusion rule. Any non-.log file landing in logs/ would have been tracked silently.
Added proper logs/* and reports/* exclusions with the same pattern used for var/ and work/

docs/ — complete rewrite:

The docs site had 111 files across 30 directories, most of them written at various stages of development, not reflecting current architecture
I replaced all of it with six files: index.md, how-it-works.md, autonomy-ladder.md, getting-started.md, cli-reference.md, contributing.md
Every CLI command in the reference was verified against the actual source code — not inferred, not remembered, not guessed

That last point matters. The first draft of cli-reference.md was written by an AI assistant — from inference, not from source. I caught it, pushed back, and made it search the actual command registrations before writing anything. Same standard I apply to everything else.

The CLI reference problem is the whole problem in miniature

The first draft of cli-reference.md was written by an AI assistant — from inference, not from source.

It had wrong subcommands. Plausible ones, but wrong.

core-admin proposals inspect <id> — doesn't exist. It's show.

core-admin inspect status — legacy verb-first pattern, purged months ago. It's core-admin admin status.

core-admin governance coverage — wrong group entirely. It's core-admin constitution status.

Three wrong commands in one file. All confident. All wrong.

I caught it. Pushed back. Asked the assistant to search the actual source code before writing anything. It did. The commands got fixed.

The irony was not subtle: an AI assistant producing plausible but unverified output, in documentation for a system that exists specifically to prevent AI from producing plausible but unverified output.

That's not a documentation problem. That's an epistemic problem. And it's the same one that lives in .intent/northstar/core_northstar.md:

Nothing is assumed silently. All assumptions must be explicit, owned, and traceable. Reasoning requires citation. If CORE cannot point to evidence, it cannot act.

What this has to do with autonomy

CORE is currently at A2+ — governed generation, universal workflow pattern. I'm working toward A3 — strategic autonomy, where CORE identifies and proposes architectural improvements without being asked.

For A3 to be trustworthy, the system has to be clean. Not just the code — the whole project. The README someone reads before cloning. The docs they follow when getting started. The .gitignore that determines what gets committed.

If those are wrong, the foundation is wrong. And you can't build autonomous operation on a wrong foundation.

Cleaning the repo isn't glamorous. It doesn't advance the autonomy ladder. But it's the kind of work the system's own philosophy demands — and that I'd been quietly deferring.

The self-referential part

There's something almost uncomfortable about this.

I built a system that enforces: you cannot ship what you cannot defend. And then I had a README with a broken command, a .gitignore with a missing rule, and a documentation site with 111 files of outdated content.

The system couldn't enforce standards on its own repository — it doesn't govern Markdown files. That's a human responsibility.

Which means the human has to do it.

That's not a failure of CORE. That's the design. .intent/ is human-authored and immutable at runtime. CORE can never write to it. The constitution is mine to maintain.

The same is true for everything outside the autonomy lanes — the README, the docs, the project presentation. CORE governs the code. I govern the rest.

And today I did.