feat: consolidate the owner-led acceptance workflow

CHANGELOG.md

@@ -21,6 +21,12 @@ Development version: `0.2.4.dev0`. Public install remains the immutable v0.2.3 r
 
 ### Post-release engineering
 
+- Consolidated the owner workflow around visible public-PR and constructed-demo entry points,
+  explicit criteria confirmation, unresolved-decision progress, and direct criterion navigation.
+  Optional alpha-feedback controls now live under research options, constructed demo records remain
+  explicitly segregated, and evidence types remain separate. Added a documentation index that
+  distinguishes current operating guidance from historical evidence snapshots, and refreshed the
+  official-source market comparison without claiming customer or market validation.
 - Limited analysis concurrency to redundant same-PR, same-head runs while leaving every revocation
   writer runnable. The publisher revalidates the live pull immediately before mutation and
   neutralizes its exact Check if identity or applicability changes after the write. Default-base

README.md

@@ -137,6 +137,8 @@ they do not establish correctness, customer validation, or Stage 1 progress.
 See the
 [v0.2.3 status and next-stage audit](docs/releases/v0.2.3-status-and-next-stages.md)
 for the implemented feature ledger, current gaps, and owner-led Stage 2 roadmap.
+The [documentation map](docs/README.md) separates current operating documents from historical
+evidence snapshots.
 
 ```bash
 python3 -m venv .venv

ROADMAP.md

@@ -20,6 +20,7 @@ which provides the wheel, source archive, and checksum manifest.
 | Published install | v0.2.3 GitHub Release with wheel, source archive, and checksum manifest |
 | Active source line | Unreleased `0.2.4.dev0`; no v0.2.4 release, tag, or package publication exists |
 | Post-PR #193 resulting-main snapshot (2026-08-13) | PR #193 product-source baseline at `432371c4faec0b790f70fec32b4d3fc4d5132cfa` (PR head `8bb407079a0ff7098d2fc18af3d75b216725df2e`, base `9426e8714ffd2c3742bb074ae26fc788f1049c63`) |
+| Post-PR #196 resulting-main snapshot (2026-08-17) | Exact PR #196 head `5a6a25a6dff23cdfa8dcb4023b83144078620610` landed in merge `8387156fd6f6e90eef7caf58881b0cc5bb62b111`; hosted resulting-main CI run [`32093041685`](https://github.com/YuzeJ21/Scope-Proof/actions/runs/32093041685) succeeded as the exact-head engineering record |
 | Verified product baseline | PR #184 release integration landed on `main` at `448c42758ea139bf9203cbf1bb04b02b02ae412c` |
 | Product verification | Full product-code verification is bound to `fb74d4bbb402f4de3e2fabb56ce28c948214f8c2`; package, install, installed-benchmark, and health artifacts are bound to `81598899fcd85df58ab22f9212f2e8382f4a5e5f`. |
 | Release integration evidence | PR #184 release integration at `448c42758ea139bf9203cbf1bb04b02b02ae412c`; exact-main CI, CodeQL, and Pages all succeeded, and `origin/main` matched at the 2026-08-08 branch-start snapshot |
@@ -49,6 +50,13 @@ storage. The dated post-PR #193 resulting-main snapshot at
 declaration of perpetually current `main`. These are engineering changes on `0.2.4.dev0`, not a
 new published release; v0.2.3 remains the published release and none earns Stage 1 credit.
 
+PR #194 aligned the dated status record without turning it into a moving-head claim; PR #195 closed
+Stage 1 as not pursued and activated owner-led Stage 2 without customer-validation claims; and PR
+#196 added the exact-head informational Check lifecycle with bounded default-base repair. The next
+owner workflow consolidation slice may simplify first use, criteria confirmation, decision progress,
+and current documentation. It remains Stage 2 engineering work and does not claim customer
+validation.
+
 ### Verification and evidence boundaries
 
 - Engineering checks do not prove acceptance-criteria correctness.
@@ -281,6 +289,11 @@ validation. Work may improve product and workflow clarity, deterministic evidenc
 fail-closed lifecycle integrity, packaging, installation, compatibility, accessibility
 engineering, documentation, public official-source research, and release readiness.
 
+The current owner workflow consolidation priority is to keep public PR and constructed-demo entry
+clear, make explicit criteria confirmation unmistakable, put unresolved decisions before secondary
+evidence detail, and provide direct navigation to the next criterion. It must preserve every
+evidence boundary and keep optional external research secondary.
+
 The [Stage 2 productization packet](docs/commercialization/stage2-readiness-packet.md) is the
 operating boundary. External commercial discovery is optional and separate from owner-led
 productization. It is not required to continue Stage 2 and needs separate owner authorization

apps/web/app.py

@@ -1149,11 +1149,18 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
 fetch_action_placeholder = st.empty()
 alpha_feedback_mode = bool(st.session_state.get("alpha_feedback_mode", False))
 
-with st.expander("Try ScopeProof", expanded=False):
+with st.container(border=True):
+    st.markdown("**Deliberately constructed demonstration**")
+    st.caption(
+        "A visible practice-data path. Any saved record remains constructed-demo-tagged and "
+        "segregated from genuine review claims. It is not a public PR, customer case, production "
+        "result, or validation claim."
+    )
     if st.button(
         "Load deliberately constructed demo",
         key="load_demo",
         disabled=replacement_blocked or alpha_feedback_mode,
+        use_container_width=True,
     ):
         labels = load_demo_labels()
         snapshot = load_demo_snapshot()
@@ -1179,13 +1186,42 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
         _reset_analysis()
         st.rerun()
 
-with st.expander("Alpha feedback session (optional)", expanded=False):
+with st.expander("Advanced source options", expanded=False):
+    github_token = st.text_input(
+        "Optional GitHub token",
+        type="password",
+        help=(
+            "Used only in this session to increase free GitHub rate limits. "
+            "Never exported or saved."
+        ),
+        key="github_token",
+    )
+    candidate_paths_text = st.text_area(
+        "Bounded unchanged candidate paths (optional)",
+        key="candidate_paths",
+        help=(
+            "One explicit repository-relative file path per line. ScopeProof does not "
+            "infer paths or scan the repository."
+        ),
+    )
+    candidate_paths = list(
+        dict.fromkeys(
+            line.strip() for line in candidate_paths_text.splitlines() if line.strip()
+        )
+    )
+    st.caption("At most eight explicit UTF-8 text files are fetched at the PR head SHA.")
+
+requirements_source_url = ""
+with st.expander("Research and historical options", expanded=False):
+    st.caption(
+        "Stage 1 is closed and external feedback is not required for owner-led Stage 2. "
+        "This optional research path is separate from the standard product workflow."
+    )
     alpha_feedback_mode = st.checkbox(
         "Collect local alpha feedback for this review",
         value=False,
         key="alpha_feedback_mode",
     )
-
     if alpha_feedback_mode:
         st.caption(
             "Qualification is session-only. Confirm a genuine public case before fetching; "
@@ -1209,6 +1245,7 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
             "This review contains no confidential information, secrets, or private links",
             key="no_confidential_information",
         )
+
 alpha_qualification_ready = True
 alpha_qualification_input: AlphaQualificationInput | None = None
 alpha_qualification: AlphaQualification | None = None
@@ -1252,30 +1289,6 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
 else:
     st.caption("Standard review mode does not create participant research records.")
 
-with st.expander("Advanced source options", expanded=False):
-    github_token = st.text_input(
-        "Optional GitHub token",
-        type="password",
-        help=(
-            "Used only in this session to increase free GitHub rate limits. "
-            "Never exported or saved."
-        ),
-        key="github_token",
-    )
-    candidate_paths_text = st.text_area(
-        "Bounded unchanged candidate paths (optional)",
-        key="candidate_paths",
-        help=(
-            "One explicit repository-relative file path per line. ScopeProof does not "
-            "infer paths or scan the repository."
-        ),
-    )
-    candidate_paths = list(
-        dict.fromkeys(
-            line.strip() for line in candidate_paths_text.splitlines() if line.strip()
-        )
-    )
-    st.caption("At most eight explicit UTF-8 text files are fetched at the PR head SHA.")
 reopened_review = st.session_state["review_state"]
 fetch_action_label = (
     "Check current head"
@@ -1696,8 +1709,12 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
             for message in warnings_by_criterion[criterion_id]:
                 st.warning(message)
 
+    st.caption(
+        "Typing or pressing Enter only stages draft changes. Use the explicit action below "
+        "to apply edits and bind the confirmed criteria snapshot."
+    )
     confirm_clicked = confirm_action_placeholder.button(
-        "Confirm criteria",
+        "Apply edits and confirm criteria",
         key="confirm_criteria",
         disabled=(
             bool(blank_criterion_ids)
@@ -2070,11 +2087,6 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
             if comparison.ruleset_version_changed
             else "Ruleset unchanged between reviews."
         )
-    st.caption(
-        "Evidence status describes deterministic candidates, not correctness. Evidence types "
-        "keep implementation, test, and externally recorded runtime observations separate."
-    )
-    _render_ci_observation_summary(bundle)
     finding_by_id = {finding.criterion_id: finding for finding in bundle.findings}
     diagnostic_by_id = {
         diagnostic.criterion_id: diagnostic
@@ -2086,6 +2098,54 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
     coverage_by_id = {
         row.criterion_id: row for row in criterion_coverage_rows(bundle)
     }
+    blocking_criteria = set(bundle.gate.blocking_criteria)
+    unresolved_ids = [
+        criterion.criterion_id
+        for criterion in bundle.criteria
+        if criterion.criterion_id not in resolution_by_id
+    ]
+    recorded_decisions = len(bundle.criteria) - len(unresolved_ids)
+    st.markdown("### Decision progress")
+    st.caption(
+        f"Decisions recorded: {recorded_decisions} of {len(bundle.criteria)}."
+    )
+    if unresolved_ids:
+        st.markdown("### Unresolved criteria queue")
+        st.caption(
+            "Review candidate evidence and record an explicit human decision for each item."
+        )
+        for criterion_id in unresolved_ids:
+            st.markdown(f"[Review {criterion_id}](#review-{criterion_id.lower()})")
+        for criterion_id in unresolved_ids:
+            criterion = next(
+                item for item in bundle.criteria if item.criterion_id == criterion_id
+            )
+            with st.container(border=True):
+                st.markdown(f"#### Review {criterion_id}")
+                st.text(criterion.text)
+                evidence_status = evidence_status_text(
+                    coverage_by_id[criterion_id].evidence_status
+                )
+                st.caption(
+                    f"Candidate evidence: {evidence_status}"
+                )
+                st.caption(
+                    "Observed runtime evidence and the human acceptance decision remain "
+                    "separate from static implementation or test candidates."
+                )
+                st.text(finding_by_id[criterion_id].recommended_action)
+                if st.button(
+                    f"Open {criterion_id} decision controls",
+                    key=f"inspect_queue_{criterion_id}",
+                ):
+                    st.session_state["selected_criterion"] = criterion_id
+    else:
+        st.success("A current human decision is recorded for every active criterion.")
+    st.caption(
+        "Evidence status describes deterministic candidates, not correctness. Evidence types "
+        "keep implementation, test, and externally recorded runtime observations separate."
+    )
+    _render_ci_observation_summary(bundle)
     evidence_strength_counts = {
         EvidenceStatus.STRONG_CANDIDATE: 0,
         EvidenceStatus.WEAK_CANDIDATE: 0,
@@ -2125,7 +2185,6 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
             format_func=lambda item: item.value,
             key="evidence_level_filter",
         )
-    blocking_criteria = set(bundle.gate.blocking_criteria)
     matrix = []
     for criterion in bundle.criteria:
         finding = finding_by_id[criterion.criterion_id]
@@ -2161,6 +2220,7 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
         )
         for row in matrix:
             with st.container(border=True):
+                st.markdown(f"#### Evidence for {row['Criterion']}")
                 st.markdown(f"**Criterion:** {row['Criterion']}")
                 st.caption("Requirement")
                 st.text(row["Requirement"])
@@ -2184,22 +2244,6 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
                     st.session_state["selected_criterion"] = row["Criterion"]
                     st.rerun()
 
-    unresolved_ids = [
-        criterion.criterion_id
-        for criterion in bundle.criteria
-        if criterion.criterion_id not in resolution_by_id
-    ]
-    if unresolved_ids:
-        st.markdown("### Unresolved criteria queue")
-        st.caption(
-            "Review candidate evidence and record an explicit human decision for each item."
-        )
-        for criterion_id in unresolved_ids:
-            st.markdown(
-                f"- **{criterion_id}** — "
-                f"{finding_by_id[criterion_id].recommended_action}"
-            )
-
     st.header("4 · Criterion Detail")
     criterion_ids = [criterion.criterion_id for criterion in bundle.criteria]
     selected_criterion = st.session_state.get("selected_criterion")
@@ -2819,6 +2863,18 @@ def _render_ingestion_limitations(source: PullRequestSnapshot | Review | None) -
             st.markdown("### What to do next")
             for message in guidance:
                 st.text(message)
+        if unresolved_ids:
+            st.markdown(
+                "[Review next unresolved criterion]"
+                f"(#review-{unresolved_ids[0].lower()})"
+            )
+        elif not final_acceptance_recorded:
+            st.markdown(
+                "[Record final acceptance after reviewing every criterion]"
+                "(#final-review-acceptance)"
+            )
+        else:
+            st.caption("Save the validated review locally or download an export below.")
         st.caption(
             f"Head SHA {bundle.review.head_sha} · Ruleset {bundle.review.ruleset_version} · "
             "results are reproducible from the exported review"

docs/README.md

@@ -0,0 +1,31 @@
+# ScopeProof documentation map
+
+Use current operating documents for product decisions. Historical records are immutable evidence
+snapshots: they preserve what was observed at a named commit or release and must not be read as the
+current product state.
+
+## Current operating documents
+
+- [Product roadmap](../ROADMAP.md) — current stage decisions, boundaries, and next owner gates.
+- [v0.2.3 status and next stages](releases/v0.2.3-status-and-next-stages.md) — published-release
+  boundary, current development line, feature ledger, gaps, and stage status.
+- [Stage 2 productization packet](commercialization/stage2-readiness-packet.md) — authorized
+  owner-led engineering scope; it does not claim customer validation.
+- [Current official-source market comparison](commercialization/market-comparison-2026-07-26.md)
+  — dated competitive research and positioning hypotheses.
+- [Development environment](development-environment.md) — supported and unsupported engineering
+  environments.
+- [Privacy readiness](privacy-readiness.md) — current local-only data and trust boundaries.
+
+## Historical evidence records
+
+- `docs/audits/` contains exact-head implementation, verification, and review snapshots.
+- `docs/releases/` contains published-release and post-merge evidence records. The current status
+  document linked above is the exception and explicitly distinguishes live operating status from
+  dated evidence.
+- `docs/research/` contains constructed or historical research evidence. It does not establish
+  customer validation or advance a product stage.
+
+When documents differ, prefer the GitHub Release for publication availability, the current roadmap
+for stage authority, and exact-head hosted checks for engineering results. Missing external evidence
+remains missing.