Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 143 additions & 0 deletions .agents/skills/coding-standards/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
---
name: coding-standards
description: Obtain the engineering standards that apply to a coding task from the Standards Engine application tools. Use at the start of any task that plans, writes, changes, reviews, tests, builds, documents, commits or releases code, before planning or editing, and again when the task grows. Not for maintaining the standards themselves; that is the standards-engine authoring skill.
---

# Coding Standards

The Standards Engine holds the engineering standards as modules. You state facts
about your task; it returns every module that applies, with its full text. Read
them before you plan or edit, then follow them.

Use the application-purpose Standards Engine MCP tools. The tool-name prefix
depends on the client (for example `mcp__standards-engine__route`); the operation
names below are exact.

## The Sequence

1. **Get the vocabulary once.** Call `routing_facts` with no arguments. It lists
every fact: its exact name, meaning and allowed values. Keep the `snapshot` it
returns.
2. **Route.** Call `route` with that snapshot, the facts that are true of your
task, and `content: {}`.
3. **Read every page.** `reading_plan` lists every module that applies.
`content.items` holds the full text of the modules on this page. While
`content.next` is present, call `route` again with exactly the arguments in
`content.next`.
4. **Work from what you hold.** Pass the same `snapshot` in every later call. A
module you already hold at that snapshot has not changed; do not read it
again.

## Worked Example

Task: implement a Rust function that is called from C.

`route` request:

```json
{
"snapshot": {"kind": "snapshot-handle", "id": "snapshot:v1:...", "schema_version": 5},
"facts": {
"routing.activities": ["implementation"],
"routing.languages": ["rust"],
"routing.boundaries": ["interop"]
},
"content": {}
}
```

Response outline (nine modules apply; this first page carries two of them):

```text
kind: application-route-result
snapshot: the same handle; keep passing it
status: needs-facts
reading_plan:
core review_state: current
router review_state: current
workflow.verification review_state: current
topic.contracts review_state: current
topic.security review_state: current
profile.boundary.interop review_state: not-reviewed
profile.language.rust review_state: current
profile.language.rust.interop review_state: not-reviewed
workflow.implementation review_state: current
unresolved_questions: routing.applications, routing.details, routing.frameworks,
routing.topics, routing.workflow-profiles
content:
offset: 0
total: 9
items:
- policy.id: core review_state: current content: "# Core Standards ..."
- policy.id: router review_state: current content: "# Standards Router ..."
next: {snapshot, facts, content: {offset: 2, limit: 8}}
```

Call `route` with `content.next` exactly as given, and repeat until a page has no
`next`. All nine modules, including the two labelled `not-reviewed`, are then in
hand.

`status: needs-facts` means some facts were not stated, so the selection may be
incomplete. Look at `unresolved_questions`: if one of those facts is true of your
task, route again with it added and the same snapshot. The modules already
returned still apply.

## Choosing Facts

- Supply what is true of the task. Copy names and values exactly from
`routing_facts`; a near spelling is rejected, never guessed.
- Omit what you do not know. An omitted fact stays unknown and comes back in
`unresolved_questions`.
- `[]` states that none of the values apply. Supply it only when you know that;
do not use it to silence a question.
- Do not delete a true fact to make a call succeed or to shrink the result. A
rejection tells you what to correct. Fewer facts means missing standards.
- When the task grows (another language, a new boundary), route again with the
added facts and the same snapshot. Read only the modules you do not yet hold.

## Reading In Small Batches

Most clients show about 50 KB of a tool result inline and divert anything larger
to a file. Route pages are sized to fit: about 40 KB each, and always at least
one whole module. Follow `content.next` until it is absent.

Use `read` for one module by ID and `read_many` for a few. Ask `read_many` for
two or three modules per call so the whole result is shown. IDs come from a
`route`, `read` or `related` result; use them exactly.

## Snapshot Reuse

- Every result returns a `snapshot`. Pass it unchanged in later calls so that
everything you read comes from one version of the standards.
- Omitting `snapshot` captures the current accepted standards afresh. Do that at
the start of a new task, not in the middle of one.
- Text held at a snapshot never changes. Do not re-read it to be safe.

