Working thesis · July 2026

What should an agent understand before it changes a repository?

Repository structure is evidence — not the same thing as intent. Putnami is exploring the layer that keeps those two distinct, and makes both usable by agents before they act.

The question

Repeated session-level discovery does not scale with how often repositories change.

A coding agent can grep every file and still misunderstand the system. Search finds text — not why a boundary exists, what a team already tried, or which tradeoffs were accepted on purpose. That understanding is rebuilt, imperfectly, inside every session, worktree, and agent, then disappears when the session ends.

The research question is not how to retrieve code faster. It is which parts of that understanding a repository can carry on its own, and which parts need a human to state once, explicitly, so they stop being rediscovered.

Two boundaries

Evidence has a boundary.

What a repository can establish

modules and boundaries
dependencies
ownership declarations
build and test commands
current configuration
revision-specific history

What it cannot establish alone

why a boundary exists
current business goals
acceptable risk
temporary exceptions
operational consequences not represented in code
who is accountable for a decision

The autonomy contract

Autonomy is granted inside a contract, not assumed from a prompt.

Clarify the goal
State what should change and why, in terms a senior engineer on the team would recognize — not a ticket paraphrase.
Challenge assumptions and alternatives
A senior agent should be able to ask why this approach over another before committing, the same way a senior engineer would.
Agree on intent, constraints and checks
Fix what must not change, what tradeoffs are acceptable, and which checks would prove the result safe.
Grant implementation autonomy
Once the contract is set, the agent works inside it without re-asking permission for every choice it already covers.
Verify the resulting change
Run the checks the contract named — not a fresh, ad hoc judgment call about whether the change looks fine.
Return evidence, not reassurance
Show source, revision, and check results. A confident paragraph is not a substitute for something a reader can inspect.

Evidence inspector · Working model

Select a statement. See how it would be classified.

This is an illustrative example drawn from Putnami's own repository, not a live query. It demonstrates the distinction the working model is built to keep, not a finished product feature.

Fact: A deterministic observation from code, config, or Git — parser or checker output.
Claim: A statement of intended truth from docs, ADRs, or team knowledge — pending verification.
Check: A reproducible verifier comparing a claim or contract against current facts.
Source: The exact file, symbol, commit, or artifact backing a fact or a check.
Revision: The commit or working-tree state the answer is scoped to.

`config/libs/core/apis/configs.go` registers the `/api/configs/resolve` route.
Fact
Extracted deterministically by parsing route registration in the Go source — no interpretation involved.
The config library README says it is the only package that mounts config HTTP routes.
Claim
A human-authored statement of intent. Useful, but unverified until a checker compares it against the code.
No other package in the workspace registers a `/api/configs/*` route.
Check
A deterministic comparison between the claim above and the full set of extracted route facts — it can pass or fail.
`config/libs/core/schema/openapi.json`
Source
The generated artifact cited as evidence for both the fact and the check result.
Indexed at a specific commit, working tree unchanged since.
Revision
The exact state every fact and check above is scoped to — so a reader knows how fresh the answer is.

One concrete change · Illustrative example

A real task from Putnami's own design record, walked through.

This is drawn from Putnami-cloud's own internal design notes for dogfooding this exact question — not a customer deployment, and not a claim that the full flow runs end to end today.

The requested goal: Review whether the cloud CLI login command still matches the identity docs.
Repository facts discovered: `surfaces/workloads/cli/internal/cloudcli/cli.go` registers `cloud login` and orchestrates the flow; `identity/libs/cli/login.go` performs the device-code exchange against the auth server.
Missing human intent: Whether `identity/doc/device-code-flow.md` still describes the endpoints `login.go` actually calls was unchecked — a claim, not a verified fact, and the gap a human needs to close before trusting the answer.
The proposed contract: Confirm the documented flow against the code path, and flag — rather than silently assume — anywhere the two have drifted.
Implementation freedom: Inside that contract, the agent reads the exact cited lines, compares them to the doc, and drafts the fix without re-confirming each file it opens.
Checks used afterward: The doc/module existence and broken-link checks re-run against the changed files.
Evidence returned: The specific lines compared, the index revision they were read at, and which check passed — not a summary claiming the docs are "up to date now."

Where this model may be wrong

Open questions, stated plainly.

Which intent belongs in Git?
What should remain in external systems?
When does extracted repository knowledge become stale?
Which checks actually earn more autonomy?
What context should never be persisted?
Where does repository intelligence end and observability begin?

Invitation

This is a working model, not a product announcement.

Working with coding agents in real repositories? I'm comparing how experienced teams establish intent, constraints, and trust before delegating changes. If this model matches—or contradicts—your experience, I'd like to compare notes.

Compare notes with me