From 802e4ed044ebb77f0689fcee3eec3ebac1d6e187 Mon Sep 17 00:00:00 2001 From: Steven Chou Date: Wed, 13 May 2026 15:46:13 +0800 Subject: [PATCH] [verified] feat: add agent trust contract proof page --- README.md | 4 + examples/reports/README.md | 2 + examples/reports/trust-contract.html | 628 +++++++++++++++++++++++++++ tests/test_static_viewer.py | 80 ++++ 4 files changed, 714 insertions(+) create mode 100644 examples/reports/trust-contract.html diff --git a/README.md b/README.md index a883c57..8b742fb 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,10 @@ Use the delegation policy simulator to translate those scores into a next-step a [examples/reports/delegation-policy.html](examples/reports/delegation-policy.html) +Read the trust contract that explains how trace evidence becomes a score, a permission tier, and a stop condition: + +[examples/reports/trust-contract.html](examples/reports/trust-contract.html) + See a failure replay that contrasts a good delegated run with a bad busywork run, then shows how the failed trace changes the next autonomy decision: [examples/reports/failure-replay.html](examples/reports/failure-replay.html) diff --git a/examples/reports/README.md b/examples/reports/README.md index c21e0f8..ddf8992 100644 --- a/examples/reports/README.md +++ b/examples/reports/README.md @@ -28,4 +28,6 @@ PYTHONPATH=src python -m agent_scorecard.cli --batch-dir examples/traces --summa Open `portfolio-viewer.html` for the public score summary, then use `delegation-policy.html` to turn the same sample data into an autonomy decision: give more permissions, keep supervised, or stop delegation until fixed. +Open `trust-contract.html` for the public trust contract that explains how trace evidence becomes a score, a permission tier, and a stop condition for Steven's personal AI OS. + Open `failure-replay.html` to see the public-safe contrast between a good delegated run and a bad busywork run, including the artifact, verification, privacy, handoff, and autonomy-decision differences. diff --git a/examples/reports/trust-contract.html b/examples/reports/trust-contract.html new file mode 100644 index 0000000..4d3b2b9 --- /dev/null +++ b/examples/reports/trust-contract.html @@ -0,0 +1,628 @@ + + + + + + Agent Scorecard Trust Contract + + + +
+
+

Agent Scorecard trust contract

+

If an agent scores X, what can Steven let it do next?

+

+ This is the visitor-facing contract for Steven's personal AI OS evaluation layer: + trace evidence earns a score, the score grants a bounded permission, and a stop condition + prevents the agent from expanding autonomy without public proof. +

+ + +
+
+ 1 + Trace evidence +

The run leaves inspectable events: request, tool calls, artifact writes, verification, and handoff.

+
+
+ 2 + Score +

The scorecard turns that evidence into a deterministic score and verdict.

+
+
+ 3 + Permission +

The verdict decides the next safe permission level for the same task pattern.

+
+
+ 4 + Stop condition +

A weak or missing proof blocks more autonomy until the failure is fixed and re-scored.

+
+
+
+ +
+

1. Trace evidence comes first

+

+ The trust contract starts with observable behavior, not the agent's confidence. A real run needs enough + public-safe evidence for another person to see what happened without exposing private vault notes, + employer details, account IDs, secrets, or local machine paths. +

+
    +
  • +

    User ask: What task did the agent accept, and what outcome was expected?

    +
    • +
  • +

    Tool discipline: Did the agent use retrieval, file, or system tools when it claimed to research or write?

    +
    • +
  • +

    Durable artifact: Did the run produce a named output that can be inspected later?

    +
    • +
  • +

    Verification: Did the agent check its own output before asking Steven for more trust?

    +
    • +
+
+ +
+

2. The score converts evidence into a permission signal

+

+ Agent evaluation is useful only when the number changes what happens next. In Agent Scorecard, + the score is a control signal for Steven's personal AI OS: it determines whether the agent gets + observation-only use, supervised drafting, bounded writes, or broader delegation. +

+ 
trace evidence -> deterministic checks -> score -> verdict -> next permission
+
+ +
+

3. Permission tiers

+

+ These tiers are intentionally concrete. Each one says what Steven can allow next, what public proof is required, + and what stops the agent before the next tier. +

+ +
+
+
+ Tier 0 +

Observe only

+ 0-49: do not delegate +
+
+
    +
  • + Permission +

    Use the agent for read-only discussion, critique, and small planning prompts. No autonomous writes or outbound actions.

    +
    • +
  • + Required evidence +

    A corrected trace showing the agent followed through on promised tool use, produced inspectable work, and gave a clear verdict.

    +
    • +
  • + Stop condition +

    Any run with no tool-backed action after a research/write promise stays here.

    +
    • +
+
+
+ +
+
+ Tier 1 +

Supervised draft

+ 50-69: limited trust +
+
+
    +
  • + Permission +

    Let the agent draft notes, plans, and reports for human review. Steven approves consequential edits before they matter.

    +
    • +
  • + Required evidence +

    Trace includes the user ask, relevant tool calls, an artifact or explicit no-artifact rationale, and a final handoff.

    +
    • +
  • + Stop condition +

    Missing artifact, missing verification, or unclear final verdict blocks write permission.

    +
    • +
