Engineering Practice Is Distributed State

During a multi-repository release, I needed to answer a basic question: was every component updated and live?

No single system could answer it. Git contained source history. Package manifests and lockfiles declared dependency state. Another repository pinned a shared module by commit. CI recorded successful builds. The deployment platform exposed the running revision. The release sequence and exceptions existed partly in documentation and partly in conversation.

The release was not one event. It was a distributed state transition:

source commit
  -> published package
  -> consumer manifest
  -> resolved lockfile
  -> shared-module revision
  -> production merge
  -> successful build
  -> observed deployed revision

Each artifact was authoritative for a different fact. A green build proved that a build completed. It did not prove that every consumer had moved, that the expected revision was deployed, or that the release process had been followed completely.

This is the technical problem behind Architekton: engineering practice is distributed across artifacts, scopes, systems, and people, but we usually inspect those sources independently.

The current public artifact is an experimental alpha, not a stable automation layer. Alpha.4 inspects that distributed evidence, supports narrowly approved guidance changes, and verifies the result while keeping those authority boundaries separate.

Effective Practice Is a Compiled View

A repository already contains parts of its engineering contract:

• package manifests and lockfiles
• test and build script declarations
• CI workflows
• ownership files
• contributor documentation
• AGENTS.md and CLAUDE.md
• architecture and engineering guidance
• release configuration

Other evidence is external: branch protection, deployment state, package registries, identity controls, and organizational policy. Some intent may remain tacit.

Architekton treats effective engineering practice as a compiled view over those sources rather than assuming one new manifest can replace them:

effective practice =
  native artifacts
  + applicable scope
  + precedence
  + provenance
  + freshness
  + explicit unknowns

Here, compiled means a reviewable interpretation of available evidence. It does not imply complete coverage or compiler-level certainty.

Native evidence

• package.json

  declares the test command

• .github/workflows/ci.yml

  runs the command in CI

• ENGINEERING.md

  states maintainer intent

• CODEOWNERS

  assigns review ownership

↓

Compiled view

Changes are tested in CI

State

pass

Scope

selected repository root

Provenance

.github/workflows/ci.yml

Unknown

hosted branch protection

Distinct outcomes, never one score

• pass
• fail
• unknown
• stale
• unsupported
• conflicting

The output should answer what appears to be true and show the basis for that conclusion:

• Which artifact supports the finding?
• At what scope does it apply?
• Is it advisory guidance, executable configuration, or observed state?
• Is the evidence current?
• Do other artifacts conflict with it?
• What could not be inspected?

Architekton preserves pass, fail, unknown, stale, unsupported, and conflicting as separate states. Collapsing them into a score would remove information that maintainers need to decide what to do next.

An unavailable hosted rule is not a pass. An unrecognized artifact is not evidence of absence. Two reasonable files that disagree are not automatically resolved by whichever one was read last.

Authority Is Part of the Model

Repository inspection has a prompt-injection and authority problem. The repository being inspected is untrusted input. A file inside it may describe commands, request credentials, or claim that it authorizes a change. Reading that content cannot grant it authority.

Architekton separates understanding practice, establishing it, maintaining it, applying it, and verifying the result. Those jobs may eventually form one product loop, but they should not share authority implicitly.

Inspection remains read-only. It discovers supported native artifacts, compiles findings with provenance and limitations, asks focused questions when material intent is missing, and does not change the selected repository.

Establishing missing guidance is a separate, guarded workflow. The current experiment covers one narrow case: proposing a root ENGINEERING.md after inspection and a complete maintainer interview.

Creation requires fresh approval of the exact target path, exact bytes, and SHA-256. The helper uses exclusive creation, syncs the approved bytes, then immediately verifies the resulting identity and hash. This detects interference visible during verification. It is not a claim of atomic publication or protection against every later change.

That workflow does not create AGENTS.md, CLAUDE.md, workflows, ownership files, security policy, or hosted controls.

Maintenance is separate and proposal-first. Existing guidance can be updated only after the target and exact change are approved. The current boundary never creates AGENTS.md or CLAUDE.md. Either file may be updated only when it already exists and the maintainer explicitly includes it in scope.

Verification is read-only again. It checks the stated intent, proposed or landed diff, semantic consistency, portability, conflicts between native artifacts, and whether a claim is supported by declared configuration, hosted state, or observed behavior. When independent assessments are unavailable, that limitation remains visible rather than being presented as independent review.

Code, workflow, and configuration remediation stays outside the maintenance workflow. Architekton can hand an exact, bounded problem to an authorized coding agent and then verify the result, but it does not turn a finding into permission to patch arbitrary repository files.

Keeping these surfaces separate prevents an inspection finding from silently becoming permission to rewrite the repository or a change from silently becoming proof that the intended outcome occurred.

The Current Step: Inspect Before Changing

