Add cognitive debt report (#202)

Adds a local-git cognitive debt report, optional GitHub review enrichment, and live watch threshold support.

Closes #170

Author: Siddhant-K-code

README.md

@@ -109,6 +109,7 @@ Full setup guide: [docs/setup.md](docs/setup.md)
 | [`agent-strace dashboard`](docs/commands.md#dashboard) | Multi-session overview |
 | [`agent-strace budget-report`](docs/commands.md#budget-report) | Weekly spend digest |
 | [`agent-strace team-report`](docs/commands.md#team-report) | Team spend by author, branch, or PR |
+| [`agent-strace cognitive-debt`](docs/commands.md#cognitive-debt) | Unreviewed agent-written code by session |
 | [`agent-strace lint <id>`](docs/commands.md#lint) | Flag bad behaviour patterns (loops, spirals, waste) |
 | [`agent-strace drift`](docs/commands.md#drift) | Detect behavioural drift over time |
 | [`agent-strace fingerprint`](docs/commands.md#fingerprint) | Baseline an agent's behavioural profile |

docs/commands.md

@@ -169,7 +169,7 @@ Live session monitor with kill-switch rules.
 | `--on-violation terminal\|file\|kill` | Action when a rule fires |
 | `--on-death CMD` | Command to run after kill (receives `{post_mortem_path}`) |
 | `--policy FILE` | Scope policy file to enforce (default: `.agent-scope.json`) |
-| `--rules FILE_OR_BUILTINS` | JSON/YAML rules file, or comma-separated built-ins such as `mcp-poisoning,loop:3/10,budget:$5,timeout:30m` |
+| `--rules FILE_OR_BUILTINS` | JSON/YAML rules file, or comma-separated built-ins such as `mcp-poisoning,loop:3/10,budget:$5,timeout:30m,cognitive-debt:0.8` |
 | `--stream-to URL` | Stream events to HTTP endpoint in real-time |
 | `--dry-run` | Evaluate rules without acting |
 
@@ -447,6 +447,26 @@ Team cost attribution across recorded sessions. By default it groups spend by gi
 | `--export text|csv|json` | Output format. `csv` is intended for spreadsheets and finance workflows |
 | `--outlier-threshold N` | Flag sessions whose cost is above `N` times the report average; default is `2.0` |
 
+### `cognitive-debt`
+```
+agent-strace cognitive-debt [--session ID] [--since DATE] [--until DATE]
+                            [--by author|branch] [--threshold N]
+                            [--format text|json] [--github-token TOKEN]
+```
+Measure unreviewed agent-written code from trace file-write events and local git history. The report works without a GitHub token; when git history is unavailable it still reports agent-written lines and treats review evidence as unknown.
+
+| Flag | Description |
+|---|---|
+| `--session ID` | Score one session by ID or prefix |
+| `--since DATE` | Start of reporting window. Accepts ISO dates or durations like `30d`; default is `30d` |
+| `--until DATE` | End of reporting window. Accepts ISO dates or durations like `7d`; default is now |
+| `--by author|branch` | Group summary rows by git author or branch |
+| `--threshold N` | Flag sessions above this debt score; default is `0.7` |
+| `--format text|json` | Output format |
+| `--github-token TOKEN` | Optional GitHub token for merged PR review/comment enrichment; local git works without it |
+
+`agent-strace watch --rules cognitive-debt:0.8` enables a live rule that alerts when a session has modified files that have not yet had human review.
+
 ### `standup`
 ```
 agent-strace standup [--session SESSION_ID]

src/agent_trace/__init__.py

@@ -1,3 +1,3 @@
 """agent-trace: strace for AI agents."""
 
-__version__ = "0.76.0"
+__version__ = "0.77.0"

src/agent_trace/cli.py

@@ -43,6 +43,7 @@
 from .standup import cmd_standup
 from .audit import cmd_audit, verify_chain
 from .cost import cmd_cost
+from .cognitive_debt import cmd_cognitive_debt
 from .curve import cmd_curve
 from .dashboard import cmd_dashboard
 from .shadow_ai import cmd_audit_tools
@@ -1056,6 +1057,23 @@ def build_parser() -> argparse.ArgumentParser:
                          default=2.0, metavar="SECONDS",
                          help="max seconds between flushes when streaming (default: 2.0)")
 
+    # cognitive-debt
+    p_debt = sub.add_parser("cognitive-debt", help="measure unreviewed agent-written code")
+    p_debt.add_argument("--session", metavar="ID", default="",
+                        help="session ID or prefix to score (default: recent sessions)")
+    p_debt.add_argument("--since", default="30d", metavar="DATE",
+                        help="start of reporting window, ISO date or duration (default: 30d)")
+    p_debt.add_argument("--until", default="", metavar="DATE",
+                        help="end of reporting window, ISO date or duration (default: now)")
+    p_debt.add_argument("--by", choices=["author", "branch"], default="author",
+                        help="group summary rows by author or branch (default: author)")
+    p_debt.add_argument("--threshold", type=float, default=0.7,
+                        help="flag sessions above this debt score (default: 0.7)")
+    p_debt.add_argument("--format", choices=["text", "json"], default="text",
+                        help="output format (default: text)")
+    p_debt.add_argument("--github-token", default="",
+                        help="GitHub token for optional PR review/comment enrichment")
+
     # mcp-scan
     p_mcp_scan = sub.add_parser("mcp-scan", help="scan runtime MCP tool poisoning indicators")
     p_mcp_scan.add_argument("--session", metavar="ID",
@@ -1670,6 +1688,7 @@ def main() -> None:
         "explain": cmd_explain,
         "timeline": cmd_timeline,
         "cost": cmd_cost,
+        "cognitive-debt": cmd_cognitive_debt,
         "diff": cmd_diff,
         "why": cmd_why,
         "audit": cmd_audit,