diff --git a/.operator/analyst/consistency.md b/.operator/analyst/consistency.md index 0ac6f61..eba1483 100644 --- a/.operator/analyst/consistency.md +++ b/.operator/analyst/consistency.md @@ -10,8 +10,8 @@ Cross-stack consistency checks for the monorepo. Reference, do not restate: `intelligence/rules/context.md`, and `intelligence/rules/dev-context-engineering.md`. ## Package & layer boundaries -- Import direction holds everywhere: `core` (nothing runtime) ← `adapters` ← `engine`; `app` uses `core` types + `adapters` read-only, never `engine` runtime. -- Inside `engine/`, imports flow strictly downward per the layer graph (`platforms/` ⇏ `agents/`, `storage/` ⇏ `pipeline/`, `infra/` → Node built-ins only). +- Import direction holds everywhere: `core` (runtime limited to Zod schema values + error classes; `zod` only) ← `adapters` ← `engine`; `app` uses `core` types + `adapters` read-only, never `engine` runtime. +- Inside `engine/`, imports flow strictly downward per the layer graph (`platforms/` ⇏ `agents/`, `storage/` ⇏ `pipeline/`, `infra/` → `@operator/core` + `logging/` (types) + Node built-ins (+ better-sqlite3 under `infra/local/`), `logging/` → `@operator/core` types + pino + Node built-ins). - Primitive-boundary calls (`git.*`, `PRManager.*`, `VCSPlatform.*`, `AgentRuntime.run`, KV writes) appear only in `engine/pipeline/primitives/**`. ## Vocabulary & language diff --git a/.operator/context/engine.md b/.operator/context/engine.md index cf0f02e..93f672c 100644 --- a/.operator/context/engine.md +++ b/.operator/context/engine.md @@ -21,8 +21,8 @@ pipeline/primitives/ → agents/, platforms/, storage/, infra/, @operator/core agents/ → platforms/, events/, infra/, @operator/core platforms/ → infra/, logging/, @operator/core storage/ → @operator/core, @operator/adapters -infra/ → Node built-ins only -logging/ → nothing +infra/ → @operator/core, logging/ (types), Node built-ins (+ better-sqlite3 under infra/local/) +logging/ → @operator/core (types), pino, Node built-ins ``` `platforms/` must NOT import `agents/`; `storage/` must NOT import `pipeline/`; etc. diff --git a/.operator/data/retrospectives/2026W28.md b/.operator/data/retrospectives/2026W28.md new file mode 100644 index 0000000..dc20802 --- /dev/null +++ b/.operator/data/retrospectives/2026W28.md @@ -0,0 +1,96 @@ +## Optimization 2026W28 + +### Prompt Changes Applied +- `context/engine.md`: Corrected `infra/` layer-graph line to include `logging/` (types) plus `@operator/core`, `pino`, and `better-sqlite3` under `infra/local/`. +- `analyst/consistency.md`: Replaced stale `core (nothing runtime)` and incomplete `infra/` dependency claims with accurate package-boundary wording (`logging/` types, `better-sqlite3`). +- `improver/quality-log.md`: Added fenced AOP block syntax requirement (`=== EMIT ===` … `=== END EMIT ===`); colon `EMIT:` lines are silently dropped. +- `planner/quality-gates.md`: Added canonical frontmatter quoting rule (all `buildFrontmatter` double-quoted fields: `title`, `source`, `parent_id`, `created_at`, status timestamps, `path`). + +### Task Changes +- No reprioritization — both pending tasks (`T20260704-192F30EC`, `T20260704-7B62ACD9`) remain valid and unblocked. +- `T20260704-7B62ACD9`: clarified acceptance-criteria grep step via body-update below (invalid `:38` pathspec suffix removed). + +=== EMIT body-update === +target: T20260704-7B62ACD9 +body: | + # Correct the false "zero runtime" claim about @operator/core + + ## Problem + Authoritative rules and docs describe `@operator/core` as having "zero + runtime code" / "zero runtime dependencies" (error classes as the only + runtime). This is false: `packages/core/package.json` declares `zod` as a + runtime dependency and `packages/core/src/schemas/**` (15+ files, e.g. + `repo.schema.ts:1` `import { z } from "zod"`) constructs Zod schema **values** + at runtime. Because these rules are loaded into every agent's context, the + drift steers agents toward wrong conclusions (rejecting legitimate schema code + in core, or duplicating schemas elsewhere to "keep core runtime-free"). + + ## Solution + Correct every **package-level** "zero runtime" claim to state core's real + permitted runtime precisely. Use consistent phrasing, e.g.: + + > `@operator/core` — shared types, interfaces, Zod schemas, and error classes. + > Runtime is limited to Zod schema values + error class constructors, with + > `zod` as its single runtime dependency. No cross-workspace runtime imports. + + Prefer having secondary docs reference the rule rather than restate the full + boundary (single source of truth), but at minimum make each statement accurate. + + ### MUST NOT change (these are correct or off-limits) + - `types/`-subdirectory-scoped claims — schemas live in `schemas/`, not + `types/`, so these remain true: `intelligence/rules/typescript.md:38`, + `docs/architecture-v5.md:1519`, `intelligence/agents/operator-code-reviewer.md:44`. + - `.operator/data/findings/F20260704-0002.md` — the finding record quotes the + stale claim to describe the bug and is orchestrator-owned; do not edit it. + - `AGENTS.md` is generated — do NOT hand-edit; regenerate via + `bash intelligence/scripts/sync.sh` after editing the source rules. + + ## Affected Files + - `intelligence/rules/context.md:35` — repo-tree comment: replace + "shared types + interfaces, zero runtime code" with the accurate runtime. + - `intelligence/rules/typescript.md:70-71` — package-boundary table for + `@operator/core`: line 70 ("nothing runtime") and line 71 + ("error classes (the only runtime)") must reflect `zod` + Zod schema values. + - `docs/architecture-v5.md:102-103` — tree comment "shared contracts (zero + runtime except error classes)". + - `docs/architecture-v5.md:197-199` — boundary block ("nothing external except + type-only node: modules" / "zero runtime code beyond error class constructors"). + - `docs/architecture-v5.md:217` — "`core` has zero runtime dependencies." + (flatly contradicted by the `zod` dependency). + - `intelligence/agents/operator-code-reviewer.md:24` — "@operator/core has + zero runtime dependencies beyond error class constructors". + - `CONTRIBUTING.md:42` — "shared types, interfaces, error classes (zero runtime)". + - `AGENTS.md` — regenerate from the corrected rules via + `bash intelligence/scripts/sync.sh` (do not hand-edit). + + ## Acceptance Criteria + - `intelligence/rules/context.md` and `intelligence/rules/typescript.md` + describe core's actual permitted runtime (Zod schema values + error classes, + `zod` as the single runtime dependency). + - Run `git grep -in "zero runtime" -- ':!.operator'` and confirm every hit + is either an accurate `types/`-subdirectory-scoped statement (e.g. + `intelligence/rules/typescript.md` runtime-code-in-`types/` rule) or the + orchestrator-owned finding record `F20260704-0002.md` (exempt). No + package-level "zero runtime" claim about `@operator/core` remains in + `docs/**`, `intelligence/**`, `CONTRIBUTING.md`, or regenerated `AGENTS.md`. + - The `types/`-subdirectory-scoped statements and the finding record are left + unchanged. + - This is a documentation-only change with no runtime behavior change, so the + regression guard is the grep verification above plus a clean `npm run lint`; + a vitest regression test does not apply (no executable behavior changes). + - Build/lint pass: `npm run typecheck` and `npm run lint` are clean. +=== END EMIT === + +### Status Reconciliation +- None — all 14 pending findings and 2 pending tasks are in consistent `pending` state; no parent/child lifecycle drift detected. + +### New Patterns (watching) +- **Improver AOP colon-syntax** (`F20260705-8DE9F5EB`): bundled `engine/content/prompts/agents/improver.md` still documents `EMIT: status-update` YAML-key form; parser requires fenced blocks. `.operator/improver/quality-log.md` now pins correct syntax; engine prompt fix still needs a task. +- **Work-item frontmatter quoting drift**: planner-generated task samples use unquoted `title`/`parent_id` — rule added after two PR review threads; watch for recurrence before extending to creator prompts. +- **Layer-graph stale lines in `intelligence/rules/typescript.md`**: `infra/` and `logging/` lines at `:105-106` still wrong in the authoritative rule (finding `F20260705-0556B309`); `.operator/context/engine.md` corrected locally. + +### No Changes Needed +- `.operator/context/project.md`, `packages.md`, `verifier/packages.md` — already state accurate `@operator/core` runtime boundary. +- `.operator/project.yaml` and `README.md` — auto-detect order and merge-policy wording already correct. +- `.operator/analyst/prompt-quality.md` — already covers prompt↔code drift and AOP contract alignment. +- Task queue — no obsolete or duplicate tasks to cancel; 12 engine-code findings await dedicated tasks beyond the two in-flight doc/prompt fixes. \ No newline at end of file diff --git a/.operator/improver/quality-log.md b/.operator/improver/quality-log.md index f4ea11c..2f6e755 100644 --- a/.operator/improver/quality-log.md +++ b/.operator/improver/quality-log.md @@ -45,3 +45,24 @@ findings for this repository. proposals to change analyzer/creator/verifier rules are emitted as findings (kind: finding) so they go through the normal PR gate — the retrospective never edits rule files directly. + +## AOP lifecycle records (required syntax) + +Status reconciliation, task cancellation, and body clarifications MUST use +fenced AOP blocks — the parser accepts ONLY `=== EMIT ===` … +`=== END EMIT ===` markers (`engine/pipeline/primitives/agent-output-protocol.ts`). +Colon-prefixed lines like `EMIT: status-update` are free text and are silently +dropped. + +Example: + +``` +=== EMIT status-update === +target: F20260416-0002 +status: rejected +reason: "superseded by merged task" +=== END EMIT === +``` + +Use the same fenced form for `child-item` and `body-update`. Never edit work-item +frontmatter directly — emit lifecycle changes through these blocks only. diff --git a/.operator/planner/quality-gates.md b/.operator/planner/quality-gates.md index 89a6738..11d3e71 100644 --- a/.operator/planner/quality-gates.md +++ b/.operator/planner/quality-gates.md @@ -26,3 +26,10 @@ Rules for validating findings and generating tasks in this repository. - **Reject non-actionable findings** back with reason: no concrete file:line evidence, stylistic preference without a rule source, or duplicate of an open item. +- **Work-item frontmatter quoting.** Generated task/finding bodies are + orchestrator-owned, but when a plan embeds a sample frontmatter block, match + the canonical writer (`buildFrontmatter` in `engine/work-items/work-items.ts`): + `title`, `source`, `parent_id`, `created_at`, status timestamps (`started_at`, + `completed_at`, `failed_at`, `rejected_at`), and `path` are double-quoted + strings. Unquoted scalars create noisy diffs when the orchestrator later + patches status fields.