crewscore 0.2.4__tar.gz → 0.2.6__tar.gz

{crewscore-0.2.4 → crewscore-0.2.6}/AGENTS.md

@@ -33,6 +33,8 @@ crewscore test --prompt-file ./system-prompt.md --json --threshold 50
 crewscore test --prompt-file ./system-prompt.md --report out.html --badge badge.svg
 
 # apply guardrail patterns
+crewscore fix --prompt-file ./system-prompt.md --plan          # dry-run: list planned dimensions, no write
+crewscore fix --prompt-file ./system-prompt.md --dry-run       # alias for --plan
 crewscore fix --prompt-file ./system-prompt.md
 crewscore fix --prompt-file ./system-prompt.md --apply
 crewscore fix --prompt-file ./system-prompt.md --output ./guarded.md --json

{crewscore-0.2.4 → crewscore-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crewscore
-Version: 0.2.4
+Version: 0.2.6
 Summary: CrewScore — offline structural production-readiness scorecard for AI agent system prompts.
 Project-URL: Homepage, https://crewscore.ai
 Project-URL: Repository, https://github.com/shmindmaster/crewscore
@@ -189,7 +189,12 @@ Human mode also prints a one-line share blurb with your overall score and [crews
 ### Apply guardrail patterns
 
 ```bash
-# print enhanced prompt
+# plan only — list dimensions that would be fixed (no file write)
+crewscore fix --prompt-file ./system-prompt.md --plan
+# alias:
+crewscore fix --prompt-file ./system-prompt.md --dry-run
+
+# print enhanced prompt (stdout only)
 crewscore fix --prompt-file ./system-prompt.md
 
 # write in place and show score delta
@@ -200,9 +205,11 @@ crewscore fix --prompt-file ./system-prompt.md --output ./system-prompt-guarded.
 
 # machine-readable summary
 crewscore fix --prompt-file ./system-prompt.md --apply --json
+# plan as JSON (fixes_planned, written: false)
+crewscore fix --prompt-file ./system-prompt.md --plan --json
 ```
 
-These are **prompt text templates**. They can raise the structural score without changing runtime behavior — wire matching controls (tool gates, logging, budgets) in your application.
+`--plan` / `--dry-run` is mutually exclusive with `--apply` and `--output`. These are **prompt text templates**. They can raise the structural score without changing runtime behavior — wire matching controls (tool gates, logging, budgets) in your application.
 
 ### Vendor checklist (self-attest, secondary)
 

{crewscore-0.2.4 → crewscore-0.2.6}/README.md

@@ -162,7 +162,12 @@ Human mode also prints a one-line share blurb with your overall score and [crews
 ### Apply guardrail patterns
 
 ```bash
-# print enhanced prompt
+# plan only — list dimensions that would be fixed (no file write)
+crewscore fix --prompt-file ./system-prompt.md --plan
+# alias:
+crewscore fix --prompt-file ./system-prompt.md --dry-run
+
+# print enhanced prompt (stdout only)
 crewscore fix --prompt-file ./system-prompt.md
 
 # write in place and show score delta
@@ -173,9 +178,11 @@ crewscore fix --prompt-file ./system-prompt.md --output ./system-prompt-guarded.
 
 # machine-readable summary
 crewscore fix --prompt-file ./system-prompt.md --apply --json
+# plan as JSON (fixes_planned, written: false)
+crewscore fix --prompt-file ./system-prompt.md --plan --json
 ```
 
-These are **prompt text templates**. They can raise the structural score without changing runtime behavior — wire matching controls (tool gates, logging, budgets) in your application.
+`--plan` / `--dry-run` is mutually exclusive with `--apply` and `--output`. These are **prompt text templates**. They can raise the structural score without changing runtime behavior — wire matching controls (tool gates, logging, budgets) in your application.
 
 ### Vendor checklist (self-attest, secondary)
 

crewscore-0.2.6/_product-experience/00-discovery.md

@@ -0,0 +1,51 @@
+# CrewScore — Discovery
+
+**Date:** 2026-07-28  
+**Repo:** `shmindmaster/crewscore`  
+**Surfaces in scope:** Public web (crewscore.ai / `index.html`), CLI, GitHub Action, docs/launch.
+
+## Product promise
+
+Offline **structural pre-gate** for AI agent system prompts: discover missing hygiene signals, explain with open rules, fix text templates, gate CI — never claim red-team or certification.
+
+## Users & jobs
+
+| Persona | Job | Success looks like |
+| --- | --- | --- |
+| **Agent builder** (primary) | Before merge/demo, know if system prompt lacks production hygiene | Score + top gaps + fix or CI gate in <2 min |
+| **OSS / HN visitor** | Understand product in 15s without install | One click demo → memorable number → trust honesty |
+| **AppSec-curious** | Prefer open rules over black-box scores | Expand full rule IDs; match CLI |
+| **Buyer / ops** (secondary) | Self-attest vendor diligence | Separate, demoted checklist — not the hero |
+
+## Domain objects
+
+- **Prompt artifact** (text / file / URL)
+- **Ruleset** (`crewscore-hygiene@x.y.z`) + **rule_id** findings
+- **Score result** (8 dimensions, overall, structural tier, warnings)
+- **Fix pack** (appended templates; mutates text only)
+- **Scan set** (repo paths; CLI/Action)
+- **Share artifact** (image / text; must not overclaim)
+
+## Capability map (what exists)
+
+| Surface | Status | Notes |
+| --- | --- | --- |
+| Public marketing / demo site | Deep reviewed | Single-page score tool; primary viral surface |
+| CLI `test` / `scan` / `fix` / `rules` / `export-eval` | Deep reviewed | Strong; truth source for web |
+| GitHub Action + PR sticky summary | Shallow reviewed | Functional; not browser UX |
+| Vendor self-attest | Shallow reviewed | Demoted; still competes for attention if tab-equal |
+| Auth / billing / admin | Not applicable | Zero-install OSS |
+| Live LLM / agent runtime | Not applicable | Explicitly out of scope |
+
+## Constraints
+
+- Deterministic scoring (no model calls on critical path)
+- Browser must stay offline-capable (local `score-engine.js`)
+- Honesty > virality theater
+- Keep HTML contract tests (builder-first hero, authenticity, escapeHtml, engine parity)
+
+## Evidence sources
+
+- Runtime: live site + Playwright primary journey
+- Code: `index.html`, `score-engine.js`, CLI
+- Research: `docs/research/2026-07-28-useful-product-and-virality-research.md`

crewscore-0.2.6/_product-experience/01-audit.md

@@ -0,0 +1,94 @@
+# CrewScore — Product experience audit
+
+**Date:** 2026-07-28  
+**Method:** Discovery + live journey (Playwright) + implementation review  
+**Scope:** Public web primary; CLI/Action as continuity targets
+
+## Coverage ledger
+
+| Surface | Status | Notes |
+| --- | --- | --- |
+| Public marketing / zero-install demo | Deep reviewed | Core product surface for cold traffic |
+| Customer product (web score/fix) | Deep reviewed | Same page as marketing |
+| Developer integrations (CLI/Action) | Shallow reviewed | Strong utility; linked in footer |
+| Vendor diligence | Shallow reviewed | Secondary; over-weighted in IA if equal tab |
+| Auth / billing / ops / support portals | Not applicable | |
+
+## Primary journey audited
+
+**Try template → score → understand → fix → share**
+
+Evidence (2026-07-28): Weak demo → 0/100 → Fix → 46/100 works. Full rule dump previously overloaded; polish reduced dump but **workflow still single-panel form**, not a task lifecycle.
+
+## Findings
+
+### F1 — Workflow is a form, not a preflight job  
+**Severity:** High · **Class:** product-fix-required  
+**Evidence:** One panel with score, fix, URL, vendor tab; no explicit stages, plan-before-mutate, or completion.  
+**Impact:** Builders don't feel "I completed a gate"; visitors don't learn the product story.  
+**Recommendation:** Stage the job: Prompt → Inspect → Act → Export.  
+**Validate:** Task completion without reading docs; time-to-first-insight < 20s.
+
+### F2 — "Fix" mutates without plan preview (agentic control gap)  
+**Severity:** High · **Class:** product-fix-required  
+**Evidence:** `fixAndRescore` replaces textarea immediately; no preview of sections that will be appended.  
+**Impact:** Surprising text mutation; reduces trust for production prompts.  
+**Recommendation:** Preview plan (dimensions/sections to add) → explicit Apply.  
+**Validate:** User can cancel fix; prompt unchanged until Apply.
+
+### F3 — Capability boundary is easy to misread as "AI safety product"  
+**Severity:** High · **Class:** product-fix-required  
+**Evidence:** Hero about agent prompts; scoring is regex. Honesty present but competes with marketing.  
+**Impact:** Trust collapse on HN; wrong mental model.  
+**Recommendation:** Persistent capability chip + result stamp: "Structural pre-gate · not red-team".  
+**Validate:** After first score, user can restate what product is/isn't.
+
+### F4 — Results still present as dashboard, not decisions  
+**Severity:** Medium · **Class:** product-fix-required  
+**Evidence:** 8 bars + optional full rules; top gaps improved but no "next action" hierarchy beyond Fix.  
+**Impact:** Cognitive load; weak link to CI/export-eval.  
+**Recommendation:** Decision stack: Top gaps (act) → dimension radar/checklist → optional rules → CI/export CTA.  
+**Validate:** First click after score is gap-relevant action ≥70% of sessions (instrument).
+
+### F5 — Vendor path steals IA equality  
+**Severity:** Medium · **Class:** product-fix-required  
+**Evidence:** Tab strip co-primary with agent scoring. Research demoted vendor.  
+**Impact:** Dilutes builder product; resurrects questionnaire theater.  
+**Recommendation:** Vendor as secondary link / `#vendor`, not equal tab chrome.  
+**Validate:** Cold open shows only agent job.
+
+### F6 — Visual system still "AI product default"  
+**Severity:** Medium · **Class:** product-fix-required  
+**Evidence:** Dark slate + cyan gradient + system sans; generic after 2026 AI sites.  
+**Impact:** Low memorability; fails distinctive frontend-design bar.  
+**Recommendation:** Preflight/instrument aesthetic — amber caution + terminal mono + radar/checklist signature.  
+**Validate:** Screenshot recognition without logo text in informal test.
+
+### F7 — Empty / error / success states underdesigned  
+**Severity:** Medium · **Class:** product-fix-required  
+**Evidence:** Empty = blank textarea; error = red line; success = scorecard only.  
+**Impact:** No guided first action; recovery is weak for URL/CORS failures.  
+**Recommendation:** Empty invites one demo; errors name cause + paste fallback; success has completion checklist.  
+**Validate:** Empty state has single recommended action; URL error offers paste.
+
+### F8 — No outcome instrumentation  
+**Severity:** Medium · **Class:** product-fix-required  
+**Evidence:** No events for score/fix/share (by design privacy-first, but no measurement plan either).  
+**Impact:** Cannot learn if UX works post-launch.  
+**Recommendation:** Privacy-safe local counters + optional anonymous funnel (no prompt text). See `06-outcome-measurement-plan.md`.
+
+### F9 — CLI/Action continuity weak on web  
+**Severity:** Low · **Class:** informational  
+**Evidence:** Footer codes only.  
+**Impact:** Web users don't graduate to CI.  
+**Recommendation:** After score, "Gate this in CI" copy-paste block with scan/action snippet.
+
+## Prioritized decision list
+
+1. Redesign primary workflow stages + fix plan/apply (F1, F2)  
+2. Capability stamp + decision-first results (F3, F4)  
+3. Demote vendor IA (F5)  
+4. Distinctive preflight visual system (F6)  
+5. Empty/error/success states (F7)  
+6. Measurement without prompt capture (F8)  
+7. CI handoff CTA (F9)

crewscore-0.2.6/_product-experience/02-workflow-and-feature-design.md

@@ -0,0 +1,60 @@
+# CrewScore — Workflow & feature design
+
+## Outcome
+
+Builder completes a **structural preflight** on an agent prompt: knows overall hygiene, top missing signals, optionally applies text templates with consent, and leaves with share/CI next step — without believing the product is a red-team.
+
+## Target primary workflow
+
+```
+Entry (cold / return)
+  → Stage 1 PROMPT: paste | template | URL
+  → Stage 2 INSPECT: score + capability stamp + top gaps + dims
+  → Stage 3 ACT: plan fix → approve → re-inspect
+  → Stage 4 EXPORT: share image/text | CI snippet | improved prompt
+```
+
+### Stage details
+
+| Stage | User intent | Happy path | Empty | Error | Recovery |
+| --- | --- | --- | --- | --- | --- |
+| PROMPT | Provide artifact | Template or paste | Invite "Weak demo" | — | — |
+| INSPECT | Understand gaps | Score + top 3 gaps | — | Engine missing | Reload |
+| ACT | Improve text | Preview sections → Apply | No weak dims → "Already covered" | — | Cancel keeps original |
+| EXPORT | Take result elsewhere | Share / download / CI | — | Clipboard denied | Manual select |
+
+## Secondary workflow
+
+**Vendor self-attest** — linked, not staged with primary. Self-attest stamp. No equal chrome.
+
+## Information architecture
+
+- **Primary nav:** none (single job page)
+- **Progress:** step indicator 1–4 (or Prompt / Inspect / Act / Export)
+- **Results hierarchy:** (1) overall + soft verdict (2) capability stamp (3) top gaps (4) dimensions (5) all rules (6) export
+- **Progressive disclosure:** full rules collapsed; formula collapsed
+
+## Agentic / AI interaction contract
+
+CrewScore scoring is **deterministic**, not generative. The only "agent-like" action is **fix** (mutates user content).
+
+| Action | Autonomy | Control |
+| --- | --- | --- |
+| Score | Auto on request | User initiates; no network model |
+| Explain findings | Auto with score | Expand/collapse; open rule_ids |
+| Fix plan | Preview only | List dimensions/sections that would be appended |
+| Apply fix | Explicit approval | Apply / Cancel; original retained until Apply |
+| Share | User-triggered | Copy text / image; disclaimer in share string |
+| URL load | User-triggered | CORS failure → paste fallback |
+
+**Prohibited claims in UI:** certification, audit complete, red-team pass, runtime safety proven.
+
+**Uncertainty:** Always structural-only; template_boilerplate warning when fix templates detected.
+
+## Acceptance signals
+
+- Time from land → first score ≤ 20s with template  
+- Fix cannot change text without Apply  
+- After score, user sees capability stamp without scrolling past fold on desktop  
+- Vendor not equal-weight with primary CTA  
+- Share text includes "not a red-team"  

crewscore-0.2.6/_product-experience/06-outcome-measurement-plan.md

@@ -0,0 +1,59 @@
+# CrewScore — Outcome measurement plan
+
+## Decision this plan supports
+
+Did the preflight web experience improve **successful structural pre-gates** (score → understand → act → export) without increasing overclaim/trust failure?
+
+## Population & journey
+
+- **Population:** Anonymous visitors to crewscore.ai + optional CLI users (separate)  
+- **Journey boundary:** First paint → first score → optional fix apply → optional share/CI copy  
+- **Baseline:** Pre-redesign qualitative (manual Playwright + audit F1–F9)  
+- **Comparison:** Post-deploy week-over-week funnel (if analytics enabled)
+
+## Metrics (balanced)
+
+| Outcome | Metric | Guardrail |
+| --- | --- | --- |
+| Activation | % sessions with ≥1 score | Bounce without interaction |
+| Understanding | % expand "top gaps" or dim row | Time-to-score only |
+| Controlled fix | % fix_plan_shown → fix_applied | fix_applied without plan (should be ~0) |
+| Export | % share_or_download_or_ci_copy | Share without score (should be 0) |
+| Trust | Qualitative: can restate "not red-team" | Support/issue reports of overclaim |
+| Privacy | Zero prompt text in analytics | Any payload containing prompt body = fail |
+
+## Event semantics (privacy-safe)
+
+No prompt text, no URLs of private gists content, no PII.
+
+| Event | Properties |
+| --- | --- |
+| `cs_score` | `source`: template\|paste\|url; `overall_bucket`: 0\|1-49\|50-69\|70-89\|90-100; `ruleset` |
+| `cs_fix_plan` | `dims_to_fix_count` |
+| `cs_fix_apply` | `delta_bucket` |
+| `cs_fix_cancel` | — |
+| `cs_export` | `kind`: share_text\|share_img\|download_prompt\|ci_copy |
+| `cs_rules_expand` | — |
+| `cs_vendor_open` | — |
+
+**Implementation default for OSS launch:** localStorage counters only (`crewscore_metrics_v1`) + optional `console.debug` — no third-party by default. Document how to wire Plausible/Umami later with same events.
+
+**Schema authority:** Python module `crewscore/metrics.py` (`bucket_score`, `append_event`, `validate_props`) is the testable source of truth for event buckets and forbidden prop keys; web localStorage must keep matching event names/buckets.
+
+## Decision thresholds (pre-commit)
+
+| Signal | Green | Yellow | Red |
+| --- | --- | --- | --- |
+| Score rate (engaged sessions) | ≥40% | 20–40% | <20% |
+| Fix apply / plan ratio | 30–80% | <30% or >90% | plan never shown |
+| Export after score | ≥15% | 5–15% | <5% |
+| Trust issues (manual) | 0 severe | wording nits | "certification" complaints |
+
+## Qualitative
+
+- 5 builder think-alouds: "what does this score mean?"  
+- Show HN first-comment monitoring for black-box / overclaim language  
+
+## Limitations
+
+No production analytics currently; local counters only until owner enables privacy-respecting host.

{crewscore-0.2.4 → crewscore-0.2.6}/action.yml

@@ -27,7 +27,7 @@ inputs:
     required: false
     default: "crewscore-summary.md"
   pr-comment:
-    description: On pull_request events, post or update a sticky PR comment with the summary (requires pull-requests: write)
+    description: "On pull_request events, post or update a sticky PR comment with the summary (requires pull-requests write permission)"
     required: false
     default: "true"
 

{crewscore-0.2.4 → crewscore-0.2.6}/crewscore/__init__.py

@@ -1,3 +1,3 @@
 """CrewScore — offline structural production-readiness scorecard for AI agent prompts."""
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"

{crewscore-0.2.4 → crewscore-0.2.6}/crewscore/cli.py

@@ -429,13 +429,21 @@ def export_eval(prompt, prompt_file, output_dir):
     type=click.Path(),
     help="Write enhanced prompt to a new file",
 )
+@click.option(
+    "--plan",
+    "--dry-run",
+    "plan",
+    is_flag=True,
+    default=False,
+    help="List planned fix dimensions without writing (dry-run)",
+)
 @click.option(
     "--json",
     "as_json",
     is_flag=True,
     help="Emit JSON summary of applied dimensions and score delta",
 )
-def fix(prompt, prompt_file, apply, output, as_json):
+def fix(prompt, prompt_file, apply, output, plan, as_json):
     """Append recommended guardrail patterns to a system prompt."""
     from crewscore.scorers.fix_patterns import apply_fixes, explain_fixes, generate_fixes
 
@@ -454,6 +462,13 @@ def fix(prompt, prompt_file, apply, output, as_json):
         )
         sys.exit(1)
 
+    if plan and (apply or output):
+        err_console.print(
+            "[red]Error: --plan/--dry-run is mutually exclusive with "
+            "--apply and --output[/red]"
+        )
+        sys.exit(1)
+
     before = structural_analysis.analyze(system_prompt)
     before_result = build_result(before)
     fixes = generate_fixes(before)
@@ -463,6 +478,51 @@ def fix(prompt, prompt_file, apply, output, as_json):
         "(tool allowlists, human approval hooks, logging, and policy enforcement)"
     )
 
