mempalace-code 1.10.3__tar.gz → 1.10.4__tar.gz

{mempalace_code-1.10.3 → mempalace_code-1.10.4}/.claude/skills/verify/INSTRUCTIONS.md

@@ -49,6 +49,16 @@ Run in parallel:
 | Format | `ruff format --check mempalace_code/ tests/ scripts/` | 30s |
 | Tests | `python -m pytest tests/ -x -q -m "not needs_network"` | 120s |
 | Typecheck | `python -m pyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"` | 120s |
+| Strict slice typecheck | `python -m pyright -p pyrightconfig.strict.json` | 60s |
+| Public safety | `python scripts/public_safety_scan.py --tracked --staged` | 30s |
+| Scorecard | `python scripts/quality_scorecard.py --check` | 30s |
+
+The scorecard check is stdlib-only (no install, no network) and validates the
+quality scorecard's shape, determinism, public-safety, and committed artifact
+freshness. The public-safety scan checks tracked and staged repository files for
+private local paths, secret-like tokens, and local-only raw artifacts. After a
+quality change lands, regenerate the committed artifacts with
+`python scripts/quality_scorecard.py --write` (see `docs/quality/README.md`).
 
 ### If storage changed — add these
 

{mempalace_code-1.10.3 → mempalace_code-1.10.4}/.github/workflows/ci.yml

@@ -59,8 +59,12 @@ jobs:
             pyproject.toml
             uv.lock
       - run: pip install ruff
-      - run: ruff check mempalace_code/ tests/
-      - run: ruff format --check mempalace_code/ tests/
+      - run: ruff check mempalace_code/ tests/ scripts/
+      - run: ruff format --check mempalace_code/ tests/ scripts/
+      - name: Public-safety scan (tracked + staged)
+        run: python scripts/public_safety_scan.py --tracked --staged
+      - name: Quality scorecard (shape + determinism + public-safety)
+        run: python scripts/quality_scorecard.py --check
 
   typecheck:
     runs-on: ubuntu-latest
@@ -76,6 +80,8 @@ jobs:
       - run: pip install -e ".[dev,chroma,spellcheck,treesitter]"
       - name: Pyright typecheck
         run: python -m pyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"
+      - name: Pyright strict slice
+        run: python -m pyright -p pyrightconfig.strict.json
 
   model-tests:
     runs-on: ubuntu-latest

{mempalace_code-1.10.3 → mempalace_code-1.10.4}/.gitignore

@@ -23,6 +23,7 @@ palace/
 .venv/
 venv/
 .env
+.verify-state
 
 # IDE
 .idea/

{mempalace_code-1.10.3 → mempalace_code-1.10.4}/CHANGELOG.md

@@ -4,6 +4,40 @@
 
 No changes yet.
 
+## v1.10.4 — 2026-06-06
+
+Patch release for public quality/demo gates after v1.10.3.
+
+### Added
+
+- Deterministic public quality scorecard artifacts under `docs/quality/`, with
+  Markdown and JSON output generated by `scripts/quality_scorecard.py`.
+- Repo-wide public-safety scanner for tracked and staged files:
+  `python scripts/public_safety_scan.py --tracked --staged`.
+- Public-safe multi-agent workflow review protocol for future quality work.
+- Strict Pyright slice config for stable low-level modules, gated in CI and
+  `/verify`.
+- Detailed Autopilot demo backlog items for dependency audit CI, release status
+  checks, committed-tree public-safety scanning, scorecard metric expansion,
+  architecture guards, CLI/MCP contracts, docs drift guards, and workflow
+  effectiveness checks.
+
+### Changed
+
+- `/verify` and CI now run public-safety, scorecard freshness, and strict-slice
+  typecheck gates in addition to lint, format, tests, and basic Pyright.
+- Ruff global ignores were reduced from 33 to 3; older package/test debt remains
+  scoped to per-file ignores so new scripts inherit stricter rules.
+- Suppression scanning now uses Python tokenization so strings/docstrings that
+  mention `# type: ignore` do not count as live suppressions.
+- `scripts/quality_scorecard.py --check` now fails when committed scorecard
+  artifacts are stale.
+
+### Removed
+
+- `.verify-state` is no longer tracked and is ignored as a local-only verification
+  baseline.
+
 ## v1.10.3 — 2026-06-05
 
 Follow-up patch for the v1.10.2 release: fixes the hosted test failure, refreshes

