feat: stabilize 2.1 alpha MCP change-control and onboarding surfaces by orenlab · Pull Request #50 · orenlab/codeclone

orenlab · 2026-07-07T19:51:54Z

Summary

This PR prepares the CodeClone 2.1 alpha line by stabilizing the MCP change-control workflow, tightening controller budget/hygiene behavior, extending engineering memory and observability surfaces, and refreshing the public onboarding/docs structure.

The branch is currently ahead of main by 133 commits and is intended as an integration PR for the 2.1 alpha surface rather than a narrow single-file bug fix.

What changed

MCP change-control and controller workflow

Refines the controlled-change flow around intent, implementation context, blast radius, patch contracts, review receipts, and workspace hygiene.
Improves MCP payload handling, help/tool messages, session mixins, and workflow orchestration.
Tightens context-governance and token-budget behavior for agent-facing workflows.
Keeps edit_allowed as the authoritative permission signal for agent edits.

Workspace hygiene and verification safety

Optimizes hygiene snapshot reuse on the start path.
Reduces redundant git work in dirty-state digest handling while preserving digest identity.
Improves dirty workspace classification and controller hygiene behavior.
Adds regression coverage for hygiene snapshot reuse and digest byte-identity behavior.

Engineering memory and trajectory support

Extends memory models, schema migration, retrieval, trajectory storage/export, and lifecycle/status handling.
Improves memory governance and retrieval continuation behavior.
Adds support code for richer memory records, trajectory evidence, and projection metadata.

Setup and onboarding

Adds the new setup CLI surface and setup engine modules.
Introduces project discovery, capability detection, setup planning, rollup, apply, rendering, and wizard flows.
Adds reusable CLI UI helpers for help presentation, tours, mascot/progress/typewriter output.

Observability and analytics

Extends observability query/runtime/store support.
Adds analytics mapping support and improves export/integrity handling.
Updates audit event handling and analysis-completed payload behavior.

Documentation and release materials

Refreshes README, AGENTS, CLAUDE, CHANGELOG, and contribution-facing docs.
Replaces the previous docs/book and docs/guide structure with the new docs/concepts, docs/guides, docs/integrations, and docs/internal structure.
Adds report screenshots/assets for public presentation.

Type-safety and utility hardening

Narrows payload and mapping helpers.
Improves JSON, atomic write, file lock, SQLite, config, baseline, cache, parser, CFG, and benchmark support code.
Fixes several strict typing issues in action/benchmark/helper paths.

Why

CodeClone 2.1 introduces a stronger “Structural Change Controller” model for AI-assisted Python development:

agents declare intent before editing;
CodeClone maps allowed paths, do-not-touch paths, review context, blast radius, and budget;
edits are checked against the declared boundary;
finish produces verifiable receipts and hygiene evidence;
engineering memory and trajectories preserve reusable project knowledge.

This PR consolidates that alpha surface so the release line has one coherent controller, setup, memory, observability, and documentation baseline.

Review focus

Please focus review on:

MCP change-control semantics and edit_allowed behavior;
workspace hygiene and dirty snapshot compatibility;
token/context budget behavior for MCP responses;
engineering memory schema/migration compatibility;
setup CLI behavior and generated config safety;
docs restructuring and public onboarding clarity.

…eval on audit-write failure

…zard)

Rich escape codes broke substring checks on numeric and styled output. Add strip_ansi() in tests/_assertions.py and route CLI text assertions through assert_contains_all/assert_contains_none.

Rewrite docs IA contract for zensical.toml navigation and update plugin doc-path assertions to docs/integrations and docs/guides layouts.

Add branch-coverage tests across cache, memory, MCP, observability, setup, and CLI surfaces. Deduplicate mascot rich-step helpers to avoid new clone groups in pre-commit.

github-actions · 2026-07-07T19:52:38Z

CodeClone Review

✅ Passed · Health 91/100 (A) · Baseline ok · Cache miss · CodeClone 2.1.0a1

Review snapshot

Area	Signal	Review note
Clones	0 total, 0 new, 0 known	no new clone debt reported
Quality	CC max 20, CBO max 9, LCOM4 max 3, overloaded 43	structural metric snapshot
Dependencies	avg 7.0, p95 22, max 24, cycles 0	acyclic
Coverage Join	not joined	no coverage.xml facts in this report
Security Surfaces	281 surfaces, 6 categories, 133 production	report-only boundary inventory
API Surface	7659 symbols, 656 modules	0 breaking, 0 added
Dead code	0 high-confidence, 2 suppressed	clean

Review focus

Treat 133 production security surface(s) as review-first boundary code when touched.
Review 43 overloaded module candidate(s) when they intersect this PR.