The first public step makes repository practice inspectable before expanding the product's authority to change or apply it.

The core contract is language-neutral: discover native evidence, retain provenance, preserve uncertainty, and keep repository content from authorizing execution or mutation.

It currently has two ways to apply that contract.

Guided inspection

The host agent can use safe file tools to inspect relevant native artifacts. This is the path for documentation repositories, repositories containing agent capabilities, hybrid repositories, and ecosystems without a maintained deterministic adapter.

Guided inspection is progressive and non-exhaustive. It starts with the smallest relevant evidence and expands only when that evidence points elsewhere. It reports its coverage instead of implying complete understanding.

Optional deterministic adapter

The first adapter is implemented in TypeScript and compiled to a Node.js runtime. It provides bounded, repeatable discovery and structural analysis for:

• JavaScript and TypeScript package roots
• conventional agent-capability repository structures
• the structure of an ENGINEERING.md contract
• supported guidance, ownership, and GitHub workflow artifacts
• selected Dockerfile and Dependabot configuration relationships

The adapter inspects a small allowlist that includes AGENTS.md, CLAUDE.md, ENGINEERING.md, project documentation, conventional CODEOWNERS locations, package.json, JavaScript lockfiles, GitHub Actions workflows, agent-capability definitions, plugin manifests, and provider metadata.

These analyzers interpret documented structural subsets. The workflow analysis can identify bounded static patterns such as overlapping triggers, notification error masking, conditional or path-filter risk, documentation fast paths, runtime drift, and Dependabot target branches. It does not implement full GitHub Actions semantics. Finding an agent-capability declaration does not prove that the capability behaves correctly. Finding a script name does not prove that the command passes. Finding a workflow does not prove that a notification was received, a deployment occurred, or the corresponding hosted protection is enabled.

The Selected Root Is the Interpretation Boundary

Every inspection begins with one explicit repository root. Discovery must remain inside that boundary.

For a JavaScript or TypeScript package root, the deterministic adapter can interpret root package metadata, lockfiles, script names, guidance, ownership, and workflow inventory. Nested allowlisted artifacts may be inventoried, but the alpha does not compose workspace relationships or infer package-to-package behavior across a monorepo.

A nested package can be selected explicitly as the root for its own run. That produces a root-level interpretation of that package, not a composed view of the entire parent repository.

Silent root expansion changes scope and authority. A tool should not decide that a parent Git directory, workspace folder, or adjacent repository belongs to an inspection simply because it is discoverable from the filesystem.

Safe Read Is a Concrete Constraint

Read-only is not only a product label. The deterministic path enforces a bounded input model:

• do not execute repository commands, hooks, plugins, or source files
• do not follow symbolic links during discovery
• reject roots that are not directories
• bound recursion depth, traversed directory entries, supported-file count, individual file size, and total bytes read
• return partial evidence with an unsupported diagnostic when a limit truncates coverage
• avoid emitting full file contents, environment values, tokens, or command bodies
• report malformed, unreadable, ambiguous, and conflicting artifacts without guessing

These controls reduce the amount of untrusted repository data the adapter processes. They do not prove that the repository is safe, that its application code is correct, or that every parser behavior is covered.

Building Toward the Product One Boundary at a Time

The longer-term product direction extends beyond inspection:

1. Understand a repository's engineering system.
2. Expose its current practice and provenance.
3. Identify gaps and conflicts.
4. Recommend proportionate improvements.
5. Let maintainers review and accept changes.
6. Make accepted guidance usable by humans and agents.
7. Audit drift without confusing advice with enforcement.

The current release tests a narrow path through that loop: can Architekton produce a useful, attributable view of existing repository practice, support exact maintainer-approved guidance changes, and verify the result without letting one stage inherit authority from another?

Further work depends on evidence from real use. That includes better inspection across ecosystems, workspace composition, hosted-provider observation, and using accepted practice during everyday engineering work. Each authority boundary should earn the next one.

This is not stable V1 or 1.0. The alpha does not inspect application source code, execute declared commands, or perform arbitrary remediation. Its workflow analysis is bounded static evidence, not full GitHub Actions semantics or proof of hosted settings, notification receipt, deployment, or application behavior. The report schema and compatibility surface remain unstable.

What I Want to Learn

The useful question is whether a maintainer gets a more accurate and reviewable account of the engineering practice that already exists.

The current artifact is the 0.0.0-alpha.4 experimental prerelease.

If you inspect a repository with it, I am looking for concrete feedback:

• Which finding was useful or wrong?
• Which native artifact or ecosystem behavior was missed?
• Was provenance sufficient to check the conclusion?
• Did unknown, unsupported, and conflicting remain understandable?
• Was the repository unchanged after inspection?

Architekton makes engineering practice inspectable without replacing the artifacts and controls that already carry authority. The current alpha keeps that authority narrow while the evidence model is tested against real repositories.