Evidence and plan versus actual

Choose planned targets before implementation, then record changes as work lands. Planned and recorded changes are available on every plan. Linked GitHub pull requests and checks require Business or Enterprise and evidence tracking, which is off by default.

Set planned changes

Use Planned changes to select catalog objects, architecture documents and proposed objects. These targets describe the intended scope. A proposed object stays a proposal until a person accepts it into the catalog or it is dropped.

The Spec records what must be true; the Implementation plan describes how to get there. A planned target belongs to that intent, even when you later decide it needs no implementation change.

Record what changes

In Recorded changes, select Record a change, choose an object or document and choose Created, Updated or Removed. Add a note explaining what changed. Over MCP, use record_architecture_change with the target, change kind and optional note.

Recorded changes keep the person who recorded them, or the agent attribution with its client name and operator. An agent report is not verification or approval. Check the underlying work before treating a report as evidence of correctness.

Read plan versus actual

“Not changed” means no recorded change exists yet. A missing recorded change never implies missing implementation. Ask whether the work needs recording, the plan changed or the target needs no change. Treat the row as a prompt to ask, never as a finding that nothing was implemented.

Link pull requests and inspect checks

On Business or Enterprise, an administrator enables Evidence tracking in Settings > Design docs. Connect GitHub, then add a pull request URL to the design doc or use link_pull_request over MCP. The record shows the linked PR's state and check results.

Connector evidence keeps its source and scope: repository, pull request, commit and check. A merged PR establishes merge state; a passing check establishes that check's reported result on its commit. A closed issue establishes an issue state. None establishes that a deployment is correct. ArchDocs does not infer that you linked every relevant PR.

Ready to ship means evidence tracking is on, the doc is active and unshipped, at least one PR is linked and all linked PRs are merged. It is a prompt to review the record. Required variations, open-question policy and acceptance criteria still have their own ship gates.

Record the outcome and ship

For acceptance criteria: Early access. Email hello@archdocs.io to turn it on for your organization.

Write Evidence of work with the outcome, checks, deviations and unfinished work. This variation is optional by default. Its text records your account of what landed; it does not turn that account into verified evidence.

Select Mark shipped and review the dialog. You can record shipping manually when PR status is unavailable, subject to your organization's gates. The default open-question policy is Warn, which requires acknowledgement if questions remain. With approvals off, you can ship from Draft; Free uses readiness tracking without human approval requirements.

If early-access acceptance criteria block shipping, a person with verification:manage can select Ship anyway, with an exception, give a reason and select Mark shipped with exception. This records an exception for the reviewed results and commits. It does not change criterion results or bypass required variations and blocked open questions. Agents cannot ship with an exception.

Shipping freezes planned changes, recorded changes and PR membership. Linked PR state and checks can still update. Work logs continue after shipping. Implemented code and a Shipped record do not establish general availability.