spike+demo(workflow): contract-hash drift, auditable lint waivers, free-authoring beat

Implements the three maintainer-review items that strengthen gate evidence
(the rest stay RFC-design-level):

* Contract-hash drift (review #3): Capability.contract_hash() =
  sha256(input_kind + output schema), recorded per referenced capability in
  FrozenWorkflowRecord; import rejects contract drift even when the manual
  version string was never bumped (manual versions demoted to secondary).
* Auditable lint suppression (review #6): allow_self_chain capability policy
  opts legitimate draft->critique->redraft refinement out of the self-review
  lint; per-plan lint_waivers (node id -> justification) suppress lints AND
  are recorded in the frozen record/export envelope.
* Free-authoring beat (demo review): 'freely/decompose' trigger gives the
  planner ONLY goal + capability descriptions (no recipe) — the honest
  model-authored claim; recipe-free instruction pinned by a CI test.

Suites: 11 + 34 + 8 = 53 deterministic tests.

Author: caohy1988

contributing/samples/workflows/authored_workflow_demo/DEMO_NARRATIVE.md

@@ -42,6 +42,23 @@ Send: **"Plan and run a codebase security review."** The chat streams:
 > construct that lets each file flow review→verify independently — item A can be
 > verifying while item B is still being reviewed."
 
+## Beat 1b — free authoring (the honest "model-authored" claim)
+
+In a new session, send: **"Freely plan a security review of the files — decompose it yourself."**
+
+```
+🧭 Free authoring — the planner receives ONLY the goal + capability
+   descriptions (reviewer, verifier, triager, formatter); no plan recipe.
+   The shape below is the model's own decomposition (it may differ run to
+   run — and the freeze beat then makes THIS run replayable).
+```
+
+> "Beat 1 was instruction-guided so the recording is reproducible — the model
+> filled in a known shape. This beat is the real claim: goal + capabilities
+> in, plan out, no recipe. Whatever it authors, the same validator, lints,
+> freeze, and replay machinery apply — free authoring composes with
+> everything you're about to see, and the frozen hash pins *this* run."
+
 ## Beat 2 — validate (capability allow-list)
 
 ```
@@ -210,7 +227,7 @@ Send: **"Plan a sloppy review: have the reviewer double-check its own findings."
 > engine at a visible cost (one planner call, the work outside its context);
 > the plan **exported** to a portable, defensively-imported audit artifact; and
 > a re-send replayed the exact frozen plan with zero planner calls. The
-> deterministic test suites — 11 (#92) + 31 (#93) + 7 (demo) — lock all of this
+> deterministic test suites — 11 (#92) + 34 (#93) + 8 (demo) — lock all of this
 > in CI, including the no-LLM reuse path, the export round-trip / tamper /
 > drift checks, the plan-quality lints, and the six-coordination-pattern
 > coverage sweep (adversarial verification and tournament included)."
@@ -236,6 +253,6 @@ Send: **"Plan a sloppy review: have the reviewer double-check its own findings."
 
 ```bash
 pytest contributing/samples/workflows/dynamic_supervisor_spike/test_dynamic_supervisor_spike.py -q  # 11
-pytest contributing/samples/workflows/authored_workflow_spike/test_authoring.py -q                  # 31
-pytest contributing/samples/workflows/authored_workflow_demo/test_demo_agent.py -q                  # 7
+pytest contributing/samples/workflows/authored_workflow_spike/test_authoring.py -q                  # 34
+pytest contributing/samples/workflows/authored_workflow_demo/test_demo_agent.py -q                  # 8
 ```

contributing/samples/workflows/authored_workflow_demo/README.md

@@ -47,6 +47,14 @@ Point at the ADK-native evidence as it streams:
 
 (Re-send the same prompt to show resume reuses the frozen spec — same hash, not re-authored.)
 
+Then run the **free-authoring beat** — in a **new session**, send:
+
+```text
+Freely plan a security review of the files — decompose it yourself.
+```
+
+The planner receives ONLY the goal + capability descriptions (no plan recipe — `test_free_planner_instruction_is_recipe_free` pins this). The shape may differ run to run; that's the point — and the freeze beat then makes *this* run replayable. Talking point: *the default walkthrough shows the mechanics on a scripted plan; this beat is the honest "model-authored" claim.*
+
 Then run the **quality-gate beat** — send:
 
 ```text
@@ -82,11 +90,11 @@ Proof points: multi-stage `fan_out → step → step`; branch `step → branch`;
 
 ```bash
 pytest contributing/samples/workflows/dynamic_supervisor_spike/test_dynamic_supervisor_spike.py -q  # 11
-pytest contributing/samples/workflows/authored_workflow_spike/test_authoring.py -q                  # 31
-pytest contributing/samples/workflows/authored_workflow_demo/test_demo_agent.py -q                  # 7
+pytest contributing/samples/workflows/authored_workflow_spike/test_authoring.py -q                  # 34
+pytest contributing/samples/workflows/authored_workflow_demo/test_demo_agent.py -q                  # 8
 ```
 
-- Deterministic suites: #92 **11** + #93 **31** + demo **7** = **49** (incl. a no-LLM reuse-path test, the six-pattern coverage sweep — adversarial verification + tournament via loop-carried `init` — and the plan-quality lints).
+- Deterministic suites: #92 **11** + #93 **34** + demo **8** = **53** (incl. a no-LLM reuse-path test, the six-pattern coverage sweep — adversarial verification + tournament via loop-carried `init` — the plan-quality lints with `allow_self_chain` policy + recorded waivers, contract-hash drift rejection, and the recipe-free free-authoring instruction pin).
 - PR #3 CI green except the documented fork-only `agent-triage` token job.
 
 ## Recording notes

contributing/samples/workflows/authored_workflow_demo/security_audit_planner/agent.py

@@ -222,6 +222,26 @@ def _registry() -> CapabilityRegistry:
 )
 
 
+# The FREE-AUTHORING beat: the planner receives ONLY the goal + capability
+# descriptions — no plan recipe. This is the honest "model-authored" claim
+# (the default _PLANNER_INSTR dictates the shape for recording reliability;
+# the spike's demand gate also used free authoring).
+_FREE_TRIGGERS = ("freely", "free-form", "your own plan", "decompose")
+_FREE_PLANNER_INSTR = (
+    "Author a WorkflowSpec using ONLY these capabilities: "
+    + _REGISTRY_DESC
+    + " The task input has a 'files' list of objects with path and code."
+    " GOAL: audit the files for security issues and produce a one-line"
+    " report note. Decompose the goal into a plan YOURSELF — no recipe is"
+    " provided. Choose whichever control blocks fit (step / fan_out /"
+    " pipeline / branch / loop_until). Binding rules:"
+    " Binding(source='task', path='files') reads the file list;"
+    " Binding(source='step', step=<id>) reads a prior step's output; a"
+    " pipeline stage takes the previous stage's per-item output"
+    " automatically. Set output to the final step."
+)
+
+
 def _msg(text: str) -> Event:
   return Event(
       content=types.Content(role="model", parts=[types.Part(text=text)])
@@ -305,18 +325,27 @@ async def author_validate_execute(ctx: Context, node_input):
     )
   else:
     reused = False
+    free = any(k in str(node_input or "").lower() for k in _FREE_TRIGGERS)
     cap_list = ", ".join(f"`{n}`" for n in reg.names())
-    yield _msg(
-        "🧭 **Model-authored Workflow** — planning a security audit over "
-        f"{len(FILES)} files using only registered capabilities "
-        f"({cap_list})."
-    )
+    if free:
+      yield _msg(
+          "🧭 **Free authoring** — the planner receives ONLY the goal +"
+          f" capability descriptions ({cap_list}); no plan recipe. The shape"
+          " below is the model's own decomposition (it may differ run to"
+          " run — and the freeze beat then makes THIS run replayable)."
+      )
+    else:
+      yield _msg(
+          "🧭 **Model-authored Workflow** — planning a security audit over "
+          f"{len(FILES)} files using only registered capabilities "
+          f"({cap_list})."
+      )
     planner = Agent(
         name="planner",
         model=MODEL,
         output_schema=WorkflowSpec,
         generate_content_config=DET,
-        instruction=_PLANNER_INSTR,
+        instruction=_FREE_PLANNER_INSTR if free else _PLANNER_INSTR,
     )
     raw = await ctx.run_node(
         planner,

contributing/samples/workflows/authored_workflow_demo/test_demo_agent.py

@@ -136,6 +136,18 @@ def test_quality_gate_rejects_self_review_plan():
   assert "re-checks its own capability's output" in lints[0]
 
 
+def test_free_planner_instruction_is_recipe_free():
+  # The honesty contract behind the free-authoring beat: the default
+  # instruction dictates the plan; the free instruction must NOT — only the
+  # goal, the capability descriptions, and the binding rules.
+  assert "reviewer then verifier" in demo._PLANNER_INSTR  # scripted (default)
+  assert "reviewer then verifier" not in demo._FREE_PLANNER_INSTR
+  assert "(1)" not in demo._FREE_PLANNER_INSTR  # no step recipe
+  assert "YOURSELF" in demo._FREE_PLANNER_INSTR
+  # trigger sets must not overlap (a prompt can't be both free and sloppy).
+  assert not set(demo._FREE_TRIGGERS) & set(demo._SLOPPY_TRIGGERS)
+
+
 def test_demo_spec_quality_lints_clean_and_independent():
   # Zero plan-quality lints: verification is by a DIFFERENT capability
   # (reviewer -> verifier), and the fan-out is synthesized (triager).

contributing/samples/workflows/authored_workflow_spike/DESIGN.md

@@ -131,6 +131,8 @@ Then **`Graph.validate_graph()`** (reused) handles duplicate names, `START`/reac
 - **self-review**: a node (or pipeline stage) consuming output produced by the *same capability* — same-capability review cannot provide independent verification;
 - **unsynthesized fan-out**: the terminal output binds a bare per-item `fan_out` never combined or verified downstream.
 
+**Suppression** (so the lints stay credible instead of globally disabled): a capability registered with `allow_self_chain=True` opts out of the self-review lint (legitimate `draft → critique → redraft` refinement), and per-plan `lint_waivers` (node id → justification) are **recorded in the `FrozenWorkflowRecord`** — a suppressed lint is an auditable decision, not a silenced one.
+
 The complementary positive facts (`independence_facts`) are derivable from the frozen spec — e.g. *"stage `verifier` sees ONLY stage `reviewer`'s per-item output"* — which is what lets the frozen record **prove** structural bias controls to an auditor, not just assert them.
 
 ## 4. Semantics
@@ -152,7 +154,9 @@ class FrozenWorkflowRecord(BaseModel):
   spec_hash: str                      # sha256(canonical_json(spec)) — see §10
   planner_model: str
   registry_version: str
-  capability_versions: dict[str, str]
+  capability_versions: dict[str, str]          # manual bumps — coarse SECONDARY signal
+  capability_contract_hashes: dict[str, str]   # DERIVED sha256(input_kind+output schema) — primary drift signal
+  lint_waivers: dict[str, str]                 # node id -> justification; auditable lint suppression
   validation: ValidationResult        # {passed: bool, warnings: [...]}
   created_at: str                     # ISO-8601, stamped at freeze
   task_input_schema: dict | None      # expected root task-input schema (enables template reuse)
@@ -243,7 +247,10 @@ Re-runnable: `contributing/samples/workflows/authored_workflow_spike/` (31 deter
     # INTEGRITY (never trust the envelope's own `validation`):
     #   1. recompute sha256(canonical_json(spec)); REJECT if != envelope["spec_hash"]
     #   2. re-run WorkflowSpecValidator against the CURRENT registry
-    #   3. registry/capability drift -> fail loudly (or explicit migration)
+    #   3. registry/capability drift -> fail loudly (or explicit migration);
+    #      capability drift = manual version (secondary) AND derived contract
+    #      hash sha256(input_kind + output schema) (primary — catches schema
+    #      changes nobody versioned)
     # EXECUTION-INPUT:
     #   replay   : task_input digest must match envelope["task_input_digest"] (else audit-only)
     #   template : task_input validated against envelope["task_input_schema"] before execution

contributing/samples/workflows/authored_workflow_spike/README.md

@@ -26,7 +26,7 @@ behind the RFC's "can a model author good plans?" question.
 pytest contributing/samples/workflows/authored_workflow_spike/test_authoring.py -q
 ```
 
-Expected: **31 passed** — `Binding` invariant, `max_iters>=1`, validator accepts a
+Expected: **34 passed** — `Binding` invariant, `max_iters>=1`, validator accepts a
 valid spec and rejects unknown capability / non-preceding binding / duplicate id,
 the open-map warning, and interpreter execution of fan_out→aggregate, **pipeline (barrier-free per-item review→verify, plus per-stage `max_fan_out` enforcement)**, branch
 (correct route), and loop_until (stops + correct output); plus **plan export/import**
@@ -38,7 +38,10 @@ shapes: sequence/loop/leaf by capability name; runtime fan_out/pipeline/branch
 flagged no-equivalent rather than fabricated); plus **pattern coverage**
 (adversarial verification and tournament via loop-carried `init`, incl. the
 no-`init` validation error) and **plan-quality lints** (same-capability
-self-review and unsynthesized fan-out warn; an independent plan lints clean).
+self-review and unsynthesized fan-out warn; an independent plan lints clean;
+`allow_self_chain` policy and recorded per-plan waivers suppress auditably);
+plus **contract-hash drift** (import rejects a changed capability schema even
+when the manual version string was never bumped).
 
 ## Pattern coverage — the six coordination shapes