@deeeed/metamask-harness 0.29.0 → 0.29.2

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.29.2 - 2026-08-01
+
+### Changed
+
+- Upgrade `@farmslot/recipe-harness` to 0.11.1 so iOS lifecycle terminate and restart remain idempotent when Simulator reports that it found nothing to terminate.
+
+## 0.29.1 - 2026-08-01
+
+### Added
+
+- Deploy the static getting-started site through GitHub Pages when its files change on `main`, with manual deployment restricted to the same `main` branch.
+- Document the farmslot specification on the getting-started site: what it standardizes, that its schemas are published and versioned, and why one spec is what makes an engineer's run and a fleet run the same artifact. Carries the control-plane boundary — experimental, sole-maintained, and required by nothing the site teaches.
+
+### Changed
+
+- Define composition-first recipe maintenance and require failures to be classified against authoritative expectations before the owning product, recipe, runtime, or harness layer is changed and revalidated.
+- Define the signed-deeplink canonicalization boundary, its required negative cases, and the distinction between external-ingress proof and in-app route-consumption evidence.
+
+### Fixed
+
+- Correct the site's setup path: `mm-harness setup-base` shipped in 0.29.0, so the bootstrap is no longer described as unpublished.
+
 ## 0.29.0 - 2026-08-01
 
 ### Added

package/docs/RECIPES.md

@@ -64,8 +64,33 @@ Rules:
 - Use real product paths; never mutate hidden state to fabricate proof.
 - Prove preparation with an independent read/assert or visible UI postcondition.
 - Keep ticket-specific claims in task-local recipes.
-- Parameterize repeated behavior instead of multiplying names.
+- Compose, repair, or parameterize repeated behavior instead of multiplying names.
 - Keep secrets out of recipes, libraries, and evidence.
+- Limit claims to the boundary actually exercised. In-app navigation cannot
+  prove external ingress, and security-boundary proofs require accepted and
+  rejected cases.
+
+## Classify failures before changing either layer
+
+Recipes are maintained proof assets, not immutable descriptions of the app.
+Locators, labels, routes, and screen structure can legitimately change, so a
+failed recipe is not by itself evidence of either recipe drift or a product
+regression.
+
+1. Reproduce the failing node and compare it with authoritative acceptance
+   criteria, product contracts, or known-good evidence.
+2. Inspect the current product surface and resolved recipe source, then classify
+   the cause as product regression, recipe drift, fixture/runtime drift, or
+   harness defect.
+3. If an accepted product change establishes recipe drift, repair the smallest
+   shared action or recipe node that owns it. Otherwise preserve the failure
+   and fix or report the owning product, runtime, or harness layer.
+4. Rerun the repaired path and every shared recipe that composes it.
+5. Report the classification, owning source, change, and fresh evidence together.
+
+Do not duplicate a stale recipe to avoid maintaining it. Do not change product
+code merely to satisfy an obsolete proof path, or update a recipe merely to
+make a real regression pass.
 
 Keep responsibilities narrow:
 

package/docs/SECURITY.md

@@ -31,6 +31,37 @@ Fixture setup is allowed before the proof window when it is explicit in the
 trace. Mutating setup must finish with a real read/assert or visible UI
 postcondition.
 
+## Signed deeplink boundary
+
+Treat every raw or original URL parameter as attacker-controlled. Route handlers
+may receive only canonical parameters authorized by a valid signature and the
+link's `sig_params` list. Never add a handler fallback to original parameters,
+including for attribution or a destination considered read-only.
+
+Attribution fields such as `utm_*` may pass through only when they are inside
+the signed parameter set, explicitly allowlisted for the destination, and
+validated for bounded length and character format before use.
+
+A publishable signed-deeplink proof covers the whole ingress boundary:
+
+1. a valid, signed, destination-allowlisted, format-valid, within-limit
+   attribution value reaches the destination;
+2. an unsigned candidate parameter reaches neither handler nor destination;
+3. tampering with a signed value causes authorization failure or interstitial
+   demotion, and no candidate parameter reaches handler or destination;
+4. malformed `sig_params` and invalid signatures cause authorization failure or
+   interstitial demotion, and no candidate parameter reaches handler or
+   destination;
+5. a signed attribution key outside the destination allowlist does not reach
+   the destination or attribution context;
+6. signed attribution values with invalid characters or excessive length do
+   not reach the destination or attribution context;
+7. handler observations for accepted links contain canonical values only.
+
+Opening the same route from inside an already-running app proves downstream
+navigation or analytics consumption only. It is not evidence for external link
+parsing, signature verification, or canonicalization.
+
 ## Wallet fixtures
 
 Each checkout has one canonical fixture:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.29.0",
+  "version": "0.29.2",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -23,7 +23,7 @@
     "@farmslot/agent-runtime": "^0.5.0",
     "@farmslot/handoff": "^0.3.1",
     "@farmslot/protocol": "^0.15.0",
