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
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,12 @@ change, is written down in `COMPATIBILITY.md`.

### Added

- `change init --verify-clause <contract#clause>` can select existing Contract
clauses for first-time Evidence registration. Selected unverified clauses
enter the normal Builder Evidence workflow without declaring the existing
behavior as a new implementation impact or blocking on unrelated unverified
clauses.

- External runners can append execution start and completion events without
asking ADF to launch an agent. The events retain failed and interrupted
attempts, add cache-creation, cached-input, and reasoning-output token counts
Expand Down
18 changes: 17 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,22 @@ adf change init change.first-feature \
adf next change.first-feature
```

To verify behavior that already exists, select only the Contract clauses whose
Evidence you will register:

```sh
adf change init change.verify-existing-orders \
--title "Verify existing order behavior" \
--intent "Register reproducible evidence for existing behavior" \
--verify-clause contract.order-lifecycle#orders-source-of-truth
```

The selected clauses enter the normal Evidence workflow even when they have not
been verified before. Other unverified clauses do not block this Change. Existing
behavior is not reported as a new implementation impact merely to select it for
verification. Clauses whose `evidence_mode` is `review` remain human-review work
and cannot be selected with this option.

From here, `next` says what to do. Agents normally reach it over MCP:

```sh
Expand Down Expand Up @@ -363,7 +379,7 @@ distribution is a later compatibility milestone.
| `project observe` | list what the detectors can see, for review |
| `project validate-bindings` | report missing bindings and what cannot be checked |
| `project promote-bindings` | make a reviewed draft the observation of record |
| `change init` | start a change |
| `change init` | start a change, optionally selecting existing Contract clauses to verify |
| `next` | issue the next action |
| `explain` | say why the change is where it is |
| `execution-log` | aggregate Context size and any execution metrics already reported |
Expand Down
2 changes: 2 additions & 0 deletions docs/MCP-DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,8 @@ InputにはContract Recordと`expected_digest`を必須とし、条項単位で
| `implement-change` | Repository file変更。MCP外のworkspace操作 |
| `record-evidence` | Evidence |

Changeの`verification_scope`に指定した既存Contract条項は、未検証でも`record-evidence`の対象になる。この指定はImpact Assessmentの影響申告には変換しない。MCPは通常どおり`adf_next`でActionを発行し、`adf_add_evidence`と`adf_submit`で結果を受け付けるため、専用の書込みToolは追加しない。

この対応はMCP handlerへ散在させず、Application protocolの固定tableとして一か所に置きます。
未知Actionは書込みなしとしてfail closedに扱います。

Expand Down
11 changes: 11 additions & 0 deletions docs/concepts.ja.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,8 @@ Contractは変更のたびに増えます。障害から学んだことはテス

コードがないことを、影響がないこととは扱いません。新規プロジェクトでは、最初の変更依頼から実現しようとしている振る舞いを特定し、その変更に必要な最小限のContractを作ってから実装へ進みます。

既存実装の移行では、検証するContract条項を`--verify-clause`で明示できます。指定した条項は未検証でもEvidence登録の対象になり、指定していない未検証条項は変更を止めません。既存の振る舞いを検証対象にするために、今回新たに生じる実装影響として申告する必要はありません。`evidence_mode: review`の条項は人のレビューを求めるため、この方法では選択できません。

```text
adf change init
│
Expand Down Expand Up @@ -162,6 +164,15 @@ adf change init change.first-feature \
adf next change.first-feature
```

既存実装のEvidenceを登録する場合は、対象条項を指定して変更を作ります。

```sh
adf change init change.verify-existing-orders \
--title "既存の注文処理を検証する" \
--intent "既存の振る舞いに再現可能なEvidenceを登録する" \
--verify-clause contract.order-lifecycle#orders-source-of-truth
```

エージェントには、同じ操作をMCPサーバー経由で使わせます。

```sh
Expand Down
2 changes: 2 additions & 0 deletions docs/implementation.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,8 @@ Contractへ状態を書き戻さず、未検証を合格扱いしません。

Applicationは、現在選択されたRequirementのsubjectと一致する`stale`/`failed`条項だけに、組込みの`contract-clause-revalidated` Requirementを追加します。これは`before-merge`の`evidence-backed`なBuilder作業です。Contextには対象条項とhealth findingを含め、無関係な条項と`unverified`条項はこの経路ではChangeを停止しません。現在入力に対する成功Evidenceを提出すると再検証は解決します。

既存実装を初めて検証する場合は、Changeの`verification_scope`へ`contract.id#clause-id`を列挙します。指定した条項には、状態が`unverified`でも同じ`contract-clause-revalidated` Requirementを追加します。指定していない未検証条項は追加しません。存在しない条項と`evidence_mode: review`の条項は受理しません。この検証対象は変更影響とは別に扱うため、Evidence登録だけを目的とするChangeのImpact Assessmentは、実装への影響がなければ`no-impact`にできます。

```sh
adf contract-health --project . --format text
adf contract-health --project . --format json --require-clean
Expand Down
11 changes: 10 additions & 1 deletion schemas/v1/change.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,16 @@
"title": {"type": "string", "minLength": 1},
"intent": {"type": "string", "minLength": 1},
"impact_assessment": {"const": "required"},
"base_revision": {"type": "string", "minLength": 1}
"base_revision": {"type": "string", "minLength": 1},
"verification_scope": {
"type": "array",
"items": {
"type": "string",
"pattern": "^contract\\.[A-Za-z0-9._-]+#[A-Za-z0-9][A-Za-z0-9._-]*$"
},
"minItems": 1,
"uniqueItems": true
}
},
"additionalProperties": false
}
5 changes: 5 additions & 0 deletions skill-src/adf-analyst/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,11 @@ Assess what the Change is intended to affect before relying on detected source c
action receives the Change, compact repository and governance indexes, the built-in Signal
Catalog, and up to three prior Impact Assessments.

An explicit Contract verification scope selects existing behavior for Evidence work; it
does not by itself declare a new application impact. Assess the Change intent honestly.
For an Evidence-only Change, `no-impact` is valid after the same active check required for
any other Change.

For each intended effect, choose a Signal from `context.payload.signal_catalog` and copy
its required binding names exactly. Record:

Expand Down
6 changes: 6 additions & 0 deletions skill-src/adf-builder/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,12 @@ Show that each requirement instance in the action actually holds. For each one,
- `summary`: what the evidence shows
- `basis_refs`: the tests, probes, and artifacts you actually ran or read

A Change may explicitly select existing Contract clauses for verification without
changing product code. In that case, run or inspect a reproducible check for the exact
selected clauses and register what it establishes. Do not invent implementation output
or treat the absence of a code change as Evidence. A generic passing test is insufficient
unless it exercises the behavior named by the clause.

Evidence is traceable to a contract clause or it is not evidence. A mock does not
demonstrate that a platform behaves as assumed, and a passing test that never exercised
the path proves nothing about it. Where you could not establish the requirement, report
Expand Down
Loading
Loading