_{Security Surfaces are report-only capability inventory, not vulnerability claims. Generated by CodeClone}

orenlab added 30 commits June 28, 2026 09:09

fix(mcp): polish budget response ergonomics

70dbb84

fix(mcp): polish budget response ergonomics

ea5b4d4

docs: align MCP and integration contracts

6baab39

docs: record release contract updates

8006ad9

fix(mcp): stabilize audit and install contracts

a4e2d28

perf(mcp): page findings before decoration

29638ed

perf(mcp): bound derived hotspot projection

5bd3a3b

perf(mcp): bound intent-scoped blast cache

f3bc021

fix(mcp): serialize sqlite intent registry opens

7fa2add

docs: update alpha install notes and cursor skill list

03cd309

test(mcp): stabilize sqlite intent writer ordering

af461bb

docs: align MCP governance contract notes

2194201

fix(vscode): preserve governance on uv fallback

3969ba3

fix(observability): harden sqlite store opening

7ffba41

feat(observability): expose detail drilldowns and CLI spans

3f28e23

perf(cache): reduce retained cache load memory

4379373

perf(mcp): avoid report roundtrip in analysis

46856c8

perf(cache): reduce cache load transient memory

b99b4e1

fix(report): make integrity digest cache-independent; guard MCP retri…

74f6bfc

…eval on audit-write failure

feat(cli): add read-only codeclone setup readiness command

9df0535

feat(config): add round-trip pyproject writer for setup merges

39ff442

feat(cli): add read-only setup plan with diff preview

0d576df

feat(cli): add bounded setup apply for pyproject and gitignore

5a21b13

feat(cli): add interactive setup wizard with guided apply flow

7b3e092

docs: add setup readiness guide and integration pointers

ef983fd

feat(cli): add human setup readiness surface (status, plan, apply, wi…

d8e497e

…zard)

test(setup): harden setup CLI tests and fix cursor guide IA budget

2c9d9e9

fix(types): validate metrics baseline boundaries

2180b35

fix(types): validate baseline persistence objects

776c008

fix(types): validate baseline trust payloads

3eabdcb

orenlab added 16 commits July 6, 2026 22:06

test(cli): centralize ANSI stripping for CLI assertions

e2dbb3f

Rich escape codes broke substring checks on numeric and styled output. Add strip_ansi() in tests/_assertions.py and route CLI text assertions through assert_contains_all/assert_contains_none.

test(docs): align docs IA and plugin contracts with Zensical

365c292

Rewrite docs IA contract for zensical.toml navigation and update plugin doc-path assertions to docs/integrations and docs/guides layouts.

test(coverage): raise package coverage to 99.21% gate

e744acd

Add branch-coverage tests across cache, memory, MCP, observability, setup, and CLI surfaces. Deduplicate mascot rich-step helpers to avoid new clone groups in pre-commit.

chore(docs): refresh CLAUDE.md and uv.lock

8ca1a38

fix(mcp): skip redundant dirty-summary git reads on start path

7f244b3

fix(mcp): derive finish hygiene from single snapshot

fdc2d8c

chore: untrack maintainer review kit (relocate to local .claude)

60eac9c

fix(mcp): repoint help doc_links off removed book/ and guide/ trees

1570fab

docs: align public and internal docs with code

483dc53

chore: drop check-added-large-files pre-commit hook

a9693e7

fix(mcp): correct observability limit clamp to [1, 100] in help text

1a0876f

docs: align observability limit and memory config option sets with code

c28e996

docs: refresh README with HTML sample screenshots and 2.1 alpha layout

64a74a9

fix(test): pass str to tomli.loads for Python 3.10 zensical config

7e83b14

fix(mcp): halve hygiene digest git-diff calls and dedupe start snapshot

48713f6

chore(deps): refresh transitive dependencies in uv.lock

afde615

orenlab self-assigned this Jul 7, 2026

github-advanced-security AI found potential problems Jul 7, 2026

View reviewed changes

orenlab merged commit 82f2485 into main Jul 7, 2026
28 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: stabilize 2.1 alpha MCP change-control and onboarding surfaces#50

feat: stabilize 2.1 alpha MCP change-control and onboarding surfaces#50
orenlab merged 133 commits into
mainfrom
fix/mcp-budget-fix

orenlab commented Jul 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

orenlab commented Jul 7, 2026

Summary

What changed

MCP change-control and controller workflow

Workspace hygiene and verification safety

Engineering memory and trajectory support

Setup and onboarding

Observability and analytics

Documentation and release materials

Type-safety and utility hardening

Why

Review focus

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026

CodeClone Review

Review snapshot

Review focus

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants