📖 [Docs]: Framework guidance now supports safe agentic delivery

bootstrap/AGENTS.template.md

@@ -148,6 +148,19 @@ In a repository, its root `AGENTS.md` names the host and organization and lists
 
 Clear task language may shortcut the index trail: `Review this PR <link>` enters Review, `Make this issue <description>` enters Define, and `Implement <issue>` enters Implement. The linked documentation owns each procedure; this file does not define a separate agent or skill.
 
+## Interactions
+
+Some phrases operate on the session rather than on the work, and each one resolves to a procedure defined in the canonical Ways of Working:
+
+| Phrase | Means |
+| --- | --- |
+| `wrap up` | The session is ending — scan for untracked work and land each item in its proper artifact. |
+| `park` | Move a tangent into an issue in the repository that owns it, then resume the original task. |
+| `triage` | Classify and route an item without starting implementation. |
+| `handoff` | Bring the artifacts to a state another participant can resume from. |
+
+Read `Ways-of-Working/Session-Interactions.md` in the canonical docs for what each one does. This table is a route, not a definition.
+
 ## Work in the selected repository
 
 1. Read its `README.md` to understand the repository and its build.

src/docs/Capabilities/agentic-development/advisory-agents.md

@@ -0,0 +1,107 @@
+---
+title: Advisory Agents
+description: The pattern for automation that analyses work and publishes its conclusion as advice, without deciding, relabelling, or committing.
+---
+
+# Advisory Agents
+
+Some useful automation produces a **judgement** rather than a change: whether a pull request
+looks ready, whether a specification covers its requirements, whether a change carries risk
+its description does not mention. The judgement is worth having and cannot be expressed as a
+passing or failing check, because it is not a fact — it is an opinion, and opinions can be
+wrong.
+
+The advisory pattern exists so that such automation can be useful without becoming
+authoritative.
+
+## Advice, not authority
+
+An advisory agent MUST publish its conclusion as advice and MUST NOT be the thing that
+decides.
+
+Concretely, it MUST NOT:
+
+- Commit to the branch it is advising on.
+- Merge, close, or approve the artifact it is advising on.
+- Overwrite a decision a human has recorded.
+- Re-apply a decision a human has changed.
+
+The last two are the ones that get violated by accident. An agent that sets a label on every
+run will faithfully undo the maintainer who corrected it, and it will do so without malice
+and without noticing. From the maintainer's side, the correction simply does not stick, and
+the reasonable conclusion is that the automation is broken and should be turned off.
+
+So the constraint is behavioural, not just permissive: it is not enough that a human *can*
+override the agent. Overriding it MUST be final.
+
+## Seed once, never relabel
+
+Where an advisory agent expresses its conclusion as a label, it MUST apply that label only
+when no label from the same set is present, and MUST leave the set alone thereafter.
+
+This gives the agent exactly one turn to speak. It supplies an initial assessment when there
+is none — which is the case where the automation adds most, because the alternative is
+nothing — and from then on the field belongs to whoever curates it.
+
+The rule is what makes the agent safe to run repeatedly. Combined with idempotence, it means a
+re-run on an artifact a human has since touched changes nothing at all.
+
+## Idempotent by construction
+
+An advisory agent MUST be safe to run repeatedly on the same artifact.
+
+It will be: events fire more than once, workflows are re-run, and an artifact under active
+review is re-examined many times. An agent whose output accumulates turns a busy pull request
+into an unreadable one, and the noise costs more than the advice is worth.
+
+In practice that means an agent updates its previous conclusion in place rather than adding a
+new one, and says nothing when it has nothing new to say. Silence at steady state is a
+feature.
+
+## Triggering late
+
+An advisory agent SHOULD trigger when work is declared ready rather than on every change.
+
+Advice on unfinished work is mostly advice about the unfinished parts, and a contributor
+learns to ignore it — after which the one useful comment is ignored too. Waiting until the
+author says the work is ready both makes the advice relevant and makes it clear what it is
+about.
+
+Where an agent must run earlier, it SHOULD scope its advice to what is stable, and MUST NOT
+present provisional findings as conclusions.
+
+## Advice is legible
+
+An advisory agent's output MUST make clear what it is: which agent produced it, what it
+examined, and that it is advice rather than a gate.
+
+An unattributed conclusion is indistinguishable from a requirement, and a reviewer who cannot
+tell the difference either treats optional advice as blocking or treats a real constraint as
+optional. Naming the source also makes the agent's own failures diagnosable: advice that is
+consistently wrong is a fixable bug in the agent, but only if it is traceable to the agent.
+
+Where advice rests on a rule, it MUST cite the documentation that carries the rule, so the
+reviewer can check the rule rather than trusting the agent's summary of it. An agent MUST NOT
+introduce a requirement that no documentation states — if the rule is real it belongs in
+documentation, and if it is not, the agent is inventing policy.
+
+## Composition
+
+Several advisory agents MAY examine the same artifact, and MUST NOT depend on each other's
+output or on the order in which they run.
+
+Independence is what keeps them cheap to add and remove. A chain of advisors is a pipeline
+with failure modes, and a pipeline whose stages are opinions has failure modes nobody can
+debug.
+
+Where two advisors disagree, both conclusions stand and the human resolves them. That is not
+a defect in the design; disagreement between two opinions is information, and suppressing it
+would mean picking a winner arbitrarily.
+
+## Where this connects
+
+- [Spec](spec.md#requirements) — the requirement that advice and authority are separate.
+- [Agent Interaction](agent-interaction.md) — the artifacts an advisory agent publishes onto.
+- [Automation Labels](../../Ways-of-Working/Automation-Labels.md) — label ownership, which is what makes seed-once enforceable.
+- [Review Etiquette](../../Ways-of-Working/Review-Etiquette.md) — the human review the advice feeds into.
+- [AI-First Development](../../Ways-of-Working/Principles/AI-First-Development.md#4-eyes-or-n-eyes-principle) — why an automated reviewer adds eyes rather than replacing them.

src/docs/Capabilities/agentic-development/agent-interaction.md

@@ -0,0 +1,111 @@
+---
+title: Agent Interaction
+description: How humans and agents coordinate through issues, labels, and pull requests, and why intent and implementation are kept in separate artifacts.
+---
+
+# Agent Interaction
+
+Once more than one participant works a repository — several people, several agents, or a mix
+— they need somewhere to coordinate. The tempting answer is a conversation: a chat, a thread,
+a prompt history. The problem with a conversation is that it is not part of the repository.
+It cannot be reviewed, it cannot be queried, and it disappears when the session does.
+
+The platform already provides durable coordination artifacts. This page states how the
+framework uses them.
+
+## Coordination happens on artifacts
+
+All coordination between humans and agents MUST happen through platform artifacts — issues,
+labels, and pull requests — rather than through any channel that leaves no trace in the
+repository.
+
+The rule follows from
+[everything as code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code):
+if the decision is not in the repository, the repository does not record why it looks the way
+it does. It also follows from practical asymmetry — an agent's session ends and takes its
+context with it, while an issue persists and can be picked up by a different agent, a
+different runtime, or a person, weeks later.
+
+| Artifact | What it carries | Why it, specifically |
+| --- | --- | --- |
+| **Issue** | The intent: what is wanted, why, and what "done" means | Durable, addressable, and independent of who acts on it |
+| **Label** | A discrete decision or state transition | Machine-readable, so automation can react without parsing prose |
+| **Pull request** | The proposed implementation, and the negotiation over it | Reviewable line by line, and revertible as one unit |
+| **Comment** | Reasoning, questions, and advice attached to its subject | Stays with the artifact it concerns rather than in a separate stream |
+
+## Two artifacts, two questions
+
+Intent MUST be recorded separately from implementation. The issue states *what* is wanted and
+*why*; the pull request proposes *how*.
+
+The separation earns its keep at rejection. When a single artifact holds both, discarding a
+bad implementation discards the reasoning that motivated it, and the next attempt starts from
+nothing. When they are separate, the pull request closes and the issue stands — still stating
+what is needed, now with a documented approach that did not work.
+
+It also puts each question in front of the right reviewer. Whether something *should* be done
+is a question about priorities and fit; whether an implementation is *correct* is a question
+about the code. These are different judgements, often made by different people, and merging
+them into one thread means the cheaper question crowds out the harder one.
+
+```mermaid
+flowchart LR
+    intent["Issue<br/>what and why"] --> impl["Pull request<br/>how"]
+    impl -->|"rejected"| intent
+    impl -->|"accepted"| merged["Merged"]
+```
+
+The consequence is a rule about creation order: an issue exists before the work that resolves
+it. Where a change is genuinely trivial, the pull request MAY stand alone, but it then carries
+its own statement of intent, because something has to.
+
+## Labels are the control channel
+
+Where automation must be told something, it MUST be told with a label rather than with prose.
+
+Prose is where humans express nuance, which is exactly what makes it a poor instruction to a
+machine: parsing it means guessing, and a guess about whether a maintainer approved something
+is a guess with consequences. A label is unambiguous, appears in the artifact's timeline with
+who applied it and when, and can be required or forbidden by a rule.
+
+Labels used for coordination MUST follow the organization's
+[label vocabulary](../../Ways-of-Working/Automation-Labels.md), so that a label's owner and
+meaning are knowable without reading the workflow that consumes it. Automation MUST ignore
+labels it does not own.
+
+## An agent is a participant, not an authority
+
+An agent operating on these artifacts MUST do so under the same rules as any other
+participant.
+
+That means it opens issues and pull requests rather than pushing to protected branches, its
+changes are reviewed, and its conclusions are advice until someone acts on them. The
+[four-eyes principle](../../Ways-of-Working/Principles/AI-First-Development.md#4-eyes-or-n-eyes-principle)
+does not weaken because one pair of eyes is automated; an agent reviewing an agent is
+[advisory](advisory-agents.md), and human authority over the merge remains.
+
+The symmetry is deliberate. A process that gave agents a privileged path would have two sets
+of rules, and the agent path would be the one nobody audits.
+
+## Handover is a state, not a message
+
+Work passed from one participant to another MUST be handed over through the artifact's own
+state — its labels, its assignment, its review status — and MUST NOT depend on a message
+having been delivered.
+
+An agent that finishes its part and describes the next step in a comment has produced
+something a human must read and act on. An agent that finishes its part and moves the
+artifact into the state the next stage reacts to has produced something the process picks up.
+The first is a notification; the second is a handover.
+
+This is what allows a chain of work to survive interruption. Any participant can determine
+what happens next by looking at the artifact, without reconstructing a conversation.
+
+## Where this connects
+
+- [Spec](spec.md#requirements) — the requirement that coordination happens on durable artifacts and that intent is separable from implementation.
+- [Advisory Agents](advisory-agents.md) — how an agent publishes judgement onto these artifacts without taking authority.
+- [Automation Labels](../../Ways-of-Working/Automation-Labels.md) — the label vocabulary and ownership rules.
+- [Workflow](../../Ways-of-Working/Workflow.md) — the stages these artifacts move through.
+- [Issue Format](../../Ways-of-Working/Issues/index.md) — what an issue states.
+- [PR Format](../../Ways-of-Working/PR-Format.md) — what a pull request states.

src/docs/Capabilities/agentic-development/conformance.md

@@ -0,0 +1,112 @@
+---
+title: Conformance
+description: What a repository must provide to be conformant with the agentic development framework, what it may add, and the duplication checks that keep the router thin.
+---
+
+# Conformance
+
+A framework that cannot be checked is a preference. This page states what conformance to
+agentic development means for a single repository: the baseline it MUST provide, what it MAY
+add, and the conditions that indicate it has drifted.
+
+The checks are deliberately structural. Whether a repository's documentation is *good* is a
+review question; whether its agent context resolves correctly is a property that can be
+determined by looking.
+
+## The mandatory baseline
+
+A conformant repository MUST provide all of the following.
+
+| Requirement | Conformant when |
+| --- | --- |
+| **A router agent file** | The repository root holds a single agent instruction file, and it routes rather than instructs ([design](design.md#pointer-files)) |
+| **Reading order** | The router states the order in which context is read, from repository-local to organization-canonical |
+| **Client routes** | Every supported runtime's expected instruction path exists and resolves to the router, carrying no content of its own ([client behavior](design.md#client-behavior)) |
+| **Canonical coordinates** | The router names the organization's canonical documentation and memory locations, so context is reachable without prior knowledge |
+| **Freshness** | Canonical context is refreshed at the start of every session, in every runtime ([refresh hooks](design.md#refresh-hooks)) |
+| **Precedence** | The router states that local files never override a standard and that memory never overrides documentation |
+
+The baseline is small on purpose. Every item is something an agent needs before it can find
+anything else; nothing on the list is a judgement about how the repository should be
+documented.
+
+## The router stays thin
+
+The router MUST NOT restate a standard.
+
+This is the check that decays fastest, because adding one useful line to the router is always
+easier than finding where that line belongs. A router that has grown into a summary is the
+worst of both outcomes: it is not authoritative, so it may be wrong, and it is convenient, so
+it is what gets read.
+
+A repository is non-conformant where any of these hold:
+
+- The router contains a rule that also appears in organization documentation.
+- The router contains a rule that appears nowhere else — meaning documentation is missing, and
+  the router is standing in for it.
+- A client route contains instructions rather than a pointer to the router.
+- A path-scoped rule file restates something the router or a standard already says.
+- A named intent carries a copy of the procedure it invokes
+  ([plugin distribution](plugin-distribution.md)).
+
+Each of these is the same fault: one fact in two places, which is
+[one fact one place](../../Ways-of-Working/Documentation-Model.md) violated, and which
+resolves in whichever direction the reader happens to look first.
+
+The remedy is always the same, and it is not deletion of the content: move the content to the
+layer that owns it, then reduce the local file to a pointer.
+
+## What a repository may add
+
+Beyond the baseline, a repository MAY add:
+
+- **Path-scoped rules**, for a caveat that is genuinely local to a directory and cannot be
+  stated as a standard.
+- **Runtime adapters**, for a client the organization has not yet standardized on, provided the
+  adapter is a route and adds no content.
+- **Named intents**, for recurring workflows, provided they remain pointers.
+- **Repository-specific documentation**, which is normal and expected — the constraint is on
+  restating standards, not on documenting the repository.
+
+An addition MUST NOT introduce a requirement. Where local practice differs from a standard,
+the resolution is to change the standard or to record an
+[exemption](../repository-governance/spec.md#exemption), not to encode the difference where
+only agents will read it.
+
+## Levels
+
+Conformance is graded, so that a repository can be positioned honestly rather than being
+either compliant or not.
+
+| Level | Meaning |
+| --- | --- |
+| **Baseline** | Every mandatory item is present; an agent can resolve context correctly from a cold start |
+| **Consistent** | Baseline, plus no duplication findings: no local file restates a standard |
+| **Uniform** | Consistent, plus every supported runtime resolves identically, and the shared tool layer is declared in each ([MCP servers](mcp-servers.md)) |
+
+Only **Baseline** is required. The higher levels describe a repository whose agent context
+needs no per-runtime knowledge to work with, which is the state the framework is aiming at.
+
+## Checking
+
+Conformance MUST be checkable without running an agent.
+
+The baseline is a set of file and content properties, and duplication is detectable by
+comparing local text against the standards it might be restating. Both are amenable to the
+same [drift detection](../repository-governance/design.md#drift-detection-and-reconciliation)
+the organization already applies to repository structure, and a conformance finding MUST name
+its remedy for the same reason every other finding does: a finding that only reports a problem
+becomes a number people learn to ignore.
+
+Determining conformance by asking an agent whether it understood the repository MUST NOT be
+treated as a check. The answer is generated from the same context whose adequacy is in
+question.
+
+## Where this connects
+
+- [Spec](spec.md) — the requirements this checklist measures against.
+- [Design](design.md) — the mechanisms each baseline item refers to.
+- [MCP Servers](mcp-servers.md) — the shared tool layer the **Uniform** level requires.
+- [Plugin Distribution](plugin-distribution.md) — the pointer discipline the duplication checks apply to intents.
+- [Repository Governance](../repository-governance/index.md) — the drift detection and exemption machinery conformance checking reuses.
+- [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — one fact one place, which the duplication checks enforce.