devtime-ei 0.4.0__tar.gz → 0.5.1__tar.gz

{devtime_ei-0.4.0/src/devtime_ei.egg-info → devtime_ei-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devtime-ei
-Version: 0.4.0
+Version: 0.5.1
 Summary: Local-first Engineering Intelligence for software repositories
 Author-email: Aviad Shakargi <aviad94@gmail.com>
 Maintainer-email: Aviad Shakargi <aviad94@gmail.com>
@@ -8,7 +8,7 @@ License: Apache-2.0
 Project-URL: Homepage, https://github.com/Shakargy/devtime
 Project-URL: Repository, https://github.com/Shakargy/devtime
 Project-URL: Issues, https://github.com/Shakargy/devtime/issues
-Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.4.0
+Project-URL: Release Notes, https://github.com/Shakargy/devtime/releases/tag/v0.5.1
 Project-URL: Demo, https://youtu.be/1Hiu3Y9J_SI
 Keywords: devtools,cli,static-analysis,repository-analysis,engineering-intelligence,local-first
 Classifier: Development Status :: 3 - Alpha
@@ -39,17 +39,17 @@ Dynamic: license-file
 
 # DevTime
 
-**Local-first Engineering Intelligence for software repositories.**
+**DevTime verifies what your repository can actually prove.**
 
-DevTime helps a codebase explain itself from evidence.
-
-It scans code, tests, configs, routes, and decisions to identify supported software
-concepts, link claims to files, surface uncertainty, and warn about a narrow set of
-risky changes.
+A file named `stripe/webhook.ts` looks like proof that a repo handles Stripe
+webhooks. It might be a handler that only returns 404. DevTime checks statements
+about a repository against its implementation, tests, configuration, and recorded
+decisions, then reports what is supported, what is contradicted, what is missing,
+and what went stale.
 
 > No cloud. No telemetry. No code execution. No AI required.
 
-![DevTime terminal demo - install, scan, and explain a repo from evidence](assets/devtime-terminal-demo.svg)
+![DevTime verify demo - a claim goes from SUPPORTED to CONTRADICTED to STALE](assets/devtime-verify-demo.svg)
 
 Prefer video? [Watch the 2-minute demo](https://youtu.be/1Hiu3Y9J_SI): DevTime scans
 a repo locally, explains concepts from evidence, surfaces uncertainty, catches a
@@ -65,8 +65,17 @@ dtc demo init
 cd devtime-demo-saas
 dtc init
 dtc scan
-dtc concepts
-dtc explain "Billing Webhooks"
+dtc verify
+```
+
+On the demo repo that ends with billing webhook signature verification
+SUPPORTED, JWT authentication SUPPORTED, and route test association WEAK, naming
+the routes with no test importing them. Point it at your own repository and the
+answers change:
+
+```bash
+cd your-repo
+dtc init && dtc scan && dtc verify
 ```
 
 The PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the
@@ -115,6 +124,39 @@ dtc risk --diff
 A full, copy-pasteable walkthrough (including the risk-diff and corroborated-decision
 steps) is in **[DEMO_SCRIPT.md](DEMO_SCRIPT.md)**.
 
+## Verify claims (experimental)
+
+A claim is a statement about the repository. Verification answers it with a
+status and receipts, never with confidence the evidence cannot back.
+
+```text
+Status: CONTRADICTED
+
+Contradictions:
+  - The billing webhook endpoint cannot verify signatures
+    because it is a disabled stub.
+      claimed:  pages/api/stripe/webhook.ts is named and routed
+                as a billing webhook endpoint.
+      observed: The handler's only behavior is a 404/501 response.
+```
+
+- **SUPPORTED** - required behavior evidence exists in the current scan
+- **WEAK** - the surface exists, but the proving evidence is missing
+- **CONTRADICTED** - credible evidence conflicts with the claim, both sides shown
+- **UNKNOWN** - the surface exists but coverage cannot responsibly decide
+- **NOT_APPLICABLE** - the repository has no surface this claim is about
+
+Four built-in claims ship: route test association, admin authorization, billing
+webhook signatures, and JWT authentication. `dtc verify` leads with what it can
+actually verify in your repository, and when nothing applies it says what would
+make a claim verifiable instead of dead-ending.
+
+Truth and freshness are separate: when a file behind a verified claim changes,
+the claim goes STALE and names the file. `dtc risk --diff` reports which verified
+claims a diff destabilizes.
+
+See **[VERIFICATION.md](VERIFICATION.md)** for the full model and its limits.
+
 ## Why this exists
 
 Git records what changed, but it does not preserve the reasoning behind those
@@ -142,6 +184,7 @@ It is especially useful if you:
 
 Questions DevTime helps answer include:
 
+- Can this repository actually prove the thing its file names imply?
 - Where is authentication actually implemented?
 - What files prove that Billing Webhooks exist?
 - What is still uncertain?
@@ -150,17 +193,25 @@ Questions DevTime helps answer include:
 
 ## What DevTime does
 
+- Verifies claims about a repository and reports status, evidence, and both sides
+  of any contradiction.
+- Tracks freshness, so a verified claim goes stale when the evidence behind it changes.
 - Detects concepts from routes, tests, configs, dependencies, and docs.
 - Explains from evidence by linking claims to files and signals.
 - Surfaces uncertainty when evidence is missing or weak.
 - Scores understanding with an Understanding Score and Understanding Debt label.
-- Reviews narrow risky diffs with advisory findings from local memory.
+- Reviews narrow risky diffs with advisory findings, including which verified
+  claims a diff destabilizes.
 - Records decisions locally so rationale can reduce uncertainty when corroborated by code.
 
 ## Supported concepts
 
-V0 detects six supported concept families. It does not discover arbitrary domain
-concepts yet:
+Underneath verification is a scanner that builds local, evidence-backed memory:
+
+![DevTime terminal demo - install, scan, and explain a repo from evidence](assets/devtime-terminal-demo.svg)
+
+DevTime detects six supported concept families. It does not discover arbitrary
+domain concepts yet:
 
 - Authentication
 - Billing Webhooks
@@ -169,7 +220,7 @@ concepts yet:
 - Admin Permissions
 - File Uploads
 
-Anything outside these six is out of scope for V0. See [LIMITATIONS.md](LIMITATIONS.md).
+Anything outside these six is out of scope for now. See [LIMITATIONS.md](LIMITATIONS.md).
 
 ## What DevTime does not do
 
@@ -204,7 +255,7 @@ Anything outside these six is out of scope for V0. See [LIMITATIONS.md](LIMITATI
 | `dtc context <concept>` | Create a governed Context Pack for agents or humans. |
 | `dtc risk --diff` | Review a git diff for risky changes using local evidence (advisory). |
 | `dtc decision add` | Add a local decision record that can reduce uncertainty. |
-| `dtc verify [claim]` | Verify a repository claim against evidence: status, contradictions, freshness (experimental). |
+| `dtc verify [claim]` | Verify repository claims against evidence: status, contradictions, freshness (experimental). |
 
 (Also available: `dtc evidence`, `dtc debt`, `dtc status`, `dtc doctor --privacy`,
 `dtc export`, `dtc reset`, `dtc mcp start`.)
@@ -296,30 +347,6 @@ python -m venv .venv
 pip install -e ".[dev]"
 ```
 
-## Verify claims (experimental)
-
-DevTime is growing into a verification layer: ask whether a statement about the
-repository is actually supported.
-
-```bash
-dtc verify billing-webhook-signature
-```
-
-```
-Billing Webhook Signature Verification
-Claim: Incoming billing webhooks verify the payment provider's signature.
-Status: CONTRADICTED
-
-Contradictions:
-  - The billing webhook endpoint cannot verify signatures because it is a disabled stub.
-      claimed:  apps/web/pages/api/stripe/webhook.ts is named and routed as a billing webhook endpoint.
-      observed: The handler's only behavior is a 404/501 response.
-```
-
-Statuses are SUPPORTED, WEAK, CONTRADICTED, or UNKNOWN; contradictions always
-show both sides; changed evidence marks a claim STALE. Two built-in claims ship
-(billing webhook signatures, JWT authentication). See **[VERIFICATION.md](VERIFICATION.md)**.
-
 ## Example output
 
 ```

{devtime_ei-0.4.0 → devtime_ei-0.5.1}/README.md

@@ -1,16 +1,16 @@
 # DevTime
 
-**Local-first Engineering Intelligence for software repositories.**
+**DevTime verifies what your repository can actually prove.**
 
-DevTime helps a codebase explain itself from evidence.
-
-It scans code, tests, configs, routes, and decisions to identify supported software
-concepts, link claims to files, surface uncertainty, and warn about a narrow set of
-risky changes.
+A file named `stripe/webhook.ts` looks like proof that a repo handles Stripe
+webhooks. It might be a handler that only returns 404. DevTime checks statements
+about a repository against its implementation, tests, configuration, and recorded
+decisions, then reports what is supported, what is contradicted, what is missing,
+and what went stale.
 
 > No cloud. No telemetry. No code execution. No AI required.
 
-![DevTime terminal demo - install, scan, and explain a repo from evidence](assets/devtime-terminal-demo.svg)
+![DevTime verify demo - a claim goes from SUPPORTED to CONTRADICTED to STALE](assets/devtime-verify-demo.svg)
 
 Prefer video? [Watch the 2-minute demo](https://youtu.be/1Hiu3Y9J_SI): DevTime scans
 a repo locally, explains concepts from evidence, surfaces uncertainty, catches a
@@ -26,8 +26,17 @@ dtc demo init
 cd devtime-demo-saas
 dtc init
 dtc scan
-dtc concepts
-dtc explain "Billing Webhooks"
+dtc verify
+```
+
+On the demo repo that ends with billing webhook signature verification
+SUPPORTED, JWT authentication SUPPORTED, and route test association WEAK, naming
+the routes with no test importing them. Point it at your own repository and the
+answers change:
+
+```bash
+cd your-repo
+dtc init && dtc scan && dtc verify
 ```
 
 The PyPI distribution is `devtime-ei`. The Python package remains `devtime`, and the
@@ -76,6 +85,39 @@ dtc risk --diff
 A full, copy-pasteable walkthrough (including the risk-diff and corroborated-decision
 steps) is in **[DEMO_SCRIPT.md](DEMO_SCRIPT.md)**.
 
+## Verify claims (experimental)
+
+A claim is a statement about the repository. Verification answers it with a
+status and receipts, never with confidence the evidence cannot back.
+
+```text
+Status: CONTRADICTED
+
+Contradictions:
+  - The billing webhook endpoint cannot verify signatures
+    because it is a disabled stub.
+      claimed:  pages/api/stripe/webhook.ts is named and routed
+                as a billing webhook endpoint.
+      observed: The handler's only behavior is a 404/501 response.
+```
+
+- **SUPPORTED** - required behavior evidence exists in the current scan
+- **WEAK** - the surface exists, but the proving evidence is missing
+- **CONTRADICTED** - credible evidence conflicts with the claim, both sides shown
+- **UNKNOWN** - the surface exists but coverage cannot responsibly decide
+- **NOT_APPLICABLE** - the repository has no surface this claim is about
+
+Four built-in claims ship: route test association, admin authorization, billing
+webhook signatures, and JWT authentication. `dtc verify` leads with what it can
+actually verify in your repository, and when nothing applies it says what would
+make a claim verifiable instead of dead-ending.
+
+Truth and freshness are separate: when a file behind a verified claim changes,
+the claim goes STALE and names the file. `dtc risk --diff` reports which verified
+claims a diff destabilizes.
+
+See **[VERIFICATION.md](VERIFICATION.md)** for the full model and its limits.
+
 ## Why this exists
 
 Git records what changed, but it does not preserve the reasoning behind those
@@ -103,6 +145,7 @@ It is especially useful if you:
 
 Questions DevTime helps answer include:
 
+- Can this repository actually prove the thing its file names imply?
 - Where is authentication actually implemented?
 - What files prove that Billing Webhooks exist?
 - What is still uncertain?
@@ -111,17 +154,25 @@ Questions DevTime helps answer include:
 
 ## What DevTime does
 
+- Verifies claims about a repository and reports status, evidence, and both sides
+  of any contradiction.
+- Tracks freshness, so a verified claim goes stale when the evidence behind it changes.
 - Detects concepts from routes, tests, configs, dependencies, and docs.
 - Explains from evidence by linking claims to files and signals.
 - Surfaces uncertainty when evidence is missing or weak.
 - Scores understanding with an Understanding Score and Understanding Debt label.
-- Reviews narrow risky diffs with advisory findings from local memory.
+- Reviews narrow risky diffs with advisory findings, including which verified
+  claims a diff destabilizes.
 - Records decisions locally so rationale can reduce uncertainty when corroborated by code.
 
 ## Supported concepts
 
-V0 detects six supported concept families. It does not discover arbitrary domain
-concepts yet:
+Underneath verification is a scanner that builds local, evidence-backed memory:
+
+![DevTime terminal demo - install, scan, and explain a repo from evidence](assets/devtime-terminal-demo.svg)
+
+DevTime detects six supported concept families. It does not discover arbitrary
+domain concepts yet:
 
 - Authentication
 - Billing Webhooks
@@ -130,7 +181,7 @@ concepts yet:
 - Admin Permissions
 - File Uploads
 
-Anything outside these six is out of scope for V0. See [LIMITATIONS.md](LIMITATIONS.md).
+Anything outside these six is out of scope for now. See [LIMITATIONS.md](LIMITATIONS.md).
 
 ## What DevTime does not do
 
@@ -165,7 +216,7 @@ Anything outside these six is out of scope for V0. See [LIMITATIONS.md](LIMITATI
 | `dtc context <concept>` | Create a governed Context Pack for agents or humans. |
 | `dtc risk --diff` | Review a git diff for risky changes using local evidence (advisory). |
 | `dtc decision add` | Add a local decision record that can reduce uncertainty. |
-| `dtc verify [claim]` | Verify a repository claim against evidence: status, contradictions, freshness (experimental). |
+| `dtc verify [claim]` | Verify repository claims against evidence: status, contradictions, freshness (experimental). |
 
 (Also available: `dtc evidence`, `dtc debt`, `dtc status`, `dtc doctor --privacy`,
 `dtc export`, `dtc reset`, `dtc mcp start`.)
@@ -257,30 +308,6 @@ python -m venv .venv
 pip install -e ".[dev]"
 ```
 
-## Verify claims (experimental)
-
-DevTime is growing into a verification layer: ask whether a statement about the
-repository is actually supported.
-
-```bash
-dtc verify billing-webhook-signature
-```
-
-```
-Billing Webhook Signature Verification
-Claim: Incoming billing webhooks verify the payment provider's signature.
-Status: CONTRADICTED
-
-Contradictions:
-  - The billing webhook endpoint cannot verify signatures because it is a disabled stub.
-      claimed:  apps/web/pages/api/stripe/webhook.ts is named and routed as a billing webhook endpoint.
-      observed: The handler's only behavior is a 404/501 response.
-```
-
-Statuses are SUPPORTED, WEAK, CONTRADICTED, or UNKNOWN; contradictions always
-show both sides; changed evidence marks a claim STALE. Two built-in claims ship
-(billing webhook signatures, JWT authentication). See **[VERIFICATION.md](VERIFICATION.md)**.
-
 ## Example output
 
 ```

{devtime_ei-0.4.0 → devtime_ei-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devtime-ei"
-version = "0.4.0"
+version = "0.5.1"
 description = "Local-first Engineering Intelligence for software repositories"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -50,7 +50,7 @@ dev = [
 Homepage = "https://github.com/Shakargy/devtime"
 Repository = "https://github.com/Shakargy/devtime"
 Issues = "https://github.com/Shakargy/devtime/issues"
-"Release Notes" = "https://github.com/Shakargy/devtime/releases/tag/v0.4.0"
+"Release Notes" = "https://github.com/Shakargy/devtime/releases/tag/v0.5.1"
 Demo = "https://youtu.be/1Hiu3Y9J_SI"
 
 [project.scripts]

{devtime_ei-0.4.0 → devtime_ei-0.5.1}/src/devtime/__init__.py

@@ -1,6 +1,6 @@
 """DevTime - local-first Engineering Intelligence for repository memory."""
 
-__version__ = "0.4.0"
+__version__ = "0.5.1"
 
 # Version metadata (Builder Edition, Chapter 20).
 EVIDENCE_MODEL = "2026.06.1"

{devtime_ei-0.4.0 → devtime_ei-0.5.1}/src/devtime/cli.py

@@ -97,51 +97,71 @@ def verify(
     conn = connection.connect()
     try:
         if list_claims:
+            # Relevance is computed live so the list answers the useful question:
+            # which of these claims apply to THIS repository?
+            current = {r.claim_slug: r for r in ver.verify_all(conn)}
             rows = []
             for slug, definition in ver.BUILTIN_CLAIMS.items():
                 latest = ver.load_latest_verification(conn, slug)
                 freshness, changed = ver.freshness_for(conn, slug)
+                live = current.get(slug)
                 rows.append(
                     {
                         "claim_id": slug,
                         "name": definition.name,
                         "statement": definition.statement,
+                        "applies_here": bool(
+                            live and live.status in ver.APPLICABLE_STATUSES
+                        ),
+                        "current_status": live.status if live else None,
                         "last_status": latest[0]["status"] if latest else None,
                         "freshness": freshness,
                         "changed_evidence": changed,
                     }
                 )
+            rows.sort(key=lambda r: (not r["applies_here"], r["claim_id"]))
             if as_json:
-                console.print_json(_json.dumps({"schema_version": "1", "claims": rows}))
+                console.print_json(_json.dumps({"schema_version": "2", "claims": rows}))
             else:
                 console.print("[bold]Built-in claims[/bold]\n")
                 for r in rows:
+                    if not r["applies_here"]:
+                        console.print(f"  [dim]{r['claim_id']} (not applicable here)[/dim]")
+                        continue
                     status_txt = r["last_status"] or "never verified"
                     console.print(f"  {r['claim_id']}")
                     console.print(f"    {r['statement']}")
-                    console.print(f"    last status: {status_txt}   freshness: {r['freshness']}")
+                    console.print(
+                        f"    current: {r['current_status']}   "
+                        f"last verified: {status_txt}   freshness: {r['freshness']}"
+                    )
                     for p in r["changed_evidence"]:
                         console.print(f"      changed since verification: {p}", markup=False)
                     console.print("")
             return
 
-        slugs = [claim] if claim else list(ver.BUILTIN_CLAIMS.keys())
-        results = []
-        for slug in slugs:
+        if claim:
             try:
-                result = ver.verify_claim(conn, slug)
+                results = [ver.verify_claim(conn, claim)]
             except KeyError:
-                console.print(f"[red]Unknown claim:[/red] {slug}")
+                console.print(f"[red]Unknown claim:[/red] {claim}")
                 console.print("Run [bold]dtc verify --list[/bold] to see built-in claims.")
                 raise typer.Exit(code=1)
-            ver.save_verification(conn, result)
-            results.append(result)
+        else:
+            results = ver.verify_all(conn)
+
+        # Only real verifications are recorded. A claim that does not apply to
+        # this repository was not verified, so storing it would pollute
+        # freshness and diff impact with claims that have no evidence.
+        for result in results:
+            if result.status in ver.APPLICABLE_STATUSES:
+                ver.save_verification(conn, result)
 
         if as_json:
             console.print_json(
                 _json.dumps(
                     {
-                        "schema_version": "1",
+                        "schema_version": "2",
                         "command": "verify",
                         "results": [r.to_dict() for r in results],
                     }
@@ -149,11 +169,94 @@ def verify(
             )
             return
 
-        for result in results:
+        _print_report(results, single=bool(claim))
+    finally:
+        conn.close()
+
+
+def _print_report(results: list, single: bool) -> None:
+    """Report card: what DevTime can and cannot verify about this repository."""
+    from devtime.intelligence import verification as ver
+
+    applicable = [r for r in results if r.status in ver.APPLICABLE_STATUSES]
+    not_applicable = [r for r in results if r.status == ver.NOT_APPLICABLE]
+
+    for result in applicable:
+        _print_verification(result)
+
+    if not_applicable and not single:
+        console.print("[dim]Not applicable to this repository:[/dim]")
+        for r in not_applicable:
+            reason = r.why[0] if r.why else "No relevant surface was found."
+            console.print(f"  - {r.claim_slug}: {reason}", markup=False)
+        console.print("")
+
+    if single and not applicable:
+        # An explicitly requested claim that does not apply still explains itself.
+        for result in not_applicable:
             _print_verification(result)
+        return
+
+    if not applicable:
+        _print_nothing_verifiable()
+
+
+def _print_nothing_verifiable() -> None:
+    """Never a dead end: say what was scanned and what would unlock a claim."""
+    from devtime.db import connection
+
+    conn = connection.connect()
+    try:
+        scan = conn.execute(
+            "SELECT id, file_count, signal_count FROM scans WHERE status = 'completed' "
+            "ORDER BY started_at DESC LIMIT 1"
+        ).fetchone()
+        kinds = []
+        if scan:
+            kinds = conn.execute(
+                "SELECT kind, COUNT(*) c FROM signals WHERE scan_id = ? "
+                "GROUP BY kind ORDER BY c DESC LIMIT 6",
+                (scan["id"],),
+            ).fetchall()
     finally:
         conn.close()
 
+    console.print("[bold]No built-in claim applies to this repository yet.[/bold]")
+    console.print("")
+    if scan:
+        console.print(
+            f"DevTime scanned {scan['file_count']} files and found "
+            f"{scan['signal_count']} signals.",
+            markup=False,
+        )
+        if kinds:
+            summary = ", ".join(f"{k['kind']}={k['c']}" for k in kinds)
+            console.print(f"Evidence collected: {summary}", markup=False)
+        else:
+            console.print(
+                "No evidence was extracted, which usually means this repository's "
+                "language or framework is outside current scanner coverage.",
+                markup=False,
+            )
+    console.print("")
+    console.print("Built-in claims become verifiable when a repository has:")
+    console.print("  - HTTP routes and tests (route-test-coverage)")
+    console.print("  - admin, staff, or back-office routes (admin-authorization)")
+    console.print("  - JWT usage or a JWT dependency (jwt-authentication)")
+    console.print("  - billing webhooks or a payment provider (billing-webhook-signature)")
+    console.print("")
+    console.print(
+        "This is a coverage limit, not a verdict on your repository. "
+        "Scanner support is strongest on TypeScript, Next.js, Express, and "
+        "FastAPI-style code; see LIMITATIONS.md.",
+        markup=False,
+    )
+    console.print(
+        "If DevTime missed something your repository clearly has, that is worth "
+        "an issue: https://github.com/Shakargy/devtime/issues",
+        markup=False,
+    )
+
 
 def _print_verification(result) -> None:
     color = {
@@ -161,6 +264,7 @@ def _print_verification(result) -> None:
         "WEAK": "yellow",
         "CONTRADICTED": "red",
         "UNKNOWN": "cyan",
+        "NOT_APPLICABLE": "dim",
     }.get(result.status, "white")
     console.print(f"[bold]{result.claim_name}[/bold]")
     console.print(f"Claim: {result.statement}")