From ca29259a3af28db31da266f6f6ca6e91c4ea661e Mon Sep 17 00:00:00 2001 From: Jeffrey Phillips Freeman Date: Wed, 18 Feb 2026 12:57:22 -0500 Subject: [PATCH] Docs: Updated implementation plan --- implementation_plan.md | 541 ++++++++++++++++++++++++----------------- 1 file changed, 317 insertions(+), 224 deletions(-) diff --git a/implementation_plan.md b/implementation_plan.md index 79446cbf..3cc36e93 100644 --- a/implementation_plan.md +++ b/implementation_plan.md @@ -31,15 +31,15 @@ ## Guiding Principles -- Keep `docs/specification.md` as the single source of truth; this plan is sequencing only and stays intentionally minimal. -- Local mode is the only execution target through M6; server mode is stub-only (interfaces raise `NotImplementedError`) with no server implementation in this repo. -- Plan lifecycle: Action (non-processing) → Strategize → Execute → Apply; decision tree persisted, Execute may revert to Strategize, Apply terminal states are `applied`/`constrained`/`errored`/`cancelled` with constrained allowed to revert. -- Identity rules: actions/projects/tools/skills/actors/automation profiles use namespaced names; plans/decisions/resources/validation attachments use ULIDs; top-level plans may carry names, subplans are ULID-only. -- Registry-first: ResourceType/Resource/Tool/Validation/Skill/Actor/Provider registries are authoritative. -- Resource registry: physical/virtual resources form a DAG; resource types define parent/child constraints, auto-discovery rules, sandbox strategy, handler metadata, and equivalence rules for virtual resources. -- Tool-only mutation path: tool lifecycle (discover/activate/execute/deactivate) uses resource bindings and ChangeSet capture; validations are read-only tools (required/informational) attached to resources with optional project/plan scope. +- Keep `docs/specification.md` as the single source of truth; this plan stays intentionally minimal and sequencing-only. +- Local mode is the only execution target through M6; server mode is stub-only (ACP/LSP client interfaces raise `NotImplementedError`) with no server implementation here. +- Plan lifecycle: Action → Strategize → Execute → Apply; decision tree persisted; Execute may revert to Strategize; Apply terminal states are `applied`/`constrained`/`errored`/`cancelled` with constrained allowed to revert. +- Identity rules: actions/projects/tools/skills/actors/automation profiles use namespaced names; plans/decisions/resources/validation attachments use ULIDs; top-level plans may be named but child plans are ULID-only. +- Registry-first: Resource/ResourceType/Tool/Validation/Skill/Actor/Provider registries are authoritative; validation attachments are resource-scoped with optional project/plan narrowing. +- Resource model: physical/virtual resources form a DAG; resource types define parent/child constraints, auto-discovery, sandbox strategy, handler metadata, and equivalence for virtual resources. +- Tool execution: tool lifecycle (discover/activate/execute/deactivate) uses resource bindings and ChangeSet capture; validations are read-only tools with required/informational mode. - YAML configs (actions/actors/tools/skills/validations/resource types/automation profiles) follow spec schemas with env-var interpolation; validate at load time. -- ACMS v1 (UKO + CRP + Context Assembly Pipeline) is the M6 target; details remain in the spec. +- ACMS v1 (UKO + CRP + Context Assembly Pipeline) is the M6 target; all detail stays in the spec. ### Core Architectural Requirements @@ -49,7 +49,7 @@ **Autonomy with Control**: Decision-tree recording, invariants + reconciliation, automation profiles, and correction flows per spec. -**Interop**: MCP + Agent Skills Standard tool sources supported via tool/skill abstraction (local mode). +**Interop**: MCP + Agent Skills tool sources in local mode; ACP/LSP interface stubs present for future server/IDE clients. ### Continuous Testing and Documentation Policy - Do not mark any parent checklist item complete until **all** subordinate Code, Document, Tests tasks and any generated `Fix - ...` tasks are resolved and the associated Notes section has the latest context. @@ -1192,14 +1192,14 @@ CLEVERAGENTS_TEST_MODE=true - Milestone forecast (Target -> ETA | Delta | Risk): - M1 (2026-02-15) -> ETA 2026-02-20 | +5d | HIGH - M2 (2026-02-18) -> ETA 2026-02-24 | +6d | HIGH - - M3 (2026-02-22) -> ETA 2026-02-28 | +6d | HIGH - - M4 (2026-03-01) -> ETA 2026-03-05 | +4d | MED-HIGH - - M5 (2026-03-05) -> ETA 2026-03-08 | +3d | MEDIUM + - M3 (2026-02-22) -> ETA 2026-02-27 | +5d | HIGH + - M4 (2026-03-01) -> ETA 2026-03-04 | +3d | MED-HIGH + - M5 (2026-03-05) -> ETA 2026-03-06 | +1d | MEDIUM - M6 (2026-03-10) -> ETA 2026-03-12 | +2d | MEDIUM - Track forecast (Track | Status | ETA | Risk | Blocking): - Track A (Plan lifecycle + persistence) | behind ~2-3d | ETA 2026-02-20 | MED-HIGH | execute/apply integration + CLI/Robot tests - Track B (Projects/resources + sandbox) | behind ~3-4d | ETA 2026-02-24 | MED-HIGH | resource tree/inspect + handlers/auto-discovery - - Track C (Actors/tools/skills/validations) | behind ~6-7d | ETA 2026-02-28 | HIGH | actor YAML compiler + tool/validation CLI + registry persistence + - Track C (Actors/tools/skills/validations) | behind ~6-7d | ETA 2026-02-27 | HIGH | actor YAML compiler + tool/validation CLI + registry persistence - Track D (Change tracking + apply pipeline) | behind ~4-5d | ETA 2026-02-24 | HIGH | ChangeSet capture + validation gating + diff review - Track Q (Quality automation) | ahead | ETA 2026-02-18 | LOW | maintenance only - Track T (Testing) | at risk (Rui out) | ETA 2026-02-27+ | HIGH | QA load on Brent + feature owners @@ -1210,6 +1210,32 @@ CLEVERAGENTS_TEST_MODE=true - Aditya | available | medium | MEDIUM | actor/skill YAML configs + MCP adapter + hierarchical graphs - Brent | available | high (QA load) | MED-HIGH | coverage + integration stability + CLI/persistence tests - Rui | unavailable 2026-02-13 to 2026-02-27 | zero | HIGH | test backlog resumes after 2026-02-27 +- Mike/Brian | standby | low | LOW | none + +### 2026-02-18 (Day 10 since kickoff on 2026-02-09) +- Timeline reference: Day 7/M1 = 2026-02-15, Day 10/M2 = 2026-02-18, Day 14/M3 = 2026-02-22, Day 21/M4 = 2026-03-01, Day 25/M5 = 2026-03-05, Day 30/M6 = 2026-03-10. +- Summary (Team | Status | Risk | Notes): Behind ~3-4d | HIGH | M1 blocked by apply pipeline + validation gating + M1 CLI/persistence tests; resource/project registries and tool runtime are done, actor/skill schema work in progress. +- Milestone forecast (Target -> ETA | Delta | Risk): + - M1 (2026-02-15) -> ETA 2026-02-20 | +5d | HIGH + - M2 (2026-02-18) -> ETA 2026-02-24 | +6d | HIGH + - M3 (2026-02-22) -> ETA 2026-02-27 | +5d | HIGH + - M4 (2026-03-01) -> ETA 2026-03-04 | +3d | MED-HIGH + - M5 (2026-03-05) -> ETA 2026-03-06 | +1d | MEDIUM + - M6 (2026-03-10) -> ETA 2026-03-10 | +0d | MED-HIGH +- Track forecast (Track | Status | ETA | Risk | Blocking): + - Track A (Plan lifecycle + persistence) | behind ~2-3d | ETA 2026-02-20 | MED-HIGH | apply pipeline wiring + CLI/persistence tests + - Track B (Projects/resources + sandbox) | behind ~3-4d | ETA 2026-02-24 | MED-HIGH | resource tree/inspect + handlers/auto-discovery + - Track C (Actors/tools/skills/validations) | behind ~5-6d | ETA 2026-02-27 | HIGH | actor compiler + tool/validation CLI + MCP/Agent Skills adapters + - Track D (Change tracking + apply pipeline) | behind ~4-5d | ETA 2026-02-24 | HIGH | apply pipeline + validation gating + diff review + - Track Q (Quality automation) | ahead | ETA 2026-02-18 | LOW | maintenance only + - Track T (Testing) | at risk (Rui out) | ETA 2026-02-27+ | HIGH | QA load on Brent + feature owners +- Developer forecast (Name | Availability | Load | Risk | Focus): + - Jeff | available | critical-path overloaded | HIGH | apply pipeline wiring + tool/validation CLI + actor compiler + - Luis | available | high | MED-HIGH | apply pipeline + validation runner + decision persistence + - Hamza | available | med-high | MEDIUM | resource handlers + DAG CLI + UKO/RDF groundwork + - Aditya | available | medium | MEDIUM | actor/skill YAML configs + MCP/Agent Skills adapters + - Brent | available | high (QA load) | MED-HIGH | M1/M2 CLI/persistence tests + coverage stability + - Rui | unavailable 2026-02-13 to 2026-02-27 | zero | HIGH | test backlog resumes after 2026-02-27 - Mike/Brian | standby | low | LOW | none ## Implementation Checklist @@ -1434,23 +1460,23 @@ Merge points and acceptance checks are tracked as checklist items under each mil - [X] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. (97% total, fail-under=97 passes) - [X] **COMMIT (Owner: Brent | Group: Q0-Minimum | Branch: feature/q0-min-coverage | Done: Day 5, February 13, 2026 18:54:15 +0000) - Commit message: "feat(qa): enforce coverage >=97% in CI"** - - [X] Git [Brent]: `git checkout master` - done on 2026-02-13 - - [X] Git [Brent]: `git pull origin master` - done on 2026-02-13 - - [X] Git [Brent]: `git checkout -b feature/q0-min-coverage` - done on 2026-02-13 + - [X] Git [Brent]: `git checkout master` + - [X] Git [Brent]: `git pull origin master` + - [X] Git [Brent]: `git checkout -b feature/q0-min-coverage` - [X] Git [Brent]: `git fetch origin && git merge origin/master` (run before final tests and before commit) - skipped (SSH key unavailable in CI, already on latest master) - - [X] Code [Brent]: Ensure `nox -s coverage_report` fails below 97% and emits a single-line error message suitable for CI parsing. - done on 2026-02-13 (COVERAGE_THRESHOLD constant + session.error with CI-parseable summary) - - [X] Code [Brent]: Update CI summary output (or job annotations) to surface the 97% threshold failure line clearly. - done on 2026-02-13 (added "Surface coverage summary" step in CI that reads build/coverage.json) - - [X] Docs [Brent]: Update `docs/development/testing.md` with the 97% coverage requirement and a sample failure output. - done on 2026-02-13 (created docs/development/testing.md with full testing guide) - - [X] Tests (Behave) [Brent]: Add a scenario that parses coverage config and asserts threshold >=97%. - done on 2026-02-13 (features/coverage_threshold_enforcement.feature, 11 scenarios) - - [X] Tests (Robot) [Brent]: Add a Robot test that runs `nox -s coverage_report` and asserts pass/fail behavior. - done on 2026-02-13 (robot/coverage_threshold.robot, 6 test cases) - - [X] Tests (ASV) [Brent]: Add `benchmarks/coverage_report_bench.py` for coverage report runtime baseline. - done on 2026-02-13 (benchmarks/coverage_report_bench.py, 4 benchmarks) - - [X] Quality [Brent]: Run `nox` (all default sessions, including benchmark). - done on 2026-02-13 (lint 0 findings, typecheck 0 errors, 2235 unit scenarios passed, 211 integration tests passed) - - [X] Git [Brent]: `git add .` (only after coverage check passes) - done on 2026-02-13 - - [X] Git [Brent]: `git commit -m "feat(qa): enforce coverage >=97% in CI"` (only after coverage check passes) - done on 2026-02-13 + - [X] Code [Brent]: Ensure `nox -s coverage_report` fails below 97% and emits a single-line error message suitable for CI parsing. (COVERAGE_THRESHOLD constant + session.error with CI-parseable summary) + - [X] Code [Brent]: Update CI summary output (or job annotations) to surface the 97% threshold failure line clearly. (added "Surface coverage summary" step in CI that reads build/coverage.json) + - [X] Docs [Brent]: Update `docs/development/testing.md` with the 97% coverage requirement and a sample failure output. (created docs/development/testing.md with full testing guide) + - [X] Tests (Behave) [Brent]: Add a scenario that parses coverage config and asserts threshold >=97%. (features/coverage_threshold_enforcement.feature, 11 scenarios) + - [X] Tests (Robot) [Brent]: Add a Robot test that runs `nox -s coverage_report` and asserts pass/fail behavior. (robot/coverage_threshold.robot, 6 test cases) + - [X] Tests (ASV) [Brent]: Add `benchmarks/coverage_report_bench.py` for coverage report runtime baseline. (benchmarks/coverage_report_bench.py, 4 benchmarks) + - [X] Quality [Brent]: Run `nox` (all default sessions, including benchmark). (lint 0 findings, typecheck 0 errors, 2235 unit scenarios passed, 211 integration tests passed) + - [X] Git [Brent]: `git add .` (only after coverage check passes) + - [X] Git [Brent]: `git commit -m "feat(qa): enforce coverage >=97% in CI"` (only after coverage check passes) - [X] Forgejo PR [Brent]: Open PR from `feature/q0-min-coverage` to `master` with description "Enforce 97% coverage via nox coverage_report with explicit CI summary output and updated docs/tests.". - [X] Git [Brent]: `git checkout master` - [X] Git [Brent]: `git branch -d feature/q0-min-coverage` - - [X] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`. - done on 2026-02-13 (97.5% coverage, threshold 97%) + - [X] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`. (97.5% coverage, threshold 97%) **Parallel Group Q0-Advanced Gates [Brent - AFTER M1]** @@ -1517,11 +1543,11 @@ No standalone Q0-Advanced commits planned. Advanced QA enhancements are bundled - [X] Traceability [Aditya]: Found commit "docs(skill): add skill YAML schema and examples" (2026-02-16T19:52:47+05:30); updated C0.skill.schema Done/commit message to match. - [X] Traceability [Aditya]: Found commit "feat(cli): add skill commands" (2026-02-17T14:44:40+00:00); updated C0.skill.cli Done/commit message to match. - [X] Traceability [Aditya]: Found commit "docs(actor): update schema.py module docstring" (2026-02-09T20:23:33+05:30); updated C3.schema Done/commit message to match. -- [ ] Traceability [Aditya]: Find the actual commit message used for "feat(actor): add built-in provider actors" in `git log --all`, then update the completed COMMIT entry to replace "Done: commit not found" with the correct `Done: Day ,