## Review Labels

Every `reading_plan` entry and every delivered module carries `review_state`.

| Label | Meaning |
| --- | --- |
| `current` | This exact text was approved for application use. |
| `changed-since-review` | The text was edited after it was approved. |
| `not-reviewed` | The text has never been approved for application use. |

All three are delivered and all apply to your task. The label tells you how
settled the wording is; it is not permission to skip a module. If a module's
wording is unclear, or two modules seem to disagree, tell the user which modules
and what their labels are instead of silently choosing.

## When A Call Is Rejected

| Code | What to do |
| --- | --- |
| `APPLICATION.INPUT_INVALID` | Correct the field named in `input_feedback`. Check fact names and values against `routing_facts`. Keep the facts that are true. |
| `APPLICATION.UNKNOWN_TARGET` | The ID is not registered. Use an ID exactly as `route`, `read` or `related` returned it. |
| `APPLICATION.UNKNOWN_GROUP`, `APPLICATION.TRAVERSAL_NOT_PERMITTED` | Use a group and direction that `relationship_groups` lists. |
| `APPLICATION.RESULT_LIMIT` | Ask for fewer modules in one call. |
| `APPLICATION.INTERNAL_UNAVAILABLE`, `APPLICATION.UNSUPPORTED_CAPTURE` | The server could not answer. Report it to the user; do not guess the standards. |

`related` and `relationship_groups` show how modules relate when you need to
follow a prerequisite. `describe_input` shows an exact argument shape when your
client abbreviates one.
4 changes: 2 additions & 2 deletions .agents/skills/standards-engine/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ description: Maintain this repository's coding standards through an authoring-pu
# Standards Engine Authoring

This skill is maintenance material for standards authors. Ordinary application
agents use their application-purpose tool catalog and approved guidance, rather
than loading this authoring skill.
agents use their application-purpose tool catalog and the `coding-standards`
skill, rather than loading this authoring skill.

Use the generated public Interface. The Engine is the sole writer of standards
Markdown, metadata, supplementary projections, SQLite state, and local Git
Expand Down
8 changes: 5 additions & 3 deletions .agents/skills/standards-engine/references/authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -231,8 +231,10 @@ and templates support `revise-operational-artifact`.

After material review, call authoring `preview_application` with the exact revision
and an application read, route or related request. Inspect the complete returned
content, required closure, relationship filtering and qualification results. Repair
missing qualifications or retain authoring-only material outside application exposure.
content, selected closure, relationship filtering and each item's `review_state`
label. The preview delivers every registered item an application agent would
receive; approve or withdraw exposure to change a label, and keep authoring-only
reasoning in provenance records, which the application view never returns.
Candidate previews remain bound to the revision and do not publish a snapshot.

Refresh the client catalog after an engine update and inspect initialization's
Expand Down Expand Up @@ -337,7 +339,7 @@ for the code-to-content handoff. Read operational aids to obtain their captured
authoring target. Submit provenance content and an explicit exposure decision
in the same coherent change as applicable; the Engine binds final candidate
content. Provenance-only maintenance retains unchanged normative revisions.
Application eligibility starts empty and becomes active only after reviewed
An approval changes an item's application `review_state` label only after reviewed
publication, not after merely creating a draft.


