diff --git a/project/AICSDP/p3/step-03-mc-07-design-specification.md b/project/AICSDP/p3/step-03-mc-07-design-specification.md new file mode 100644 index 0000000..85a90ef --- /dev/null +++ b/project/AICSDP/p3/step-03-mc-07-design-specification.md @@ -0,0 +1,173 @@ +# Step 03 Design Specification — MC-07 Information Architecture + +> **Artifact type:** IA (sub-template C) · **Subject:** `@diamondslab/diamonds` v2.0 documentation +> **Status:** ✅ **FINALIZED v1.0 — OP-4 ratified (draft-and-react, Owner 2026-07-07)** · **Date:** 2026-07-07 · **Interview mode:** draft-and-react +> **Owner reactions applied:** L2 = 6 docs (added `upgrades-and-callbacks`); cut-safety rule accepted as drafted; api/\* scope = min signatures+one-liners / stretch prose. +> **Inputs:** Plan §6.3 (4 design questions), §5.3 (per-doc cut staging), §8 (Branch-2); Session 1 briefs (MC-04 §2.5, MC-21 §2.4, MC-12 §2.4); repo docs reality (`README.md`, `docs/`, `examples/`); toolkit step-03 sub-template C. + +--- + +## §1 — Brief Intake Confirmation + +MC-07 (Plan §6.3): design the v2.0 documentation **Information Architecture** — a three-layer structure (Quickstart / Core Concepts / Reference) plus colocated working examples. Resolves **F-25/F-40** (docs-vs-code gap) and **F-41** (auditor reproducibility surface) at the IA level. Four Plan §6.3 design questions: (1) Layer 2 concept-doc list + ordering; (2) cross-layer link structure; (3) doc-authoring style guide; (4) Layer 3 per-doc scope. Dominant principle lens: **Maintainability 1.5×**. Branch-2 obligation: the IA must survive **per-doc cuts**. + +**Current-state grounding [CONFIRM]:** docs today are unlayered and scattered — `README.md` (feature list + partial usage), `docs/` holds 5 ABI-generator files, `defender-integration.md`, `testing-guide.md`, `monitoring-troubleshooting.md`, `ROADMAP.md`, and `.uxf` design diagrams; `examples/` holds defender/local/config/test example dirs. No quickstart, no conceptual layer, reference is fragmentary. This _is_ the F-25/F-40 gap. + +## §2 — Design Specification + +### C.1 — Layer Structure + +**Three layers**, each with a distinct job: + +| Layer | Job | Entry | +| -------------------- | ------------------------------------------------------------- | ----------------------------------------- | +| **L1 Quickstart** | First-use: from zero to a locally-deployed diamond in <15 min | On-ramp from `README.md` | +| **L2 Core Concepts** | Understanding: the mental model behind the API (5–6 docs) | Independently enterable; L1 links forward | +| **L3 Reference** | Depth: per-module / per-strategy / per-flow detail | Independently enterable; L2 links forward | + +- **Reader path:** `README` → L1 Quickstart → (as needed) L2 Core Concepts → (as needed) L3 Reference. Off-ramps: each L2 doc links forward to the relevant L3 doc; each L3 doc links back to its L2 concept. +- **Layer interdependency:** layers are **independently enterable** — an experienced Diamond dev can jump straight to L3; a new user follows L1→L2. Deep understanding does _not_ require reading lower layers linearly. This independence is the backbone of per-doc-cut safety. + +### C.2 — Doc Set Composition (Design Q1 + Q4) + +**L1 Quickstart (1 doc):** + +| Doc | Purpose | ~Length | Variance | +| --------------- | ----------------------------------------------------------------------------------- | ------: | -------- | +| `quickstart.md` | Install → configure a minimal diamond → deploy locally → read the deployment record | 2–3 pp | Low | + +**L2 Core Concepts (6 docs — ordered; doc 6 added per OP-4 reaction):** + +| # | Doc | Purpose | ~Length | Variance | +| --- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------: | -------- | +| 1 | `concepts/deployment-model.md` | The config → strategy → deployment-record pipeline (the _first-deploy_ path) | 2–3 pp | Low | +| 2 | `concepts/strategy-pattern.md` | Base/Local/RPC strategies; the 15 lifecycle methods; extension via hooks (**anchors MC-04**) | 3–4 pp | Med | +| 3 | `concepts/configuration-and-versioning.md` | JSON config, Zod validation, facet/selector versioning, collision resolution | 2–3 pp | Med | +| 4 | `concepts/deployment-records-and-repositories.md` | The Repository pattern; record schema; persistence | 2 pp | Low | +| 5 | `concepts/diamond-abi-and-types.md` | Combined Diamond ABI generation + TypeChain types | 2 pp | Low | +| 6 | `concepts/upgrades-and-callbacks.md` | Deploy-vs-upgrade detection (`DiamondDeployer` finds an existing deployment → upgrade); post-deployment callbacks | 2–3 pp | Med | + +**L3 Reference (per-doc, cut-stageable):** + +| Doc | Purpose | ~Length | Variance | +| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------: | ---------------------------------------------------------- | +| `reference/api/` (core, strategies, repositories, schemas) | Per-module API reference | large | **High** (min: signatures+one-liners; stretch: full prose) | +| `reference/how-to-write-a-strategy.md` | Extend `BaseDeploymentStrategy` — worked via **`LoggingDeploymentStrategy`** (**MC-04 §2.5**) | 2–3 pp | Med | +| `reference/migration-v1-to-v2.md` | The `examples/migration-v1-to-v2.md` migration doc (**MC-21 §2.4**, co-authored w/ MC-04) | 2–3 pp | Med | +| `reference/verify-a-release.md` | The four-spoke auditor flow (**MC-12 §2.4**) — F-41 surface | 2–3 pp | Med | +| `reference/config-schema.md` | The Diamond config JSON schema, field by field | 2 pp | Med | + +_Per-doc variance is highest in `reference/api/` — Plan §5.3 cut-staging applies: min = signatures + one-line descriptions; stretch = full prose per symbol._ + +### C.3 — Cross-Link Graph (Design Q2) — **per-doc-cut safe** + +**Governing rule:** _links are navigational, never load-bearing._ No doc's **content** depends on another doc existing; a cut doc leaves at worst a dangling forward-link (gracefully degradable), never a broken concept. + +``` +README ──► L1 quickstart + │ (forward, optional) + ▼ + ┌─────────────── L2 Core Concepts ───────────────┐ + │ deployment-model ─► strategy-pattern │ (intra-L2 links are + │ configuration ─► deployment-records │ forward-only, acyclic) + │ deployment-model ─► upgrades-and-callbacks │ + │ diamond-abi-and-types │ + └───────┬───────────────┬───────────────┬────────┘ + │ (each L2 ─► its L3) │ + ▼ ▼ ▼ + L3: how-to-write-a-strategy api/* migration-v1-to-v2 + verify-a-release config-schema + (L3 ◄─ back-links to L2 concept; L3 docs do NOT hard-link each other) +``` + +- **Within-layer:** only L2 has intra-layer links, all **forward/acyclic** (deployment-model → strategy-pattern; configuration → deployment-records). No L2 doc's meaning requires another. +- **Cross-layer:** L1→L2 (forward, optional), L2→L3 (concept→reference), L3→L2 (back-link to parent concept). **L3 docs never hard-link each other** — this is what keeps a single L3 cut from cascading. +- **External:** ERC-2535 EIP, Hardhat docs, ethers `Signer` docs, CycloneDX spec (from `verify-a-release.md`). +- **Cut-safety demonstrated:** cutting any single L3 doc (e.g. `config-schema.md`) breaks only its inbound L2 forward-link, which degrades to prose ("see the config schema") — no other doc loses meaning. Cutting an L2 doc drops its forward-links to L3 but L3 docs remain independently valid. + +### C.4 — Style Guide (Design Q3) + +- **Voice:** second-person ("you") for L1/L2/how-to; impersonal for L3 api/schema reference. +- **Code blocks:** language-tagged (` ```typescript `, ` ```bash `, ` ```json `); **no line numbers**; output in a separate fenced block labeled `# output`. Imports shown explicitly (no elision) in L1/how-to. +- **Cross-links:** relative paths (`../concepts/strategy-pattern.md`); descriptive link text (never "here"); anchors lowercase-kebab. +- **Headings:** H1 = doc title only; H2 = major sections; H3 = subsections; deeper requires rationale. +- **Code-vs-prose ratio:** L1/how-to code-heavy (≥50% code); L2 balanced; L3 api = signature + concise prose. +- **Package-manager convention:** Yarn 4 in repo-facing snippets (matches README); note npm/pnpm work for consumers. + +### C.5 — Per-Doc Scope (Design Q4 — abbreviated; full table in the finalized brief) + +Each doc specifies: section list · included · excluded (with pointer to where it lives) · examples. Illustrative: + +- **`quickstart.md`** — §Install, §Minimal config, §Deploy local, §Read the record. _Excludes_ upgrades, RPC, custom strategies (→ L2/L3). _Example:_ a 3-facet local diamond. +- **`concepts/strategy-pattern.md`** — §Why strategies, §Base/Local/RPC, §The 15 lifecycle methods, §Extending via hooks. _Excludes_ the full worked subclass (→ `how-to-write-a-strategy.md`). _Example:_ the hook signatures from `BaseDeploymentStrategy`. +- **`concepts/upgrades-and-callbacks.md`** _(added per OP-4)_ — §Deploy-vs-upgrade detection, §How `DiamondDeployer` decides, §Post-deployment callbacks and when they run. _Excludes_ first-deploy pipeline (→ `deployment-model.md`) and per-facet versioning mechanics (→ `configuration-and-versioning.md`). _Example:_ an upgrade that adds one facet + a callback that initializes it. +- **`reference/verify-a-release.md`** — §What's in a release-evidence bundle, §The four spokes (Integrity/CommitIdentity/Content/Reproduction), §Running it as a fresh AI session. _Excludes_ the manifest schema internals (→ MC-12 brief). _Example:_ the auditor prompt skeleton. +- **`reference/api/*`** — **min:** exported symbol signatures + one-line description; **stretch:** params/returns/throws prose + example per symbol. Plan §5.3 cut point. + +### C.6 — Verification Approach + +- **AI proxy-reader test:** 5 questions against the deployed docs at **≥80%** correct (Plan §6.3 method). Question _text_ is refined in the **Verification brief (M1-E3)** and made Phase-6-executable in **Step 05**. +- **Auditor-persona check:** `reference/verify-a-release.md` specifically gets an auditor-reader pass (F-41): can a fresh AI session verify a release from the doc alone? +- **Link integrity:** link-checker clean (and — because links are navigational-only — a broken link never means a broken concept). + +### C.7 — Rejected Alternatives at IA Level + +| Alternative | Why rejected | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Flat single-README** (status quo, expanded) | Doesn't close F-25/F-40; no auditor surface; unmaintainable at scale | +| **Two-layer (Tutorial + Reference)** | Leaves the conceptual gap — readers can _do_ but not _understand_; weak mental model | +| **Tool-generated API docs only (TypeDoc)** | No conceptual layer, no auditor flow; F-41 unmet; generated prose reads poorly | +| **Four-layer (add a "Guides/How-To" layer)** | Over-couples: how-to docs cross-reference each other and cascade on cuts — weakens the Branch-2 mitigation. How-tos instead live _inside_ L3 reference as independent docs | + +## §3 — Phase 5 Estimate Refinement + +Per Plan §5.3, refinement is available at the **per-doc** level for L3 (high variance). Draft position: total IA authoring holds at the Plan estimate; the `reference/api/*` min/stretch band (C.5) is the primary variance carrier. _To confirm at reaction._ + +## §4 — Rejected Alternatives at Specification Level + +See C.7 (IA-level). No lower-level spec alternatives beyond those. + +## §5 — Per-Artifact Principle Scorecard Contribution (draft) + +| Principle | Wt | Draft verdict | Rationale | +| ------------------------ | ---- | ------------: | ------------------------------------------------------------------------------------- | +| Security | 1.5× | PASS | Docs specify no secret handling; migration doc uses placeholder ARN only | +| Maintainability | 1.5× | PASS | Layered IA + per-doc-cut safety + style guide = maintainable, extensible docs | +| Economics | 1.0× | PASS | Cut-staging (C.5) bounds authoring cost; style guide accelerates Phase-5 AI authoring | +| Operations | 1.0× | PASS | `verify-a-release.md` + monitoring content surfaces ops without elevation | +| Scoring & Metrics | 1.0× | PASS | Proxy-reader ≥80% is a measurable gate | +| Correctness Verification | 1.5× | PASS | C.6 proxy-reader + auditor-persona verification designed in | + +**Draft: 6 PASS.** _Pending OP-4 ratification._ + +## §6 — Phase 2 Invalidation Check + +**No.** MC-07 designs deferred v2.0 docs; nothing in the shipped 1.5.0 invalidates it. (Consistent with M0 no-amendment verdict.) + +## §7 — Phase 5 Implementability Check + +Implementable: each doc is independently authorable; the style guide is a reusable context package; L3 api can be cut to min. No blocking gaps. + +## §8 — Forward Handoff Notes + +- **Verification brief (M1-E3):** refine C.6 proxy-reader into an actual 5-question set (F.2.B). +- **Step 04:** the three cross-brief L3 docs (how-to-write-a-strategy, migration, verify-a-release) are shared artifacts — reconcile authorship/attribution. +- **Phase 5:** author in layer order L1→L2→L3; `reference/api/*` last (cut candidate). + +## §9 — Cross-Brief References + +- **MC-04 §2.5** → `reference/how-to-write-a-strategy.md` (LoggingDeploymentStrategy worked example). +- **MC-21 §2.4** → `reference/migration-v1-to-v2.md` (migration doc, co-authored; effort attributed to MC-04). +- **MC-12 §2.4** → `reference/verify-a-release.md` (four-spoke auditor flow). +- **[P3-Obs-09 note]:** the MC-21 cohort citation drift is a Step-04 fix, not an MC-07 concern. + +## §10 — Confidence and Code-Access Notes + +Docs reality grounded by direct repo read `[CONFIRM]`. Cross-brief anchors grounded on Session 1 artifacts `[CONFIRM]`. Layer/doc-set decisions are design proposals `[QUESTION]` pending OP-4 reaction. + +## Version History + +| Version | Date | Change | +| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| v0.1-draft | 2026-07-07 | Initial draft for OP-4 draft-and-react | +| v1.0 | 2026-07-07 | OP-4 ratified. Applied Owner reactions: L2 → 6 docs (added `upgrades-and-callbacks`); cut-safety rule accepted; api/\* min=signatures+one-liners. Finalized. | diff --git a/project/AICSDP/p3/step-03-observability-design-specification.md b/project/AICSDP/p3/step-03-observability-design-specification.md new file mode 100644 index 0000000..e4072e5 --- /dev/null +++ b/project/AICSDP/p3/step-03-observability-design-specification.md @@ -0,0 +1,137 @@ +# Step 03 Design Specification — Observability Touchpoints + +> **Artifact type:** Observability (sub-template E) · **Subject:** `@diamondslab/diamonds` v2.0 +> **Status:** ✅ **FINALIZED v1.0 — OP-5 ratified (question-by-question, Owner 2026-07-07)** · **Date:** 2026-07-07 +> **Central discipline:** **Operations stays 1.0×** — this is a baseline design a future-cycle Phase 2 can elevate cleanly. No silent elevation. +> **Inputs:** Plan §10.1 (intent), §10.3 (watch-triggers); MC-04 (15 lifecycle methods + `LoggingDeploymentStrategy`); MC-21 (Signer points); M0-E2 crossover note (real `release.yml`); MC-12 (publish flow); toolkit sub-template E. +> **Owner decisions:** vehicle = structured logging via `LoggingDeploymentStrategy`; depth = all 15 boundaries low-cardinality + outcome counters; alerting = define severities, defer infra. + +--- + +## §1 — Brief Intake Confirmation + +Observability supplementary brief (Plan §10.1): give the v2.0 chosen mechanisms observability hooks that a future-cycle Operations elevation can build on — **without** elevating Operations now (it stays 1.0×). First-design brief: no Plan design-question enumeration; questions discovered in-interview and ratified (OP-5). The design deliberately **reuses MC-04's `LoggingDeploymentStrategy`** as the observability vehicle rather than standing up new infrastructure — the cleanest baseline. + +## §2 — Design Specification + +### E.1 — Touchpoint Inventory + +Vehicle: **structured logging** emitted by `LoggingDeploymentStrategy` (MC-04 §2.5), which already logs entry/exit/throw for the 15 lifecycle methods + state transitions + tx hashes. Observability _reuses_ those emission points and adds a thin set of **outcome counters**. All low-cardinality (aggregatable). + +| Touchpoint | Mechanism location | Mode | Cardinality | +| ------------------------------------- | --------------------------------------------------------------------------- | -------------------------------- | ----------------------- | +| `lifecycle.method.{enter,exit,throw}` | Each of MC-04's 15 lifecycle methods (5 phases × pre/main/post) | Structured log | Low (method-name label) | +| `state.transition` | Each `diamond.updateDeployedDiamondData(...)` + registry Add/Replace/Remove | Structured log | Low | +| `onchain.tx` | Each `deploy()` / `diamondCut()` / callback tx | Structured log (tx hash field) | Low | +| `signer.resolved` | MC-21 refactored constructor — `signer.provider` resolution point | Structured log (no key material) | Low | +| `deploy.outcome` | `deploy()` completion | Counter (success/fail) | Low | +| `cut.outcome` | `diamondCut()` completion | Counter (success/fail) | Low | +| `callback.outcome` | post-deployment callback completion | Counter (success/fail) | Low | +| `ci.gate` | MC-11 `ci.yml` / MC-22 `dev-env-smoke.yml` job result | Event (CI-native) | Low | +| `publish.provenance` | MC-11 `release.yml` `npm publish --provenance` result | Event (CI-native) | Low | + +### E.2 — What Gets Observed + +| Touchpoint | Information | Operational question it answers | Sample rate | +| -------------------------------- | --------------------------------------------------------- | ------------------------------------------------------ | ---------------------- | +| `lifecycle.method.*` | method name, phase, duration, error (if throw) | Where in a deployment did time go / did it fail? | Always-on | +| `state.transition` | facet, selector count, Add/Replace/Remove | What did this deployment change? | Always-on | +| `onchain.tx` | tx hash, gas used | Is the on-chain effect auditable? | Always-on | +| `signer.resolved` | signer address, provider network (**never key material**) | Which signer/network did this run use? | Always-on | +| `*.outcome` counters | success/fail count by operation | What's the deploy/cut/callback failure rate over time? | Always-on (aggregated) | +| `ci.gate` / `publish.provenance` | job result, commit | Did the gate pass / did provenance generate? | Per-run | + +### E.3 — Alerting Thresholds + +**Baseline posture (OP-5):** define **severities** and the _conditions that would warrant an alert_, but **defer alerting/paging infrastructure** to the consuming application and a future-cycle Operations elevation. This is the deliberate 1.0× boundary — the design names the alert surface without building it. + +| Condition | Severity (defined, not wired) | Note | +| --------------------------------------- | ----------------------------- | ---------------------------------------------- | +| `deploy.outcome` / `cut.outcome` = fail | critical | Consumer wires paging; library logs at `error` | +| `callback.outcome` = fail | warning | Partial-deploy risk (MC-04 edge case) | +| `publish.provenance` = fail | critical (CI-native) | Blocks release; already fails the CI job | +| `ci.gate` (smoke) = fail | critical (CI-native) | MC-22 blocks merge | + +_No suppression/rate-limiting designed this cycle — deferred with the alerting infra (would be Operations-elevation work)._ + +### E.4 — Dashboard Sketches (guidance for Phase 4; not built here) + +- **Deployment History** — panels: deploys over time (by network), success/fail rate, mean lifecycle duration; filters: network, diamond, time. _Fed by `_.outcome`counters +`lifecycle.method._`._ +- **Release Evidence** — panels: last publish provenance status, commit-identity match, SBOM presence; filters: version. _Fed by `publish.provenance` + MC-12 bundle._ (Marked future/baseline.) + +### E.5 — Phase 7 Watch-Trigger Integration (Plan §10.3) + +Honest mapping — the observability touchpoints support the **operational** watch-triggers; several §10.3 triggers are **process/methodology** triggers with no code touchpoint (surfaced as an observation). + +| Watch-Trigger (§10.3) | Supporting touchpoint | Supported? | +| -------------------------------------------- | -------------------------------------------------------------- | ------------------ | +| First hotfix event → MTTR | `deploy.outcome` / `cut.outcome` + `lifecycle.method.*` timing | ✅ code-observable | +| First external adopter ramp-up (clone→green) | (none — process/Phase-6 proxy measurement) | ⚠️ process trigger | +| External-contributor doc adequacy | (none — MC-07 proxy-reader test) | ⚠️ process trigger | +| Feature-branch staleness >30 days | (none — repo/PR metadata, not runtime) | ⚠️ process trigger | +| Operations elevation deferred | this brief _is_ the baseline the trigger elevates | ✅ by design | +| AI-multiplier calibration | (none — Phase 7 ops-tracking of dev-hours) | ⚠️ process trigger | + +### E.6 — Rejected Observability Approaches + +| Alternative | Why rejected | +| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| **Metrics-first (Prometheus-style sink)** | Requires a metrics runtime the library lacks; pushes toward Operations elevation (deferred to future cycle) | +| **Distributed traces/spans** | Overkill for a deployment library at baseline; heavy to build and consume | +| **Full high-cardinality per-call labels** | Storage-costly, beyond baseline; low-cardinality aggregation suffices | +| **Specify + wire alert thresholds now** | Would silently elevate Operations to 1.5× — must route via Phase 2 amendment, not a brief | +| **New bespoke observability module** | `LoggingDeploymentStrategy` already exists (MC-04); reuse beats rebuild | + +## §3 — Phase 5 Estimate Refinement + +Minimal — the vehicle (`LoggingDeploymentStrategy`) is already estimated under MC-04; this brief adds only the thin outcome-counter layer + severity documentation. No material refinement; baseline holds. + +## §4 — Rejected Alternatives at Specification Level + +See E.6. + +## §5 — Per-Artifact Principle Scorecard Contribution + +| Principle | Wt | Verdict | Rationale | +| ------------------------ | -------- | ----------------------------: | ----------------------------------------------------------------------------------------------------------------------- | +| Security | 1.5× | PASS | `signer.resolved` logs address/network only, **never key material** (consistent with MC-04 no-redaction-but-no-secrets) | +| Maintainability | 1.5× | PASS | Reuses `LoggingDeploymentStrategy`; no new module to maintain | +| Economics | 1.0× | PASS | Low-cardinality; no metrics infra cost; counter layer is cheap | +| **Operations** | **1.0×** | **PASS (baseline preserved)** | Touchpoints + severities designed; **alerting infra explicitly deferred** — no silent elevation | +| Scoring & Metrics | 1.0× | PASS | `*.outcome` counters give measurable deploy/cut/callback rates | +| Correctness Verification | 1.5× | PASS | `onchain.tx` + `state.transition` logs give an auditable deployment trail | + +**6 PASS.** Operations integrity confirmed at 1.0× (no elevation). + +## §6 — Phase 2 Invalidation Check + +**No.** Baseline observability over deferred v2.0 mechanisms; nothing in shipped 1.5.0 invalidates it. Consistent with M0 no-amendment. + +## §7 — Phase 5 Implementability Check + +Implementable: the log points exist in `LoggingDeploymentStrategy`; the counter layer is a thin wrapper; severities are documentation. No blocking gaps. + +## §8 — Forward Handoff Notes + +- **Future-cycle Phase 2:** this baseline is the clean elevation surface — a re-weighting to Operations 1.5× would wire alerting (E.3), suppression, dashboards (E.4), and possibly a metrics sink. +- **Step 04:** the `LoggingDeploymentStrategy` reuse is a shared dependency with MC-04 — coordinate. +- **Phase 4:** E.4 dashboard sketches are the input to architecture. + +## §9 — Cross-Brief References + +- **MC-04** — `LoggingDeploymentStrategy` is the observability vehicle; the 15 lifecycle methods are the touchpoint inventory. +- **MC-21** — refactored Signer resolution is the `signer.resolved` touchpoint (address/network only). +- **MC-11 (shipped `release.yml`) / MC-22** — CI + publish-provenance events (`ci.gate`, `publish.provenance`), grounded on the real workflow (M0-E2). +- **MC-12** — publish flow feeds the Release-Evidence dashboard sketch. + +## §10 — Confidence and Code-Access Notes + +Lifecycle methods + `LoggingDeploymentStrategy` grounded on MC-04 Session 1 brief `[CONFIRM]`; real `release.yml` grounded via M0-E2 `[CONFIRM]`; watch-triggers from Plan §10.3 `[CONFIRM]`. Touchpoint set is a ratified design `[CONFIRM via OP-5]`. + +**New observation — P3-Obs-12:** several Plan §10.3 watch-triggers are process/methodology triggers with no runtime code touchpoint; the Observability sub-template E.5 assumes touchpoint-backable triggers. E.5 handled it by marking process triggers explicitly, but the toolkit could distinguish "code-observable" vs "process" watch-triggers. Route: Phase 3 v1.1. + +## Version History + +| Version | Date | Change | +| ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| v1.0 | 2026-07-07 | Initial authoring; OP-5 ratified (structured-logging vehicle; all-15 low-cardinality + counters; alerting deferred). 6 PASS, Operations 1.0× preserved. | diff --git a/project/AICSDP/p3/step-03-verification-design-specification.md b/project/AICSDP/p3/step-03-verification-design-specification.md new file mode 100644 index 0000000..887ff7b --- /dev/null +++ b/project/AICSDP/p3/step-03-verification-design-specification.md @@ -0,0 +1,160 @@ +# Step 03 Design Specification — Verification Artifacts + +> **Artifact type:** Verification (sub-template F) · **Subject:** `@diamondslab/diamonds` v2.0 +> **Status:** ✅ **FINALIZED v1.0 — OP-6 ratified (question-by-question, Owner 2026-07-07)** · **Date:** 2026-07-07 +> **Central discipline:** **instruments, not descriptions.** This brief produces instrument _specifications with worked examples_; **Step 05** refines them to full Phase-6-executable form. This is the **Correctness-Verification CONDITIONAL resolution path**. +> **Inputs:** the four primaries' verification methods (MC-04 conformance, MC-21 MK-01, MC-07 proxy-reader C.6, MC-12 four-spoke auditor); M0-E2 MC-12 grounding (real `release.yml`, provenance-only insufficient for F-41); toolkit sub-template F. +> **Owner decisions:** concreteness = shape + 2–3 worked examples, defer full enumeration to Step 05; execution = CI-gated code instruments + pre-release reader/auditor; MC-12 auditor targets the v2.0 six-file bundle (notes the 1.5.0 gap). + +--- + +## §1 — Brief Intake Confirmation + +Verification supplementary brief (Plan §10.1): produce the _instrument specifications_ for the four primaries' verification methods, resolving Phase 2's CV CONDITIONAL. Per OP-6, each instrument is specified as **shape + 2–3 fully-worked representative examples** — enough to be an instrument (not a description) while leaving full enumeration to Step 05. Dominant lens: **Correctness Verification 1.5×**. + +## §2 — Design Specification + +### F.1 — Verification Instrument Inventory + +| Instrument | Verifies | Scope | Phase 6 execution | +| ------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------- | ------------------------------------- | +| **I-1 Conformance Suite** (F.2.A) + **Harness** (F.2.D) | MC-04 `IDeploymentStrategy` conformance | 17 tests, 3 categories; any strategy subclass | **Per-PR CI** (block merge) | +| **I-2 MK-01 Byte-Identity Test** (F.2.A) | MC-21 refactor preserves deployment output | Structural byte-identity of deploy artifacts pre/post refactor | **Per-PR CI** (block merge) | +| **I-3 Proxy-Reader Question Set** (F.2.B) | MC-07 IA reader-readiness | 5 questions ≥80% against deployed docs | **Pre-release** (fresh AI session) | +| **I-4 Auditor-Persona Prompt** (F.2.C) | MC-12 release-evidence reproducibility (F-41) | Four-spoke flow over the v2.0 six-file bundle | **Pre-release** (external AI auditor) | + +### F.2.A — Test Suite (I-1 Conformance + I-2 MK-01) + +**I-1 Conformance Suite — 17 tests, 3 categories** (MC-04 §2.4): + +- **Category 1 — Lifecycle (5):** each of the 5 phases invokes its pre/main/post hooks in order. +- **Category 2 — Post-condition (7):** each lifecycle method leaves the documented state. +- **Category 3 — Edge-case (5):** partial deployment, deployment-record migration, multi-call atomicity, etc. + +_Worked examples (the pattern Step 05 enumerates fully):_ + +| ID | Input | Expected output | Predicate | +| ------------ | ------------------------------------------ | ---------------------------------------------------------- | ---------------------------------------------------------- | +| C1-01 | A strategy subclass; run `deployDiamond()` | pre→main→post hooks fire in order for the Deploy phase | assert call-order log == `[preDeploy, deploy, postDeploy]` | +| C2-03 | After `diamondCut()` | deployment record's facet selectors updated to the cut set | `record.selectors === expectedSelectors` | +| C3-02 (edge) | `diamondCut()` throws mid-multi-call | no partial state persisted (atomicity) | `record` unchanged from pre-call snapshot | + +- **Coverage targets:** all 15 lifecycle methods; the 3 documented edge cases from MC-04 Branch-1 mitigation. +- **Failure handling:** **block merge** (per-PR CI). Conformance output JSON (`diamonds-conformance-v1.0`) is the artifact MC-12's bundle references. + +**I-2 MK-01 Byte-Identity Test** (MC-21): + +- _Worked example:_ deploy a fixture diamond with the **v1.3.2** `RPCDeploymentStrategy` (via `ethers.Wallet`) and with the **v2.0** Signer-injected strategy (same Wallet as Signer); assert the produced deployment artifacts (addresses modulo nonce, selector sets, cut calldata) are **structurally byte-identical**. +- **Predicate:** `normalize(artifact_v1) === normalize(artifact_v2)` where `normalize` strips address/nonce nondeterminism. +- **Failure handling:** block merge — the refactor must not change deployment output. + +### F.2.B — Proxy-Reader Question Set (I-3, MC-07) + +- **Success criteria:** 5 questions, **≥80%** correct (4/5), against the deployed v2.0 docs (MC-07 IA). +- **Question-generation discipline:** one question per reader need — install, core concept, extension, migration, verification — spanning all three IA layers. + +_Worked examples (2 of 5; Step 05 finalizes all 5 + answer keys):_ + +1. _(L1)_ "Following only the Quickstart, what command deploys a diamond locally, and where is the deployment record written?" — tests L1 self-sufficiency. +2. _(L3, auditor-adjacent)_ "Using only `reference/verify-a-release.md`, list the four verification spokes and which one checks SHA-256 integrity." — tests F-41 reader-readiness. + +- **Grounds on** MC-07 §C.6; Step 05 turns these into executable question+answer-key pairs. + +### F.2.C — Auditor-Persona Prompt (I-4, MC-12) + +- **Persona:** an external smart-contract auditor, fresh AI session, **no practitioner support**, given only an npm package URL + a GitHub release URL; motivated to confirm the published code matches released source (F-41). +- **Target (per OP-6):** the **v2.0 six-file evidence bundle + four-spoke flow**. **Grounding note (M0-E2):** the shipped **1.5.0 `release.yml` produces `npm publish --provenance` only** — one of the six artifacts — which MC-12 §2.6 deemed insufficient for F-41. This instrument therefore verifies the _v2.0 target_ the six-file bundle is designed to reach, and its existence documents the gap between 1.5.0 (provenance-only) and the v2.0 auditor-reproducible target. + +_Worked prompt skeleton (Step 05 finalizes full text + expected-output rubric):_ + +``` +You are an external auditor. You have ONLY: , . +No practitioner will answer questions. Using the release-evidence manifest as your +entry point, execute the four spokes: + A Integrity — verify each file's SHA-256 matches the manifest. + B CommitIdentity — verify manifest.release.commit == GitHub release commit == npm provenance commit. + C Content — review the SBOM (CycloneDX 1.5), conformance output, and migration doc. + D Reproduction — (optional) yarn install --frozen-lockfile against the lockfile; confirm SBOM consistency. +Report per spoke: verified / discrepancies-found / incomplete. +``` + +- **Expected output:** all four spokes "verified" for a well-formed release; a seeded discrepancy (e.g. mismatched SHA) must be caught by Spoke A. + +### F.2.D — Conformance Harness (I-1) + +- **Harness scope:** exercises the MC-04 conformance properties against _any_ `IDeploymentStrategy` implementation (self-conformance for Base/Local/RPC; regression detection; external-strategy conformance). +- **Input set:** the 3 built-in strategies + a property-based generator for hook-ordering sequences. +- **Verification predicate:** for every method, observed pre/main/post ordering and post-conditions satisfy the Category-1/2 specs; edge inputs satisfy Category-3. + +### F.3 — Cross-Brief Integration + +| Instrument | Brief(s) verified | Method | +| ------------------------- | -------------------------------------------------------------------------------- | ------------------------------------ | +| I-1 Conformance + Harness | MC-04 | Per-PR CI; output feeds MC-12 bundle | +| I-2 MK-01 | MC-21 | Per-PR CI byte-identity | +| I-3 Proxy-Reader | MC-07 | Pre-release AI session ≥80% | +| I-4 Auditor-Persona | MC-12 (+ transitively MC-04 conformance output, MC-21 migration doc via Spoke C) | Pre-release external auditor | + +Step 04 consumes this to line instruments up with the artifacts they verify; Step 05 refines each to executable form. + +### F.4 — Rejected Verification Approaches + +| Alternative | Why rejected | +| ------------------------------------------ | -------------------------------------------------------------- | +| Full enumeration in Step 03 | Duplicates Step 05; single-session fatigue risk (OP-6) | +| Descriptions only (no worked examples) | Reads as "descriptions not instruments" → CV stays CONDITIONAL | +| All instruments pre-release manual | Loses per-PR regression protection on conformance + MK-01 | +| Auditor verifies 1.5.0 provenance-only | Doesn't drive toward the F-41 target the brief exists for | +| Human-only conformance review (no harness) | Not repeatable; fails regression-detection purpose | + +## §3 — Phase 5 Estimate Refinement + +Instrument _specification_ is bounded; the variance lives in Step 05's full enumeration (17 cases, 5 questions, full prompt). No material Step-03 refinement. + +## §4 — Rejected Alternatives at Specification Level + +See F.4. + +## §5 — Per-Artifact Principle Scorecard Contribution + +| Principle | Wt | Verdict | Rationale | +| ---------------------------- | -------- | -------: | --------------------------------------------------------------------------------------------------------------------------------------- | +| Security | 1.5× | PASS | Auditor instrument verifies provenance/commit-identity; no secret handling | +| Maintainability | 1.5× | PASS | Harness makes conformance repeatable; instruments are reusable | +| Economics | 1.0× | PASS | CI-gated vs pre-release split matches cost to value | +| Operations | 1.0× | PASS | Pre-release auditor + CI gates are operational checkpoints (baseline) | +| Scoring & Metrics | 1.0× | PASS | ≥80% proxy-reader threshold; pass/fail conformance counts | +| **Correctness Verification** | **1.5×** | **PASS** | Four concrete instruments with worked examples + predicates + execution discipline — **resolves the CV CONDITIONAL** (Step 06 confirms) | + +**6 PASS.** CV instruments are concrete (not descriptions) → CV CONDITIONAL → **PASS** trajectory established; Step 05 refinement + Step 06 gate confirm. + +## §6 — Phase 2 Invalidation Check + +**No.** Instruments verify deferred v2.0 work; the MC-12 grounding is an update, not an invalidation (M0-E2). Amendment package stays empty. + +## §7 — Phase 5 Implementability Check + +Implementable: conformance suite + harness are standard TS tests; MK-01 is a fixture+predicate; proxy-reader/auditor are AI-session runbooks. Step 05 produces the executable content. No blocking gaps. + +## §8 — Forward Handoff Notes + +- **Step 05 (Verification Strategy):** enumerate I-1's 17 cases fully; write I-3's 5 questions + answer keys; write I-4's full prompt + expected-output rubric; refine I-2 to a concrete fixture+predicate. +- **Step 06:** this brief + Step 05 are what move CV CONDITIONAL → PASS. +- **Phase 6:** wire I-1/I-2 into per-PR CI; schedule I-3/I-4 pre-release. + +## §9 — Cross-Brief References + +- **MC-04** — 17-test conformance suite + harness (I-1); conformance output feeds MC-12 bundle. +- **MC-21** — MK-01 structural byte-identity (I-2). +- **MC-07** — proxy-reader question set (I-3) grounds on §C.6. +- **MC-12** — auditor-persona (I-4) targets the v2.0 six-file bundle; carries the M0-E2 provenance-only gap note. + +## §10 — Confidence and Code-Access Notes + +Verification methods grounded on Session 1 briefs `[CONFIRM]`; MC-12 grounding on M0-E2 + real `release.yml` `[CONFIRM]`; instrument shapes ratified `[CONFIRM via OP-6]`. Full instrument _content_ intentionally deferred to Step 05 `[AWARE]`. + +## Version History + +| Version | Date | Change | +| ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| v1.0 | 2026-07-07 | Initial authoring; OP-6 ratified (shape+worked-examples; CI/pre-release split; auditor targets v2.0 bundle w/ 1.5.0 gap note). 6 PASS; CV CONDITIONAL→PASS trajectory established. | diff --git a/project/AICSDP/p3/step-04-inter-artifact-coordination.md b/project/AICSDP/p3/step-04-inter-artifact-coordination.md new file mode 100644 index 0000000..87080f3 --- /dev/null +++ b/project/AICSDP/p3/step-04-inter-artifact-coordination.md @@ -0,0 +1,83 @@ +# Step 04 — Inter-Artifact Coordination Register + +> **Status:** ✅ FINALIZED v1.0 — OP-7 ratified (draft-and-react, Owner 2026-07-07) · **Date:** 2026-07-07 +> **Consumes:** the six Step 03 briefs' §9 Cross-Brief References (MC-04, MC-21, MC-12 [Session 1]; MC-07, Observability, Verification [M1]) + M0 crossover note. **Interview mode:** draft-and-react. + +--- + +## §0 — Phase-2 Invalidations Surfaced in Step 03 + +**Empty.** All six briefs produced Phase-2 invalidation check = **No** (Session 1: MC-04/MC-21/MC-12; M1: MC-07 §6, Observability §6, Verification §6). Consistent with the M0 no-amendment verdict. Step 06 §7 Amendment Package stays empty. + +## §1 — Cross-Artifact References (bidirectional) + +| Source brief §9 ref | Target | Back-reference present? | +| ------------------------------------------- | -------------------------------- | ---------------------------------------------- | +| MC-04 → migration doc | MC-21 | ✅ MC-21 §2.4 → migration doc (co-authored) | +| MC-04 → conformance output consumed by | MC-12 | ✅ MC-12 §2.1 `files.conformance` | +| MC-04 → LoggingDeploymentStrategy reused by | Observability | ✅ Observability §9 → MC-04 vehicle | +| MC-21 → migration doc | MC-04 | ✅ (bidirectional; effort attributed to MC-04) | +| MC-12 → conformance format | MC-04 | ✅ MC-04 §2.4 release-evidence tier | +| MC-07 → how-to-write-a-strategy | MC-04 | ✅ (LoggingDeploymentStrategy worked example) | +| MC-07 → migration-v1-to-v2 | MC-21 | ✅ | +| MC-07 → verify-a-release | MC-12 | ✅ (four-spoke) | +| Observability → Signer resolution | MC-21 | ✅ | +| Observability → publish/CI events | MC-11 (real release.yml) / MC-12 | ✅ (M0 grounding) | +| Verification I-1..I-4 → four primaries | MC-04/21/07/12 | ✅ (§5 below) | + +All references are bidirectional or intentionally one-way (noted). No dangling references. + +### §1.1 — P3-Obs-09 Reconciliation (cohort citation drift) + +**Fixed here (register-level).** The MC-21 Session 1 artifact §2.4 cites the coordinated cohort as _"MC-04 + MC-21 + MC-22 + MC-13 per Plan §5.2."_ **Correction:** the cohort is defined in **Plan §2.2** (not §5.2, which is "Stretch Scope"), and is a **five-member** set that **includes MC-05**: **MC-05 + MC-04 + MC-21 + MC-22 + MC-13** (see §4). This register is the authoritative cohort statement; the MC-21 artifact erratum is logged for the M4 review (P3-Obs-09) rather than rewritten here. + +## §2 — Latent Cross-References Surfaced in Step 04 + +- **Observability ↔ Verification:** the `*.outcome` counters (Observability E.1) and the `onchain.tx`/`state.transition` logs are _evidence sources_ the I-1 conformance harness and I-4 auditor can draw on. Latent but non-conflicting — noted for Phase 5. +- **MC-07 verify-a-release ↔ MC-12 auditor / Verification I-4:** the L3 reference doc and the auditor-persona instrument describe the same four-spoke flow from two angles (reader doc vs verification instrument). Keep them consistent in Phase 5 (single source: MC-12 §2.4). + +## §3 — Shared Design Decisions + +| Shared artifact | Briefs | Attribution / rule | +| -------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| `examples/migration-v1-to-v2.md` | MC-04 + MC-21 (+ MC-07 references it) | Co-authored; **effort attributed to MC-04** (double-count avoidance) | +| `LoggingDeploymentStrategy` | MC-04 (defines) + Observability (reuses as vehicle) | Single implementation; Observability adds only the counter layer | +| Conformance output (`diamonds-conformance-v1.0`) | MC-04 (produces) + MC-12 (bundles) + Verification I-1 (executes) | Format defined by MC-04 Phase 5; consumed by MC-12 manifest `files.conformance` | +| `reference/verify-a-release.md` ↔ auditor-persona | MC-07 + MC-12 + Verification I-4 | Single four-spoke source (MC-12 §2.4) | + +## §4 — Phase 5 Implementation Ordering + Coordinated Landing Cohort + +**Coordinated Landing Cohort (v2.0 entry, Plan §2.2):** **MC-05 + MC-04 + MC-21 + MC-22 + MC-13** land together as the single v2.0 breaking release. + +- **MC-05** (OZDefender cascade-delete) — still shipped as-is in 1.5.0 (M0 crossover); removed at v2.0. +- **MC-04** (IDeploymentStrategy) → anchor; **MC-21** (Signer refactor) depends on MC-04; **MC-22** (dev-env-smoke.yml) depends on MC-04+MC-05+MC-21; **MC-13** (v2.0 CHANGELOG) documents the breaking set. + +**Ordering:** MC-04 → MC-21 → MC-05 → MC-22 → MC-13; docs (MC-07) and observability/verification instruments author in parallel; MC-12 evidence bundle extends the already-shipped `release.yml` last. + +## §5 — Verification Dependencies (→ Step 05 input) + +| Instrument | Verifies | Execution | +| ------------------------------- | --------------------------------------------------------------------- | ----------- | +| I-1 Conformance suite + harness | MC-04 | Per-PR CI | +| I-2 MK-01 byte-identity | MC-21 | Per-PR CI | +| I-3 Proxy-reader question set | MC-07 | Pre-release | +| I-4 Auditor-persona prompt | MC-12 (+ transitively MC-04 conformance, MC-21 migration via Spoke C) | Pre-release | + +This is the direct input to Step 05 (M2-E2), which refines each to Phase-6-executable form. + +## §6 — Inter-Brief Conflicts + +**None found.** The six briefs are mutually consistent: shared artifacts have single owners (§3), references are bidirectional (§1), and no two briefs specify conflicting behavior for the same mechanism. The only reconciliation item was the P3-Obs-09 citation drift (§1.1), which is a citation error, not a design conflict. + +## §7 — Coordination Confidence and Open Questions + +- **Confidence:** High. All cross-references verified; cohort reconciled; no conflicts. +- **Open questions:** none blocking. The Observability↔Verification latent evidence-sharing (§2) is a Phase 5 note, not a Phase 3 gap. +- **New observation P3-Obs-13:** the four-spoke flow is described in three places (MC-12 §2.4, MC-07 `verify-a-release.md`, Verification I-4). Coordination resolved it to a single source (MC-12 §2.4), but the toolkit could prompt Step 03 to declare a "single source of truth" for artifacts referenced by 3+ briefs. Route: Phase 3 v1.1. + +## Version History + +| Version | Date | Change | +| ---------- | ---------- | ------------------------------------------------------------------------------- | +| v0.1-draft | 2026-07-07 | Initial Coordination Register draft for OP-7 | +| v1.0 | 2026-07-07 | OP-7 ratified (no conflicts; P3-Obs-09 reconciled; cohort recorded). Finalized. | diff --git a/project/AICSDP/p3/step-05-verification-strategy.md b/project/AICSDP/p3/step-05-verification-strategy.md new file mode 100644 index 0000000..1f22674 --- /dev/null +++ b/project/AICSDP/p3/step-05-verification-strategy.md @@ -0,0 +1,119 @@ +# Step 05 — Verification Strategy (Phase-6-Executable Instruments) + +> **Status:** ✅ FINALIZED v1.0 — OP-8 ratified (draft-and-react, Owner 2026-07-07) · **Date:** 2026-07-07 +> **Consumes:** Verification brief F.2 (M1-E3); Coordination Register §5 (M2-E1); Plan §6 per-MC verification methods. **Central discipline:** instruments, not descriptions. **Interview mode:** draft-and-react. +> **Purpose:** refine I-1..I-4 into Phase-6-executable form so Step 06 moves Correctness Verification CONDITIONAL → PASS. + +--- + +## I-1 — Conformance Suite (MC-04) — 17 cases enumerated + +**Execution:** per-PR CI, block-merge. **Output:** `diamonds-conformance-v1.0` JSON (bundled by MC-12). + +**Category 1 — Lifecycle (5): each phase invokes pre/main/post in order.** + +| ID | Input | Expected | Predicate | +| -------------- | ------------------------------------ | --------------------------------------- | ---------------------- | +| C1-01 Deploy | subclass; `deployDiamond()` | order `[preDeploy, deploy, postDeploy]` | `callLog === expected` | +| C1-02 Cut | pending facet change; `diamondCut()` | `[preCut, cut, postCut]` | `callLog === expected` | +| C1-03 Callback | post-deploy callback registered | `[preCallback, callback, postCallback]` | `callLog === expected` | +| C1-04 Registry | facet add/replace/remove | `[preRegistry, registry, postRegistry]` | `callLog === expected` | +| C1-05 Verify | post-deploy verification phase | `[preVerify, verify, postVerify]` | `callLog === expected` | + +**Category 2 — Post-condition (7): each method leaves documented state.** + +| ID | After | Predicate | +| ----- | ----------------------------- | ------------------------------------------------------ | +| C2-01 | `deployDiamond()` | `record.diamondAddress` set; `record.facets` populated | +| C2-02 | `diamondCut()` add | selectors ∪ new; no collisions | +| C2-03 | `diamondCut()` replace | selector→facet remapped; count stable | +| C2-04 | `diamondCut()` remove | selectors ∖ removed | +| C2-05 | callback | callback side-effect state present | +| C2-06 | `updateDeployedDiamondData()` | persisted record == in-memory | +| C2-07 | verify phase | on-chain selectors == record selectors | + +**Category 3 — Edge-case (5): MC-04 Branch-1 mitigation.** + +| ID | Scenario | Predicate | +| ----- | ------------------------------------------- | ---------------------------------------------------- | +| C3-01 | partial deployment (fail mid-facet) | no diamond address persisted; record rolled back | +| C3-02 | multi-call atomicity (cut throws mid-batch) | record unchanged from pre-call snapshot | +| C3-03 | deployment-record migration (old schema) | migrated record validates against current Zod schema | +| C3-04 | re-deploy detection | `DiamondDeployer` upgrades, does not re-create | +| C3-05 | selector collision | collision detected; deploy aborts with typed error | + +**Failure handling:** any case fails → block merge. **Coverage:** all 15 lifecycle methods + 3 documented edge cases. + +## I-2 — MK-01 Byte-Identity Test (MC-21) — fixture + predicate + +**Fixture:** deploy a fixed 3-facet diamond twice against the same `ethers.Wallet` — once via v1.3.2 `RPCDeploymentStrategy(rpcUrl, privateKey, …)`, once via v2.0 `RPCDeploymentStrategy(signer, …)` with `signer = new ethers.Wallet(privateKey, provider)`. + +**Predicate:** + +``` +normalize(artifact) = strip {addresses, nonces, timestamps, gasPrice} → { selectorSets, cutCalldata (minus addr), facetOrder } +assert deepEqual( normalize(v1_artifact), normalize(v2_artifact) ) +``` + +**Execution:** per-PR CI, block-merge. **Verifies:** the Signer refactor changes the _injection surface_ only, not deployment output (SR-03 closure; MK-01 preserved). + +## I-3 — Proxy-Reader Question Set (MC-07) — 5 questions + answer keys + +**Success:** ≥80% (4/5) correct, fresh AI session against the deployed v2.0 docs. One question per reader need, spanning all three layers. + +| # | Layer | Question | Answer key | +| --- | ---------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| Q1 | L1 | "Using only the Quickstart, what command deploys a diamond locally and where is the record written?" | the documented deploy command; record path under the configured deployments dir | +| Q2 | L2 | "Name the three built-in deployment strategies and what distinguishes RPC from Local." | Base/Local/RPC; RPC uses an injected Signer/remote provider vs Local's Hardhat network | +| Q3 | L2→L3 | "To add a custom strategy, which base class do you extend and which methods are the extension hooks?" | `BaseDeploymentStrategy`; the `protected async …Tasks()` pre/main/post hooks | +| Q4 | L3 | "From the migration doc, what constructor change does v2.0 make to RPCDeploymentStrategy?" | `privateKey: string` → `signer: Signer` (clean break, no shim) | +| Q5 | L3/auditor | "From verify-a-release, list the four spokes and which checks SHA-256 integrity." | Integrity/CommitIdentity/Content/Reproduction; Spoke A = SHA-256 | + +**Discipline:** questions chosen to be representative of real reader needs (install, concept, extension, migration, verification). + +## I-4 — Auditor-Persona Prompt (MC-12) — full prompt + rubric + +**Persona:** external smart-contract auditor; fresh AI session; only an npm URL + GitHub release URL; no practitioner support; goal = confirm published code matches released source (F-41). **Target:** v2.0 six-file bundle + four spokes. **Grounding (M0-E2):** shipped 1.5.0 `release.yml` produces `npm publish --provenance` only (1 of 6 artifacts) — this instrument verifies the v2.0 target and documents that gap. + +**Prompt:** + +``` +You are an independent smart-contract release auditor. You have ONLY: + • npm package URL: + • GitHub release URL: <…/releases/tag/v2.0.0> +No maintainer will answer questions. Starting from the release-evidence manifest +(diamonds-v2.0.0-release-evidence.json) as your entry point, execute: + Spoke A — Integrity: verify each listed file's SHA-256 == manifest.files[*].sha256. + Spoke B — CommitIdentity: verify manifest.release.commit == GitHub release commit == npm provenance commit. + Spoke C — Content: review the CycloneDX 1.5 SBOM, the conformance output, and the migration doc for coherence. + Spoke D — Reproduction: (optional) yarn install --frozen-lockfile against the bundled lockfile; confirm SBOM consistency. +Report, per spoke: verified | discrepancies-found | incomplete — with the evidence you used. +``` + +**Expected-output rubric:** + +- Well-formed release → all four spokes "verified". +- **Seeded-discrepancy check** (test harness): corrupt one file's bytes so its SHA ≠ manifest → **Spoke A must report "discrepancies-found"**; failure to catch = instrument defect. +- Missing provenance (the current 1.5.0 state) → Spoke B "incomplete" (documents the v2.0 gap). + +## §5 — Executability & CV-Resolvable Check + +| Instrument | Executable? | Coverage gap? | +| ---------------- | -------------------------------------- | ----------------------------------------- | +| I-1 Conformance | ✅ 17 concrete case tuples | none | +| I-2 MK-01 | ✅ fixture + normalize predicate | none | +| I-3 Proxy-reader | ✅ 5 Qs + answer keys | none | +| I-4 Auditor | ✅ full prompt + rubric + seeded check | 1.5.0 provenance-only noted (v2.0 target) | + +**All four instruments are Phase-6-executable, not descriptions.** Consistent with Coordination Register §5. **The Correctness-Verification CONDITIONAL is RESOLVABLE** — Step 06 scorecard refresh reports CV → PASS. + +## §6 — New Observations + +- **P3-Obs-14:** Step 05 for a first-design Verification brief mostly _enumerates_ the Step 03 shape; the toolkit could note that a well-specified F.2 (shape + worked examples) makes Step 05 near-mechanical — a positive signal that the OP-6 "shape + worked examples" choice paid off. Route: Phase 3 v1.1 (methodology insight, low priority). + +## Version History + +| Version | Date | Change | +| ---------- | ---------- | -------------------------------------------------------------------------------------------- | +| v0.1-draft | 2026-07-07 | Initial Verification Strategy; four instruments refined to Phase-6-executable; CV resolvable | +| v1.0 | 2026-07-07 | OP-8 ratified. Finalized. | diff --git a/project/AICSDP/p3/step-06-design-specification-synthesis.md b/project/AICSDP/p3/step-06-design-specification-synthesis.md new file mode 100644 index 0000000..324ec24 --- /dev/null +++ b/project/AICSDP/p3/step-06-design-specification-synthesis.md @@ -0,0 +1,92 @@ +# Step 06 — Design Specification Bundle (Phase 3 Capstone) + +> **Status:** ✅ FINALIZED v1.0 — synthesis-only; Owner gate result reviewed · **Date:** 2026-07-07 +> **Consumes:** Steps 01–05 (all finalized) + Phase 2 Plan §9 scorecard. **Discipline:** synthesis-only — no net-new design decisions (none surfaced). +> **Subject:** `@diamondslab/diamonds` — Phase 3 (Design & Technical Analysis) complete. + +--- + +## §0 — Improvement Plan Currency Re-Verification + +**Passes.** Phase 2 Plan unchanged since M0 (Plan Date 2026-05-22; subject v1.3.2 as-written; no amendments). Subject-version drift v1.3.2 → v1.5.0 recorded (M0-E1); the shipped 1.5.0 is packaging/release only and does not touch the deferred v2.0 design surface (M0-E2). No re-anchor needed. + +## §1 — Design Specification Catalog + +| # | Brief | Type | Session | Scorecard | Status | +| --- | --------------------------------- | ----------------- | ------- | ----------------- | ------ | +| 1 | MC-04 Strategy Extension Contract | Contract (A) | 1 | 6 PASS | ✅ | +| 2 | MC-21 Signer-Injection Refactor | Refactor (B) | 1 | 6 PASS | ✅ | +| 3 | MC-12 Release Evidence Schema | Schema (D) | 1 | 6 PASS | ✅ | +| 4 | MC-07 Information Architecture | IA (C) | 2 | 6 PASS | ✅ | +| 5 | Observability Touchpoints | Observability (E) | 2 | 6 PASS (Ops 1.0×) | ✅ | +| 6 | Verification Artifacts | Verification (F) | 2 | 6 PASS (CV path) | ✅ | + +All six Step 03 briefs authored to the toolkit output format. **Step 03 complete.** + +## §2 — Coordination Map (fold-in of Step 04) + +From the [Coordination Register](./step-04-inter-artifact-coordination.md): §0 invalidations empty; cross-references bidirectional; **no inter-brief conflicts**. Shared artifacts (single-owner): `examples/migration-v1-to-v2.md` (MC-04+MC-21, effort→MC-04), `LoggingDeploymentStrategy` (MC-04+Observability), conformance output (MC-04→MC-12→Verification I-1), four-spoke flow (single source MC-12 §2.4). **Coordinated Landing Cohort (v2.0):** MC-05 + MC-04 + MC-21 + MC-22 + MC-13 (Plan §2.2). P3-Obs-09 cohort-citation drift reconciled in the register. + +## §3 — Verification Strategy (fold-in of Step 05) + +From the [Verification Strategy](./step-05-verification-strategy.md): four instruments refined to **Phase-6-executable** form — I-1 (17 conformance cases), I-2 (MK-01 fixture+predicate), I-3 (5 proxy-reader Qs+keys), I-4 (full auditor prompt+rubric w/ seeded-discrepancy check). Execution: CI-gated code instruments (I-1/I-2), pre-release reader/auditor (I-3/I-4). **All executable, not descriptions.** + +## §4 — Phase-3-Level Scorecard Refresh + +Aggregate of the six per-artifact scorecards, compared to Phase 2 §9: + +| Principle | Wt | Phase 2 §9 | Phase 3 aggregate | Change | +| ---------------------------- | ---- | --------------- | ----------------- | ----------------------------------------------------------------------------------------------------- | +| Security | 1.5× | PASS | **PASS** | held | +| Maintainability | 1.5× | PASS | **PASS** | held | +| Economics | 1.0× | PASS | **PASS** | held | +| **Operations** | 1.0× | **CONDITIONAL** | **PASS** | ⬆ resolved — Observability brief designed baseline touchpoints at 1.0× (no silent elevation) | +| Scoring & Metrics | 1.0× | PASS | **PASS** | held | +| **Correctness Verification** | 1.5× | **CONDITIONAL** | **PASS** | ⬆ resolved — Verification brief + Step 05 produced Phase-6-executable instruments (not descriptions) | + +**Both Phase-2 CONDITIONALs resolved to PASS. No FAIL.** + +## §5 — Forward Handoffs + +- **Phase 4 (Architecture):** Observability E.4 dashboard sketches; MC-07 IA as the docs-site structure; MC-12 bundle-emission CI job design. +- **Phase 5 (Implementation):** the Coordinated Landing Cohort + ordering (§2); MC-07 per-doc cut-staging (author L1→L2→L3, api/\* last at min-scope); MC-04 `IDeploymentStrategy` + `LoggingDeploymentStrategy`; MC-21 Signer refactor; the six-file MC-12 evidence job extending the shipped `release.yml`. +- **Phase 6 (Testing & Audit):** execute the four instruments — I-1/I-2 per-PR CI; I-3/I-4 pre-release. +- **Phase 7 (Deployment & Evolution):** the §10.3 watch-triggers (Observability E.5 marks code-observable vs process); v2.0 launch. +- **Next-cycle Phase 2:** Operations elevation to 1.5× (the Observability baseline is the clean surface); `diamonds-safe`/NTI-03 (`SafeDeploymentStrategy` — explicitly future-cycle, not this cycle's `LoggingDeploymentStrategy`); the deferred stretch MCs. + +## §6 — Bundle Self-Evaluation Scorecard (Phase Gate) + +| Check | Result | +| ---------------------------------------------------------------------------- | ------------------------------------ | +| All six Step 03 briefs present + output-format compliant | ✅ | +| Coordination Register complete, no conflicts | ✅ | +| Verification Strategy: instruments executable | ✅ | +| Scorecard: ≥ target distribution (6 PASS ideal; ≤2 COND ok; any FAIL blocks) | ✅ **6 PASS, 0 CONDITIONAL, 0 FAIL** | +| No net-new design decision introduced in synthesis | ✅ | +| §0 currency re-verified | ✅ | + +**PHASE GATE: PASS.** Phase 4 is unblocked on all six dimensions. + +## §7 — Phase 2 Amendment Package + +**Empty.** No Step 03 brief produced a Phase-2 invalidation (Coordination §0). The MC-12 crossover was a grounding update, not an amendment (M0-E2). Channel 2 did not fire this cycle. + +## §8 — Upstream Phase 2 Toolkit Gaps Carried Forward + +| Gap | Source | Route | +| ---------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------- | +| **VG-P3-U-01** — Phase 2 Step 03 §2 missing MC-21 detail | Step 01 | Phase 2 toolkit v1.2 (require every multi-mechanism MC in §1.1 to have a §2 entry) | +| **VG-P3-U-02** — NTI cycle-vs-future ambiguity | Step 01 | Phase 2 toolkit v1.2 (ask per-NTI: this-cycle or future-cycle) | +| **P3-Obs-09** — MC-21 artifact cohort-citation drift (§5.2 vs §2.2; MC-05 dropped) | M0/Step 04 | Erratum in MC-21 artifact (M4 disposition); Step 03 checklist could verify cohort citations | + +## §9 — Confidence and Observation Notes + +- **Confidence:** High. All inputs finalized, conflict-free, Owner-ratified; both CONDITIONALs resolved with cited basis. +- **Observation log at hand-off to M4:** P3-Obs-01..08 (Session 1) + P3-Obs-09 (cohort drift), P3-Obs-10 (parallel-track early-ship currency event), P3-Obs-11 (two productization tracks/one subject), P3-Obs-12 (process vs code-observable watch-triggers), P3-Obs-13 (single-source-of-truth for 3+-brief artifacts), P3-Obs-14 (well-specified F.2 makes Step 05 mechanical). **14 total** — within the toolkit's 8–15 prediction for a first Phase 3 dogfood. +- **Handoff to M4:** consolidate the 14 observations into `dogfooding-observations.md`; run the three-pass review; queue the Phase 3 v1.1 + Phase 2 v1.2 revision sessions. + +## Version History + +| Version | Date | Change | +| ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| v1.0 | 2026-07-07 | Step 06 capstone. Phase gate PASS (6 PASS, 0 COND, 0 FAIL); both Phase-2 CONDITIONALs resolved; amendment package empty; upstream gaps carried. Synthesis-only, no net-new decisions. |