+    if plan:
+        planned = list(fixes.keys())
+        if as_json:
+            click.echo(
+                json.dumps(
+                    {
+                        "fixes_planned": planned,
+                        "before": before_result.to_dict(),
+                        "written": False,
+                        "note": honesty_note,
+                    },
+                    indent=2,
+                    sort_keys=True,
+                )
+            )
+            return
+        console.print()
+        console.print(
+            Panel(
+                f"[bold]{BRAND.upper()} — Fix Plan (dry-run)[/bold]",
+                border_style="cyan",
+                expand=False,
+            )
+        )
+        console.print()
+        if not planned:
+            console.print(
+                "  [green]No fixes needed — structural score is already strong.[/green]"
+            )
+        else:
+            console.print(
+                f"  [cyan]Would apply[/cyan] templates for {len(planned)} dimension(s):"
+            )
+            for key in planned:
+                console.print(f"    · {key}")
+            console.print()
+            console.print(explain_fixes(fixes))
+            console.print()
+            console.print(
+                "[dim]Plan only — file not modified. "
+                "Re-run without --plan and with --apply or --output to write.[/dim]"
+            )
+        console.print()
+        return
+
     if not fixes:
         if as_json:
             click.echo(

crewscore-0.2.6/crewscore/metrics.py

@@ -0,0 +1,81 @@
+"""Privacy-safe local metrics schema (no network, never store prompt text).
+
+Schema authority for event names/buckets used by web localStorage
+(`crewscore_metrics_v1`) and any future CLI counters.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+# Keys that must never appear in metrics payloads (case-insensitive).
+FORBIDDEN_PROP_KEYS = frozenset(
+    {
+        "prompt",
+        "text",
+        "body",
+        "system_prompt",
+        "content",
+    }
+)
+
+
+def bucket_score(n: int | float) -> str:
+    """Map an overall score to a privacy-safe bucket string."""
+    score = int(n) if n is not None else 0
+    if score <= 0:
+        return "0"
+    if score < 50:
+        return "1-49"
+    if score < 70:
+        return "50-69"
+    if score < 90:
+        return "70-89"
+    return "90-100"
+
+
+def validate_props(props: dict[str, Any] | None) -> bool:
+    """Reject payloads that could carry prompt or free-text body content.
+
+    Raises ValueError when a forbidden key is present (case-insensitive).
+    Returns True when props are safe.
+    """
+    if not props:
+        return True
+    for key in props:
+        if str(key).lower() in FORBIDDEN_PROP_KEYS:
+            raise ValueError(
+                f"metrics props must not include prompt text key: {key!r}"
+            )
+    return True
+
+
+def append_event(
+    store: dict[str, Any] | None,
+    event: str,
+    props: dict[str, Any] | None = None,
+    *,
+    max_events: int = 200,
+) -> dict[str, Any]:
+    """Append a privacy-checked event; cap store size to max_events (newest kept).
+
+    Store shape matches web localStorage:
+      {"events": [{"e": name, "t": epoch_ms, "p": props}, ...]}
+    """
+    props = dict(props or {})
+    validate_props(props)
+
+    out: dict[str, Any] = dict(store or {})
+    events = list(out.get("events") or [])
+    events.append(
+        {
+            "e": event,
+            "t": int(time.time() * 1000),
+            "p": props,
+        }
+    )
+    if max_events > 0 and len(events) > max_events:
+        events = events[-max_events:]
+    out["events"] = events
+    return out

crewscore-0.2.6/docs/superpowers/plans/2026-07-28-preflight-completion-sdd.md

@@ -0,0 +1,105 @@
+# Plan: Preflight completion slice (SDD + TDD)
+
+**Repo:** `C:\Repos\shmindmaster\crewscore`  
+**Branch:** `feat/preflight-completion` (off main)  
+**Goal:** Finish audit leftovers with TDD-backed, shippable product work — CLI fix plan parity, locked UX contracts, metrics module, export completion, 0.2.6.
+
+## Global constraints
+
+- TDD: failing test first for every production behavior change.
+- Honesty: structural pre-gate only; no red-team / certification claims.
+- Keep existing HTML contract strings: builder-first hero, "Vendor checklist (self-attest)", not-a-red-team, templates inflate.
+- Web scoring stays offline (`score-engine.js`); no LLM SDKs.
+- Tests: `py -3.13 -m pytest` must stay green.
+- Prefer small commits per task.
+- Do not force-push main; work on feature branch; PR or merge when green.
+
+## Tasks
+
+### Task 1 — CLI fix plan / dry-run (agentic parity with web)
+
+**Why:** Web has plan→apply; CLI `fix` still mutates or dumps with less control.
+
+**TDD:**
+1. RED: `test_fix_plan_json_lists_dimensions_without_writing` — `crewscore fix --prompt-file X --plan --json` exits 0, lists `fixes_planned` keys, does not change file.
+2. RED: `test_fix_plan_human_lists_dimensions` — human output mentions planned dimensions / "plan" language.
+3. GREEN: implement `--plan` / `--dry-run` on `fix` command.
+4. RED/GREEN: without `--plan` or `--apply`/`--output`, behavior unchanged (print enhanced prompt).
+
+**Files:** `crewscore/cli.py`, `tests/test_cli.py`, optionally thin helper in `scorers/fix_patterns.py`.
+
+**Done when:** pytest for plan flags pass; applying still works.
+
+---
+
+### Task 2 — Web UX contract tests (lock preflight workflow)
+
+**Why:** Audit F1–F5 implemented in HTML without strong regression tests.
+
+**TDD:**
+1. RED tests in `tests/test_web_ux.py` asserting `index.html` contains:
+   - stage markers: Prompt / Inspect / Act / Export (or `stg-prompt` … `stg-export`)
+   - "Plan fix" or plan-before-mutate language
+   - "Apply plan" and Cancel
+   - capability stamp "Structural pre-gate"
+   - vendor secondary (not equal primary tab list as only chrome)
+   - `crewscore_metrics_v1` or track() privacy events
+2. GREEN: only if HTML missing pieces — fix HTML to match; do not remove honesty strings.
+
+**Files:** `tests/test_web_ux.py`, possibly `index.html`.
+
+**Done when:** new tests pass; existing vendor/web_engine tests pass.
+
+---
+
+### Task 3 — Privacy-safe metrics module (testable pure core)
+
+**Why:** F8 — metrics only inlined in index.html; untestable.
+
+**TDD:**
+1. RED: pure functions in Python or small JS-testable contract — prefer Python helper `crewscore/metrics.py`:
+   - `bucket_score(n) -> str` buckets
+   - `append_event(store, event, props, *, max_events=200) -> store` no prompt keys allowed
+   - `assert_privacy(props)` rejects keys like `prompt`, `text`, `body`
+2. GREEN: implement module; wire optional CLI `crewscore` does not require metrics.
+3. Document web localStorage schema matches event names in `_product-experience/06-outcome-measurement-plan.md`.
+
+**Files:** `crewscore/metrics.py`, `tests/test_metrics.py`, doc touch if needed.
+
+**Done when:** metrics unit tests pass; no prompt capture.
+
+---
+
+### Task 4 — Export completion checklist + reduced-motion
+
+**Why:** F7 success state incomplete; a11y floor.
+
+**TDD:**
+1. RED: `test_web_ux` asserts export deck has completion checklist markers (e.g. `export-checklist` or three completion items: share/CI/prompt).
+2. RED: CSS or HTML has `prefers-reduced-motion` rule.
+3. GREEN: update `index.html` export stage + CSS.
+
+**Files:** `index.html`, `tests/test_web_ux.py`.
+
+**Done when:** tests pass.
+
+---
+
+### Task 5 — Version 0.2.6 + README CLI docs + ship
+
+**Why:** Surface new `--plan` flag; ship coherent release.
+
+**TDD:**
+1. RED: version string expectations if any (prefer dynamic RULESET/version tests already).
+2. GREEN: bump `__version__` / pyproject to 0.2.6; export web engine; README documents `crewscore fix --plan`.
+3. Run full pytest; commit; open PR or merge to main; tag/publish only if existing publish pattern allowed (PyPI via 1Password).
+
+**Files:** `crewscore/__init__.py`, `pyproject.toml`, `README.md`, `score-engine.js`, AGENTS.md if needed.
+
+**Done when:** full suite green; package version 0.2.6; docs mention plan.
+
+## Parallelism note
+
+Tasks 1 and 3 are file-independent (can parallel via worktrees).  
+Tasks 2 and 4 share `index.html` / `test_web_ux.py` — sequential after 1 or with 1 done.  
+Task 5 last.

crewscore-0.2.6/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="3" fill="#0a0c0b"/>
+  <rect x="2" y="2" width="28" height="28" rx="2" fill="none" stroke="#e8a317" stroke-width="1.5" opacity="0.7"/>
+  <text x="16" y="21" text-anchor="middle" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="11" font-weight="700" fill="#e8a317">CS</text>
+</svg>