Expand Down
20 changes: 14 additions & 6 deletions .agents/skills/standards-engine/references/environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,13 @@ new application session after authoring. The Engine cannot erase prior context.
}
```

Add `"--route-page-bytes", "N"` to the application arguments only when the client
shows more or less than about 50 KB of a tool result inline. The default page
budget is 40,960 bytes of result JSON, the range is 8,192–2,097,152, a page always
holds at least one whole module, and the option is a launch error for authoring.
Application agents use the `coding-standards` skill in
`.agents/skills/coding-standards/`; this authoring skill is for maintainers.

These are separate intended audiences, not two registrations every agent should
receive. Translate the command, arguments and environment to the client's actual
configuration format. Restart the Engine and reconnect after the interface-41
Expand All @@ -51,7 +58,7 @@ configured purpose.

The local server remains synchronous MCP stdio with protocol `2025-11-25`;
requests execute serially and immutable Engine handles survive reconnection.
The current implementation is 0.2.0 and Engine interface 44. No network listener,
The current implementation is 0.2.0 and Engine interface 49. No network listener,
paid model turn, remote publication or extra server dependency is introduced.
The existing local authoring authorization adapter is owner-operated and
always-allow; explicit user authorization still governs requested changes.
Expand All @@ -63,11 +70,12 @@ remote multi-user permission service.

## Bootstrap and cutover

New automatic snapshots read accepted local `main`. The code release initially
contains empty application-approval and provenance manifests. Application reads
therefore return a bounded unavailable result until the separate content work
reviews and publishes the required material. Authoring can read the unchanged
standards once the code candidate is integrated into accepted main.
New automatic snapshots read accepted local `main`. The application-approval
manifest records which exact material was reviewed for application use. Since
interface 49 it labels delivered material (`current`, `changed-since-review` or
`not-reviewed`) and never withholds it, so application reads and routes work
before, during and after the separate content review. Authoring can read the
unchanged standards once the code candidate is integrated into accepted main.

Use a disposable clone with candidate `main` for pre-merge qualification. Preserve
active installed proposals and recovery obligations before cutover. Old Analysis
Expand Down
47 changes: 30 additions & 17 deletions .agents/skills/standards-engine/references/navigation.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,9 @@ MCP tool definitions supplied by the client; invoke the tools directly.
group the selected policies into `read_many` with the returned
snapshot and ordered `items` such as `[{"target":"core"}]`. Select up to 32
unique read items per call. The complete result is bounded to 2 MiB and any
unavailable item rejects the whole group; narrow the selection on a limit.
unregistered or failed item rejects the whole group; narrow the selection on a
limit. Two or three modules per call keep a result within what most clients
show inline.
Grouping preserves the same exact text, authority and detail options as `read`.
5. Use returned inspect operations and handles when more detail is needed.
`inspect` accepts opaque handles, not repository locators.
Expand Down Expand Up @@ -47,16 +49,23 @@ selected, deduplicated target order. `content.total` counts all selected targets
`route` request, preserving its facts and snapshot. Nonzero offsets require an
explicit snapshot. Changing facts intentionally starts a different selection.

The complete route result, including its plan, questions, items and continuation,
is limited to 2 MiB. Byte pressure returns fewer whole reads. A first record that
cannot fit returns a typed limit rejection, never clipped policy text. Request a
selection-only route and explicitly `read` that target when the client can receive
it. An unavailable selected dependency or a failed read rejects the result;
partial prefixes are not returned as success. An offset equal to the selected
count returns an empty final page; a larger offset is invalid.

All content uses the same captured authority and ordinary read/qualification
rules. Missing facts remain unresolved even when selected text is returned.
The complete authoring route result, including its plan, questions, items and
continuation, is limited to 2 MiB. Byte pressure returns fewer whole reads. A first
record that cannot fit returns a typed limit rejection, never clipped policy text.
Request a selection-only route and explicitly `read` that target when the client can
receive it. A failed read rejects the result; partial prefixes are not returned as
success. An offset equal to the selected count returns an empty final page; a
larger offset is invalid.

Application route pages are sized for inline display instead: 40 KiB of result
JSON by default, or the application server's `--route-page-bytes` value
(8,192–2,097,152). A page always holds at least one whole read, so a module larger
than the budget arrives alone rather than as a rejection. Every selected module is
delivered with its `review_state` label (`current`, `changed-since-review` or
`not-reviewed`); approval state never withholds a selected module.

All content uses the same captured authority and ordinary read rules. Missing
facts remain unresolved even when selected text is returned.
Only selected content is paged. Compact plans contain the complete selected closure;
all fact questions remain present. The full explanation additionally includes
unresolved-policy rows. Content continuations preserve the requested detail.
Expand Down Expand Up @@ -95,8 +104,8 @@ do not rebuild them from stale spellings or a different snapshot.
Malformed common JSON shapes fail before capture. A vocabulary-dependent error can
occur after capture when the snapshot was omitted; it returns invalid field feedback,
not a successful route or authoring change. Correct the field or consult the
snapshot-bound vocabulary. Unqualified application Router content remains unavailable
before its vocabulary is interpreted or disclosed.
snapshot-bound vocabulary. Application routing interprets the vocabulary whatever
the Router's review label is.

Focused authoring `route` defaults to `compact-route-result`: canonicalized
supplied facts, selected reading entries and required dependencies, every typed
Expand All @@ -110,7 +119,7 @@ Each unanswered question carries its registered fact definition. Supply empty
sets only when the task establishes absence, rather than to silence questions.
Full rule expressions describe evaluated applicability, not inferred policy prose.
Required dependency reasons identify their graph edge and source. Several reasons
may select the same standard. Application purpose retains the same qualified
may select the same standard. Application purpose retains the same labelled
selection and all questions even when full detail is requested; private authoring
rule explanations are not exposed.

Expand All @@ -127,15 +136,19 @@ traversal policy, without reading policy text merely to find a group name. Reuse
its snapshot with `related`. An omitted snapshot captures accepted authority;
nonzero page offsets require the returned snapshot. Pages contain up to 32 whole
records (default 8), with a 16 KiB page limit; follow `next` unchanged. Application
vocabulary comes only from its permitted graph and requires qualified Router content.
vocabulary comes only from its permitted graph: every registered material, in the
five application relationship groups.

An unknown focused group returns `GRAPH.UNKNOWN_GROUP` (application:
`APPLICATION.UNKNOWN_GROUP`) and `relationship_groups`, the same bounded first
vocabulary page. Choose a returned ID explicitly. A registered group can have no
edges for the selected target; that is a successful empty query. Traversal directions
and transitivity describe the group's traversal policy, not a claim of existing
relationships. Authoring provenance groups are excluded from application vocabulary.
Native authoring queries and draft previews keep their existing rejection contracts.
A traversal the group does not permit returns `APPLICATION.TRAVERSAL_NOT_PERMITTED`
in application purpose; an unregistered target returns `APPLICATION.UNKNOWN_TARGET`.
Native authoring queries keep their existing rejection contracts; draft previews
return the application codes bound to their revision.

## Accepted-Snapshot Analysis

Expand Down Expand Up @@ -172,6 +185,6 @@ instruction to infer an impact decision.

Use `describe_input` for argument shapes, not policy text. It observes only the
running purpose-qualified catalog and needs no snapshot. Application connections
can discover their own reviewed-guidance navigation inputs but cannot discover
can discover their own navigation inputs but cannot discover
unpublished authoring operations or definitions. `route`, `read`, and `related`
remain the owners of policy selection, text and relationships.
5 changes: 4 additions & 1 deletion .github/workflows/purpose-separated-engine.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ on:
paths:
- 'tools/**'
- '.agents/skills/standards-engine/**'
- '.agents/skills/coding-standards/**'
- 'evaluation/standards-effectiveness/**'
- '*.md'
- 'workflows/**'
Expand Down Expand Up @@ -73,5 +74,7 @@ jobs:
"$python" -m unittest discover -s tools/standards_contracts/tests
"$python" -m unittest discover -s tools/standards_analysis/tests
PYTHONPATH=.:tools/standards_verifier "$python" -m unittest discover -s tools/standards_verifier/tests
"$python" -m unittest discover -s tools/standards_engine/tests
# One unittest process per Engine test module, as many at a time as the runner has cores.
# It fails if any module fails or if fewer tests run than a serial discovery finds.
"$python" -m tools.standards_engine.tests.parallel_unittest --durations 25
PYTHONPATH=.:tools/standards_verifier "$python" tools/standards_verifier/verify.py --complete
Loading
Loading