{mempalace_code-1.10.3 → mempalace_code-1.10.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mempalace-code
-Version: 1.10.3
+Version: 1.10.4
 Summary: Developer memory tool — mine codebases and conversations into a LanceDB-backed searchable palace. No API key required.
 Project-URL: Homepage, https://github.com/rergards/mempalace-code
 Project-URL: Repository, https://github.com/rergards/mempalace-code

mempalace_code-1.10.4/docs/BACKLOG.yaml

@@ -0,0 +1,271 @@
+# ============================================================
+# BACKLOG.yaml — Machine-readable project backlog
+# Format: sections + items (DH2-style)
+# Parse:  backlog list --status open --file docs/BACKLOG.yaml
+# ============================================================
+#
+# project: mempalace-code
+
+sections:
+  - id: immediate
+    order: 1
+    title: "IMMEDIATE — Foundation & Project Setup"
+    description: "Fork identity, CI, docs. Must be done before any feature work."
+  - id: pre_release
+    order: 2
+    title: "PRE-RELEASE — v1.0 Blockers (Autopilot Pass)"
+    description: "P0 and P1 items that must land before a public v1.0. All items here are autopilot-ready — owner decisions already made. Batch in one large autopilot pass. Items needing owner judgment live in other sections."
+  - id: coding_first
+    order: 3
+    title: "CODING-FIRST — Smart Code Mining"
+    description: "Language-aware chunking, structural boundaries, code-optimized search. The core differentiator."
+  - id: storage_reliability
+    order: 4
+    title: "STORAGE & RELIABILITY"
+    description: "LanceDB hardening, migration tooling, backup/restore."
+  - id: mcp_developer_tools
+    order: 5
+    title: "MCP — Developer-Focused Tools"
+    description: "New and improved MCP tools for coding workflows."
+  - id: cleanup
+    order: 6
+    title: "CLEANUP — De-emphasize Dialog-First Features"
+    description: "Refactor or gate conversation-centric modules. Keep functional but not default."
+  - id: quality
+    order: 7
+    title: "QUALITY — Tests, Benchmarks, CI"
+    description: "Test coverage, code-mining benchmarks, CI hardening."
+  - id: autopilot_demo
+    order: 8
+    title: "AUTOPILOT DEMO — Code Quality Showcase"
+    description: "Measurable, public-safe improvements that demonstrate Autopilot can raise code quality without changing product scope."
+  - id: future
+    order: 9
+    title: "FUTURE — Post-v1 Ideas"
+    description: "Ideas for after the first public release."
+# ============================================================
+# OPEN ITEMS
+# ============================================================
+items:
+  - key: STORE-HF-CACHED-SEARCH-SUBPROCESS-GUARD
+    section: quality
+    status: open
+    priority: P2
+    summary: Add subprocess-level guard that cached model search/fetch never emits HuggingFace token warnings or performs network metadata calls after setup.
+    acceptance:
+      - Run a real CLI subprocess with a preseeded HuggingFace cache and network/socket access blocked or mocked.
+      - Assert `mempalace-code search` exits successfully without `HF_TOKEN`, `unauthenticated`, `huggingface.co`, or retry noise on stdout/stderr.
+      - Assert repeated `mempalace-code fetch-model` on a cached model uses local-only resolution and does not perform Hub metadata requests.
+      - Keep the existing network-marked download tests separate from this no-network regression guard.
+  - key: DEPENDENCY-SECURITY-UPGRADE-GATE
+    section: quality
+    status: open
+    priority: P1
+    summary: Add a repeatable audited dependency-upgrade gate before raising package ceilings or refreshing the lock.
+    acceptance:
+      - Enumerate current and target versions for direct runtime, dev, and optional dependencies from package metadata before changing bounds.
+      - Query OSV or an equivalent advisory source for both current and target direct dependency versions; block target ranges that are compromised or currently affected.
+      - Run pip-audit or an equivalent resolver-level audit on fresh environments for the default install and every optional extra whose bounds change.
+      - Keep deprecated optional backends capped away from affected ranges; do not raise ChromaDB to 1.x while GHSA-f4j7-r4q5-qw2c affects the available 1.x line.
+      - Update uv.lock only after the audited resolver passes, then run hosted-CI-equivalent tests in a clean pip environment so stale local locks cannot hide dependency drift.
+  - key: DEPENDENCY-SCHEDULED-AUDIT-CI
+    section: quality
+    status: open
+    priority: P1
+    summary: Add a scheduled dependency audit workflow that checks current resolved packages without changing bounds.
+    acceptance:
+      - Add a GitHub Actions workflow on `schedule` and `workflow_dispatch` that installs the default package and every optional extra in fresh environments.
+      - Run `pip-audit` or an equivalent resolver-level audit for default, `[dev]`, `[treesitter]`, `[spellcheck]`, and `[chroma]` installs.
+      - Query OSV or an equivalent advisory source for direct dependency versions including `lancedb`, `sentence-transformers`, `pyyaml`, `packaging`, `chromadb`, and tree-sitter packages.
+      - Treat known accepted risks as explicit allowlist entries with advisory ID, package, affected range, reason, and expiry date.
+      - Publish only package names, versions, advisory IDs, and remediation notes; never include private resolver caches, machine paths, or credentials.
+      - Open or update a backlog item when an advisory appears, a package becomes yanked, or a previously safe target range becomes affected.
+  - key: RELEASE-PUBLICATION-STATUS-GATE
+    section: quality
+    status: open
+    priority: P1
+    summary: Add a release-status verification gate that checks every public publication surface before calling a release shipped.
+    acceptance:
+      - Add a script or documented command that takes an expected version and checks tag existence, tag workflow status, GitHub Release presence, PyPI version visibility, and clean install smoke from PyPI.
+      - Verify `publish/main`, the version tag, GitHub Actions tag publish run, GitHub Releases, and PyPI JSON/API state as separate facts with separate pass/fail rows.
+      - Fail if branch tests pass but tag publish, release creation, or PyPI visibility is missing or red.
+      - Keep output public-safe: no private remote URLs, tokens, local paths, hostnames, or non-public incident notes.
+      - Wire the command into the `/release` skill/runbook and require it before release completion summaries.
+      - Add tests for parsing mocked GitHub/PyPI responses and for partial-success states such as "tests green, PyPI missing".
+  - key: AUTOPILOT-DEMO-QUALITY-SCORECARD
+    section: autopilot_demo
+    status: done
+    priority: P1
+    summary: Add a deterministic public quality scorecard that makes Autopilot cleanup progress visible across releases.
+    acceptance:
+      - Add a script or command that emits markdown and JSON metrics for code size, largest modules, Ruff ignore counts, Pyright mode, unreasoned suppressions, test count, and available smoke suites.
+      - Generate any raw baseline evidence under local ignored docs/audits/, then commit only a sanitized public summary with public repo data and relative paths.
+      - Document how each Autopilot demo task updates the scorecard with before/after metrics.
+      - CI or `/verify` runs the scorecard command and fails on malformed output.
+    resolution: "2026-06-05: Deterministic public scorecard: scripts/quality_scorecard.py emits Markdown+JSON; --check gates shape/determinism/public-safety in CI lint job and /verify; baseline committed to docs/quality/; update workflow in docs/quality/README.md"
+    done_summary: "Deterministic public scorecard: scripts/quality_scorecard.py emits Markdown+JSON; --check gates shape/determinism/public-safety in CI lint job and /verify; baseline committed to docs/quality/; update workflow in docs/quality/README.md"
+  - key: AUTOPILOT-DEMO-PUBLIC-SAFETY-GATE
+    section: autopilot_demo
+    status: done
+    priority: P1
+    summary: Add a repo-wide public-safety gate for tracked and staged files.
+    acceptance:
+      - Add a stdlib scanner that checks tracked worktree files and staged index blobs.
+      - Block secret-like tokens, real local machine paths, and local-only artifact paths without printing the matched secret text.
+      - Wire the scanner into CI and `/verify`.
+      - Remove or ignore any local-only artifact that is already tracked.
+    resolution: "2026-06-06: Added scripts/public_safety_scan.py --tracked --staged, CI and /verify wiring, focused tests, and removed tracked .verify-state while adding it to .gitignore."
+    done_summary: "Repo-wide public-safety scan now gates tracked/staged files and redacts matched content; .verify-state is local-only."
+  - key: AUTOPILOT-DEMO-RUFF-RATCHET
+    section: autopilot_demo
+    status: done
+    priority: P1
+    summary: Reduce transitional Ruff ignores in a measurable ratchet without broad style-only churn.
+    acceptance:
+      - Record baseline counts for global ignores, per-file ignores, and inline suppressions before edits.
+      - Remove at least one global ignore family or reduce per-file ignore entries by at least 25% for a focused module group.
+      - Replace any necessary inline suppressions with reasoned, narrow suppressions; no new blanket `noqa` entries.
+      - "`ruff check`, `ruff format --check`, Pyright, and the relevant focused tests pass; update the quality scorecard."
+    resolution: "2026-06-06: Reduced global Ruff ignores from 33 to 3 by keeping existing package/test debt scoped to per-file ignores and making new scripts inherit the stricter rule set."
+    done_summary: "Ruff global ignore ratchet: broad historical ignores are now scoped away from scripts; no new inline suppressions."
+  - key: AUTOPILOT-DEMO-PYRIGHT-STRICT-SLICE
+    section: autopilot_demo
+    status: done
+    priority: P1
+    summary: Establish a strict Pyright slice for stable low-level modules and expand it gradually.
+    acceptance:
+      - Add a strict typecheck config or command for a small stable slice such as config, reader, MCP tool profiles, and mining scanner.
+      - Replace ad hoc `Any` and broad dictionaries in that slice with typed contracts where the code owns the boundary.
+      - Keep compatibility shims and third-party stub gaps outside the first strict slice unless they can be fixed narrowly.
+      - CI or `/verify` runs both the existing basic Pyright check and the strict-slice check; update the quality scorecard.
+    resolution: "2026-06-06: Added pyrightconfig.strict.json for version.py, mcp_tool_profiles.py, and disk_budget.py; annotated disk_budget.py enough to pass strict; wired strict slice into CI and /verify."
+    done_summary: "Initial strict Pyright slice gates three stable low-level modules in CI and /verify."
+  - key: AUTOPILOT-DEMO-PYRIGHT-STRICT-SLICE-EXPANSION
+    section: autopilot_demo
+    status: open
+    priority: P1
+    summary: Expand the strict Pyright slice to config, reader, and mining scanner after adding typed boundaries.
+    acceptance:
+      - Add `mempalace_code/config.py`, `mempalace_code/reader.py`, and `mempalace_code/mining/scanner.py` to `pyrightconfig.strict.json`.
+      - Introduce typed config payload aliases, reader result types, gitignore rule types, and scan filter generics instead of broad dict/list shapes.
+      - Add focused tests or type-level assertions for config fallback shape, reader result variants, and scanner rule parsing where the typed contracts expose previously implicit behavior.
+      - Keep the strict-slice command in `/verify` and CI; do not weaken strict diagnostics to make the slice pass.
+      - Keep the existing basic Pyright gate green throughout.
+      - Update the quality scorecard and report the strict-slice expansion publicly.
+  - key: AUTOPILOT-DEMO-PUBLIC-SAFETY-COMMITTED-MODE
+    section: autopilot_demo
+    status: open
+    priority: P1
+    summary: Add an explicit committed-tree public-safety scan mode for publishable release verification.
+    acceptance:
+      - Extend `scripts/public_safety_scan.py` with a mode that scans exactly the committed tree at `HEAD`, independent of staged or unstaged worktree state.
+      - Keep existing `--tracked --staged` behavior for pre-commit use, but document when to use committed-tree mode before release or after merge.
+      - Add tests proving deleted local-only files do not trigger tracked worktree failures, while committed local-only paths still fail.
+      - Wire committed-tree mode into release verification docs or `/release`, not into every edit-time `/verify` run unless it remains fast.
+      - Ensure all failure output remains redacted to rule id and file position only.
+  - key: AUTOPILOT-DEMO-WORKFLOW-REVIEW-PROTOCOL
+    section: autopilot_demo
+    status: done
+    priority: P1
+    summary: Document the public-safe adversarial Claude workflow protocol for repo quality work.
+    acceptance:
+      - Define review lenses, skeptical refutation, synthesis, implementation, and verification steps.
+      - Separate publishable summaries from local-only raw workflow artifacts.
+      - Link the protocol from quality docs.
+      - Include the canonical quality verification commands.
+    resolution: "2026-06-06: Added docs/quality/workflow-review-protocol.md and linked it from docs/quality/README.md."
+    done_summary: "Public-safe multi-agent workflow review protocol is documented for future quality improvements."
+  - key: AUTOPILOT-DEMO-ARCHITECTURE-GUARD
+    section: autopilot_demo
+    status: open
+    priority: P1
+    summary: Add an import-boundary guard so core modules cannot accidentally depend on CLI, MCP, or optional legacy backend layers.
+    acceptance:
+      - Add a dependency graph check based on Python imports, using a standard library parser or a small dev-only tool.
+      - Enforce at minimum that storage/config/mining core does not import CLI, MCP dispatch, or Chroma-only modules.
+      - Define explicit layers such as `core`, `storage`, `mining`, `cli`, `mcp`, `legacy_optional`, and `scripts`; keep the layer map in a public config or script constant.
+      - Detect direct violations, transitive cycles, and imports hidden behind `TYPE_CHECKING` separately so intentional type-only imports can be reviewed rather than silently blocked.
+      - Report cycles and boundary violations with file-level paths that are easy for Autopilot to fix.
+      - Add positive and negative fixture tests for the guard itself and wire the command into `/verify` and CI if it stays fast; update the quality scorecard.
+  - key: AUTOPILOT-DEMO-CLI-GOLDEN-SCENARIOS
+    section: autopilot_demo
+    status: open
+    priority: P1
+    summary: Build subprocess-level golden CLI scenarios that prove real user workflows, not only unit internals.
+    acceptance:
+      - Run `mempalace-code init`, `mine`, `status`, `search`, `read`, `export`, `import`, `backup`, and `restore` in a disposable temp home/palace.
+      - Cover at least one important guard/failure path such as missing palace, invalid read range, or unsafe mirror preflight.
+      - Force offline/version-check-disabled environment variables so the suite is deterministic and network-free.
+      - Assert stdout/stderr contracts for each scenario: stable success text, stable error text, no HuggingFace token warning noise, and no absolute local paths in publishable output.
+      - Use a generated fixture project small enough for CI but representative enough to include Python source, Markdown, config, and one non-Python supported file.
+      - Add the scenario suite to the quality scorecard as a real workflow suite distinct from unit-level CLI tests.
+      - Remove all smoke artifacts or report them explicitly; update release/verify docs and the quality scorecard.
+  - key: AUTOPILOT-DEMO-MCP-STDIO-CONTRACTS
+    section: autopilot_demo
+    status: open
+    priority: P1
+    summary: Add real MCP stdio contract tests for profiles, tool discovery, and representative tool calls.
+    acceptance:
+      - Start `python -m mempalace_code.mcp_server` as a subprocess and exercise JSON-RPC initialize, tools/list, and tools/call through stdin/stdout.
+      - Verify `minimal`, `code`, `kg`, `notes`, and `full` profiles expose only the expected tools.
+      - Include representative success and error responses for read-only, write, graph/KG, and disabled-tool paths.
+      - Assert response envelopes follow MCP JSON-RPC shape, include stable error codes/messages where applicable, and do not leak tracebacks for expected user errors.
+      - Add timeout and subprocess cleanup guards so failed tests do not leave orphan MCP server processes.
+      - Record profile/tool counts in the scorecard so future tool-surface changes are visible.
+      - Keep direct handler tests as fast unit coverage but label them separately from real MCP stdio coverage; update the quality scorecard.
+  - key: AUTOPILOT-DEMO-SECURITY-BOUNDARY-TESTS
+    section: autopilot_demo
+    status: open
+    priority: P2
+    summary: Harden external-input boundaries with focused abuse-case tests for paths, archives, JSONL, YAML, and command preflight parsing.
+    acceptance:
+      - Add tests for backup/restore tar traversal, import/export malformed JSONL, read path ambiguity, YAML project config validation, and mirror preflight command parsing.
+      - Prefer standard-library table-driven tests; add a fuzz/property-test dependency only if it clearly improves signal and stays dev-only.
+      - Every rejected input returns a stable error code/message and does not create partial palace state.
+      - Document any remaining accepted risk in a public-safe plan or backlog follow-up; update the quality scorecard.
+  - key: AUTOPILOT-DEMO-PERF-BUDGETS
+    section: autopilot_demo
+    status: open
+    priority: P2
+    summary: Add deterministic performance budgets for mining, search, read, and maintenance on synthetic fixtures.
+    acceptance:
+      - Build generated fixtures that do not require network access or external repositories.
+      - Measure mine time, incremental no-op time, search latency, read latency, and cleanup/optimize smoke duration.
+      - Store conservative budgets and machine-independent comparison rules so CI failures indicate meaningful regressions, not normal hardware variance.
+      - Separate hard CI budgets from informational local benchmark output; hard budgets should use ratios or generous floors that survive normal hosted-runner variance.
+      - Include a "budget changed because" field in the public artifact whenever thresholds move.
+      - Publish before/after numbers in the quality scorecard and release notes when a demo task improves a budget.
+  - key: AUTOPILOT-DEMO-DOCS-DRIFT-GUARD
+    section: autopilot_demo
+    status: open
+    priority: P2
+    summary: Add an automated docs drift guard for CLI commands, MCP tools, optional extras, and release gates.
+    acceptance:
+      - Generate or validate the CLI command inventory from argparse/code instead of manually trusting README snippets.
+      - Validate MCP tool tables in README and AGENT_INSTALL against the authoritative tool registry and profiles.
+      - Validate optional extras and release/dependency gates in public docs against pyproject.toml and workflow files.
+      - Validate documented verification commands in `CLAUDE.md`, `.claude/skills/verify/INSTRUCTIONS.md`, `.claude/skills/release/INSTRUCTIONS.md`, and `docs/quality/README.md` against canonical command lists.
+      - Add fixture tests for stale docs so the guard proves it fails before it is wired into CI.
+      - Fail with actionable file/section messages and update the quality scorecard.
+  - key: AUTOPILOT-DEMO-SCORECARD-METRIC-EXPANSION
+    section: autopilot_demo
+    status: open
+    priority: P2
+    summary: Expand the quality scorecard with metrics for gates that now matter to the public demo.
+    acceptance:
+      - Add strict-slice file count and strict-slice paths from `pyrightconfig.strict.json`.
+      - Add public-safety scan coverage fields for tracked, staged, and committed-tree modes once committed-tree mode exists.
+      - Add architecture guard status, CLI golden scenario count, MCP stdio contract count, docs drift guard status, and dependency audit status as optional metrics that appear when the corresponding scripts exist.
+      - Keep scorecard output deterministic, stdlib-only, timestamp-free, and public-safe.
+      - Update `docs/quality/README.md` to define every new metric and how Autopilot tasks should cite before/after deltas.
+  - key: AUTOPILOT-DEMO-WORKFLOW-EFFECTIVENESS-GUARD
+    section: autopilot_demo
+    status: open
+    priority: P2
+    summary: Add a lightweight guard that workflow review summaries are actionable rather than ceremonial.
+    acceptance:
+      - Define a public-safe workflow summary schema with fields for review lens, finding, evidence file/path, action taken, verification, and deferral reason.
+      - Add a checker for sanitized workflow summary files or PR-body snippets that rejects findings without concrete evidence or explicit action/deferral.
+      - Keep raw multi-agent transcripts local-only under ignored paths; commit only the synthesized public summary when needed.
+      - Document that passive review output is not enough: each surviving finding must either change code/tests/docs or become a backlog item with acceptance criteria.
+      - Add tests for accepted summaries, missing evidence, missing action, and accidental private path/token content.

mempalace_code-1.10.4/docs/quality/README.md

@@ -0,0 +1,90 @@
+# Quality Scorecard
+
+A deterministic, public-safe snapshot of code-quality signals for the
+`AUTOPILOT DEMO` backlog section. It exists so cleanup work has measurable
+before/after evidence instead of becoming invisible churn.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| [`scorecard.md`](scorecard.md) | Human-readable baseline (committed). |
+| [`scorecard.json`](scorecard.json) | Machine-readable baseline (committed). |
+| [`workflow-review-protocol.md`](workflow-review-protocol.md) | Public-safe multi-agent review protocol for quality work. |
+
+Both are generated by [`scripts/quality_scorecard.py`](../../scripts/quality_scorecard.py).
+
+## Generate
+
+```bash
+# Print to stdout
+python scripts/quality_scorecard.py                 # Markdown
+python scripts/quality_scorecard.py --format json   # JSON
+python scripts/quality_scorecard.py --format both   # both
+
+# Regenerate the committed artifacts under docs/quality/
+python scripts/quality_scorecard.py --write
+
+# Validate shape, determinism, public-safety, and committed freshness (CI / verify gate)
+python scripts/quality_scorecard.py --check
+
+# Scan tracked/staged repository files for publish-safety leaks
+python scripts/public_safety_scan.py --tracked --staged
+```
+
+The script uses **only the Python standard library** (no project import, no
+network), so it runs anywhere Python 3.11+ is available.
+
+## What it measures
+
+All metrics are repo-local and public-safe by construction — no timestamps, no
+absolute paths, no machine identifiers:
+
+- **Code size** — package/test file counts and line totals.
+- **Largest modules** — top modules by line count (relative paths only).
+- **Ruff ignores** — global ignore count, selected rule families, and per-file
+  ignore patterns/entries from `pyproject.toml`.
+- **Pyright** — type-checking mode and strict status.
+- **Suppressions** — total and *unreasoned* type/pyright ignores and blanket
+  `noqa`, using the same policy as
+  [`tests/test_type_suppressions.py`](../../tests/test_type_suppressions.py)
+  (`# type: ignore[code]  # reason: ...`). Fixture dirs are excluded.
+- **Tests** — test file and test-function counts.
+- **Suites** — which CLI/MCP/smoke surfaces exist.
+- **Verification commands** — the canonical `/verify` pre-commit checks (kept
+  verbatim-identical to `.claude/skills/verify/INSTRUCTIONS.md`, enforced by a
+  drift test).
+
+## Determinism & public-safety
+
+`--check` builds the scorecard twice and fails if the JSON differs, validates
+the output shape (types, required keys, sort order, invariants), checks that the
+committed Markdown/JSON artifacts are fresh, and runs a rendered-output
+public-safety scan for private paths and secret-like tokens. CI (`lint` job) and
+`/verify` also run `scripts/public_safety_scan.py --tracked --staged`, which
+checks the repository files themselves for real local paths, secret-like tokens,
+and local-only artifact paths.
+
+## How Autopilot demo tasks update this scorecard
+
+Every task in the `AUTOPILOT DEMO` backlog section should record a before/after
+delta here:
+
+1. **Before** the change, capture the baseline: `python scripts/quality_scorecard.py --format json`.
+   Keep raw/private working notes only under the git-ignored `docs/audits/`;
+   never commit them.
+2. Make the focused change (e.g. remove a Ruff ignore family, add a strict
+   Pyright slice, add a real CLI/MCP suite).
+3. **After** the change, regenerate the committed artifacts:
+   `python scripts/quality_scorecard.py --write`.
+4. In the PR/commit description and release notes, cite the moved metric using
+   public repo data only — e.g. "unreasoned suppressions N → M",
+   "Ruff global ignores N → M", "Pyright strict slice added". The committed
+   `scorecard.json` diff is the evidence.
+
+Run `python scripts/quality_scorecard.py --check` before committing so the
+regenerated artifacts stay well-formed and public-safe.
+
+For adversarial multi-agent review of a quality change, use
+[`workflow-review-protocol.md`](workflow-review-protocol.md) and publish only
+the sanitized synthesis and verification evidence.

mempalace_code-1.10.4/docs/quality/scorecard.json

@@ -0,0 +1,189 @@
+{
+  "code_size": {
+    "package_code_lines": 18978,
+    "package_files": 73,
+    "package_total_lines": 23442,
+    "test_files": 54,
+    "test_total_lines": 39198
+  },
+  "largest_modules": [
+    {
+      "lines": 1609,
+      "path": "mempalace_code/storage.py"
+    },
+    {
+      "lines": 1466,
+      "path": "mempalace_code/mining/chunkers.py"
+    },
+    {
+      "lines": 1074,
+      "path": "mempalace_code/dialect.py"
+    },
+    {
+      "lines": 1032,
+      "path": "mempalace_code/watcher.py"
+    },
+    {
+      "lines": 904,
+      "path": "mempalace_code/mining/symbols.py"
+    },
+    {
+      "lines": 858,
+      "path": "mempalace_code/entity_detector.py"
+    },
+    {
+      "lines": 753,
+      "path": "mempalace_code/knowledge_graph.py"
+    },
+    {
+      "lines": 735,
+      "path": "mempalace_code/cli.py"
+    },
+    {
+      "lines": 720,
+      "path": "mempalace_code/mining/orchestrator.py"
+    },
+    {
+      "lines": 660,
+      "path": "mempalace_code/entity_registry.py"
+    }
+  ],
+  "pyright": {
+    "include": [
+      "mempalace_code",
+      "tests"
+    ],
+    "python_version": "3.11",
+    "strict": false,
+    "type_checking_mode": "basic"
+  },
+  "ruff": {
+    "global_ignore_rules": [
+      "B007",
+      "E501",
+      "SIM105"
+    ],
+    "global_ignores": 3,
+    "per_file_ignores": {
+      "by_pattern": [
+        {
+          "count": 24,
+          "pattern": "mempalace_code/**/*.py"
+        },
+        {
+          "count": 14,
+          "pattern": "tests/**/*.py"
+        }
+      ],
+      "patterns": 2,
+      "total_entries": 38
+    },
+    "selected_rule_families": 12
+  },
+  "schema_version": 1,
+  "scope": {
+    "package_dir": "mempalace_code",
+    "tests_dir": "tests"
+  },
+  "suites": [
+    {
+      "description": "CLI command tests",
+      "name": "cli",
+      "path": "tests/test_cli.py",
+      "present": true
+    },
+    {
+      "description": "End-to-end CLI workflow tests",
+      "name": "cli_e2e",
+      "path": "tests/test_e2e.py",
+      "present": true
+    },
+    {
+      "description": "CLI command module tests",
+      "name": "cli_command_modules",
+      "path": "tests/test_cli_command_modules.py",
+      "present": true
+    },
+    {
+      "description": "MCP server handler tests",
+      "name": "mcp_server",
+      "path": "tests/test_mcp_server.py",
+      "present": true
+    },
+    {
+      "description": "MCP stdio transport tests",
+      "name": "mcp_stdio",
+      "path": "tests/test_stdio.py",
+      "present": true
+    },
+    {
+      "description": "MCP tool profile tests",
+      "name": "mcp_tool_profiles",
+      "path": "tests/test_mcp_tool_profiles.py",
+      "present": true
+    },
+    {
+      "description": "Backup/restore CLI tests",
+      "name": "backup_cli",
+      "path": "tests/test_backup_cli.py",
+      "present": true
+    },
+    {
+      "description": "Offline / no-network guard tests",
+      "name": "offline",
+      "path": "tests/test_offline.py",
+      "present": true
+    },
+    {
+      "description": "migrate-storage disposable smoke",
+      "name": "migrate_storage_smoke",
+      "path": "scripts/migrate_storage_smoke.py",
+      "present": true
+    }
+  ],
+  "suppressions": {
+    "noqa_blanket": 0,
+    "noqa_total": 41,
+    "scope": [
+      "mempalace_code",
+      "tests"
+    ],
+    "type_pyright_total": 110,
+    "type_pyright_unreasoned": 0,
+    "unreasoned_total": 0
+  },
+  "tests": {
+    "test_files": 54,
+    "test_functions": 2266
+  },
+  "verification_commands": [
+    {
+      "command": "ruff check mempalace_code/ tests/ scripts/",
+      "name": "lint"
+    },
+    {
+      "command": "ruff format --check mempalace_code/ tests/ scripts/",
+      "name": "format"
+    },
+    {
+      "command": "python -m pytest tests/ -x -q -m \"not needs_network\"",
+      "name": "tests"
+    },
+    {
+      "command": "python -m pyright --pythonpath \"$(python -c 'import sys; print(sys.executable)')\"",
+      "name": "typecheck"
+    },
+    {
+      "command": "python -m pyright -p pyrightconfig.strict.json",
+      "name": "typecheck_strict_slice"
+    },
+    {
+      "command": "python scripts/public_safety_scan.py --tracked --staged",
+      "name": "public_safety"
+    },
+    {
+      "command": "python scripts/quality_scorecard.py --check",
+      "name": "scorecard"
+    }
+  ]
+}