-    "@farmslot/recipe-harness": "^0.11.0",
+    "@farmslot/recipe-harness": "^0.11.1",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",
     "esbuild": "0.28.1",

package/site/architecture.html

@@ -135,6 +135,65 @@
   </div>
 </section>
 
+<section class="wrap">
+  <h2 id="spec">The spec underneath</h2>
+  <p>
+    <code>mm-harness</code> implements <strong>farmslot</strong>, a versioned specification for agentic
+    proof work. The CLI is one implementation of it, not the thing itself.
+  </p>
+
+  <div class="stack">
+    <div class="layer layer-static">
+      <span class="layer-n">1</span>
+      <span class="layer-name">The specification</span>
+      <span class="layer-sub">recipes, action manifests, observations and traces, evidence, handoff</span>
+    </div>
+    <div class="arrow" aria-hidden="true">↓</div>
+    <div class="layer layer-static">
+      <span class="layer-n">2</span>
+      <span class="layer-name">mm-harness implements it</span>
+      <span class="layer-sub">for MetaMask products</span>
+    </div>
+    <div class="arrow" aria-hidden="true">↓</div>
+    <div class="layer layer-static">
+      <span class="layer-n">3</span>
+      <span class="layer-name">Skills drive it</span>
+      <span class="layer-sub">the workflows an agent follows</span>
+    </div>
+  </div>
+
+  <p>Schemas are published and versioned. Every recipe carries the URL it validates against:</p>
+  <div class="out">"$schema": <a href="https://farmslot.io/schemas/recipe-v1.schema.json">"https://farmslot.io/schemas/recipe-v1.schema.json"</a></div>
+  <p>
+    Action manifests carry <code>action-manifest-v1</code>; evidence records its own
+    <code>schemaVersion</code> and <code>runner_protocol_version</code>. Versioning is what keeps a
+    bundle readable by tooling written after it was produced.
+  </p>
+
+  <h3>Why the spec is the scaling mechanism</h3>
+  <p>
+    The recipe you run from the CLI is the same artifact a control plane dispatches to a worker,
+    monitors, and gates — dispatch, worker, self-review, human gate, publication, each step speaking
+    these contracts. Evidence returns in the same shape either way, so a fleet result is reviewable by
+    whoever wrote the recipe. Parity is structural: one spec, both sides.
+  </p>
+  <p>The seam shows in the CLI's own help — the flags a control plane supplies:</p>
+  <div class="out">managed trust boundary (not needed for normal runs; Farmslot supplies it):
+  --source-trust, --source-kind, --source-name, --source-digest,
+  <span class="hint">--approve-plan</span> (binds approval to the exact reviewed plan)</div>
+  <p>Approve a plan and only that plan runs — which is what keeps the gate a gate.</p>
+
+  <div class="note">
+    <span class="note-title">What you actually need</span>
+    <p>
+      The farmslot control plane is <strong>experimental and sole-maintained</strong>. Nothing this site
+      teaches requires it — the harness, recipes, and skills are complete on their own, and the CLI says
+      as much: those flags are "not needed for normal runs". The specification is what you adopt; the
+      control plane is one consumer of it.
+    </p>
+  </div>
+</section>
+
 <section class="wrap">
   <h2 id="loop">The improvement loop</h2>
   <p>The stack is arranged so each run can leave the next one better informed.</p>

package/site/index.html

@@ -62,6 +62,10 @@
     screenshots. The steps below follow <strong>discover → drive → prove</strong>, which is also the
     order you will work in from here on.
   </p>
+  <p>
+    <code>mm-harness</code> implements the farmslot specification —
+    <a href="architecture.html#spec">see Architecture</a>.
+  </p>
 
   <div class="doctrine">
     <p>
@@ -147,11 +151,11 @@ me the exact error.</code></pre></div>
           <div class="path-tag">Path A — from zero</div>
           <h4 style="margin:0 0 .5rem">No checkout yet</h4>
           <p style="font-size:.92rem;color:var(--text-dim)">
-            A one-shot bootstrap command is being prepared but is <strong>not published yet</strong> —
-            it is not on the npm package, so do not paste it from elsewhere expecting it to resolve.
-            Until it ships, use the install below and clone <em>one</em> product repo yourself.
+            Install below, then <code>mm-harness setup-base</code> clones the MetaMask product repos
+            into one standard layout and runs each repo's own dependency install. Use
+            <code>--dry-run</code> first to see the layout it would create.
           </p>
-          <p style="margin-bottom:0"><span class="badge soon">bootstrap: shipping soon</span></p>
+          <p style="margin-bottom:0"><span class="badge live">available now</span></p>
         </div>
         <div class="path-card">
           <div class="path-tag">Path B — you already have a checkout</div>