+
+
+ +
+
+ Tier 2 +

Bounded write

+ 70-84: supervised autonomy +
+
+
    +
  • + Permission +

    Allow narrow writes in public-safe project areas and short task runs with explicit success checks.

    +
    • +
  • + Required evidence +

    Passing scorecard checks for tool discipline, durable artifact creation, verification, privacy, and concise handoff quality.

    +
    • +
  • + Stop condition +

    A weakest trace below 50/100, privacy concern, or stale public proof stops delegation until fixed.

    +
    • +
+
+
+ +
+
+ Tier 3 +

Broader delegation

+ 85-100: invest more +
+
+
    +
  • + Permission +

    Give the agent more tokens, a wider queue, and carefully bounded project permissions for the same proven task pattern.

    +
    • +
  • + Required evidence +

    Portfolio average and weakest trace both clear 85/100, with public proof that the agent can act, verify, and explain the result.

    +
    • +
  • + Stop condition +

    Any regression below the supervised floor or any private-data exposure returns the task pattern to review.

    +
    • +
+
+
+
+
+ +
+

4. Stop conditions are part of the contract

+

+ A stop condition is not a punishment. It is the control layer doing its job. The agent can earn back permission + by producing a better trace, but it cannot talk its way around missing evidence. +

+
    +
  • +

    Promise without action: The agent says it will research, write, or verify, then no matching tool evidence appears.

    +
    • +
  • +

    No inspectable artifact: The run leaves Steven with a summary but no durable output or explicit reason for skipping one.

    +
    • +
  • +

    No verification: The agent claims the work is complete without checking the artifact or result.

    +
    • +
  • +

    Public proof gap: The repo cannot show a sanitized report that explains the score and autonomy decision.

    +
    • +
+
+ +
+

How to use this in a real agent run

+

+ Start with a sanitized trace from a real or synthetic agent run. Score it, inspect the public report, then use this trust contract + to decide what the agent is allowed to do next. Keep private vault content, employer-sensitive details, and secrets out of the public proof. +

+ +
+ 
1. Collect a public-safe trace.
+2. Run Agent Scorecard against the trace.
+3. Open the report and inspect the failure signals.
+4. Pick the matching permission tier.
+5. Stop, supervise, or expand autonomy based on evidence.
+ +
    +
  • + Trace walkthrough + Shows how one tiny trace becomes checks, a score, and a trust decision. +
    • +
  • + Portfolio viewer + Summarizes the committed public examples and weakest-trace policy result. +
    • +
  • + Delegation policy + Turns scores into a next-step autonomy decision. +
    • +
  • + Failure replay + Shows how a bad busywork run blocks broader permissions. +
    • +
+
+
+ +
+

+ This page is self-contained: no external scripts, stylesheets, images, network requests, tokens, account IDs, private traces, or local paths. +

+

+ It is meant as public proof for Steven's agent evaluation layer, not as a dump of private operating-system context. +

+
+
+ + diff --git a/tests/test_static_viewer.py b/tests/test_static_viewer.py index fb48d51..cb2ca2e 100644 --- a/tests/test_static_viewer.py +++ b/tests/test_static_viewer.py @@ -163,6 +163,86 @@ def test_failure_replay_page_is_static_public_and_actionable(self) -> None: self.assertNotRegex(html, r"[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}") + def test_trust_contract_page_is_static_public_and_linked(self) -> None: + html_path = REPORTS_DIR / "trust-contract.html" + self.assertTrue(html_path.exists()) + + html = html_path.read_text(encoding="utf-8") + root_readme = (REPO_ROOT / "README.md").read_text(encoding="utf-8") + reports_readme = (REPORTS_DIR / "README.md").read_text(encoding="utf-8") + + self.assertIn("", html.lower()) + self.assertIn("Agent Scorecard trust contract", html) + self.assertIn("Steven's personal AI OS", html) + self.assertIn("trace evidence earns a score", html) + self.assertIn("public proof", html) + self.assertIn("agent evaluation", html) + self.assertIn("How to use this in a real agent run", html) + + for anchor in ( + 'id="trace-evidence"', + 'id="score"', + 'id="permission-tiers"', + 'id="stop-conditions"', + 'id="real-agent-run"', + ): + self.assertIn(anchor, html) + + for tier in ( + "Observe only", + "Supervised draft", + "Bounded write", + "Broader delegation", + ): + self.assertIn(tier, html) + + for phrase in ( + "Required evidence", + "Stop condition", + "0-49: do not delegate", + "50-69: limited trust", + "70-84: supervised autonomy", + "85-100: invest more", + "trace evidence -> deterministic checks -> score -> verdict -> next permission", + ): + self.assertIn(phrase, html) + + for report_name in ( + "trace-walkthrough.html", + "portfolio-viewer.html", + "delegation-policy.html", + "failure-replay.html", + ): + self.assertIn(f'href="{report_name}"', html) + + self.assertIn("examples/reports/trust-contract.html", root_readme) + self.assertIn("trust-contract.html", reports_readme) + + lower_html = html.lower() + self.assertNotIn(" None: from agent_scorecard.report import to_portfolio_badge_svg