SCOPE.md update; scope-vs-intent assessment after MAS-WP-0010 (history/)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assistant: claude-code Assistant-Model: opus Assistant-Process: 5787@bnt-lap001 Assistant-Session: 5db26b82-138b-40cc-9856-4d5eb0f752fd
This commit is contained in:
parent
87be0d1da3
commit
3d99c818d9
2 changed files with 145 additions and 9 deletions
27
SCOPE.md
27
SCOPE.md
|
|
@ -3,9 +3,12 @@
|
|||
## One-liner
|
||||
|
||||
Reference implementation and spec workbench for Mail Address Semantics
|
||||
(MAS): parser, statute discovery, pure policy, generator, CLI, mail
|
||||
gateway, reference ticket service, and a tested Postfix integration
|
||||
profile. It implements v0.1.1 and the v0.2 draft.
|
||||
(MAS), and the email building block for a future multimodal communication
|
||||
framework. Contents: parser, statute discovery, pure policy, generator,
|
||||
CLI, mail gateway, reference ticket service, a tested Postfix integration
|
||||
profile, and the mode contract with an email side that works as master or
|
||||
slave. It implements address spec v0.1.1, the v0.2 draft and mode contract
|
||||
v0.1 (draft).
|
||||
|
||||
## Core Idea
|
||||
|
||||
|
|
@ -78,8 +81,9 @@ delivery stays external.
|
|||
- Status: active. The reference experiment (MAS-WP-0002) passed its
|
||||
decision gate on 2026-10-18; the findings are in
|
||||
`docs/experiment-review.md`.
|
||||
- Finished: MAS-WP-0001 to 0006, 0008 and 0010. Postfix profile, v0.1.1 errata,
|
||||
v0.2 draft, address composer, and v0.2 conformance cases.
|
||||
- Finished: MAS-WP-0001 to 0006, 0008 and 0010. Postfix profile, v0.1.1
|
||||
errata, v0.2 draft, address composer, v0.2 conformance cases, and the
|
||||
mode contract with its reference implementation.
|
||||
- Open: MAS-WP-0007 (retire the live MX; backlog, unblocked) and
|
||||
MAS-WP-0009 (declare v0.2 final; waits for a second implementation or
|
||||
deployment).
|
||||
|
|
@ -88,12 +92,17 @@ delivery stays external.
|
|||
v0.2 §7.1). The mode contract v0.1 draft and the reference
|
||||
implementation are done (MAS-WP-0010); `mas test` runs the contract
|
||||
corpus.
|
||||
- The live `mas-mx` pod runs an image built before the profile refactor.
|
||||
- Tests: `.venv/bin/pytest` runs 199 tests, offline apart from loopback
|
||||
fixtures and the Docker probe.
|
||||
- The live `mas-mx` pod runs an image built before the profile refactor
|
||||
and before `mas_modes`. The current Dockerfile builds and imports
|
||||
cleanly but has not been deployed.
|
||||
- Tests: `.venv/bin/pytest` runs 242 tests, offline apart from loopback
|
||||
fixtures and the Docker probe. `mas test` runs four corpora: parser
|
||||
62, statute 16, v0.2 statute-aware 29, mode contract 172.
|
||||
- Assessments: `history/` (latest: `2026-10-19T090725Z-scope-vs-intent.md`).
|
||||
|
||||
## Getting Oriented
|
||||
|
||||
- Start with: INTENT.md, then `docs/experiment-review.md`
|
||||
- Start with: INTENT.md, then `docs/experiment-review.md` and
|
||||
`docs/reuse-surface.md`
|
||||
- Agent instructions: AGENTS.md
|
||||
- Workplans: workplans/
|
||||
|
|
|
|||
127
history/2026-10-19T090725Z-scope-vs-intent.md
Normal file
127
history/2026-10-19T090725Z-scope-vs-intent.md
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
# Scope vs. intent: assessment, 2026-10-19T09:07:25Z
|
||||
|
||||
**State assessed:** `main` after MAS-WP-0010 (commit `87be0d1`).
|
||||
INTENT.md (phase 2, with the mode reference implementation) compared with
|
||||
SCOPE.md as updated alongside this record.
|
||||
**Evidence:** workplan files, `mas test` (parser 62/62, statute 16/16,
|
||||
v0.2 statute-aware 29/29, mode contract 172/172), and `pytest` (242
|
||||
passed, including the Docker Postfix probe).
|
||||
|
||||
## Verdict
|
||||
|
||||
Scope and intent agree closely. Five of the eight phase-2 done criteria
|
||||
are met, one is substantially met, and two are open. All five phase-2
|
||||
goals have a working reference, except finalizing v0.2. The open items are
|
||||
not missing work. They are gated on things this repo cannot produce
|
||||
alone: an independent implementation, and a founder teardown decision.
|
||||
|
||||
The main risks are new, and they come from the building-block ambition.
|
||||
The repo now holds two draft specs that only one implementation has ever
|
||||
run. The mode contract has no peer authentication. And the send cap
|
||||
(principle 10) is not one total cap when both roles run in one deployment.
|
||||
|
||||
## Done criteria (INTENT.md, *Phase 2 is done when*)
|
||||
|
||||
| # | Criterion | Status | Evidence / gap |
|
||||
|---|---|---|---|
|
||||
| 1 | Fresh Postfix from `integrations/postfix/` alone delivers the corpus and refuses relaying | **Substantially met** | The probe installs a stock Debian Postfix, runs only `install.sh`, and passes the full corpus plus 5 relay negatives. The probe adds only what the README asks the caller to provide (milter start, an app). The profile has not been tried by someone following the README by hand. |
|
||||
| 2 | `mas compose` right for every observed destination | **Met** | IONOS and Google Groups forms, plus refusals (`tests/test_compose.py`). |
|
||||
| 3 | v0.2 final, or withdrawn with reasons | **Open** | Founder decision: draft until a second implementation exists (MAS-WP-0009, backlog). No work is planned that would produce that implementation. |
|
||||
| 4 | Handoff reading of P2 in the v0.2 text, pointing to the contract | **Met** | SCP-8, v0.2 §7.1. |
|
||||
| 5 | Live test environment retired, evidence archived | **Open** | MAS-WP-0007 is unblocked but backlog. It needs founder actions (key revocation). The running pod is stale (it predates the profile refactor and `mas_modes`). |
|
||||
| 6 | Mode contract v0.1 with schemas and fixtures | **Met (draft)** | `mas-modes-v0.1-spec/`: 2 schemas, transitions, 27 messages, 13 flows. |
|
||||
| 7 | Email side passes them in both roles | **Met** | `mas test` 172/172; 31 role tests. Caveat: the contract, the stubs and the implementation were written together (see risk A). |
|
||||
| 8 | Callback scenarios deterministic in the suite | **Met** | 10 scenarios, fake clock, explicit stepping. |
|
||||
|
||||
## Goals (INTENT.md, *Phase 2 intent*)
|
||||
|
||||
1. **Adoptable integration:** met for Postfix. Exim stays at notes, which
|
||||
the intent allows (on demand).
|
||||
2. **Forwarder-safe generation:** met. The library and CLI emit the
|
||||
canonical form, the forwarder-safe form or a refusal.
|
||||
3. **v0.2 to final:** not met, and see risk A.
|
||||
4. **Safe reference behavior:** met and extended. Principle 10 now holds in
|
||||
both roles, and holds against sends the master requests. See risk C for
|
||||
a gap in "caps how much it can send in total".
|
||||
5. **Email as a building block:** met at the reference level. There is a
|
||||
contract, both roles, stubs and `docs/reuse-surface.md`. Risks B and D
|
||||
decide whether a real framework can actually build on it.
|
||||
|
||||
## Boundaries held
|
||||
|
||||
- **Architectural core.** The parser does no I/O, policy is pure, and only
|
||||
`discovery.py` touches the network. `mas_modes` sits above the gateway
|
||||
and changes none of these.
|
||||
- **Email is the only real channel.** The stubs never contact anyone. No
|
||||
telephony, chat or CMS connector entered the repo.
|
||||
- **The framework itself is not built.** The orchestration in `mas_modes`
|
||||
is limited to what email-as-master needs.
|
||||
- Phase-1 exclusions (policy daemon, registry, plugins, P3, parent
|
||||
inheritance) are untouched.
|
||||
|
||||
## Risks and drift
|
||||
|
||||
**A. Two draft specs, both self-validated.** The repo maintains three
|
||||
bundles: v0.1.1, the v0.2 draft and the mode contract v0.1 draft. Each
|
||||
draft has been run only against code written alongside it. The founder
|
||||
gate for v0.2 (a second implementation) applies even more to the mode
|
||||
contract, whose flows still contain harness-specific assumptions (the
|
||||
stub master assigns `EXT-100`, ...). So the corpus is language-neutral in
|
||||
format, but not yet in practice.
|
||||
*Recommendation:* scope MAS-WP-0009's second implementation to cover both
|
||||
drafts. A small consumer in a second language is enough: address parsing
|
||||
plus the slave role against the stub master. Make the flow fixtures
|
||||
independent of harness details first.
|
||||
|
||||
**B. No peer authentication in the mode contract.** `mail.send`,
|
||||
`case.assign` and `case.policy` steer real outbound mail. `handoff.status`
|
||||
changes what email tells customers. CONTRACT.md defines idempotency and
|
||||
ordering, but not how email knows that a master or mode is who it claims
|
||||
to be. The reference endpoints are unauthenticated (documented as
|
||||
loopback-only). For a reusable building block this is a contract gap, not
|
||||
just an implementation shortcut.
|
||||
*Recommendation:* add a transport-security section to contract v0.1
|
||||
before anyone integrates: at minimum, a shared-secret HMAC or mTLS
|
||||
requirement per peer, and binding `status_url` to the handoff.
|
||||
|
||||
**C. The send cap is split.** In a deployment with both roles, the master
|
||||
role sends through the ticket service's outbox and cap, and the slave role
|
||||
through `mas_modes.mailer`'s outbox and cap. Total outbound can then reach
|
||||
about twice the configured cap. The behavior over the cap also differs:
|
||||
the ticket service keeps replies unsent, while the mailer refuses with
|
||||
`send-cap-reached`. Principle 10 says "caps how much it can send in total".
|
||||
*Recommendation:* make `mas_modes.mailer.Mailer` the only outbound path,
|
||||
and have the ticket service send through it. The gate is already shared;
|
||||
the outbox and counter are not.
|
||||
|
||||
**D. The master role depends on an example.** The only `MasterStore`
|
||||
implementation is the reference ticket service in `examples/`, and the
|
||||
harness imports it by path. The reuse surface calls the email side
|
||||
reusable but the ticket service an example. A framework that wants email
|
||||
as master has to write its own store.
|
||||
*Recommendation:* that is acceptable for v0.1. State it in
|
||||
`docs/reuse-surface.md`, and add a minimal in-package `MasterStore` (no
|
||||
ticket semantics) if a consumer asks.
|
||||
|
||||
**E. Operational drift.** The live MX runs a stale image, and the
|
||||
Dockerfile has changed twice since (profile, `mas_modes`). It is still a
|
||||
public, reply-capable endpoint.
|
||||
*Recommendation:* decide MAS-WP-0007 soon. Retire it, or redeploy it once
|
||||
so that what runs matches what is tested.
|
||||
|
||||
## Scope changes made with this assessment
|
||||
|
||||
SCOPE.md: the one-liner now names the building-block role and the mode
|
||||
contract; the Current State reflects MAS-WP-0010 (242 tests, four `mas
|
||||
test` corpora, the undeployed Dockerfile); and the Getting Oriented section
|
||||
points to `docs/reuse-surface.md` and to this `history/` folder. In Scope
|
||||
and Out of Scope were already aligned with INTENT.md and are unchanged.
|
||||
|
||||
## Suggested next work (not yet recorded as work items)
|
||||
|
||||
1. Contract v0.1: transport security (risk B). Highest priority before any
|
||||
integration.
|
||||
2. One outbound path and one cap (risk C). Small.
|
||||
3. Flow fixtures independent of the harness, and a second-language
|
||||
consumer of both drafts (risk A, MAS-WP-0009).
|
||||
4. Decision on MAS-WP-0007 (risk E).
|
||||
Loading…
Add table
Add a link
Reference in a new issue