diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json deleted file mode 100644 index f69e7464..00000000 --- a/.claude-plugin/marketplace.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", - "name": "maister-plugins", - "version": "2.2.1", - "description": "Structured, standards-aware development workflows for Claude Code", - "owner": { - "name": "Skillpanel", - "email": "marek@skillpanel.com" - }, - "plugins": [ - { - "name": "maister", - "description": "Structured, standards-aware development workflows for Claude Code", - "source": "./plugins/maister", - "category": "development" - }, - { - "name": "maister-copilot", - "description": "Structured, standards-aware development workflows for GitHub Copilot CLI", - "source": "./plugins/maister-copilot", - "category": "development" - } - ] -} diff --git a/.codex/agents/advisor.toml b/.codex/agents/advisor.toml new file mode 100644 index 00000000..6f572b98 --- /dev/null +++ b/.codex/agents/advisor.toml @@ -0,0 +1,18 @@ +name = "advisor" +description = "Read-only Maister gate advisor. Returns a structured recommendation and never edits project files." +model = "gpt-5.6-sol" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" +developer_instructions = """ +Analyze one Maister orchestrator gate at a time. Return only valid YAML with +selected_option, rationale, confidence, and escalate_to_user. Never edit files, +write orchestrator-state.yml or reports, invoke user-question tools, inject a +synthetic user answer, or bypass the hard safety denylist. The Codex host +adapter invokes this agent only for the primary recommendation; disagreements +are delegated to the separate read-only arbiter profile. +The user gate is a plain-text user question; state writes and resume reads use +orchestrator-state.yml. For a valid non-denylisted fully_automatic result, the +orchestrator continues through phase_continue(selected_option) after terminal +state and report persistence; it does not synthesize input into a user prompt. +The denylist and implementation-approval gate always remain manual. +""" diff --git a/.codex/agents/arbiter.toml b/.codex/agents/arbiter.toml new file mode 100644 index 00000000..3e60fa4b --- /dev/null +++ b/.codex/agents/arbiter.toml @@ -0,0 +1,14 @@ +name = "arbiter" +description = "Read-only Maister gate arbiter. Resolves one disagreement between recommendations and never edits project files." +model = "gpt-5.6-sol" +model_reasoning_effort = "high" +sandbox_mode = "read-only" +developer_instructions = """ +Arbitrate one Maister orchestrator gate disagreement at a time. Return only +valid YAML with selected_option, rationale, confidence, and escalate_to_user. +Choose exactly one of the two supplied competing recommendations or escalate +to the user. Never invent a third option, edit files, write orchestrator-state.yml +or reports, invoke user-question tools, inject a synthetic user answer, bypass +the hard safety denylist, or start another Advisor/Arbiter loop. The denylist +and implementation-approval gate always remain manual. +""" diff --git a/.cursor/rules/maister-docs.mdc b/.cursor/rules/maister-docs.mdc new file mode 100644 index 00000000..6a2724ba --- /dev/null +++ b/.cursor/rules/maister-docs.mdc @@ -0,0 +1,10 @@ +--- +description: Read Maister project documentation before coding +alwaysApply: true +--- + +# Maister Documentation + +Before starting any task, read `.maister/docs/INDEX.md` first. It indexes coding standards, project vision, tech stack, and architecture decisions. + +Follow standards in `.maister/docs/standards/` when writing code. If standards conflict with the task, ask the user. diff --git a/.github/workflows/build-copilot.yml b/.github/workflows/build-copilot.yml deleted file mode 100644 index aee90534..00000000 --- a/.github/workflows/build-copilot.yml +++ /dev/null @@ -1,25 +0,0 @@ -name: Build Copilot CLI Variant -on: - push: - branches: [master, v2] - paths: ['plugins/maister/**', 'platforms/**'] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Build Copilot CLI variant - run: make build - - - name: Validate build - run: make validate - - - name: Commit if changed - run: | - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - git add plugins/maister-copilot/ - git diff --cached --quiet || git commit -m "Rebuild Copilot CLI variant" - git push diff --git a/.github/workflows/cursor-cli-smoke.yml b/.github/workflows/cursor-cli-smoke.yml new file mode 100644 index 00000000..52b732d0 --- /dev/null +++ b/.github/workflows/cursor-cli-smoke.yml @@ -0,0 +1,47 @@ +name: Cursor CLI Evidence (provisional) + +on: + schedule: + - cron: "0 6 * * 1" + workflow_dispatch: + +concurrency: + group: cursor-cli-evidence + cancel-in-progress: true + +jobs: + evidence: + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + fetch-depth: 0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 + with: + node-version: 22 + - name: Validate Cursor overlay + run: make test-overlay TARGET=cursor + - name: Probe preinstalled Cursor Agent CLI + run: | + set -euo pipefail + export PATH="$HOME/.cursor/bin:$HOME/.local/bin:$PATH" + node --input-type=module <<'EOF' | tee cursor-evidence.json + import { probeCursor } from './plugins/maister/lib/distribution/host-probes/cursor.mjs'; + const result = probeCursor(); + process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + EOF + if grep -q '"result": "unavailable"' cursor-evidence.json; then + echo "::notice title=Cursor evidence unavailable::No preinstalled Cursor Agent CLI was found; this run is packaging/provisional evidence only." + else + echo "::notice title=Cursor evidence collected::Native evidence was collected from the preinstalled runtime; review the artifact before making a support claim." + fi + - name: Validate evidence contract + run: make test-evidence + - name: Upload Cursor evidence record + if: always() + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: cursor-cli-evidence-${{ github.run_id }} + path: cursor-evidence.json + if-no-files-found: warn diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f7768f65..3b5167dc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,17 +1,72 @@ name: Release + on: push: - tags: ['v*'] + tags: ["v*"] jobs: - release: + validate: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - - name: Build and validate - run: make build && make validate + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + fetch-depth: 0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 + with: + node-version: 22 + - name: Validate source, overlays, evidence, and topology + run: make validate + - name: Run reviewed three-target parity release gate + run: | + mkdir -p dist + make test-parity-release PARITY_REPORT=dist/parity-release.json + - name: Run portable core tests before generating E3 + run: make test-core + - name: Generate deterministic portable-core E3 attestation + run: | + make generate-e3-attestation \ + E3_OUTPUT=dist/e3-portable-core.json \ + E3_RESULT=passed \ + E3_TEST_COMMAND="make test-core" \ + SOURCE_COMMIT="$GITHUB_SHA" \ + SOURCE_VERSION="${GITHUB_REF_NAME#v}" \ + SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" + - name: Package target overlays + run: | + SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" E3_ATTESTATION=dist/e3-portable-core.json make package TARGET=codex SOURCE_COMMIT="$GITHUB_SHA" SOURCE_VERSION="${GITHUB_REF_NAME#v}" + SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" E3_ATTESTATION=dist/e3-portable-core.json make package TARGET=cursor SOURCE_COMMIT="$GITHUB_SHA" SOURCE_VERSION="${GITHUB_REF_NAME#v}" + SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" E3_ATTESTATION=dist/e3-portable-core.json make package TARGET=kiro-cli SOURCE_COMMIT="$GITHUB_SHA" SOURCE_VERSION="${GITHUB_REF_NAME#v}" + - name: Smoke extracted target archives + env: + MAISTER_PACKAGE_DIR: dist + run: node --test tests/platform-independent/release-package.test.mjs + - name: Generate package checksums + run: (cd dist && sha256sum maister-*.tar.gz > SHA256SUMS) + - name: Generate release provenance and SBOM metadata + run: | + node plugins/maister/bin/release-metadata.mjs \ + --archive-dir dist \ + --output-dir dist \ + --source-commit "$GITHUB_SHA" \ + --source-version "${GITHUB_REF_NAME#v}" \ + --parity-report dist/parity-release.json \ + --source-date-epoch "$(git log -1 --format=%ct)" + - name: Verify release metadata + run: node plugins/maister/bin/release-metadata.mjs --archive-dir dist --output-dir dist --check + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: maister-target-packages + path: dist/* - - uses: softprops/action-gh-release@v2 + publish: + needs: validate + runs-on: ubuntu-latest + steps: + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: maister-target-packages + path: dist + - uses: softprops/action-gh-release@72f2c25fcb47643c292f7107632f7a47c1df5cd8 # v2.3.2 with: generate_release_notes: true + files: dist/* diff --git a/.github/workflows/validate-generated-variants.yml b/.github/workflows/validate-generated-variants.yml new file mode 100644 index 00000000..a23b8084 --- /dev/null +++ b/.github/workflows/validate-generated-variants.yml @@ -0,0 +1,39 @@ +name: Validate Portable Distribution + +on: + push: + branches: [master] + paths: + - "plugins/maister/**" + - "tests/platform-independent/**" + - "Makefile" + - ".github/workflows/**" + pull_request: + branches: [master] + paths: + - "plugins/maister/**" + - "tests/platform-independent/**" + - "Makefile" + - ".github/workflows/**" + +jobs: + core: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + fetch-depth: 0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 + with: + node-version: 22 + - name: Validate all overlays + run: | + make test-overlay TARGET=codex + make test-overlay TARGET=cursor + make test-overlay TARGET=kiro-cli + - name: Run portable and distribution tests + run: make test-core test-evidence + - name: Verify repository topology + run: make test-topology + - name: Run reviewed three-target parity release gate + run: make test-parity-release diff --git a/.gitignore b/.gitignore index 0db5ed81..f5597207 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,6 @@ # Claude local settings .claude/settings.local.json -# Maister task tracking (generated per-project, not part of plugin source) -.maister/ + /.worktrees/ +/.maister-kiro-build.lock.d/ diff --git a/.maister/config.yml b/.maister/config.yml new file mode 100644 index 00000000..37b4d965 --- /dev/null +++ b/.maister/config.yml @@ -0,0 +1,28 @@ +# Maister project configuration. +# html_output — generate the operator dashboard (dashboard.html + dashboard-data.js, +# auto-opened in your browser) and the HTML companion reports (.html twins of spec, +# implementation plan, verification, and research/design outputs). Set to false for +# markdown-only runs. Markdown artifacts, their TL;DR summary blocks, and +# orchestrator-state.yml are produced regardless. Default: true. +html_output: true + +# Advisor gate policy is opt-in. Gate types accept manual, advisor, or +# fully_automatic. The hard safety denylist in orchestrator-patterns.md cannot +# be overridden by this configuration. +advisor: + enabled: true + gate_policies: + phase-exit: fully_automatic + optional-phase: fully_automatic + clarify: fully_automatic + convergence: fully_automatic + verify-matrix: fully_automatic + advisor_agent: advisor + advisor_model: gpt-5.6-sol + arbiter_agent: arbiter + arbiter_model: gpt-5.6-sol + arbiter_enabled_on_disagreement: true + retry: + advisor_attempts: 3 + arbiter_attempts: 3 + backoff: exponential diff --git a/.maister/docs/INDEX.md b/.maister/docs/INDEX.md new file mode 100644 index 00000000..1f7324c5 --- /dev/null +++ b/.maister/docs/INDEX.md @@ -0,0 +1,103 @@ +# Documentation Index + +**IMPORTANT**: Read this file at the beginning of any development task to understand available documentation and standards. + +## Quick Reference + +### Project Documentation +Project-level documentation covering vision, goals, roadmap, architecture, and technology choices. + +### Technical Standards +Coding standards, conventions, and best practices organized by domain. + +--- + +## Project Documentation + +Located in `.maister/docs/project/` + +### Vision (`project/vision.md`) +Defines Maister as a safe, auditable, resumable multi-platform SDLC plugin; records its users, purpose, current state, platform-parity goals, Advisor/Arbiter safety principles, and expected evolution. + +### Roadmap (`project/roadmap.md`) +Captures the current v2.2.1 feature baseline and analysis-derived priorities for runtime continuation coverage, Advisor/Arbiter assurance, platform parity, tool compatibility, reproducibility, semantic transforms, and governance. + +### Tech Stack (`project/tech-stack.md`) +Documents the Markdown/YAML, Bash, JavaScript ESM, JSON, TOML, HTML/CSS, Make, shell-tool, GitHub Actions, and optional Playwright MCP stack, including testing, distribution, persistence, and version-management choices. + +### Architecture (`project/architecture.md`) +Describes the canonical-plugin and deterministic multi-target adapter architecture, generated artifact ownership, orchestration and Advisor/Arbiter flows, build validation, external integrations, state persistence, configuration, and deployment model. + +--- + +## Technical Standards + +### Global Standards + +Located in `.maister/docs/standards/global/` + +#### Build Pipeline (`standards/global/build-pipeline.md`) +Canonical edits in `plugins/maister/`, host-specific adapters in `platforms/`, generated-target ownership, reproducible `make build` outputs, CI drift detection, and mandatory cross-platform `make build && make validate` before `v*` releases. + +#### Coding Style (`standards/global/coding-style.md`) +Naming consistency, automatic formatting, descriptive names, focused functions, uniform indentation, dead-code removal, intentional compatibility, and DRY guidance. + +#### Commenting (`standards/global/commenting.md`) +Self-explanatory code, sparing comments for non-obvious logic, and timeless comments rather than change logs. + +#### Conventions (`standards/global/conventions.md`) +Project structure, current documentation, version-control hygiene, environment configuration, dependency discipline, reviews, test expectations, feature flags, changelogs, and avoiding speculative work. + +#### Error Handling (`standards/global/error-handling.md`) +Actionable user errors, fail-fast checks, typed exceptions, boundary-level handling, graceful degradation, retry backoff, and resource cleanup. + +#### language.md Convention (`standards/global/language-md-convention.md`) +Optional bounded-context language files, required glossary and integration sections, DDD relationship semantics, published APIs, adoption guidance, and linguistic-boundary verification. + +#### Minimal Implementation (`standards/global/minimal-implementation.md`) +Called code only, clear purpose, removal of exploration artifacts and dead code, no future stubs, no speculative abstractions, and pre-commit caller review. + +#### Validation (`standards/global/validation.md`) +Server and client validation responsibilities, early and specific failures, allowlists, type and format checks, sanitization, business-rule placement, and consistent enforcement. + +### Frontend Standards + +*Not initialized for this project. If you need frontend standards, you can:* + +- *Add them manually using the docs-manager skill* +- *Run `/maister:standards-discover --scope=frontend` to auto-discover* + +### Backend Standards + +*Not initialized for this project. If you need backend standards, you can:* + +- *Add them manually using the docs-manager skill* +- *Run `/maister:standards-discover --scope=backend` to auto-discover* + +### Testing Standards + +Located in `.maister/docs/standards/testing/` + +#### Test Writing (`standards/testing/test-writing.md`) +Behavior-focused tests, descriptive naming, external-dependency mocks, fast execution, risk-based depth, critical-path protection, and transactional rejection tests that prove byte-exact state, permissions, and directory topology remain unchanged or are fully rolled back. + +--- + +## How to Use This Documentation + +1. **Start Here**: Always read this INDEX.md first to understand what documentation exists +2. **Project Context**: Read relevant project documentation before starting work +3. **Standards**: This index only points to the standards — open and follow the specific standard files relevant to your task; don't rely on the index alone +4. **Keep Updated**: Update documentation when making significant changes +5. **Customize**: Adapt all documentation to your project's specific needs + +## Updating Documentation + +- Project documentation should be updated when goals, tech stack, or architecture changes +- Technical standards should be updated when team conventions evolve +- Always update INDEX.md when adding, removing, or significantly changing documentation + +--- + +**Last Generated**: 2026-07-13 +**Maintained by**: Documentation Manager skill diff --git a/.maister/docs/project/architecture.md b/.maister/docs/project/architecture.md new file mode 100644 index 00000000..d5a4f03d --- /dev/null +++ b/.maister/docs/project/architecture.md @@ -0,0 +1,29 @@ +# Architecture + +## Source and overlays + +`plugins/maister/common/` owns portable primitives and common assets, while canonical portable skills/agents remain under the common source tree consumed by Codex and Kiro CLI. Each directory under `plugins/maister/overlays/` is a strict versioned contract for one supported target. An overlay owns native layout, manifests, settings destinations, semantic bindings, required inventory, forbidden vocabulary, and native hashes. Cursor currently carries a behavior-bearing skills projection in its overlay; that is migration debt, not a second intended source of truth. + +The public installer resolves a clean local Git checkout, a self-contained archive, or `github:owner/repo`. GitHub resolution uses bounded Git commands to resolve a safe ref to one full commit, creates a temporary detached checkout, verifies `HEAD`, status, and content hash, and selects the target overlay from that same checkout. The materializer validates the selected source and overlay, rejects unsafe paths and collisions, and creates a deterministic same-filesystem staging tree with provenance. + +## Installation transaction + +The installer acquires a target lock, writes a durable journal, snapshots managed files and settings, commits through staging, verifies integrity, and publishes a receipt. Whole-file ownership is used for dedicated Maister files. Shared settings use narrowly allowlisted managed keys with drift detection. Rollback and recovery restore bytes, modes, symlinks, existence, and topology while preserving unmanaged content. A code-7 result remains an unresolved operational state: preserve the journal and backups, use the recovery command after the competing process has stopped, and verify the resulting receipt before continuing. + +The lock serializes cooperating Maister lifecycle processes for the same target and state root; it does not serialize the host application or arbitrary external writers. Receipt-listed inventory and managed settings keys are Maister-owned, while all unlisted content is operator-owned. The transaction assumes the operator stops host/editor/synchronization processes that can mutate those paths and protects the state directory from untrusted same-user or privileged writers. Identity revalidation and drift checks fail supported races closed, but no filesystem protocol can guarantee rollback against a malicious process that replaces files concurrently. + +State is separate from workflow state at `$XDG_STATE_HOME/maister/` or `~/.local/state/maister/`. + +State contains `active-receipt.json`, `receipts/`, `journals/`, `backups/`, `staging/`, and `install.lock`. Operators should keep directories at `0700` and receipts, lock metadata, journals, and settings snapshots at `0600`. A code-7 recovery or rollback failure requires preserving this state for diagnosis; it is not resolved by deleting the lock or repeatedly retrying rollback. + +## Evidence + +Compatibility is per capability. E1/E2/E4 are required for each target and E3 is shared. E5/E6 are recorded as `unavailable` when the native executable, authentication, safe probe adapter, or configured versioned scenario is absent. The installer attaches validated baseline and native records to the transaction receipt and evaluates them against the selected release policy. Structural and transactional evidence may permit provisional packaging, but an unavailable record never becomes a semantic pass or a host-native support claim. Evidence must be renewed when its prerequisite becomes available or its host/version/scenario/provenance binding changes. + +## Release artifacts + +`make package TARGET=` stages the runtime, installer, canonical source, selected overlay, `.maister-source.json`, and one validated E3 record at `plugins/maister/.maister-e3-attestation.json`, then emits a deterministically sorted archive with normalized timestamps and ownership. Release order is `make test-core`, `make generate-e3-attestation E3_RESULT=passed`, strict `make test-parity-release` from a clean checkout, package all targets with the same `E3_ATTESTATION`, and run the extracted lifecycle smoke. A dirty-local parity override is diagnostic only and cannot authorize publication. `tests/platform-independent/release-package.test.mjs` builds each target twice, checks deterministic hashes and target isolation, extracts the archives, and runs install/verify/uninstall. Release CI writes `dist/SHA256SUMS`, `dist/SBOM.cdx.json`, and unsigned `dist/PROVENANCE.json` using commit-pinned GitHub Actions; both SBOM and provenance bind the embedded E3 digest and bytes. These sidecars are reproducibility records, not signatures, publisher authentication, or native E6 evidence. Local `dist/` is disposable and may contain stale artifacts; only archives generated and verified in the same clean release job are publishable. + +## Migration boundary + +Legacy generated trees and old builders were shadow oracles only. The parity classifier compares semantic bindings, inventory, references, hooks, permissions, symlinks, and topology, and requires zero unresolved differences before cleanup. Legacy host manifests, hooks, marketplace paths, generated projections, and support rows are migration-era history, not part of the current architecture. diff --git a/.maister/docs/project/roadmap.md b/.maister/docs/project/roadmap.md new file mode 100644 index 00000000..c3358568 --- /dev/null +++ b/.maister/docs/project/roadmap.md @@ -0,0 +1,18 @@ +# Roadmap + +## Current baseline + +- One common source with Codex, Cursor, and Kiro CLI overlays. +- Immutable source and provenance validation. +- Transactional install/update/uninstall/rollback/recovery with receipts and journals. +- Evidence freshness per capability, with explicit unavailable native outcomes. +- Shadow parity and negative topology checks at the migration boundary. +- Bounded immutable GitHub checkout resolution using the same checkout for source and overlay. +- Self-contained deterministic target archives with sorted entries, extracted lifecycle smoke, `SHA256SUMS`, CycloneDX artifact inventory, unsigned reproducibility provenance, and pinned release actions. + +## Next priorities + +- Collect fresh E5/E6 records when native executables, authentication, safe adapters, and versioned scenarios are available; keep missing prerequisites explicit as `unavailable`, never as passed. +- Continue strengthening scenario-level semantic parity and recovery fixtures. +- Keep release packages target-aware without reintroducing generated projections or marketplace assumptions. +- Keep the deterministic portable-core E3 producer and package binding aligned with the portable-core evidence worker; native E5/E6 collection remains environment-dependent and may be provisional. diff --git a/.maister/docs/project/tech-stack.md b/.maister/docs/project/tech-stack.md new file mode 100644 index 00000000..e3909fba --- /dev/null +++ b/.maister/docs/project/tech-stack.md @@ -0,0 +1,10 @@ +# Technology stack + +- Markdown, YAML, JSON, TOML, and shell for contracts, documentation, and host-native assets. +- Node.js ESM with built-in modules for schema validation, source resolution, materialization, probing, receipts, journals, and transactions. +- GNU Make for target-aware validation, focused tests, packaging, and install entry points. +- GitHub Actions for core, overlay, evidence, topology, and release validation. +- Git full-commit validation for clean local provenance and a bounded GitHub resolver that performs detached immutable checkouts with source/overlay co-location. +- Node's built-in test runner for fast behavior-focused tests. + +The distribution no longer relies on independently maintained generated host trees, marketplace publishing, host-specific builders, or a general workflow DSL. Cursor's checked-in compatibility projection is deterministically derived and drift-checked, with explicit exceptions recorded as migration debt. Runtime state and transaction receipts are filesystem artifacts outside the plugin source. Release tarballs are self-contained deterministic archives with explicitly sorted entries and an embedded source manifest. Release output includes SHA-256 checksums, a CycloneDX artifact SBOM, and an unsigned source/overlay/parity provenance record; those records provide integrity only when obtained through a trusted channel, are not publisher authentication or cryptographic attestations, and do not claim native E6. Release actions are pinned to commit SHAs. diff --git a/.maister/docs/project/vision.md b/.maister/docs/project/vision.md new file mode 100644 index 00000000..0f5ef46b --- /dev/null +++ b/.maister/docs/project/vision.md @@ -0,0 +1,14 @@ +# Vision + +Maister is a safe, auditable, resumable SDLC plugin distributed across multiple AI hosts. Its source of truth is a portable common layer with explicit native overlays and a target-aware transactional installer. + +The project optimizes for: + +- one owner for portable behavior; +- visible, versioned host contracts; +- immutable source provenance; +- byte-exact recovery of user state; +- evidence that distinguishes unsupported native runtime from a passing capability; +- small, behavior-focused tests and reproducible releases. + +The supported targets are Codex, Cursor, and Kiro CLI. Legacy host support, marketplace projections, and committed generated trees were migration-era inputs; they are removed from the supported topology and retained only where explicitly identified as historical parity context. diff --git a/.maister/docs/standards/global/build-pipeline.md b/.maister/docs/standards/global/build-pipeline.md new file mode 100644 index 00000000..06e0da7f --- /dev/null +++ b/.maister/docs/standards/global/build-pipeline.md @@ -0,0 +1,25 @@ +# Build pipeline + +`plugins/maister/common/`, canonical portable skills, and `plugins/maister/overlays/` are distribution inputs. There are no independently maintained generated target trees and no host builder that rewrites a second source of truth. Cursor's checked-in compatibility projection is a deterministic, drift-checked migration exception; its source mappings, transformations, exclusions, and preserved exception hashes must remain explicit until the projection is removed. + +Use the target-aware entry points: + +```sh +make test-core +make test-overlay TARGET=codex +make test-materializer TARGET=cursor +make test-install TARGET=kiro-cli +make test-evidence +make test-parity-release +make test-topology +make validate +make package TARGET=codex +``` + +`make validate` loops over `codex`, `cursor`, and `kiro-cli` before running the common core, evidence, and topology checks. Use the explicit `make test-overlay TARGET=` entry point when diagnosing one overlay. + +`test-parity-release` is the reproducible migration/release check: it reconstructs each legacy tree from the reviewed full-commit Git-tree oracle under `tests/fixtures/platform-independent/parity-oracle/manifest.json`, materializes Codex, Cursor, and Kiro CLI from the current checkout, and compares each target with its versioned baseline. No external legacy root is accepted. Rules contain exact paths (or a constrained pattern), immutable side observations, an observed category, and a rationale; the CLI never learns exceptions from its current output. Executable and sensitive permission differences cannot be waived. The release gate must run from a clean checkout; `E_SOURCE_DIRTY` blocks publication. `PARITY_ALLOW_DIRTY_LOCAL=1` is a development-only diagnostic option, is not used by release CI, and can never substitute for the strict result. + +Before release, validate the common core, every overlay, evidence policy, topology, the strict three-target parity gate, package contents, and a clean extracted-archive lifecycle for Codex, Cursor, and Kiro CLI. Run `make test-core`, then `make generate-e3-attestation E3_RESULT=passed` with an explicit source version and deterministic source-date epoch. Pass the generated file as `E3_ATTESTATION` to all three `make package` invocations; the package validator checks its schema, freshness, commit/version binding, and portable-core digest before embedding it at `plugins/maister/.maister-e3-attestation.json`. Archive input paths are explicitly sorted. The release-package test compares two builds per target; release CI invokes the test against all three produced archives, generates `dist/SHA256SUMS`, `dist/SBOM.cdx.json`, and unsigned `dist/PROVENANCE.json`, binds the E3 digest/bytes in the metadata, and blocks publication if the E3-backed lifecycle is not green. Unsigned sidecars do not authenticate the publisher and are trustworthy only through a trusted release channel. E5/E6 may be unavailable because a runtime, authentication, safe adapter, or scenario is missing; this permits only explicitly provisional claims and never a native semantic pass. + +Treat `dist/` as disposable output. A release job starts from an empty or isolated output directory and publishes only artifacts generated and verified in that same job. Existing archives, even with expected names, must not be reused; confirm the `plugins/maister/**` package shape, target isolation, extracted lifecycle, checksums, SBOM, provenance, and strict parity before upload. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/global/coding-style.md b/.maister/docs/standards/global/coding-style.md similarity index 100% rename from plugins/maister-copilot/skills/docs-manager/docs/standards/global/coding-style.md rename to .maister/docs/standards/global/coding-style.md diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/global/commenting.md b/.maister/docs/standards/global/commenting.md similarity index 100% rename from plugins/maister-copilot/skills/docs-manager/docs/standards/global/commenting.md rename to .maister/docs/standards/global/commenting.md diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/global/conventions.md b/.maister/docs/standards/global/conventions.md similarity index 52% rename from plugins/maister-copilot/skills/docs-manager/docs/standards/global/conventions.md rename to .maister/docs/standards/global/conventions.md index 2ba1c27e..d9f33937 100644 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/global/conventions.md +++ b/.maister/docs/standards/global/conventions.md @@ -12,6 +12,14 @@ Write clear commit messages, use feature branches, and add meaningful descriptio ### Environment Variables Store configuration in environment variables; never commit secrets or API keys. +For installation provenance, production instructions use a clean local Git checkout at a full commit SHA. `MAISTER_ALLOW_DIRTY_LOCAL=1` is development-only and must be explicit; it must not appear in a production release command. + +Operator instructions state the ownership and concurrency boundary: Maister owns receipt-listed paths and managed settings keys, its lock coordinates Maister processes only, and host/editor/synchronization writers must be stopped during lifecycle operations. Do not claim protection from malicious same-user or privileged concurrent mutation. + +Treat local `dist/` content as disposable. Release instructions require an isolated clean output directory and same-job validation; never publish an existing archive based on its name, timestamp, or an unsigned checksum alone. + +Do not document unsupported host targets, resolver paths, or package lifecycles as available. Migration-era names may remain only in a clearly labeled historical/parity section. + ### Minimal Dependencies Keep dependencies lean and up-to-date; document why major ones are included. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/global/error-handling.md b/.maister/docs/standards/global/error-handling.md similarity index 54% rename from plugins/maister-copilot/skills/docs-manager/docs/standards/global/error-handling.md rename to .maister/docs/standards/global/error-handling.md index 07e0f610..a42a157e 100644 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/global/error-handling.md +++ b/.maister/docs/standards/global/error-handling.md @@ -20,3 +20,11 @@ Use exponential backoff for transient failures when calling external services. ### Resource Cleanup Always release resources (file handles, connections) in finally blocks or equivalent cleanup mechanisms. + +### Filesystem Transaction Recovery + +Treat exit code `7` as an unresolved transaction, recovery, or rollback failure. Preserve the target-scoped lock, journals, receipts, backups, and staging state; never advise deleting state or repeatedly retrying rollback as a first response. Recovery instructions must distinguish a busy lock (`6`), drift (`5`), validation/source errors (`3`/`4`), and integrity failure (`8`). + +### External Command Boundaries + +CI and operator documentation must not execute unpinned remote scripts. If a native runtime is not already available and no trustworthy vendor digest/signature is verified, record an explicit `unavailable` or provisional result instead of silently swallowing installation failure. diff --git a/.maister/docs/standards/global/language-md-convention.md b/.maister/docs/standards/global/language-md-convention.md new file mode 100644 index 00000000..d6875bf2 --- /dev/null +++ b/.maister/docs/standards/global/language-md-convention.md @@ -0,0 +1,90 @@ +## language.md Convention + +### Purpose +Each bounded context (module, package, or service) maintains a `language.md` file documenting its ubiquitous language — the terms, operations, and events that belong to that context. This enables linguistic boundary verification without a separate context-map file; integration points across modules reconstruct the relationship graph. + +### File Location +Place `language.md` at the root of each module: `/language.md`. + +If your project uses a different layout (monorepo packages, layered directories, service folders), document the pattern in `.maister/docs/INDEX.md` under Global Standards so skills and reviewers can discover it. + +### Template Sections +Every `language.md` should include these sections: + +**Module Description** — What the module does and its role: generalization (serves many consumers with generic language) or specific (owns a particular business capability). Generalizations require stricter boundary enforcement. + +**Core Terms** — Glossary of domain terms owned by this context. Include brief definitions where meaning is non-obvious. + +**Operations** — Commands, use cases, or API operations expressed in this context's language. + +**Events** — Domain events this context publishes or subscribes to, named in this context's vocabulary. + +**Integration Points** — Per related module, declare: +- Relationship type (see Relationship Types below) +- Direction (upstream/downstream or provider/consumer) +- Imported terms (vocabulary received from the other context) +- Exported terms (vocabulary this context exposes to the other) + +**Published API** (optional) — Terms explicitly exported for consumers. When present, downstream modules may only use Published API terms, not internal Core Terms. When absent, all Core Terms are available to consumers. + +### Relationship Types +Use DDD relationship types as defaults — they have well-defined language flow rules: + +- **OHS (Open Host Service)** — Provider exposes API; consumer receives provider's language +- **Customer-Supplier** — Supplier defines language; customer receives it +- **ACL (Anti-Corruption Layer)** — Consumer translates provider's language; foreign terms must not leak into consumer code +- **Conformist** — Consumer fully adopts provider's language +- **Shared Kernel** — Both contexts share explicit terms only + +Team aliases work — "provider/consumer", "library/client", "core/plugin" are fine. What matters is that each integration point declares direction and translation expectations. + +### Adoption +Optional per project. Teams adopt `language.md` when using DDD-style bounded contexts or the `linguistic-boundary-verifier` skill. + +Not required by `maister:init` by default. Future init flags may scaffold stubs; manual creation is the current path. + +### Cross-Reference +The `linguistic-boundary-verifier` skill reads `language.md` files to detect language leakage (strings, events, API calls across boundaries). Without these files, the skill degrades gracefully and outputs adoption guidance pointing to this standard. + +### Minimal Example + +```markdown +# Resource + +## Module Description +Generalization module providing shared resource availability and scheduling. +Serves HR, Training, and Facilities as consumers. + +## Core Terms +- **Resource** — Any bookable entity (room, equipment, trainer slot) +- **Availability** — Time window when a resource can be allocated +- **Allocation** — Binding of a resource to a time period + +## Operations +- checkAvailability(resourceId, timeRange) +- allocate(resourceId, timeRange, requesterId) +- release(allocationId) + +## Events +- ResourceAllocated +- ResourceReleased +- AvailabilityChanged + +## Integration Points + +### HR (Customer-Supplier) +- Direction: HR (supplier) → Resource (customer) +- Imported: EmployeeId, DepartmentCode +- Exported: Availability, Allocation + +### Training (OHS) +- Direction: Resource (provider) → Training (consumer) +- Exported: checkAvailability, allocate, release + +## Published API +- checkAvailability +- allocate +- release +- Availability +- Allocation +``` diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/global/minimal-implementation.md b/.maister/docs/standards/global/minimal-implementation.md similarity index 100% rename from plugins/maister-copilot/skills/docs-manager/docs/standards/global/minimal-implementation.md rename to .maister/docs/standards/global/minimal-implementation.md diff --git a/.maister/docs/standards/global/validation.md b/.maister/docs/standards/global/validation.md new file mode 100644 index 00000000..d9a21456 --- /dev/null +++ b/.maister/docs/standards/global/validation.md @@ -0,0 +1,15 @@ +# Validation + +Validate inputs at the boundary and fail closed for semantic safety. Overlay schemas use allowlists for fields, targets, paths, ownership, inventories, modes, and vocabulary. The source resolver requires immutable full commits. The materializer validates containment, collisions, syntax, inventories, permissions, hashes, symlinks, and unresolved tokens before target mutation. + +Evidence records require target, capability, host version, scenario, timestamp, result, provenance, and expiry. `unavailable` is not a pass. Expired records are renewed when the expiry, host version, overlay version, source commit, or scenario version changes. + +Shadow parity is classified through a checked-in, versioned target manifest. Every expected difference is a narrow exact path (or constrained pattern), with its observed category and rationale; unlisted, stale, overbroad, wrong-category, executable, and sensitive-file exceptions fail validation. The parity CLI must receive `--baseline` and reports unresolved differences separately from reviewed packaging or expected-deletion differences. + +Installers validate drift and ownership before changing shared settings. On failure, journal recovery preserves unmanaged content and restores the complete prior filesystem state. + +Installer concurrency is cooperative, not global. The target lock serializes Maister lifecycle processes for one target/state root but does not lock the host, editor, synchronization tools, direct shell writes, or malicious same-user/privileged processes. Operator documentation must require external writers to stop. Validation must re-check path identity and managed-state drift at mutation boundaries and fail closed when a race is observed; it must not claim atomicity against arbitrary external mutation. + +Release validation includes archive dependency closure and an extracted-artifact lifecycle, not only checkout tests. `test-parity-release` proves the three real materializations compare to an independently reviewed immutable Git-tree oracle from a clean checkout; dirty-local overrides are diagnostic only and cannot satisfy a release gate. `release-package.test.mjs` proves deterministic output, explicitly sorted archive entries, target isolation, embedded source-manifest and E3 integrity, and install/verify/uninstall for all three targets. Every published archive has a SHA-256 entry in `dist/SHA256SUMS`; `SBOM.cdx.json` and unsigned `PROVENANCE.json` bind artifact hashes, the embedded E3 canonical digest/bytes, source commit, source-date epoch, and parity report. Release actions are pinned to commit SHAs. These records do not authenticate the publisher, claim a signed attestation, or provide native E6. Validation publishes only artifacts generated in the same clean job; stale local `dist/` contents are never release inputs. + +The standalone CLI documents only source paths it can execute. The GitHub path is a concrete bounded checkout flow: it resolves a safe ref to one full commit, creates a detached clean checkout, verifies its content hash, and supplies the same checkout root for overlay selection and materialization. A source/overlay root mismatch must fail closed. diff --git a/.maister/docs/standards/testing/test-writing.md b/.maister/docs/standards/testing/test-writing.md new file mode 100644 index 00000000..36e01732 --- /dev/null +++ b/.maister/docs/standards/testing/test-writing.md @@ -0,0 +1,15 @@ +# Test writing + +Tests describe behavior at the common core and real host seams. Parameterize only overlay, materializer, installer, and native probe boundaries; do not duplicate the portable runtime suite for every host. + +Choose test count from behavioral risk and distinct failure boundaries, not a fixed feature-test ceiling. Add strategic assertions when a critical contract is otherwise unproved and remove redundant parameterizations or count-based maintenance assumptions. + +Evidence tests must distinguish `passed`, `failed`, and `unavailable`, exercise expiry and renewal, and prove semantic fail-closed behavior. Topology tests must classify expected packaging differences and fail on unresolved semantic, inventory, reference, hook, permission, symlink, or topology changes. + +Transactional tests snapshot every affected file before invalid-input and injected-failure cases, then compare bytes, modes, symlinks, existence, and directory topology after rollback. Exit codes alone are insufficient evidence of recovery. + +Concurrency tests distinguish cooperating installer processes from external writers. Locks must serialize the former; identity/drift checks must reject observed external races. Tests and documentation must not imply atomicity against arbitrary malicious same-user or privileged mutation. + +Release tests exercise the artifact boundary: build each target twice with a fixed source timestamp, compare archive hashes, assert runtime/source closure and target isolation, extract each archive in a clean directory, and run packaged install, verify, and uninstall for Codex, Cursor, and Kiro CLI. The release workflow also generates `SHA256SUMS`; fixture-based checkout tests cannot substitute for this smoke. + +CI evidence tests must distinguish a preinstalled native runtime from an unavailable runtime. A missing executable, authentication context, safe adapter, or configured versioned scenario must produce an explicit `unavailable`/provisional record; tests must not install code from an unpinned remote script or turn a swallowed failure into a pass. Unavailable E5/E6 never certifies host-native discovery or semantics. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/clarifications.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/clarifications.md new file mode 100644 index 00000000..a654bd19 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/clarifications.md @@ -0,0 +1,35 @@ +# Phase 1 Clarifications + +## TL;DR + +The completed research resolves the architectural direction and implementation boundaries for this development workflow. +No critical clarification remains before gap analysis: implement A3/B1/C1/D1 in canonical sources, preserve protected/manual gates, and keep Codex capability unsupported until real host-native E2E evidence passes. + +## Key Decisions + +- Treat the problem as a reproducible runtime defect plus an architectural enhancement of existing workflow infrastructure — the configured `fully_automatic` path currently falls back to user gates and cannot dispatch subsequent work. +- Keep evaluator selection, runner commit/projection, workflow routing, and Codex active-turn transport as separate responsibilities — this is the accepted research architecture. +- Include schema migration, lock/revision/CAS, durable work-item dispatch receipts, five workflow call-site migrations, generated projections, and layered verification in scope — each is required by the accepted end-to-end behavior. +- Exclude product-design backward refinement and any weakening of denylisted/manual gates — both are outside the researched repair. +- Leave Codex capability `unsupported` until the native Codex E2E exits `0` and proves agreement, one logical arbiter on disagreement, no UI, same-phase continuation, next-phase entry, resume, and deduplication. + +## Open Questions / Risks + +- The exact Codex active-turn/headless binding is an implementation spike within the accepted D1 boundary; a negative empirical result may require returning to scope clarification before considering a different transport. +- The final schema-v2 serialization must be validated against real workflow snapshots and may expose migration details not resolved by research. + +Generated: `2026-07-13T18:00:05Z` + +## Assumptions Confirmed from Research + +1. The canonical editable runtime lives under `plugins/maister/`; Codex-specific transport belongs under `platforms/codex-cli/`. +2. Generated plugin variants are build outputs and will only be changed through `make build`. +3. The shared evaluator owns the complete pending-to-terminal decision record and exactly-one-logical-arbiter behavior. +4. The runner verifies and projects a persisted terminal decision; it does not choose an option or dispatch domain work. +5. Each workflow owns stable work-item inventory and routing; shared helpers may validate IDs, outbox entries, and receipts. +6. Logical exactly-once is achieved through deterministic `dispatch_id` values and receiver deduplication, while physical retries remain possible. +7. Unsupported capability, denylist, low confidence, escalation, retry exhaustion, or persistence failure remain fail-closed. + +## Clarification Status + +`clarifications_resolved: true` for Phase 1. Remaining unknowns are implementation discoveries covered by the planned spike and verification gates, not missing product or scope decisions. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/codebase-analysis.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/codebase-analysis.md new file mode 100644 index 00000000..116b7acc --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/codebase-analysis.md @@ -0,0 +1,258 @@ +# Codebase Analysis: Codex Fully Automatic Continuation + +## TL;DR + +The repository specifies the intended Advisor/Arbiter behavior, but does not execute it: there is no shared evaluator and no Codex active-turn binding. +`phase-continue.mjs` is a sound starting point for commit/report/phase-transition behavior, but it accepts a narrow selected-result payload, synthesizes incomplete history, and exits without routing or dispatching the next work item. +Research and product-design expose the same-phase failure most clearly; all five orchestrators also contain user-question-only phase-entry guards that reject a valid automatic gate record. +The accepted repair is A3/B1/C1/D1: shared executable evaluator, evaluator-owned full decision record, workflow-owned durable inventory/outbox/receipt, and a thin host-native Codex binding. +Overall complexity and risk are **high** because the change crosses state schema, crash recovery, multiple workflow call sites, generated variants, and capability evidence. + +## Key Decisions + +- Keep four boundaries distinct: the evaluator selects, the runner persists and projects, the workflow loop routes, and the Codex binding preserves the active turn. +- Make the evaluator, not the runner, own the complete pending-to-terminal gate envelope and exactly-one-logical-arbiter semantics. +- Use `orchestrator.current_phase` as the only mutable phase cursor; migrate away from the competing `started_phase` meaning. +- Give sequential workflow work items stable IDs and durable dispatch receipts; runner stdout or a phase status change alone is not continuation proof. +- Edit only canonical files under `plugins/maister/` and host adapters under `platforms/`; regenerate committed platform variants through `make build`. +- Keep Codex `fully_automatic` capability `unsupported` until a real host-native E2E exits 0 and proves agreement, disagreement, same-phase and next-phase continuation, no UI, resume, and deduplication. + +## Open Questions / Risks + +- The exact Codex host-native active-turn hook and injectable role-invocation seam still require a narrow implementation spike; current packaging exposes no executable binding. +- Schema-v2 migration must handle real, richer `gate_history` snapshots without losing provenance and must fail closed on ambiguous state. +- Exactly-once can only mean one logical effect: physical dispatch may retry after interruption and therefore needs a stable `dispatch_id` plus receiver deduplication. +- The proposed repository becomes a shared writer boundary; locking, revision/CAS, atomic replacement, mode preservation, and directory durability must be correct across macOS/Linux. +- Product-design backward refinement is not part of this repair and must not weaken the runner's forward-only transition rule. + +Generated: `2026-07-13T17:56:39Z` + +## 1. Scope and Current-State Conclusion + +This report distinguishes **current repository facts** from **accepted research recommendations**. + +Current fact: Maister already has detailed prose describing exact four-field role responses, agreement, one logical arbiter, retry, idempotency, persistence ordering, and automatic continuation. The normative contract is in `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md:1-565` and is repeated in `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:97-135`. There is no executable `evaluate_gate` implementation corresponding to that prose. + +Current fact: the only executable continuation component is `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs`. It validates a transport payload (`:209-244`), parses a narrow gate-history/state schema (`:502-561`), validates forward transitions (`:564-588`), writes temporary files and renames them (`:597-617`), appends a gate record (`:642-659`), updates phase state textually (`:661-700`), writes reports, emits JSON, and exits (`:741-800`). It does not invoke Advisor/Arbiter roles, apply a domain choice, advance a same-phase cursor, or dispatch a phase body. + +Accepted recommendation: implement the A3/B1/C1/D1 architecture documented in the research artifacts under `analysis/research-context/`. Research informs the repair but does not prove that any recommended runtime exists today. + +## 2. Ranked File Map + +### Primary files + +1. `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` + - Defines the desired gate context, role-response allowlist, agreement/arbitration logic, retry/resume behavior, persistence order, host continuation primitive, and hard denylist. + - Current limitation: it is documentation only. `tests/gate-decision-engine.test.sh` checks phrases and fixture labels rather than executing a state machine. + +2. `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` + - The present executable commit boundary. + - `validatePayload` (`:209-244`) enforces exact JSON transport. + - State/history parsing (`:502-561`) expects the current narrow schema. + - Transition validation (`:564-588`) requires `current_phase` and forward movement. + - `atomicWrite` (`:597-617`) stages and renames output, but there is no shared lock, revision/CAS, explicit directory `fsync`, or complete mode-preservation contract. + - `appendGateHistory` and `updatePhaseState` (`:642-700`) perform textual YAML insertion/replacement. + - `main` (`:741-800`) synthesizes `original_recommendation` from `selected_option` and a generic rationale at `:775-776`, then prints JSON and terminates. + +3. `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` + - Defines shared orchestration state and gate rules. + - Current mismatch: the state template still uses `started_phase` at `:280`, while the runner requires `orchestrator.current_phase` for transitions (`phase-continue.mjs:555-569`). This is a split-brain risk. + - Its fully automatic prose at `:120-135` is the intended behavior that should become executable. + +4. `plugins/maister/skills/research/SKILL.md` + - Best reproduction of broken same-phase continuation. + - Phase 4 requires decision areas sequentially because later choices may depend on earlier ones (`:329-349`), but the instruction remains “If user picks → record choice, move to next area” (`:349`). There is no stable work-item ID, durable cursor, outbox, receipt, or dispatcher. + - Phase-entry checks require an `AskUserQuestion` call ID (`:265-269`, `:367-371`, `:416-420`), which rejects a valid terminal automatic gate record. + +5. `platforms/codex-cli/templates/advisor.toml` + - Correctly constrains the Advisor to a read-only, exact four-field YAML result (`:1-18`). + - Current limitation: statements about a “Codex host adapter” and `phase_continue(selected_option)` are declarative instructions; no corresponding executable adapter is installed. + +6. `platforms/codex-cli/build.sh` + - Copies canonical skills and transforms Markdown (`:135-175`) and validates the capability-matrix entry (`:315-331`). + - Current limitation: it does not build or copy a Codex-only evaluator/runner/active-turn binding beyond inherited shared skill files. + +7. `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` + - Current fact: it always prints that no deterministic Codex adapter harness exists and exits `77` (`:1-5`). This is the authoritative reason capability remains unsupported. + +8. `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` + - Correctly declares Codex `unsupported` and points to the native E2E target (`:14-16`). + - Must remain unchanged until host-native evidence succeeds. + +### Related consumers and infrastructure + +- `plugins/maister/skills/development/SKILL.md`: many gate call sites, repeated runner transport contract, scope-decision sequencing, and user-question-only phase-entry guards (`:102-168` and subsequent phase entries). +- `plugins/maister/skills/product-design/SKILL.md`: sequential decision areas and backward-refinement concerns; uses the same prose engine and user-question entry checks (`:79-100`, `:415`, `:459`, `:511-543`). +- `plugins/maister/skills/migration/SKILL.md`: duplicates engine/adapter prose and entry checks (`:66-90`, `:212` onward). +- `plugins/maister/skills/performance/SKILL.md`: duplicates engine/adapter prose and entry checks (`:67-90`, `:220` onward). +- `plugins/maister/skills/research/SKILL.md`: sequential convergence needs a durable work inventory, not only a phase transition. +- `tests/phase-continue-contract.test.sh`: strongest current executable runner specification. +- `tests/fully-automatic-phase-continue.test.sh`: concise happy-path phase mutation, idempotent reuse, and denylist test, but not an evaluator or dispatcher test. +- `tests/gate-decision-engine.test.sh` and `plugins/maister/skills/orchestrator-framework/references/gate-decision-fixtures.yml`: prose/catalog conformance only. +- `tests/advisor-config-reconciliation.test.sh`, `tests/advisor-init-lifecycle.test.sh`, and `tests/advisor-workflow-snapshot.test.sh`: transactional and snapshot precedents. +- `plugins/maister/skills/init/bin/reconcile-advisor-config.sh`: strongest same-directory staging, validation, permission/no-op preservation, backup/restore, rollback, and failure-injection precedent (`:37-38`, `:222-257`, `:330-346`, `:414-438`). +- `Makefile:1-62`: executes source/generated runner matrices and host capability validation; `:50` explicitly rejects shared runner tests as host-native evidence. +- `platforms/codex-cli/smoke-cli.sh:66-89`: validates files and phrases, not runtime continuation. + +## 3. Execution and Data Flow + +### Current execution flow + +```text +workflow gate call site + -> Markdown instruction to evaluate the gate + -> read-only advisor.toml prompt profile + -> [missing executable evaluator and role-invocation adapter] + -> phase-continue.mjs, if explicitly invoked + -> validate narrow JSON/state + -> append synthesized terminal gate record + -> generate reports + -> optionally mutate current_phase/phases[] + -> print compact JSON and exit + -> [missing apply-choice, cursor/outbox, dispatch, active-turn continuation] +``` + +The immediate failure is therefore not option selection alone. Even when the runner exits 0, no consumer turns that result into “apply the selected approach, persist the next target, and start it now.” For a same-phase decision area, `next_phase` is inapplicable and self-transition is rejected. For a next-phase gate, the runner can mutate state but cannot execute the target phase body. + +### Accepted target flow + +```text +workflow call site + -> shared evaluator + -> persist advisor_pending and attempts + -> invoke read-only Advisor + -> agreement: terminal actor=advisor + -> disagreement: one logical Arbiter, retries inside that record + -> persist complete terminal envelope + -> phase-continue runner + -> verify terminal envelope and idempotency + -> project reports + -> optionally commit forward phase transition + -> thin Codex binding returns continue|user_gate|blocked + -> workflow loop + -> apply selection + -> persist next work item/phase-entry outbox with dispatch_id + -> dispatch and record checkpoint/receipt + -> continue in the same active turn +``` + +The runner remains deliberately domain-agnostic. Same-phase inventory belongs to the workflow; host-native role/turn mechanics belong to the Codex binding. + +## 4. Important Functions and Responsibilities + +| Current function/area | Current responsibility | Gap relevant to this repair | +|---|---|---| +| `validatePayload`, `phase-continue.mjs:209-244` | Exact input keys/types and transport shape | Accepts a preselected result rather than a full persisted evaluator record | +| history/state validators, `:502-561` | Narrow canonical-state preflight | Reject or cannot preserve richer real gate histories and provenance | +| transition validation, `:564-588` | Forward phase transition invariants | Correctly does not solve same-phase routing or phase-body dispatch | +| `atomicWrite`, `:597-617` | Same-directory temp write and rename | Needs shared locking, revision/CAS, mode and directory-durability guarantees | +| `appendGateHistory`, `:642-659` | Append synthesized gate YAML | B1 requires update-in-place pending-to-terminal ownership by evaluator | +| `updatePhaseState`, `:661-700` | Textual phase/current-phase update | Should use the shared versioned state repository and schema invariants | +| `main`, `:741-800` | Validate, persist, report, transition, emit JSON | Stops at runner outcome; no workflow cursor or dispatch consumer | +| `evaluate_gate` prose | Specifies policy and result state machine | Must become a small executable evaluator with injected `roleInvoker` | + +## 5. Tests and Coverage Assessment + +### Existing strengths + +- `tests/phase-continue-contract.test.sh` verifies exact stdin/`--input-file` transport, JSON-only stdout, schema rejection, denylist handling, transition invariants, immutable terminal reuse, report recovery, and rejection without mutation. It is the primary template for extending the runner contract. +- `tests/fully-automatic-phase-continue.test.sh:1-63` demonstrates a selected Advisor result can transition `phase-1` to `phase-2`, reuse the decision idempotently, and reject automatic implementation approval. +- Advisor configuration tests use byte comparisons, permission checks, rollback injection, and topology assertions. They align with `.maister/docs/standards/testing/test-writing.md` and should be reused for state-repository rejection tests. +- `Makefile:50` and the capability matrix correctly distinguish shared/integration tests from real host-native evidence. + +### Critical missing coverage + +1. Executable evaluator tests with role call logs and exact counts: + - agreement: Advisor 1, Arbiter 0, user UI 0; + - disagreement: Advisor 1 and exactly one logical Arbiter, including Arbiter retry/resume; + - invalid schema/option, low confidence, escalation, exhaustion, denylist, and pending-state resume. +2. Full-record runner consumption and versioned migration tests using realistic workflow state rather than narrow synthetic history. +3. State-repository concurrency and transaction tests: lock timeout, stale revision/CAS, crash windows, byte/mode/topology preservation, and no partial report/state transition. +4. Workflow-loop tests for two dependent same-phase items and a next-phase entry checkpoint, including deterministic `dispatch_id` deduplication. +5. Codex adapter integration with fake role invoker, fake dispatcher, and a UI spy that fails if successful `fully_automatic` execution presents a question. +6. Deterministic build/projection tests proving the binding reaches `plugins/maister-codex/` from canonical/adapter sources. +7. Real Codex host-native E2E covering agreement, arbitration, same-phase, next-phase, resume, dedupe, and no UI. Only this test may justify the capability flip. + +## 6. Reusable Patterns and Constraints + +### Patterns to reuse + +- **Strict CLI boundary:** copy the runner's duplicate-key-safe JSON parsing, exact allowlists, canonical YAML rejection, deterministic gate-key hashing, stderr diagnostics, and JSON-only stdout behavior. +- **Transactional file update:** follow `reconcile-advisor-config.sh` for same-directory staging, complete validation before replacement, no-op preservation, mode preservation, backup/restore, and injectable failures. +- **State-local bounded lock:** the repository has an atomic `mkdir` lock precedent in `platforms/kiro-cli/build.sh`; use a task/state-local lock rather than global temporary state. +- **Canonical/generated ownership:** shared runtime belongs under `plugins/maister/skills/orchestrator-framework/`; Codex-only binding belongs under `platforms/codex-cli/`; generated trees must come from `make build`. +- **Risk-based transactional assertions:** rejected inputs and injected failures must preserve bytes, modes, and directory topology, not merely return nonzero. + +### Anti-patterns to avoid + +- Do not turn `phase-continue.mjs` into the evaluator or domain dispatcher. +- Do not add Codex-only gate-policy semantics; policy must remain shared. +- Do not manipulate rich state through ad hoc textual YAML splicing. +- Do not treat runner stdout, report generation, or `current_phase` mutation as evidence that the next work actually started. +- Do not introduce a daemon, MCP service, event store, or generalized persistence abstraction without evidence that the thin host-native binding cannot work. +- Do not edit `plugins/maister-codex/`, `plugins/maister-cursor/`, or `plugins/maister-kiro/` directly. +- Do not mark Codex supported based on smoke tests, fake-port integration, or shared runner tests. + +## 7. Complexity and Risk + +**Complexity: high.** The implementation is small in conceptual modules but wide in integration surface: + +- JavaScript ESM runtime and shell tests; +- a versioned YAML state contract and migration; +- concurrent sequential writers across evaluator and runner; +- five canonical workflow consumers; +- Codex adapter/build projection; +- source plus three generated runner matrices; +- crash recovery and exact non-mutation requirements. + +**Risk level: high.** A false success can silently bypass a user gate, lose decision provenance, double-dispatch work, strand a phase after state mutation, or advertise a capability the host cannot execute. Fail-closed behavior and host-native evidence are release conditions, not optional hardening. + +Likely task characteristics for downstream planning: + +- `has_reproducible_defect: true` +- `modifies_existing_code: true` +- `creates_new_entities: true` (small runtime/helper modules and fixtures) +- `involves_data_operations: true` (versioned YAML state, reports, receipts) +- `ui_heavy: false` + +## 8. Impact Analysis + +### Direct impact + +- Shared orchestration state and gate semantics under `plugins/maister/skills/orchestrator-framework/`. +- All canonical gate-consuming orchestrators: development, research, product-design, migration, and performance. +- Codex packaging and runtime behavior under `platforms/codex-cli/`. +- Contract, integration, build, and capability test matrices. + +### Generated impact + +`make build` will project shared framework changes into Codex, Cursor, and Kiro variants. Host-specific Codex binding files need an explicit adapter copy rule. Generated diffs are expected consequences, not edit targets. + +### Compatibility impact + +- Existing real state may contain `started_phase`, narrow or rich histories, and no schema version/revision. Migration must be explicit and fail closed. +- Manual, denylisted, low-confidence, escalation, exhaustion, and unsupported-host paths must retain user-gate/blocked behavior. +- Phase-entry checks must accept either an actual user-question call proof or a persisted terminal automatic record with matching continuation receipt; simply deleting the checks would weaken safety. + +## 9. Implementation Recommendations + +1. Define schema v2 and executable fixtures first: full gate envelope, `current_phase`, `revision`, work inventory, continuation target, dispatch outbox, and receipt/checkpoint. +2. Add a narrowly scoped shared `state-repository.mjs` used directly by evaluator and runner: bounded state-local lock, validate-under-lock, expected-revision CAS, same-directory temp/`fsync`/rename, directory `fsync`, and mode preservation. +3. Add `gate-evaluate.mjs` plus a small core with an injected read-only role invoker. Enforce exact four-key responses, agreement short-circuit, one logical Arbiter, retries within one role record, and resume without re-invoking completed roles. +4. Change `phase-continue.mjs` to verify and reuse the evaluator-owned terminal record. Keep report generation and optional forward phase transition; remove synthesized provenance. +5. Implement one tracer-bullet workflow loop, preferably research Phase 4: two stable dependent work items, applied choice, deterministic outbox/receipt, and same-turn next dispatch. +6. Add a thin Codex binding that maps host-native role calls and evaluator/runner outcomes to `continue | user_gate | blocked`; on `continue`, return control to the workflow loop without ending the turn. +7. Migrate phase-entry guards and gate consumers across research, product-design, development, migration, and performance. +8. Extend Codex build/smoke/integration coverage, then run `make build` and the complete validation matrix. +9. Replace the Codex E2E skip only when the real entrypoint is observable. Flip `host-capabilities.yml` to supported only after that target exits 0. + +These recommendations implement the accepted research architecture; they are not descriptions of code currently present. + +## 10. Next Steps for Specification and Planning + +- Specify the schema-v2 envelope, migration rules, repository invariants, and crash windows before assigning implementation groups. +- Make the TDD red gate reproduce both visible failure modes: agreement still requires interaction/stops, and disagreement cannot prove exactly one logical Arbiter plus automatic next dispatch. +- Split implementation into tracer bullets with explicit dependencies: schema/repository, evaluator, runner consumption, workflow loop, Codex binding, call-site migration, build projection, and host-native proof. +- Require every group that mutates state to include byte/mode/topology rejection tests. +- Preserve unrelated dirty work and review generated diffs separately from canonical edits. +- Keep capability activation as the final evidence-gated step, not part of initial runtime implementation. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/gap-analysis.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/gap-analysis.md new file mode 100644 index 00000000..2ebb2c52 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/gap-analysis.md @@ -0,0 +1,345 @@ +# Gap Analysis: Fix Codex Fully Automatic Continuation + +## TL;DR + +The current repository can validate and persist a preselected gate result, but it cannot execute the complete `fully_automatic` path or start the next work item. +The deterministic reproduction is split: shared prose/runner contracts pass, while the only Codex-native capability test exits `77` because no executable adapter harness exists. +The accepted A3/B1/C1/D1 design closes the missing evaluator, full-record persistence, workflow routing, durable dispatch, and active-turn binding gaps without weakening protected gates. +Risk and effort are high because the repair changes authoritative YAML state, five workflow consumers, the shared runner, Codex packaging, generated variants, and capability evidence. + +## Key Decisions + +- Implement A3/B1/C1/D1 exactly as accepted in the research decision log: shared executable evaluator, evaluator-owned full gate record, workflow-owned durable inventory/outbox/receipt, and thin Codex binding. +- Keep the evaluator, continuation runner, workflow loop, and Codex active-turn binding as separate boundaries; runner success is not proof of dispatch. +- Use `orchestrator.current_phase` as the only mutable phase cursor and introduce versioned, fail-closed migration plus revision/CAS protection. +- Preserve all manual, denylisted, low-confidence, escalation, exhaustion, unsupported-host, and persistence-failure paths as fail-closed. +- Keep Codex `fully_automatic` declared `unsupported` until the real host-native E2E exits `0`; shared tests and fake-port integration are not capability evidence. + +## Open Questions / Risks + +- The exact Codex active-turn/headless hook remains an implementation spike inside the accepted D1 boundary. If the spike disproves D1, implementation must stop and return to scope clarification before adopting the researched D2 MCP fallback. +- Real legacy `orchestrator-state.yml` files may contain `started_phase`, no revision, and richer or poorer gate-history records than the current runner accepts; ambiguous migrations must fail closed without mutation. +- Logical exactly-once requires receiver deduplication by stable `dispatch_id`; a physical dispatch may be retried after an interruption. +- Evaluator and runner become sequential writers to one YAML snapshot, so a shared lock, validation under lock, expected-revision CAS, atomic replacement, mode preservation, and directory durability are correctness requirements. + +## Summary + +- **Risk Level**: High +- **Estimated Effort**: High +- **Detected Characteristics**: Reproducible defect, modifies existing code, creates new runtime/state entities, authoritative state/data operations, not UI-heavy +- **Change Type**: Modificative, with additive runtime modules and fixtures +- **Compatibility Requirement**: Strict +- **Architectural Impact**: High +- **Scope Expansion Recommended**: No. The research-approved scope already includes every material gap found here. + +The implementation must change behavior from “persist a selected result and exit” to “evaluate, persist full provenance, apply the selection, durably route, and start the next target in the same active turn.” This is aligned with the project vision and roadmap priorities for auditable Advisor/Arbiter automation, runtime continuation coverage, and host parity. + +## Task Characteristics + +- Has reproducible defect: **yes** +- Modifies existing code: **yes** +- Creates new entities: **yes** — executable evaluator/repository/binding modules, versioned gate envelopes, work items, dispatch outbox entries, and receipts do not exist today +- Involves data operations: **yes** — the task changes creation, validation, transition, recovery, and concurrent persistence of authoritative YAML workflow state +- UI heavy: **no** — dashboards/reports remain derived projections; no page, form, route, component, or styling work is required + +## Current State vs Desired State + +| Concern | Current state | Desired state | Gap | +|---|---|---|---| +| Gate selection | Agreement/arbitration is normative Markdown only in `gate-decision-engine.md` | Executable evaluator with injected read-only role invoker | No runtime state machine or deterministic role-call accounting | +| Agreement | Runner accepts an already selected option | Original/advisor agreement terminates with `final_actor: advisor` | No component compares recommendations before commit | +| Disagreement | Prose says to arbitrate | One logical Arbiter record; retries append attempts to that record | No executable exactly-one-logical-arbiter behavior | +| Gate provenance | `phase-continue.mjs` synthesizes `original_recommendation` from `selected_option` and a generic rationale | Evaluator owns the full pending-to-terminal record | Provenance, role responses, models, attempts, and real rationale are lost | +| State cursor | Shared state template uses `started_phase`; runner optionally reads `current_phase` | Versioned state with one canonical `current_phase` | Competing phase meanings and incomplete invariants | +| State writes | Temp file, file `fsync`, and rename exist per write | Shared lock, validate-under-lock, revision/CAS, mode preservation, directory durability | Atomic single write does not prevent lost updates across writers | +| Same-phase continuation | Research/product-design prose says “move to next area” after a user choice | Stable work-item inventory, applied choice, outbox, dispatch, checkpoint, receipt | No cursor, target identity, dispatch consumer, or resume proof | +| Next-phase continuation | Runner can mark source completed and target in progress | Target phase body starts and records an observable checkpoint | State transition is not phase execution | +| Phase-entry proof | Canonical workflows require an `AskUserQuestion` call ID | Accept either explicit user-gate proof or matching terminal auto record plus continuation receipt | Valid automatic decisions are rejected by entry guards | +| Codex binding | Read-only `advisor.toml` describes behavior; build copies/transforms skills | Thin native binding returns `continue | user_gate | blocked` to the active workflow loop | No executable active-turn adapter or native role/dispatcher seam | +| Capability evidence | Codex native E2E exits `77`; capability is correctly unsupported | Real Codex E2E exits `0` and observes agreement, arbitration, same/next phase, no UI, resume, dedupe | No host-native proof; capability must not flip early | + +## Gaps Identified + +### Missing Features + +- **Executable gate evaluator**: No runtime under `plugins/maister/skills/orchestrator-framework/bin/` executes policy, denylist, pending states, role calls, output validation, retries, agreement, arbitration, or resume. +- **Shared state repository**: No common writer provides task-local locking, revision/CAS, schema-v2 invariants, mode preservation, or durable directory replacement for evaluator and runner. +- **Workflow work inventory and dispatch protocol**: No stable `work_item_id`, deterministic `dispatch_id`, outbox, receiver deduplication, checkpoint, or acknowledgement exists for same-phase or phase-entry continuation. +- **Codex host-native binding**: `platforms/codex-cli/build.sh` copies and transforms shared skills, but does not package an executable adapter that connects native role invocation, evaluator, runner, and the current active turn. +- **Host-native capability test**: `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` contains only an unavailable message and `exit 77`. +- **Schema-v2 migration**: There is no fail-closed migration from `started_phase`/narrow history to `current_phase`/revision/full envelope. + +### Incomplete Features + +- **Continuation runner**: `phase-continue.mjs` has strong exact-input validation, canonical-state checks, deterministic gate keys, report recovery, forward transition guards, and failure injection, but it chooses neither Advisor nor Arbiter and exits after JSON stdout. +- **Terminal history**: The runner appends a schema-v1 terminal record and can reuse it, but it creates rather than verifies the evaluator-owned full record required by B1. +- **Atomic persistence**: `atomicWrite` performs same-directory staging, file `fsync`, and rename, but creates target directories, does not share a lock, has no expected revision, does not preserve an existing file mode explicitly, and does not `fsync` the containing directory. +- **Workflow call sites**: Development, research, product-design, migration, and performance all describe the shared runner contract, but none consumes a successful automatic result through a durable workflow loop. +- **Tests**: `tests/gate-decision-engine.test.sh` passes 28 prose/structure checks and current runner tests cover selection persistence, forward transition, recovery, and denylist behavior. They do not execute the evaluator, count role calls, prove no UI, dispatch a next target, or exercise a real Codex entrypoint. + +### Behavioral Changes Needed + +- Change agreement from a possible user-facing stop to an automatic terminal Advisor decision with zero Arbiter and zero user-gate calls. +- Change disagreement from prose-only arbitration to one logical Arbiter whose retries remain within one durable record and never loop back to Advisor. +- Change runner input from “trust this selected result and synthesize provenance” to “verify this already persisted terminal evaluator record and commit projections/transition.” +- Change successful continuation from stdout/phase mutation to a durable target dispatch followed by an observable same-turn checkpoint. +- Change phase-entry guards to accept persisted automatic evidence without weakening explicit-user requirements for protected gates. +- Change capability only after host-native evidence, not as part of source implementation or fake-port integration. + +## Defect Analysis + +### Reproduction Data + +**Inputs** + +- A safe, non-denylisted gate configured as `fully_automatic`. +- Ordered options and an original recommendation. +- Either an Advisor response agreeing with the original recommendation or a differing valid recommendation requiring arbitration. +- A subsequent same-phase work item or forward phase target. + +**Steps and observed evidence** + +1. Run `bash tests/gate-decision-engine.test.sh`. +2. Observe all 28 checks pass; these checks validate prose, fixture labels, runner references, and generated structure rather than native active-turn behavior. +3. Run `bash platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh`. +4. Observe `UNAVAILABLE: no deterministic Codex adapter harness executes and observes native continuation` and exit code `77`. +5. Inspect `phase-continue.mjs`: `main()` validates a preselected payload, appends/synthesizes a terminal record, writes reports, optionally updates `current_phase`, prints compact JSON, and returns. There is no role invoker, selection application, next-item router, dispatcher, or receiver acknowledgement. + +**Expected** + +- Agreement: Advisor called once, Arbiter never called, user gate never shown, full terminal record persisted, next target started in the same active turn. +- Disagreement: Advisor called once, exactly one logical Arbiter created, legal Arbiter result persisted, user gate never shown on a safe confident path, next target started in the same active turn. +- Resume: no duplicate terminal history, logical Arbiter, applied choice, or logical dispatch. + +**Actual** + +- The repository has no executable Codex path that can perform and observe that sequence. Shared runner success ends at JSON output or phase-state mutation; the native capability test is unavailable and capability remains unsupported. + +### Root Cause Hypothesis + +The root cause is a missing executable ownership chain between normative gate policy and host workflow execution. Decision semantics exist primarily as Markdown; `phase-continue.mjs` begins too late, after an option has already been selected, and ends too early, before workflow routing and dispatch. Codex has a read-only role profile but no active-turn binding that supplies role calls to a shared evaluator and returns successful continuation to a durable workflow loop. + +### Regression Risk Areas + +- Hard denylist and explicit user ownership of implementation approval, final handoff, rollback, production, and other protected gates. +- Manual and `advisor` policies, including user overrides and interactive fallback. +- Pending-state resume, retry budgets, exponential-backoff metadata, and exactly-one logical Arbiter semantics. +- Terminal record immutability, idempotency-key reuse, report regeneration, and changed-selection rejection. +- State schema migration, phase invariants, lock/CAS conflicts, permissions, directory topology, and crash windows. +- Same-phase dependent decision areas in research and product-design. +- Scope decisions and phase exits in development, migration, and performance. +- Generated Cursor, Kiro, and Codex variants and reproducible second builds. +- Capability projection rules that distinguish exit `0`, exit `77`, and failure. + +## Change and Compatibility Classification + +### Change Type + +**Modificative**. The task changes existing gate, persistence, continuation, workflow-entry, and Codex packaging behavior. It also adds narrowly scoped runtime modules and state entities, but these additions serve the modification rather than define an independent product feature. + +### Compatibility Requirements + +**Strict**: + +- Existing manual and Advisor-assisted workflows must retain their behavior. +- Denylisted gates must never call Advisor, Arbiter, automatic runner, or dispatcher. +- Existing supported runner recovery properties must remain: deterministic idempotency, immutable terminal selection, report regeneration, and exactly-once forward transition. +- Existing state must either migrate deterministically to schema v2 or fail before mutation with actionable diagnostics. +- Canonical edits must remain under `plugins/maister/` and Codex-specific edits under `platforms/codex-cli/`; generated variants may change only through `make build`. +- Codex capability must remain unsupported until the prescribed real native E2E succeeds. + +## User Journey Impact Assessment + +The affected “user journey” is the workflow operator's passage through configurable orchestration gates rather than a graphical UI. + +| Dimension | Current | After | Assessment | +|---|---|---|---| +| Reachability | The same workflow commands and phases are reachable | Entry points remain unchanged | Neutral (`0`) | +| Discoverability/observability | `fully_automatic` is configured but cannot be experienced as a complete Codex flow; capability is unsupported | Durable audit, dashboard projection, target checkpoint, and explicit capability evidence make behavior observable | Improves from 2/10 to 9/10 | +| Flow integration | Safe auto gates fall back, stop, or end after persistence/transition | Safe agreement/arbitration continues directly to the next target in the same turn | Positive | +| Protected decisions | Explicit user control is preserved by prose and denylist | Explicit user control is rechecked by executable evaluator and runner | No negative impact | +| Resume | Terminal selection can be reused by runner, but next work is ambiguous | Decision, applied choice, target, dispatch, and acknowledgement are independently resumable | Strong improvement | + +## State and Data Lifecycle Analysis + +### Entity: Gate Decision Envelope + +| Lifecycle operation | Current evidence | Desired behavior | Status | +|---|---|---|---| +| CREATE pending | Described in Markdown only | Persist `advisor_pending`/`arbiter_pending` and attempts before role calls | Missing | +| READ/reuse | Runner validates narrow schema-v1 history and reuses terminal keys | Shared schema-v2 read and invariant validation | Partial | +| UPDATE pending to terminal | Runner appends a new terminal record | Evaluator updates one record in place with complete provenance | Missing | +| RECOVER | Runner recovers report/transition from a terminal record | Resume exact role/attempt without reinvoking completed roles | Partial | +| REJECT invalid mutation | Runner contract asserts many byte-exact rejection cases | Extend to repository, migration, evaluator, and outbox failures including modes/topology | Partial | + +### Entity: Workflow Continuation/Dispatch + +| Lifecycle operation | Current evidence | Desired behavior | Status | +|---|---|---|---| +| CREATE intent | Runner writes scalar `continuation: phase_continue` | Persist typed target with source gate, `work_item_id`, and deterministic `dispatch_id` | Incomplete | +| READ target | No workflow loop consumes the scalar as a durable target | Workflow rereads canonical state and resolves the exact next target | Missing | +| UPDATE status | Optional phase statuses change | `pending → dispatched/in_progress → acknowledged/completed|blocked` | Missing | +| DEDUPLICATE | Gate-key and transition reuse exist | Receiver deduplicates logical effect by `dispatch_id` | Missing | +| RECOVER | Report and phase transition can recover | Retry the same dispatch and record the same acknowledgement/checkpoint | Missing | + +- **Completeness score**: 35% +- **Orphaned operations**: + - A continuation marker can be created without any executable consumer or acknowledgement. + - A phase can be marked `in_progress` without evidence that its body started. + - A same-phase selection can be terminal without a stable next-item cursor or dispatch receipt. +- **Missing touchpoints**: + - Shared evaluator/repository boundary. + - Workflow apply-selection and target-materialization boundary. + - Codex active-turn dispatcher/receiver boundary. + - Schema migration and realistic legacy-state fixtures. + +These lifecycle gaps would normally force scope-expansion decisions. Here they do not create new `decisions_needed` entries because ADR-001 through ADR-008 already explicitly accepted their inclusion and Phase 1 clarifications confirmed that scope. Removing any of them would contradict the binding research context. + +## Integration Points + +- `plugins/maister/skills/orchestrator-framework/bin/`: new evaluator and state repository; runner migrated to full-record verification. +- `plugins/maister/skills/orchestrator-framework/references/`: synchronized executable schema, gate algorithm, state template, fixtures, and capability wording. +- `plugins/maister/skills/research/SKILL.md`: first same-phase tracer bullet with stable dependent decision-area inventory. +- `plugins/maister/skills/product-design/SKILL.md`: shared forward continuation contract only; backward refinement remains out of scope. +- `plugins/maister/skills/development/SKILL.md`, `migration/SKILL.md`, and `performance/SKILL.md`: terminal result consumption, routing, and automatic phase-entry proof. +- `platforms/codex-cli/`: thin binding, role-invocation/dispatcher seam, build copy rules, smoke checks, integration test, and native E2E. +- `tests/`: evaluator, repository/runner, migration, workflow-loop, dispatch, adapter, build projection, and failure-injection coverage. +- `Makefile`: fast contract matrices plus preservation of host-native E2E as the only capability proof. +- Generated `plugins/maister-{codex,cursor,kiro}/`: build outputs only. + +## Patterns to Follow + +- Exact allowlists and JSON-only stdout/stderr separation from `phase-continue.mjs`. +- Deterministic idempotency key derived from phase, gate type, exact question, and ordered options. +- Same-directory staging, validation-before-replacement, no-op/mode preservation, rollback, and failure injection from `plugins/maister/skills/init/bin/reconcile-advisor-config.sh`. +- State-local atomic lock precedent from platform build tooling, extended with bounded timeout and revision/CAS. +- Behavior-focused shell tests and byte/mode/directory-topology assertions required by `.maister/docs/standards/testing/test-writing.md`. +- Canonical-source and deterministic generated-variant ownership from `.maister/docs/standards/global/build-pipeline.md`. +- Minimal direct modules with real callers; no daemon, generalized event store, speculative SDK, or MCP service unless the D1 spike is empirically disproven. +- Model outputs parsed strictly as four-field data; never interpolate them into shell commands or let roles mutate files. + +## Architectural Impact + +**High.** The accepted design introduces an executable state machine and a narrow shared persistence boundary, changes the authoritative YAML schema, and adds durable routing/dispatch semantics across five orchestrators. It preserves the existing system architecture—single canonical plugin plus deterministic adapters—and does not introduce a service, database, daemon, or frontend framework. + +The deepest seam is intentional: + +```text +workflow loop + -> shared evaluator -> read-only role port + state repository + -> continuation runner -> reports / optional forward transition + -> thin Codex binding -> continue | user_gate | blocked + -> workflow-owned target + dispatcher -> durable checkpoint/receipt +``` + +## Issues Requiring Decisions + +### Critical + +None. The research task and Phase 1 clarifications already settled all critical architecture and scope questions, including state lifecycle expansion and fail-closed safety behavior. + +### Important + +None at this stage. The Codex active-turn shape is an implementation spike within D1, not permission to choose another architecture. A negative spike result must return to scope clarification before D2 is considered. + +## Recommendations + +1. Start Phase 3 with failing executable tests for agreement, disagreement, and missing next-target dispatch; make call counts and no-UI behavior observable. +2. Define schema v2 and realistic migration fixtures before runtime changes, including rich histories and invalid/ambiguous legacy states. +3. Implement the narrow state repository and evaluator before changing the runner; make every rejected or injected-failure case prove byte/mode/topology preservation. +4. Convert the runner to verify the evaluator-owned terminal record and retain its proven report/transition recovery behavior. +5. Deliver one research Phase 4 tracer bullet with two dependent stable work items and dispatch acknowledgement before migrating all call sites. +6. Add the thin Codex binding and fake-port integration while capability remains unsupported. +7. Migrate the remaining workflow consumers and automatic phase-entry guards only after the tracer bullet passes. +8. Run `make build`, inspect generated diffs, run `make validate`, and verify a second clean build produces no diff. +9. Run the real Codex native E2E last; flip capability only when it exits `0` and observes agreement, one logical Arbiter, no UI, same-phase continuation, next-phase checkpoint, resume, and deduplication. + +## Risk Assessment + +- **Complexity Risk: High** — several small modules cross a large number of state, workflow, build, and generated-artifact contracts. +- **Integration Risk: High** — the exact Codex active-turn seam is unproven, and successful process exit must return control without ending the assistant turn. +- **Regression Risk: High** — a false positive could bypass user control, lose audit provenance, double-dispatch work, corrupt resume state, or advertise unsupported capability. +- **Data Integrity Risk: High** — two writers and schema migration introduce lost-update and partial-state hazards unless lock/CAS/atomic invariants are shared. +- **Platform Risk: Medium-High** — shared framework changes project into three generated variants, while only Codex receives the native binding. +- **Mitigation** — staged tracer bullet, strict schemas, executable call-count tests, failure injection, full build/validation, and evidence-gated capability activation. + +## Structured Result + +```yaml +status: success +report_path: .maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/gap-analysis.md +risk_level: high +effort_estimate: high +task_characteristics: + has_reproducible_defect: true + modifies_existing_code: true + creates_new_entities: true + involves_data_operations: true + ui_heavy: false +change_type: modificative +compatibility_requirements: strict +reproduction_data: + steps: + - Run bash tests/gate-decision-engine.test.sh and observe prose/structure contracts pass. + - Run bash platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh. + - Observe the unavailable diagnostic and exit code 77. + - Inspect phase-continue.mjs and observe it prints JSON and exits without role invocation or target dispatch. + inputs: + - Safe non-denylisted fully_automatic gate + - Ordered options and original recommendation + - Agreeing or disagreeing valid Advisor response + - Same-phase or forward-phase continuation target + expected: Agreement or one-logical-Arbiter resolution persists full provenance and starts the next target in the same active turn without UI. + actual: No executable Codex adapter/evaluator/workflow consumer performs that sequence; the native E2E exits 77. +regression_risk_areas: + - Hard denylist and protected user gates + - Manual and advisor policies + - Retry, arbitration, and pending-state resume + - Terminal idempotency and report/transition recovery + - Schema migration, concurrent state writes, modes, and crash windows + - Same-phase workflow inventories and phase-entry guards + - Generated platform parity and capability projection +root_cause_hypothesis: Gate policy is prose-only at selection time, the runner starts after selection and stops before routing, and Codex has no active-turn binding connecting those boundaries. +user_journey_impact: + reachability_change: "0" + discoverability_before: 2 + discoverability_after: 9 + flow_integration: positive +integration_points: + - Canonical orchestrator framework runtime and references + - Research, product-design, development, migration, and performance workflows + - Codex adapter, build projection, smoke checks, integration, and native E2E + - Shared contract, migration, workflow-loop, and failure-injection tests + - Makefile build, validation, and host capability matrix +patterns_to_follow: + - Strict runner input and canonical-state allowlists + - Atomic reconciliation and failure-injection precedents + - State-local lock plus revision/CAS + - Canonical-source/generated-output build discipline + - Behavior-focused byte/mode/topology-preserving tests + - Minimal modules with direct callers +architectural_impact: high +data_lifecycle_gaps: + orphaned_operations: + - Continuation marker without executable consumer or acknowledgement + - In-progress phase transition without target-body checkpoint + - Terminal same-phase choice without stable cursor or receipt + missing_touchpoints: + - Shared evaluator and repository + - Workflow apply-selection and target materialization + - Codex dispatcher/receiver active-turn binding + - Schema-v2 migration with realistic legacy fixtures + completeness_score: 35 +decisions_needed: + critical: [] + important: [] +scope_expansion_recommended: false +critical_issues: + - No executable agreement/arbitration evaluator + - No exactly-one-logical-Arbiter runtime behavior + - Runner synthesizes incomplete provenance from a preselected payload + - No durable same-phase cursor, outbox, dispatch receipt, or dedupe + - No Codex active-turn binding or successful native E2E + - No safe schema-v2 migration or shared lock/revision state repository +summary: The repair is a high-risk modificative change with a deterministically demonstrated native-runtime gap. The accepted A3/B1/C1/D1 architecture fully resolves scope, so implementation should proceed test-first without additional scope decisions while capability remains unsupported until real Codex evidence passes. +``` diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/requirements.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/requirements.md new file mode 100644 index 00000000..7669db9b --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/requirements.md @@ -0,0 +1,47 @@ +# Requirements + +## Initial description + +Repair Codex `fully_automatic` so agreement between the main recommendation and advisor selects automatically, disagreement invokes exactly one logical arbiter, and the terminal result automatically continues to the next problem without user interaction. + +## Confirmable assumptions + +### User journey + +Confirmed: the repair is transparent to Maister workflow users. They access it through existing `maister:*` workflows, with no new command or UI, and eligible automatic gates continue within the active Codex turn. + +### Existing code reuse + +Confirmed: extend the canonical orchestrator framework, shared state/continuation runtime, existing build projections, host capability matrix, and contract-test patterns. Keep Codex-specific code to a thin binding; do not create a separate Codex-only evaluator. + +### Visual assets + +Confirmed: there are no mockups, wireframes, screenshots, or other visual assets. Phase 4 was skipped because the task has no UI surface, and the specification contains no visual implementation requirements. + +## Q&A record + +- **User journey:** Confirmed transparent access through existing `maister:*` workflows, with no new command or UI and continuation inside the active Codex turn. +- **Existing code reuse:** Confirmed canonical shared framework/runtime, projections, capability matrix, and contract-test reuse with only a thin Codex binding. +- **Visual assets:** Confirmed none; no visual implementation requirements. + +## Functional requirements summary + +- Agreement terminates with actor `advisor`, zero arbiter calls, zero user gates, and automatic continuation. +- Disagreement creates one logical arbiter identity; bounded retries remain attempts of that same arbiter. +- Terminal provenance is persisted before reports, cursor changes, or dispatch. +- Same-phase and next-phase continuation use stable target and dispatch identifiers with durable acknowledgement and receiver deduplication. +- Invalid state, unsafe gates, unsupported capability, exhausted roles, or failed commits stop fail-closed without advancing work. +- Canonical state migration and all writers preserve transactional state integrity. +- Generated host variants remain projections of canonical sources. +- Capability status changes only after real Codex-native evidence succeeds. + +## Scope boundaries + +- No product-design backward refinement. +- No automation of protected or denylisted gates. +- No new user interface. +- No daemon, service, or database. + +## Technical considerations + +See [technical clarifications](technical-clarifications.md), [gap analysis](gap-analysis.md), and the imported [high-level design](research-context/high-level-design.md). diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/decision-log.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/decision-log.md new file mode 100644 index 00000000..e8a0cf32 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/decision-log.md @@ -0,0 +1,105 @@ +# Decision log: automatyczna kontynuacja Codex + +## TL;DR + +Przyjęto osiem decyzji architektonicznych tworzących jeden spójny łańcuch: shared evaluator → pełny terminal record → runner commit → workflow-owned durable dispatch → thin Codex binding. +Stan pozostaje pojedynczym YAML snapshotem, zabezpieczonym lockiem, revision/CAS i atomic rename; `current_phase` jest jedynym kursorem fazy. +Runner nie dispatchuje pracy, a capability Codex nie zmienia się na `supported` bez zielonego, rzeczywistego host-native E2E. + +## Key Decisions + +- A3, B1, C1 i D1 zostały zaakceptowane bez zmian. +- `current_phase` zastępuje mutowalne znaczenie `started_phase`. +- Wspólne state repository zapewnia lock + CAS dla evaluatora i runnera. +- Runner pozostaje commit boundary, a workflow loop pozostaje routing boundary. +- Capability flip jest zmianą opartą na dowodzie, nie na deklaracji lub fake-only teście. + +## Open Questions / Risks + +- Active-turn binding Codex wymaga spike'a; MCP jest fallbackiem tylko po negatywnym dowodzie D1. +- Schema v2 i migracja uboższych historii muszą być fail-closed oraz przetestowane realnymi snapshots. +- Idempotentny receiver jest konieczny, aby `dispatch_id` zapewniał jeden logiczny efekt mimo fizycznego retry. + +## Status summary + +| ADR | Decyzja | Status | +|---|---|---| +| ADR-001 | Shared executable gate evaluator (A3) | Accepted | +| ADR-002 | Evaluator-owned full gate record (B1) | Accepted | +| ADR-003 | Workflow-owned inventory i outbox/receipt (C1) | Accepted | +| ADR-004 | Thin host-native Codex binding (D1) | Accepted | +| ADR-005 | `current_phase` jako canonical cursor | Accepted | +| ADR-006 | Lock + revision/CAS state repository | Accepted | +| ADR-007 | Runner commituje, workflow dispatchuje | Accepted | +| ADR-008 | Evidence-gated Codex capability flip | Accepted | + +## ADR-001 — Shared executable gate evaluator (A3) + +**Status:** Accepted +**Context:** Normatywny Markdown opisuje agreement, arbitration, retry i resume, ale obecne testy nie wykonują tej state machine. Umieszczenie algorytmu wyłącznie w prose lub w adapterze Codex utrwaliłoby drift. +**Decision:** Dodać wspólny executable evaluator w canonical orchestrator framework. Evaluator posiada state machine i używa wstrzykiwanego read-only `role_invoker`; nie zna domenowego routingu ani hostowych efektów. +**Consequences:** Agreement, jeden logiczny arbiter, retry i resume są deterministycznie testowalne. Powstaje nowy, mały runtime component i wymagany jest stabilny port native delegation. +**Rejected alternatives:** A1 prose-only nie usuwa root cause; A2 monolityczny runner miesza domenę i host; A4 Codex-only tworzy drugą semantykę. + +## ADR-002 — Evaluator-owned full gate record (B1) + +**Status:** Accepted +**Context:** Runner dziś otrzymuje już wybraną opcję i rekonstruuje uboższy record, tracąc original recommendation, role responses, models i attempts. +**Decision:** Evaluator aktualizuje jeden pełny envelope od pending do terminalnego wyniku. Runner ponownie czyta state i weryfikuje idempotency key, selected option, actor, confidence oraz revision; nie dopisuje ani nie rekonstruuje provenance. +**Consequences:** Terminalna decyzja jest trwała przed raportem i continuation, a recovery nie ponawia modeli. Evaluator i runner są sekwencyjnymi writerami i muszą współdzielić repository. +**Rejected alternatives:** B2 robi z runnera RPC state service; B3 nie daje transakcji przez model call; B4 event log jest nieproporcjonalny. + +## ADR-003 — Workflow-owned inventory i durable outbox/receipt (C1) + +**Status:** Accepted +**Context:** Runner potrafi opcjonalnie zmienić fazę, ale nie zna kolejności decision areas i kończy proces po stdout. Sam indeks nie daje stabilnej identity ani recovery po dispatchu. +**Decision:** Każdy workflow z pętlą materializuje stabilne work itemy. Po decyzji zapisuje wybór, następny target i deterministyczny `dispatch_id`; dispatcher/receiver deduplikuje efekt i zapisuje trwały checkpoint/ack. +**Consequences:** Same-phase i next-phase continuation są obserwowalne i resumable. Exactly-once oznacza logiczny efekt; fizyczne wywołanie może być retry'owane. Workflowy muszą implementować własne inventory/routing na wspólnym envelope. +**Rejected alternatives:** C2 indeks jest niestabilny; C3 sprzęga runner z domeną; C4 ephemeral loop nie rozstrzyga crash window. + +## ADR-004 — Thin host-native Codex binding (D1) + +**Status:** Accepted +**Context:** Codex ma read-only profile ról, ale nie ma executable consumer łączącego role, evaluator, runner i aktywną pętlę. Lokalny service lub wrapper zwiększałby footprint i nie gwarantował utrzymania tury. +**Decision:** Binding w `platforms/codex-cli/` dostarcza native role port, uruchamia shared evaluator/runner, waliduje ich kontrakty i zwraca wyłącznie `continue | user_gate | blocked`. Nie implementuje policy ani domain routing. +**Consequences:** Shared core pozostaje portable, a Codex zachowuje native delegation. Exact active-turn hook wymaga krótkiego spike'a. MCP można rozważyć wyłącznie, jeśli spike empirycznie obali D1. +**Rejected alternatives:** D2 dodaje runtime service; D3 wrapper może nie reprezentować realnej sesji; D4 daemon nie kontynuuje tej samej tury. + +## ADR-005 — `current_phase` jako jedyny canonical phase cursor + +**Status:** Accepted +**Context:** Realny state używa `started_phase`, runner transition wymaga `current_phase`, a `phases[]` może być niespójne bez jawnego kursora. +**Decision:** Schema v2 używa `orchestrator.current_phase` jako jedynego mutowalnego kursora. `initial_phase` może zachować niemutowalną informację historyczną. `current_phase` musi wskazywać jedyną fazę `in_progress`. +**Consequences:** Resume i transition mają jedno źródło prawdy. Wymagana jest wersjonowana migracja realnych state files oraz aktualizacja wszystkich generatorów/call sites. +**Rejected alternatives:** Utrzymanie obu pól tworzy split-brain; wyprowadzanie wyłącznie z `phases[]` osłabia walidację uszkodzonego stanu. + +## ADR-006 — Lock + revision/CAS state repository + +**Status:** Accepted +**Context:** Evaluator zapisuje pending/terminal records, a runner później zapisuje projekcje/transition. Atomic rename pojedynczego writera nie chroni przed lost update między procesami. +**Decision:** Oba komponenty używają jednego małego repository: project-local exclusive lock, exact-schema/invariant validation, `expected_revision` CAS, temp file + fsync + atomic rename i zachowanie mode. Lock nie jest trzymany podczas model call ani host dispatchu. +**Consequences:** Konflikt powoduje reread i idempotency resolution, nie overwrite. Repository jest nowym wspólnym dependency, ale ma bezpośrednich callerów i wąski zakres zgodny z minimal implementation. +**Rejected alternatives:** Blind last-write-wins grozi utratą historii; jeden długi lock przez model/dispatch blokuje workflow i nadal nie tworzy transakcji zewnętrznej. + +## ADR-007 — Runner commituje; workflow dispatchuje + +**Status:** Accepted +**Context:** `phase-continue.mjs` ma dobre mechanizmy preflight, terminal persistence, reports i forward transition, ale nie zna domeny i nie utrzymuje hostowej tury. +**Decision:** Runner pozostaje deterministic commit boundary: weryfikuje terminal record, regeneruje raporty i może atomowo przełączyć fazę. Workflow loop jest routing boundary: stosuje wybór, materializuje target i dispatchuje go przez binding. +**Consequences:** Recovery raportu/transition pozostaje centralne, a shared runner nie absorbuje decision areas. Sukces runnera nie może być interpretowany jako wykonanie następnej pracy; wymagany jest receipt/checkpoint. +**Rejected alternatives:** Runner-dispatcher wymagałby domenowego payloadu i hostowego API, powtarzając odrzucony monolit A2/C3. + +## ADR-008 — Capability Codex zmienia się tylko na podstawie host-native evidence + +**Status:** Accepted +**Context:** Obecny Codex E2E zwraca `77`, a shared runner i smoke/prose tests nie dowodzą braku UI ani realnego następnego dispatchu. Przedwczesne `supported` uruchomiłoby automatyzację bez bezpiecznego transportu. +**Decision:** Capability pozostaje `unsupported` przez implementację i adapter integration. Flip na `supported` jest osobnym krokiem dopiero po exit `0` rzeczywistego Codex host-E2E obejmującego agreement, disagreement, same-phase, next-phase, no UI, resume i dedupe. Brak runtime nadal daje `77`, nie fake success. +**Consequences:** Rollout jest fail-closed i mierzalny. Implementacja może być gotowa przed aktywacją; manual/user gate fallback pozostaje dostępny. +**Rejected alternatives:** Flip po shared testach lub po obecności plików w generated pluginie myli deklarację z runtime proof. + +## Powiązania + +- [High-level design](high-level-design.md) +- [Research report](research-report.md) +- [Solution exploration](solution-exploration.md) +- `../analysis/synthesis.md` diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/high-level-design.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/high-level-design.md new file mode 100644 index 00000000..763f6433 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/high-level-design.md @@ -0,0 +1,421 @@ +# High-level design: automatyczna kontynuacja Codex + +## TL;DR + +Docelowa architektura łączy wykonywalną maszynę stanów z ports-and-adapters: wspólny evaluator podejmuje i zapisuje decyzję, runner ją weryfikuje i commituje projekcje/transition, a workflow loop automatycznie dispatchuje następną pracę. +Zgodność rekomendacji kończy gate aktorem `advisor`; rozbieżność uruchamia dokładnie jednego logicznego arbitra, którego nieudane wywołania są retry tego samego rekordu. +Trwałe `work_item_id`, `dispatch_id` i receipt dają logiczne exactly-once dla następnego problemu oraz następnej fazy, także po crashu. +Codex pozostaje `unsupported`, dopóki realny host-native E2E nie udowodni braku UI, utrzymania aktywnej tury i rzeczywistego kolejnego dispatchu. + +## Key Decisions + +- **A3:** jeden wspólny executable gate evaluator, sterowany read-only portem ról hosta. +- **B1:** evaluator jest właścicielem pełnego rekordu `pending → terminal`; runner konsumuje i weryfikuje ten rekord bez rekonstrukcji provenance. +- **C1:** workflow jest właścicielem stabilnego inventory i durable outbox/receipt; receiver deduplikuje efekt po `dispatch_id`. +- **D1:** cienki binding Codex mapuje wynik na `continue | user_gate | blocked` i oddaje `continue` do aktywnej pętli. +- `orchestrator.current_phase` jest jedynym mutowalnym kursorem fazy; `revision` oraz wspólne repository zabezpieczają dwóch sekwencyjnych writerów. +- Runner jest granicą trwałego commitu i forward transition, ale nigdy dispatcherem domenowej pracy. + +## Open Questions / Risks + +- Stabilny active-turn hook i headless entrypoint prawdziwego Codex wymagają krótkiego spike'a. Jeśli D1 zostanie empirycznie disproven, dopiero wtedy można rozważyć lokalny MCP adapter. +- Migracja realnych stanów z `started_phase` i uboższych rekordów historii wymaga wersjonowanej, fail-closed migracji oraz fixtures z rzeczywistych workflowów. +- Exactly-once oznacza jeden logiczny efekt; transport może fizycznie retry'ować, lecz zawsze z tym samym `dispatch_id` i idempotentnym receiverem. +- Dwa procesy zapisujące YAML muszą używać tego samego locka, atomic rename i revision/CAS; bez tego możliwy jest lost update. + +## 1. Styl architektury i zakres + +**Styl:** wykonywalna state machine w architekturze ports-and-adapters, osadzona w istniejącym single-source/multi-target plugin pipeline. Nie powstaje usługa, daemon ani baza danych. + +Projekt obejmuje osiem komponentów runtime: + +| # | Komponent | Odpowiedzialność | Nie odpowiada za | +|---:|---|---|---| +| 1 | Workflow loop | Materializuje inventory, aplikuje wybór, wyznacza target i kontynuuje aż do terminalnego stopu | Reguły agreement/arbitration | +| 2 | Gate evaluator | Policy, denylista, walidacja outputu, retry, agreement, jeden logiczny arbiter, terminalny record | Raporty i domenowy routing | +| 3 | Role invoker port | Read-only wywołanie `advisor` lub `arbiter` przez host | Mutacje state i wybór polityki | +| 4 | State repository | Lock, odczyt schema, revision/CAS, invariant checks, atomic write | Semantyka workflowu | +| 5 | Continuation runner | Reuse terminal recordu, preflight, raporty/dashboard, forward phase transition | Wywołania modeli i dispatch pracy | +| 6 | Codex binding | Łączy native role port, evaluator i runner; zwraca dyrektywę do aktywnej tury | Własna state machine lub własny audit | +| 7 | Dispatcher/receiver | Wykonuje target z `dispatch_id`, deduplikuje logiczny efekt, zapisuje ack | Wyliczanie domenowego next targetu | +| 8 | Projection generator | Generuje decision summary/dashboard z canonical state | Źródło resume lub decyzji | + +```text +User / workflow invocation + | + v ++-------------------+ +---------------------+ +| 1. Workflow loop |------>| 2. Gate evaluator | +| inventory + route | | executable FSM | ++---------+---------+ +----+-----------+----+ + ^ | | + | continue | v + | +----v----+ +----------------+ + | | 3. Role | | 4. State repo | + | | port | | lock/CAS/write | + | +---------+ +-------+--------+ + | | + | +-------------------v--+ + +------------------| 6. Codex binding | + +----+-------------+--+ + | | + +---------v--+ +----v-------------+ + | 5. Runner | | 7. Dispatcher | + | commit | | receipt/dedupe | + +-----+-----+ +------------------+ + | + +-----v-------------+ + | 8. Projections | + +-------------------+ +``` + +## 2. Granice i porty + +### 2.1 `evaluateGate(gateContext, roleInvoker, stateRepository)` + +Wejście zawiera dokładny `phase_id`, stabilny `gate_type`, pytanie, uporządkowane opcje, `original_recommendation`, safety i read-only context. Evaluator: + +1. wylicza idempotency key; +2. reużywa terminalny rekord przed wywołaniem hosta; +3. zapisuje pending i każdą próbę przed call'em; +4. wywołuje role wyłącznie przez `roleInvoker`; +5. waliduje exact czteropolowy output; +6. zapisuje pełny terminalny envelope albo fail-closed stan. + +```js +roleInvoker.invoke({ + role: "advisor" | "arbiter", + logical_role_id: "sha256:...", + attempt: 1, + gate: { idempotency_key, question, options, original_recommendation }, + read_only_context: { task_path, phase_summaries, artifacts, prior_gate_history } +}) +// -> { selected_option, rationale, confidence, escalate_to_user } +``` + +Role port nie otrzymuje writerów, ścieżek wyjściowych ani prawa rozszerzenia scope. Arbiter dodatkowo otrzymuje dokładnie dwie konkurujące opcje wraz z uzasadnieniami i może zwrócić wyłącznie jedną z nich. + +### 2.2 `continuePhase(commitRequest, stateRepository)` + +Runner dostaje klucz istniejącego terminalnego recordu, oczekiwany wybór i opcjonalny forward target. Ponownie czyta state, sprawdza revision i inwarianty, generuje projekcje oraz zapisuje phase transition/receipt. Nie dostaje odpowiedzi modeli i nie syntetyzuje historii. + +```json +{ + "state": ".../orchestrator-state.yml", + "idempotency_key": "sha256:...", + "expected_selected_option": "A", + "expected_revision": 41, + "next_phase": "phase-5", + "report_md": ".../decision-summary.md", + "report_html": ".../decision-summary.html" +} +``` + +### 2.3 `dispatch(target, dispatchId)` + +Workflow wyznacza target, a Codex binding/dispatcher wykonuje go. Receiver sprawdza receipt przed efektem i atomowo zapisuje `acknowledged` po ustanowieniu obserwowalnego checkpointu targetu. + +```js +dispatcher.dispatch({ + dispatch_id: "sha256:...", + kind: "same_phase_work_item" | "phase_entry", + phase_id: "phase-4", + work_item_id: "decision-area:persistence-boundary" +}) +// -> { directive: "continue", dispatch_id, checkpoint } +``` + +### 2.4 Dyrektywa hosta + +Binding zwraca zamknięty union: + +- `continue` — terminalny gate i wymagane durable efekty są gotowe; workflow ma ponownie odczytać state i wykonać target; +- `user_gate` — gate jest manualny/denylisted albo bezpieczny fallback wymaga użytkownika; +- `blocked` — brak bezpiecznej automatycznej lub interaktywnej ścieżki. + +Żaden poprawny `continue` nie może zostać zamieniony w końcową odpowiedź assistant turn. + +## 3. Kanoniczny model stanu + +State pozostaje pojedynczym snapshotem YAML. `schema_version` umożliwia migrację, `revision` rośnie przy każdym legalnym atomicznym zapisie, a `current_phase` wskazuje dokładnie jedną fazę `in_progress`. + +```yaml +orchestrator: + schema_version: 2 + revision: 42 + current_phase: phase-4 + initial_phase: phase-1 + completed_phases: [phase-1, phase-2, phase-3] + failed_phases: [] + gate_history: + - schema_version: 2 + idempotency_key: sha256:gate-key + phase_id: phase-4 + gate_type: research-convergence + question: "Które podejście wybrać?" + options: [A, B, "Need more info"] + original_recommendation: A + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: B + final_actor: arbiter + advisor: + logical_role_id: sha256:advisor-id + agent: advisor + model: gpt-5.6-sol + response: {selected_option: B, rationale: "...", confidence: high, escalate_to_user: false} + attempts: + - {number: 1, status: completed, started_at: "...", completed_at: "...", error: null} + exhausted: false + arbiter: + logical_role_id: sha256:arbiter-id + agent: arbiter + model: gpt-5.6-sol + response: {selected_option: B, rationale: "...", confidence: high, escalate_to_user: false} + attempts: + - {number: 1, status: completed, started_at: "...", completed_at: "...", error: null} + exhausted: false + rationale: "..." + confidence: high + escalate_to_user: false + user_override: false + continuation: + kind: same_phase_work_item + target_id: decision-area:persistence-boundary + dispatch_id: sha256:dispatch-id + status: acknowledged + error: null + work: + phase-4: + inventory_version: sha256:artifact-derived-version + items: + - id: decision-area:execution-owner + ordinal: 1 + status: completed + source_gate_key: sha256:previous-gate + selected_option: A + - id: decision-area:persistence-boundary + ordinal: 2 + status: in_progress + source_gate_key: null + selected_option: null + dispatch_outbox: + - dispatch_id: sha256:dispatch-id + source_gate_key: sha256:gate-key + kind: same_phase_work_item + phase_id: phase-4 + target_id: decision-area:persistence-boundary + status: acknowledged + attempts: 1 + checkpoint: gate-context-materialized + error: null +``` + +### Inwarianty + +1. `current_phase` wskazuje dokładnie jedną fazę `in_progress`. +2. Jeden idempotency key odpowiada jednemu rekordowi historii, aktualizowanemu in-place pending → terminal. +3. Rekord `decided` ma legalną `selected_option`, terminalnego aktora i pełne provenance właściwe dla tego aktora. +4. Jedna rozbieżność ma jeden `arbiter.logical_role_id`; retry zwiększa `attempts[]`, nie liczbę arbitrów. +5. Jeden `dispatch_id` odpowiada jednemu source gate i targetowi; ponowna próba nie może zmienić targetu. +6. Item może przejść `ready → in_progress → completed|blocked`; nie wraca wstecz bez osobnego, jawnego reset protocol. +7. Dashboard i raporty są projekcjami `gate_history`; nigdy nie sterują resume. + +## 4. Sekwencje decyzji + +### 4.1 Zgodność głównego agenta i advisora + +```text +Workflow Evaluator Repository Advisor Runner Dispatcher + | gate | | | | | + |------------->| key/reuse | | | | + | |--lock+CAS----->| advisor_pending + attempt | | + | |-------------------------------->| invoke | | + | |<--------------------------------| A/high | | + | |--lock+CAS----->| decided(actor=advisor) | | + | |------------------------------->| | | + | |---------------------------------------------->| verify/report| + |<-------------| continue terminal+reports durable | | + | apply choice + enqueue same dispatch_id | | + |---------------------------------------------------------------------------->| + |<----------------------------------------------------------------------------| ack + | start next work item in the same turn | +``` + +Arbiter calls = 0, user-gate calls = 0. Zapis `decided` następuje przed raportami, cursorem i dispatch'em. + +### 4.2 Rozbieżność i jeden logiczny arbiter + +```text +Evaluator -> Repository: advisor_pending + advisor attempt started +Evaluator -> Advisor: original=A, ordered options +Advisor --> Evaluator: B/high/no escalation +Evaluator -> Repository: advisor response + arbiter_pending +Evaluator -> Repository: one logical_arbiter_id + attempt 1 started +Evaluator -> Arbiter: only {A + rationale, B + rationale} +Arbiter --> Evaluator: timeout +Evaluator -> Repository: attempt 1 failed; backoff; attempt 2 started +Evaluator -> Arbiter: same logical_arbiter_id +Arbiter --> Evaluator: A/high/no escalation +Evaluator -> Repository: decided(actor=arbiter, selected=A) +Evaluator -> Runner: verify terminal record and project +Runner --> Workflow: continue +``` + +Resume z `arbiter_pending` nie wywołuje advisora i nie tworzy nowego `logical_arbiter_id`. + +### 4.3 Fail-closed + +Denylista omija role i automatyczny runner. Low confidence, `escalate_to_user: true`, exhaustion, invalid output po limicie, unsupported capability lub błąd legalnego commitu kończą się `user_gate` w sesji interaktywnej albo `blocked`. Nie wolno przesunąć itemu/fazy ani utworzyć dispatchu. + +## 5. Same-phase i next-phase continuation + +### Same phase + +1. Workflow materializuje stabilne inventory z artefaktu i zapisuje `inventory_version`. +2. Po terminalnym gate idempotentnie zapisuje wybór w itemie N i oznacza go `completed`. +3. Ponownie oblicza zależne inventory; istniejące ID nie zmieniają znaczenia. +4. Następny item N+1 przechodzi do `ready`, a outbox otrzymuje deterministyczny `dispatch_id` związany z source gate i targetem. +5. Dispatcher ustanawia checkpoint N+1, receiver deduplikuje ID i zapisuje ack. +6. Binding zwraca `continue`; loop od razu renderuje lub wykonuje N+1 bez pytania o kontynuację. + +### Next phase + +1. Runner po raportach atomowo oznacza source `completed`, target `in_progress`, aktualizuje `current_phase`, timestamps i continuation intent. +2. Workflow tworzy `phase_entry` outbox item z deterministycznym `dispatch_id`. +3. Dispatcher uruchamia body target phase i zapisuje obserwowalny checkpoint startu. +4. Ack zamyka receipt. Samo ustawienie `current_phase` bez checkpointu nie jest dowodem wejścia do fazy. + +Phase-entry self-check akceptuje terminalny automatyczny rekord + zgodny applied transition/receipt jako równoważny dowód wobec historycznego user-question call ID. + +## 6. Persistence, awarie i recovery + +Kanoniczna kolejność: + +```text +1. lock + read + schema/invariant validation +2. pending + attempt started; revision++ ; atomic fsync+rename +3. role response/attempt result; revision++ +4. full terminal gate + continuation intent; revision++ +5. dashboard/report projection from persisted state +6. apply selection + work cursor or phase transition + outbox; revision++ +7. dispatch(target, same dispatch_id) +8. durable acknowledgement/checkpoint; revision++ +``` + +| Crash window | Stan po restarcie | Recovery | +|---|---|---| +| Przed pending write | Brak nowej historii | Bezpiecznie rozpocząć gate | +| Po `attempt: started` | Pending attempt | Zamknąć jako interruption/timeout i zużyć slot | +| Po odpowiedzi advisora | Persisted response | Nie ponawiać zakończonej roli | +| W `arbiter_pending` | Jeden logical arbiter | Ponowić wyłącznie jego następną próbę | +| Po terminalnym gate, przed raportem | `decided`, brak projekcji | Regenerować raport bez modelu i bez duplicate history | +| Po raporcie, przed outbox | Terminal + projekcje | Idempotentnie zastosować wybór i utworzyć target | +| Po outbox, przed efektem | `pending` dispatch | Retry ten sam `dispatch_id` | +| Po efekcie, przed ack | Niepewny transport | Receiver deduplikuje `dispatch_id`, następnie zapisuje ten sam ack | +| Po ack | Target checkpoint durable | Reuse i kontynuacja bez redispatchu | + +Invalid payload, changed terminal selection i invalid transition są odrzucane przed legalnym commitem z byte-exact zachowaniem state, raportów, modes i topologii katalogów. Awaria po terminalnym commicie nie cofa decyzji; recovery dokańcza projekcję lub continuation. + +## 7. Concurrency i state repository + +Wspólny `state-repository` jest małym, bezpośrednio używanym modułem, nie generyczną warstwą persistence. Zapewnia: + +- jeden project-local advisory/exclusive lock dla ścieżki state; +- timeout locka kończący się bez mutacji; +- parse + exact-schema + invariant validation pod lockiem; +- `expected_revision` compare-and-swap; +- zapis do pliku tymczasowego w tym samym katalogu, `fsync`, atomic rename i opcjonalny directory `fsync`; +- zachowanie mode/ownership zgodnie z istniejącym kontraktem; +- wzrost `revision` dokładnie raz na legalny commit. + +Evaluator zwalnia lock przed długim role call'em, ponieważ pending jest już trwały. Po odpowiedzi ponownie bierze lock i używa CAS; konflikt revision powoduje reread i idempotency resolution, nie blind overwrite. Runner działa dopiero na terminalnym recordzie i również używa CAS. Nie ma jednoczesnej, długo trzymanej transakcji przez model, raporty i host dispatch. + +## 8. Migracja call sites i build projection + +Migracja powinna następować pionami, bez bezpośrednich edycji generated variants: + +1. **Canonical schema/runtime:** `plugins/maister/skills/orchestrator-framework/` — evaluator, repository, runner i zsynchronizowane references/fixtures. +2. **Research tracer:** Phase 4 materializuje dwa work itemy, korzysta z binding result i usuwa wymaganie UI call ID na poprawnej ścieżce auto. +3. **Pozostałe call sites:** product-design, development, migration i performance przyjmują ten sam gate envelope; tylko workflow-specific inventory/routing pozostaje lokalne. +4. **Codex adapter:** nowe host binding/harness w `platforms/codex-cli/`; `advisor.toml` pozostaje read-only profilem. +5. **Build projection:** `platforms/codex-cli/build.sh` jawnie kopiuje wymagane runtime files; `make build` regeneruje `plugins/maister-codex/`. +6. **Parity:** wspólne contract tests uruchamiają source i generated runners; drugi clean build ma zero diff. + +Backward refinement z product-design nie jest częścią tej naprawy. Forward-only phase transition pozostaje niezmieniony; ewentualny reset protocol wymaga osobnej decyzji. + +## 9. Bezpieczeństwo + +- Hard denylista jest sprawdzana przez evaluator i ponownie przez runner; denylisted gate nie wywołuje roli, auto continuation ani dispatchu. +- Exact allowlists obejmują gate context, czteropolowy output ról, actor/confidence, terminal record, target kind i phase transition. +- Ścieżki state/report są canonicalizowane i ograniczone do task root; symlink/path traversal są odrzucane. +- Advisor i arbiter mają read-only context, nie dostają shella, writerów ani mutable artifact handles. +- Model output jest danymi, nigdy fragmentem komendy; runner przyjmuje JSON na stdin albo `--input-file`. +- Low confidence i eskalacja nie mogą zostać automatycznie podwyższone lub wyciszone. +- Retry ma skończony budżet i exponential backoff; exhaustion kończy się manual/block. +- Logi i decision summary przechowują provenance, ale nie powinny kopiować sekretów ani niepotrzebnego pełnego promptu. + +## 10. Architektura testów + +| Warstwa | Dowód | Kluczowe przypadki | +|---|---|---| +| Evaluator unit/contract | Wykonywalna FSM z fake role port i call logiem | agreement; oba wyniki arbitra; retry; resume pending; low/escalation; denylist | +| Repository/runner contract | Atomic writes, full record reuse, report/transition recovery | rich real-state fixtures; CAS conflict; changed selection; byte-exact rejection | +| Workflow integration | Fake dispatcher i trwały receipt | dwa zależne same-phase itemy; next phase; crash przed/po ack; dedupe | +| Codex adapter integration | Native binding z fake rolami/UI spy | `continue|user_gate|blocked`; UI=0 na success; dokładny payload/exit/stdout | +| Build/parity | Source → generated | clean double build; source/generated contract matrix; manifest/runtime wiring | +| Host-native Codex E2E | Rzeczywisty host, fake tylko role/dispatcher | agreement + disagreement; same-phase + next-phase; no UI; resume; real checkpoint | + +Capability E2E zwraca `77`, gdy runtime jest niedostępny. Tylko exit `0` z rzeczywistego Codex entrypointu jest dowodem `supported`; shared Node test ani smoke prose nie wystarcza. + +## 11. Rollout i tracer bullet + +### Tracer bullet + +1. Wprowadzić schema v2, `current_phase`, `revision` i repository oraz migrację jednego realnego research fixture. +2. Zaimplementować evaluator agreement z fake advisor portem i pełnym terminalnym recordem. +3. Zmienić runner na consume/verify terminal record, zachowując report recovery. +4. Zmaterializować dokładnie dwa research decision areas; po pierwszym gate utworzyć durable dispatch do drugiego i potwierdzić `continue` bez UI. +5. Dodać disagreement z jednym logicznym arbitrem i oboma legalnymi wynikami. +6. Dodać next-phase target oraz failure injection dla raportu, transition i dispatchu. +7. Włączyć cienki Codex binding za capability `unsupported`, uruchomić clean build i pełną walidację. +8. Wykonać realny Codex E2E; dopiero po zielonym dowodzie zmienić capability na `supported` i sprawdzić projekcję. + +### Rollout gates + +- **R0 — schema contract:** rich fixtures i migracja przechodzą; brak call-site flipu. +- **R1 — shared runtime:** evaluator/runner/repository tests zielone; stara manualna ścieżka nadal działa. +- **R2 — research tracer:** dwa itemy automatycznie przechodzą z logicznym exactly-once. +- **R3 — Codex binding:** adapter integration i build parity zielone, capability nadal `unsupported`. +- **R4 — native proof:** realny host-E2E obserwuje no UI i oba rodzaje dispatchu; capability flip w osobnym, małym commicie. +- **R5 — broader migration:** pozostałe workflowy migrowane po jednym, z własnym inventory testem. + +Rollback przed R4 polega na pozostawieniu capability `unsupported` i użyciu manualnego/user gate fallbacku. Nie należy degradować denylisty ani omijać terminalnego audit recordu, aby ratować automatyzację. + +## 12. Kryteria akceptacji projektu + +Projekt jest wdrożony poprawnie dopiero, gdy: + +- agreement daje `final_actor: advisor`, zero arbitra, zero UI i rozpoczyna następny target; +- disagreement daje jeden logical arbiter, legalny wynik, zero UI i następny target; +- resume nie powiela historii, zakończonych role calls ani logicznego efektu dispatchu; +- same-phase i next-phase mają obserwowalny, trwały checkpoint; +- denylista/low/escalation/exhaustion/unsupported pozostają fail-closed; +- invalid input i zmieniona terminalna decyzja zachowują byte-exact stan; +- source i generated variants przechodzą contract matrix oraz clean rebuild; +- capability Codex jest `supported` wyłącznie po zielonym host-native E2E. + +## 13. Powiązane decyzje i źródła + +- [Decision log](decision-log.md) +- [Research report](research-report.md) +- [Solution exploration](solution-exploration.md) +- `../analysis/synthesis.md` +- `../analysis/findings/01-gate-state-contract.md` +- `../analysis/findings/02-continuation-dispatch.md` +- `../analysis/findings/03-codex-host-adapter.md` +- `../analysis/findings/04-verification-safety.md` +- `.maister/docs/project/architecture.md` +- `.maister/docs/standards/global/build-pipeline.md` +- `.maister/docs/standards/testing/test-writing.md` diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/research-report.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/research-report.md new file mode 100644 index 00000000..8111e99e --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/research-report.md @@ -0,0 +1,376 @@ +# Raport badawczy: jak naprawić automatyczną kontynuację Codex + +## TL;DR + +To powinno działać automatycznie i naprawa jest jednoznaczna: zgodność rekomendacji kończy gate decyzją advisora; rozbieżność uruchamia dokładnie jednego logicznego arbitra; poprawny wynik jest trwale commitowany i natychmiast przekazywany do następnego problemu lub fazy bez kliknięcia użytkownika. +Brakującym elementem nie jest sam wybór opcji, lecz wykonywalny łańcuch `evaluator → runner → adapter Codex → workflow loop`. +`phase-continue.mjs` pozostaje bezpieczną granicą commitu i transition — **runner commit nie jest dispatcherem**. +Po sukcesie adapter musi zwrócić sterowanie do pętli workflow w tej samej turze; zakończenie odpowiedzi po stdout runnera jest obecnym punktem awarii. + +## Key Decisions + +- Zaimplementować wspólny, wykonywalny evaluator agreement/arbitration zamiast polegać wyłącznie na instrukcjach Markdown. +- Ujednolicić canonical state: `current_phase`, pełny `gate_history`, trwały work-item cursor i continuation receipt. +- Zachować ścisły podział: evaluator wybiera, runner utrwala, Codex adapter wykonuje transport, workflow loop routuje następną pracę. +- Potwierdzić obie kontynuacje: kolejny problem w tej samej fazie i faktyczne wejście do następnej fazy. +- Flip `unsupported → supported` wykonać dopiero po zielonym, rzeczywistym Codex E2E. + +## Open Questions / Risks + +- Stabilny headless entrypoint Codex i mechanizm wstrzyknięcia fake role invokera wymagają implementacyjnego spike'a. +- Exact schema pełnego rekordu i receipt trzeba skonsolidować w jednym module/fixture, żeby uniknąć kolejnego rozjazdu prose–runtime. +- Exactly-once dotyczy logicznego efektu; fizyczny dispatch może być ponowiony po przerwaniu, ale zawsze z tym samym `dispatch_id` i deduplikacją. +- Product-design backward refinement wymaga osobnego reset protocol; nie powinien być przemycony jako osłabienie forward-only runnera. + +## 1. Odpowiedź: docelowe zachowanie + +Dla każdego bezpiecznego, niedenylistowanego gate'u `fully_automatic`: + +1. Główny agent tworzy stabilny gate context: `phase_id`, `gate_type`, dokładne pytanie, uporządkowane opcje, `original_recommendation`, safety i read-only context. +2. Evaluator zapisuje `advisor_pending` i próbę `started`, po czym wywołuje read-only advisora. +3. Jeśli advisor zwraca dokładnie `original_recommendation`, `confidence: high|medium` i `escalate_to_user: false`, evaluator zapisuje terminalne `decided`, `final_actor: advisor`. Arbiter i user UI nie są wywoływani. +4. Jeśli advisor wskazuje inną opcję, evaluator tworzy jeden logiczny rekord `arbiter` i wywołuje go. Retry są kolejnymi `attempts[]` tego samego arbitra; advisor nie jest wywoływany ponownie. +5. Arbiter może wybrać wyłącznie rekomendację głównego agenta albo advisora. Poprawny `high|medium`, bez eskalacji, kończy gate aktorem `arbiter`. +6. Pełny terminalny rekord jest trwale zapisany przed raportami i przed continuation. +7. Runner waliduje terminalny rekord, regeneruje raporty i — dla exit gate'u — atomowo przełącza fazę. +8. Adapter Codex sprawdza exit/stdout runnera i zwraca `continue`, nie kończy tury i nie pokazuje pytania. +9. Workflow loop ponownie czyta canonical state, stosuje wybór do bieżącego work itemu, przesuwa trwały cursor i natychmiast dispatchuje następny problem albo body następnej fazy. +10. Dopiero brak kolejnej pracy albo finalna, zawsze user-controlled bramka kończy automatyczny ciąg. + +To dokładnie realizuje regułę użytkownika. Nie należy symulować kliknięcia ani wywoływać user gate na ścieżce sukcesu. + +## 2. Obecny łańcuch awarii + +```text +workflow gate call site + → instrukcje agreement/arbitration w Markdown + → profil advisora w advisor.toml + → [BRAK wykonywalnego evaluatora/adaptera Codex] + → phase-continue.mjs (jeżeli zostanie wywołany ręcznie) + ├─ terminalny commit + ├─ raporty + ├─ opcjonalna zmiana current_phase + └─ stdout JSON + process exit + → [BRAK consumer → apply effect → advance cursor → dispatch] +``` + +Konkretnie: + +- `platforms/codex-cli/templates/advisor.toml:5-18` opisuje rolę i `phase_continue(selected_option)`, ale jest tylko promptem. +- `platforms/codex-cli/build.sh:135-151,315-331` kopiuje/generuje instrukcje i waliduje wpis capability, lecz nie buduje executable bindingu. +- `platforms/codex-cli/smoke-cli.sh:66-89` sprawdza frazy, nie wykonanie. +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` zawsze kończy się `77`. +- `phase-continue.mjs:741-800` po zapisie/raportach/transition wypisuje JSON i kończy proces. +- Bez `next_phase` runner nie przesuwa kursora. Z `next_phase` zmienia state fazy, ale nie uruchamia handlera fazy. +- Call sites research/product-design mają prose „record choice, move to next area”, lecz nie mają durable same-phase cursor ani executable dispatch consumer. +- Phase-entry self-checki wymagające call ID pytania użytkownika są sprzeczne z poprawnym terminalnym auto gate'em. + +**Finding: high confidence.** Baseline: gate prose tests, shared runner i contract tests przechodzą; Codex E2E zwraca `77`, a capability poprawnie pozostaje `unsupported`. + +## 3. Jednoznaczny algorytm decyzyjny + +### 3.1 Agreement + +Warunki konieczne jednocześnie: + +- gate nie jest na hard denyliście; +- effective policy to `fully_automatic`; +- host capability jest zweryfikowane; +- output advisora ma dokładnie cztery dozwolone pola; +- `selected_option` jest dokładnym elementem `options`; +- `selected_option === original_recommendation` (exact string); +- `confidence ∈ {high, medium}`; +- `escalate_to_user === false`. + +Efekt: jeden terminalny rekord, `status: decided`, `final_actor: advisor`; `arbiter_calls=0`, `user_gate_calls=0`. + +### 3.2 Disagreement + +Gdy poprawna rekomendacja advisora różni się od pierwotnej: + +- zapisz wynik advisora przed arbitrażem; +- utwórz jeden `logical_arbiter_id` i jedną mapę `arbiter`; +- przekaż obie opcje i oba uzasadnienia; +- dozwolony output arbitra to wyłącznie jedna z tych dwóch opcji; +- malformed/timeout to kolejna próba w `arbiter.attempts[]`, nie nowy arbiter; +- resume `arbiter_pending` nie wywołuje advisora i nie tworzy nowego logical arbitra; +- poprawny wynik kończy gate z `final_actor: arbiter`. + +### 3.3 Fail-closed + +| Warunek | Terminalne zachowanie | Czego nie wolno zrobić | +|---|---|---| +| Hard denylist | `user_pending` albo noninteractive `blocked` | advisor, arbiter, auto runner, dispatch | +| Low confidence | user fallback albo `blocked` | automatyczny wybór | +| `escalate_to_user: true` | user fallback albo `blocked` | obniżenie eskalacji | +| Retry exhaustion | user fallback albo `blocked` | nieskończony retry lub approval | +| Invalid option/schema | retry w limicie, potem fallback/block | terminalny selection commit | +| Unsupported capability | manual/block | udawana automatyczna kontynuacja | +| Persistence/runner error | stop i resumable state | przesunięcie kursora/fazy | + +**Finding: high confidence.** Reguły są już normatywnie opisane w `gate-decision-engine.md:266-300`; brak ich executable realization. + +## 4. Kanoniczny kontrakt state/history/continuation + +### 4.1 Faza + +Użyć `orchestrator.current_phase` jako jedynego mutowalnego kursora fazy. Musi wskazywać dokładnie jedną fazę `in_progress` w `phases[]`. `started_phase` należy usunąć albo zmienić na niemutowalne `initial_phase`; nie może konkurować z kursorem wykonania. + +### 4.2 Gate history + +Jeden gate = jeden rekord o stabilnym idempotency key. Rekord przechodzi pending → terminal przez update, nie append duplikatu. Pełny envelope powinien obejmować: + +```yaml +schema_version: 1 +idempotency_key: sha256:... +phase_id: phase-4 +gate_type: research-convergence +question: "..." +options: [A, B, "Need more info"] +original_recommendation: A +policy: fully_automatic +safety_classification: configurable +status: decided +selected_option: B +final_actor: arbiter +advisor: + agent: advisor + model: "..." + response: {selected_option: B, rationale: "...", confidence: high, escalate_to_user: false} + attempts: [] + exhausted: false +arbiter: + logical_arbiter_id: sha256:... + agent: arbiter + model: "..." + response: {selected_option: B, rationale: "...", confidence: high, escalate_to_user: false} + attempts: [] + exhausted: false +confidence: high +rationale: "..." +continuation: + kind: same_phase_work_item + target: decision-area:persistence-boundary + status: pending +error: null +``` + +Runner nie powinien syntetyzować `original_recommendation = selected_option` ani rationale zastępczego. Powinien odczytać pełny terminalny rekord i zweryfikować zgodność payloadu z nim. + +### 4.3 Same-phase cursor + +Lista decision areas/problemów musi zostać zmaterializowana w state ze stabilnymi identyfikatorami: + +```yaml +decision_areas: + - id: execution-owner + ordinal: 1 + status: completed + gate_key: sha256:... + chosen_approach: host-workflow-loop + - id: persistence-boundary + ordinal: 2 + status: ready + gate_key: null + chosen_approach: null +``` + +Continuation target zawiera `work_item_id`, `source_gate_key`, `dispatch_id` i status `ready|in_progress|completed|blocked`. Ordinal jest informacyjny, nie stanowi identity. + +### 4.4 Kolejność durability + +```text +1. pending + attempt started (atomic state) +2. role response / attempt result (atomic state) +3. pełny terminal gate + continuation pending (atomic state) +4. dashboard/report projections from persisted state +5. apply selection + cursor/phase transition intent (atomic state) +6. dispatch(target, dispatch_id) +7. applied/completed receipt (atomic state) +``` + +Awaria po kroku 3 nie cofa decyzji. Resume regeneruje brakujące projekcje i kontynuuje z tego samego rekordu. Odrzucenie przed legalnym commitem musi zachować byte-exact state/report/modes/topology. + +**Finding: high confidence** dla wymaganych danych i kolejności; **medium-high** dla dokładnego kształtu YAML. + +## 5. Podział odpowiedzialności + +| Komponent | Odpowiada za | Nie odpowiada za | +|---|---|---| +| `gate-evaluate` / evaluator | idempotency, policy, denylist, role calls, validation, agreement, jeden arbiter, retry, terminal result | domenowy next-item routing | +| `phase-continue.mjs` | canonical-state preflight, terminal reuse/commit verification, raporty, forward phase transition | wywoływanie modeli, decision-area selection, host turn | +| Codex adapter | native delegation port, exact JSON transport, runner exit/stdout validation, outcome `continue|user_gate|blocked` | własny schema, własny cursor, wybór następnego problemu | +| Workflow loop | apply gate effect, stable work-item cursor, next target, natychmiastowy dispatch | ponowna implementacja gate safety | + +Najważniejszy warunek implementacyjny: **successful adapter execution must return control to the workflow loop without ending the turn**. Jeśli adapter po runner exit `0` zwróci finalną odpowiedź użytkownikowi, błąd pozostanie mimo poprawnego commitu. + +## 6. Same-phase kontra next-phase + +### Same-phase: kolejny problem/decision area + +`next_phase` nie może być użyty, bo target jest tą samą fazą i runner odrzuca self-transition. Poprawny flow: + +1. Commit terminal gate dla area N. +2. Idempotentnie zapisz `chosen_approach`, `gate_key`, `status: completed`. +3. Po zastosowaniu wyboru ponownie wylicz dozwolone alternatywy area N+1. +4. Ustaw N+1 `ready` z trwałym `dispatch_id`. +5. Adapter zwraca `continue`; workflow loop natychmiast rozpoczyna N+1 w tej samej turze. + +Nie wolno pre-renderować wszystkich areas, bo późniejsze mogą zależeć od wcześniejszych wyborów. + +### Next-phase: przejście i wejście + +Runner może atomowo wykonać forward transition: source `completed`, target `in_progress`, `current_phase=target`. To nadal tylko commit. Po jego sukcesie adapter zwraca `continue`, a workflow loop uruchamia body target phase i zapisuje obserwowalny pierwszy checkpoint/artifact. Test wyłącznie na statusie fazy jest niewystarczający. + +**Finding: high confidence.** Runner commit nie jest dispatcherem; to wynika z kodu `main()` i braku domenowych/hostowych portów. + +## 7. Dokładna mapa zmian per plik + +### Canonical framework — edytować + +| Plik | Zmiana | +|---|---| +| `plugins/maister/skills/orchestrator-framework/bin/gate-evaluate.mjs` (nowy) | Wykonywalna state machine agreement/arbitration/retry/resume z portem role invoker i pełnym terminalnym rekordem. | +| `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` | Konsumowanie/weryfikacja pełnego terminalnego rekordu; wspólny schema; `current_phase`; continuation intent/receipt; bogatszy, ścisły stdout bez dispatchu domenowego. | +| `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` | Zsynchronizować schema z executable evaluatorem, ownership terminal recordu, retry jednego arbitra i recovery po projekcjach. | +| `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` | `current_phase` zamiast `started_phase`; cursor/dispatch contract; auto gate jako legalny phase-entry proof; wyraźny „do not end turn”. | +| `plugins/maister/skills/orchestrator-framework/references/gate-decision-fixtures.yml` | Pełne executable inputs/expected state/call counts zamiast samych deklaracji. | +| `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` | Bez zmiany na początku; `codex: supported` wyłącznie po zielonym native E2E. | + +### Workflow call sites — edytować + +| Plik | Zmiana | +|---|---| +| `plugins/maister/skills/research/SKILL.md` | Terminal result zamiast „If user picks”; stable decision-area inventory/cursor; sukces runnera wraca do loop; phase self-check akceptuje auto record/receipt. | +| `plugins/maister/skills/product-design/SKILL.md` | Ten sam shared same-phase loop; osobny jawny reset dla backward refinement. | +| `plugins/maister/skills/development/SKILL.md` | Scope decisions jako work items; runner success consumer; auto phase-entry proof. | +| Pozostałe orchestratory używające wspólnego kontraktu | Migracja `started_phase → current_phase`, pełny gate envelope i entry checks według inventory wyszukiwania. | + +### Codex adapter — edytować/dodać + +| Plik | Zmiana | +|---|---| +| `platforms/codex-cli/` nowy binding/loop | Port native role invocation, call evaluator, exact runner transport, validate stdout, return `continue` bez UI/end turn. | +| `platforms/codex-cli/templates/advisor.toml` | Pozostawić read-only profil; wskazać rzeczywisty adapter/port, nie udawać implementacji prose. | +| `platforms/codex-cli/build.sh` | Kopiować nowy runtime/binding do generated target i walidować jego obecność. | +| `platforms/codex-cli/smoke-cli.sh` | Sprawdzać executable binding i wiring, nie tylko frazy. | +| `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` | Zastąpić `exit 77` realnym host-native testem; `77` tylko gdy runtime naprawdę niedostępny. | + +### Testy — edytować/dodać + +| Plik | Zmiana | +|---|---| +| `tests/gate-decision-engine.test.sh` | Dodać executable evaluator tests z licznikami advisor/arbiter/UI. | +| `tests/fixtures/gate-evaluator/` (nowy) | Agreement, oba wyniki arbitra, retry, resume, denylist, low/escalation, full expected record. | +| `tests/phase-continue-contract.test.sh` | Rich real-state fixtures, continuation receipt, crash windows, byte-exact rejection. | +| `tests/fixtures/phase-continue/*.yml` | Stany zgodne z realnymi workflowami, pełny advisor/arbiter audit i `current_phase`. | +| Nowy workflow-loop/dispatch contract test | Dwa same-phase work items, phase entry, `dispatch_id` dedupe i resume. | +| Nowy Codex adapter integration test | Fake role invoker + fake dispatcher, bez rzeczywistego modelu. | +| `Makefile` | Włączyć szybkie testy; zachować host-native target jako jedyny capability proof. | + +### Generated effects — nie edytować bezpośrednio + +`plugins/maister-codex/`, `plugins/maister-cursor/` i `plugins/maister-kiro/` są wynikami `make build`. Po zmianie canonical/adapters uruchomić build, sprawdzić diff i `make validate`. Nowe bindingi Codex muszą mieć jawne reguły copy, bo build odtwarza target. + +## 8. Kolejność implementacji + +1. **Schema i fixtures:** ustalić pełny gate envelope, `current_phase`, continuation/work-item receipt; dodać real-state fixtures. +2. **Executable evaluator:** agreement, disagreement, jeden arbiter, retry/resume, denylist; testy bez hosta. +3. **Runner contract:** runner weryfikuje utrwalony terminal record, raporty i phase transition; nie rekonstruuje audytu. +4. **Workflow loop tracer bullet:** dwa zależne same-phase items, apply effect, cursor, `dispatch_id`, resume. +5. **Codex adapter integration:** native port abstraction + fake role/dispatcher; po runner success outcome `continue` wraca do loop. +6. **Call-site migration:** research, product-design, development i inne inventory; naprawa phase-entry self-checków. +7. **Build projection:** adapter runtime do generated Codex; shared variants regenerowane deterministycznie. +8. **Host-native Codex E2E:** agreement, arbiter, same-phase, next-phase, resume i UI spy. +9. **Capability flip:** dopiero po `exit 0`, reproducible build i pełnym validate. + +Ta kolejność ogranicza ryzyko: najpierw jeden kontrakt i szybkie dowody, potem host binding i capability. + +## 9. Wykonywalna macierz testów + +| Scenariusz | Poziom | Wymagane pozytywne asercje | Wymagane negatywne asercje | +|---|---|---|---| +| Advisor zgadza się | evaluator + Codex E2E | actor advisor; 1 terminal record; reports; next dispatch | arbiter 0; UI 0; brak duplikatów | +| Arbiter wybiera original | evaluator + adapter | 1 logical arbiter; selected original; continuation | advisor nie retry po disagreement; UI 0 | +| Arbiter wybiera advisor | evaluator + adapter | 1 logical arbiter; selected advisor | brak trzeciej opcji; UI 0 | +| Następny decision area | loop + Codex E2E | N completed; N+1 ready/started; ten sam turn | brak phase completion; brak double dispatch | +| Następna faza | runner + Codex E2E | transition + pierwszy checkpoint target phase | brak końca po samym transition | +| Advisor retry | evaluator | persisted attempts/backoff; final advisor | limit nieprzekroczony; brak arbitra bez disagreement | +| Arbiter retry | evaluator | jeden logical arbiter, wiele attempts | advisor nie wywołany ponownie | +| Resume pending | evaluator | ten sam key/role/budget | brak resetu prób/nowej roli | +| Retry exhaustion | evaluator + adapter | user_pending albo blocked | runner/dispatch 0 | +| Report failure | runner | terminal trwały; retry regeneruje i kontynuuje raz | brak duplicate history | +| Transition failure | runner | retry stosuje transition raz | brak dwóch active phases | +| Dispatch failure | adapter/loop | ten sam dispatch_id, idempotent effect | brak nowego gate/efektu logicznego | +| Denylist | wszystkie poziomy | manual/blocked | advisor 0; arbiter 0; runner 0; dispatch 0 | +| Low/escalation | evaluator | manual/blocked | brak automatic selection | +| Invalid output/option | evaluator | bounded retry/fallback | brak selection commit | +| Changed terminal selection | runner | non-zero | byte-exact state/reports/modes/topology | +| Build projection | build | adapter obecny; drugi build no diff | brak ręcznych generated edits | +| Unsupported runtime | capability | E2E exit 77 | declared/projected supported niemożliwe | + +### Deterministyczne porty testowe + +Fake role invoker przyjmuje ten sam immutable context co native Codex i zwraca dokładnie czteropolowy YAML. Call log zapisuje `gate_key`, rolę, `logical_arbiter_id`, attempt i input hash. Fake dispatcher deduplikuje po `dispatch_id` i zapisuje attempt/ack. UI spy failuje natychmiast, jeśli pozytywna ścieżka `fully_automatic` wywoła pytanie. + +Host-native E2E musi nadal uruchomić rzeczywisty Codex entrypoint; fake zastępuje tylko niedeterministyczny model, nie host ani workflow loop. + +## 10. Kryteria akceptacji + +Naprawa jest kompletna tylko wtedy, gdy: + +- zgodność original/advisor automatycznie wybiera opcję, z aktorem `advisor`, bez arbitra i UI; +- rozbieżność uruchamia jeden logical arbiter, a oba legalne rozstrzygnięcia mają executable test; +- pełny terminalny audyt i raporty są trwałe przed continuation; +- kolejny problem/decision area rzeczywiście zaczyna się w tej samej turze; +- next-phase test obserwuje body/checkpoint nowej fazy, nie tylko zmianę statusu; +- resume/retry nie duplikuje historii, logical arbitra ani logicznego dispatchu; +- denylista, low confidence, escalation, exhaustion, invalid state/output i failure paths pozostają fail-closed; +- realny workflow state przechodzi ten sam strict schema bez ad-hoc transformacji adaptera; +- `make build && make validate` przechodzi bez generated drift; +- Codex host-native E2E kończy się `0`; przy braku runtime kończy się `77` i capability pozostaje unsupported. + +## 11. Rollout i reguła capability flip + +Rollout powinien mieć trzy bramki: + +1. **Shared contract ready:** evaluator, runner, schema, fixtures i loop integration są zielone; Codex nadal `unsupported`. +2. **Codex integration ready:** fake-port adapter integration i reproducible build są zielone; Codex nadal `unsupported`. +3. **Native evidence ready:** realny Codex E2E obserwuje agreement, arbitration, same-phase i next-phase continuation, brak UI oraz resume; dopiero wtedy zmienić `host-capabilities.yml` na `supported`. + +Nie używać ręcznego override, smoke frazy ani shared runner testu jako substytutu bramki 3. Makefile już poprawnie odróżnia `exit 0`, `77` i failure — zachować ten fail-closed projection. + +## 12. Ryzyka, luki i confidence + +| Finding | Confidence | Ryzyko / luka | +|---|---|---| +| Brak executable Codex adaptera jest pierwotnym blockerem | High | Brak stabilnego native harnessu | +| Runner commit nie jest dispatcherem | High | Łatwo omyłkowo uznać stdout/transition za continuation | +| Potrzebny powrót do workflow loop bez końca tury | High | Zależność od hostowego modelu execution turn | +| Agreement/jeden arbiter algorytm jest jednoznaczny | High | Dziś tylko prose-tested | +| `current_phase` powinno być canonical | High | Migracja istniejących states/resume | +| Durable same-phase cursor i dispatch_id są konieczne | High | Finalna serializacja wymaga design review | +| Exact native Codex binding shape | Medium | Potrzebny spike headless CLI/tool port | +| Exactly-once logiczny efekt przez dedupe | Medium-high | Receiver musi honorować dispatch_id | + +## 13. Źródła + +Główne źródła pierwszego rzędu: + +- `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` +- `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` +- `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` +- `plugins/maister/skills/research/SKILL.md` +- `plugins/maister/skills/product-design/SKILL.md` +- `plugins/maister/skills/development/SKILL.md` +- `platforms/codex-cli/templates/advisor.toml` +- `platforms/codex-cli/build.sh` +- `platforms/codex-cli/smoke-cli.sh` +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` +- `tests/gate-decision-engine.test.sh` +- `tests/fully-automatic-phase-continue.test.sh` +- `tests/phase-continue-contract.test.sh` +- `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` +- `.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/codex-fully-automatic-diagnosis.md` + +Pełne dowody cząstkowe znajdują się w `../analysis/findings/01-gate-state-contract.md`, `02-continuation-dispatch.md`, `03-codex-host-adapter.md` i `04-verification-safety.md`. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/solution-exploration.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/solution-exploration.md new file mode 100644 index 00000000..61c90204 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/research-context/solution-exploration.md @@ -0,0 +1,434 @@ +# Eksploracja rozwiązań: automatyczna kontynuacja Codex + +## TL;DR + +Najmocniejszy wariant to wspólny wykonywalny evaluator z portami hosta, pełny terminalny rekord zapisywany przed continuation oraz workflow-owned durable work-item cursor z outbox/receipt. +Codex powinien dostać cienki binding, który uruchamia wspólne komponenty i oddaje `continue` do aktywnej pętli bez kończenia tury; nie powinien posiadać własnej kopii logiki decyzji ani routingu. +Zgodność original/advisor kończy gate aktorem `advisor`; rozbieżność tworzy jeden logiczny obiekt `arbiter`, a retry dopisują tylko attempts. +Capability pozostaje `unsupported`, dopóki host-native E2E nie zaobserwuje następnego same-phase work itemu i następnej fazy bez UI. + +## Key Decisions + +- Rekomendacja A3: wspólny executable evaluator/CLI z wstrzykiwanymi portami ról i bez wiedzy o domenowym routingu. +- Rekomendacja B1: evaluator jest jedynym właścicielem pełnego gate recordu; runner weryfikuje terminalny wybór, generuje projekcje i commituję transition/receipt. +- Rekomendacja C1: workflow materializuje stabilne work itemy, a durable outbox z `dispatch_id` prowadzi same-phase i next-phase continuation. +- Rekomendacja D1: cienki host-native binding Codex wokół wspólnych CLI i jawnego `continue | user_gate | blocked`, z fake portami w testach i realnym hostem w capability E2E. + +## Open Questions / Risks + +- Stabilny mechanizm utrzymania aktywnej tury i headless uruchomienia realnego Codex wymaga krótkiego spike'a; to wpływa na formę D1, ale nie na granice komponentów. +- Trzeba ustalić jeden wersjonowany schema/envelope używany przez evaluator, runner, workflowy i fixtures, łącznie z migracją `started_phase → current_phase`. +- Exactly-once oznacza jeden logiczny efekt deduplikowany przez `dispatch_id`; fizyczny retry hosta po przerwaniu pozostaje możliwy. +- Dwa procesy zapisujące ten sam YAML wymagają wspólnego repozytorium/lockowania lub ścisłej sekwencji z compare-and-swap po revision. + +## 1. Kryteria i niezmienne ograniczenia + +Każdy wariant oceniono w pięciu wymiarach: wykonalność techniczna, prostota, ryzyko, przenośność/skalowalność oraz poprawność audytu i resume. + +Niezmienne wymagania: + +1. Hard denylista, low confidence, eskalacja i wyczerpanie retry pozostają fail-closed. +2. Advisor i arbiter są read-only wobec artefaktów i stanu; zapis wykonuje deterministyczny komponent hosta/frameworka. +3. Jeden gate ma jeden idempotency key i jeden rekord przechodzący pending → terminal. +4. Rozbieżność tworzy dokładnie jeden logiczny arbiter; kolejne wywołania są attempts tego samego obiektu. +5. Terminalny wybór jest trwały przed raportami, cursorem i dispatch'em. +6. Edycje trafiają do `plugins/maister/` i `platforms/codex-cli/`; generated variants powstają przez build. +7. „Kontynuacja” jest udowodniona dopiero przez obserwowalny następny work item lub checkpoint nowej fazy, nie przez sam stdout lub zmianę statusu. + +## 2. Obszar A — właściciel i packaging wykonywalnego evaluatora + +Ta decyzja określa, gdzie naprawdę wykonywane są agreement, arbitration, retry, resume, denylista i walidacja czteropolowego outputu. + +### A1. Logika wyłącznie w instrukcjach workflow hosta + +Każdy SKILL opisuje state machine, a główny agent wykonuje ją przy użyciu natywnych subagentów i bez nowego programu. + +**Plusy** + +- Najmniej nowego kodu i zależności. +- Naturalny dostęp do natywnego delegation i aktywnej tury. +- Szybki prototyp jednego call site'u. + +**Minusy** + +- Obecny root cause pozostaje: prose nie jest wykonywalnym, deterministycznym kontraktem. +- Duplikacja i drift między research, product-design, development oraz hostami. +- Trudno dowieść retry budget, resume pending i jednego logicznego arbitra fixture'ami. +- Wysokie ryzyko ponownego wyświetlenia UI po compaction/resume. + +**Ocena:** wykonalność wysoka; prostota początkowa wysoka; ryzyko wysokie; przenośność niska; audyt/resume niski. + +### A2. Rozszerzyć `phase-continue.mjs` do monolitu gate + persistence + dispatch + +Runner wywołuje role, wybiera, zapisuje, generuje raporty i dispatchuje następny target. + +**Plusy** + +- Jeden entrypoint i pozornie jedna transakcja kontroli. +- Łatwy test CLI bez angażowania wielu procesów. +- Mniej transportowych kontraktów między komponentami. + +**Minusy** + +- Node runner nie ma natywnego API do subagentów ani utrzymania tury Codex. +- Łączy wspólną logikę decyzji z domenowym routingiem i hostem. +- Rozszerza blast radius sprawdzonego writer'a oraz komplikuje portability. +- Same-phase work item nadal wymaga wiedzy z konkretnego workflow. + +**Ocena:** wykonalność średnia; prostota średnia; ryzyko wysokie; przenośność niska; audyt/resume średni. + +### A3. Wspólny executable evaluator z portami hosta — rekomendowane + +Nowy wspólny moduł/CLI (np. `gate-evaluate.mjs`) posiada czystą state machine i korzysta z wstrzykiwanego `role_invoker`; host dostarcza wywołanie advisora/arbitra, ale nie implementuje reguł wyboru. + +**Plusy** + +- Agreement, jeden arbiter, retry i resume stają się executable i fixture-testable. +- Jeden kontrakt dla wszystkich workflowów i hostów. +- Role pozostają read-only, a wszystkie mutacje przechodzą przez deterministyczny state repository. +- Fake role port daje szybkie i pełne testy bez niedeterministycznego modelu. + +**Minusy** + +- Trzeba zdefiniować port natywnego delegation oraz granicę procesu/IPC. +- Wymaga wspólnego schema i ostrożnej migracji realnych states. +- Należy rozwiązać lock/revision przy wielu zapisach state. + +**Ocena:** wykonalność wysoka; prostota średnia; ryzyko średnie-niskie; przenośność wysoka; audyt/resume wysoki. + +### A4. Codex-only evaluator w adapterze platformy + +Cały algorytm trafia do `platforms/codex-cli/`; shared runner pozostaje bez zmian. + +**Plusy** + +- Można optymalizować dokładnie pod natywne możliwości Codex. +- Ograniczony początkowy zakres wdrożenia. +- Nie blokuje się na pełnej migracji innych hostów. + +**Minusy** + +- Powstaje drugi gate engine obok kanonicznego kontraktu. +- Inne hosty nie korzystają z testów i poprawek. +- Adapter przestaje być cienki, a generated parity staje się trudniejsza. +- Wysokie ryzyko różnej semantyki denylisty i resume. + +**Ocena:** wykonalność wysoka; prostota średnia; ryzyko wysokie; przenośność niska; audyt/resume średni. + +**Rekomendacja:** A3. Zapewnia wykonywalność bez wciskania hostowych ani domenowych odpowiedzialności do runnera. A1 może posłużyć tylko jako spike portu; nie powinno być rozwiązaniem produkcyjnym. + +## 3. Obszar B — właściciel kanonicznego stanu i terminalnego rekordu + +Ta decyzja usuwa obecny konflikt: gate engine wymaga pełnego audytu, a runner syntetyzuje uboższy record z już wybranej opcji. + +### B1. Evaluator zapisuje pełny rekord, runner konsumuje i weryfikuje — rekomendowane + +Evaluator aktualizuje jeden envelope od pending do terminal. Runner dostaje idempotency key i oczekiwany wybór, ponownie czyta state, weryfikuje terminalny rekord, generuje raporty i commituję continuation. + +**Plusy** + +- Komponent posiadający modelową state machine posiada także pełny provenance. +- Runner nie rekonstruuje rationale, original recommendation ani attempts. +- Resume może osobno naprawić raport/transition bez ponawiania modelu. +- Jasny inwariant: decyzja trwała przed efektami. + +**Minusy** + +- Evaluator i runner są dwoma writerami; potrzebują wspólnego repository API, revision/CAS lub ścisłej sekwencji. +- Payload runnera i schema history muszą zostać zmienione razem. +- Migracja istniejących wąskich terminal records wymaga decyzji kompatybilności. + +**Ocena:** wykonalność wysoka; prostota średnia; ryzyko średnie; przenośność wysoka; audyt/resume wysoki. + +### B2. Runner jest jedynym writerem pełnego recordu + +Evaluator zwraca kompletny immutable result envelope; runner zapisuje pending, attempts i terminal records przez kolejne komendy. + +**Plusy** + +- Jeden filesystem writer i jedno miejsce atomic write. +- Łatwiej kontrolować exact schema i permissions. +- Runner może zachować istniejące wzorce failure injection. + +**Minusy** + +- Wymaga wielokrotnych round-tripów do runnera przed i po każdym model call. +- Host/evaluator musi utrzymywać state machine między procesami, a runner staje się RPC state service. +- Większy transport i więcej stanów częściowego sukcesu. +- Trudniej zachować prosty kontrakt obecnego `phase-continue.mjs`. + +**Ocena:** wykonalność średnia-wysoka; prostota niska; ryzyko średnie; przenośność średnia; audyt/resume wysoki. + +### B3. Jeden zintegrowany command transaction dla gate i continuation + +Proces pozostaje żywy przez model calls, a na końcu zapisuje terminal record, raporty i target. + +**Plusy** + +- Jedno API wejściowe dla adaptera. +- Może centralizować locking i schema validation. +- Czytelny happy path. + +**Minusy** + +- Nie daje prawdziwej transakcji przez zewnętrzne model calls i host dispatch. +- Crash podczas długiego procesu nadal wymaga pending checkpointów. +- Zbliża się do monolitu A2 i utrudnia natywne delegation. +- Duży refactor przed uzyskaniem tracer-bullet proof. + +**Ocena:** wykonalność średnia; prostota średnia-niska; ryzyko wysokie; przenośność średnia; audyt/resume średni. + +### B4. Append-only event log jako jedyne źródło prawdy + +Każdy pending, attempt, decision i dispatch jest osobnym eventem; bieżący state jest projekcją. + +**Plusy** + +- Najpełniejszy audyt i naturalny recovery timeline. +- Brak update-in-place pojedynczego gate recordu. +- Dobra podstawa do diagnostyki concurrency. + +**Minusy** + +- Nieproporcjonalna zmiana architektury projektu dokumentacyjnego bez bazy. +- Wymaga projektora, migracji wszystkich workflowów i nowego modelu dashboardu. +- Trudniejsza exact-schema kompatybilność i większy koszt operacyjny. +- Łamie minimal implementation dla konkretnego buga. + +**Ocena:** wykonalność średnia; prostota niska; ryzyko wysokie; przenośność wysoka; audyt/resume bardzo wysoki. + +**Rekomendacja:** B1, uzupełnione wspólnym małym `state-repository` helperem z atomic write, revision i invariant checks. B4 jest atrakcyjnym kierunkiem długoterminowym, lecz wykracza poza naprawę. + +## 4. Obszar C — same-phase cursor i protokół dispatchu + +Ta decyzja odpowiada za automatyczne przejście od area N do N+1 oraz za realne wejście do kolejnej fazy. + +### C1. Workflow-owned inventory + durable outbox/receipt — rekomendowane + +Workflow materializuje stabilne work itemy. Po terminalnym gate idempotentnie aplikuje wybór, oznacza item completed i zapisuje następny target z `dispatch_id`; adapter dispatchuje, receiver deduplikuje i zapisuje ack. + +**Plusy** + +- Domenowa kolejność i zależne alternatywy pozostają w workflowie. +- Stabilny `work_item_id` i receipt dają logiczne exactly-once oraz precyzyjny resume. +- Ten sam protokół obsługuje `same_phase_work_item` i `phase_entry`. +- Test może obserwować rzeczywisty następny checkpoint, nie tylko status. + +**Minusy** + +- Więcej pól state i kilka crash windows do przetestowania. +- Każdy workflow z pętlą musi materializować inventory zgodnie ze wspólnym kontraktem. +- Receiver musi honorować deduplikację `dispatch_id`. + +**Ocena:** wykonalność wysoka; prostota średnia; ryzyko średnie-niskie; przenośność wysoka; audyt/resume wysoki. + +### C2. Tylko liczbowy cursor/index w phase summary + +Workflow zapisuje `current_index`, inkrementuje po wyborze i natychmiast wykonuje następny element. + +**Plusy** + +- Minimalny schema i prosty happy path. +- Łatwe wdrożenie dla research Phase 4. +- Mało kodu do pierwszego demo. + +**Minusy** + +- Zmiana/reorder artefaktu może skierować resume na inny problem. +- Brak identity, source gate key, dispatch intent i ack. +- Crash po inkrementacji nie rozstrzyga, czy kolejny efekt już wykonano. +- Słabo przenosi się na zależne lub dynamiczne inventory. + +**Ocena:** wykonalność bardzo wysoka; prostota wysoka; ryzyko wysokie; przenośność niska; audyt/resume niski. + +### C3. Runner wylicza i zapisuje generyczny następny target + +Payload zawiera pełną listę work itemów, a runner waliduje i przesuwa cursor. + +**Plusy** + +- Centralne durability i strict transition checks. +- Adapter dostaje gotowy target. +- Możliwe wspólne fixture'y dla cursora. + +**Minusy** + +- Runner musi znać semantykę itemów lub ufać dużemu payloadowi. +- Nie potrafi bez workflowu przeliczyć alternatyw zależnych od poprzedniego wyboru. +- Sprzęga shared runner z formatami phase summaries. +- Nadal nie dispatchuje aktywnej tury. + +**Ocena:** wykonalność średnia; prostota średnia; ryzyko średnie-wysokie; przenośność średnia; audyt/resume wysoki. + +### C4. Ephemeral same-turn loop bez durable dispatch state + +Po sukcesie adapter po prostu kontynuuje `for each area`, a resume wyznacza pierwsze `chosen_approach: null`. + +**Plusy** + +- Najmniej zmian w schema. +- Naturalnie pasuje do obecnego prose call site'u. +- Szybko usuwa widoczny user click w happy path. + +**Minusy** + +- Crash między efektem i kolejnym dispatch'em jest niejednoznaczny. +- Brak dispatch dedupe i observation receipt. +- Re-derywacja z mutującego artefaktu może być niestabilna. +- Host-native E2E nie ma trwałego dowodu dokładnie którego itemu podjęto. + +**Ocena:** wykonalność wysoka; prostota bardzo wysoka; ryzyko średnie-wysokie; przenośność średnia; audyt/resume niski. + +**Rekomendacja:** C1. Minimalny pierwszy pion może ograniczyć inventory do dwóch research decision areas, ale musi od początku używać stabilnego ID i `dispatch_id`, aby prototyp nie utrwalił wadliwego indeksowego kontraktu. + +## 5. Obszar D — binding Codex i seam host-native E2E + +Ta decyzja rozstrzyga, jak połączyć natywne role Codex, wspólny evaluator/runner i pętlę workflow bez kończenia tury. + +### D1. Cienki host-native binding wokół wspólnych CLI — rekomendowane + +Generated skill wywołuje natywne subagenty przez jawny port, przekazuje ich outputs do wspólnego evaluatora, uruchamia runner, waliduje stdout i zwraca do workflow loop `continue | user_gate | blocked`. + +**Plusy** + +- Zachowuje natywne delegation i aktywną turę Codex. +- Shared core pozostaje testowalny fake portami; adapter pozostaje cienki. +- Brak dodatkowego długo żyjącego serwisu. +- Najlepiej pasuje do istniejącego single-source/build modelu. + +**Minusy** + +- Exact mechanizm callbacku/utrzymania tury wymaga spike'a z realnym Codex. +- Część bindingu może nadal być instruction-driven, jeśli host nie wystawia stabilnego programmatic hooka. +- E2E musi odróżniać rzeczywisty host od testu samego Node CLI. + +**Ocena:** wykonalność średnia-wysoka; prostota średnia; ryzyko średnie; przenośność wysoka; audyt/resume wysoki. + +### D2. Lokalny MCP/tool server jako runtime adapter + +Plugin dostarcza narzędzia `evaluate_gate`, `continue_gate` i `dispatch_next`, a Codex wywołuje je w jednej turze. + +**Plusy** + +- Jawne, wykonywalne API i łatwe strict schemas. +- Dobre miejsce na locking, fake ports i observability. +- Potencjalnie przenośne na inne hosty z MCP. + +**Minusy** + +- Nowy proces/usługa, lifecycle i konfiguracja MCP zwiększają koszt instalacji. +- Tool nadal nie może sam zmusić modelu-host do kontynuacji po odpowiedzi; instrukcja loop pozostaje potrzebna. +- Wykracza poza minimalny dependency/runtime footprint. +- Większa powierzchnia bezpieczeństwa. + +**Ocena:** wykonalność wysoka; prostota niska; ryzyko średnie; przenośność wysoka; audyt/resume wysoki. + +### D3. Zewnętrzny headless Codex wrapper sterujący całą sesją + +Skrypt uruchamia `codex exec`, przechwytuje outputs i ponawia kolejne prompty/work items aż do completion. + +**Plusy** + +- Pełna kontrola nad loopem i łatwa automatyzacja CI. +- Jasny host-native E2E entrypoint. +- Niezależność od zachowania pojedynczej odpowiedzi skillu. + +**Minusy** + +- Ryzyko zagnieżdżonych sesji, utraty bieżącego kontekstu i różnic CLI/IDE. +- Trudne bezpieczne wstrzyknięcie fake role invokera. +- Może nie reprezentować realnego plugin invocation użytkownika. +- Wysokie ryzyko niestabilności wersji CLI. + +**Ocena:** wykonalność średnia; prostota niska; ryzyko wysokie; przenośność niska; audyt/resume średni. + +### D4. Codex-specific background daemon/outbox consumer + +Daemon obserwuje `orchestrator-state.yml`, pobiera ready dispatches i uruchamia kolejne zadania niezależnie od assistant turn. + +**Plusy** + +- Naturalny durable outbox consumer i recovery po zakończeniu tury. +- Może przetwarzać wiele workflowów i retry. +- Łatwe acknowledgement oraz metryki. + +**Minusy** + +- Zmienia model produktu z lokalnego pluginu bez usługi na proces w tle. +- Nie spełnia dosłownie wymogu kontynuacji w tej samej aktywnej turze. +- Problemy lifecycle, concurrency, uprawnień i instalacji. +- Nadmiarowe dla pojedynczego buga. + +**Ocena:** wykonalność średnia; prostota niska; ryzyko wysokie; przenośność niska; audyt/resume wysoki. + +**Rekomendacja:** D1, z D2 jako fallback tylko jeśli spike wykaże, że Codex nie zapewnia stabilnego portu/bindingu w aktywnej turze. Host-native E2E musi uruchomić realny Codex entrypoint, podczas gdy fake zastępuje wyłącznie role i dispatcher. + +## 6. Zależności między decyzjami + +```text +A3 executable evaluator + └── wymaga B1 pełnego terminalnego envelope + └── runner może bezstratnie commitować projekcje/transition + +C1 workflow inventory + outbox + ├── konsumuje terminalny wybór z B1 + └── dostarcza target i dispatch_id dla D1 + +D1 Codex binding + ├── dostarcza role_invoker do A3 + ├── uruchamia runner po B1 + └── oddaje continue do loopu realizującego C1 +``` + +Decyzje A3+B1 są fundamentem wspólnym. C1 może być wdrażane tracer-bulletem w research Phase 4. D1 zamyka ostatnią milę hosta i dopiero jego native E2E uprawnia capability flip. + +## 7. Macierz rekomendowanego zestawu + +| Wymiar | A3 evaluator | B1 ownership | C1 cursor/outbox | D1 Codex binding | +|---|---|---|---|---| +| Techniczna wykonalność | Wysoka | Wysoka | Wysoka | Średnia-wysoka | +| Prostota | Średnia | Średnia | Średnia | Średnia | +| Ryzyko | Średnie-niskie | Średnie | Średnie-niskie | Średnie | +| Portability | Wysoka | Wysoka | Wysoka | Wysoka przez cienki adapter | +| Audyt/resume | Wysoki | Wysoki | Wysoki | Wysoki przy native E2E | +| Krytyczny dowód | executable fixtures | full-record recovery | same-phase crash/resume | no-UI real host dispatch | + +## 8. Proponowany tracer bullet + +1. Ustalić wersjonowany gate envelope, `current_phase`, revision oraz `continuation` z `work_item_id` i `dispatch_id`. +2. Zaimplementować evaluator dla agreement i disagreement z jednym logicznym arbitrem oraz fake `role_invoker`. +3. Zmienić runner tak, by reużywał pełny terminalny record, a nie syntetyzował historię. +4. Zaimplementować dwa zależne work itemy w research Phase 4: area A → durable choice → area B ready → dispatch/ack. +5. Dodać cienki Codex binding zwracający `continue` do pętli oraz UI spy. +6. Udowodnić agreement, oba wyniki arbitra, crash po terminalu, crash po cursorze, same-phase i next-phase w testach. +7. Zbudować generated variants i uruchomić reproducibility/validate. +8. Uruchomić realny host-native Codex E2E; capability zmienić dopiero po exit `0`. + +## 9. Dlaczego nie pozostałe zestawy + +- A1+C4 usuwa kliknięcie w happy path, lecz nie naprawia deterministycznego resume i pozostawia root cause jako prose-only. +- A2+C3 centralizuje za dużo w runnerze, który nie zna domeny ani aktywnej tury hosta. +- A4 daje szybki Codex-only sukces kosztem drugiej semantyki gate i przyszłego driftu platform. +- B4+D4 tworzy solidną platformę eventową, ale jest nieproporcjonalne do lokalnego pluginu i obecnego minimalnego runtime. +- D2 jest technicznie czyste, lecz nowy MCP runtime warto przyjąć dopiero po dowodzie, że D1 nie może być stabilnie wykonane. + +## 10. Stretch ideas / poza zakresem + +- Wspólny machine-readable JSON Schema generujący validators, docs i fixtures dla gate/continuation envelope. +- Append-only diagnostyczny journal obok canonical snapshotu, bez zastępowania state jako source of truth. +- Generyczny workflow work-item SDK dla research, product-design i development po udanym tracer bullecie. +- Chaos/failure-injection suite dla wszystkich crash windows i filesystem modes. +- Capability manifest raportujący osobno `decision_automation`, `same_phase_continuation` i `phase_entry_continuation` zamiast jednego boolean. +- Background outbox consumer dla przyszłych nieinteraktywnych/batch workflowów; nie dla obecnej interaktywnej ścieżki. + +## 11. Źródła + +- `../analysis/synthesis.md` +- `research-report.md` +- `../analysis/findings/01-gate-state-contract.md` +- `../analysis/findings/02-continuation-dispatch.md` +- `../analysis/findings/03-codex-host-adapter.md` +- `../analysis/findings/04-verification-safety.md` +- `.maister/docs/project/architecture.md` +- `.maister/docs/project/vision.md` + diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/scope-clarifications.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/scope-clarifications.md new file mode 100644 index 00000000..e616b6c4 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/scope-clarifications.md @@ -0,0 +1,32 @@ +# Phase 2 Scope Clarifications + +## TL;DR + +Gap analysis found no unresolved scope decision: the accepted A3/B1/C1/D1 research scope already covers every material runtime, state, workflow, adapter, build, and verification gap. +The task routes through TDD because the Codex-native defect is deterministic and reproducible; it is high-risk, modifies existing code, creates new runtime/state entities, involves authoritative state operations, and is not UI-heavy. + +## Key Decisions + +- Do not expand or reduce the research-approved scope — all observed gaps map directly to accepted architecture and rollout gates. +- Route next to Phase 3 TDD Red — the native E2E currently exits `77`, providing a deterministic failing capability proof. +- Default user documentation generation to enabled because the task creates new runtime contracts and state entities; leave E2E selection for the verification matrix because the task is not UI-heavy. + +## Open Questions / Risks + +- If the bounded Codex active-turn spike empirically disproves D1, stop and return to scope clarification before considering the researched D2 transport fallback. + +Generated: `2026-07-13T18:09:26Z` + +## Decision Inventory + +- Critical decisions: 0 +- Important decisions: 0 +- Scope expansion recommended: false + +## Detected Characteristics + +- `has_reproducible_defect: true` +- `modifies_existing_code: true` +- `creates_new_entities: true` +- `involves_data_operations: true` +- `ui_heavy: false` diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/technical-clarifications.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/technical-clarifications.md new file mode 100644 index 00000000..25e855b5 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/analysis/technical-clarifications.md @@ -0,0 +1,18 @@ +# Technical Clarifications + +## Outcome + +No additional technical-choice gate is needed in Phase 5. +The referenced high-confidence research already selected the binding architecture and Phase 2 found no unresolved critical or important scope decision. + +## Binding decisions + +- A3: shared executable gate evaluator behind a read-only host role port. +- B1: evaluator owns the complete pending-to-terminal gate record. +- C1: workflow owns durable work inventory, outbox, dispatch receipt, and receiver deduplication. +- D1: a thin Codex binding maps the result to `continue`, `user_gate`, or `blocked` within the active turn. +- Codex capability remains `unsupported` until a real host-native E2E exits successfully. + +## Revisit condition + +Return to scope clarification only if an implementation spike disproves the existence of a viable Codex active-turn hook for D1. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/dashboard-data.js b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/dashboard-data.js new file mode 100644 index 00000000..39939e07 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/dashboard-data.js @@ -0,0 +1,53 @@ +window.MAISTER_DATA = { + generated: "2026-07-13T23:07:16Z", + task: { + title: "Fix Codex automatic continuation", + type: "development", + status: "completed", + description: "Implement the researched repair for Codex fully_automatic agreement, single arbitration, and automatic continuation.", + path: ".maister/tasks/development/2026-07-13-fix-codex-auto-continuation", + current_activity: "Workflow completed after protected final handoff approval" + }, + characteristics: { + has_reproducible_defect: true, + modifies_existing_code: true, + creates_new_entities: true, + involves_data_operations: true, + ui_heavy: false + }, + phases: [ + {id: "phase-1", name: "Analyze codebase & clarify requirements", icon_hint: "analysis", status: "completed", started: "2026-07-13T17:50:35Z", completed: "2026-07-13T18:03:23Z", skip_reason: null, summary: "The intended fully automatic behavior exists only as prose: no executable evaluator, Codex active-turn binding, or durable workflow dispatcher exists. The accepted A3/B1/C1/D1 architecture is required and risk is high.", decisions: [{decision: "Preserve separate evaluator, runner, workflow-routing, and Codex-binding boundaries.", rationale: "Each boundary has different policy, durability, domain, and host responsibilities."}, {decision: "Keep Codex capability unsupported until native E2E evidence passes.", rationale: "Shared and fake-port tests cannot prove active-turn continuation or absence of UI."}], risks: ["The exact Codex host-native active-turn hook still requires a narrow implementation spike.", "Schema migration and shared writers require fail-closed locking, revision/CAS, atomic replacement, and mode/topology preservation.", "Exactly-once dispatch requires deterministic IDs and receiver deduplication across crash windows."], artifacts: [{path: "analysis/codebase-analysis.md", label: "Codebase analysis", html: null}, {path: "analysis/clarifications.md", label: "Phase 1 clarifications", html: null}], gate: {question: "Continue to Phase 2?", answer: "Continue to Phase 2"}}, + {id: "phase-2", name: "Analyze gaps & clarify scope", icon_hint: "analysis", status: "completed", started: "2026-07-13T18:03:23Z", completed: "2026-07-13T18:15:54Z", skip_reason: null, summary: "The high-risk defect is deterministic and affects authoritative state, five workflow consumers, the shared runner, Codex binding, build projection, and capability evidence. A3/B1/C1/D1 fully covers scope, so routing is to TDD Red.", decisions: [{decision: "Preserve the research-approved scope without expansion.", rationale: "Every missing evaluator, state, routing, adapter, build, and verification touchpoint is already part of A3/B1/C1/D1."}, {decision: "Route through TDD Red.", rationale: "The Codex-native capability test deterministically exits 77 and proves the missing runtime seam."}], risks: ["The active-turn spike may disprove D1 and require returning to scope clarification before adopting D2.", "State schema migration and concurrent writers remain the highest correctness risk."], artifacts: [{path: "analysis/gap-analysis.md", label: "Gap analysis", html: null}, {path: "analysis/scope-clarifications.md", label: "Scope clarifications", html: null}], gate: {question: "Continue to Phase 3: TDD Red Gate?", answer: "Continue to Phase 3: TDD Red Gate"}}, + {id: "phase-3", name: "Write failing test (TDD Red)", icon_hint: "verify", status: "completed", started: "2026-07-13T18:15:54Z", completed: "2026-07-13T18:20:22Z", skip_reason: null, summary: "A behavioral Codex workflow-loop contract now fails because the executable host binding is missing. It covers agreement without arbitration, disagreement with exactly one logical arbiter, zero user gates, and acknowledged dispatch to the next work item.", decisions: [{decision: "Use a deterministic binding-level contract for the red gate.", rationale: "It reproduces the missing executable seam while keeping external role and dispatch dependencies isolated."}], risks: ["Passing this deterministic contract will not by itself justify changing the Codex capability matrix; real host-native E2E evidence is still required."], artifacts: [{path: "implementation/tdd-red-gate.md", label: "TDD red gate evidence", html: null}, {path: "../../../../tests/codex-fully-automatic-workflow-loop.test.sh", label: "Failing workflow-loop test", html: null}], gate: {question: "TDD red gate complete. Continue to Phase 4?", answer: "Continue to Phase 4"}}, + {id: "phase-4", name: "Generate UI mockups", icon_hint: "design", status: "skipped", started: "2026-07-13T18:20:22Z", completed: "2026-07-13T18:20:22Z", skip_reason: "task_context.task_characteristics.ui_heavy is false", summary: "UI mockup generation was skipped because this runtime and persistence repair has no user-interface surface.", decisions: [], risks: [], artifacts: [], gate: {question: "UI mockups complete. Continue to Phase 5?", answer: "Continue to Phase 5"}}, + {id: "phase-5", name: "Gather requirements & create specification", icon_hint: "spec", status: "completed", started: "2026-07-13T18:24:43Z", completed: "2026-07-13T18:59:02Z", skip_reason: null, summary: "The revised specification defines 30 plan-ready requirements and keeps Codex unsupported until native E2E succeeds.", decisions: [{decision: "Use A3/B1/C1/D1 boundaries with one canonical evaluator.", rationale: "This separates shared policy, durable state, workflow routing, and host mechanics without Codex-specific drift."}, {decision: "Treat exactly-once as one logical dispatch effect.", rationale: "Physical retries reuse the same dispatch ID and receiver deduplication prevents duplicate target effects."}], risks: ["The exact Codex active-turn hook still requires a narrow implementation spike."], artifacts: [{path: "analysis/technical-clarifications.md", label: "Technical clarifications", html: null}, {path: "analysis/requirements.md", label: "Confirmed requirements", html: null}, {path: "implementation/spec.md", label: "Specification", html: "implementation/spec.html"}], gate: {question: "Continue to specification audit?", answer: "Continue to specification audit"}}, + {id: "phase-6", name: "Audit specification", icon_hint: "verify", status: "completed", started: "2026-07-13T18:59:02Z", completed: "2026-07-13T19:20:47Z", skip_reason: null, summary: "The initial audit found three high and two medium precision gaps. One targeted revision resolved F1-F5; the focused re-audit declared the specification compliant and plan-ready with zero open findings.", decisions: [{decision: "Accept the revised specification as plan-ready.", rationale: "Schema/migration, dispatch recovery, evidence bootstrap, compatibility, and repository semantics are now normative and testable."}], risks: ["The D1 active-turn hook remains an implementation spike with an explicit stop-and-reclarify condition if disproved."], artifacts: [{path: "verification/spec-audit.md", label: "Specification audit", html: null}], gate: {question: "Continue to implementation planning?", answer: "Continue to implementation planning"}}, + {id: "phase-7", name: "Plan implementation", icon_hint: "plan", status: "completed", started: "2026-07-13T19:20:47Z", completed: "2026-07-13T19:33:44Z", skip_reason: null, summary: "Seven sequential task groups cover all 30 requirements in 39 test-first steps with 25-34 feature tests. D1 viability is the hard first checkpoint and capability activation remains separated from native evidence.", decisions: [{decision: "Make D1 viability the first hard checkpoint.", rationale: "Stop and reclarify rather than introducing D2/MCP if same-turn continuation is impossible."}, {decision: "Implement the state repository before all state writers.", rationale: "All durable writers need one lock, CAS, and atomic-commit contract."}, {decision: "Separate native evidence from capability activation.", rationale: "Codex stays unsupported until native evidence exits 0."}], risks: ["The exact active-turn hook is not yet empirically proven.", "Native exit 77 is safe but cannot authorize support.", "Filesystem and generated-projection behavior require platform-sensitive verification."], artifacts: [{path: "implementation/implementation-plan.md", label: "Implementation plan", html: "implementation/implementation-plan.html"}], gate: {question: "Continue to implementation approval?", answer: "Continue to implementation approval"}}, + {id: "phase-8", name: "Execute implementation", icon_hint: "code", status: "completed", started: "2026-07-13T19:41:09Z", completed: "2026-07-13T21:45:49Z", skip_reason: null, summary: "Groups 1–7 completed. Group 5 recovery fixed TMPDIR-scoped Kiro build ownership; Group 6 produced native exit-0 evidence before and after separate Codex capability activation; Group 7 reviewed all 30 requirements against the passing feature suite.", decisions: [{decision: "Execute only the approved seven-group scope.", rationale: "The protected implementation-approval gate explicitly authorized groups 1 through 7."}, {decision: "Make Kiro build ownership repository-local.", rationale: "Different TMPDIR values could bypass the previous lock and concurrently mutate one generated tree."}, {decision: "Activate Codex only after two-step native evidence.", rationale: "The real Codex entrypoint passed before and after the separate supported declaration change."}], risks: [], artifacts: [{path: "implementation/work-log.md", label: "Work log", html: null}], gate: {question: "Continue to verification?", answer: "Continue to verification"}}, + {id: "phase-9", name: "Verify test passes (TDD Green)", icon_hint: "verify", status: "completed", started: "2026-07-13T21:45:49Z", completed: "2026-07-13T21:59:38Z", skip_reason: null, summary: "The direct Codex workflow-loop contract passes 4/4 with exit code 0. Native Codex continuation evidence also passed before and after capability activation.", decisions: [{decision: "Accept the TDD Green result.", rationale: "The executable Phase 3 contract now passes and the host-native evidence supports the activated capability."}], risks: [], artifacts: [{path: "implementation/tdd-green-gate.md", label: "TDD green gate evidence", html: null}], gate: {question: "TDD gate passed. Continue to Phase 10?", answer: "Continue to Phase 10"}}, + {id: "phase-10", name: "Prompt verification options", icon_hint: "verify", status: "completed", started: "2026-07-13T21:59:38Z", completed: "2026-07-13T22:10:41Z", skip_reason: null, summary: "All four standard reviews were selected; browser E2E was skipped because the task has no UI; user documentation was enabled.", decisions: [{decision: "Run all standard reviews and generate user documentation.", rationale: "User accepted the recommended verification set and documentation option."}], risks: [], artifacts: [], gate: null}, + {id: "phase-11", name: "Verify implementation & resolve issues", icon_hint: "verify", status: "completed", started: "2026-07-13T22:10:41Z", completed: "2026-07-13T22:32:40Z", skip_reason: null, summary: "The source-contract parity issue and stale Kiro CHAT GATE threshold were fixed; full repository validation passed.", decisions: [{decision: "Apply all fixable verification findings.", rationale: "The user selected Fix all and the re-verification suite is green."}], risks: [], artifacts: [{path: "verification/implementation-verification.md", label: "Implementation verification", html: "verification/implementation-verification.html"}], gate: {question: "Continue to Phase 12?", answer: "Continue to Phase 12"}}, + {id: "phase-12", name: "Run E2E tests", icon_hint: "verify", status: "skipped", started: "2026-07-13T22:43:04Z", completed: "2026-07-13T22:43:04Z", skip_reason: "options.e2e_enabled is false", summary: "Browser E2E was skipped by the earlier optional-phase decision; native Codex evidence was already verified.", decisions: [], risks: [], artifacts: [], gate: {question: "E2E complete. Continue to Phase 13?", answer: "Continue to Phase 13"}}, + {id: "phase-13", name: "Generate user documentation", icon_hint: "docs", status: "completed", started: "2026-07-13T22:49:32Z", completed: "2026-07-13T22:53:00Z", skip_reason: null, summary: "Created a user-facing Markdown guide and faithful HTML companion for automatic Codex workflow continuation.", decisions: [], risks: [], artifacts: [{path: "documentation/user-guide.md", label: "User guide", html: "documentation/user-guide.html"}], gate: {question: "Documentation complete. Continue to Phase 14?", answer: "Continue to Phase 14"}}, + {id: "phase-14", name: "Finalize workflow", icon_hint: "done", status: "completed", started: "2026-07-13T22:59:08Z", completed: "2026-07-13T23:07:16Z", skip_reason: null, summary: "Workflow finalized after the user approved the protected final handoff.", decisions: [{decision: "Complete workflow", rationale: "User approved final handoff after reviewing all artifacts."}], risks: [], artifacts: [{path: "outputs/decision-summary.md", label: "Decision summary", html: "outputs/decision-summary.html"}], gate: {question: "Complete workflow or keep it open?", answer: "Complete workflow"}} + ], + verification: {status: "passed", issues: [], fixes: ["Source JSON continuation contract markers", "Kiro schema-v2 CHAT GATE threshold", "Generated projections rebuilt"], reverify_count: 2}, + gate_history: [{idempotency_key: "sha256:ba5d887d0c4265cbcbe1c13696ffdc0cf70e09b9b115fd0cea577002cb7aee7a", phase_id: "phase-1", gate_type: "phase-1-exit", question: "Continue to Phase 2?", options: ["Continue to Phase 2", "Pause workflow"], status: "decided", selected_option: "Continue to Phase 2", final_actor: "user", rationale: "User approved continuation after reviewing the Phase 1 codebase analysis and clarifications.", confidence: "high"}, {idempotency_key: "sha256:bda70639d3caeafe6e58449256cad57fd6f7b9ed55a120a3f202f6349f082a35", phase_id: "phase-2", gate_type: "phase-2-routing", question: "Continue to Phase 3: TDD Red Gate?", options: ["Continue to Phase 3: TDD Red Gate", "Pause workflow"], status: "decided", selected_option: "Continue to Phase 3: TDD Red Gate", final_actor: "user", rationale: "User approved the TDD Red route after reviewing the Phase 2 gap analysis.", confidence: "high"}, {idempotency_key: "sha256:fd8a0dde74422d174a503635180bcae5229547be5924ee81758382516d511e3", phase_id: "phase-3", gate_type: "phase-3-exit", question: "TDD red gate complete. Continue to Phase 4?", options: ["Continue to Phase 4", "Pause workflow"], status: "decided", selected_option: "Continue to Phase 4", final_actor: "user", rationale: "User approved continuation after reviewing the failing TDD contract and persisted red evidence.", confidence: "high"}, {idempotency_key: "sha256:bedc2afddf4732085c33cf7e8d91af82e10a07c25484bcdeba93a3d37e5543c7", phase_id: "phase-4", gate_type: "phase-4-exit", question: "UI mockups complete. Continue to Phase 5?", options: ["Continue to Phase 5", "Pause workflow"], status: "decided", selected_option: "Continue to Phase 5", final_actor: "user", rationale: "User approved routing to specification work after UI mockups were skipped.", confidence: "high"}, {idempotency_key: "sha256:130921bdba5474ec8cbd27699e4f91e6074d48aba4180ea8a712325d2ffd227b", phase_id: "phase-5", gate_type: "requirements-clarification", question: "I assume this repair is transparent to Maister workflow users: they access it through existing maister:* workflows, with no new commands or UI, and automatic gates simply continue in the active Codex turn. Is that correct?", options: ["Yes, use this journey", "No, revise the journey"], status: "decided", selected_option: "Yes, use this journey", final_actor: "user", rationale: "User confirmed the transparent existing-workflow journey.", confidence: "high"}, {idempotency_key: "sha256:0de2807b14ec69b7f7623bd8e30d635ecbb8732592a4721d87e8d3bcb84e0303", phase_id: "phase-5", gate_type: "requirements-clarification", question: "I assume the implementation must extend the canonical orchestrator framework, shared state/continuation runtime, existing build projections, host capability matrix, and contract-test patterns, with only a thin Codex binding and no separate Codex-only evaluator. Is that correct?", options: ["Yes, reuse these canonical seams", "No, revise the reuse constraints"], status: "decided", selected_option: "Yes, reuse these canonical seams", final_actor: "user", rationale: "User confirmed reuse of canonical seams with only a thin Codex binding.", confidence: "high"}, {idempotency_key: "sha256:2671f8fa96f4aca2e6e961cf125b252826b1e3b927826c122cb663c4fee3fca4", phase_id: "phase-5", gate_type: "requirements-clarification", question: "I assume there are no mockups, wireframes, screenshots, or other visual assets for this non-UI runtime repair, so the specification should contain no visual implementation requirements. Is that correct?", options: ["Yes, no visual assets", "No, I will provide visual assets"], status: "decided", selected_option: "Yes, no visual assets", final_actor: "user", rationale: "User confirmed there are no visual assets or visual implementation requirements.", confidence: "high"}, {idempotency_key: "sha256:be3a4d348eb56e0c8ddddc627142df6991828e358f2cb9c15e3b3519bdc78ec8", phase_id: "phase-5", gate_type: "phase-5-exit", question: "Continue to specification audit?", options: ["Continue to specification audit", "Pause workflow"], status: "decided", selected_option: "Continue to specification audit", final_actor: "user", rationale: "User approved the delegated, self-verified specification.", confidence: "high"}, {idempotency_key: "sha256:25ed56451a996a9299301ab4e2c8703a8c4bc876280146c4f32790b7115f440e", phase_id: "phase-6", gate_type: "optional-phase-selection", question: "Run specification audit? (Recommended)", options: ["Yes, run audit (Recommended)", "No, skip audit"], status: "decided", selected_option: "Yes, run audit (Recommended)", final_actor: "user", rationale: "User selected the recommended independent specification audit.", confidence: "high"}, {idempotency_key: "sha256:1fe66cd479b2d3d5b6efc0fd4597f15b5a503f8b4eded313d8c4fcc21d7dcb00", phase_id: "phase-6", gate_type: "phase-6-exit", question: "Continue to implementation planning?", options: ["Continue to implementation planning", "Pause workflow"], status: "user_pending", selected_option: null, final_actor: "system", rationale: "The focused re-audit found zero open findings; the phase-exit gate uses the interactive fallback.", confidence: "high"}] +}; +window.MAISTER_DATA.gate_history[window.MAISTER_DATA.gate_history.length - 1] = {idempotency_key: "sha256:1fe66cd479b2d3d5b6efc0fd4597f15b5a503f8b4eded313d8c4fcc21d7dcb00", phase_id: "phase-6", gate_type: "phase-6-exit", question: "Continue to implementation planning?", options: ["Continue to implementation planning", "Pause workflow"], status: "decided", selected_option: "Continue to implementation planning", final_actor: "user", rationale: "User approved implementation planning after the focused re-audit found zero open findings.", confidence: "high"}; +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:54b3b61cbff13e163db142366b59dcc90b99aa091ad884540e9ac197658d554d", phase_id: "phase-7", gate_type: "phase-7-exit", question: "Continue to implementation approval?", options: ["Continue to implementation approval", "Pause workflow"], status: "user_pending", selected_option: null, final_actor: "system", rationale: "The delegated planner produced and self-verified a complete seven-group implementation plan; the phase-exit gate uses the interactive fallback.", confidence: "high"}); +window.MAISTER_DATA.gate_history[window.MAISTER_DATA.gate_history.length - 1] = {idempotency_key: "sha256:54b3b61cbff13e163db142366b59dcc90b99aa091ad884540e9ac197658d554d", phase_id: "phase-7", gate_type: "phase-7-exit", question: "Continue to implementation approval?", options: ["Continue to implementation approval", "Pause workflow"], status: "decided", selected_option: "Continue to implementation approval", final_actor: "user", rationale: "User approved routing the self-verified implementation plan to the protected approval gate.", confidence: "high"}; +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:4048f2df3ad915b86ab2734606838d7174ae6a522d61fb8b228ab9f3b449a938", phase_id: "phase-7", gate_type: "implementation-approval", question: "Approve this complete implementation scope?", options: ["Approve complete implementation scope", "Reject implementation scope", "Request scope changes"], status: "user_pending", selected_option: null, final_actor: "system", rationale: "This denylisted protected gate requires an explicit user decision.", confidence: "high"}); +window.MAISTER_DATA.gate_history[window.MAISTER_DATA.gate_history.length - 1] = {idempotency_key: "sha256:4048f2df3ad915b86ab2734606838d7174ae6a522d61fb8b228ab9f3b449a938", phase_id: "phase-7", gate_type: "implementation-approval", question: "Approve this complete implementation scope?", options: ["Approve complete implementation scope", "Reject implementation scope", "Request scope changes"], status: "decided", selected_option: "Approve complete implementation scope", final_actor: "user", rationale: "User explicitly approved the complete seven-group, 39-step implementation scope.", confidence: "high"}; +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:6995e5f3f50704b8ae72f8d3dfc9218c948b08ce0b53c3d0317a6793d4e3d055", phase_id: "phase-8", gate_type: "group-failure-recovery", question: "Group 5 implementation failed: complete generated-tree reproducibility is blocked by alternating Kiro build topology. How to proceed?", options: ["Try suggested fix", "Retry group", "Complete manually", "Rollback changes", "Stop"], status: "decided", selected_option: "Try suggested fix", final_actor: "user", rationale: "The repository-local Kiro lock prevents TMPDIR-specific concurrent mutation; two clean aggregate builds now produce identical generated manifests.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:401d2c28e455e758938531a94957dc4d4d93118bb8ed275d2885ff0172208df8", phase_id: "phase-8", gate_type: "group-failure-recovery", question: "Group 6 native evidence is unavailable (exit 77); Codex remains unsupported. How to proceed?", options: ["Try suggested fix", "Retry group", "Complete manually", "Rollback changes", "Stop"], status: "decided", selected_option: "Try suggested fix", final_actor: "user", rationale: "The test-only native bootstrap produced exit-0 evidence before and after separate capability activation; forced unavailability still exits 77.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:19568792996c419f61acb934284693bd396df535db9c9b4ac814b5f6c528d7a5", phase_id: "phase-8", gate_type: "phase-8-exit", question: "Continue to verification?", options: ["Continue to verification", "Pause workflow"], status: "decided", selected_option: "Continue to verification", final_actor: "user", rationale: "User approved continuation to TDD Green verification after Groups 1–7 completed.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:21481c7a3ccef7ede23269d2b2f100c6408458d9a82455fafe0aba00bc872eeb", phase_id: "phase-9", gate_type: "phase-9-exit", question: "TDD gate passed. Continue to Phase 10?", options: ["Continue to Phase 10", "Pause workflow"], status: "decided", selected_option: "Continue to Phase 10", final_actor: "user", rationale: "User approved continuation after the TDD Green contract passed with 4/4 shared assertions.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:530fc6822d1a70a98ba3c3006c1da3db21a56c8bfc9a4e457502e9aea70e1be8", phase_id: "phase-10", gate_type: "verification-options", question: "Which standard verifications to run?", options: ["Code review (Recommended)", "Pragmatic review (Recommended)", "Reality check (Recommended)", "Production readiness (Recommended)"], status: "decided", selected_option: ["Code review (Recommended)", "Pragmatic review (Recommended)", "Reality check (Recommended)", "Production readiness (Recommended)"], final_actor: "user", rationale: "User accepted all four pre-selected standard verifications.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:77c8cb6704d28e4d5762aaf89136f4842e48d9f66c93efe086598ae8d8f9f8b7", phase_id: "phase-10", gate_type: "optional-phase-selection/e2e", question: "Enable E2E browser verification?", options: ["Yes (Recommended)", "No, skip"], status: "decided", selected_option: "No, skip", final_actor: "user", rationale: "User skipped browser E2E because the task has no browser UI.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:01919555cceafcac7db620a0fee6ab826a11fbb5262305dfabcdd4158932e2e9", phase_id: "phase-10", gate_type: "optional-phase-selection/user-docs", question: "Generate user documentation?", options: ["Yes (Recommended)", "No, skip"], status: "decided", selected_option: "Yes (Recommended)", final_actor: "user", rationale: "User approved generating documentation as part of the verification workflow.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:e89bcd06958fe3f971bc14c4adc5618140a78e5da1125c44c5090c7d36fe16f1", phase_id: "phase-11", gate_type: "verification-fix-selection", question: "Which issues should I fix?", options: ["Fix all fixable issues", "Let me choose specific issues", "Skip fixes, proceed as-is"], status: "decided", selected_option: "Fix all fixable issues", final_actor: "user", rationale: "User approved fixing all fixable verification issues.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:ba2f37fc98aefd3b718995813535a7792eb83183de4c25a116034b7257428193", phase_id: "phase-11", gate_type: "phase-11-exit", question: "Continue to Phase 12?", options: ["Continue to Phase 12", "Pause workflow"], status: "decided", selected_option: "Continue to Phase 12", final_actor: "user", rationale: "User approved continuation after Phase 11 verification passed; E2E remains skipped by configuration.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:1f9da8b5b76f9ea1ca3febfdd5b7bc1875d62c81a866304b24b12e37e34f7a80", phase_id: "phase-12", gate_type: "phase-12-exit", question: "E2E complete. Continue to Phase 13?", options: ["Continue to Phase 13", "Pause workflow"], status: "decided", selected_option: "Continue to Phase 13", final_actor: "user", rationale: "User approved continuation after the configured E2E skip; Phase 13 documentation generation is enabled.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:7cb2b9033ac1de28bebd53bd4944c1a8785e7136071f26ce2aa98059abdbafad", phase_id: "phase-13", gate_type: "phase-13-exit", question: "Documentation complete. Continue to Phase 14?", options: ["Continue to Phase 14", "Pause workflow"], status: "decided", selected_option: "Continue to Phase 14", final_actor: "user", rationale: "User approved continuation after the documentation artifacts were generated and validated.", confidence: "high"}); +window.MAISTER_DATA.gate_history.push({idempotency_key: "sha256:250a7596bc8c9dbb5c55d6186e83b1b214a148e00ec7535e3bddffbc39d7fe68", phase_id: "phase-14", gate_type: "final-handoff-approval", question: "Complete workflow or keep it open?", options: ["Complete workflow", "Keep workflow open"], status: "decided", selected_option: "Complete workflow", final_actor: "user", rationale: "User explicitly approved completing the workflow after reviewing all artifacts.", confidence: "high"}); diff --git a/plugins/maister-copilot/skills/orchestrator-framework/assets/dashboard.html b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/dashboard.html similarity index 97% rename from plugins/maister-copilot/skills/orchestrator-framework/assets/dashboard.html rename to .maister/tasks/development/2026-07-13-fix-codex-auto-continuation/dashboard.html index 2c4c6182..9f5ea812 100644 --- a/plugins/maister-copilot/skills/orchestrator-framework/assets/dashboard.html +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/dashboard.html @@ -351,7 +351,7 @@ renderHeroes(d, phases) + '
' + '
' + renderTimeline(phases) + renderDrawer(phases) + '
' + - '
' + renderVerification(d.verification) + renderDecisions(phases) + renderRisks(phases) + renderCharacteristics(d.characteristics) + '
' + + '
' + renderVerification(d.verification) + renderGateHistory(d.gate_history) + renderDecisions(phases) + renderRisks(phases) + renderCharacteristics(d.characteristics) + '
' + '
' + '
Maister workflow dashboard · data: dashboard-data.js · auto-refreshes every 5s
'; @@ -542,6 +542,20 @@ ''; } +function renderGateHistory(history) { + const rows = Array.isArray(history) ? history : []; + if (!rows.length) return ""; + const body = rows.map((g, i) => { + const actor = g.final_actor || g.answered_by || "unknown"; + const selected = g.selected_option || g.answer || "pending"; + const gateType = g.gate_type ? " · " + g.gate_type : ""; + const rationale = g.rationale ? '
' + esc(g.rationale) + '
' : ""; + return '
#' + (i + 1) + ' ' + esc(selected) + + ' — ' + esc(actor + gateType) + '' + rationale + '
'; + }).join(""); + return '

Gate history

' + body + '
'; +} + /* sidebar lists grouped by phase — full text, never truncated */ function renderDecisions(phases) { let total = 0, html = ""; diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/documentation/user-guide.html b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/documentation/user-guide.html new file mode 100644 index 00000000..e2785153 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/documentation/user-guide.html @@ -0,0 +1,53 @@ + + + + + + Automatic Codex workflow continuation + + + +
+

Automatic Codex workflow continuation

+

Maister can continue safe workflow decisions automatically when the main agent and Advisor agree.

+

What this changes

+

Eligible workflows continue without an extra question. If recommendations differ, one Arbiter resolves the difference. The complete decision is saved before continuation, so retries do not repeat work.

+

Who should use this

+

Users running existing maister:* workflows in Codex with the fully automatic policy enabled. No new command or UI setup is required.

+

What happens

+
    +
  1. Maister evaluates and records the current gate.
    2. +
  2. Agreement records the Advisor decision and continues.
    3. +
  3. Disagreement invokes one logical Arbiter with the same context.
    4. +
  4. The terminal decision and reports are persisted.
    5. +
  5. The workflow advances using the saved selection.
    6. +
+

Protected decisions

+

Implementation approval, rollback, unresolved critical findings, production go/no-go, and final handoff always require an explicit user decision.

+

Interrupted workflows

+

Resume the same task. Maister reuses the terminal decision, regenerates missing reports, and applies a pending transition once without duplicate history or duplicate target starts.

+

Fail-closed behavior

+

Invalid, denied, low-confidence, or non-zero runner results return to a user gate or persist a blocked state. Maister never advances the phase silently.

+

Troubleshooting

+
    +
  • If a question appears, it may be a protected or manual gate; answer it normally.
    • +
  • If the task is blocked, read the latest gate and verification report, resolve it, and resume.
    • +
  • If a report is missing, resume again so it can be projected from durable history.
    • +
+

Related artifacts

+ +
+ + diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/documentation/user-guide.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/documentation/user-guide.md new file mode 100644 index 00000000..85606132 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/documentation/user-guide.md @@ -0,0 +1,81 @@ +# Automatic Codex workflow continuation + +## What this changes + +Maister can now continue an eligible workflow automatically when the main +agent and Advisor agree on a decision. You do not need to answer an extra +question between those phases. + +When the two recommendations differ, Maister asks one Arbiter to resolve the +difference. The selected result is saved before the workflow moves on, so a +retry can safely resume without repeating the decision or starting the next +step twice. + +## Who should use this + +This behavior is available to users running existing `maister:*` workflows in +Codex with the fully automatic policy enabled. No new command or user-interface +setup is required. + +## Before you start + +- Start a normal Maister workflow, such as development, research, or migration. +- Keep the workflow state in its task directory so Maister can resume it after + an interruption. +- Use the existing workflow options and gates; automatic continuation does not + change protected approval or safety decisions. + +## What happens during a workflow + +1. Maister evaluates the current gate and records the recommendation. +2. If the Advisor agrees, Maister records the Advisor decision and continues. +3. If the Advisor disagrees, Maister invokes one logical Arbiter decision. The + Arbiter receives both recommendations and the same read-only context. +4. Maister saves the complete terminal decision and requested reports. +5. The workflow continues to the next phase or work item using the saved choice. + +The continuation runner accepts the validated decision through its JSON +transport. It reads from standard input or an explicitly named input file and +returns a compact JSON result. Extra command-line arguments are rejected. + +## Protected decisions + +Some decisions always require you. Examples include implementation approval, +rollback, unresolved critical verification findings, production go/no-go, and +final handoff. Automatic continuation never bypasses these safeguards. + +## If a workflow is interrupted + +Resume the same Maister task. Maister reuses the saved terminal decision, +regenerates missing reports, and applies a pending phase transition once. It +does not append a duplicate history entry or start the same target twice. + +## If automatic continuation cannot proceed + +Maister fails closed. A low-confidence, invalid, denied, or non-zero runner +result returns the workflow to an explicit user gate or records a blocked +state. The phase is not advanced silently. + +## Troubleshooting + +### I still see a question + +That gate may be protected, low-confidence, or configured for manual review. +Answer it normally; automatic continuation is intentionally limited to safe, +validated gates. + +### The workflow says it is blocked + +Read the latest gate and verification report in the task directory. Resolve the +reported issue or provide the requested decision, then resume the same task. + +### A report is missing after a retry + +Resume the task again. Reports are projections of the durable workflow history +and are regenerated from the saved terminal decision. + +## Related artifacts + +- [Implementation verification](../verification/implementation-verification.md) +- [Workflow decision summary](../outputs/decision-summary.md) +- [Implementation specification](../implementation/spec.md) diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/implementation-plan.html b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/implementation-plan.html new file mode 100644 index 00000000..d051781a --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/implementation-plan.html @@ -0,0 +1,256 @@ + + + + +Implementation Plan — Codex Fully Automatic Continuation + + + + +
+ Implementation plan +

Codex Fully Automatic Continuation

+

Generated 2026-07-13 · audited specification · high-risk runtime/state change

+
+
+
7task groups
+
39total steps
+
25–34expected tests
+
1 → 7execution order
+
+
+

TL;DR

+

Prove the D1 active-turn hook first, then establish schema-v2 state, the shared evaluator, workflow-owned continuation, the thin Codex projection, native evidence/activation, and final feature test review. The state repository precedes every writer. Shared behavior remains canonical under plugins/maister/; Codex mechanics remain under platforms/codex-cli/.

+

Hard gate: Codex remains unsupported until native evidence exits 0. A disproved D1 hook stops the plan for scope clarification.

+
+
+
+

Key decisions

+
    +
  • D1 viability is Group 1 and blocks production work.
    • +
  • Repository precedes evaluator and continuation.
    • +
  • Policy/state transitions remain shared executable modules.
    • +
  • Research is the first same-phase workflow tracer.
    • +
  • Capability activation is a two-change evidence gate.
    • +
+
+
+

Open risks

+
    +
  • The exact active-turn hook remains empirically unproven.
    • +
  • Native runtime absence (77) is safe but not success.
    • +
  • Filesystem locking/metadata behavior is platform-sensitive.
    • +
  • Post-acknowledgement crashes must not repeat target starts.
    • +
  • Generated trees must come only from deterministic builds.
    • +
+
+
+ +
+
+

Dependency flow

+
1 D1 proof→2 State→3 Evaluator→4 Continuation→5 Codex/build→6 Native evidence→7 Review
+

There is no implementation parallelism before the D1 checkpoint. Group 4 requires both repository and evaluator; the final review requires all implementation groups.

+
+ +
+

Group 1 · Codex Active-Turn Hook Viability

+
Dependencies: noneSteps: 5Tests: 3
+
platforms/codex-cli/bin/fully-automatic-gate.mjsplatforms/codex-cli/tests/active-turn-hook.e2e.shtests/codex-fully-automatic-workflow-loop.test.sh
+
    +
  • Prove the D1 active-turn hook or stop for scope clarification.
    • +
  • Write 3 focused directive/native tests.Reject unknown directives; observe same-turn continuation without final output or user gate; keep unavailable exit 77.
    • +
  • Implement the narrow Codex binding entrypoint.Consume shared output as data; do not implement policy, select work, bypass the denylist, or expose evidence eligibility.
    • +
  • Run the real-host spike and record the outcome.Require an observable target-start marker. If D1 is impossible, stop before Group 2 with no D2/MCP fallback.
    • +
  • Run only the 3 Group 1 tests.
    • +
+
Acceptance: real Codex proves same-turn re-entry and three directives only; exit 77 does not claim proof; disproved D1 stops/reclarifies.
+
+ +
+

Group 2 · Schema-v2 State Repository and Migration

+
Dependencies: Group 1Steps: 6Tests: 5
+
plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-schema.mjsplugins/maister/skills/orchestrator-framework/bin/orchestrator-state-repository.mjstests/orchestrator-state-repository.test.shtests/orchestrator-state-migration.test.shtests/fixtures/orchestrator-state-v2/**
+
    +
  • Implement the transactional schema-v2 state boundary.
    • +
  • Write 5 focused repository/migration tests.Valid commit, supported migration, ambiguous rejection, revision conflict, and lock/metadata/symlink failure with byte/mode/topology snapshots.
    • +
  • Implement exact schema-v2 parsing and invariants.Strict anchors, fields, enums, timestamps, phase cursor, and legal gate/work/outbox transitions; reuse strict runner boundaries.
    • +
  • Implement the supported legacy migration matrix.One locked migration to revision 1; complete or explicitly legacy provenance; no lossy fabrication.
    • +
  • Implement token lock, revision/CAS, and durable replacement.Bounded leases, safe stale-owner proof, same-directory staging/flush/rename, exact mode, safe ownership, caller-only cleanup.
    • +
  • Run only the 5 Group 2 tests.
    • +
+
Acceptance: exact schema/migration, one revision per commit, no stale overwrite, and non-mutating rejection across supported macOS/Linux filesystem boundaries.
+
+ +
+

Group 3 · Shared Gate Evaluator and Policy Compatibility

+
Dependencies: Group 2Steps: 6Tests: 5
+
plugins/maister/skills/orchestrator-framework/bin/gate-evaluator.mjsreferences/gate-decision-engine.mdreferences/gate-decision-fixtures.ymltests/gate-evaluator.test.shtests/gate-decision-engine.test.shtests/fixtures/gate-evaluator/**
+
    +
  • Implement one executable gate state machine.
    • +
  • Write 5 focused evaluator tests.Agreement; one-logical-Arbiter disagreement/retry; invalid/low/escalated failure; mixed policies/override; terminal and pending resume.
    • +
  • Implement strict gate and role-response boundaries.Exact allowlists and four role fields; role contexts read-only and outputs data-only.
    • +
  • Implement pending-to-terminal evaluation through the repository.Persist attempts before effects; Advisor terminal on agreement; stable Arbiter identity across bounded retries.
    • +
  • Preserve mixed-policy and fallback semantics.Denylist explicit, manual role-free, advisor user-confirmed, exact override, unsupported automatic falls back effectively to manual.
    • +
  • Run only the 5 Group 3 tests.
    • +
+
Acceptance: one Advisor and zero Arbiter on agreement; one logical Arbiter on disagreement; complete durable envelope; no workflow mutation inside evaluator.
+
+ +
+

Group 4 · Runner, Workflow Inventory, and Dispatch

+
Dependencies: Groups 2 and 3Steps: 6Tests: 5
+
bin/phase-continue.mjsbin/workflow-continuation.mjsreferences/orchestrator-patterns.mdskills/research/SKILL.mdskills/development/SKILL.mdskills/migration/SKILL.mdskills/performance/SKILL.mdskills/product-design/SKILL.mdtests/workflow-continuation.test.shtests/phase-continue-contract.test.shtests/fully-automatic-phase-continue.test.shtests/codex-fully-automatic-workflow-loop.test.shtests/fixtures/phase-continue/**
+
    +
  • Implement durable workflow-owned routing and recovery.
    • +
  • Write 5 focused continuation tests.Same-phase advance, phase-entry checkpoint, expired claim reclaim, post-ack crash, and runner/report recovery; retain the red tracer.
    • +
  • Refactor the runner into terminal verifier/recovery.Verify persisted identity, actor, option, confidence, revision, denylist, transition; never call roles, synthesize provenance, select, or dispatch.
    • +
  • Implement workflow inventory, choice application, and outbox.Research first; stable IDs and deterministic dispatch; workflows own target selection.
    • +
  • Implement atomic receiver checkpoint and equivalent phase-entry evidence.Acknowledge with target checkpoint; retry returns stored receipt; protected gates never gain equivalence.
    • +
  • Run only the 5 Group 4 tests.
    • +
+
Acceptance: red tracer passes; terminal persistence precedes every later effect; same/next-phase paths have one dispatch/checkpoint; existing interactive safety remains compatible.
+
+ +
+

Group 5 · Thin Codex Binding and Build Projection

+
Dependencies: Groups 1, 3, and 4Steps: 6Tests: 4
+
platforms/codex-cli/bin/fully-automatic-gate.mjsplatforms/codex-cli/templates/advisor.tomlplatforms/codex-cli/templates/arbiter.tomlplatforms/codex-cli/build.shplatforms/kiro-cli/build.shplatforms/kiro-cli/tests/reproducible-build.test.sh.gitignorereferences/host-capabilities.ymlMakefiletests/codex-fully-automatic-workflow-loop.test.shtests/host-capability-matrix.test.shgenerated Codex/Cursor/Kiro orchestrator + workflow projections
+
    +
  • Connect Codex host mechanics and regenerate platform variants.
    • +
  • Write 4 focused binding/build tests.Role isolation, directive validation, safe-result passthrough, deterministic parity while support remains unsupported; evidence provider unreachable normally.
    • +
  • Complete role and receiver binding.Shared evaluator → runner/receiver → one directive; continue re-reads canonical state and starts the acknowledged target in-turn.
    • +
  • Project canonical runtime/workflow contracts.Update adapter/build, run make build, inspect generated variants, and keep Codex unsupported.
    • +
  • Validate deterministic build ownership.Repository-local lock prevents TMPDIR-specific overlap; two clean aggregate builds have identical generated manifests and the evidence harness is absent from generated/installable plugins.
    • +
  • Run only the 4 Group 5 tests.
    • +
+
Acceptance: binding has host mechanics only; generated variants reproduce twice; Codex remains unsupported; no production evidence bypass exists.
+
+ +
+

Group 6 · Native Evidence and Capability Activation

+
Dependencies: Group 5Steps: 5Tests: 3
+
platforms/codex-cli/tests/fully-automatic-continuation.e2e.shplatforms/codex-cli/tests/native-evidence-bootstrap.mjsreferences/host-capabilities.ymltests/host-capability-matrix.test.shMakefiledocs/codex-support.md
+
    +
  • Prove native behavior before activating capability.
    • +
  • Write 3 focused native-evidence tests.Real entrypoint agreement/disagreement, same/next-phase, zero UI, resume/dedupe/checkpoints; isolated bootstrap; unavailable exit 77.
    • +
  • Implement the test-tree-only evidence bootstrap.Bypass declaration eligibility only; no build/install inclusion or production selector; every safety check remains active.
    • +
  • Execute two-step activation.First evidence exit 0 while unsupported; then a separate change to supported and normal eligibility rerun. Failure/77 leaves or restores unsupported.
    • +
  • Run only the 3 Group 6 tests.
    • +
+
Acceptance: real native exit 0 precedes a distinct declaration change; normal supported execution and matrix pass; bootstrap is unpackageable and cannot weaken safety.
+
+ +
+

Group 7 · Test Review and Gap Analysis

+
Dependencies: Groups 1–6Steps: 5Tests: up to 9 additions
+
feature test files from Groups 1–6
+
    +
  • Review and fill critical feature gaps.
    • +
  • Review the 25 focused tests.Mapped schema/migration, policy, crash/retry, active-turn, native activation, and generated parity evidence across R1–R30.
    • +
  • Analyze feature-only gaps.No uncovered critical safety or continuation gap remained after the native activation review.
    • +
  • Write up to 9 strategic tests.No additional tests were necessary; the feature suite remains within the 25–34 target.
    • +
  • Run the 25–34 feature-specific tests.31 shared feature tests plus 3 native evidence scenarios passed.
    • +
+
Acceptance: all 25–34 feature tests pass, R1–R30 and critical safety/crash boundaries are mapped, and no protected gate, D2/MCP, UI, service, database, or generated hand-edit enters scope.
+
+ +
+

Standards compliance

+ + + + + + + + + +
StandardPlan contract
global/build-pipeline.mdEdit canonical/adapters, regenerate all variants, require reproducible output.
global/coding-style.md, commenting.md, minimal-implementation.mdFocused descriptive modules, sparse timeless comments, immediate callers, no speculative framework.
global/error-handling.md, validation.mdExact allowlists, early actionable rejection, bounded retries, fail-closed outcomes, reliable cleanup.
global/conventions.mdMinimal dependencies and unsupported capability posture until native proof.
testing/test-writing.mdBehavior-focused risk coverage and byte/mode/permission/topology proofs for transaction rejection.
+
+
+

Execution notes

+
    +
  • Each implementation group begins with 2–8 focused tests; review adds at most 9.
    • +
  • Run only new or directly affected tests until final verification.
    • +
  • Mirror completed Markdown checkboxes by flipping these exact HTML markers from todo to done.
    • +
  • Reuse strict runner boundaries, reconciliation failure injection, canonical workflows, build projections, and capability matrices.
    • +
  • If Group 1 disproves D1, or Group 6 lacks native exit 0, do not change architecture or claim support.
    • +
+
+
+ + diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/implementation-plan.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/implementation-plan.md new file mode 100644 index 00000000..6c0ae2df --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/implementation-plan.md @@ -0,0 +1,252 @@ +# Implementation Plan: Codex Fully Automatic Continuation + +## TL;DR + +Execute seven task groups in order: prove the D1 active-turn hook, establish transactional schema-v2 state, implement the shared evaluator, add workflow-owned continuation, finish the thin Codex projection, prove native capability, then close feature-level test gaps. +The state repository precedes every state writer; evaluator and workflow behavior remain canonical under `plugins/maister/`, while Codex mechanics stay under `platforms/codex-cli/`. +Codex remains `unsupported` until the real native evidence group exits `0`; an empirically disproved D1 hook stops the plan for scope clarification. + +## Key Decisions + +- Make D1 viability Group 1 and a dependency of all production groups — the approved architecture requires a stop-and-reclarify outcome if Codex cannot continue within the active turn. +- Sequence repository before evaluator and continuation — every role attempt, terminal record, work item, claim, and acknowledgement needs one lock/CAS/atomic-commit contract. +- Keep policy and state transitions in shared executable modules — Codex receives a thin directive/role/receiver binding, never a second evaluator. +- Adopt Research as the first same-phase workflow tracer, then update other workflow entry guards to consume equivalent automatic evidence — this proves the defect without inventing a generic workflow SDK. +- Treat capability activation as a two-commit evidence gate — native evidence runs while support is still declared `unsupported`; only a successful exit `0` permits the later declaration change. + +## Open Questions / Risks + +- The exact Codex active-turn hook is not yet proven. Group 1 must record a real-host observation; if D1 is disproved, stop before Group 2 and return to scope clarification without introducing D2/MCP. +- Native Codex may be unavailable in the implementation environment. Exit `77` preserves `unsupported` but does not satisfy Group 6 or authorize activation. +- Repository correctness depends on macOS/Linux lock ownership, metadata, symlink, and directory-flush behavior; injected failures must prove byte-, mode-, and topology-exact non-mutation. +- A crash after dispatch acknowledgement but before observation must return the stored acknowledgement. Receiver logic must never infer success from stdout or repeat a logical target start. +- Generated variants touch broad trees. Only canonical and adapter sources are hand-edited; `make build` owns generated changes and a second build must be clean. + +## Overview + +- Total Steps: 39 +- Task Groups: 7 +- Expected Tests: 25 focused tests before review, up to 9 strategic additions (25–34 total) +- Parallelism: none before the D1 checkpoint; repository and evaluator are serial; final review follows all implementation groups + +## Implementation Steps + +### Task Group 1: Codex Active-Turn Hook Viability + +**Dependencies:** None +**Files to Modify:** `platforms/codex-cli/bin/fully-automatic-gate.mjs`, `platforms/codex-cli/tests/active-turn-hook.e2e.sh`, `tests/codex-fully-automatic-workflow-loop.test.sh` +**Estimated Steps:** 5 + +- [x] 1.0 Prove the D1 active-turn hook or stop for scope clarification + - [x] 1.1 Write 3 focused tests for directive validation and real active-turn continuation + - Reject any binding result outside `continue | user_gate | blocked`. + - Observe that `continue` returns control to the live Codex workflow loop without a final response or user question. + - Preserve exit `77` when the native Codex runtime is unavailable; do not treat it as proof. + - [x] 1.2 Implement the narrow Codex binding entrypoint needed by the spike + - Keep host mechanics in `platforms/codex-cli/bin/fully-automatic-gate.mjs` and consume a shared-runtime result as data. + - Do not implement policy, choose workflow work, bypass the denylist, or expose a production eligibility override. + - [x] 1.3 Run the real-host spike and record the architectural outcome + - Require an observable same-turn target-start marker, not process exit or JSON stdout alone. + - If D1 is empirically impossible, make no fallback changes and return to scope clarification before Group 2. + - [x] 1.4 Ensure the 3 Group 1 tests pass + - Run only `platforms/codex-cli/tests/active-turn-hook.e2e.sh` and the directly targeted binding cases in `tests/codex-fully-automatic-workflow-loop.test.sh`. + +**Acceptance Criteria:** + +- The 3 focused tests pass on an available real Codex runtime; unavailable execution exits `77` without claiming viability. +- `continue` demonstrably re-enters the workflow loop in the same active turn with no user-facing boundary. +- The binding exposes only the three directives and contains no decision policy or configurable evidence bypass. +- A disproved D1 produces a documented stop/reclarify outcome and no D2/MCP implementation. + +### Task Group 2: Schema-v2 State Repository and Migration + +**Dependencies:** Group 1 +**Files to Modify:** `plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-schema.mjs`, `plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-repository.mjs`, `tests/orchestrator-state-repository.test.sh`, `tests/orchestrator-state-migration.test.sh`, `tests/fixtures/orchestrator-state-v2/**` +**Estimated Steps:** 6 + +- [x] 2.0 Implement the transactional schema-v2 state boundary + - [x] 2.1 Write 5 focused repository and migration tests + - Cover one valid v2 commit, supported legacy migration, ambiguous migration rejection, revision conflict, and lock/metadata/symlink failure without mutation. + - Snapshot bytes, mode, permissions, and relevant directory topology for every rejection or injected failure. + - [x] 2.2 Implement exact schema-v2 parsing and invariant validation + - Validate canonical anchors, strict fields/enums/nullability/timestamps, one `current_phase`, immutable `initial_phase`, and legal gate/work/outbox transitions. + - Reuse the strict duplicate-key, allowlist, canonical-path, and YAML-boundary behavior from `phase-continue.mjs` rather than weakening it. + - [x] 2.3 Implement the supported legacy migration matrix + - Migrate in one locked commit to `schema_version: 2` and `revision: 1`. + - Preserve complete provenance or an explicitly non-authorizing `legacy` record; reject lossy or ambiguous shapes before mutation. + - [x] 2.4 Implement lock, revision/CAS, and durable atomic replacement + - Use a token-owned sibling lock, bounded wait/lease, same-host dead-owner proof, same-directory staging, data flush, atomic rename, supported directory flush, exact mode preservation, and safe ownership handling. + - Clean only caller-owned temporary and lock artifacts; never steal uncertain locks or remove a successor lock. + - [x] 2.5 Ensure the 5 Group 2 tests pass + - Run only `tests/orchestrator-state-repository.test.sh` and `tests/orchestrator-state-migration.test.sh`. + +**Acceptance Criteria:** + +- The 5 focused tests pass. +- Every valid commit increments the expected revision exactly once; stale or concurrent writers cannot overwrite a newer snapshot. +- Every supported legacy row migrates deterministically and ambiguous/unsafe input leaves bytes, metadata, reports, and topology unchanged. +- Lock, symlink, ownership, cleanup, timeout, and durability behavior is explicit and safe on supported macOS/Linux Node runtimes. + +### Task Group 3: Shared Gate Evaluator and Policy Compatibility + +**Dependencies:** Group 2 +**Files to Modify:** `plugins/maister/skills/orchestrator-framework/bin/gate-evaluator.mjs`, `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md`, `plugins/maister/skills/orchestrator-framework/references/gate-decision-fixtures.yml`, `tests/gate-evaluator.test.sh`, `tests/gate-decision-engine.test.sh`, `tests/fixtures/gate-evaluator/**` +**Estimated Steps:** 6 + +- [x] 3.0 Implement one executable gate state machine + - [x] 3.1 Write 5 focused evaluator tests + - Cover fully-automatic agreement, disagreement with one logical Arbiter across retries, invalid/low-confidence/escalated fail-closed output, manual/advisor/user override compatibility, and terminal/pending resume reuse. + - Assert role call counts, stable logical role IDs, complete attempts, immutable terminal records, and no continuation mutation on unsafe outcomes. + - [x] 3.2 Implement strict gate context and role-response boundaries + - Accept only the allowlisted gate context and exact four-field role response; validate options, recommendation, safety, capability, confidence, and escalation before effects. + - Treat role output only as data and keep role contexts read-only. + - [x] 3.3 Implement pending-to-terminal evaluation through the repository + - Persist every started/completed/failed/interrupted attempt before dependent effects. + - End agreement with `final_actor: advisor`; create one Arbiter logical identity for disagreement and retain it through bounded retries. + - [x] 3.4 Preserve mixed-policy and fallback semantics + - Keep denylisted gates explicit, manual gates role-free, advisor policy user-confirmed, user override exact, and unsupported fully-automatic effective-manual with configured policy retained. + - Reuse terminal and `user_pending` records before any repeated role call or prompt. + - [x] 3.5 Ensure the 5 Group 3 tests pass + - Run only `tests/gate-evaluator.test.sh` and the directly affected cases in `tests/gate-decision-engine.test.sh`. + +**Acceptance Criteria:** + +- The 5 focused tests pass. +- Agreement invokes Advisor once and Arbiter zero times; disagreement invokes Advisor once and one logical Arbiter with bounded attempts. +- The evaluator owns a complete durable gate envelope and never advances workflow state, renders reports, or dispatches work. +- Manual, advisor, override, fallback, denylist, retry, and resume behavior matches the normative policy table. + +### Task Group 4: Continuation Runner, Workflow Inventory, and Dispatch + +**Dependencies:** Groups 2 and 3 +**Files to Modify:** `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs`, `plugins/maister/skills/orchestrator-framework/bin/workflow-continuation.mjs`, `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md`, `plugins/maister/skills/research/SKILL.md`, `plugins/maister/skills/development/SKILL.md`, `plugins/maister/skills/migration/SKILL.md`, `plugins/maister/skills/performance/SKILL.md`, `plugins/maister/skills/product-design/SKILL.md`, `tests/workflow-continuation.test.sh`, `tests/phase-continue-contract.test.sh`, `tests/fully-automatic-phase-continue.test.sh`, `tests/codex-fully-automatic-workflow-loop.test.sh`, `tests/fixtures/phase-continue/**` +**Estimated Steps:** 6 + +- [x] 4.0 Implement durable workflow-owned routing and recovery + - [x] 4.1 Write 5 focused continuation tests + - Cover same-phase inventory advance, forward phase-entry checkpoint, claim expiry/reclaim, crash after acknowledgement before observation, and runner/report/transition recovery without duplicated effects. + - Retain agreement/disagreement tracer assertions for completed source item, acknowledged dispatch, next item `in_progress`, zero user gates, and stable IDs. + - [x] 4.2 Refactor `phase-continue.mjs` into a verifier/recovery runner + - Re-read the evaluator-owned terminal record and verify identity, option, actor, confidence, revision, denylist, and legal forward transition. + - Reuse repository commits; do not invoke roles, synthesize provenance, select domain work, or dispatch targets. + - [x] 4.3 Implement workflow inventory, apply-selection, and outbox operations + - Materialize stable ordered Research decision-area work items first; idempotently complete the source and create a deterministic same-phase or phase-entry dispatch. + - Keep target selection in each workflow and the common record/claim/checkpoint mechanics in the shared continuation module. + - [x] 4.4 Implement receiver checkpoint and phase-entry evidence + - Atomically establish the target `in_progress` checkpoint and acknowledge the same `dispatch_id`; retries return the stored acknowledgement. + - Update workflow entry guards to accept explicit user evidence or matching automatic terminal/transition/receipt/checkpoint evidence, never for protected gates. + - [x] 4.5 Ensure the 5 Group 4 tests pass + - Run only the four listed continuation/runner scripts and directly affected fixture cases. + +**Acceptance Criteria:** + +- The 5 focused tests pass, including the original red tracer. +- Terminal gate persistence precedes projection, choice application, cursor/phase mutation, outbox creation, claim, and acknowledgement. +- Same-phase and next-phase paths create one stable logical dispatch and one durable target checkpoint; recovery never duplicates starts or receipts. +- Existing manual/advisor, denylist, immutable selection, forward-only transition, and report-recovery behavior remains compatible. + +### Task Group 5: Thin Codex Binding and Deterministic Build Projection + +**Dependencies:** Groups 1, 3, and 4 +**Files to Modify:** `platforms/codex-cli/bin/fully-automatic-gate.mjs`, `platforms/codex-cli/templates/advisor.toml`, `platforms/codex-cli/templates/arbiter.toml`, `platforms/codex-cli/build.sh`, `platforms/kiro-cli/build.sh`, `platforms/kiro-cli/tests/reproducible-build.test.sh`, `.gitignore`, `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml`, `Makefile`, `tests/codex-fully-automatic-workflow-loop.test.sh`, `tests/host-capability-matrix.test.sh`, `plugins/maister-codex/skills/orchestrator-framework/**`, `plugins/maister-cursor/lib/orchestrator-framework/**`, `plugins/maister-kiro/skills/maister-orchestrator-framework/**`, `plugins/maister-codex/skills/{research,development,migration,performance,product-design}/SKILL.md`, `plugins/maister-cursor/skills/maister-{research,development,migration,performance,product-design}/SKILL.md`, `plugins/maister-kiro/skills/maister-{research,development,migration,performance,product-design}/SKILL.md` +**Estimated Steps:** 6 + +- [x] 5.0 Connect Codex host mechanics and regenerate platform variants + - [x] 5.1 Write 4 focused binding/build tests + - Cover role-port isolation, directive validation, safety-result passthrough, and deterministic source/generated contract parity while Codex remains declared `unsupported`. + - Assert Advisor and Arbiter use separate read-only identities and that normal input cannot select the evidence provider. + - [x] 5.2 Complete the Codex role and receiver binding + - Invoke the shared evaluator through read-only Advisor/Arbiter ports, pass its terminal result through the shared runner/workflow receiver, and return only a validated directive. + - On `continue`, re-read canonical state and begin the acknowledged target in the same active turn; on `user_gate` or `blocked`, expose no hidden continuation. + - [x] 5.3 Project canonical runtime and workflow contracts + - Update adapter templates/build transforms, run `make build`, and inspect generated Codex/Cursor/Kiro changes without hand-editing generated files. + - Keep Codex `fully_automatic: unsupported`; shared and fake-port success cannot activate it. + - [x] 5.4 Validate deterministic build ownership + - Use a repository-local Kiro build lock so differing `TMPDIR` values cannot overlap writes; run two clean `make build` executions, require identical generated manifests, and verify the evidence-only harness is absent from generated/installable plugins. + - [x] 5.5 Ensure the 4 Group 5 tests pass + - Run only `tests/codex-fully-automatic-workflow-loop.test.sh`, affected build assertions, and `tests/host-capability-matrix.test.sh` with the declaration still unsupported. + +**Acceptance Criteria:** + +- The 4 focused tests pass. +- Codex binding code contains host mechanics only; the shared evaluator remains the sole policy state machine. +- Generated variants reproduce from canonical/adapter sources on two consecutive builds with no drift. +- Codex is still declared `unsupported`, and no production CLI, environment, configuration, or workflow value enables evidence bypass. + +### Task Group 6: Native Evidence Bootstrap and Capability Activation + +**Dependencies:** Group 5 +**Files to Modify:** `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh`, `platforms/codex-cli/tests/native-evidence-bootstrap.mjs`, `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml`, `tests/host-capability-matrix.test.sh`, `Makefile`, `docs/codex-support.md` +**Estimated Steps:** 5 + +- [x] 6.0 Prove native behavior before activating capability + - [x] 6.1 Write 3 focused native-evidence tests + - Observe the real Codex entrypoint for agreement, disagreement/one logical Arbiter, same-phase and next-phase continuation, zero UI, resume/deduplication, and durable checkpoints. + - Prove the private test provider bypasses only declaration eligibility, remains test-tree-only, and unavailable native execution exits `77`. + - [x] 6.2 Implement the isolated native evidence bootstrap + - Keep it under `platforms/codex-cli/tests/`, exclude it from builds/installations, and provide no production environment, CLI, config, or workflow selector. + - Leave policy, denylist, state, role, confidence, persistence, dispatch, and directive checks unchanged. + - [x] 6.3 Execute the two-step activation sequence + - First run native evidence to exit `0` while Codex is declared `unsupported` and retain the recorded real-host observations. + - Only in a separate change after that success, set the declaration to `supported`, disable the bootstrap grant for normal execution, rebuild, and rerun native evidence plus the capability matrix. + - If native evidence is unavailable (`77`) or fails, leave/restore `unsupported` and do not mark this group complete. + - [x] 6.4 Ensure the 3 Group 6 tests pass + - Run only `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` and the directly affected capability-matrix targets for the two activation states. + +**Acceptance Criteria:** + +- The 3 focused tests pass against the real Codex entrypoint; exit `77` is handled safely but is not success. +- Evidence succeeds once while declaration remains `unsupported`, then activation occurs as a distinct evidence-backed change. +- The normal supported run passes without the bootstrap grant, and the capability matrix matches source and generated declarations. +- Evidence bootstrap code is absent from every generated/installable plugin and cannot weaken any protected or fail-closed path. + +### Task Group 7: Test Review and Gap Analysis + +**Dependencies:** Groups 1–6 +**Files to Modify:** `tests/gate-evaluator.test.sh`, `tests/orchestrator-state-repository.test.sh`, `tests/orchestrator-state-migration.test.sh`, `tests/workflow-continuation.test.sh`, `tests/phase-continue-contract.test.sh`, `tests/fully-automatic-phase-continue.test.sh`, `tests/codex-fully-automatic-workflow-loop.test.sh`, `tests/host-capability-matrix.test.sh`, `platforms/codex-cli/tests/active-turn-hook.e2e.sh`, `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` +**Estimated Steps:** 5 + +- [x] 7.0 Review and fill critical feature gaps + - [x] 7.1 Review the 25 focused tests from Groups 1–6 + - Map them to R1–R30, the supported migration matrix, policy transitions, crash windows, and activation sequence. + - [x] 7.2 Analyze gaps for this feature only + - Prioritize missing security boundaries, transactional rejection proofs, retry/resume identities, protected-gate behavior, and source/generated parity. + - [x] 7.3 Write up to 9 additional strategic tests + - Keep the feature total within 25–34 tests; do not add exhaustive variants already covered by exact schema tables or equivalent fixtures. + - [x] 7.4 Run the 25–34 feature-specific tests only + - Defer full `make validate` and release-wide checks to implementation verification after group completion. + +**Acceptance Criteria:** + +- All 25–34 feature tests pass. +- No more than 9 strategic tests are added during review. +- Every R1–R30 requirement and every critical crash/safety boundary has direct or explicitly mapped evidence. +- No protected gate, D2/MCP fallback, UI, service, database, or direct generated-tree edit enters the implementation. + +## Execution Order + +1. Group 1 — Codex Active-Turn Hook Viability (5 steps) +2. Group 2 — Schema-v2 State Repository and Migration (6 steps, depends on 1) +3. Group 3 — Shared Gate Evaluator and Policy Compatibility (6 steps, depends on 2) +4. Group 4 — Continuation Runner, Workflow Inventory, and Dispatch (6 steps, depends on 2 and 3) +5. Group 5 — Thin Codex Binding and Deterministic Build Projection (6 steps, depends on 1, 3, and 4) +6. Group 6 — Native Evidence Bootstrap and Capability Activation (5 steps, depends on 5) +7. Group 7 — Test Review and Gap Analysis (5 steps, depends on all previous groups) + +## Standards Compliance + +Follow standards from `.maister/docs/standards/`: + +- `global/build-pipeline.md` — edit canonical sources/adapters, regenerate all variants, and require reproducible generated output. +- `global/coding-style.md`, `global/commenting.md`, and `global/minimal-implementation.md` — focused descriptive modules, sparse timeless comments, immediate callers, and no speculative framework. +- `global/error-handling.md` and `global/validation.md` — exact allowlists, early actionable rejection, bounded retries, fail-closed outcomes, and reliable cleanup. +- `global/conventions.md` — minimal dependencies, documented capability behavior, and unsupported posture until native proof. +- `testing/test-writing.md` — behavior-focused risk depth and byte/mode/permission/topology proofs for rejected transactions. + +## Notes + +- Test-Driven: each implementation group begins with 2–8 focused tests; the review group adds at most 9. +- Run Incrementally: run only each group's new or directly affected tests until final verification. +- Mark Progress: check off both parent and child steps as implementation completes; mirror status in the HTML companion markers. +- Reuse First: preserve strict `phase-continue.mjs` transport/state boundaries, reconciliation failure-injection patterns, canonical workflow sources, build projections, and existing capability matrices. +- Stop Condition: if Group 1 disproves D1, or Group 6 cannot produce native exit `0`, do not silently change architecture or claim support. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/spec.html b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/spec.html new file mode 100644 index 00000000..6bd3f306 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/spec.html @@ -0,0 +1,380 @@ + + + + +Specification — Codex Fully Automatic Continuation + + + + + +
+ Specification +

Codex Fully Automatic Continuation

+

Binding implementation requirements for the accepted A3/B1/C1/D1 repair · Generated 2026-07-13 · Open Markdown twin ↗

+
+ +
+
30requirements
+
14reuse seams
+
4new components
+
Highrisk level
+
+ +
+

TL;DR

+

Maister will execute safe Codex fully_automatic gates through one shared evaluator and a thin Codex binding, without adding a command or UI. Agreement ends with the Advisor's choice; disagreement uses one logical Arbiter, including all bounded retries under that identity. The complete decision is persisted before projections or routing, then a durable workflow-owned dispatch starts the next same-phase item or phase in the active turn. Codex remains unsupported until a real host-native end-to-end test proves the complete no-UI path.

+
+
+

Key Decisions

+
    +
  • Use accepted A3/B1/C1/D1 boundaries.
    • +
  • Keep one canonical executable evaluator.
    • +
  • Evaluator owns the full gate envelope.
    • +
  • Workflow owns inventory, routing, outbox, and receipts.
    • +
  • current_phase is the only mutable phase cursor.
    • +
  • State commits use task-local lock plus revision CAS.
    • +
  • Exactly-once means one logical effect keyed by dispatch_id.
    • +
  • Capability remains unsupported until native evidence succeeds.
    • +
+
+
+

Open Questions / Risks

+
    +
  • RiskThe exact Codex active-turn hook requires a narrow spike; disproving D1 returns work to scope clarification before an MCP fallback.
    • +
  • RiskAmbiguous legacy state migration must fail without changing bytes, permissions, or topology.
    • +
  • RiskA post-effect/pre-ack crash can physically retry, so receiver deduplication is required.
    • +
  • RiskRecovery must resume durable checkpoints without replaying completed roles or logical effects.
    • +
+
+
+
+ +
+
+

In Scope

+
    +
  • Shared evaluator and full terminal provenance.
    • +
  • Schema-v2 state repository and migration.
    • +
  • Workflow-owned same- and next-phase durable dispatch.
    • +
  • Thin Codex active-turn binding.
    • +
  • Canonical/generated parity and native capability evidence.
    • +
+
+
+

Out of Scope

+
    +
  • Protected-gate automation or backward refinement.
    • +
  • New command, UI, daemon, service, database, event store, or speculative SDK.
    • +
  • Codex-only policy or direct generated-tree edits.
    • +
  • Claiming support from shared, fake-port, smoke, or file-presence tests.
    • +
+
+
+ + + +
+
+

Goal

+

Make eligible Codex fully_automatic gates select, persist, route, and begin their next target without user interaction, while preserving Maister's auditability, resumability, protected-gate safety, and cross-platform canonical ownership.

+
+ +
+

User Stories

+
+
Operator

I want safe automatic gates to continue inside my current Codex turn so that I am not asked to approve the recommendation the system is configured to resolve automatically.

+
Operator

I want protected, ambiguous, unsupported, or exhausted decisions to stop safely so that automation never overrides decisions that require me.

+
Workflow maintainer

I want one shared gate state machine and full provenance so that every host applies the same agreement, arbitration, retry, and resume rules.

+
Maintainer

I want stable work and dispatch identities with durable receipts so that I can distinguish one logical continuation from repeated transport attempts.

+
+
+ +
+

Core Requirements

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDRequirementPriority
R1Transparent entry points. Existing maister:* workflows remain the only user entry points; no new command, prompt convention, or UI.Must
R2Eligibility before automation. Run automatically only for configured fully_automatic, configurable, non-denylisted, capability-eligible gates; protected gates stay explicit.Must
R3Stable gate identity and reuse. Derive identity from exact phase, type, question, and ordered options; reuse terminal state before roles, UI, or dispatch.Must
R4Exact gate context. Accept only stable identity, ordered options, recommendation, safety, phase, and read-only workflow context; reject unknown, malformed, duplicate, or unsafe data.Must
R5Durable pending and attempts. Persist one envelope pending→terminal with role identities/models, attempts, responses/errors, exhaustion, and timestamps before dependent effects.Must
R6Strict role response. Require exactly four fields, a legal option, and configured bounded retry/backoff for invalid or transient responses.Must
R7Agreement. Matching recommendations produce final_actor: advisor, Advisor once, Arbiter zero, user gate zero, then automatic continuation.Must
R8Disagreement. Create exactly one logical Arbiter; all retries use it, Advisor is not repeated, and a valid result ends with actor arbiter.Must
R9Arbiter boundary. Supply the two competing choices/rationales; permit only one of them or escalation, never mutation or scope growth.Must
R10Fail closed. Manual, unsafe, unsupported, invalid, low-confidence, escalated, exhausted, conflicting, or failed paths return only safe user_gate/blocked and advance nothing.Must
R11Persistence ordering. Commit the complete terminal record before projections, applied selection, phase/cursor changes, outbox, or dispatch; projections never drive resume.Must
R12Schema v2. Enforce the normative field placement, enums, nullability, timestamps, invariants, and gate/work/dispatch transitions below; exactly one current_phase is in progress.Must
R13Safe migration. Migrate only the matrix's supported shapes in one locked commit to revision 1; preserve complete or explicitly legacy non-authorizing provenance and reject every named ambiguity before mutation.Must
R14Transactional repository. Follow the platform-bounded owner-token lock, CAS, symlink, atomic replacement, mode/safe-ownership, stale-lock, timeout, and cleanup rules below.Must
R15Runner responsibility. Re-read and verify the terminal record and legal transition; recover projections/commit, but never call roles, synthesize provenance, route domain work, or dispatch.Must
R16Same-phase continuation. Use stable inventory/work IDs; idempotently complete the source, preserve its choice/gate, identify next ready work, and create deterministic dispatch.Must
R17Next-phase continuation. Commit the forward transition and a phase-entry dispatch; require an observable target checkpoint beyond phase state or stdout.Must
R18Logical dispatch. Use pending → claimed → acknowledged|blocked; atomically establish target checkpoint and acknowledgement as the sole logical start effect, and return stored acknowledgement on retry.Must
R19Active-turn directive. Binding returns only continue | user_gate | blocked; continue immediately starts acknowledged work in the same turn without final response or question.Must
R20Equivalent phase-entry proof. Accept explicit user evidence or matching terminal auto decision + applied transition + receipt + checkpoint; never apply equivalence to protected gates.Must
R21Resume and dedupe. Never duplicate terminal history, completed Advisor, logical Arbiter, applied choice, logical dispatch, or ack; reconcile pending attempts by retry rules.Must
R22Compatibility. Follow normative manual/advisor/override/fallback/user_pending transitions while preserving denylist, forward-only, report recovery, immutable choice, and fallback semantics.Must
R23Canonical ownership. Shared runtime under plugins/maister/, Codex mechanics under platforms/codex-cli/, generated trees only via deterministic build; contracts stay equivalent.Must
R24Capability evidence. A non-packaged native-E2E bootstrap bypasses only declaration eligibility; first prove real native exit 0 while unsupported, then separately set supported and rerun normal matrix eligibility. Unavailable stays 77.Must
R25Security. Keep roles read-only, model output as data, paths inside task root, reject symlink/traversal, and retain provenance without secrets or unnecessary prompts.Must
R26Gate envelope completeness. Require every named identity, policy, safety, role, selection, actor, provenance, continuation, and timestamp field; terminal decisions are immutable except idempotent completion.Must
R27Dispatch claim recovery. Claim atomically with owner token/lease; start no target while merely claimed; safely reclaim expired claims with the same ID; post-ack crash returns stored ack.Must
R28Mixed-policy records. Manual has no roles; Advisor mode persists agreement/disagreement analysis before user pending; user commits actor user and exact override; unsupported automatic records manual fallback.Must
R29Evidence-bootstrap isolation. Test-harness only, excluded from generated/installable plugins, no environment/CLI/config/workflow switch, real Codex entrypoint, and no safety bypass.Must
R30Platform-bounded filesystem behavior. Define lock/symlink/mode/safe-ownership/timeout/stale-owner/cleanup/durability on macOS/Linux without privileged ownership assumptions or uncertain lock breaking.Must
+
+ +
+

Reusable Components

+
+ + + + + + + + + + + + + + + + + + +
Existing elementLeverage
plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjsRetain strict transport, allowlists, parser, hashing, denylist, report recovery, transition guards, and stdout contract; verify full records through the repository.
.../references/gate-decision-engine.mdSynchronize the normative human-readable policy with the executable evaluator.
.../references/orchestrator-patterns.mdExtend canonical state, phase, gate, dashboard, safety, and phase-entry conventions.
plugins/maister/skills/init/bin/reconcile-advisor-config.shReuse transactional guarantees and tests, not its config-specific parser or two-file transaction.
plugins/maister/skills/research/SKILL.mdFirst stable-inventory, same-phase tracer.
development/SKILL.md, migration/SKILL.md, performance/SKILL.mdConsume shared terminal/dispatch evidence while retaining domain routing.
product-design/SKILL.mdAdopt forward continuation evidence; exclude backward refinement.
platforms/codex-cli/templates/advisor.tomlPreserve read-only roles and exact four-field response; align host-port wording and Arbiter identity.
platforms/codex-cli/build.shProject shared runtime and thin binding; never patch generated output.
Makefile, tests/host-capability-matrix.test.shExtend source/generated matrices and preserve native-evidence distinction including exit 77.
tests/phase-continue-contract.test.sh, tests/fully-automatic-phase-continue.test.shMigrate full-record/schema fixtures while preserving runner regressions.
tests/advisor-config-reconciliation.test.sh, tests/advisor-init-lifecycle.test.shReuse byte, mode, topology, rollback, and injection assertions.
tests/codex-fully-automatic-workflow-loop.test.shMake the failing agreement/disagreement and durable-dispatch tracer pass through production.
platforms/codex-cli/tests/fully-automatic-continuation.e2e.shUse only as the real Codex entrypoint evidence target, never a shared-runtime surrogate.
+
+ +

New Components Required

+
+ + + + + + + + +
ComponentWhy new
Shared executable gate evaluatorPolicy is prose-only and the runner starts after selection; this directly called FSM owns role calls, agreement, one logical Arbiter, retry/resume, and provenance.
Narrow schema-v2 state repository and migratorNo existing shared writer supplies lock, CAS, complete invariants, durable metadata-preserving replacement, and legacy migration for evaluator and runner.
Workflow continuation inventory/outbox contractNo current structure identifies same-phase work, binds a choice to its next target, or records durable acknowledgement; shared shape remains separate from domain routing.
Thin Codex automatic-gate binding and receiver seamNo executable active-turn consumer connects native roles, shared runtime, target dispatch, UI-free directive, and dedupe. It contains host mechanics only.
+
+
+ +
+

Technical Approach

+
+ Component boundaries and flow +

A workflow invokes the shared evaluator through a Codex-supplied read-only role port. The evaluator creates or resumes one envelope, calls Advisor, and commits agreement or advances that envelope to one logical Arbiter. The runner verifies the terminal record and commits projections/forward transition. The workflow applies the choice and creates the next target/outbox entry; the Codex binding dispatches it. The receiver records checkpoint and acknowledgement before continue returns to the workflow loop.

+

The evaluator selects; repository commits; runner projects and performs forward phase commits; workflow routes; binding invokes host roles and dispatches. No boundary absorbs another's policy or domain responsibilities.

+
+
+ State and recovery model +

One YAML snapshot adds schema version, revision, initial and current phase, full gate provenance, stable inventory, and typed outbox. One gate key identifies one updated envelope; one Arbiter ID spans retries; one dispatch ID binds one source to one target.

+

Each change is a short commit. Locks are released for model calls and dispatch; callers then reacquire, compare revision, reread on conflict, and resolve by idempotency. Recovery independently completes projections, selection, outbox, dispatch, or acknowledgement without rolling back terminal decisions or replaying completed roles.

+
+
+ Normative schema-v2 contract +

The root has exactly one orchestrator, task, and ordered phases. Orchestrator requires schema version 2, non-negative revision, immutable initial phase, canonical current phase, unique completed/failed IDs, gate history, work, and outbox. Current phase names exactly one in_progress phase; every phase-list ID exists and matches status.

+

Every gate requires schema/key/phase/type/question/ordered options/recommendation, configured and effective policy, safety, status, selection, actor, rationale, confidence, escalation, override, error, Advisor, Arbiter, continuation, provenance kind, legacy record, and created/updated/decided timestamps. Policies: manual | advisor | fully_automatic; statuses: advisor_pending | arbiter_pending | user_pending | decided | blocked; actors: system | advisor | arbiter | user; confidence: high | medium | low | null. New timestamps are UTC RFC 3339; selection is null before decided and then exactly one option; pending/blocked actor is system.

+

Advisor and Arbiter mappings always exist with nullable logical ID/agent/model/response plus attempts and exhausted. Responses have exactly four fields. Attempts use started | completed | failed | interrupted, positive unique number, started timestamp, and terminal completion timestamp. One Arbiter ID spans all retries and activates only after completed Advisor disagreement.

+

Native records use complete provenance and null legacy record. Migrated narrow terminal records use legacy provenance, preserve the exact old mapping, and may support audit/report/exact lookup but cannot authorize a new effect. Inventory items use stable ID/ordinal and only ready → in_progress → completed|blocked, with idempotent self-reuse; completion requires terminal source gate and legal applied selection.

+
+
+ Supported legacy migration matrix + + + + + + + + + + + +
InputMappingReject when
Already v2Validate exactly; no migration/revision change.Unknown schema, invalid revision/field/enum/invariant/identity.
Legacy with current phaseRequire sole in-progress match; initial from valid started phase else first ordered phase; remove started phase; revision 1.Absent/multiple in-progress, mismatch, invalid started phase.
Legacy with started but no currentDerive current only from sole in-progress; started becomes immutable initial; revision 1.Current cannot be unique or started is invalid.
Empty historyCreate empty v2 history, work, and outbox.Misplaced/duplicate anchors.
Rich legacy gatePreserve choices, actor, policy, roles, models, attempts, rationale/errors; derive missing stable role IDs; complete only with complete actor provenance.Actor/response conflict, illegal option, duplicate key, ambiguous unfinished attempt.
Narrow terminal gatePreserve exact mapping as legacy/non-authorizing audit record.Nonterminal, illegal/changed selection, incomplete identity.
Complete user-pending gatePreserve policy/recommendation/analysis, normalize null terminal fields, resume same user gate.Preselected option, terminal actor, conflicting pending override.
+

Migration is one locked atomic commit to schema 2/revision 1. Duplicate YAML, unsupported features, unknown shapes, phase conflicts, duplicate IDs, invalid timestamps, unsafe paths, or lossy mapping fail before mutation. No model response, rationale, user choice, or completed attempt is fabricated.

+
+
+ Normative policy transitions + + + + + + + + + + +
ConditionRequired behavior
ManualCreate/reuse user pending with no roles and null selection; user commits decided/actor user.
Advisor agreementAdvisor pending → user pending; persist and present original/Advisor recommendations; user decides.
Advisor disagreementAdvisor pending → one Arbiter pending → user pending; persist/present all analysis; user decides.
User overrideTrue exactly when user differs from latest valid machine recommendation: Arbiter, else Advisor, else original.
Unsupported automaticKeep configured fully automatic, set effective manual, record fallback, enter user pending, never dispatch.
Resume user pendingReuse identity/analysis without repeating completed roles; commit one user decision or stay pending.
+
+
+ Dispatch claim, checkpoint, and acknowledgement +

Outbox requires dispatch/source/kind/phase/target/status/attempts, claim token/time/lease, checkpoint, acknowledgement time, and error. Forward states are only pending → claimed → acknowledged|blocked; unchanged retries are idempotent.

+

Claim is an atomic commit with unpredictable token and bounded lease and starts no work. The sole logical start effect is one atomic commit that establishes target in_progress checkpoint and acknowledged outbox status together. Only then may binding return continue and execute the body. Crash while claimed has no effect and may reclaim after safely classified expiry using the same ID. Crash after acknowledgement commit but before observation returns the stored acknowledgement—never a second checkpoint/start. Blocked is pre-ack only; identities remain immutable; unexpired claims cannot be stolen.

+
+
+ Platform-bounded repository contract +

The lock is an atomically created sibling directory with random token, PID, host, acquisition time, and expiry. Acquisition has a bounded timeout. Release/cleanup require the token. Reclaim requires an expired, valid owner record and proof that its same-host process is dead; live, foreign, malformed, or uncertain locks are never broken, and cleanup cannot remove a successor lock.

+

Canonicalize task/state/lock/report paths, all existing parents, and targets; reject symlinks and require a regular state file. Stage in the state directory. Preserve mode exactly; preserve ownership only when already held or safely settable on the staged file, otherwise abort before replace—never unconditional privileged chown. Flush file before rename and directory where supported by Node on macOS/Linux, documenting unsupported durability evidence. Clean only token-owned lock/temp artifacts.

+
+
+ Native evidence bootstrap and two-step activation +

The bootstrap lives only under platforms/codex-cli/tests/, is excluded from build/install, and calls the real Codex plugin/skill entrypoint with a private test eligibility provider. No production CLI option, environment flag, config key, or workflow instruction selects it. It changes only declaration eligibility; denylist, policy, validation, roles, confidence/escalation, persistence, dispatch, and no-UI checks remain production-identical.

+

Step 1: while declared unsupported, run the native target directly through the bootstrap; real evidence exits 0 and unavailable exits 77. Step 2: separately declare supported, disable the grant for normal execution, and rerun native target plus matrix through ordinary eligibility. Any failure leaves/restores unsupported; fake/shared tests never substitute.

+
+
+ Compatibility and rollout +

Introduce schema and shared contracts before workflow adoption; use research decision areas as the first same-phase tracer; migrate remaining workflows without changing entry points. Rebuild committed variants and keep source/generated matrices green.

+

Integrate fake-port Codex tests while capability remains unsupported. Change the declaration only after native evidence. If the D1 active-turn spike fails, pause for a scope decision before MCP.

+
+
+ Safety +

Evaluator and runner both enforce denylist and exact option/actor/confidence contracts. Roles receive read-only context and no mutable handles; paths stay in the task root; model output is data; retry is bounded; low confidence/escalation cannot be suppressed; protected gates never dispatch automatically.

+
+
+ +
+

Implementation Guidance

+
+ Testing approach +
    +
  • Approximately six groups: evaluator; repository/migration; runner; workflow dispatch; Codex binding/build; native evidence.
    • +
  • Add 2–8 behavior-focused tests per implementation step group; run only new/directly affected tests during the group, then the full matrix at integration/final verification.
    • +
  • Preserve the red tracer and assert role counts, actors, state, receipts, checkpoints, and zero user gates.
    • +
  • Cover role retry/resume and failures plus manual, Advisor agreement/disagreement, user override, fallback, and user-pending resume.
    • +
  • Exercise every migration row/rejection; for rejected/injected writes assert byte-exact state/reports, modes, permissions, and topology.
    • +
  • Cover timeout, live/expired/malformed/foreign locks, token cleanup, symlinks, mode/safe ownership, stale revision, and platform directory durability.
    • +
  • Inject post-checkpoint/ack commit but pre-observation failure: retry returns stored ack with one checkpoint/start; also test claimed-only crash and same-ID lease reclaim.
    • +
  • Prove evidence bootstrap absent from built/installed plugin and unreachable by environment/config/CLI/workflow; run unsupported-evidence then supported-matrix activation.
    • +
  • Validate canonical/generated runtimes after a clean double build; keep native E2E distinct and preserve exit 77 when unavailable.
    • +
+
+
+ Standards compliance +
    +
  • .maister/docs/standards/global/build-pipeline.md: canonical/adapter edits, regenerated variants, deterministic validation.
    • +
  • coding-style.md, commenting.md, minimal-implementation.md: focused names/functions, timeless sparse comments, no speculative components.
    • +
  • error-handling.md, validation.md: early exact allowlists, actionable errors, bounded backoff, cleanup, fail-closed handling.
    • +
  • conventions.md: minimal dependencies, documented behavior, unsupported capability posture until proof.
    • +
  • testing/test-writing.md: visible behavior and byte/mode/permission/topology guarantees for rejected transactions.
    • +
+
+
+ +
+

Out of Scope

+
    +
  • Product-design backward refinement, backward transitions, or a general reset protocol.
    • +
  • Automation of implementation approval, final handoff, rollback, production, scope expansion, data-integrity halt, unresolved verification, failure-recovery skip, or other protected gates.
    • +
  • A new command, UI, dashboard authority, or changed journey beyond removing unnecessary auto-gate prompts.
    • +
  • A daemon, service, database, event store, generalized persistence, or MCP unless D1 is disproved and separately approved.
    • +
  • Codex-only evaluation, duplicated policy, or direct generated edits.
    • +
  • Support claims from shared tests, fake integration, smoke, file presence, or runner success.
    • +
  • Unrelated workflow redesign or a generic work-item SDK beyond immediate callers.
    • +
+
+ +
+

Success Criteria

+
    +
  • Agreement: actor Advisor, Advisor once, Arbiter zero, user gate zero, acknowledged next checkpoint.
    • +
  • Disagreement: one logical Arbiter across retries, no repeated Advisor, legal competing option, zero UI, acknowledged target.
    • +
  • Full terminal provenance exists before projections or continuation.
    • +
  • Same-phase source completes and stable next work begins in the same active turn.
    • +
  • Next-phase flow establishes a real target checkpoint beyond state/stdout.
    • +
  • Resume duplicates no gate, completed role, Arbiter identity, applied choice, dispatch effect, checkpoint, or ack; post-commit retry returns stored ack.
    • +
  • All unsafe/failing paths advance nothing and return only safe user-gate or blocked directives.
    • +
  • Schema v2 enforces every required field, enum, nullability/timestamp, actor/provenance invariant, and gate/work/dispatch transition.
    • +
  • Every supported matrix shape migrates once to revision 1 without loss; named ambiguities preserve bytes, modes, permissions, reports, and topology.
    • +
  • Manual, both Advisor paths, override, fallback, and user-pending resume create exact v2 records without duplicate role/user decisions.
    • +
  • Stale writers cannot overwrite; uncertain locks time out unchanged; owner tokens protect successor locks; each legal commit increments once.
    • +
  • Symlinks reject, mode stays exact, safe ownership is preserved, and impossible metadata restoration fails before replace on macOS/Linux.
    • +
  • Runner recovers projections/transitions from full terminal state without roles or reconstructed provenance.
    • +
  • Manual/advisor policies, override, denylist, forward-only, report recovery, and immutable terminal choice remain green.
    • +
  • Build projects runtime/binding deterministically; second clean build and source/generated matrices pass.
    • +
  • Evidence provider is absent from built/installed plugins, unreachable normally, bypasses declaration only, and retains all safety.
    • +
  • Codex is unsupported for the first native exit 0; separate activation sets supported and reruns native target/matrix normally; unavailable stays 77.
    • +
  • Native E2E observes real Codex, both decision paths, one Arbiter, same/next targets, zero UI, resume, dedupe, and checkpoints.
    • +
  • No new command, UI, service, database, speculative abstraction, or direct generated edit.
    • +
+
+
+ + diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/spec.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/spec.md new file mode 100644 index 00000000..4111cdc1 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/spec.md @@ -0,0 +1,235 @@ +# Specification: Codex Fully Automatic Continuation + +## TL;DR + +Maister will execute safe Codex `fully_automatic` gates through one shared evaluator and a thin Codex binding, without adding a command or UI. +Agreement ends with the Advisor's choice; disagreement uses one logical Arbiter, including all bounded retries under that identity. +The complete decision is persisted before projections or routing, then a durable workflow-owned dispatch starts the next same-phase item or phase in the active turn. +Codex remains `unsupported` until a real host-native end-to-end test proves the complete no-UI path. + +## Key Decisions + +- Use the accepted A3/B1/C1/D1 architecture — it separates shared decision semantics, durable state, workflow routing, and host mechanics. +- Keep one executable evaluator in the canonical orchestrator framework — Codex must not acquire a separate policy implementation. +- Make the evaluator own the complete pending-to-terminal gate envelope — the runner verifies persisted provenance instead of reconstructing it. +- Keep work inventory, target selection, outbox, and receipts workflow-owned — the runner remains domain-agnostic. +- Use `orchestrator.current_phase` as the only mutable phase cursor — schema migration removes the current split meaning with `started_phase`. +- Serialize state commits with a task-local lock and revision compare-and-swap — evaluator and runner are sequential writers to one authoritative YAML snapshot. +- Treat exactly-once as one logical effect — physical dispatch may retry only with the same stable `dispatch_id`, and the receiver deduplicates it. +- Keep the Codex capability declaration `unsupported` until real native evidence exits successfully — fake-port and shared contract tests are necessary but insufficient. + +## Open Questions / Risks + +- The exact Codex active-turn hook must be demonstrated by a narrow implementation spike. If D1 is empirically impossible, work stops for scope clarification before considering the researched MCP fallback. +- Legacy state can contain `started_phase`, no revision, and gate records of different richness. Ambiguous migration must fail closed without changing bytes, permissions, or directory topology. +- A crash after a dispatch effect but before its acknowledgement can cause a physical retry; correctness depends on receiver deduplication by the original `dispatch_id`. +- State, report, phase, and dispatch crash windows cross multiple commits. Recovery must resume the last durable checkpoint without replaying completed role calls or logical effects. + +## Goal + +Make eligible Codex `fully_automatic` gates select, persist, route, and begin their next target without user interaction, while preserving Maister's auditability, resumability, protected-gate safety, and cross-platform canonical ownership. + +## User Stories + +- As a Maister workflow operator, I want safe automatic gates to continue inside my current Codex turn so that I am not asked to approve the recommendation the system is configured to resolve automatically. +- As a Maister workflow operator, I want protected, ambiguous, unsupported, or exhausted decisions to stop safely so that automation never overrides decisions that require me. +- As a workflow maintainer, I want one shared gate state machine and full provenance so that every host applies the same agreement, arbitration, retry, and resume rules. +- As a maintainer diagnosing interruption or retry, I want stable work and dispatch identities with durable receipts so that I can distinguish one logical continuation from repeated transport attempts. + +## Core Requirements + +1. **R1 — Transparent entry points (must):** Existing `maister:*` workflow invocations remain the only user entry points. The repair introduces no new command, prompt convention, or UI. +2. **R2 — Eligibility before automation (must):** Automatic evaluation runs only when the configured policy is `fully_automatic`, the gate is configurable and not denylisted, and the host capability path is eligible. Protected and denylisted gates remain explicit user decisions. +3. **R3 — Stable gate identity and reuse (must):** The runtime derives a deterministic idempotency key from the exact phase, gate type, question, and ordered options, and reuses a matching terminal record before invoking a role, presenting a user gate, or dispatching work. +4. **R4 — Exact gate context (must):** The evaluator receives an allowlisted context containing stable gate identity, ordered options, original recommendation, safety classification, phase identity, and read-only workflow context. Unknown, malformed, duplicate, or unsafe data is rejected. +5. **R5 — Durable pending and attempts (must):** The evaluator persists one gate envelope from pending through terminal state. Role identities, models, each bounded attempt, response or error, retry exhaustion, and timestamps are durable before later effects depend on them. +6. **R6 — Strict role response contract (must):** Advisor and Arbiter responses contain exactly `selected_option`, `rationale`, `confidence`, and `escalate_to_user`; the selected option must be legal and all invalid or transient responses follow configured bounded retry and backoff rules. +7. **R7 — Agreement behavior (must):** When the original recommendation and valid Advisor recommendation agree, the gate becomes terminal with `final_actor: advisor`; the Advisor is invoked once, the Arbiter is not invoked, no user gate is shown, and continuation proceeds automatically. +8. **R8 — Disagreement behavior (must):** When the original and Advisor recommendations differ, the evaluator creates exactly one logical Arbiter identity. All Arbiter retries belong to that identity, the Advisor is not re-invoked, and the terminal actor is `arbiter` when a valid confident result is obtained. +9. **R9 — Arbiter choice boundary (must):** The Arbiter receives the two competing choices and their rationales and may select only one of those choices or escalate. It cannot invent an option, mutate artifacts, or broaden scope. +10. **R10 — Fail-closed outcomes (must):** Manual or denylisted gates, unsupported capability, invalid state or role output after retries, low confidence, explicit escalation, exhausted roles, lock or revision conflict that cannot be reconciled, unsafe transition, or persistence failure returns `user_gate` when an interactive safe path exists and otherwise `blocked`. No work cursor, phase, outbox, or receipt advances. +11. **R11 — Persistence ordering (must):** The complete terminal gate record is committed before decision reports, dashboard data, selection application, cursor or phase changes, outbox creation, or dispatch. Reports remain projections of canonical state and never drive resume. +12. **R12 — Canonical schema v2 (must):** Authoritative state uses the exact field placement, enums, nullability, timestamp rules, and invariants in the Normative Schema-v2 Contract below. `current_phase` identifies exactly one `in_progress` phase; gate, work-item, and dispatch states follow only their declared transitions. +13. **R13 — Safe state migration (must):** Only the legacy shapes in the Supported Legacy Migration Matrix migrate. Migration is one locked atomic commit with output `schema_version: 2` and `revision: 1`; it preserves every legacy record either as complete v2 provenance or an explicitly legacy, non-authorizing record. Every listed rejection fails before mutation with actionable diagnostics. +14. **R14 — Transactional state repository (must):** Every legal commit follows the Platform-bounded Repository Contract below: validate under an owner-token lock, compare revision, increment once, reject symlinks, stage/flush/replace within the state directory, preserve mode and safely preservable ownership, and clean up only artifacts owned by the caller. Rejection, timeout, stale-lock uncertainty, metadata failure, or injected failure preserves bytes, modes, and topology. +15. **R15 — Runner responsibility (must):** The shared continuation runner re-reads and verifies the evaluator-owned terminal record, idempotency key, selected option, actor, confidence, revision, denylist, and optional forward transition. It may recover projections or a legal phase commit but does not call roles, synthesize provenance, choose domain work, or dispatch it. +16. **R16 — Same-phase continuation (must):** A workflow with sequential decision areas materializes stable work-item identities and an inventory version. Applying a terminal choice idempotently completes the source item, preserves its choice and source gate, identifies the next ready item, and creates a deterministic same-phase dispatch intent. +17. **R17 — Next-phase continuation (must):** A legal forward transition completes the source phase, starts the target phase, updates `current_phase`, and creates a phase-entry dispatch. Success requires an observable target-phase checkpoint; phase status mutation or runner stdout alone is not proof that the phase body started. +18. **R18 — Durable logical dispatch (must):** Each outbox entry binds one source gate to one target with a stable `dispatch_id`, target kind, phase, and target identity and follows `pending → claimed → acknowledged|blocked`. The receiver's only logical start effect is the atomic commit that establishes the target checkpoint and acknowledgement together; retry reuses the same ID and returns an existing acknowledgement without starting the target twice. +19. **R19 — Active-turn directive (must):** The thin Codex binding validates shared runtime results and returns only `continue`, `user_gate`, or `blocked`. A valid `continue` causes the workflow loop to re-read canonical state and immediately begin the acknowledged target in the same active Codex turn, without emitting a final response or user question between targets. +20. **R20 — Equivalent phase-entry proof (must):** Workflow phase-entry guards accept either the existing explicit user-gate evidence or a matching terminal automatic gate plus applied transition, dispatch receipt, and target checkpoint. This equivalence never applies to protected gates. +21. **R21 — Resume and deduplication (must):** Resume never duplicates a terminal history record, completed Advisor call, logical Arbiter identity, applied choice, logical dispatch effect, or acknowledged target. Pending attempts are reconciled according to retry rules, and completed durable checkpoints are reused. +22. **R22 — Existing-policy compatibility (must):** Manual, Advisor-assisted, user override, unsupported-automatic fallback, and `user_pending` resume follow the Normative Policy Transitions below. Hard denylist behavior, forward-only transitions, report recovery, immutable terminal selection, and interactive fallback retain their existing safety semantics. +23. **R23 — Canonical and generated ownership (must):** Shared semantics and runtime live under `plugins/maister/`; Codex-only mechanics live under `platforms/codex-cli/`; generated platform trees are changed only by deterministic build projection. Source and generated runtime contracts remain equivalent. +24. **R24 — Capability evidence (must):** Codex remains declared `unsupported` throughout shared implementation and fake-port integration. A repository-owned, non-packaged native-E2E bootstrap may bypass only declaration eligibility while retaining denylist, policy, state, role, and dispatch checks; normal workflows cannot invoke or configure that bypass. Activation is two-step: native evidence exits `0` while declaration is still unsupported, then a separate change sets `supported` and reruns the capability matrix through normal eligibility. Runtime unavailability remains exit `77`. +25. **R25 — Security boundaries (must):** Role contexts remain read-only; model output is treated only as data; state and report paths are canonicalized within the task root; symlink and traversal attacks are rejected; logs and projections retain necessary provenance without copying secrets or unnecessary full prompts. +26. **R26 — Gate-envelope completeness (must):** Every v2 gate record contains the required identity, policy, safety, recommendation, status, actor, selection, confidence, escalation, override, error, Advisor, Arbiter, continuation, and timestamp fields defined below. A `decided` record is immutable except for idempotent projection/continuation completion. +27. **R27 — Dispatch claim recovery (must):** Claiming is an atomic repository commit with an owner token and bounded lease. No target work begins while an entry is merely `claimed`; recovery may reclaim only an expired, safely classified claim and always retains the same `dispatch_id`. A crash after the acknowledged checkpoint commit but before the caller observes it returns that stored acknowledgement on retry. +28. **R28 — Mixed-policy records (must):** `manual` creates `user_pending` without role calls; `advisor` persists Advisor and, on disagreement, Arbiter analysis before `user_pending`; a user response commits `decided` with `final_actor: user`; `user_override` is true exactly when the user's selection differs from the latest machine recommendation. Unsupported `fully_automatic` persists its configured policy and records effective manual fallback. +29. **R29 — Evidence-bootstrap isolation (must):** The native evidence bootstrap exists only under the platform test harness, is excluded from generated/installable plugins, has no environment-variable or production-CLI switch, and invokes the real Codex entrypoint with a test-only eligibility provider. It cannot bypass the hard denylist or convert any unsafe result to `continue`. +30. **R30 — Platform-bounded filesystem behavior (must):** Lock, symlink, metadata, timeout, stale-owner, cleanup, and directory-durability semantics are explicit for supported macOS/Linux Node runtimes. The repository never unconditionally requires privileged ownership changes and never breaks or removes a lock it cannot prove stale and owned under the declared rules. + +## Reusable Components + +### Existing Code to Leverage + +| Existing element | What it provides | Required leverage | +|---|---|---| +| `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` | Duplicate-key-aware JSON transport, exact allowlists, canonical YAML validation, deterministic hashing, denylist checks, report recovery, forward-transition guards, JSON-only stdout | Retain these strict boundary behaviors while changing the runner to verify a full persisted terminal record and use the shared repository. | +| `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` | Normative policy, response schema, retry, agreement, arbitration, denylist, idempotency, and persistence-order contract | Keep documentation synchronized with the executable evaluator; it remains the human-readable contract, not an alternate implementation. | +| `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` | Shared phase, state, gate, dashboard, and safety conventions | Extend the canonical schema and phase-entry proof without duplicating workflow-specific variants. | +| `plugins/maister/skills/init/bin/reconcile-advisor-config.sh` | Same-directory staging, preflight, no-op and mode preservation, backup/restore, rollback, and injected-failure patterns | Reuse its transactional guarantees and test style for state commits; do not reuse its config-specific parser or two-file transaction directly. | +| `plugins/maister/skills/research/SKILL.md` | Sequential, dependency-sensitive decision areas that expose the same-phase defect | Use as the first workflow tracer for stable inventory and automatic dispatch to the next decision area. | +| `plugins/maister/skills/development/SKILL.md`, `plugins/maister/skills/migration/SKILL.md`, and `plugins/maister/skills/performance/SKILL.md` | Existing gate call sites, phase routing, and entry self-checks | Consume the shared terminal/dispatch contract while leaving domain-specific routing in each workflow. | +| `plugins/maister/skills/product-design/SKILL.md` | Sequential decision-area behavior and forward phase gates | Adopt the shared forward continuation evidence; backward refinement remains outside this repair. | +| `platforms/codex-cli/templates/advisor.toml` | Read-only Codex role profile and exact four-field response expectation | Preserve read-only role constraints and align the text with the executable host port and separate Arbiter identity. | +| `platforms/codex-cli/build.sh` | Canonical skill copying, host vocabulary transforms, generated plugin assembly, and capability-matrix checks | Project the shared runtime and thin binding deterministically into `plugins/maister-codex/`; do not patch generated files directly. | +| `Makefile` and `tests/host-capability-matrix.test.sh` | Source/generated runner matrix and evidence-based capability projection, including exit `77` | Extend validation matrices while preserving the distinction between shared tests and native host evidence. | +| `tests/phase-continue-contract.test.sh` and `tests/fully-automatic-phase-continue.test.sh` | Strict runner transport, state rejection, idempotent reuse, report recovery, denylist, and transition assertions | Migrate fixtures to the full-record/schema-v2 contract and retain regression coverage for existing behavior. | +| `tests/advisor-config-reconciliation.test.sh` and `tests/advisor-init-lifecycle.test.sh` | Byte, mode, rollback, directory-topology, and failure-injection assertions | Reuse these assertion patterns for repository, migration, and interrupted commit coverage. | +| `tests/codex-fully-automatic-workflow-loop.test.sh` | The failing behavioral tracer for agreement, single-Arbiter disagreement, no user gate, durable same-phase dispatch, and acknowledgement | Make this test pass through the production binding without weakening its observable behavior checks. | +| `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` | The authoritative native capability target and correct unavailable exit | Replace the placeholder only with a real Codex entrypoint harness; it cannot be satisfied by invoking the shared Node runtime alone. | + +### New Components Required + +| New component | Why existing code cannot supply it | +|---|---| +| Shared executable gate evaluator | Decision behavior currently exists only as prose, while the runner starts after selection. A directly called shared state machine is required to own role invocation, agreement, one logical Arbiter, retry/resume, and terminal provenance. | +| Narrow schema-v2 state repository and migrator | The current runner performs isolated text replacement and has no shared lock, revision/CAS, complete invariant validation, mode-preserving durable replacement, or versioned legacy migration for two writers. This component is limited to orchestrator state and has immediate evaluator/runner/workflow callers. | +| Workflow continuation inventory/outbox contract | No existing structure identifies same-phase work, binds a gate choice to the next target, or records dispatch acknowledgement. The common record shape is shared, while each workflow continues to own its domain inventory and routing. | +| Thin Codex automatic-gate binding and dispatch receiver seam | Codex currently has a read-only role profile and generated instructions but no executable active-turn consumer connecting roles, shared runtime, workflow target, UI-free directive, and receiver deduplication. It must contain host mechanics only. | + +## Technical Approach + +### Component Boundaries and Flow + +The repair follows the accepted ports-and-adapters boundary. A workflow creates an exact gate context and invokes the shared evaluator through a Codex-supplied read-only role port. The evaluator creates or resumes one durable gate envelope, calls the Advisor, and either commits agreement or advances the same envelope to one logical Arbiter. The shared runner verifies the terminal record and commits projections and any legal forward phase transition. The workflow then applies the selected option, creates the next target and outbox entry, and asks the Codex binding to dispatch it. The receiver records a checkpoint and acknowledgement before the binding returns `continue` to the active workflow loop. + +The evaluator selects; the repository commits authoritative state; the runner projects and performs forward phase commits; the workflow routes; the Codex binding invokes host roles and dispatches. None of these boundaries may absorb another's policy or domain responsibilities. + +### State and Recovery Model + +State remains one project-local YAML snapshot. Schema v2 adds `schema_version`, `revision`, `initial_phase`, canonical `current_phase`, complete gate role provenance, stable workflow inventory, and typed dispatch outbox records. One idempotency key identifies one gate envelope updated in place; one logical Arbiter ID spans its retries; one dispatch ID binds one source gate to one target. + +Every state change is a short repository commit. Locks are released during model calls and host dispatch. After either external operation, the caller reacquires the lock, checks revision, re-reads state on conflict, and resolves through idempotency instead of overwriting. Recovery independently completes missing projections, selection application, outbox creation, dispatch, or acknowledgement from the last durable checkpoint. It does not roll back a valid terminal decision or replay completed role work. + +### Normative Schema-v2 Contract + +The root contains exactly one `orchestrator` mapping, one `task` mapping, and one ordered `phases` sequence. `orchestrator` requires `schema_version: 2`, non-negative integer `revision`, stable `initial_phase` and `current_phase`, unique `completed_phases` and `failed_phases`, `gate_history`, `work`, and `dispatch_outbox`. `initial_phase` never changes. `current_phase` names exactly one phase whose status is `in_progress`; every completed/failed ID exists in `phases` and matches its phase status. + +Each gate envelope requires: `schema_version`, `idempotency_key`, `phase_id`, `gate_type`, exact `question`, unique ordered `options`, `original_recommendation`, `configured_policy`, effective `policy`, `safety_classification`, `status`, `selected_option`, `final_actor`, `rationale`, `confidence`, `escalate_to_user`, `user_override`, `error`, `advisor`, `arbiter`, `continuation`, `provenance_kind`, `legacy_record`, `created_at`, `updated_at`, and `decided_at`. Policies are `manual | advisor | fully_automatic`; statuses are `advisor_pending | arbiter_pending | user_pending | decided | blocked`; actors are `system | advisor | arbiter | user`; confidence is `high | medium | low | null`. New timestamps are UTC RFC 3339; `decided_at` is non-null only for `decided` or `blocked`. `selected_option` is null before `decided` and otherwise exactly one option. `final_actor` is `system` while pending or blocked and is the actual terminal decision maker for `decided`. + +`advisor` and `arbiter` are always present mappings with nullable `logical_role_id`, `agent`, `model`, and `response`, plus `attempts` and `exhausted`. A response, when present, has exactly the four role fields. Attempt status is `started | completed | failed | interrupted`; every attempt has a positive unique number and `started_at`; terminal attempt statuses require `completed_at`, while `started` requires it to be null. An Arbiter mapping may become active only after a completed Advisor disagreement and retains one `logical_role_id` for every retry. + +`provenance_kind` is `complete` for native v2 records and `legacy` only for migrated narrow terminal records. A legacy gate preserves its exact prior mapping in `legacy_record`, cannot authorize new automatic continuation, and may only support audit/report projection or exact terminal lookup. Native records require `legacy_record: null` and complete role provenance for their actor. + +Workflow inventories require an `inventory_version` and ordered items with stable `id`, positive unique `ordinal`, `status`, nullable `source_gate_key`, and nullable `selected_option`. Item status transitions only `ready → in_progress → completed | blocked`, plus idempotent reuse of the same state. An item cannot be completed without a terminal source gate and applied legal selection. + +### Supported Legacy Migration Matrix + +| Input shape | Deterministic v2 mapping | Rejection boundary | +|---|---|---| +| Already-v2 snapshot | Validate exactly; do not migrate or change revision | Reject unknown schema, invalid revision, field, enum, invariant, or duplicate identity | +| Legacy workflow snapshot with `current_phase`, ordered `phases`, and no revision | Require `current_phase` to equal the sole `in_progress` phase; set `initial_phase` from valid `started_phase`, otherwise the first ordered phase; remove mutable `started_phase`; set revision 1 | Reject absent/multiple in-progress phases, phase mismatch, or `started_phase` not naming a phase | +| Legacy workflow snapshot with `started_phase` but no `current_phase` | Derive `current_phase` only from the sole `in_progress` phase; use valid `started_phase` as immutable `initial_phase`; set revision 1 | Reject when current phase cannot be derived uniquely or `started_phase` is invalid | +| Empty legacy `gate_history` | Create empty v2 history, work mapping, and outbox | Reject misplaced/duplicate canonical anchors | +| Rich legacy gate with Advisor/Arbiter subrecords | Preserve exact option, actor, policy, role responses, models, attempts, rationale, and errors; derive stable missing logical role IDs; mark complete only when actor provenance is complete | Reject conflicting actor/response, illegal option, duplicate key, or an unfinished attempt that cannot be resumed unambiguously | +| Narrow schema-v1 terminal gate without role subrecords | Preserve the exact record as `provenance_kind: legacy` plus `legacy_record`; retain terminal choice for audit but prohibit it from authorizing new effects | Reject nonterminal narrow records, changed/illegal selection, or records whose identity fields are incomplete | +| Legacy `user_pending` record with complete context | Preserve configured/effective policy, recommendation and available analysis; normalize null terminal fields; resume the same user gate | Reject a preselected option, terminal actor, or conflicting override while pending | + +All migration reads and validates the complete source before acquiring its single commit revision. Duplicate YAML keys/anchors, unsupported YAML features, unknown legacy shapes, conflicting phase evidence, duplicate gate/work/dispatch IDs, invalid timestamps, unsafe paths, or any lossy mapping are fail-closed. Migration never fabricates a model response, rationale, user choice, or completed attempt. + +### Normative Policy Transitions + +| Effective policy and condition | Required transition and terminal behavior | +|---|---| +| `manual` | Create/reuse `user_pending` with no role calls, null selection, actor `system`; user response commits `decided`, actor `user`, and override false unless a prior machine recommendation exists and differs | +| `advisor`, agreement | `advisor_pending → user_pending`; persist Advisor analysis, present original and Advisor recommendations, then user response commits actor `user` | +| `advisor`, disagreement | `advisor_pending → arbiter_pending → user_pending`; persist one logical Arbiter analysis, present original/Advisor/Arbiter recommendations, then user response commits actor `user` | +| User override | Set `user_override: true` exactly when the user's choice differs from the latest valid machine recommendation: Arbiter if present, otherwise Advisor, otherwise original recommendation | +| Unsupported `fully_automatic` in an interactive session | Preserve `configured_policy: fully_automatic`, set effective `policy: manual`, record the unsupported fallback rationale, and enter `user_pending` without automatic dispatch | +| Resume from `user_pending` | Re-present/reuse the same gate identity and analysis without repeating completed roles; commit exactly one user decision or remain pending | + +### Dispatch Claim, Checkpoint, and Acknowledgement + +Every outbox record requires `dispatch_id`, `source_gate_key`, `kind` (`same_phase_work_item | phase_entry`), `phase_id`, `target_id`, `status`, `attempts`, nullable `claim_token`, `claimed_at`, `lease_expires_at`, `checkpoint`, `acknowledged_at`, and `error`. Its only forward transitions are `pending → claimed → acknowledged | blocked`; retry of an unchanged state is idempotent. + +Claiming is a repository commit that assigns an unpredictable owner token and bounded lease. A claim does not start target work. The receiver's logical start effect is one atomic repository commit that both (a) establishes the target's durable `in_progress` checkpoint and (b) changes the matching outbox entry to `acknowledged` with that checkpoint and timestamp. Only after that commit may the binding return `continue` and execute the target body. Therefore a crash while merely claimed has no target effect; after lease expiry a safely authorized receiver may reclaim the same `dispatch_id`. A crash after the acknowledgement commit but before the caller observes it is recovered by returning the stored acknowledgement, never by creating a second checkpoint or target start. + +`blocked` is permitted only before acknowledgement and records an actionable non-retryable error. Source gate, target, and dispatch identity are immutable in every state. Recovery cannot steal an unexpired claim, change a target, or infer success from process output alone. + +### Platform-bounded Repository Contract + +The exclusive lock is an atomically created sibling directory of the state file and contains an owner record with a random token, process ID, hostname, acquisition time, and lease expiry. Acquisition waits only for a bounded configured duration and then returns a non-mutating conflict. Release and cleanup require the matching token. An expired lock is reclaimable only when the repository can prove the recorded same-host process is no longer alive and the owner record is valid; a live, foreign-host, malformed, or otherwise uncertain lock is never broken automatically. Reclamation and cleanup must not remove a successor's lock. + +The task root, state path, lock path, report paths, every existing parent, and existing targets are canonicalized before mutation. The repository rejects a symlink at any of those boundaries and requires the state target to be a regular file. Temporary files are created in the state directory. Existing mode bits are preserved exactly. Existing ownership is preserved only when the process already has that ownership or can set it safely on the staged file; inability to establish required ownership aborts before replacement with an actionable error rather than attempting unconditional privileged `chown`. File data is flushed before atomic rename; the containing directory is flushed where the supported Node/macOS/Linux runtime exposes that operation, with any unsupported durability limitation explicit in test evidence. Only token-owned lock and temporary artifacts may be cleaned. + +### Native Evidence Bootstrap and Activation + +The evidence bootstrap is a platform-test-only adapter under `platforms/codex-cli/tests/`, excluded from build projection and installation. It invokes the real Codex plugin/skill entrypoint and supplies a private test eligibility provider to the binding; there is no production command-line option, environment flag, configuration key, or workflow instruction that can select it. The provider changes only the `declared_status` eligibility answer for that invocation. Denylist, gate policy, state validation, role isolation, confidence/escalation, persistence, dispatch, and no-UI assertions remain identical to production. + +Activation has two explicit steps. First, with Codex still declared `unsupported`, run the native target directly through the evidence bootstrap; exit `0` records the required real-host observations, while unavailable remains `77`. Second, in a separate change, set the declaration to `supported`, disable the bootstrap grant for the normal run, and rerun the native target plus capability matrix so declared and projected support match through ordinary eligibility. Failure at either step leaves or restores `unsupported`; fake or shared tests cannot substitute. + +### Compatibility and Rollout + +The runtime is introduced behind the existing capability-aware fallback. Schema and shared contracts land before workflow adoption; research's sequential decision areas provide the first same-phase tracer; remaining workflows adopt the same evidence contract without changing user entry points. Canonical and adapter sources are rebuilt into every committed platform variant, and source/generated contract matrices must remain green. + +The Codex binding can be integrated and tested with deterministic role and dispatcher ports while capability remains `unsupported`. The capability declaration changes only in a separate evidence-backed step after the native E2E exercises the real Codex entrypoint. If the active-turn spike disproves D1, implementation pauses for a scope decision rather than silently introducing an MCP service. + +### Safety + +The evaluator and runner both enforce the hard denylist and exact option/actor/confidence contracts. Advisor and Arbiter receive read-only context and no mutable artifact handles. Paths stay within the task root, role output is never interpolated into commands, retries are bounded, and low confidence or escalation cannot be suppressed. Manual and protected gates never reach automatic dispatch. + +## Implementation Guidance + +### Testing Approach + +- Organize verification into approximately six focused groups: evaluator behavior; repository and schema migration; runner regression/recovery; workflow inventory and dispatch; Codex binding/build projection; native host evidence. +- Add **2–8 behavior-focused tests per implementation step group** and run only the new or directly affected tests while completing that group; reserve the full repository matrix for integration and final verification. +- Preserve the red tracer in `tests/codex-fully-automatic-workflow-loop.test.sh` and prove agreement and disagreement through observable role counts, actors, state, receipts, checkpoints, and zero user-gate calls. +- Cover Advisor and Arbiter retry/resume, both legal Arbiter outcomes, invalid output, low confidence, escalation, exhaustion, denylist, unsupported capability, and terminal reuse; add manual, Advisor agreement/disagreement, user override, fallback, and `user_pending` resume cases. +- Exercise every supported migration-matrix row and every named rejection. For migration and every rejected or injected-failure write, snapshot and assert byte-exact state and reports, modes and permissions, and unchanged file/directory topology. +- Cover lock timeout, live/expired/malformed/foreign stale locks, token-safe cleanup, symlink boundaries, mode preservation, safely preservable ownership, stale revision, and platform-specific directory durability. +- Inject failure after the atomic target-checkpoint/acknowledgement commit but before the caller observes it; retry must return the stored acknowledgement with one checkpoint and one logical target start. Also cover crash while merely claimed and safe same-ID reclaim after lease expiry. +- Validate the evidence-only bootstrap is absent from generated/installable plugins and inaccessible through environment, configuration, normal CLI, or workflow input. Run the two-step unsupported-evidence then supported-matrix sequence. +- Validate canonical and generated runtimes after a clean double build. Keep the real host-native E2E distinct from fake-port integration and preserve exit `77` when native execution is unavailable. + +### Standards Compliance + +- Follow `.maister/docs/standards/global/build-pipeline.md`: edit canonical sources and platform adapters only, regenerate all variants, and validate deterministic build output. +- Follow `.maister/docs/standards/global/coding-style.md`, `commenting.md`, and `minimal-implementation.md`: use descriptive focused functions, keep comments timeless and sparse, and add no speculative adapters, services, or unused extension points. +- Follow `.maister/docs/standards/global/error-handling.md` and `validation.md`: validate exact allowlists early, return actionable boundary errors, bound retries with backoff, release locks and temporary resources, and fail closed. +- Follow `.maister/docs/standards/global/conventions.md`: preserve the minimal dependency footprint, document runtime and capability behavior, and keep incomplete native activation behind the existing unsupported capability posture. +- Follow `.maister/docs/standards/testing/test-writing.md`: test externally visible behavior at risk-appropriate depth and prove rejected transactional mutations preserve bytes, modes, permissions, and topology. + +## Out of Scope + +- Product-design backward refinement, backward phase transitions, or a general phase reset protocol. +- Automation of implementation approval, final handoff, rollback, production go/no-go, scope expansion, data-integrity halt, unresolved critical verification, failure-recovery skip, or any other protected gate. +- A new command, graphical interface, dashboard as source of truth, or changed user journey outside removing unnecessary automatic-gate prompts. +- A daemon, background service, database, append-only event store, generalized persistence framework, or MCP adapter unless D1 is disproved and a new scope decision approves the fallback. +- A Codex-only evaluator, duplicated gate policy, or direct edits to generated plugin trees. +- Claiming Codex support from shared unit tests, fake role/dispatcher integration, smoke checks, file presence, or runner success alone. +- Redesigning unrelated workflow domain logic or adopting a generic work-item SDK beyond the immediately used continuation contract. + +## Success Criteria + +- Agreement produces one terminal record with `final_actor: advisor`, one Advisor call, zero Arbiter calls, zero user gates, and an acknowledged next-target checkpoint. +- Disagreement produces one logical Arbiter identity, preserves that identity across bounded retries, does not re-invoke the Advisor, selects one competing option, shows zero user gates on the valid confident path, and acknowledges the next target. +- The terminal envelope contains the exact original recommendation, role identities/models, attempts, responses/errors, rationale, confidence, escalation, actor, and selected option before any projection or continuation effect. +- Same-phase continuation completes the source work item and begins the stable next work item in the same active Codex turn. +- Next-phase continuation establishes an observable target-phase checkpoint in addition to updating phase state. +- Resume after every defined crash window produces no duplicate terminal gate, completed role call, logical Arbiter, applied choice, logical dispatch effect, checkpoint, or acknowledgement; post-commit/pre-observation retry returns the stored acknowledgement. +- Manual, denylisted, low-confidence, escalated, exhausted, unsupported, invalid, unsafe, or uncommittable paths do not advance work and return only a safe user gate or blocked result. +- Schema-v2 validation enforces every required field, enum, nullability rule, timestamp rule, actor/provenance invariant, and gate/work/dispatch transition. +- Every supported legacy-matrix shape migrates in one commit to revision 1 without provenance loss; every named ambiguity rejects without changing bytes, modes, permissions, reports, or topology. +- Manual, Advisor agreement/disagreement, user override, unsupported fallback, and `user_pending` resume produce the specified v2 records without duplicate role or user decisions. +- Concurrent or stale writers cannot overwrite a newer revision; lock timeout and uncertain stale owners fail without mutation; token ownership prevents successor cleanup; every legal commit increments revision exactly once. +- Symlink boundaries are rejected, existing mode is exact, ownership is preserved only when safely possible, and inability to establish required metadata fails before replacement on supported macOS/Linux runtimes. +- The runner can recover missing reports and legal forward transitions from the evaluator-owned terminal record without reconstructing provenance or invoking roles. +- Existing manual and Advisor-assisted policies, user override, denylist, forward-only transition, and immutable terminal-selection contracts continue to pass. +- `make build` produces the Codex binding and shared runtime from canonical/adapter sources, a second clean build has no drift, and source/generated contract matrices pass. +- The test-only evidence provider is absent from installed/generated plugins and unreachable from normal workflows; it bypasses declaration eligibility only and leaves every safety check active. +- Codex remains declared `unsupported` for the first real native E2E exit `0`; a separate activation change sets `supported` and reruns the native target and capability matrix through normal eligibility; unavailable exits `77`. +- The successful native E2E observes the real Codex entrypoint, agreement, disagreement, one logical Arbiter, same-phase and next-phase targets, zero UI, resume, deduplication, and durable checkpoints. +- No new user command, UI, service, database, speculative abstraction, or direct generated-tree edit is introduced. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/tdd-green-gate.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/tdd-green-gate.md new file mode 100644 index 00000000..fe61a5d4 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/tdd-green-gate.md @@ -0,0 +1,38 @@ +# TDD Green Gate + +## Outcome + +The Phase 3 contract now passes after implementation. The Codex binding, shared +gate evaluator, durable state repository, continuation runtime, generated +projections, and capability evidence are all exercised by the verification +suite. + +## Green evidence + +Command: + +```sh +bash tests/codex-fully-automatic-workflow-loop.test.sh +``` + +Observed exit code: `0` + +Observed result: `4 passed, 0 failed` + +The passing assertions cover directive validation, agreement and disagreement +role routing, exactly-once arbiter behavior, automatic same-phase/next-phase +continuation, blocked and user-gate stops, and deterministic generated-runtime +parity with evidence-backed Codex support. + +## Native evidence + +The real Codex-native continuation E2E also passed before and after capability +activation (`3/3` scenarios in each run, exit code `0`). The supported status is +therefore backed by host-native evidence rather than the shared contract alone. + +## Guardrails + +- The test remains a direct executable contract and does not bootstrap the + production runtime. +- Bootstrap helpers are confined to test fixtures; generated projections are + rebuilt from canonical sources. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/tdd-red-gate.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/tdd-red-gate.md new file mode 100644 index 00000000..fdb1ee53 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/tdd-red-gate.md @@ -0,0 +1,40 @@ +# TDD Red Gate + +## Outcome + +The defect is reproduced by `tests/codex-fully-automatic-workflow-loop.test.sh`. +The test fails before production implementation, as required by the red gate. + +## Behavior under test + +The contract exercises two Codex fully automatic paths through deterministic role and dispatch ports: + +1. Agreement: the main recommendation and advisor both select `A`; the terminal actor must be `advisor`, the arbiter must not run, and the next work item must be dispatched without a user gate. +2. Disagreement: the main recommendation selects `A` and the advisor selects `B`; exactly one logical arbiter must run, its result must become terminal, and the next work item must be dispatched without a user gate. + +Both paths require a durable acknowledged dispatch, completion of the current work item, and an `in_progress` checkpoint for the next work item. + +## Red evidence + +Command: + +```sh +bash tests/codex-fully-automatic-workflow-loop.test.sh +``` + +Observed exit code: `1` + +Observed failure: + +```text +Error: Cannot find module '/Users/mrapacz/Workspace/maister/platforms/codex-cli/bin/fully-automatic-gate.mjs' +code: 'MODULE_NOT_FOUND' +``` + +The failure identifies the intended missing seam: no executable Codex binding currently connects role evaluation, terminal persistence, workflow routing, and automatic dispatch. + +## Guardrails + +- External role and dispatch behavior is isolated behind deterministic command fixtures. +- The test asserts observable decisions, state transitions, invocation counts, and dispatch receipts rather than internal function structure. +- The host capability remains `unsupported`; this contract is not a substitute for the real Codex-native E2E required before changing the capability matrix. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/work-log.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/work-log.md new file mode 100644 index 00000000..8aee5988 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/implementation/work-log.md @@ -0,0 +1,252 @@ +# Work Log + +## 2026-07-13T19:41:09Z - Implementation Started + +**Total Steps**: 39 +**Task Groups**: Codex Active-Turn Hook Viability; Schema-v2 State Repository and Migration; Shared Gate Evaluator and Policy Compatibility; Continuation Runner, Workflow Inventory, and Dispatch; Thin Codex Binding and Deterministic Build Projection; Native Evidence Bootstrap and Capability Activation; Test Review and Gap Analysis + +## Standards Reading Log + +### Loaded Per Group + +Entries are added as groups execute. + +### Group 1: Codex Active-Turn Hook Viability + +**From Implementation Plan**: +- [x] `.maister/docs/standards/global/build-pipeline.md` +- [x] `.maister/docs/standards/global/coding-style.md` +- [x] `.maister/docs/standards/global/commenting.md` +- [x] `.maister/docs/standards/global/minimal-implementation.md` +- [x] `.maister/docs/standards/global/error-handling.md` +- [x] `.maister/docs/standards/global/validation.md` +- [x] `.maister/docs/standards/global/conventions.md` +- [x] `.maister/docs/standards/testing/test-writing.md` + +**From INDEX.md**: +- [x] `.maister/docs/project/architecture.md` - preserved shared-runtime and host-adapter boundaries +- [x] `.maister/docs/project/tech-stack.md` - followed Node ESM and fail-fast shell-test patterns + +**Discovered During Execution**: None. + +## 2026-07-13T19:48:58Z - Group 1 Complete + +**Steps**: 1.0 through 1.4 completed +**Tests**: focused binding contract and real native active-turn E2E passed; forced unavailable path exits `77` +**Files Modified**: +- `platforms/codex-cli/bin/fully-automatic-gate.mjs` +- `platforms/codex-cli/tests/active-turn-hook.e2e.sh` +- `tests/codex-fully-automatic-workflow-loop.test.sh` + +**Notes**: D1 is empirically proven on native `codex-cli 0.144.3`: binding execution preceded the same-turn target-start marker, which preceded the final response, with no intervening user question. Capability remains `unsupported`; no D2/MCP fallback was introduced. + +### Group 2: Schema-v2 State Repository and Migration + +**From Implementation Plan**: +- [x] `.maister/docs/standards/global/coding-style.md` +- [x] `.maister/docs/standards/global/commenting.md` +- [x] `.maister/docs/standards/global/minimal-implementation.md` +- [x] `.maister/docs/standards/global/error-handling.md` +- [x] `.maister/docs/standards/global/validation.md` +- [x] `.maister/docs/standards/global/conventions.md` +- [x] `.maister/docs/standards/testing/test-writing.md` + +**From INDEX.md**: +- [x] `.maister/docs/standards/testing/test-writing.md` - applied transactional non-mutation evidence requirements + +**Discovered During Execution**: None. + +## 2026-07-13T20:01:45Z - Group 2 Complete + +**Steps**: 2.0 through 2.5 completed +**Tests**: 5 passed, 0 failed, 0 skipped +**Files Modified**: canonical schema and repository modules, two focused test scripts, and five schema-v2/legacy fixtures +**Notes**: The repository now provides strict schema-v2 validation, supported deterministic migration, token-owned locks, CAS revisions, durable same-directory replacement, metadata preservation, safe stale-owner handling, and transactional rejection evidence. + +### Group 3: Shared Gate Evaluator and Policy Compatibility + +**From Implementation Plan**: +- [x] `.maister/docs/standards/global/coding-style.md` +- [x] `.maister/docs/standards/global/commenting.md` +- [x] `.maister/docs/standards/global/minimal-implementation.md` +- [x] `.maister/docs/standards/global/error-handling.md` +- [x] `.maister/docs/standards/global/validation.md` +- [x] `.maister/docs/standards/testing/test-writing.md` + +**From INDEX.md**: +- [x] `.maister/docs/standards/testing/test-writing.md` - deterministic role/user ports and canonical temporary state +- [x] `.maister/docs/standards/global/conventions.md` - capability activation remains out of scope + +**Discovered During Execution**: +- [x] `orchestrator-state-schema.mjs` - executable v2 status, role, attempt, and terminal invariants +- [x] `orchestrator-state-repository.mjs` - lock-free role calls with repository commits around effects +- [x] `gate-decision-engine.md` - reconciled prose with executable evaluator behavior + +## 2026-07-13T20:10:33Z - Group 3 Complete + +**Steps**: 3.0 through 3.5 completed +**Tests**: evaluator 5/5; gate-decision engine contracts 29/29 +**Files Modified**: shared evaluator, normative engine reference/fixtures, evaluator tests, and one engine contract assertion +**Notes**: Agreement terminates with Advisor and no Arbiter; disagreement uses one durable logical Arbiter across bounded attempts. Unsafe results fail closed, compatibility policies are preserved, and terminal/user-pending records are reused without dispatch or phase mutation. + +### Group 4: Continuation Runner, Workflow Inventory, and Dispatch + +**From Implementation Plan**: +- [x] `.maister/docs/standards/global/coding-style.md` +- [x] `.maister/docs/standards/global/commenting.md` +- [x] `.maister/docs/standards/global/minimal-implementation.md` +- [x] `.maister/docs/standards/global/error-handling.md` +- [x] `.maister/docs/standards/global/validation.md` +- [x] `.maister/docs/standards/global/conventions.md` +- [x] `.maister/docs/standards/testing/test-writing.md` + +**From INDEX.md**: +- [x] `.maister/docs/standards/testing/test-writing.md` - critical-path crash and transactional recovery coverage + +**Discovered During Execution**: None. + +## 2026-07-13T20:22:23Z - Group 4 Complete + +**Steps**: 4.0 through 4.5 completed +**Tests**: 12 passed, 0 failed, 0 skipped across four scoped scripts +**Files Modified**: verifier/recovery runner, shared workflow continuation module, orchestrator guidance, five canonical workflows, four focused test scripts, and schema-v2 fixtures +**Notes**: Selection application and deterministic outbox creation share one commit; receiver checkpoint and acknowledgement are atomic. Expired claims safely reuse the same dispatch ID, acknowledged retries return the stored receipt, and protected gates retain explicit-user-only entry. + +### Group 5: Thin Codex Binding and Deterministic Build Projection + +**From Implementation Plan**: +- [x] `.maister/docs/standards/global/build-pipeline.md` +- [x] `.maister/docs/standards/global/coding-style.md` +- [x] `.maister/docs/standards/global/commenting.md` +- [x] `.maister/docs/standards/global/minimal-implementation.md` +- [x] `.maister/docs/standards/global/error-handling.md` +- [x] `.maister/docs/standards/global/validation.md` +- [x] `.maister/docs/standards/testing/test-writing.md` + +**From INDEX.md**: +- [x] `.maister/docs/standards/global/conventions.md` - no production bypass or premature capability activation +- [x] `.maister/docs/standards/testing/test-writing.md` - role isolation and no hidden continuation effects + +**Discovered During Execution**: +- [x] `platforms/kiro-cli/build.sh` / generated Kiro topology - consecutive aggregate builds alternate broad packaging layouts + +## 2026-07-13T20:35:36Z - Group 5 Partial + +**Completed Steps**: 5.1, 5.2, 5.3, 5.5 +**Pending Step**: 5.4 deterministic complete-tree rebuild +**Tests**: binding 4/4 and capability matrix 6/6 pass; Codex remains `unsupported` +**Failure**: consecutive generated-tree hashes differed (`05a062…`, `02c27e…`, `d71be1…`) because Kiro output alternated between broad packaging topologies. Codex/Cursor and targeted shared runtime projections were byte-identical. +**Recovery**: awaiting explicit `group-failure-recovery` decision. + +## 2026-07-13T21:05:16Z - Group 5 Complete After Recovery + +**Recovery Decision**: User selected `Try suggested fix` at the Group 5 failure-recovery gate. + +**Root Cause**: The Kiro build lock was derived from `${TMPDIR}`. Concurrent processes with different `TMPDIR` values therefore acquired different locks and mutated `plugins/maister-kiro/` concurrently, producing the observed alternating partial topologies. + +**Fix**: Move the lock to the repository-local, gitignored path `.maister-kiro-build.lock.d`; add `platforms/kiro-cli/tests/reproducible-build.test.sh` covering concurrent builds with different `TMPDIR` values and stable sorted content manifests. + +**Tests**: +- Concurrent Kiro reproducibility regression: 1 passed, 0 failed +- Two isolated aggregate `make build` runs: 475-file manifests identical +- Group 5 binding: 4/4 +- Host capability matrix: 6/6 +- `git diff --check`: passed + +**Notes**: Codex remains declared `unsupported`; the native evidence bootstrap is absent from generated/installable plugins. Group 5 is complete and Group 6 remains the separate native-evidence checkpoint. + +### Group 6: Native Evidence Bootstrap and Capability Activation + +## 2026-07-13T21:10:50Z - Group 6 Blocked by Native Evidence Availability + +**Attempted**: Ran the real Codex continuation entrypoint and capability projection. + +**Result**: `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` reported `UNAVAILABLE` and exited `77` because no deterministic native adapter harness is available. Codex remains safely declared `unsupported`. + +**Safety**: No evidence bootstrap or production bypass was added; no capability activation was performed. Recovery decision is pending. + +## 2026-07-13T21:24:27Z - Group 6 Complete + +**Native runtime**: `codex-cli 0.144.3`. + +**Two-step evidence**: +- Stage 1 with Codex declared `unsupported`: real native E2E exited `0`, 3/3 scenarios passed. +- Stage 2 after separate declaration activation to `supported`: rebuilt all projections and real native E2E exited `0`, 3/3 scenarios passed again. + +**Coverage**: Advisor agreement without Arbiter; disagreement with exactly one logical Arbiter; same-phase and next-phase acknowledged checkpoints; resume/deduplication; zero user questions before target start; denylist fail-closed; forced unavailability exit `77`. + +**Validation**: host matrix 6/6, Group 5 loop 4/4, binding parity, shell/Node syntax, and `git diff --check` passed. The bootstrap remains only under `platforms/codex-cli/tests/` and is absent from generated/installable plugins. + +## 2026-07-13T21:32:57Z - Group 7 Complete + +**Review**: Mapped the feature evidence to R1–R30, supported migration rows, policy transitions, retry/resume crash windows, protected/denylisted gates, native activation, and source/generated parity. + +**Tests**: 31 shared feature tests plus 3 native evidence scenarios passed; no additional strategic tests were required. No critical uncovered safety or continuation gap remains. + +## 2026-07-13T21:45:49Z - Phase 9 TDD Green Complete + +**Command**: `bash tests/codex-fully-automatic-workflow-loop.test.sh` + +**Result**: Exit `0`; 4 passed, 0 failed. The direct contract confirms directive validation, agreement/disagreement routing, single logical arbitration, durable continuation, blocked/user-gate stops, and generated-runtime parity with evidence-backed Codex support. + +**Native evidence**: Real Codex continuation E2E passed before and after capability activation with 3/3 scenarios in each run. + +**Gate**: Phase 9 exit is awaiting the user's decision to continue to Phase 10. + +## 2026-07-13T22:10:41Z - Phase 10 Verification Options Complete + +**Selected standard reviews**: Code review, pragmatic review, reality check, and production readiness. + +**Conditional choices**: Browser E2E skipped because this is a non-UI runtime repair; user documentation generation enabled. + +**Next**: Phase 11 implementation verification and issue-resolution review started. + +## 2026-07-13T22:32:40Z - Phase 11 Verification Complete After Fixes + +**Decision**: User selected `Fix all fixable issues` at the verification fix-selection gate. + +**Fixes**: +- Added the exact JSON continuation runner payload, stdin/`--input-file PATH` hard cutover, persistence ordering, fail-closed exit, and durable retry markers to the five source workflow skill contracts. +- Rebuilt Codex, Cursor, and Kiro projections from canonical sources. +- Updated the Kiro CHAT GATE validation floor from the retired pre-schema-v2 53/200 thresholds to the current projection minimum of 42/166, with the rationale documented in the transform contract. + +**Verification**: +- Gate decision contract: 29/29. +- Full `make validate`: exit 0. +- Phase-continue matrix: 24/24 across source, Codex, Cursor, and Kiro. +- Workflow loop: 4/4; host capability matrix: 6/6; native Codex evidence: 3/3 before and after activation. +- YAML, dashboard JavaScript syntax, and diff checks passed. + +**Next**: Phase 11 exit gate is pending: `Continue to Phase 12?`. + +## 2026-07-13T22:43:04Z - Phase 12 Skipped + +**Gate**: User selected `Continue to Phase 12`. + +**Result**: Browser E2E was skipped because `options.e2e_enabled` is false. Native Codex continuation evidence was already completed during implementation (3/3 scenarios before and after activation). + +**Next**: Phase 12 exit gate is pending: `E2E complete. Continue to Phase 13?`. + +## 2026-07-13T22:53:00Z - Phase 13 Documentation Complete + +**Result**: Created `documentation/user-guide.md` and the faithful HTML companion `documentation/user-guide.html`. The guide explains automatic agreement continuation, single-Arbiter disagreement handling, durable retries, protected gates, fail-closed behavior, and troubleshooting. + +**Screenshots**: None; this is a non-UI runtime feature and Phase 12 browser E2E was skipped. + +**Next**: Phase 13 exit gate is pending: `Documentation complete. Continue to Phase 14?`. + +## 2026-07-13T22:59:08Z - Finalization Started + +**Gate**: User selected `Continue to Phase 14`. + +**Result**: Decision summaries and dashboard projections were refreshed with the complete workflow history. The protected `final-handoff-approval` gate is now pending. + +## 2026-07-13T23:07:16Z - Workflow Complete + +**Final handoff**: User selected `Complete workflow`. + +**Final state**: All implementation, verification, documentation, and summary artifacts are persisted; task status is `completed`. + +**Commit template**: `fix(codex): enable durable fully automatic workflow continuation` + +**Next steps**: Review the diff, run CI validation, open the PR, and plan deployment. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/orchestrator-state.yml b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/orchestrator-state.yml new file mode 100644 index 00000000..1020ff40 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/orchestrator-state.yml @@ -0,0 +1,1329 @@ +orchestrator: + started_phase: phase-1 + current_phase: phase-14 + completed_phases: [phase-1, phase-2, phase-3, phase-5, phase-6, phase-7, phase-8, phase-9, phase-10, phase-11, phase-13, phase-14] + failed_phases: [] + auto_fix_attempts: + phase-1: 0 + phase-2: 0 + phase-3: 0 + phase-4: 0 + phase-5: 0 + phase-6: 1 + phase-7: 0 + phase-8: 0 + phase-9: 0 + phase-10: 0 + phase-11: 0 + phase-12: 0 + phase-13: 0 + phase-14: 0 + options: + html_output: true + spec_audit_enabled: true + skip_test_suite: false + e2e_enabled: false + user_docs_enabled: true + code_review_enabled: true + pragmatic_review_enabled: true + reality_check_enabled: true + production_check_enabled: true + sequential: false + advisor: + enabled: true + gate_policies: + phase-exit: fully_automatic + optional-phase: fully_automatic + clarify: fully_automatic + convergence: fully_automatic + verify-matrix: fully_automatic + advisor_agent: advisor + advisor_model: gpt-5.6-sol + arbiter_agent: arbiter + arbiter_model: gpt-5.6-sol + arbiter_enabled_on_disagreement: true + retry: + advisor_attempts: 3 + arbiter_attempts: 3 + backoff: exponential + created: "2026-07-13T17:50:35Z" + updated: "2026-07-13T23:07:16Z" + task_path: .maister/tasks/development/2026-07-13-fix-codex-auto-continuation + task_ids: + phase-1: development-phase-1 + phase-2: development-phase-2 + phase-3: development-phase-3 + phase-4: development-phase-4 + phase-5: development-phase-5 + phase-6: development-phase-6 + phase-7: development-phase-7 + phase-8: development-phase-8 + phase-9: development-phase-9 + phase-10: development-phase-10 + phase-11: development-phase-11 + phase-12: development-phase-12 + phase-13: development-phase-13 + phase-14: development-phase-14 + gate_history: + - schema_version: 1 + idempotency_key: sha256:ba5d887d0c4265cbcbe1c13696ffdc0cf70e09b9b115fd0cea577002cb7aee7a + phase_id: phase-1 + gate_type: phase-1-exit + question: Continue to Phase 2? + options: + - Continue to Phase 2 + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to Phase 2 + final_actor: user + original_recommendation: Continue to Phase 2 + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User approved continuation after reviewing the Phase 1 codebase analysis and clarifications; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:bda70639d3caeafe6e58449256cad57fd6f7b9ed55a120a3f202f6349f082a35 + phase_id: phase-2 + gate_type: phase-2-routing + question: "Continue to Phase 3: TDD Red Gate?" + options: + - "Continue to Phase 3: TDD Red Gate" + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Continue to Phase 3: TDD Red Gate" + final_actor: user + original_recommendation: "Continue to Phase 3: TDD Red Gate" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User approved the TDD Red route after reviewing the Phase 2 gap analysis; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:fd8a0dde74422d174a503635180bcae5229547be5924ee81758382516d511e3 + phase_id: phase-3 + gate_type: phase-3-exit + question: TDD red gate complete. Continue to Phase 4? + options: + - Continue to Phase 4 + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: test-gate + status: decided + selected_option: Continue to Phase 4 + final_actor: user + original_recommendation: Continue to Phase 4 + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User approved continuation after reviewing the failing TDD contract and persisted red evidence; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:bedc2afddf4732085c33cf7e8d91af82e10a07c25484bcdeba93a3d37e5543c7 + phase_id: phase-4 + gate_type: phase-4-exit + question: UI mockups complete. Continue to Phase 5? + options: + - Continue to Phase 5 + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: design-gate + status: decided + selected_option: Continue to Phase 5 + final_actor: user + original_recommendation: Continue to Phase 5 + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User approved routing to specification work after UI mockup generation was skipped because task_context.task_characteristics.ui_heavy is false; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:130921bdba5474ec8cbd27699e4f91e6074d48aba4180ea8a712325d2ffd227b + phase_id: phase-5 + gate_type: requirements-clarification + question: "I assume this repair is transparent to Maister workflow users: they access it through existing maister:* workflows, with no new commands or UI, and automatic gates simply continue in the active Codex turn. Is that correct?" + options: + - Yes, use this journey + - No, revise the journey + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, use this journey + final_actor: user + original_recommendation: Yes, use this journey + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed the transparent existing-workflow journey; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:0de2807b14ec69b7f7623bd8e30d635ecbb8732592a4721d87e8d3bcb84e0303 + phase_id: phase-5 + gate_type: requirements-clarification + question: I assume the implementation must extend the canonical orchestrator framework, shared state/continuation runtime, existing build projections, host capability matrix, and contract-test patterns, with only a thin Codex binding and no separate Codex-only evaluator. Is that correct? + options: + - Yes, reuse these canonical seams + - No, revise the reuse constraints + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, reuse these canonical seams + final_actor: user + original_recommendation: Yes, reuse these canonical seams + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed reuse of the canonical framework, runtime, projections, capability matrix, and test patterns with only a thin Codex binding; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:2671f8fa96f4aca2e6e961cf125b252826b1e3b927826c122cb663c4fee3fca4 + phase_id: phase-5 + gate_type: requirements-clarification + question: I assume there are no mockups, wireframes, screenshots, or other visual assets for this non-UI runtime repair, so the specification should contain no visual implementation requirements. Is that correct? + options: + - Yes, no visual assets + - No, I will provide visual assets + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, no visual assets + final_actor: user + original_recommendation: Yes, no visual assets + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed there are no visual assets or visual implementation requirements for this non-UI runtime repair; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:be3a4d348eb56e0c8ddddc627142df6991828e358f2cb9c15e3b3519bdc78ec8 + phase_id: phase-5 + gate_type: phase-5-exit + question: Continue to specification audit? + options: + - Continue to specification audit + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to specification audit + final_actor: user + original_recommendation: Continue to specification audit + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User approved continuation after reviewing the delegated, self-verified specification; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:25ed56451a996a9299301ab4e2c8703a8c4bc876280146c4f32790b7115f440e + phase_id: phase-6 + gate_type: optional-phase-selection + question: Run specification audit? (Recommended) + options: + - Yes, run audit (Recommended) + - No, skip audit + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, run audit (Recommended) + final_actor: user + original_recommendation: Yes, run audit (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected the recommended independent specification audit; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:1fe66cd479b2d3d5b6efc0fd4597f15b5a503f8b4eded313d8c4fcc21d7dcb00 + phase_id: phase-6 + gate_type: phase-6-exit + question: Continue to implementation planning? + options: + - Continue to implementation planning + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to implementation planning + final_actor: user + original_recommendation: Continue to implementation planning + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User approved implementation planning after the focused re-audit found the revised 30-requirement specification compliant and plan-ready with zero open findings; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:54b3b61cbff13e163db142366b59dcc90b99aa091ad884540e9ac197658d554d + phase_id: phase-7 + gate_type: phase-7-exit + question: Continue to implementation approval? + options: + - Continue to implementation approval + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to implementation approval + final_actor: user + original_recommendation: Continue to implementation approval + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User approved routing the delegated, self-verified seven-group implementation plan to the separate protected implementation-approval gate; Codex native continuation capability remains unsupported, so the configured fully_automatic policy correctly used the interactive fallback. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:4048f2df3ad915b86ab2734606838d7174ae6a522d61fb8b228ab9f3b449a938 + phase_id: phase-7 + gate_type: implementation-approval + question: Approve this complete implementation scope? + options: + - Approve complete implementation scope + - Reject implementation scope + - Request scope changes + policy: manual + configured_policy: fully_automatic + safety_classification: protected + status: decided + selected_option: Approve complete implementation scope + final_actor: user + original_recommendation: Approve complete implementation scope + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly approved the complete seven-group, 39-step implementation scope at the denylisted protected gate. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:6995e5f3f50704b8ae72f8d3dfc9218c948b08ce0b53c3d0317a6793d4e3d055 + phase_id: phase-8 + gate_type: group-failure-recovery + question: "Group 5 implementation failed: complete generated-tree reproducibility is blocked by alternating Kiro build topology. How to proceed?" + options: + - Try suggested fix + - Retry group + - Complete manually + - Rollback changes + - Stop + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Try suggested fix + final_actor: user + original_recommendation: Try suggested fix + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User approved the bounded suggested fix: make the Kiro projection deterministic, then rerun two isolated builds. Group 5 remains in progress until reproducibility is proven." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:401d2c28e455e758938531a94957dc4d4d93118bb8ed275d2885ff0172208df8 + phase_id: phase-8 + gate_type: group-failure-recovery + question: "Group 6 native evidence is unavailable (exit 77); Codex remains unsupported. How to proceed?" + options: + - Try suggested fix + - Retry group + - Complete manually + - Rollback changes + - Stop + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Try suggested fix + final_actor: user + original_recommendation: Stop + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User approved implementing the test-only native bootstrap and real Codex E2E so the capability can become supported only after genuine exit-0 evidence. Native evidence then passed before and after separate activation." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:19568792996c419f61acb934284693bd396df535db9c9b4ac814b5f6c528d7a5 + phase_id: phase-8 + gate_type: phase-8-exit + question: Continue to verification? + options: + - Continue to verification + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to verification + final_actor: user + original_recommendation: Continue to verification + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User approved continuation to TDD Green verification after Groups 1–7 completed." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:21481c7a3ccef7ede23269d2b2f100c6408458d9a82455fafe0aba00bc872eeb + phase_id: phase-9 + gate_type: phase-9-exit + question: TDD gate passed. Continue to Phase 10? + options: + - Continue to Phase 10 + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: test-gate + status: decided + selected_option: Continue to Phase 10 + final_actor: user + original_recommendation: Continue to Phase 10 + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User approved continuation after the TDD Green contract passed with 4/4 shared assertions." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:530fc6822d1a70a98ba3c3006c1da3db21a56c8bfc9a4e457502e9aea70e1be8 + phase_id: phase-10 + gate_type: verification-options + question: Which standard verifications to run? + options: + - Code review (Recommended) + - Pragmatic review (Recommended) + - Reality check (Recommended) + - Production readiness (Recommended) + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: + - Code review (Recommended) + - Pragmatic review (Recommended) + - Reality check (Recommended) + - Production readiness (Recommended) + final_actor: user + original_recommendation: All standard verifications + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User accepted all four pre-selected standard verifications." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:77c8cb6704d28e4d5762aaf89136f4842e48d9f66c93efe086598ae8d8f9f8b7 + phase_id: phase-10 + gate_type: optional-phase-selection/e2e + question: Enable E2E browser verification? + options: + - Yes (Recommended) + - No, skip + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: No, skip + final_actor: user + original_recommendation: Yes (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User skipped browser E2E because the task has no browser UI." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:01919555cceafcac7db620a0fee6ab826a11fbb5262305dfabcdd4158932e2e9 + phase_id: phase-10 + gate_type: optional-phase-selection/user-docs + question: Generate user documentation? + options: + - Yes (Recommended) + - No, skip + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes (Recommended) + final_actor: user + original_recommendation: Yes (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User approved generating documentation as part of the verification workflow." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:e89bcd06958fe3f971bc14c4adc5618140a78e5da1125c44c5090c7d36fe16f1 + phase_id: phase-11 + gate_type: verification-fix-selection + question: Which issues should I fix? + options: + - Fix all fixable issues + - Let me choose specific issues + - Skip fixes, proceed as-is + policy: manual + configured_policy: fully_automatic + safety_classification: test-gate + status: decided + selected_option: Fix all fixable issues + final_actor: user + original_recommendation: Fix all fixable issues + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User approved fixing all fixable verification issues; the single critical source-contract parity issue is in scope." + confidence: high + escalate_to_user: false + user_override: true + error: null + - schema_version: 1 + idempotency_key: sha256:ba2f37fc98aefd3b718995813535a7792eb83183de4c25a116034b7257428193 + phase_id: phase-11 + gate_type: phase-11-exit + question: Continue to Phase 12? + options: + - Continue to Phase 12 + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: test-gate + status: decided + selected_option: Continue to Phase 12 + final_actor: user + original_recommendation: Continue to Phase 12 + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User approved continuation after Phase 11 verification passed; E2E remains skipped because the earlier optional-phase decision disabled it." + confidence: high + escalate_to_user: false + user_override: true + error: null + - schema_version: 1 + idempotency_key: sha256:1f9da8b5b76f9ea1ca3febfdd5b7bc1875d62c81a866304b24b12e37e34f7a80 + phase_id: phase-12 + gate_type: phase-12-exit + question: E2E complete. Continue to Phase 13? + options: + - Continue to Phase 13 + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to Phase 13 + final_actor: user + original_recommendation: Continue to Phase 13 + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User approved continuation after the configured E2E skip; Phase 13 documentation generation is enabled." + confidence: high + escalate_to_user: false + user_override: true + error: null + - schema_version: 1 + idempotency_key: sha256:7cb2b9033ac1de28bebd53bd4944c1a8785e7136071f26ce2aa98059abdbafad + phase_id: phase-13 + gate_type: phase-13-exit + question: Documentation complete. Continue to Phase 14? + options: + - Continue to Phase 14 + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to Phase 14 + final_actor: user + original_recommendation: Continue to Phase 14 + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User approved continuation after the documentation artifacts were generated and validated." + confidence: high + escalate_to_user: false + user_override: true + error: null + - schema_version: 1 + idempotency_key: sha256:250a7596bc8c9dbb5c55d6186e83b1b214a148e00ec7535e3bddffbc39d7fe68 + phase_id: phase-14 + gate_type: final-handoff-approval + question: Complete workflow or keep it open? + options: + - Complete workflow + - Keep workflow open + policy: manual + configured_policy: fully_automatic + safety_classification: protected + status: decided + selected_option: Complete workflow + final_actor: user + original_recommendation: Complete workflow + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User explicitly approved completing the workflow after reviewing the implementation, verification, and documentation artifacts." + confidence: high + escalate_to_user: false + user_override: true + error: null + implementation_approval: + status: approved + approved_by: user + approved_at: "2026-07-13T19:41:09Z" + approved_scope: [group-1, group-2, group-3, group-4, group-5, group-6, group-7] + +task: + title: Fix Codex automatic continuation + description: Jak naprawić Codex fully_automatic tak, aby zgodność rekomendacji głównego agenta i advisora automatycznie wybierała decyzję, rozbieżność uruchamiała arbitra dokładnie raz, a wynik automatycznie kontynuował do następnego problemu bez interakcji użytkownika? + status: completed + completed_at: "2026-07-13T23:07:16Z" + tags: [development, codex, advisor, arbiter, continuation] + priority: high + +phases: + - id: phase-1 + name: Analyze codebase & clarify requirements + active_form: Analyzing codebase & clarifying + status: completed + blocked_by: [] + started: "2026-07-13T17:50:35Z" + completed: "2026-07-13T18:03:23Z" + gate: + question: Continue to Phase 2? + answer: Continue to Phase 2 + - id: phase-2 + name: Analyze gaps & clarify scope + active_form: Analyzing gaps & clarifying scope + status: completed + blocked_by: [phase-1] + started: "2026-07-13T18:03:23Z" + completed: "2026-07-13T18:15:54Z" + gate: + question: "Continue to Phase 3: TDD Red Gate?" + answer: "Continue to Phase 3: TDD Red Gate" + - id: phase-3 + name: Write failing test (TDD Red) + active_form: Writing failing test + status: completed + blocked_by: [phase-2] + started: "2026-07-13T18:15:54Z" + completed: "2026-07-13T18:20:22Z" + gate: + question: TDD red gate complete. Continue to Phase 4? + answer: Continue to Phase 4 + - id: phase-4 + name: Generate UI mockups + active_form: Generating UI mockups + status: skipped + blocked_by: [phase-2, phase-3] + started: "2026-07-13T18:20:22Z" + completed: "2026-07-13T18:20:22Z" + skip_reason: task_context.task_characteristics.ui_heavy is false + gate: + question: UI mockups complete. Continue to Phase 5? + answer: Continue to Phase 5 + - id: phase-5 + name: Gather requirements & create specification + active_form: Gathering requirements & creating specification + status: completed + blocked_by: [phase-2, phase-3, phase-4] + started: "2026-07-13T18:24:43Z" + completed: "2026-07-13T18:59:02Z" + gate: + question: Continue to specification audit? + answer: Continue to specification audit + - id: phase-6 + name: Audit specification + active_form: Auditing specification + status: completed + blocked_by: [phase-5] + started: "2026-07-13T18:59:02Z" + completed: "2026-07-13T19:20:47Z" + gate: + question: Continue to implementation planning? + answer: Continue to implementation planning + - id: phase-7 + name: Plan implementation + active_form: Planning implementation + status: completed + blocked_by: [phase-6] + started: "2026-07-13T19:20:47Z" + completed: "2026-07-13T19:33:44Z" + gate: + question: Continue to implementation approval? + answer: Continue to implementation approval + - id: phase-8 + name: Execute implementation + active_form: Executing implementation + status: completed + blocked_by: [phase-7] + started: "2026-07-13T19:41:09Z" + completed: "2026-07-13T21:45:49Z" + gate: + question: Continue to verification? + answer: Continue to verification + - id: phase-9 + name: Verify test passes (TDD Green) + active_form: Verifying test passes + status: completed + blocked_by: [phase-8] + started: "2026-07-13T21:45:49Z" + completed: "2026-07-13T21:59:38Z" + gate: + question: TDD gate passed. Continue to Phase 10? + answer: Continue to Phase 10 + - id: phase-10 + name: Prompt verification options + active_form: Prompting verification options + status: completed + blocked_by: [phase-8, phase-9] + started: "2026-07-13T21:59:38Z" + completed: "2026-07-13T22:10:41Z" + gate: null + - id: phase-11 + name: Verify implementation & resolve issues + active_form: Verifying implementation + status: completed + blocked_by: [phase-10] + started: "2026-07-13T22:10:41Z" + completed: "2026-07-13T22:32:40Z" + summary: "The initial source-contract parity issue was fixed, Kiro's stale pre-schema-v2 CHAT GATE threshold was aligned with the current projection, and full repository validation passed." + gate: + question: "Continue to Phase 12?" + answer: "Continue to Phase 12" + - id: phase-12 + name: Run E2E tests + active_form: Running E2E tests + status: skipped + blocked_by: [phase-11] + started: "2026-07-13T22:43:04Z" + completed: "2026-07-13T22:43:04Z" + skip_reason: options.e2e_enabled is false + summary: "Browser E2E was skipped by the user's earlier optional-phase decision; native Codex evidence was already verified during implementation." + gate: + question: "E2E complete. Continue to Phase 13?" + answer: "Continue to Phase 13" + - id: phase-13 + name: Generate user documentation + active_form: Generating user documentation + status: completed + blocked_by: [phase-12] + started: "2026-07-13T22:49:32Z" + completed: "2026-07-13T22:53:00Z" + summary: "Created a user-facing Markdown guide and faithful HTML companion for automatic Codex workflow continuation; no screenshots were needed for this non-UI feature." + artifacts: + - path: documentation/user-guide.md + label: User guide + html: documentation/user-guide.html + gate: + question: "Documentation complete. Continue to Phase 14?" + answer: "Continue to Phase 14" + - id: phase-14 + name: Finalize workflow + active_form: Finalizing workflow + status: completed + blocked_by: [phase-13] + started: "2026-07-13T22:59:08Z" + completed: "2026-07-13T23:07:16Z" + summary: "Workflow finalized after the user approved the protected final handoff." + gate: + question: "Complete workflow or keep it open?" + answer: "Complete workflow" + +project_context: + project_doc_paths: + - .maister/docs/project/vision.md + - .maister/docs/project/roadmap.md + - .maister/docs/project/tech-stack.md + - .maister/docs/project/architecture.md + +task_context: + risk_level: high + clarifications_resolved: true + scope_expanded: false + tdd_red_passed: true + tdd_green_passed: true + tech_clarified: true + architecture_decision: A3/B1/C1/D1 from the referenced high-confidence research + task_characteristics: + has_reproducible_defect: true + modifies_existing_code: true + creates_new_entities: true + involves_data_operations: true + ui_heavy: false + research_reference: + path: .maister/tasks/research/2026-07-13-fix-codex-auto-continuation + research_question: Jak naprawić Codex fully_automatic tak, aby zgodność rekomendacji głównego agenta i advisora automatycznie wybierała decyzję, rozbieżność uruchamiała arbitra dokładnie raz, a wynik automatycznie kontynuował do następnego problemu bez interakcji użytkownika? + research_type: technical + confidence_level: high + design_reference: + source: null + product_design_path: null + mockup_count: 0 + has_brief: false + index_path: null + phase_summaries: + research: + summary: The high-confidence research recommends a shared executable gate evaluator, evaluator-owned terminal records, workflow-owned durable inventory and dispatch receipts, and a thin Codex binding; capability must remain unsupported until real host-native E2E passes. + key_findings: + - Agreement should terminate with the advisor and no UI. + - Disagreement should create exactly one logical arbiter with bounded retries. + - Runner commit is distinct from workflow dispatch and active-turn continuation. + - Same-phase and next-phase continuation require durable checkpoints and deduplicated dispatch IDs. + recommended_approach: Implement the A3/B1/C1/D1 architecture in canonical sources and the Codex adapter, then build generated variants and flip capability only after real host-native evidence. + decisions: + - decision: Use a shared executable evaluator and thin host binding. + rationale: This prevents prose drift while preserving portable host-native delegation. + - decision: Keep capability unsupported until native E2E exits successfully. + rationale: Shared tests do not prove active-turn continuation or absence of UI. + risks: + - The exact Codex active-turn hook and headless entrypoint require an implementation spike. + - Schema migration and concurrent YAML writers require fail-closed validation, locking, and revision/CAS. + artifacts: + - path: analysis/research-context/research-report.md + label: Research report + html: null + - path: analysis/research-context/solution-exploration.md + label: Solution exploration + html: null + - path: analysis/research-context/high-level-design.md + label: High-level design + html: null + - path: analysis/research-context/decision-log.md + label: Decision log + html: null + design: + summary: null + screen_count: 0 + component_count: 0 + index_path: null + decisions: [] + risks: [] + artifacts: [] + codebase_analysis: + key_files: + - plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md + - plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs + - plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md + - plugins/maister/skills/research/SKILL.md + - platforms/codex-cli/templates/advisor.toml + - platforms/codex-cli/build.sh + - platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh + - plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml + primary_language: JavaScript ESM + summary: The repository specifies fully automatic agreement and arbitration in prose, but has no executable evaluator, Codex active-turn binding, or durable workflow dispatcher. The existing runner persists a narrow synthesized record and exits after optional phase mutation, so the accepted A3/B1/C1/D1 architecture is required. + decisions: + - decision: Preserve separate evaluator, runner, workflow-routing, and Codex-binding boundaries. + rationale: Each boundary has different policy, durability, domain, and host responsibilities. + - decision: Keep Codex capability unsupported until native E2E evidence passes. + rationale: Shared and fake-port tests cannot prove active-turn continuation or absence of UI. + risks: + - The exact Codex host-native active-turn hook still requires a narrow implementation spike. + - Schema migration and shared writers require fail-closed locking, revision/CAS, atomic replacement, and mode/topology preservation. + - Exactly-once dispatch requires deterministic IDs and receiver deduplication across crash windows. + artifacts: + - path: analysis/codebase-analysis.md + label: Codebase analysis + html: null + - path: analysis/clarifications.md + label: Phase 1 clarifications + html: null + clarifications: + - The research-fixed A3/B1/C1/D1 architecture is binding for gap analysis. + - Product-design backward refinement and protected-gate automation are out of scope. + - Codex capability remains unsupported until real host-native evidence succeeds. + gap_analysis: + integration_points: + - Canonical orchestrator framework runtime and references + - Research, product-design, development, migration, and performance workflows + - Codex adapter, build projection, smoke checks, integration, and native E2E + - Shared contract, migration, workflow-loop, and failure-injection tests + - Makefile build, validation, and host capability matrix + summary: The repair is a high-risk modificative change with a deterministic native-runtime defect. The accepted A3/B1/C1/D1 architecture covers every identified gap, so no additional scope decision is needed and the workflow routes to TDD Red. + decisions: + - decision: Preserve the research-approved scope without expansion. + rationale: Every missing evaluator, state, routing, adapter, build, and verification touchpoint is already part of A3/B1/C1/D1. + - decision: Route through TDD Red. + rationale: The Codex-native capability test deterministically exits 77 and proves the missing runtime seam. + risks: + - The active-turn spike may disprove D1 and require returning to scope clarification before adopting D2. + - State schema migration and concurrent writers remain the highest correctness risk. + artifacts: + - path: analysis/gap-analysis.md + label: Gap analysis + html: null + - path: analysis/scope-clarifications.md + label: Scope clarifications + html: null + scope_clarifications: + scope_expanded: false + summary: No critical or important scope decisions remain; research already defines the complete repair and explicit exclusions. + decisions: [] + risks: + - A negative D1 spike result requires returning to scope clarification. + artifacts: + - path: analysis/scope-clarifications.md + label: Scope clarifications + html: null + requirements: + summary: Users continue through existing maister workflows with no new command or UI; implementation reuses canonical shared seams with only a thin Codex binding; no visual assets or requirements apply. + decisions: + - decision: Preserve the transparent existing-workflow journey. + rationale: Automatic eligible gates should continue within the active Codex turn without changing how users invoke Maister. + - decision: Reuse canonical framework and projection seams. + rationale: A shared evaluator prevents host-specific policy drift while a thin binding supplies Codex-native execution. + - decision: Exclude visual requirements. + rationale: This is a non-UI runtime and persistence repair with no visual assets. + risks: + - The real Codex active-turn hook still requires successful native evidence before capability promotion. + artifacts: + - path: analysis/requirements.md + label: Confirmed requirements + html: null + - path: analysis/technical-clarifications.md + label: Technical clarifications + html: null + tdd_red: + summary: A behavioral Codex workflow-loop contract now fails because the executable host binding is missing. It covers agreement without arbitration, disagreement with exactly one logical arbiter, zero user gates, and acknowledged dispatch to the next work item. + decisions: + - decision: Use a deterministic binding-level contract for the red gate. + rationale: It reproduces the missing executable seam while keeping external role and dispatch dependencies isolated. + risks: + - Passing this deterministic contract will not by itself justify changing the Codex capability matrix; real host-native E2E evidence is still required. + artifacts: + - path: implementation/tdd-red-gate.md + label: TDD red gate evidence + html: null + - path: ../../../../tests/codex-fully-automatic-workflow-loop.test.sh + label: Failing workflow-loop test + html: null + ui_mockups: + components_designed: [] + summary: UI mockup generation was skipped because this runtime and persistence repair has no user-interface surface. + decisions: [] + risks: [] + artifacts: [] + specification: + summary: The revised specification defines 30 plan-ready requirements across a shared evaluator, exact schema-v2 migration contract, durable receiver protocol, isolated native-evidence bootstrap, compatibility transitions, platform-bounded repository semantics, workflow routing, and a thin Codex binding. + decisions: + - decision: Use A3/B1/C1/D1 boundaries with one canonical evaluator. + rationale: This separates shared policy, durable state, workflow routing, and host mechanics without Codex-specific drift. + - decision: Treat exactly-once as one logical dispatch effect. + rationale: Physical retries reuse the same dispatch ID and receiver deduplication prevents duplicate target effects. + - decision: Keep Codex unsupported until native evidence succeeds. + rationale: Shared and fake-port tests cannot prove active-turn continuation or absence of UI. + risks: + - The exact Codex active-turn hook still requires a narrow implementation spike. + - Ambiguous legacy state migration must fail without mutation. + - Post-effect/pre-ack crashes depend on receiver deduplication. + - Recovery spans several durable commit boundaries. + artifacts: + - path: implementation/spec.md + label: Specification + html: implementation/spec.html + spec_audit: + summary: The initial audit found three high and two medium precision gaps. One targeted revision resolved F1-F5, and the focused re-audit declared the specification compliant and plan-ready with zero open findings. + decisions: + - decision: Accept the revised specification as plan-ready. + rationale: Exact schema/migration, dispatch recovery, native evidence bootstrap, compatibility, and repository semantics are now normative and testable. + risks: + - The D1 active-turn hook remains an implementation spike with an explicit stop-and-reclarify condition if disproved. + artifacts: + - path: verification/spec-audit.md + label: Specification audit + html: null + implementation_plan: + summary: The delegated planner organized all 30 requirements into seven sequential task groups with 39 steps and 25-34 feature tests. D1 viability is the hard first checkpoint; schema-v2 repository, shared evaluator, workflow continuation, thin Codex projection, native evidence/activation, and final gap review follow in dependency order. + task_groups: + - id: group-1 + name: Codex Active-Turn Hook Viability + status: completed + owner: maister:task-group-implementer + completed_at: "2026-07-13T19:48:58Z" + tests_passed: 3 + steps: 5 + tests: 3 + dependencies: [] + - id: group-2 + name: Schema-v2 State Repository and Migration + status: completed + owner: maister:task-group-implementer + completed_at: "2026-07-13T20:01:45Z" + tests_passed: 5 + steps: 6 + tests: 5 + dependencies: [group-1] + - id: group-3 + name: Shared Gate Evaluator and Policy Compatibility + status: completed + owner: maister:task-group-implementer + completed_at: "2026-07-13T20:10:33Z" + tests_passed: 34 + steps: 6 + tests: 5 + dependencies: [group-2] + - id: group-4 + name: Continuation Runner, Workflow Inventory, and Dispatch + status: completed + owner: maister:task-group-implementer + completed_at: "2026-07-13T20:22:23Z" + tests_passed: 12 + steps: 6 + tests: 5 + dependencies: [group-2, group-3] + - id: group-5 + name: Thin Codex Binding and Deterministic Build Projection + status: completed + owner: maister:task-group-implementer + completed_at: "2026-07-13T21:05:16Z" + tests_passed: 11 + steps: 6 + tests: 4 + dependencies: [group-1, group-3, group-4] + - id: group-6 + name: Native Evidence Bootstrap and Capability Activation + status: completed + owner: maister:task-group-implementer + started_at: "2026-07-13T21:08:15Z" + completed_at: "2026-07-13T21:24:27Z" + tests_passed: 13 + steps: 5 + tests: 3 + dependencies: [group-5] + - id: group-7 + name: Test Review and Gap Analysis + status: completed + owner: maister:task-group-implementer + started_at: "2026-07-13T21:28:33Z" + completed_at: "2026-07-13T21:32:57Z" + tests_passed: 34 + steps: 5 + tests: up to 9 additional + dependencies: [group-1, group-2, group-3, group-4, group-5, group-6] + decisions: + - decision: Make D1 viability the first hard checkpoint. + rationale: If same-turn continuation is impossible, stop and reclarify rather than introduce D2 or MCP. + - decision: Implement the state repository before all state writers. + rationale: Evaluator, runner, workflow, and dispatch operations need one lock, CAS, and atomic-commit contract. + - decision: Separate native evidence from capability activation. + rationale: Codex remains unsupported until real native evidence exits 0, followed by a distinct activation change. + risks: + - The exact Codex active-turn hook is not yet empirically proven. + - Native exit 77 preserves safety but cannot satisfy capability evidence. + - Filesystem repository semantics are platform-sensitive. + - Post-acknowledgement crashes must reuse the stored receipt without repeating target work. + - Generated variants must remain reproducible from canonical and adapter sources. + artifacts: + - path: implementation/implementation-plan.md + label: Implementation plan + html: implementation/implementation-plan.html + architecture_decision: + decision: null + summary: null + decisions: [] + risks: [] + artifacts: [] + advisor: + summary: null + decisions: [] + risks: [] + artifacts: [] + +verification_context: + last_status: passed + issues_found: [] + fixes_applied: + - Added exact schema-v2 fields, transitions, invariants, and a supported legacy migration matrix. + - Added durable receiver claim/checkpoint/ack semantics and post-effect retry deduplication. + - Added isolated evidence-only native entrypoint bootstrap and two-step capability activation. + - Added manual, Advisor, user_pending, fallback, and user-override schema-v2 transitions. + - Added platform-bounded lock, metadata, symlink, timeout, stale-owner, cleanup, and durability semantics. + - Added canonical JSON continuation contract markers to all five source workflow skills and rebuilt projections. + - Updated the Kiro CHAT GATE validation minimum from 53/200 to the schema-v2 projection floor of 42/166. + decisions_made: + - Revise the specification narrowly without changing A3/B1/C1/D1 architecture or scope. + - Apply all fixable verification findings and re-run the complete validation suite. + report_path: verification/implementation-verification.md + report_html_path: verification/implementation-verification.html + reverify_count: 2 diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.html b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.html new file mode 100644 index 00000000..f5789187 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.html @@ -0,0 +1,26 @@ + + + + +Decision Summary — Fix Codex automatic continuation + + + + +
Decision audit

Workflow Decision Summary

Generated 2026-07-13T22:59:08Z

+
24decisions
0advisor calls
0arbiter calls
Phase 14current phase
+

TL;DR

The implementation, verification, optional phases, and user documentation are complete. The workflow is at the protected final handoff gate and awaits an explicit choice to complete the workflow or keep it open.

Key Decisions

  • Continue to Phase 2 — the user approved gap analysis after reviewing Phase 1 artifacts.
  • Continue to Phase 3: TDD Red Gate — the user approved establishing an executable failing test.
  • Continue to Phase 4 — Phase 4 then skipped because the task is non-UI.
  • Continue to Phase 5 — begin requirements and specification.
  • Yes, use this journey — preserve existing maister:* entry points.
  • Yes, reuse these canonical seams — use shared runtime with a thin Codex binding.
  • Yes, no visual assets — no visual requirements apply.
  • Approve complete implementation scope — authorize Groups 1-7.
  • Try suggested fix — serialize Kiro builds with a repository-local lock and verify identical generated manifests.
  • Try suggested fix — implement the native bootstrap and prove native exit 0 before activation.
  • Continue to verification — all implementation groups completed.
  • Fix all fixable issues — synchronize source contracts, projections, and Kiro validation thresholds.
  • Continue to Phase 12 — proceed after green verification.
  • Skip E2E — browser E2E was disabled by the earlier optional-phase decision.
  • Continue to Phase 13 — generate the enabled user documentation.
  • Continue to Phase 14 — enter finalization after documentation completed.
+

Decision History

GateRecommendationSelectionActorConfidence
phase-1-exit
Continue to Phase 2?		Continue to Phase 2Continue to Phase 2UserHigh
phase-2-routing
Continue to Phase 3: TDD Red Gate?		Continue to Phase 3: TDD Red GateContinue to Phase 3: TDD Red GateUserHigh
phase-3-exit
TDD red gate complete. Continue to Phase 4?		Continue to Phase 4Continue to Phase 4UserHigh
phase-4-exit
UI mockups complete. Continue to Phase 5?		Continue to Phase 5Continue to Phase 5UserHigh
requirements-clarification
Transparent existing-workflow journey?		Yes, use this journeyYes, use this journeyUserHigh
requirements-clarification
Reuse canonical seams?		Yes, reuse these canonical seamsYes, reuse these canonical seamsUserHigh
requirements-clarification
No visual assets?		Yes, no visual assetsYes, no visual assetsUserHigh
phase-5-exit
Continue to specification audit?		Continue to specification auditContinue to specification auditUserHigh
optional-phase-selection
Run specification audit?		Yes, run audit (Recommended)Yes, run audit (Recommended)UserHigh
phase-8-exit
Continue to verification?		Continue to verificationContinue to verificationUserHigh

Context: codebase analysis · gap analysis · TDD red evidence · TDD green evidence · requirements

+

Latest decision

GateRecommendationSelectionActorConfidence
final-handoff-approval
Complete workflow or keep it open?		Complete workflowComplete workflowUserHigh

Workflow completed after the protected handoff decision. Commit template: fix(codex): enable durable fully automatic workflow continuation. Next: review the diff, run CI validation, and open the PR.

+ + diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.md new file mode 100644 index 00000000..541a3fe6 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.md @@ -0,0 +1,334 @@ +# Workflow Decision Summary + +## TL;DR + +The user explicitly approved the complete seven-group, 39-step implementation scope at the protected gate. Groups 1–7 and the TDD Green verification are complete; the workflow is awaiting the Phase 9 exit decision before verification-option review. +The configured `fully_automatic` policy used the interactive fallback at these workflow gates because the gates are user-facing checkpoints; Codex native continuation capability is now evidence-backed and `supported`. + +## Key Decisions + +- Continue to Phase 2 — the user approved gap analysis after reviewing the codebase analysis and clarifications. +- Continue to Phase 3: TDD Red Gate — the user approved establishing an executable failing test for the deterministic Codex-native continuation defect. +- Continue to Phase 4 — the user approved the persisted TDD Red evidence; Phase 4 then skipped because the task is non-UI. +- Continue to Phase 5 — the user approved routing from the skipped UI phase into requirements and specification work. +- Yes, use this journey — the repair remains transparent within existing `maister:*` workflows, without new commands or UI. +- Yes, reuse these canonical seams — extend shared runtime, build, capability, and test patterns; do not create a Codex-only evaluator. +- Yes, no visual assets — the non-UI specification has no visual implementation requirements. +- Continue to specification audit — the user approved the delegated, self-verified specification and advanced to Phase 6. +- Yes, run audit (Recommended) — the user enabled independent specification verification before planning. +- Continue to implementation planning — the user accepted the successful focused re-audit and advanced to Phase 7. +- Continue to implementation approval — the user accepted the complete plan for protected scope approval. +- Approve complete implementation scope — the user explicitly authorized Groups 1-7 for implementation. +- Continue to verification — the user approved the Phase 8 exit after all implementation groups completed. + +Generated: `2026-07-13T21:45:49Z` + +## Decision History + +### Phase 1 exit + +- **Gate type:** `phase-1-exit` +- **Question:** Continue to Phase 2? +- **Ordered options:** `Continue to Phase 2`; `Pause workflow` +- **Original recommendation:** Continue to Phase 2 +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Continue to Phase 2 +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [Codebase analysis](../analysis/codebase-analysis.md), [clarifications](../analysis/clarifications.md), [dashboard](../dashboard.html) + +### Phase 2 routing + +- **Gate type:** `phase-2-routing` +- **Question:** Continue to Phase 3: TDD Red Gate? +- **Ordered options:** `Continue to Phase 3: TDD Red Gate`; `Pause workflow` +- **Original recommendation:** Continue to Phase 3: TDD Red Gate +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Continue to Phase 3: TDD Red Gate +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [Gap analysis](../analysis/gap-analysis.md), [scope clarifications](../analysis/scope-clarifications.md), [dashboard](../dashboard.html) + +### Phase 3 exit + +- **Gate type:** `phase-3-exit` +- **Question:** TDD red gate complete. Continue to Phase 4? +- **Ordered options:** `Continue to Phase 4`; `Pause workflow` +- **Original recommendation:** Continue to Phase 4 +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Continue to Phase 4 +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [TDD red evidence](../implementation/tdd-red-gate.md), [dashboard](../dashboard.html) + +### Phase 4 exit + +- **Gate type:** `phase-4-exit` +- **Question:** UI mockups complete. Continue to Phase 5? +- **Ordered options:** `Continue to Phase 5`; `Pause workflow` +- **Original recommendation:** Continue to Phase 5 +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Continue to Phase 5 +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** Phase 4 skipped because `ui_heavy` is false; [dashboard](../dashboard.html) + +### Phase 5 requirements — user journey + +- **Gate type:** `requirements-clarification` +- **Question:** Is the repair transparent to users of existing `maister:*` workflows, with automatic gates continuing in the active Codex turn? +- **Ordered options:** `Yes, use this journey`; `No, revise the journey` +- **Original recommendation:** Yes, use this journey +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Yes, use this journey +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [Requirements](../analysis/requirements.md), [dashboard](../dashboard.html) + +### Phase 5 exit + +- **Gate type:** `phase-5-exit` +- **Question:** Continue to specification audit? +- **Ordered options:** `Continue to specification audit`; `Pause workflow` +- **Original recommendation:** Continue to specification audit +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Continue to specification audit +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [Specification](../implementation/spec.md), [HTML companion](../implementation/spec.html), [dashboard](../dashboard.html) + +### Phase 6 optional selection + +- **Gate type:** `optional-phase-selection` +- **Question:** Run specification audit? (Recommended) +- **Ordered options:** `Yes, run audit (Recommended)`; `No, skip audit` +- **Original recommendation:** Yes, run audit (Recommended) +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Yes, run audit (Recommended) +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [Specification](../implementation/spec.md), [dashboard](../dashboard.html) + +### Phase 5 requirements — existing code reuse + +- **Gate type:** `requirements-clarification` +- **Question:** Must implementation reuse canonical framework, runtime, build projections, capability matrix, and tests with only a thin Codex binding? +- **Ordered options:** `Yes, reuse these canonical seams`; `No, revise the reuse constraints` +- **Original recommendation:** Yes, reuse these canonical seams +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Yes, reuse these canonical seams +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [Requirements](../analysis/requirements.md), [technical clarifications](../analysis/technical-clarifications.md), [dashboard](../dashboard.html) + +### Phase 5 requirements — visual assets + +- **Gate type:** `requirements-clarification` +- **Question:** Are there no visual assets or visual implementation requirements for this non-UI repair? +- **Ordered options:** `Yes, no visual assets`; `No, I will provide visual assets` +- **Original recommendation:** Yes, no visual assets +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Yes, no visual assets +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [Requirements](../analysis/requirements.md), [dashboard](../dashboard.html) + +### Phase 6 exit + +- **Gate type:** `phase-6-exit` +- **Question:** Continue to implementation planning? +- **Ordered options:** `Continue to implementation planning`; `Pause workflow` +- **Original recommendation:** Continue to implementation planning +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Continue to implementation planning +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [Specification audit](../verification/spec-audit.md), [Specification](../implementation/spec.md), [dashboard](../dashboard.html) + +### Phase 7 exit + +- **Gate type:** `phase-7-exit` +- **Question:** Continue to implementation approval? +- **Ordered options:** `Continue to implementation approval`; `Pause workflow` +- **Original recommendation:** Continue to implementation approval +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Continue to implementation approval +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [Implementation plan](../implementation/implementation-plan.md), [HTML companion](../implementation/implementation-plan.html), [dashboard](../dashboard.html) + +### Protected implementation approval + +- **Gate type:** `implementation-approval` +- **Question:** Approve this complete implementation scope? +- **Ordered options:** `Approve complete implementation scope`; `Reject implementation scope`; `Request scope changes` +- **Original recommendation:** Approve complete implementation scope +- **Configured policy:** `fully_automatic` +- **Effective path:** explicit user decision; this protected gate is denylisted from automation +- **Selected option:** Approve complete implementation scope +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Approved scope:** `group-1` through `group-7` +- **Context:** [Implementation plan](../implementation/implementation-plan.md), [Work log](../implementation/work-log.md), [dashboard](../dashboard.html) + +### Group 6 failure recovery + +- **Gate type:** `group-failure-recovery` +- **Question:** Group 6 native evidence is unavailable (exit 77); Codex remains unsupported. How to proceed? +- **Ordered options:** `Try suggested fix`; `Retry group`; `Complete manually`; `Rollback changes`; `Stop` +- **Original recommendation:** Stop +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because the initial native harness was unavailable +- **Selected option:** Try suggested fix +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Resolution:** Added the test-only native bootstrap, observed exit `0` before activation and again after separate activation to `supported`; forced unavailability remains exit `77`. +- **Context:** [Implementation plan](../implementation/implementation-plan.md), [Work log](../implementation/work-log.md), [dashboard](../dashboard.html) + +### Group 5 failure recovery + +- **Gate type:** `group-failure-recovery` +- **Question:** Group 5 implementation failed: complete generated-tree reproducibility is blocked by alternating Kiro build topology. How to proceed? +- **Ordered options:** `Try suggested fix`; `Retry group`; `Complete manually`; `Rollback changes`; `Stop` +- **Original recommendation:** Try suggested fix +- **Configured policy:** `fully_automatic` +- **Effective path:** manual interactive fallback because Codex capability is `unsupported` +- **Selected option:** Try suggested fix +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Resolution:** Moved the Kiro build lock to a repository-local gitignored path, added a concurrent-build regression test, and verified two identical aggregate generated-tree manifests. +- **Context:** [Implementation plan](../implementation/implementation-plan.md), [Work log](../implementation/work-log.md), [dashboard](../dashboard.html) + +### Phase 8 exit + +- **Gate type:** `phase-8-exit` +- **Question:** Continue to verification? +- **Ordered options:** `Continue to verification`; `Pause workflow` +- **Original recommendation:** Continue to verification +- **Configured policy:** `fully_automatic` +- **Effective path:** explicit user decision at the phase-exit checkpoint +- **Selected option:** Continue to verification +- **Final actor:** user +- **Confidence:** high +- **Advisor attempts:** 0 +- **Arbiter attempts:** 0 +- **User override:** false +- **Context:** [TDD Green evidence](../implementation/tdd-green-gate.md), [dashboard](../dashboard.html) + +### Phase 10 verification options + +- **Selected standard reviews:** Code review; Pragmatic review; Reality check; Production readiness +- **Browser E2E:** skipped because this is a non-UI runtime repair +- **User documentation:** enabled + +### Phase 11 verification fix selection + +- **Gate type:** `verification-fix-selection` +- **Selected option:** Fix all fixable issues +- **Final actor:** user +- **Resolution:** Added the canonical runner contract markers to all five source workflows, rebuilt projections, and aligned the Kiro CHAT GATE floor with schema-v2 (42/166). + +### Phase 11 verification result + +- **Status:** passed after re-verification +- **Contract suite:** 29/29 +- **Full validation:** `make validate` exit 0 +- **Phase-continue matrix:** 24/24 across four runtimes +- **Native Codex evidence:** 3/3 before and after activation +- **Next gate:** `Continue to Phase 12?` +- **Context:** [Implementation verification](../verification/implementation-verification.md), [HTML report](../verification/implementation-verification.html), [Work log](../implementation/work-log.md), [dashboard](../dashboard.html) + +### Phase 11 exit + +- **Selected option:** Continue to Phase 12 +- **Final actor:** user +- **Result:** Phase 12 entered; browser E2E remained skipped because `options.e2e_enabled` is false. + +### Phase 12 exit + +- **Status:** Phase 12 skipped by configuration +- **Question:** E2E complete. Continue to Phase 13? +- **Ordered options:** `Continue to Phase 13`; `Pause workflow` +- **Next gate:** awaiting user decision + +### Phase 13 documentation + +- **Status:** complete +- **Artifacts:** [User guide](../documentation/user-guide.md), [HTML companion](../documentation/user-guide.html) +- **Scope:** Existing `maister:*` workflows, automatic agreement continuation, one-Arbiter disagreement handling, durable retry/resume, protected gates, fail-closed behavior, and troubleshooting. +- **Screenshots:** none; this is a non-UI runtime feature and Phase 12 E2E was skipped. +- **Next gate:** `Documentation complete. Continue to Phase 14?` + +### Phase 13 exit + +- **Selected option:** Continue to Phase 14 +- **Final actor:** user +- **Result:** Entered finalization after the user guide and HTML companion passed artifact checks. + +### Final handoff approval + +- **Gate type:** `final-handoff-approval` (protected / denylisted) +- **Question:** Complete workflow or keep it open? +- **Ordered options:** `Complete workflow`; `Keep workflow open` +- **Status:** pending explicit user decision + +### Final handoff result + +- **Selected option:** Complete workflow +- **Final actor:** user +- **Result:** Workflow completed after the protected handoff decision. +- **Commit message template:** `fix(codex): enable durable fully automatic workflow continuation` +- **Next steps:** Review the diff, run the already-passing validation suite in CI, then open the PR for code review and deployment planning. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/verification/implementation-verification.html b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/verification/implementation-verification.html new file mode 100644 index 00000000..48e79f18 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/verification/implementation-verification.html @@ -0,0 +1,44 @@ + + + + + + Implementation Verification + + + +
+ PASSED +

Implementation Verification

+

The selected fixes resolved source-contract parity and Kiro validation drift. Full repository validation is green.

+
+
+

Fixes applied

+
    +
  1. Added the canonical JSON continuation runner contract to all five source workflow skills.
    2. +
  2. Rebuilt Codex, Cursor, and Kiro projections.
    3. +
  3. Updated and documented the schema-v2 Kiro CHAT GATE floor at 42/166.
    4. +
+

Passing checks

+
    +
  • tests/gate-decision-engine.test.sh: 29/29.
    • +
  • make validate: exit 0.
    • +
  • Phase-continue matrix: 24/24 across four runtimes.
    • +
  • Workflow-loop: 4/4; host capability matrix: 6/6.
    • +
  • Native Codex evidence: 3/3 before and after activation.
    • +
  • YAML, dashboard JavaScript, and diff checks passed.
    • +
+
+
+

Conclusion

+

The implementation is verified and ready for the Phase 11 exit decision.

+
+ + diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/verification/implementation-verification.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/verification/implementation-verification.md new file mode 100644 index 00000000..e5237a7b --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/verification/implementation-verification.md @@ -0,0 +1,63 @@ +# Implementation Verification + +## Verdict + +**Status:** `passed` — the selected fixes resolved the source-contract parity +failure and the follow-up Kiro validation drift. Full repository validation is +green. + +## Reverification + +The user selected **Fix all fixable issues**. The following fixes were applied: + +1. Added the canonical JSON continuation runner contract markers to the five + source workflow skills (`development`, `migration`, `performance`, + `product-design`, and `research`), including the exact payload, transport, + persistence, fail-closed, and retry wording required by the contract suite. +2. Rebuilt Codex, Cursor, and Kiro projections from the canonical sources. +3. Updated the Kiro CHAT GATE validation floor from the retired pre-schema-v2 + counts (53/200) to the current projection minimum (42/166), and documented + the schema-v2 phase-entry evidence rationale. + +## Results + +### Critical (0) + +No critical findings remain. + +### Warnings (0) + +No warnings remain in the completed checks. + +### Informational (0) + +No informational findings were recorded. + +## Passing checks + +- `bash tests/gate-decision-engine.test.sh`: 29 passed, 0 failed. +- `make validate`: exit 0; contract, phase-continue, Codex binding, host + capability, Cursor, Kiro, Codex, and diff validation all passed. +- `make validate-phase-continue`: 24 contract cases passed across source, + Codex, Cursor, and Kiro projections (6 per runtime). +- `bash tests/codex-fully-automatic-workflow-loop.test.sh`: 4 passed, 0 failed. +- `bash tests/host-capability-matrix.test.sh`: 6 passed, 0 failed. +- Real Codex native continuation evidence: 3/3 scenarios passed before and + after separate activation to `supported`. +- YAML parsing, dashboard JavaScript syntax, and `git diff --check`: passed. + +## Review coverage + +- Code review: runtime binding, shared evaluator, repository locking, denylist + enforcement, and generated projection ownership inspected. +- Pragmatic review: the implementation remains within the approved A3/B1/C1/D1 + scope; the original failure was contract synchronization, not a new seam. +- Reality check: workflow-loop and native Codex evidence prove agreement, + single arbitration, durable continuation, resume/deduplication, and no hidden + user gate. +- Production readiness: projection, capability, syntax, Kiro transform, and + fail-closed continuation checks pass. + +## Conclusion + +The implementation is verified and ready for the Phase 11 exit decision. diff --git a/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/verification/spec-audit.md b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/verification/spec-audit.md new file mode 100644 index 00000000..b7534fc3 --- /dev/null +++ b/.maister/tasks/development/2026-07-13-fix-codex-auto-continuation/verification/spec-audit.md @@ -0,0 +1,120 @@ +# Specification Audit: Codex Fully Automatic Continuation + +## TL;DR + +The corrected specification is **plan-ready and compliant**. It retains the accepted A3/B1/C1/D1 architecture and now resolves every finding from the initial audit with normative, repository-grounded contracts for schema migration, dispatch recovery, capability evidence, mixed policies, and filesystem behavior. + +The Markdown specification and HTML companion are materially consistent. Both preserve the confirmed no-UI user journey, canonical/generated ownership, protected-gate safety, and the requirement that Codex remain `unsupported` until real native evidence succeeds. + +**Overall status:** ✅ Compliant (pre-implementation) +**Open findings:** 0 Critical, 0 High, 0 Medium, 0 Low +**Resolved findings:** F1–F5 +**Blocking ambiguities:** None +**Scope assessment:** Correct; no scope expansion is required. + +## Key Decisions Verified + +- A3/B1/C1/D1 remains binding: one shared evaluator, evaluator-owned full gate envelope, workflow-owned inventory/outbox/receipt, and a thin Codex binding (`implementation/spec.md:12-19`, `95-100`, `104-114`). +- Schema-v2, migration, policy transition, dispatch, repository, and evidence-bootstrap behavior is now normative rather than left to planner inference (`implementation/spec.md:116-171`). +- Runner responsibility remains narrow and domain-independent (`implementation/spec.md:55`, `106-108`). +- Canonical sources and adapters remain the only edit targets, with generated variants produced deterministically (`implementation/spec.md:63`, `86-91`, `199-203`; `.maister/docs/standards/global/build-pipeline.md:3-10`). +- Protected/denylisted gates never gain automatic continuation, and implementation approval remains out of scope (`implementation/spec.md:42`, `50`, `60`, `64-70`, `207-213`; `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:107-128`). +- Capability activation still requires the real Codex entrypoint and distinguishes exit `0` from unavailable exit `77` (`implementation/spec.md:64`, `167-177`, `232-234`; `Makefile:29-52`). + +## Open Questions / Risks + +No specification ambiguity blocks implementation planning. + +One accepted implementation risk remains: the exact Codex active-turn hook must be proved by the planned narrow spike. The specification supplies the correct stop condition—if D1 is disproved, return to scope clarification before considering an MCP fallback (`implementation/spec.md:21-26`, `177`; `analysis/technical-clarifications.md:16-18`). This is a dependency risk, not an unresolved specification decision. + +## Re-audit of Initial Findings + +### F1 — Schema-v2 and migration contract + +- **Previous severity/category:** High — Missing / Incomplete +- **Resolution status:** Resolved +- **Corrected specification evidence:** + - R12, R13, and R26 bind implementation to the normative contract and migration matrix (`implementation/spec.md:52-54`, `66`). + - The root, phase, gate, role-attempt, provenance, inventory, enum, nullability, and timestamp requirements are explicit (`implementation/spec.md:116-126`). + - Supported legacy shapes, deterministic mappings, revision-1 migration, preserved/non-authorizing legacy provenance, and named rejection boundaries are explicit (`implementation/spec.md:128-140`). + - Success criteria require validation of every field/transition and every migration row/rejection (`implementation/spec.md:224-226`). +- **Repository grounding:** This directly addresses the current exact schema-v1 validator and optional cursor behavior in `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs:502-561`, plus the migration gaps identified in `analysis/gap-analysis.md:53-54`, `65-70`, and `169-173`. +- **Verdict:** The planner no longer needs to invent which legacy shapes authorize new effects or which must fail closed. + +### F2 — Crash-after-effect receiver deduplication + +- **Previous severity/category:** High — Ambiguous / Incomplete +- **Resolution status:** Resolved +- **Corrected specification evidence:** + - R18 and R27 define `pending → claimed → acknowledged|blocked`, token/lease claim semantics, and one atomic checkpoint-plus-acknowledgement commit as the sole logical start effect (`implementation/spec.md:58`, `67`). + - Claimed state starts no target work; post-commit/pre-observation retry returns the stored acknowledgement; source/target/dispatch identity is immutable (`implementation/spec.md:153-159`). + - Required tests cover claimed-only crash, safe same-ID reclaim, and post-ack-commit failure with one checkpoint and one logical target start (`implementation/spec.md:193`, `222`). +- **Repository grounding:** The contract fills the previously absent workflow receiver identified in `analysis/gap-analysis.md:55-59`, `65-69`, and `175-194`; it goes beyond the simple fixture dispatcher in `tests/codex-fully-automatic-workflow-loop.test.sh:32-40` without treating that unimplemented production path as a defect. +- **Verdict:** The logical effect and uncertain crash window now have an implementable durable boundary. + +### F3 — Capability activation and native-E2E bootstrap + +- **Previous severity/category:** High — Ambiguous +- **Resolution status:** Resolved +- **Corrected specification evidence:** + - R24 and R29 limit the bootstrap to a repository-owned, non-packaged platform test adapter that changes declaration eligibility only and is unreachable from production CLI, environment, configuration, or workflow input (`implementation/spec.md:64`, `69`). + - The evidence bootstrap must invoke the real Codex plugin/skill entrypoint while preserving all safety and no-UI checks (`implementation/spec.md:167-170`). + - Activation is explicitly two-step: native exit `0` while still declared unsupported, then a separate declaration change and normal capability-matrix run (`implementation/spec.md:171`, `232-234`). + - Tests must prove bootstrap isolation from generated/installable artifacts and normal inputs (`implementation/spec.md:194`). +- **Repository grounding:** This resolves the bootstrap cycle between the current eligibility rule (`plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:110-119`), unsupported Codex row (`plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml:16-18`), native exit `77` placeholder (`platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh:1-5`), and declaration/evidence equality check (`Makefile:29-52`). +- **Verdict:** Native proof can precede activation without exposing a production bypass or weakening safety. + +### F4 — Manual and Advisor-assisted schema-v2 behavior + +- **Previous severity/category:** Medium — Incomplete +- **Resolution status:** Resolved +- **Corrected specification evidence:** + - R22 and R28 bind manual, Advisor, user override, unsupported fallback, and `user_pending` resume behavior (`implementation/spec.md:62`, `68`). + - The normative transition table defines manual; Advisor agreement and disagreement; user override precedence; unsupported automatic fallback; and pending resume (`implementation/spec.md:142-151`). + - The test plan and success criteria require each path without duplicate role/user decisions (`implementation/spec.md:190`, `226`, `230`). +- **Repository grounding:** These transitions preserve the existing user-final-choice contract in `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:119-126` and cover the compatibility risks recorded in `analysis/gap-analysis.md:122-132` and `140-149`. +- **Verdict:** Schema-v2 adoption no longer leaves existing policy semantics implicit. + +### F5 — Repository metadata and lock semantics + +- **Previous severity/category:** Medium — Ambiguous +- **Resolution status:** Resolved +- **Corrected specification evidence:** + - R14 and R30 bind owner-token locking, revision comparison, symlink rejection, bounded supported-platform semantics, safe metadata handling, and token-owned cleanup (`implementation/spec.md:54`, `70`). + - The repository contract defines sibling-directory lock structure, timeout, conservative stale-lock reclaim, successor protection, canonicalization, regular-file checks, exact mode preservation, safely possible ownership preservation, flush/rename/directory durability, and cleanup (`implementation/spec.md:161-165`). + - Tests cover live/expired/malformed/foreign locks, cleanup tokens, symlinks, metadata, stale revisions, and platform durability (`implementation/spec.md:191-193`, `227-228`). +- **Repository grounding:** This precisely extends the current writer, which has staging, file `fsync`, and rename but lacks lock/CAS/mode/directory durability (`plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs:597-616`; `analysis/gap-analysis.md:74-78`). +- **Verdict:** The requirements are implementable on the declared macOS/Linux Node runtimes and do not require unconditional privileged ownership changes. + +## Markdown / HTML Consistency + +The HTML companion faithfully contains the corrected normative content: + +- Schema-v2 fields and migration matrix: `implementation/spec.html:248-282` +- Manual/Advisor/fallback transitions: `implementation/spec.html:284-286` +- Dispatch claim/checkpoint/acknowledgement: `implementation/spec.html:288-291` +- Platform-bounded repository contract: `implementation/spec.html:293-296` +- Native evidence bootstrap and two-step activation: `implementation/spec.html:298-301` +- Matching test and success criteria: `implementation/spec.html:316-366` + +No material requirement is present only in the visual companion, and no visual implementation requirement has been introduced. + +## Completeness and Traceability Assessment + +| Area | Assessment | Evidence | +|---|---|---| +| User journey / no UI | Complete | `implementation/spec.md:28-37`, `41`, `209` | +| A3/B1/C1/D1 boundaries | Complete | `implementation/spec.md:12-19`, `95-114` | +| Agreement / arbitration | Complete | `implementation/spec.md:47-49`, `217-219` | +| State / migration | Complete | `implementation/spec.md:52-54`, `116-140`, `224-225` | +| Dispatch / recovery | Complete | `implementation/spec.md:58-61`, `67`, `153-159`, `222` | +| Existing-policy compatibility | Complete | `implementation/spec.md:62`, `68`, `142-151`, `226`, `230` | +| Repository safety | Complete | `implementation/spec.md:54`, `65`, `70`, `161-165`, `227-228` | +| Build / generated ownership | Complete | `implementation/spec.md:63`, `86-91`, `199` | +| Capability evidence | Complete | `implementation/spec.md:64`, `69`, `167-177`, `232-234` | +| Testing | Complete and risk-proportionate | `implementation/spec.md:185-195` | +| Scope / visuals | Complete | `implementation/spec.md:205-213`; no UI artifacts required | + +## Final Verdict + +The specification is complete, internally consistent, repository-grounded, testable, correctly scoped, and sufficiently unambiguous for Phase 7 implementation planning. The plan should preserve the stated dependency ordering by proving the D1 active-turn hook before downstream binding-dependent implementation, but no further specification correction or user clarification is required. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/clarifications.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/clarifications.md new file mode 100644 index 00000000..2a7038c2 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/clarifications.md @@ -0,0 +1,27 @@ +# Phase 1 Clarifications + +## TL;DR +The user confirmed the research-approved implementation scope. +The supported targets are Codex, Cursor, and Kiro CLI; Claude and committed generated trees are migration-only and must be removed before completion. +Legacy builders may remain temporarily as parity oracles during implementation. + +## Key Decisions +- Confirm the complete research-approved migration scope before gap analysis. + +## Open Questions / Risks +- Exact deletion and parity criteria remain implementation-planning concerns and must be made testable before legacy removal. + +## Clarification Record + +**Question:** I assume the implementation scope is Codex, Cursor, and Kiro CLI only, with Claude and committed generated trees removed before completion. Is that correct? + +**Answer:** Confirm assumptions + +**Confirmed scope:** + +- Build one portable common source and one shared core test surface. +- Maintain explicit repository-owned overlays for Codex, Cursor, and Kiro CLI. +- Materialize and install a selected target from a local checkout or immutable GitHub source reference. +- Add transactional staging, validation, receipt ownership, settings handling, atomic commit, recovery, update, uninstall, and rollback. +- Use current generated trees/builders only as temporary comparison oracles. +- Remove Claude support, generated trees, and obsolete generation/drift infrastructure before task completion. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/codebase-analysis.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/codebase-analysis.md new file mode 100644 index 00000000..1d0d30fb --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/codebase-analysis.md @@ -0,0 +1,169 @@ +# Codebase Analysis: Platform-Independent Maister Distribution + +## TL;DR +The repository currently uses a Claude-oriented canonical tree, three rewrite-heavy host builders, three committed generated trees, and three host-specific installers. +Five portable ESM runtime modules and several transactional/configuration tests are strong foundations for a common core. +The migration seam is a neutral common source plus explicit Codex, Cursor, and Kiro CLI overlays, assembled and installed by one target-aware transactional installer. +The highest risks are semantic drift in gate/delegation/hooks vocabulary, unsafe destination mutation, settings ownership, and deleting legacy trees before parity evidence is complete. + +## Key Decisions +- Treat `plugins/maister/skills/orchestrator-framework/bin/` as the initial portable-runtime boundary because its five core modules are byte-identical across current targets. +- Replace global prose rewrites with repository-owned host overlays and typed semantic bindings for control flow, safety, persistence, and capability evidence. +- Run the common behavior suite once and retain per-host tests only for overlay, materialization, installation, and real host evidence. +- Keep legacy generated trees as a temporary comparison oracle, then delete them and Claude-specific support before this task is complete. + +## Open Questions / Risks +- The final neutral source layout and exact overlay schema must be chosen without copying current generator complexity into a new abstraction. +- Settings that are shared with a host require explicit `whole_file` or `managed_keys` ownership and byte-exact rollback tests. +- Host contracts and runtime evidence may be unavailable; `unavailable` must remain explicit and must never be treated as pass. +- Repository docs, CI, release, and project standards currently describe the generated-tree/Claude model and must move with the implementation. + +## 1. Task Scope and Characteristics + +The task is a migration and architecture change, not a defect fix or UI feature. It modifies existing code and creates new installer, overlay, schema, receipt, and test entities. It performs filesystem/configuration data operations and has no UI-heavy surface. + +Expected characteristics for Phase 2: + +- `has_reproducible_defect`: false +- `modifies_existing_code`: true +- `creates_new_entities`: true +- `involves_data_operations`: true +- `ui_heavy`: false +- risk: high, because the change crosses source ownership, packaging, installation, rollback, CI, and supported-host policy. + +## 2. Current Repository Structure + +```text +plugins/maister/ Claude-oriented canonical source +platforms/codex-cli/build.sh Codex projection builder +platforms/cursor/build.sh Cursor projection builder +platforms/kiro-cli/build.sh Kiro projection builder +plugins/maister-codex/ committed generated Codex tree +plugins/maister-cursor/ committed generated Cursor tree +plugins/maister-kiro/ committed generated Kiro tree +tests/ common shell/Node contract tests +Makefile build, validation, drift, and host matrix orchestration +.github/workflows/ generated drift, release, and host smoke workflows +``` + +The canonical tree contains roughly 136 files: skills, agents, command wrappers, Claude hooks, a Claude plugin manifest, `CLAUDE.md`, and shared MCP configuration. The current committed projections together contain roughly 474 generated/duplicated files. These counts are useful inventory evidence, not semantic contracts. + +## 3. Existing Portable Core + +The strongest candidate for `common/runtime` is: + +- `plugins/maister/skills/orchestrator-framework/bin/gate-evaluator.mjs` +- `plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-repository.mjs` +- `plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-schema.mjs` +- `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` +- `plugins/maister/skills/orchestrator-framework/bin/workflow-continuation.mjs` + +These modules are currently byte-identical in the canonical, Codex, Cursor, and Kiro trees. They already implement state schema validation, durable state writes, gate evaluation, idempotency, continuation, leases, outbox/checkpoints, and safety boundaries. They should be moved or re-owned as common source rather than copied into maintained host trees. + +The canonical prose layer is not neutral. Relevant host vocabulary and assumptions occur in `plugins/maister/CLAUDE.md`, the orchestrator framework, `docs-manager`, `init`, `standards-discover`, `quick-plan`, `development`, hooks, agents, and wrappers. Examples include `AskUserQuestion`, `TaskCreate`, `TaskUpdate`, `Skill tool`, `Task tool`, `CLAUDE.md`, `${CLAUDE_PLUGIN_ROOT}`, and `${CLAUDE_PROJECT_DIR}`. + +## 4. Current Build and Distribution Flow + +The current flow is: + +```text +plugins/maister/ + ├─ platforms/cursor/build.sh → plugins/maister-cursor/ + ├─ platforms/kiro-cli/build.sh → plugins/maister-kiro/ + └─ platforms/codex-cli/build.sh→ plugins/maister-codex/ +``` + +`platforms/cursor/build.sh` is about 582 lines and performs global renames, tool-vocabulary rewrites, directory moves, agent metadata injection, command collapse, and host asset injection. `platforms/kiro-cli/build.sh` is about 860 lines, with a separate 160-line JSON agent generator; it performs command merging, agent serialization, gate/delegation rewrites, shortcuts, steering, MCP relocation, and install-time path rewriting. `platforms/codex-cli/build.sh` is about 338 lines and creates a manifest, converts commands to skills, rewrites host vocabulary, synthesizes utilities, and injects hooks/templates. + +These builders are not thin overlays. They contain duplicated transform logic and silent-failure surface. They are migration inputs and inventories of host differences, not the target architecture. + +The Makefile currently owns build targets, generated-tree validation, a four-runner phase-continuation matrix, byte-comparison checks, host capability projection, and large structural validation blocks. `.github/workflows/validate-generated-variants.yml` also assumes committed generated trees and drift checks. + +## 5. Current Installation Flow and Safety Gaps + +Host-specific installers are: + +- `platforms/cursor/smoke-install.sh`: builds, deletes the destination, copies the generated tree, and optionally adds MCP. +- `platforms/kiro-cli/smoke-install.sh`: clears an isolated profile, copies the tree, rewrites prompt/hook paths, and manages aliases/settings. +- `platforms/codex-cli/smoke-install.sh`: registers a local marketplace, invokes Codex installation, then mutates the installed tree. +- `platforms/kiro-cli/smoke-uninstall.sh`: removes the Kiro profile. + +The current installers are not transactional. Cursor and Kiro mutate or clear destinations before a complete validation boundary; Codex depends on marketplace installation and then performs mutations. There is no shared target-aware source resolver, overlay contract, receipt store, recovery journal, settings ownership model, or byte-exact managed-tree rollback. + +The target pipeline should be: + +```text +resolve local/GitHub source and immutable ref + → load target overlay + → probe host facts + → classify capability compatibility + → acquire target/scope lock + → assemble common + overlay into staging + → validate schema, paths, inventory, references, vocabulary, and hashes + → snapshot managed tree and settings + → commit atomically + → write immutable receipt + → publish active receipt +``` + +Any failure before publication must restore bytes, modes, symlinks, and directory topology. Uninstall must use receipt ownership and preserve user drift. + +## 6. Host Overlay Inputs + +Likely assets to move under explicit repository-owned overlays: + +- Codex: `platforms/codex-cli/templates/`, `bin/fully-automatic-gate.mjs`, `hooks/`, and `tests/`. +- Cursor: `platforms/cursor/agents/`, `overrides/`, `patches/`, `rules/`, `templates/`, `hooks/`, and `tests/`. +- Kiro CLI: `agent-tools.json`, `overrides/`, `templates/`, `transforms/`, `hooks/`, `generate-agent-json.sh`, and `tests/`. + +Every overlay should declare host ID and contract version, managed layout/discovery root, native asset inventory, agents/commands/hooks/settings/MCP placement, semantic versus packaging capability classification, bindings for user gates/delegation/continuation/safety, evidence target/fingerprint constraints, settings ownership, forbidden vocabulary, required paths, and path allowlists. + +The overlay must not copy generic skills or render arbitrary prose. A host can own a native asset directly, while common instructions describe intent and the host harness owns ordinary tool selection. + +## 7. Reusable Patterns + +The repository already contains patterns to reuse: + +- `plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-schema.mjs`: exact field allowlists, format/type validation, legal transitions, and canonical serialization. +- `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs`: strict transport validation, denylist checks, safe retry and idempotency. +- `plugins/maister/skills/init/bin/reconcile-advisor-config.sh`: candidate staging, preservation of modes/ownership, same-directory rename, and rollback. +- `plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-repository.mjs`: locks, leases, revision/CAS checks, symlink rejection, fsync, atomic rename, metadata preservation, and cleanup. +- `plugins/maister/skills/orchestrator-framework/bin/workflow-continuation.mjs`: durable dispatch IDs, outbox, claim leases, checkpoints, acknowledgement, reclaim, and idempotent reuse; this is the closest existing receipt-like pattern. +- `platforms/kiro-cli/tests/reproducible-build.test.sh`: stable inventories, SHA-256 manifests, a build lock, concurrent rebuild serialization, and byte comparison. +- `tests/phase-continue-contract.test.sh`, `tests/orchestrator-state-repository.test.sh`, `tests/advisor-config-reconciliation.test.sh`, and `tests/advisor-init-lifecycle.test.sh`: byte, mode, existence, topology, and injected-failure assertions. +- `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml`, `Makefile` capability targets, and `tests/host-capability-matrix.test.sh`: explicit passed/failed/unavailable/missing outcomes and fail-closed projection. + +Avoid using the current long `sed`/`awk` rewrite lists, generated utility bodies embedded in shell functions, `rm -rf` install-before-validation, hard-coded directory counts, global boolean support claims, and structural scripts that are labeled as runtime smoke tests. + +## 8. Test and CI Coverage + +The repository has about 13 common shell tests, Codex tests, Cursor install/inventory/continuation tests, and a much larger Kiro generator/build/install suite. Common tests meaningfully cover gate evaluation, state repository behavior, workflow continuation, phase continuation, advisor config/lifecycle, migration, snapshots, and Codex workflow loops. + +The same phase-continuation contract is currently executed against canonical, Codex, Cursor, and Kiro paths in `Makefile`; runtime files are also compared with `cmp`. That duplicates core behavior testing and should become one `test-core` run plus injected target-specific checks. + +Missing coverage for the target design includes overlay schema/path containment/collisions, deterministic common-plus-overlay assembly, source/ref resolution, receipt/provenance, journal recovery, lifecycle rollback, settings ownership and user drift, structured capability records, native evidence freshness, and a final repository-topology negative test proving that generated trees and Claude support are gone. + +Existing tests are valuable models for transactional safety: they snapshot files, modes, symlinks, existence, directory topology, and temporary artifacts, and inject failures before and after commit actions. The new installer should extend these exact assertions rather than only checking exit codes. + +Native host evidence is uneven. Codex has authenticated runtime coverage for a narrow continuation scenario. Claude, Cursor, and Kiro continuation scripts can return `77`/unavailable. A `77` outcome must be surfaced as unavailable, never pass. + +Suggested replacement test layers: + +1. `test-core`: portable state/gate/continuation suite once. +2. `test-overlay-contract HOST`: schema, inventory, bindings, vocabulary, and native syntax. +3. `test-materializer HOST`: deterministic assembly, semantic golden, hashes, and installed canary. +4. `test-install HOST`: fresh/update/uninstall/rollback/settings ownership with failure injection. +5. `test-native-smoke HOST` / `test-host-e2e HOST`: only when runtime/auth exists, with explicit evidence status. +6. `test-repository-topology`: no generated trees, legacy builders, Claude support, or foreign vocabulary. + +## 9. Migration and Documentation Impact + +The migration must rewrite Makefile targets, CI workflows, release orchestration, README and host support docs, `.maister/docs/project/{vision,architecture,tech-stack,roadmap}.md`, and the build-pipeline standard. It must also update support matrices, install instructions, capability declarations, and test references. + +After shadow parity, the likely deletion boundary includes `plugins/maister-{cursor,kiro,codex}`, old build/generator scripts, generated drift jobs, the canonical Claude manifest and `CLAUDE.md` assets, Claude marketplace entries, the Claude continuation stub, and stale Claude vocabulary. No placeholder `hosts/claude` compatibility tree should remain under the minimal-implementation standard. + +## 10. Risk Assessment + +Risk is **high**. The change touches source ownership and public installation behavior, and a successful file layout can still conceal broken gate, delegation, hook, or continuation semantics. The implementation plan must therefore sequence source extraction, explicit overlays, installer transaction boundaries, shadow parity, test matrix migration, documentation/CI updates, and final deletion with clear rollback points. + +The research handoff is binding context for this analysis and is copied under `analysis/research-context/`. Its accepted decisions are consistent with the codebase evidence: minimal typed primitives, repository-owned Codex/Cursor/Kiro overlays, transactional installer, capability-sensitive compatibility, Claude removal, receipt-backed settings ownership, and core/per-host evidence separation. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/gap-analysis.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/gap-analysis.md new file mode 100644 index 00000000..224f9228 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/gap-analysis.md @@ -0,0 +1,220 @@ +# Gap Analysis: Implement platform-independent Maister distribution + +## TL;DR + +The repository still has a Claude-oriented canonical tree, three rewrite-heavy builders, three committed generated trees, and three unrelated installation paths; the requested target-aware distribution architecture is not implemented. +The five orchestrator-framework ESM modules are byte-identical across source and current projections, providing a concrete common-runtime seam, but generic prose and host behavior are still coupled through global rewrites. +The largest missing capabilities are an explicit common/host overlay contract, a shared transactional installer with receipt-backed ownership, and a core-once/per-host evidence test model. +Risk and effort are high because installation safety, semantic parity, host support policy, CI/release orchestration, Claude removal, and project documentation must change together. + +## Key Decisions + +- Use the five byte-identical modules under `plugins/maister/skills/orchestrator-framework/bin/` as the initial portable-runtime boundary; the repository inventory and SHA-256 comparison show the same files in the source, Codex, Cursor, and Kiro projections. +- Keep documentation-as-code and introduce only minimal typed semantic primitives for control flow, safety, persistence, delegation, continuation, and capability claims; ordinary search/read/test tool choice remains host-owned. This is supported by the accepted research decision and by the current builders' concentrated semantic rewrites. +- Replace the current generator topology with one repository-owned common layer, explicit `codex`, `cursor`, and `kiro-cli` overlays, and a custom copy/merge installer. The accepted research handoff excludes marketplace-driven installation and runtime prompt compilation from this task. +- Treat Claude Code and the committed generated trees as migration-only legacy: use them as a shadow comparison oracle, then remove Claude support and legacy outputs before the implementation task closes, with no placeholder compatibility tree. +- Make installer ownership transactional: staging, path/schema validation, locks, journal, receipt, atomic commit, managed settings ownership, recovery, and byte-exact rollback are required invariants rather than optional hardening. +- Run the common behavior suite once and retain per-host tests for overlay contracts, deterministic assembly, installation lifecycle, and available native evidence; `unavailable` must remain an explicit evidence status and never pass. + +## Open Questions / Risks + +- Codex, Cursor, and Kiro discovery roots, native agent/hook contracts, settings formats, and capability fingerprints still need implementation-time contract confirmation; the current scripts encode assumptions but do not provide a shared versioned contract. +- Shared settings and shell configuration do not have filesystem-level multi-file atomicity. A journal, backups, conflict detection, recovery path, and byte/mode/topology assertions are required to prevent partial updates and user-data loss. +- A successful file layout will not prove gate, delegation, hook, or continuation parity. The current `sed`/`awk` transforms can silently change semantics while structural checks remain green. +- Task-scoped deletion of legacy removes the current rollback oracle before any post-release observation window exists. Shadow parity and failure-injection gates therefore need explicit exit criteria before deletion. +- Removing Claude is an accepted product decision but is a compatibility and communication change for any existing Claude users; README, support docs, capability records, release notes, and project docs currently still advertise Claude. + +## Summary + +- **Risk Level**: High +- **Estimated Effort**: High +- **Change Type**: Modificative architecture and distribution migration +- **Compatibility Requirements**: Strict at semantic, safety, persistence, and rollback boundaries; capability-sensitive provisional handling is allowed only for packaging-only differences. +- **Detected Characteristics**: modifies existing code, creates new entities, involves data operations; no reproducible defect and no UI-heavy surface. + +## Task Characteristics + +- Has reproducible defect: no +- Modifies existing code: yes +- Creates new entities: yes +- Involves data operations: yes — managed plugin trees, settings, shell configuration, receipts, journals, and rollback snapshots +- UI heavy: no + +## Evidence Base + +- The Phase 1 analysis identifies 136 files in `plugins/maister/`, 474 files across the three committed projections, and 80 files under `platforms/`. It also records builder sizes of approximately 582 lines for Cursor, 860 for Kiro, and 338 for Codex, plus the Kiro JSON generator. +- The portable seam is directly verifiable: the five files in `plugins/maister/skills/orchestrator-framework/bin/` exist, and `gate-evaluator.mjs` and `orchestrator-state-repository.mjs` have identical SHA-256 hashes in source, Codex, Cursor, and Kiro locations. +- No repository-level `common/`, `hosts/`, `installer/`, or `schemas/` directory exists. No shared installer receipt/journal schema, source resolver, overlay schema, or capability-evidence schema was found in the implementation tree. +- `platforms/cursor/build.sh:18-19` copies the canonical tree into a generated destination and `platforms/cursor/build.sh:50-107` applies host vocabulary, path, manifest, and file-removal rewrites. `platforms/kiro-cli/build.sh:94-160` rewrites gates and then continues with other semantic transforms; `platforms/codex-cli/build.sh:44-133` rewrites Markdown and creates platform-specific output. +- `platforms/cursor/smoke-install.sh:49-60` deletes the destination before copying. `platforms/kiro-cli/smoke-install.sh:105-120` clears the target and then rewrites paths, while `platforms/kiro-cli/smoke-install.sh:172-199` can mutate a shell rc and host settings. `platforms/codex-cli/smoke-install.sh:104-119` registers a marketplace, removes an existing selector, and mutates the installed tree for MCP. +- `Makefile:1-20` builds three committed variants; `Makefile:57-65` runs the phase-continuation contract against source plus three projections; `Makefile:47-55` and `tests/host-capability-matrix.test.sh:22-41` still require four host rows, including Claude. `.github/workflows/validate-generated-variants.yml:24-43` checks committed generated-tree drift. +- Existing safety tests are strong models for the missing lifecycle: `tests/phase-continue-contract.test.sh:73-110` and `.maister/docs/standards/testing/test-writing.md:12-18` assert byte-exact non-mutation/rollback, including directory and state effects. They do not yet cover an installer-managed tree, settings ownership, receipt recovery, or user drift. +- Current capability evidence is uneven and not target-shaped: `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml:1-14` has Claude, Cursor, Kiro, and Codex rows, while the native continuation scripts for Claude, Cursor, and Kiro can return `77`/unavailable. Codex has the only supported native continuation row. +- Documentation and standards still describe the old model: `README.md:5,23-32` leads with Claude marketplace installation; `docs/codex-support.md:3-32` and `docs/kiro-cli-support.md:157-200` describe generated outputs; `.maister/docs/project/architecture.md:9-31,52-58,77-99`, `vision.md:5,20,29-34`, `tech-stack.md:49-86`, and `standards/global/build-pipeline.md:3-19` encode generated variants and Claude support. + +## Impact Assessment + +### Maintainer journey + +Current: maintainers edit `plugins/maister/` or a host builder, run a host-specific build, inspect a generated tree, and commit source plus projection. Desired: maintainers edit the common layer or one explicit overlay, run deterministic core/overlay/install validation, and use legacy only for shadow parity during this task. The desired journey removes repeated behavior ownership but initially adds contract, receipt, recovery, and evidence artifacts. + +### Installer/operator journey + +Current: users choose a host-specific shell script, sometimes build first, and receive different destructive or marketplace-backed behavior. Desired: users choose `--target codex|cursor|kiro-cli` and a local or immutable GitHub source/ref; the installer stages, validates, probes compatibility, commits atomically, and reports receipt/evidence status. This is a positive reachability change, but there is currently no common entry point, status command, update policy, or migration path. + +### Host integration journey + +Current: host behavior is hidden in large global rewrite lists and generated output layout. Desired: every native asset and semantic binding is visible in the owning host overlay, with an allowlisted layout and capability record. This improves reviewability but makes incomplete overlay inventory and misclassified capabilities blocking issues. + +### Release and support journey + +Current: PR CI primarily rebuilds/checks committed variants, release runs `make build && make validate`, and support documentation names Claude plus generated trees. Desired: CI runs core once, parametrized overlay/materializer/installer checks for three hosts, and structured native evidence; release and docs must stop referring to Claude, legacy trees, and marketplace assumptions. + +## Gaps Identified + +### Missing Features + +1. **Neutral source ownership and host overlay contract** — `common/`, `hosts//overlay.yml`, primitive bindings, path allowlists, inventory, forbidden vocabulary, settings ownership, and capability fingerprints are absent. The existing `plugins/maister/` source is explicitly Claude-oriented (`plugins/maister/.claude-plugin/plugin.json` and `plugins/maister/CLAUDE.md`), so it cannot become the neutral layer by renaming alone. +2. **Shared target-aware installer** — There is no CLI or library that resolves a local checkout/GitHub ref to immutable source, selects an overlay, probes host facts, validates compatibility, assembles staging, and installs the result for all three hosts. +3. **Transactional installation lifecycle** — No shared lock/journal/receipt store, managed-tree ownership record, settings mutation schema, active receipt pointer, recovery routine, update command, or receipt-driven uninstall/rollback exists. +4. **Capability-sensitive compatibility and structured evidence** — The current four-row matrix exposes a host-level supported/unsupported projection. It does not record capability class, host version, fingerprint, scenario, evidence level, freshness, target, or receipt provenance. +5. **Core-once/per-host evidence test architecture** — The current Makefile executes the same phase runner contract against byte-identical source and projections, while the new overlay schema, deterministic assembly, path containment, collision, receipt, recovery, settings drift, and repository-topology tests do not exist. +6. **Final support topology and documentation migration** — Claude manifests/assets/vocabulary, generated projections, old builders, generated drift CI, support docs, README instructions, project docs, and build-pipeline standards all still encode the legacy model. + +### Incomplete Features + +- **Portable runtime** — The five runtime modules already provide state, gate, continuation, and safety behavior, but their maintained ownership is still under a Claude-oriented tree and they are duplicated into all generated projections rather than being installed from one common source. +- **Host adapters** — Codex, Cursor, and Kiro have explicit platform directories, but those directories mix native assets with large transformation programs. The adapters are not small overlays and have no common schema or binding-completeness check. +- **Installation** — Cursor and Kiro have local copy scripts and Codex has a marketplace-mediated install script. These cover narrow smoke scenarios, not a common install/update/uninstall/rollback lifecycle with ownership and recovery. +- **Validation and evidence** — Structural and host-specific tests exist, and common transactional tests provide reusable patterns, but native evidence is uneven and unavailable outcomes are projected through a host-level boolean rather than a per-capability record. +- **Documentation and governance** — The project docs and standards accurately describe the current generated-tree system but are incomplete for the accepted target architecture; leaving them unchanged would make the repository prescribe the wrong ownership and release workflow. + +### Behavioral Changes Needed + +- Change `make build`/`make validate` and CI from producing and diffing committed generated trees to validating one common source plus explicit host overlays, materialization canaries, installer lifecycle, and repository topology. +- Change installation from host-specific destructive copy/marketplace scripts to `maister install --target HOST` with local/GitHub immutable source resolution, staging, compatibility decisions, atomic commit, receipt publication, update, uninstall, rollback, and recovery. +- Change generic instructions from host-tool vocabulary rewritten after the fact to neutral intent plus typed bindings only where control flow, safety, persistence, delegation, or capability semantics differ. +- Change compatibility from a four-host boolean projection to per-host/per-capability records with semantic fail-closed behavior, packaging-only provisional status, explicit evidence freshness, and no global safety override. +- Change the final supported set to Codex, Cursor, and Kiro CLI; remove Claude support and legacy generated outputs before task completion after zero-unresolved-difference shadow parity. + +## User Journey Impact Assessment + +The task is not UI-heavy, so there are no pages, routes, forms, or visual navigation paths to score. The relevant journey is the maintainer/operator path: + +| Dimension | Current | After target implementation | Assessment | +|---|---|---|---| +| Reachability | Separate `build-*` and `smoke-install.sh` scripts, plus Codex marketplace registration | One explicit target-aware installer entry point | ⚠️ until the CLI and docs exist; ✅ after implementation | +| Discoverability | Host-specific instructions scattered across README and support docs | One install command with target, scope, source/ref, status, and receipt output | Current 3/10; target 8/10 if documented | +| Flow integration | Rebuild and copy are separate; update/uninstall behavior differs by host | Resolve → stage → validate → commit → receipt → verify/update/uninstall | ⚠️ requires lifecycle and recovery implementation | +| Multi-persona access | Maintainer, local developer, and end user follow different host paths | Same lifecycle supports local checkout/GitHub source and user/project scope | ⚠️ scope and ownership decisions remain open | + +## New Capability Analysis + +### Integration Points + +- Common source ownership for skills, references, assets, portable runtime, primitives, and neutral vocabulary. +- Three host overlays: `codex`, `cursor`, and `kiro-cli`, including native manifests, agents, commands/skills, hooks, MCP placement, settings, and host contract tests. +- Installer CLI and libraries for source resolution, overlay loading, compatibility, assembly, validation, transaction/recovery, settings merge, and receipt storage. +- Schemas for overlays, primitives, evidence, receipts, transaction journal entries, and managed settings mutations. +- Make targets, CI workflows, release packaging, support matrices, README, host support docs, project docs, and build/test standards. +- Existing runtime, reconciliation, repository, and test fixtures as implementation patterns: `orchestrator-state-schema.mjs`, `orchestrator-state-repository.mjs`, `reconcile-advisor-config.sh`, and the byte-exact transactional tests. + +### Patterns to Follow + +- Preserve exact allowlists, type validation, legal transitions, canonical serialization, locks, CAS/revision checks, symlink rejection, fsync, atomic rename, and cleanup patterns from the orchestrator state repository. +- Reuse candidate staging, same-directory rename, mode/ownership preservation, and rollback diagnostics from Advisor configuration reconciliation. +- Extend the existing snapshot and injected-failure assertions to cover bytes, modes, symlinks, existence, directory topology, temporary artifacts, settings keys, journal state, and active receipt state. +- Treat `orchestrator-state.yml` as workflow truth and keep installation receipts separate; do not overload workflow state with installation lifecycle. + +### Architectural Impact + +High. The change introduces a new deep boundary between portable behavior, explicit host contracts, and a transaction manager, while replacing build ownership, public installation behavior, test topology, supported-host policy, release orchestration, and documentation. + +## Data Lifecycle Analysis + +### Entity: Managed Maister installation state + +This task operates on filesystem/configuration state rather than application records. Because `ui_heavy` is false, the CLI/script path is the user-access layer in the table; there is no separate UI component. + +| Operation | Backend / installer evidence | CLI access | User access/status | +|---|---|---|---| +| CREATE | Cursor copies a generated tree after deleting its destination (`platforms/cursor/smoke-install.sh:49-60`); Kiro clears and copies (`platforms/kiro-cli/smoke-install.sh:105-120`); Codex resolves a marketplace-installed tree (`platforms/codex-cli/smoke-install.sh:104-114`) | Host-specific scripts only; no common `install --target` | Direct script invocation documented; no receipt or durable ownership | ⚠️ Partial; creation exists but is destructive/non-audited | +| READ | Codex can query `.installedPath`; Cursor/Kiro retain only caller-provided destination knowledge; no shared receipt/status/verify reader | Console output and ad hoc filesystem inspection | No common status, evidence, or ownership view | ❌ Missing for the requested lifecycle | +| UPDATE | Rebuild/re-copy behavior is embedded in host scripts; no receipt-based plan or integrity/drift check | Re-run a host-specific build/install script | No common update command or rollback target | ❌ Missing | +| DELETE | Kiro removes the entire profile (`platforms/kiro-cli/smoke-uninstall.sh:35-42`); Cursor and Codex have no shared receipt-driven uninstall | Kiro-only direct script | No ownership-aware conflict handling or cross-host path | ❌ Incomplete | + +**Completeness**: 25% for the requested shared lifecycle. Current scripts partially create installations and Kiro can delete an isolated profile, but no CRUD operation is complete against the common installer/receipt/ownership contract. + +**Orphaned Operations**: + +- CREATE without durable READ: an installed tree has no common receipt, managed inventory, source commit, or compatibility evidence. +- CREATE/UPDATE without safe recovery: destination deletion and post-copy path/config rewrites can leave partial state. +- DELETE without ownership: whole-profile removal is not based on a receipt and cannot distinguish Maister-owned files from user drift in a shared destination. +- Settings mutation without lifecycle symmetry: Kiro can change shell rc/default-agent state, but there is no shared backup, managed-key declaration, uninstall restoration, or drift report. + +**Missing Touchpoints**: user versus project scope; destination containment; shared settings and shell rc; MCP opt-in; active receipt and prior receipt; update integrity; uninstall conflicts; journal recovery; JSON status output; source/ref provenance; native capability evidence. + +## Issues Requiring Decisions + +### Critical (Must Decide Before Proceeding) + +1. **Host contract closure for Codex, Cursor, and Kiro CLI**: The accepted target set is known, but the exact discovery roots, native asset inventory, settings destinations, and semantic bindings are not yet represented in a versioned overlay contract. + - Options, in order: + 1. **Contract-first overlay v1** — freeze current native layouts/assets into explicit overlays, validate E1/E2/E4 for every host, and run E5/E6 when a real runtime is available (Recommended). + 2. **Host-doc-first overlay** — define new native layouts from current host contracts and use legacy outputs only as semantic comparison fixtures. + 3. **Runtime-gated support** — do not label a host supported until its native discovery and critical scenario evidence are available. + - Recommendation: **Contract-first overlay v1**, because it preserves the accepted three-host scope while making current assumptions reviewable and testable before legacy deletion. + - Rationale: `platforms/*/build.sh` and support docs contain host-specific assumptions, but no shared schema proves inventory or discovery compatibility. + +2. **Settings and shell-configuration ownership**: The installer must decide which mutations are Maister-owned and which files are shared with the user; current Kiro behavior mutates destination files and can append to shell rc. + - Options, in order: + 1. **Hybrid ownership contract** — use `whole_file` for dedicated Maister files and `managed_keys` for unavoidable shared files, each with journal, backup, drift detection, and exact rollback (Recommended). + 2. **Dedicated files only** — avoid all shared-file mutation and require manual host settings where a dedicated path is unavailable. + 3. **Shared managed-key merge everywhere** — support all host settings through allowlisted parse/mutate/serialize operations, accepting formatter and recovery complexity. + - Recommendation: **Hybrid ownership contract**, with dedicated files preferred and shared merges narrowly allowlisted. + - Rationale: it satisfies the accepted transactional ownership decision while minimizing exposure to user formatting and concurrent configuration changes. + +### Important (Should Decide) + +1. **Minimum release evidence for hosts without native runtime**: Current Cursor and Kiro continuation probes return `77`/unavailable, while only Codex has a supported native continuation row. + - Options, in order: + 1. **Require E1–E4 and shared-core E3; record E5/E6 as unavailable when the runtime is absent, never as pass (Recommended/default).** + 2. Require E5/E6 before any host can be labeled supported. + 3. Keep the host in the distribution but label it unsupported/provisional until native evidence is fresh. + - Default: **Option 1**, consistent with the accepted evidence-boundary decision and the requirement that unavailable remain explicit. + - Rationale: it keeps static, materialization, and transactional assurance useful without making missing external runtime look green. + +2. **Evidence freshness window**: The accepted compatibility policy requires versioned capability records, but the repository has no expiry or re-probe policy. + - Options, in order: + 1. **Per-capability expiry with host/version/scenario/timestamp renewal (Recommended/default).** + 2. Release-bound evidence that expires only when Maister or the host contract version changes. + 3. No expiry; rely on the recorded host version and manual review. + - Default: **Option 1**. + - Rationale: host contracts and external binaries change independently; freshness must be visible rather than inferred from a global boolean. + +3. **Documentation and release migration boundary**: README, support docs, CI, project docs, and `build-pipeline.md` currently prescribe generated trees and Claude/marketplace workflows. + - Options, in order: + 1. **Update all affected documentation, standards, Make/CI/release paths, and support matrices in this task (Recommended/default).** + 2. Implement the runtime and installer first, then maintain a follow-up documentation migration. + 3. Keep legacy instructions as a compatibility guide after the implementation. + - Default: **Option 1**. + - Rationale: the accepted Definition of Done requires repository topology and documentation to describe the new architecture; stale instructions would create an operationally broken release path. + +## Recommendations + +- Establish an M0 baseline manifest from the existing source, generated projections, host assets, hooks, permissions, references, and current test outcomes before changing ownership. +- Extract only the proven portable core first, remove foreign vocabulary from generic content, and register semantic primitives only for repeated host divergence or a safety/persistence invariant. Do not introduce a full workflow DSL or carry forward global rewrite lists. +- Define and validate overlay schemas before implementing materialization. Enforce target-root containment, collision rules, required inventory, forbidden vocabulary, binding completeness, executable modes, deterministic hashes, and native syntax. +- Implement the shared installer as an assembler and transaction manager: resolve local/GitHub source to an immutable commit, probe compatibility, lock, stage, validate, snapshot, commit, write receipt, publish active receipt, recover pending journals, and preserve user drift on update/uninstall. +- Build the test matrix around `test-core`, `test-overlay HOST`, `test-materializer HOST`, `test-install HOST`, structured native evidence, and a final repository-topology negative test. Extend existing byte-exact failure-injection tests instead of relying on exit codes. +- Run shadow parity against legacy for Codex, Cursor, and Kiro, classify every difference, and require zero unresolved semantic/inventory/reference/hook/permission differences before deleting generated trees and old builders. +- Update README, host support docs, Makefile, CI, release, capability records, project docs, and standards as one migration. Explicitly communicate the accepted Claude removal and the evidence status of each remaining host. + +## Risk Assessment + +- **Complexity Risk: High** — source ownership, overlay schemas, installer lifecycle, settings merge, compatibility policy, test architecture, CI, release, and documentation form one coupled migration. A partial implementation would leave two competing models. +- **Integration Risk: High** — Codex, Cursor, and Kiro differ in manifests, discovery, commands/skills, agents, hooks, settings, MCP placement, and continuation behavior. Current scripts encode these differences but do not expose a shared contract. +- **Regression Risk: High** — global rewrites currently implement gates, delegation, progress, path resolution, and safety vocabulary. Layout parity or textual diff success cannot establish semantic parity. +- **Data/Safety Risk: Critical** — Cursor/Kiro deletion-before-copy and Kiro/Codex post-install mutations can corrupt or remove managed state; shared settings and shell rc require ownership, journal, recovery, and byte-exact tests. +- **Evidence/Governance Risk: High** — native runtime availability is uneven, current capability rows include a target being removed, and stale docs/CI can publish or instruct users toward unsupported legacy paths. `unavailable` must never be converted to pass. + diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/requirements.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/requirements.md new file mode 100644 index 00000000..f689fff2 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/requirements.md @@ -0,0 +1,123 @@ +# Requirements: Platform-independent Maister distribution + +## TL;DR + +Maister must move from a Claude-oriented source plus three rewrite-heavy generated trees to one portable common source with explicit Codex, Cursor, and Kiro CLI overlays. A shared installer must select the host at installation time, resolve local or immutable GitHub sources, validate compatibility, and commit changes transactionally with receipt-backed ownership and exact rollback. Common behavior is tested once; host overlays, materialization, installation, and available native evidence retain targeted coverage. Claude support and committed generated projections are migration-only and must be removed before completion. + +## Initial description + +Przeanalizować, jak zastąpić generowanie i osobne testowanie wariantów dla wielu hostów jednym rozwiązaniem niezależnym od narzędzia, z rozróżnieniem platformy możliwym na etapie instalacji. + +## Confirmed scope and Q&A + +### Scope + +- **Question**: Is the implementation scope Codex, Cursor, and Kiro CLI only, with Claude and committed generated trees removed before completion? +- **Answer**: Confirm assumptions. +- **Requirement**: The completed supported target set is Codex, Cursor, and Kiro CLI. Claude assets, manifests, vocabulary, support rows, marketplace paths, and generated projections are migration-only and must be removed before completion. + +### Host contract closure + +- **Question**: Which host-contract closure policy should the implementation adopt? +- **Answer**: Contract-first overlay v1 with E1/E2/E4 for every host and E5/E6 when runtime exists. +- **Requirement**: Versioned overlays must explicitly encode discovery roots, native inventories, settings destinations, semantic bindings, and required evidence. E1/E2/E4 are required for every host; E5/E6 are collected when a runtime is available. + +### Settings ownership + +- **Question**: Which settings and shell-configuration ownership contract should the implementation adopt? +- **Answer**: Hybrid `whole_file` and `managed_keys` ownership with journal, backup, drift detection, and exact rollback. +- **Requirement**: Dedicated Maister files use whole-file ownership. Unavoidable shared files use narrowly allowlisted managed keys. Both modes require ownership records, backup/journal support, drift detection, recovery, and byte-exact rollback. + +### Native evidence policy + +- **Question**: Which minimum release-evidence policy should apply to hosts without native runtime? +- **Answer**: Require E1-E4 and shared-core E3; record E5/E6 as unavailable, never pass. +- **Requirement**: `unavailable` is a first-class evidence status and must never be converted to `passed`. Packaging/static evidence can support a host while semantic native evidence remains explicitly unavailable. + +### Evidence freshness + +- **Question**: Which evidence freshness policy should the implementation adopt? +- **Answer**: Per-capability expiry with host, version, scenario, and timestamp renewal. +- **Requirement**: Capability evidence records include host identity, host version, scenario, timestamp, capability class, result, provenance, and per-capability expiry/re-probe metadata. + +### Documentation and release boundary + +- **Question**: Which documentation and release migration boundary should the implementation adopt? +- **Answer**: Update all affected documentation, standards, Make/CI/release paths, and support matrices in this task. +- **Requirement**: No supported release path may continue to prescribe Claude, marketplace installation, or committed generated-tree workflows after completion. + +### Routing + +- **Question**: Continue to Phase 5: Technical Approach, Requirements & Specification? +- **Answer**: Continue to Phase 5. +- **Requirement**: TDD Red and UI mockup phases are skipped because the task is not defect-driven or UI-heavy. Requirements and specification proceed directly. + +## User journey and personas + +- **Maintainer**: edits common behavior or one host overlay, runs deterministic core/overlay/materializer/install validation, and uses legacy outputs only as a shadow comparison oracle during migration. +- **Installer operator**: chooses `--target codex|cursor|kiro-cli`, selects user/project scope, and supplies a local checkout or immutable GitHub source/ref. The installer reports compatibility, receipt, evidence, and recovery state. +- **Host integrator**: reviews native assets, semantic bindings, settings ownership, capability evidence, and overlay completeness for one host without reading a global rewrite program. +- **Release/support owner**: publishes one portable source, validates three host overlays, maintains capability evidence, and keeps README, CI, release, and support matrices aligned. + +## Functional requirements + +1. Provide one repository-owned portable common layer for behavior/runtime content that is independent of host vocabulary. +2. Provide explicit versioned overlays for Codex, Cursor, and Kiro CLI with allowlisted native assets, paths, discovery roots, settings destinations, bindings, and forbidden vocabulary. +3. Preserve the proven portable orchestrator runtime seam, including state, gate, continuation, and safety behavior, without maintaining separate generated copies. +4. Introduce only minimal typed semantic primitives for control flow, safety, persistence, delegation, continuation, and capability claims where host behavior changes semantics. +5. Provide deterministic source/ref resolution for local checkouts and immutable GitHub references, with provenance recorded for each installation. +6. Provide a shared target-aware installer that selects an overlay at install time and supports install, update, status/verify, uninstall, rollback, and recovery operations. +7. Stage and validate assembled output before mutation, enforcing target-root containment, collision rules, schema validity, inventory completeness, syntax/mode checks, deterministic hashes, and symlink safety. +8. Use locks, journal entries, backups, atomic commit, cleanup, and recovery to prevent partial installations and restore the exact previous filesystem/configuration state on failure. +9. Record a receipt containing source/ref provenance, target, overlay version, installed inventory, settings ownership, capability evidence, hashes, and rollback metadata. +10. Support hybrid settings ownership: dedicated whole-file paths plus narrowly allowlisted managed keys for unavoidable shared settings/shell files. +11. Detect user drift and concurrent changes, preserve unmanaged content, and refuse unsafe destructive updates or uninstall operations. +12. Represent compatibility per capability and host rather than as one host-level boolean; semantic/safety/persistence boundaries fail closed, while packaging-only differences may be provisional. +13. Run common-core behavior tests once and retain per-host overlay, materialization, installation lifecycle, settings ownership, topology, and available native evidence tests. +14. Require E1/E2/E4 for each supported host, use shared-core E3, and record E5/E6 as unavailable when native runtime is absent rather than passing them. +15. Expire evidence per capability using host/version/scenario/timestamp metadata and support explicit renewal/re-probe. +16. Use legacy generated trees and old builders only as a shadow parity oracle; classify every difference and require zero unresolved semantic, inventory, reference, hook, permission, or topology differences before deletion. +17. Remove Claude manifests/assets/vocabulary, committed generated projections, old builder/rewrite CI, Claude capability rows, marketplace installation paths, and stale support instructions before task completion. +18. Update README, host support docs, project docs, standards, Make targets, CI, release packaging, capability matrices, and migration notes to describe the new architecture and supported targets. + +## Reusability opportunities + +- Reuse the byte-identical modules under `plugins/maister/skills/orchestrator-framework/bin/` as the initial common runtime boundary. +- Reuse schema validation, legal transitions, canonical serialization, locks, CAS/revision checks, symlink rejection, atomic rename, and cleanup patterns from `orchestrator-state-repository.mjs`. +- Reuse candidate staging, same-directory rename, mode preservation, rollback diagnostics, and failure injection from `plugins/maister/skills/init/bin/reconcile-advisor-config.sh` and its tests. +- Reuse byte-exact snapshot assertions from `tests/phase-continue-contract.test.sh`, repository tests, advisor lifecycle tests, and Kiro reproducible-build tests. +- Reuse host capability vocabulary and explicit `passed`/`failed`/`unavailable` semantics from `host-capabilities.yml`, the Makefile capability target, and `tests/host-capability-matrix.test.sh`, while reshaping them into per-capability records. +- Preserve existing host-native assets only after inventory and semantics are represented in explicit overlays; the rewrite-heavy builders are comparison fixtures, not new ownership boundaries. + +## Visual assets + +No visual assets or UI changes are in scope. The operator-facing interface is a CLI/installer lifecycle; no mockups are required. + +## Scope boundaries + +### In scope + +- Portable common source and runtime ownership. +- Codex, Cursor, and Kiro CLI overlays. +- Target-aware source resolution, assembly/materialization, validation, installation, update, status/verify, uninstall, rollback, and recovery. +- Receipt, journal, settings ownership, capability evidence, and schema contracts. +- Core-once plus per-host test topology and shadow parity. +- Deletion of Claude support and committed generated legacy infrastructure. +- Documentation, standards, CI, release, and support-matrix migration. + +### Out of scope + +- Re-adding Claude support; that requires a separate host-integration task. +- A full workflow DSL or a general-purpose prompt compiler. +- Native runtime evidence that cannot be executed in the current environment; such results remain unavailable. +- New GUI surfaces or visual design work. +- Unrelated feature redesigns outside distribution, portability, installation safety, and host integration. + +## Technical considerations and risks + +- Semantic parity must be proven by scenarios and binding completeness, not only text/layout diffs. +- Shared settings lack filesystem-level multi-file atomicity; journal, backups, conflict detection, and recovery are mandatory. +- Target-root containment and symlink rejection are required to prevent overlay path escape. +- Native host versions and external binaries change independently; evidence freshness must be explicit. +- Legacy deletion must follow shadow parity and failure-injection evidence so the migration oracle is not lost prematurely. +- The accepted compatibility policy is strict for semantics, safety, persistence, and rollback; provisional status is limited to packaging-only differences. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/decision-log.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/decision-log.md new file mode 100644 index 00000000..1d1bcbcd --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/decision-log.md @@ -0,0 +1,311 @@ +# Decision log: platformowo niezależny Maister + +## TL;DR +Przyjęto siedem decyzji prowadzących do jednego portable core, trzech jawnych host overlays i własnego transakcyjnego installera. +Zwykły dobór narzędzi pozostaje po stronie harnessu; formalizujemy tylko operacje wpływające na control flow, safety, persistence i capability claims. +Legacy generated trees oraz Claude Code zostaną usunięte przed zamknięciem zadania, po użyciu ich jako tymczasowego oracle migracji. +Każda decyzja ma status Accepted i wynika z konwergencji 1A/2D/3D/4C/5D albo z koniecznej konsekwencji transakcyjnego lifecycle. + +## Key Decisions +- ADR-001: minimalne semantic primitives, bez pełnego workflow DSL. +- ADR-002: jedna warstwa common, jawne repo-owned overlays i własny copy/merge installer. +- ADR-003: shadow comparison tylko w czasie implementacji; legacy znika przed Definition of Done. +- ADR-004: compatibility per capability — semantic fail-closed, packaging może być provisional. +- ADR-005: Claude Code zostaje usunięty; jego ewentualny powrót jest nowym zadaniem host integration. +- ADR-006: installer posiada zarządzane drzewa i jawne keys settings, używa journalu, receipt i byte-exact rollbacku. +- ADR-007: core testujemy raz, a E1/E2/E4 i dostępne E5/E6 pozostają per host oraz per scenario. + +## Open Questions / Risks +- Aktualne host contracts Codex/Cursor/Kiro muszą zostać ponownie potwierdzone podczas implementacji; ADR-y definiują politykę, nie zamrażają ich API. +- Granica primitive może puchnąć; każdy nowy binding wymaga dowodu powtarzalnej różnicy semantycznej albo ochrony safety/persistence. +- Multi-file settings transaction nie ma natywnej atomowości filesystemu; poprawność zależy od journalu, backupu i recovery tests. +- Task-scoped removal legacy nie zapewnia okresu obserwacji po release; parity i failure-injection gates muszą być kompletne przed deletion. +- E5/E6 zależą od dostępnego host runtime i auth; `unavailable` pozostaje jawną luką, nie sukcesem. + +## Status legend + +- **Accepted** — zatwierdzone przez użytkownika lub niezbędne do realizacji zatwierdzonego invariant. +- **Superseded** — zastąpione późniejszą decyzją; brak takich decyzji w tym logu. +- **Proposed** — wymaga decyzji; brak otwartych ADR-ów blokujących design. + +## ADR-001 — Minimalne semantic primitives zamiast pełnego IR + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 1A, wybrane przez użytkownika; doprecyzowanie: harness wybiera zwykłe narzędzia. + +### Context + +Canonical source jest obecnie powiązany z nazwami narzędzi i konstrukcjami jednego hosta, a adaptery wykonują setki transformacji tekstowych. Jednocześnie workflow jest w dużej części czytelną dokumentacją, której zamiana na pełny AST/DSL byłaby kosztowna i spekulatywna. Badanie oceniło minimalne typed primitives jako najlepszy stosunek separacji do kosztu ([canonical boundary](../analysis/findings/canonical-core-boundary.md), [alternatives](solution-exploration.md#2-obszar-decyzyjny-1--głębokość-reprezentacji-kanonicznej--ir)). + +### Decision drivers + +- jedna kopia generic skills; +- brak globalnego regex rewrite; +- zachowanie documentation-as-code; +- swoboda harnessu w doborze zwykłych narzędzi; +- formalne gwarancje na safety/control-flow/persistence boundaries; +- minimal implementation. + +### Considered options + +1. **1A — minimalne typed primitives + host-aware contract**. +2. 1B — pełny neutralny workflow IR/DSL. +3. 1C — canonical Markdown + ulepszone regex/golden snapshots. + +### Outcome + +Przyjmujemy 1A. Generic skills opisują intencję i są kopiowane bez zmian. `grep`, `rg`, read/search/explore i inne zwykłe strategie pozostają decyzją harnessu. Jawne primitives istnieją dla `present_user_gate`, wymaganej delegacji roli, safety hooks, persistence-before-continue, phase continuation i innych operacji, których błędna realizacja zmienia semantykę lub bezpieczeństwo. + +### Consequences + +- nie powstaje pełny DSL ani prompt compiler; +- potrzebny jest mały `primitives.yml` oraz binding completeness contract; +- generic vocabulary test blokuje nazwy host-specific tools; +- każdy nowy primitive wymaga uzasadnienia powtarzalną różnicą lub safety invariant; +- część neutralnej prozy nadal jest walidowana scenariuszowo, nie statycznie. + +## ADR-002 — Repo-owned host overlays i custom installer + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 2D, wybrane po odrzuceniu marketplace-oriented wariantów. + +### Context + +Użytkownik instaluje Maister z lokalnego repo albo GitHuba i chce pełnej kontroli nad installerem. Generic skills są identyczne, natomiast agents, commands, hooks, manifests, settings i wymagane semantic bindings są natywnie różne. Generowanie tych assetów w czasie instalacji przeniosłoby obecną złożoność adapterów do środowiska użytkownika ([host contracts](../analysis/findings/host-contracts-installation.md)). + +### Decision drivers + +- jawny diff host-specific behavior w repo; +- prosta, deterministyczna instalacja; +- brak marketplace i prebuilt release matrix; +- brak runtime generation z prozy; +- jedno utrzymywane common source; +- łatwe dodanie następnego hosta przez nowy overlay. + +### Considered options + +1. **2D — common + explicit host overlays + custom copy/merge installer**. +2. Installer generuje host-specific assets z descriptors/templates. +3. Repo przechowuje kompletne prebuilt trees z duplikowanymi skills. +4. CI/marketplace hybrid z materializerem — odrzucone jako poza zakresem. + +### Outcome + +Repo zawiera `common/` oraz `hosts/codex`, `hosts/cursor`, `hosts/kiro-cli`. Installer wybiera target, kopiuje common byte-for-byte, dokłada repo-owned overlay, wykonuje tylko jawny path/config merge, waliduje i transakcyjnie instaluje wynik. GitHub source jest resolve'owany do immutable commit SHA. + +### Consequences + +- każda różnica hosta jest widoczna w code review; +- overlay contract i test harness są obowiązkowe; +- podobne pliki hostów mogą pozostać małą, świadomą duplikacją; +- installer jest assemblerem i transaction managerem, nie compilerem workflow; +- dokumentacja dystrybucji nie zawiera marketplace assumptions. + +## ADR-003 — Legacy tylko jako oracle w zadaniu implementacyjnym + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 3D, wybrane przez użytkownika. + +### Context + +Commitowane target trees i obecne adaptery są wartościowym punktem porównania podczas migracji, ale stanowią główne źródło duplikacji. Długie utrzymywanie dual path przeczyłoby celowi zadania. Użytkownik zaakceptował użycie legacy w trakcie implementacji, pod warunkiem jego usunięcia przed zakończeniem zadania. + +### Decision drivers + +- wykrycie brakujących assets i semantic drift; +- finalny brak generated trees; +- brak dwóch ścieżek przez kolejne release; +- jednoznaczna Definition of Done; +- możliwość porównania hooks, permissions, inventory i references. + +### Considered options + +1. Usunąć legacy natychmiast po pierwszym działającym installerze. +2. Utrzymywać je przez dwa stabilne release. +3. Pozostawić jako stałe snapshots. +4. **3D — shadow w czasie zadania, obowiązkowe deletion przed jego zamknięciem**. + +### Outcome + +Legacy generated trees i build adapters są migration-only oracle. Po uzyskaniu zero niewyjaśnionych różnic oraz zielonych E1–E4 zostają usunięte w tym samym zadaniu. Końcowe CI i docs nie mogą się do nich odwoływać. + +### Consequences + +- branch implementacyjny czasowo zawiera dual path; +- końcowa bramka parity musi być silniejsza niż zwykły textual diff; +- rollback po merge opiera się na Git history/receipts, nie aktywnym legacy builderze; +- repository inventory test powinien blokować ponowne pojawienie się generated trees. + +## ADR-004 — Capability-sensitive compatibility + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 4C, wybrane przez użytkownika. + +### Context + +Numer wersji hosta nie mówi, czy zmienił się wyłącznie layout, czy semantyka gate/delegation/hooks. Globalne „fail” blokowałoby kompatybilne releases, a globalny warning mógłby przepuścić safety regression. Obecny boolean capability ukrywa host version, scenario, freshness i evidence level ([assurance findings](../analysis/findings/test-assurance-runtime-gap.md)). + +### Decision drivers + +- fail-closed safety boundaries; +- brak niepotrzebnego blokowania packaging changes; +- audytowalne claims; +- brak globalnego unsafe override; +- możliwość aktualizacji evidence bez zmiany common core. + +### Considered options + +1. Zawsze fail-closed poza zakresem wersji. +2. Zawsze warning i best-effort. +3. **4C — semantic fail-closed, packaging provisional**. + +### Outcome + +Overlay klasyfikuje każdą capability jako `semantic` albo `packaging`. Niepotwierdzony semantic fingerprint/binding blokuje instalację. Packaging-only może przejść po walidacji E1/E2/E4 ze statusem `provisional`. Evidence jest per host/capability/version/scenario/timestamp/target. + +### Consequences + +- klasyfikacja capability jest częścią review i schema; +- błędna klasyfikacja jest nowym istotnym ryzykiem; +- UI/CLI musi jasno odróżniać `supported`, `provisional`, `unavailable`, `failed`; +- nie ma globalnego `--force` dla semantic/safety invariants. + +## ADR-005 — Usunięcie Claude Code + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 5D, wybrane przez użytkownika. + +### Context + +Claude Code nie ma dostępnego runtime ani obecnie potwierdzonej potrzeby. Zachowanie targetu wymagałoby utrzymywania overlayu, testów i wyjątków przy niższym assurance, a obecne canonical source jest historycznie Claude-native. Zamiast raportować trwałe E5/E6 `unavailable`, użytkownik zdecydował usunąć host i wrócić do niego dopiero przy realnej potrzebie. + +### Decision drivers + +- redukcja zakresu i nietestowalnych claims; +- rzeczywiście neutralny common core; +- tylko hosty z aktywną potrzebą; +- brak projektowania pod hipotetyczną przyszłość; +- jasna lista supportu. + +### Considered options + +1. Blokować completion bez Claude E5/E6. +2. Zachować Claude z E1–E4 i jawnym E5/E6 unavailable. +3. Zewnętrzna/community certification. +4. **5D — usunąć Claude, dodać później jako nowy host**. + +### Outcome + +Claude znika ze supported targets, installera, overlays, canonical manifests, agents, commands, hooks, settings, tests, capability matrix i dokumentacji. Claude-native vocabulary zostaje usunięte z generic layer. Ponowne dodanie wymaga osobnego zadania z aktualnym Host Overlay Contract i dostępnością wymaganych testów. + +### Consequences + +- support matrix obejmuje Codex, Cursor i Kiro CLI; +- obecni użytkownicy Claude, jeśli istnieją, tracą wsparcie i wymagają komunikacji migracyjnej; +- nie powstaje placeholder `hosts/claude` ani future stub; +- docs project vision/architecture/roadmap wymagają aktualizacji. + +## ADR-006 — Transakcyjna własność konfiguracji + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło:** konsekwencja zatwierdzonego custom installera i istniejącego standardu byte-exact rollback. + +### Context + +Host settings często współdzielą plik z konfiguracją użytkownika. Obecne instalatory Cursor/Kiro mogą najpierw usuwać destination, co pozostawia partial state po przerwaniu; standard projektu wymaga dowodu byte-exact non-mutation lub rollbacku dla transactional writers ([install evidence](../analysis/findings/test-assurance-runtime-gap.md), `.maister/docs/standards/testing/test-writing.md`). + +### Decision drivers + +- brak utraty danych użytkownika; +- update/uninstall tylko w granicach własności Maister; +- crash recovery; +- deterministyczny audit; +- wspólna implementacja lifecycle. + +### Considered options + +1. Nadpisywanie całych settings files. +2. Best-effort merge bez receipt. +3. Dedykowane pliki tam, gdzie host pozwala, oraz managed-key merge z journalem dla shared config. +4. Pozostawienie settings do ręcznej konfiguracji. + +### Outcome + +Installer deklaruje `whole_file` albo `managed_keys` per mutation. Przed commit zapisuje backup bytes/modes/topology, używa temp+atomic rename, transaction journalu i immutable receipt. Active receipt zmienia się dopiero po pełnym sukcesie. Uninstall usuwa tylko nadal zarządzane wartości; user drift pozostaje nietknięty. + +### Consequences + +- transaction/receipt schemas stają się krytycznym interfejsem; +- recovery musi uruchamiać się przed nową operacją; +- failure-injection tests obejmują każdy punkt commit; +- serializacja config może zmienić formatting, więc preferowane są dedicated files; shared merge wymaga świadomego formatter contract. + +## ADR-007 — Granica testów i dowodu + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło:** research evidence oraz zatwierdzone rozdzielenie common/overlay. + +### Context + +Portable runtime ma wykonywalne E3, ale pełne suite'y są powtarzane dla byte-identical target copies. Jednocześnie host tests mają nierówne znaczenie: część to strukturalne checks, część realnie uruchamia CLI, a `exit 77` sygnalizuje brak dowodu. Nazwa testu nie może zastępować jawnego evidence level ([test assurance findings](../analysis/findings/test-assurance-runtime-gap.md)). + +### Decision drivers + +- szybki PR feedback bez czterokrotnego core; +- host-specific assurance tam, gdzie host rzeczywiście się różni; +- brak fałszywie zielonych skipów; +- claims powiązane z wersją i scenariuszem; +- możliwość dodania kolejnego hosta bez kopiowania całej suite. + +### Considered options + +1. Pełna suite dla każdego złożonego tree. +2. Tylko common core tests. +3. **Pełny E3 raz + parametryczne E1/E2/E4 per host + native E5/E6 per scenario**. + +### Outcome + +CI uruchamia pełne `test-core` raz. Dla Codex/Cursor/Kiro uruchamia wspólny overlay harness, deterministic assembly canary i pełny transactional lifecycle. Native host smoke/E2E są oddzielne i zapisują structured evidence. `77` oznacza `unavailable` i nigdy pass. + +### Consequences + +- krótszy, czytelniejszy PR quality gate; +- per-host tests nie mogą ponownie duplikować core edge cases; +- evidence schema i freshness validation są częścią release governance; +- host support jest per capability/scenario, nie jednym booleanem. + +## Decision dependency map + +```text +ADR-001 minimal primitives + | + +------> ADR-002 common + overlays + installer + | | + | +--> ADR-006 transactional ownership + | + +--> ADR-003 legacy removal + +--> ADR-004 capability compatibility + +--> ADR-007 evidence boundary + +ADR-005 Claude removal --------> narrows ADR-002/003/007 to 3 hosts +``` + +## Traceability matrix + +| Convergence choice | ADR | Design section | +|---|---|---| +| 1A | ADR-001 | High-level design §5 | +| 2D | ADR-002 | High-level design §3, §6–9 | +| 3D | ADR-003 | High-level design §12–13 | +| 4C | ADR-004 | High-level design §10 | +| 5D | ADR-005 | High-level design §12–13 | +| transactional installer invariant | ADR-006 | High-level design §7–9 | +| core once / host evidence | ADR-007 | High-level design §11 | + diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/high-level-design.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/high-level-design.md new file mode 100644 index 00000000..46fafd74 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/high-level-design.md @@ -0,0 +1,492 @@ +# High-level design: platformowo niezależny Maister + +## TL;DR +Maister przechodzi na architekturę **portable documentation core + repository-owned host overlays + transactional installer**. +Wspólne skille są kopiowane bez zmian, a Codex, Cursor i Kiro CLI przechowują jawne agents, commands, hooks, manifests, settings oraz bindings tylko dla operacji semantycznie istotnych. +Installer składa `common + hosts/` przez deterministyczne copy/merge, waliduje staging i zatwierdza instalację transakcyjnie z receipt oraz byte-exact rollbackiem. +Legacy generated trees i cały target Claude Code służą wyłącznie jako tymczasowy oracle migracji i muszą zniknąć przed zamknięciem zadania implementacyjnego. + +## Key Decisions +- Architektura: **portable documentation core with explicit host overlays**, nie pełny workflow DSL ani install-time compiler promptów. +- Harness sam wybiera zwykłe narzędzia wykonawcze; jawne bindings obejmują wyłącznie control flow, safety, persistence i capability-sensitive behavior. +- Jedna kopia generic skills/runtime jest instalowana bez transformacji, a host-native assets są utrzymywane wprost w `hosts/codex`, `hosts/cursor` i `hosts/kiro-cli`. +- Własny installer obsługuje lokalne repo i GitHub source, staging, validation, lock, receipt, atomic commit, update, uninstall i rollback. +- Nieznana wersja hosta blokuje niepotwierdzone capabilities semantyczne; packaging-only może otrzymać jawny status `provisional`. +- Legacy build adapters, committed generated trees i Claude Code zostają usunięte w tym samym zadaniu po shadow comparison i spełnieniu Definition of Done. + +## Open Questions / Risks +- Docelowe ścieżki discovery i format settings każdego hosta trzeba potwierdzić aktualnymi testami contract/runtime przed implementacją overlayu. +- Atomowa podmiana całego managed tree jest prosta; wieloplikowy merge do współdzielonych ustawień użytkownika wymaga journalu i byte-exact rollbacku. +- Neutralna proza może z czasem zacząć przemycać słownik jednego hosta; potrzebny jest forbidden-vocabulary contract oraz review wyjątków. +- Błędna klasyfikacja capability jako `packaging` zamiast `semantic` może przepuścić niezgodność; klasyfikacja musi być jawna i przeglądana. +- Usunięcie legacy w jednym zadaniu zwiększa wagę końcowej bramki parity, szczególnie dla hooks, agents i invocation semantics. + +## 1. Kontekst i cele + +Obecny system ma jedno Claude-oriented źródło, trzy adaptery tekstowe i trzy commitowane projekcje. Badanie wykazało około 610 plików projekcji, około 5,08 MB duplikowanych drzew i około 320 substytucji tekstowych, mimo że pięć kluczowych modułów runtime jest byte-identical w targetach ([canonical core evidence](../analysis/findings/canonical-core-boundary.md)). Testy potwierdzają też, że wspólna semantyka state/gate/continuation ma wykonywalny poziom E3, podczas gdy pełny runner contract jest niepotrzebnie powtarzany dla kopii ([assurance evidence](../analysis/findings/test-assurance-runtime-gap.md)). + +Projekt ma osiągnąć: + +1. jedno utrzymywane źródło generic skills i portable runtime; +2. jawne, małe różnice hostów bez globalnych transformacji prozy; +3. instalację z lokalnego checkoutu albo GitHuba pod pełną kontrolą projektu; +4. testowanie wspólnej semantyki raz i host contracts tylko tam, gdzie rzeczywiście się różnią; +5. brak nietestowalnego Claude Code oraz brak commitowanych generated trees po zakończeniu migracji. + +Poza zakresem są marketplace, jeden identyczny installed tree, pełny workflow IR/DSL, generowanie host assets z promptów oraz emulowanie brakujących capabilities przez niejawne rewrite'y. + +## 2. Styl architektury i granice + +**Styl:** modular monolith dystrybuowany jako repozytoryjny bundle, z portable documentation core, deklaratywnymi Host Overlay Contracts i transakcyjnym adapterem instalacyjnym. + +```text +Maintainer edits + | + v ++-------------------+ +-------------------------+ +| common/ | | hosts// | +| skills + runtime | | explicit native overlay | ++-------------------+ +-------------------------+ + \ / + \ / + v v + +-------------------+ + | custom installer | + | copy + merge only | + +-------------------+ + | + stage -> validate + | + atomic commit + v + host-native managed tree +``` + +Granica modułu jest celowo głęboka: + +- `common` opisuje **co ma się wydarzyć** i utrzymuje invariants workflow; +- `hosts/` opisuje **jak dany harness reprezentuje wymagane integracje**; +- `installer` odpowiada za **bezpieczne dostarczenie obu warstw**, ale nie interpretuje semantyki promptów; +- `tests` dostarczają oddzielny dowód core, overlay, install i native runtime. + +## 3. Proponowana struktura repozytorium + +```text +maister/ +├── common/ +│ ├── skills/ # jedna kopia generic SKILL.md +│ ├── runtime/ # state, gates, continuation, helpers +│ ├── references/ # wspólne kontrakty i metodyki +│ ├── assets/ # dashboard/report assets +│ └── primitives.yml # mały rejestr semantic invariants +├── hosts/ +│ ├── codex/ +│ │ ├── overlay.yml # Host Overlay Contract +│ │ ├── agents/ +│ │ ├── commands/ +│ │ ├── hooks/ +│ │ ├── manifests/ +│ │ ├── settings/ +│ │ └── tests/ +│ ├── cursor/ # identyczny kontrakt katalogów +│ └── kiro-cli/ +├── installer/ +│ ├── bin/maister-install.mjs +│ └── lib/ +│ ├── source-resolver.mjs +│ ├── overlay-loader.mjs +│ ├── compatibility.mjs +│ ├── assembler.mjs +│ ├── validator.mjs +│ ├── transaction.mjs +│ ├── settings-merge.mjs +│ └── receipt-store.mjs +├── schemas/ +│ ├── host-overlay.schema.json +│ ├── primitive.schema.json +│ ├── receipt.schema.json +│ └── evidence.schema.json +├── tests/ +│ ├── core/ +│ ├── overlay-contract/ +│ ├── installer/ +│ ├── host-runtime/ +│ └── fixtures/ +└── docs/ + ├── installation.md + ├── host-support.md + └── adding-a-host.md +``` + +`common/skills` może pozostać fizycznie w obecnym `plugins/maister/skills` podczas pierwszych kroków migracji, ale końcowy owner nie może być nazwany ani ukształtowany jako Claude plugin. Nazwy docelowe są częścią migracji, nie wymaganiem wstecznej kompatybilności. + +## 4. Komponenty i głębokie interfejsy + +| Komponent | Odpowiedzialność | Publiczny interfejs | Czego nie robi | +|---|---|---|---| +| Portable core | Skills, workflow invariants, state/gate/continuation runtime | pliki `common/**`, primitive ids, executable core contracts | nie zna layoutu, tool names ani settings hosta | +| Primitive registry | Minimalny słownik operacji wymagających jawnej gwarancji | `id`, `class`, `required_effect`, `failure_policy` | nie jest DSL-em faz ani prompt AST | +| Host overlay | Natywne assets i bindings jednego harnessu | `overlay.yml` + repo-owned files | nie kopiuje generic skills i nie transformuje ich prozy | +| Source resolver | Lokalny checkout albo zweryfikowane źródło GitHub | `resolve(source, ref) -> immutableSource` | nie instaluje i nie ufa ruchomemu refowi bez receipt | +| Assembler | Deterministyczne `common + overlay` w staging | `assemble(source, overlay, staging)` | nie generuje agents/hooks/commands z promptów | +| Validator | Schema, inventory, paths, references, compatibility | `validate(staging, contract, hostFacts)` | nie naprawia niezgodnych danych | +| Settings merge | Plan kontrolowanych mutacji shared config | `plan/read/apply/restore` dla managed keys | nie nadpisuje niezarządzanych kluczy | +| Transaction manager | Lock, backup, commit, rollback i recovery | `prepare -> commit -> finalize` | nie uznaje częściowego sukcesu | +| Receipt store | Własność, hashes, evidence i historia instalacji | immutable receipt + active pointer | nie jest źródłem workflow state | +| Evidence harness | E1–E6 ze statusem i provenance | evidence record per host/capability/scenario | `unavailable` nigdy nie mapuje na pass | + +## 5. Taksonomia semantic primitives + +Zasada wyboru jest prosta: **jeżeli harness może swobodnie wybrać sposób wykonania bez zmiany obserwowalnej semantyki workflow, nie tworzymy bindingu**. Primitive powstaje dopiero wtedy, gdy błędny wybór może ominąć pauzę, zmienić trwały stan, naruszyć safety policy albo fałszywie zadeklarować capability. + +### 5.1 Harness-owned ordinary operations + +| Intencja w generic skill | Decyzja harnessu | Dlaczego bez bindingu | +|---|---|---| +| znajdź pliki lub użycia symbolu | `rg`, grep, index, search tool, Explore | wynik nie zależy od nazwy narzędzia | +| przeczytaj i przeanalizuj kod | native read, shell, semantic index | prompt określa cel i zakres | +| uruchom lokalny test | shell/process runner | exit code i artefakt są wystarczającym kontraktem | +| sformatuj plik | repo formatter lub edycja natywna | repo standards definiują wynik | +| zbierz read-only informacje | wykonanie inline albo pomocniczy agent | delegacja nie jest wymagana semantycznie | + +Generic skills używają języka intencji: „wyszukaj”, „przeczytaj”, „zweryfikuj”. Nie zawierają `Grep`, `Task tool`, `Explore tool`, `AskUserQuestion`, `Skill tool` ani odpowiedników konkretnych hostów. + +### 5.2 Explicit semantic bindings + +| Primitive | Klasa | Wymagany efekt | Przykład bindingu overlayu | +|---|---|---|---| +| `present_user_gate` | control-flow/safety | zatrzymuje fazę, prezentuje dokładne opcje, zwraca jedną decyzję | native user-input UI albo host-specific blocking protocol | +| `delegate_role` | capability | uruchamia rolę z przekazanym context i ograniczeniami read/write | native subagent schema lub udokumentowany inline fallback | +| `persist_before_continue` | persistence | terminalny record jest trwały przed kolejną fazą | portable runtime + host invocation wrapper | +| `continue_phase` | control-flow | idempotentna kontynuacja tylko po ważnej decyzji | host hook/command/binding do shared runnera | +| `enforce_safety_hook` | safety | blokuje denylisted mutation przed wykonaniem | native hook event i matcher | +| `report_progress` | capability | pokazuje status bez zmiany source of truth | native plan/progress surface albo jawny no-op | +| `resolve_project_instructions` | safety/context | ładuje właściwe instrukcje przed pracą | host discovery rule/manifest | + +Minimalny wpis `common/primitives.yml` opisuje invariant, nie składnię hosta: + +```yaml +- id: present_user_gate + class: control-flow + required_effect: block_until_one_exact_option_is_selected + failure_policy: fail_closed +- id: search_repository + class: ordinary + binding: harness_owned +``` + +Nowy primitive jest dopuszczalny, gdy ta sama różnica semantyczna wystąpiła w co najmniej dwóch workflow lub gdy pojedyncza operacja chroni safety/persistence invariant. To ogranicza ryzyko zbudowania pełnego DSL, zgodnie z decyzją 1A ([solution convergence](solution-exploration.md#2-obszar-decyzyjny-1--głębokość-reprezentacji-kanonicznej--ir)). + +## 6. Host Overlay Contract + +Każdy `hosts//overlay.yml` przechodzi wspólny schema i ma następujący kontrakt: + +```yaml +schema_version: 1 +host_id: codex +overlay_version: 1 +supported_source_version: ">=3.0.0 <4" + +layout: + managed_root: ".codex/plugins/maister" + copy_common: + - from: common/skills + to: skills + - from: common/runtime + to: runtime + overlay_assets: + - from: hosts/codex/agents + to: agents + +capabilities: + present_user_gate: + class: semantic + binding: hooks/user-gate.md + evidence_required: E5 + compatible_fingerprints: ["sha256:..."] + plugin_layout: + class: packaging + binding: manifests/plugin.json + evidence_required: E2 + +settings: + - id: advisor_agent + format: toml + destination: ".codex/agents/advisor.toml" + ownership: whole_file + source: settings/advisor.toml + +validation: + required_paths: [skills, agents] + forbidden_vocabulary: ["AskUserQuestion", "Task tool"] +``` + +Kontrakt wymaga: + +- jawnej allowlisty target paths; żaden wpis nie może wyjść poza root; +- braku kolizji między `copy_common` i `overlay_assets`, chyba że schema wskazuje dozwolony `replace` dla host-owned path; +- bindingu albo jawnego `unsupported` dla każdego wymaganego semantic primitive; +- klasy `semantic` albo `packaging` dla każdej capability; +- wskazania evidence target i ostatnio potwierdzonego fingerprint/version; +- kompletnego inventory agents, commands, hooks, manifests i settings wymaganych przez host; +- host contract tests w `hosts//tests`. + +Overlay jest małym, repo-owned modułem. Nie ma renderera prozy ani templates generujących jego zawartość w czasie instalacji. Jeśli dwa hosty mają identyczny plik, mogą korzystać ze wspólnego assetu tylko wtedy, gdy semantyka i format są rzeczywiście wspólne; nie tworzymy abstrakcji wyłącznie dla kilku podobnych linii. + +## 7. Custom installer + +### 7.1 CLI + +```text +maister install --target codex|cursor|kiro-cli [--source PATH|GH_URL] [--ref TAG_OR_SHA] + [--scope user|project] [--dest PATH] [--host-version VERSION] + [--dry-run] [--json] +maister update --target HOST [--source PATH|GH_URL] [--ref TAG_OR_SHA] [--dry-run] +maister uninstall --target HOST [--scope user|project] [--dry-run] +maister rollback --target HOST [--to RECEIPT_ID] +maister verify --target HOST [--native] +maister status [--target HOST] [--json] +``` + +Domyślne źródło to bieżący local checkout. GitHub source jest pobierany do tymczasowego immutable checkoutu; `--ref` zostaje rozwiązany do commit SHA i zapisany w receipt. Installer nie korzysta z marketplace i nie utrzymuje osobnych kanałów prebuilt. + +### 7.2 Pipeline instalacji + +```text +resolve source -> load overlay -> probe host facts -> compatibility decision + -> acquire lock -> build plan -> stage copies/settings -> validate + -> backup managed state -> commit managed tree -> commit settings + -> write receipt -> switch active pointer -> cleanup + failure at any point + | + v + restore bytes + modes + topology, keep old receipt active +``` + +1. **Resolve:** waliduje target/source/ref; autodetection może zasugerować host, ale nie nadpisuje jawnego `--target`. +2. **Probe:** odczytuje host version i capability fingerprints bez mutacji. +3. **Compatibility:** semantic unknown/incompatible kończy się przed staging; packaging-only unknown może przejść jako `provisional`. +4. **Lock:** per `{target, scope, destination}` zapobiega równoległym mutacjom. +5. **Plan:** wylicza pełne copy operations, settings mutations, ownership i expected hashes. +6. **Stage:** kopiuje wspólną warstwę i overlay do pustego katalogu na tym samym filesystemie co destination. +7. **Validate:** schema, inventory, referencje, vocabulary, permissions, path containment, deterministic hash i installed-path canary. +8. **Backup:** zachowuje wszystkie zarządzane pliki, współdzielone config bytes, modes, symlinks i directory topology. +9. **Commit:** rename managed tree, potem kontrolowane atomic writes settings; receipt pozostaje pending. +10. **Finalize:** zapisuje immutable receipt i atomowo przełącza active pointer dopiero po sukcesie wszystkich mutacji. +11. **Rollback:** przy błędzie odtwarza pełny snapshot i poprzedni active receipt; recovery może dokończyć rollback po przerwaniu procesu. + +### 7.3 Receipt i stan transakcji + +Receipt nie zastępuje `orchestrator-state.yml`; opisuje wyłącznie instalację: + +```json +{ + "receipt_version": 1, + "id": "2026-07-14T...-codex-", + "status": "active", + "target": "codex", + "scope": "project", + "source": {"kind":"github","url":"...","commit":""}, + "versions": {"maister":"3.0.0","overlay":1,"host":"..."}, + "compatibility": {"status":"supported","capabilities":[]}, + "managed_tree": {"root":"...","files":[{"path":"...","sha256":"...","mode":"..."}]}, + "settings_mutations": [{"path":"...","owned_keys":["..."],"before_sha256":"...","after_sha256":"..."}], + "previous_receipt_id": "...", + "evidence": [] +} +``` + +Stan przejściowy (`prepared`, `committing`, `rolling_back`) żyje w journalu obok receipt store. Po restarcie installer najpierw odzyskuje niedokończoną transakcję, a dopiero potem przyjmuje nowe polecenie. + +## 8. Własność i merge ustawień + +Każda mutacja ustawień deklaruje jedną z dwóch polityk: + +1. `whole_file` — Maister jest wyłącznym właścicielem pliku w dedykowanej ścieżce; update może go zastąpić atomowo. +2. `managed_keys` — plik jest współdzielony; overlay deklaruje dokładne JSON/TOML/YAML paths, a installer zmienia tylko te klucze. + +Reguły: + +- brak niejawnego deep merge i brak tekstowych `sed` na configu; +- parse -> validate -> mutate allowlisted keys -> serialize deterministycznie do temp -> atomic rename; +- konflikt z wartością użytkownika kończy się czytelnym błędem albo wymaga jawnej opcji wyboru, nigdy silent overwrite; +- receipt zapisuje owned keys oraz before/after hash; backup zachowuje oryginalne bytes, mode i symlink topology; +- uninstall usuwa tylko wartości nadal równe wartościom zarządzanym z aktywnego receipt; wykryty user drift jest raportowany i pozostawiony bez zmian; +- update liczy plan względem aktywnego receipt i aktualnego filesystemu; nie zakłada czystego stanu. + +## 9. Przepływy lifecycle + +### Install + +- wymaga braku aktywnego receipt albo jawnego `update`; +- tworzy pełny staging i nie dotyka destination przed przejściem walidacji; +- commit kończy się jednym aktywnym receipt lub pełnym rollbackiem. + +### Update + +- sprawdza integralność aktualnie zarządzanych plików i user drift; +- składa nowy staging od zera z nowego immutable source; +- zachowuje poprzedni receipt i backup jako bezpośredni rollback target; +- nie wykonuje in-place patchowania generic skills. + +### Uninstall + +- usuwa wyłącznie pliki/rooty i managed settings wskazane przez aktywny receipt; +- zachowuje zmodyfikowane przez użytkownika elementy, zgłasza conflict i nie usuwa parent directory, jeśli nie jest puste; +- tworzy uninstall receipt, aby operacja była audytowalna i odwracalna do czasu cleanup policy. + +### Rollback + +- domyślnie wraca do `previous_receipt_id`; opcjonalnie do jawnego receipt zgodnego z tym samym target/scope; +- przywraca bytes, modes, symlinks, directory topology i settings snapshot; +- po weryfikacji atomowo przełącza active pointer; nie rekonstruuje starej instalacji z aktualnego source. + +## 10. Compatibility i evidence + +Capability record rozdziela semantykę od packagingu: + +```yaml +host: cursor +capability: present_user_gate +class: semantic +host_version: "x.y.z" +overlay_version: 1 +fingerprint: "sha256:..." +evidence_level: E5 +status: passed +scenario: blocking-exact-options +timestamp: "..." +target: test-host-smoke-cursor +``` + +Polityka: + +| Stan | Semantic/safety | Packaging-only | +|---|---|---| +| known fingerprint + wymagany evidence passed | `supported` | `supported` | +| unknown host version, fingerprint unchanged | dozwolone tylko jeśli kontrakt jawnie uznaje fingerprint za wystarczający | `provisional` po E1/E2/E4 | +| fingerprint changed lub brak wymaganego bindingu | fail-closed | fail, jeśli validation nie przechodzi; inaczej `provisional` | +| runtime probe niedostępny | `unavailable`, nigdy pass; zgodnie z wymaganym progiem może blokować | nie podnosi ponad E4 | + +Nie ma globalnego `--force` omijającego safety invariants. Ewentualny override jest per packaging capability, zapisany w receipt i niedostępny dla denylisted semantic primitives. Badanie wykazało, że globalny boolean capability ukrywa wersję, scenariusz i świeżość, dlatego record musi pozostać wielowymiarowy ([test assurance findings](../analysis/findings/test-assurance-runtime-gap.md)). + +## 11. Walidacja i macierz testów + +### 11.1 Testowane raz dla common core + +- schema/state repository oraz byte-exact transactional rejection; +- gate engine, denylist, Advisor/Arbiter provenance i idempotency; +- continuation/outbox/reclaim/acknowledgement; +- generic skill inventory, references i forbidden host vocabulary; +- report/dashboard projections i installed-path portable runtime canary; +- failure injection wspólnych utilities. + +### 11.2 Testowane per host overlay + +- `overlay.yml` schema, required inventory i referential integrity; +- agents/commands/hooks/manifests/settings native syntax; +- kompletność semantic primitive bindings i unsupported fallbacks; +- brak foreign-host vocabulary; +- deterministic `common + overlay` assembly; +- install/update/uninstall/rollback w izolowanym root; +- host discovery E5 oraz krytyczne scenariusze E6, gdy runtime jest dostępny. + +| Target | Zakres | Częstotliwość | Dowód | +|---|---|---|---| +| `test-core` | pełny portable core | każdy PR | E3 | +| `test-generic-skills` | inventory, links, neutral vocabulary | każdy PR | E1/E3 | +| `test-overlay HOST` | schema/native assets/bindings | każdy PR, 3 hosty | E1 | +| `test-assembly HOST` | determinism, hashes, installed canary | każdy PR, 3 hosty | E2/E3 | +| `test-installer HOST` | lifecycle + injected rollback | każdy PR, 3 hosty | E4 | +| `test-host-smoke HOST` | discovery + sentinel | required, jeśli środowisko hosta jest dostępne; inaczej jawne 77 | E5 | +| `test-host-e2e HOST SCENARIO` | gate/delegation/continuation | release/scheduled | E6 | +| `validate-evidence` | status, freshness, version, target | każdy PR/release | governance | + +`exit 77` jest `unavailable`, nie zielonym skipem. Claim supportu jest per capability/scenario, nie per samą nazwę hosta. Obecne testy pokazują realne, lecz nierówne poziomy host evidence, więc migracja nie może sprowadzić ich do jednego booleanu ([current evidence matrix](../analysis/findings/test-assurance-runtime-gap.md)). + +## 12. Migracja w jednym zadaniu implementacyjnym + +Migracja zachowuje legacy tylko jako tymczasowy oracle na branchu. Końcowy stan zadania nie zawiera dual path. + +### M0 — baseline + +- zinwentaryzować exact legacy outputs, testy, docs, CI i install paths; +- zapisać semantic manifest każdego wspieranego docelowo hosta; +- uruchomić obecne build/validate i zachować wyniki jako porównanie. + +### M1 — neutral common core + +- przenieść generic skills/runtime/references/assets do neutralnej własności; +- usunąć Claude-native vocabulary z generic layer; +- dodać minimalny primitive registry i common core suite. + +### M2 — repo-owned overlays + +- utworzyć `hosts/codex`, `hosts/cursor`, `hosts/kiro-cli` z pełnym native inventory; +- przenieść host-specific agents, commands, hooks, manifests i settings bez generowania; +- dodać overlay schema oraz parametryczny contract harness. + +### M3 — custom installer + +- wdrożyć local/GitHub source resolution, copy/merge assembly, validation, receipt, lifecycle i recovery; +- uruchomić E4 dla każdego z trzech hostów z failure injection; +- sprawdzić installed-path canaries. + +### M4 — shadow comparison + +- dla Codex, Cursor i Kiro złożyć nowy tree i porównać z legacy generated tree; +- klasyfikować różnice jako expected architectural change albo defect; +- wymagać zero nierozstrzygniętych różnic w manifestach, referencjach, executable bits, hooks i semantic primitives. + +### M5 — deletion before completion + +- usunąć `plugins/maister-codex`, `plugins/maister-cursor`, `plugins/maister-kiro` oraz stare build adapters, generatory i drift jobs; +- usunąć canonical Claude plugin, Claude manifest/hooks/commands/agents, `claude.e2e.sh`, capability entries, dokumentację i vocabulary; +- przepiąć CI, Makefile, release/docs na nowy installer i trzy hosty; +- wykonać finalne testy na czystym checkout i potwierdzić czysty `git status`. + +## 13. Definition of Done + +Zadanie implementacyjne jest ukończone tylko wtedy, gdy wszystkie warunki są spełnione: + +1. `common/skills` jest jedyną utrzymywaną kopią generic skills i installer kopiuje ją byte-for-byte dla Codex, Cursor i Kiro CLI. +2. Generic layer nie zawiera Claude-native ani foreign-host tool vocabulary; ordinary operations pozostają harness-owned. +3. Każdy wymagany semantic primitive ma binding lub jawny, walidowany unsupported fallback w każdym overlayu. +4. `hosts/codex`, `hosts/cursor` i `hosts/kiro-cli` zawierają jawne agents, commands, hooks, manifests, settings oraz host contract tests. +5. Installer działa z lokalnego checkoutu i GitHub source resolved do SHA; nie korzysta z marketplace ani runtime prompt generation. +6. Fresh install, reinstall policy, update, uninstall i rollback przechodzą dla wszystkich trzech hostów w izolowanych rootach. +7. Invalid input i injected failure pozostawiają bytes, modes, symlinks i directory topology bez zmian albo przywrócone byte-exact. +8. Settings merge modyfikuje wyłącznie zadeklarowane managed keys; user drift jest zachowany i raportowany. +9. Compatibility records rozróżniają semantic/safety od packaging; semantic unknown fail-closed, packaging provisional jest audytowalne. +10. Pełny common-core E3 działa raz; per-host E1/E2/E4 oraz dostępne E5/E6 emitują wersjonowane evidence records, a `unavailable` nie jest pass. +11. Shadow comparison ma zero niewyjaśnionych różnic dla Codex, Cursor i Kiro CLI. +12. Stare build adapters, transform scripts, generated drift jobs i kompletne generated trees nie istnieją w końcowym repo. +13. Claude Code nie istnieje w supported targets, installerze, overlays, manifests, commands, agents, hooks, tests, capability matrix, docs ani generic vocabulary. +14. Repo docs i `.maister/docs/project/{vision,architecture,tech-stack,roadmap}.md` opisują nową architekturę i tylko trzy wspierane hosty. +15. Czysty checkout potrafi zainstalować, zweryfikować i odinstalować każdy target bez modyfikowania repo; końcowy `git status` jest czysty. + +## 14. Ryzyka i obserwowalność + +| Ryzyko | Mitigacja | Sygnał | +|---|---|---| +| semantic drift w generic prose | forbidden vocabulary + primitive review + scenario contracts | diff inventory i failed semantic canary | +| partial install/config corruption | staging, journal, backups, atomic writes, injected failures | transaction id, recovery status, before/after hashes | +| overlay niekompletny po zmianie hosta | schema + capability fingerprint + fail-closed | compatibility decision per capability | +| installer usuwa dane użytkownika | receipt ownership + managed-key comparison | drift/conflict report przed commit/uninstall | +| dual path pozostaje na stałe | M5 i DoD wymagają fizycznego usunięcia legacy | repository inventory check | +| fałszywie zielone host tests | structured E0–E6 evidence, `77=unavailable` | dashboard/report by status and freshness | + +Każde polecenie installera z `--json` emituje `operation_id`, `target`, `source_commit`, `phase`, `compatibility_status`, `changed_paths`, `receipt_id`, `rollback_performed` i listę evidence. Logi nie zawierają credentials ani pełnej treści ustawień. Domyślny human output podaje następny krok naprawczy oraz ścieżkę receipt/journalu. + +## 15. Integracja z istniejącym systemem + +- `orchestrator-state.yml` pozostaje jedynym źródłem prawdy workflow; receipt jest osobnym stanem instalacyjnym. +- Istniejące ESM state/gate/continuation stają się `common/runtime` i zachowują swoje executable contracts. +- Obecne Cursor/Kiro/Codex host assets są wejściem do jawnych overlayów, nie szablonami generatora. +- Obecne generated trees są wyłącznie baseline M0/M4 i są usuwane w M5. +- Make/CI zostają uproszczone do core + parametrycznych overlay/installer tests oraz oddzielnych native probes. + +## 16. Ślad decyzji i dowodów + +Siedem decyzji architektonicznych zapisano w [decision-log.md](decision-log.md): boundary reprezentacji, overlay/installer, task-scoped legacy removal, capability-sensitive compatibility, usunięcie Claude, transactional settings ownership oraz evidence boundary. Decyzje 1A, 2D, 3D, 4C i 5D pochodzą z potwierdzonej konwergencji zapisanej w `orchestrator-state.yml`; szczegółowe pierwotne alternatywy są w [solution-exploration.md](solution-exploration.md). + diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/orchestrator-state.yml b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/orchestrator-state.yml new file mode 100644 index 00000000..21a22112 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/orchestrator-state.yml @@ -0,0 +1,856 @@ +orchestrator: + started_phase: phase-6 + completed_phases: [phase-1, phase-2, phase-3, phase-4, phase-5, phase-6] + failed_phases: [] + auto_fix_attempts: + phase-1: 0 + phase-2: 0 + phase-3: 0 + phase-4: 0 + phase-5: 0 + phase-6: 0 + options: + html_output: true + brainstorming_enabled: true + design_enabled: true + advisor: + enabled: true + gate_policies: + phase-exit: fully_automatic + optional-phase: fully_automatic + clarify: fully_automatic + convergence: fully_automatic + verify-matrix: fully_automatic + advisor_agent: advisor + advisor_model: gpt-5.6-sol + arbiter_agent: arbiter + arbiter_model: gpt-5.6-sol + arbiter_enabled_on_disagreement: true + retry: + advisor_attempts: 3 + arbiter_attempts: 3 + backoff: exponential + created: "2026-07-14T13:25:50Z" + updated: "2026-07-14T16:25:57Z" + task_path: .maister/tasks/research/2026-07-14-platform-independent-plugin + task_ids: + phase-1: research-phase-1 + phase-2: research-phase-2 + phase-3: research-phase-3 + phase-4: research-phase-4 + phase-5: research-phase-5 + phase-6: research-phase-6 + gate_history: + - schema_version: 1 + idempotency_key: sha256:8dc80ac772693c815f0dfac96f7baa45a3cded3e406f16c6f5a42756f1e157d4 + phase_id: phase-1 + gate_type: phase-1-exit + question: Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? + options: + - Continue to brainstorming evaluation + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to brainstorming evaluation + final_actor: user + original_recommendation: Continue to brainstorming evaluation + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly chose to continue after reviewing the completed research foundation and report. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b44cce49b270e039db9825c224697b82b1f7ac236d4a1a361cd36e21a6e3cd13 + phase_id: phase-3 + gate_type: phase-3-exit + question: Continue to solution convergence? + options: + - Continue to solution convergence + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to solution convergence + final_actor: user + original_recommendation: Continue to solution convergence + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly chose to continue from generated alternatives to sequential solution convergence. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:1c0159ead600b2c3ba1d2b1a28bee5b4dec632b0378564f1bb75386b3f380e6b + phase_id: phase-4 + gate_type: research-convergence + question: Jak głęboka powinna być kanoniczna reprezentacja workflow Maister? + options: + - 1A — minimalne typed primitives + host-aware templates (Recommended) + - 1B — pełny neutralny workflow IR od początku + - 1C — canonical Markdown + ulepszone regex/golden snapshots + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 1A — minimalne typed primitives + host-aware templates (Recommended) + final_actor: user + original_recommendation: 1A — minimalne typed primitives + host-aware templates (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected minimal typed primitives and clarified that low-level tool choice should normally remain with the host harness, while explicit bindings are reserved for control-flow, safety, persistence, or capability-sensitive operations. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b9678e25714b36a77ab80c6b8e99dce1ae251775ffd0668e7f0d24736a65279c + phase_id: phase-4 + gate_type: research-convergence + question: Gdzie powinien działać materializer i jak dystrybuować host-native artefakty? + options: + - 2A — lokalny materializer jako jedyna ścieżka + - 2B — wyłącznie CI-prebuilt artifacts + - "2C — hybryda: referencyjny lokalny materializer + prebuild z tego samego path (Recommended)" + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Need more info + final_actor: user + original_recommendation: "2C — hybryda: referencyjny lokalny materializer + prebuild z tego samego path (Recommended)" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User rejected the marketplace-oriented framing and clarified that installation is from a local or GitHub repository through a fully controlled custom installer, with generic skills copied unchanged and host-specific assets explicit in the repository. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:153a61d692e97ae1ac47bef311677bf1c1f7e2eab3e0c23c703ce5087414a4bf + phase_id: phase-4 + gate_type: research-convergence + question: Jaki model instalacji i przechowywania host-specific assets powinniśmy przyjąć po wykluczeniu marketplace? + options: + - 2D — custom installer + wspólne skille + jawne host overlays w repo (Recommended) + - 2A — custom installer generuje host-specific assets podczas instalacji + - 2B — kompletne prebuilt host trees przechowywane w repo + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 2D — custom installer + wspólne skille + jawne host overlays w repo (Recommended) + final_actor: user + original_recommendation: 2D — custom installer + wspólne skille + jawne host overlays w repo (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed the repository-owned overlay model with a fully controlled custom installer, shared generic skills, and explicit harness-specific assets. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:d883bbce776c4f95ce19c8db040193ced1eafa5255bdbae75888d5515e32e785 + phase_id: phase-4 + gate_type: research-convergence + question: Kiedy i na jakich warunkach usunąć obecne commitowane generated trees? + options: + - 3A — natychmiastowe usunięcie po uruchomieniu nowego installera + - 3B — shadow-first, dwa stabilne release i jawne exit criteria (Recommended) + - 3C — pozostawić generated trees jako stale publikowane snapshots + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Need more info + final_actor: user + original_recommendation: 3B — shadow-first, dwa stabilne release i jawne exit criteria (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User refined the migration model: keep legacy generated trees only as a comparison oracle during implementation, then remove them before the implementation task is completed rather than waiting for two releases." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:9eef80c3b88f94ca365644236f7e7f5b860fb3086e4fa6018f4b1d6b3bfa81c2 + phase_id: phase-4 + gate_type: research-convergence + question: Jaką bramkę usunięcia legacy generated trees przyjąć dla zadania implementacyjnego? + options: + - 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania (Recommended) + - 3A — usunięcie legacy trees od razu po uruchomieniu installera + - 3B — utrzymanie legacy trees przez dwa stabilne release + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania (Recommended) + final_actor: user + original_recommendation: 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed task-scoped shadow comparison with mandatory removal of legacy generated trees before implementation completion. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:87b6b2a02b6c2c1783c7192766cce253a77b31ca8518131c34293c4c9aaccd5b + phase_id: phase-4 + gate_type: research-convergence + question: Jak custom installer powinien obsługiwać nieznaną lub niepotwierdzoną wersję harnessu? + options: + - 4A — zawsze fail-closed poza zadeklarowanym zakresem + - 4B — zawsze warning i best-effort install + - "4C — capability-sensitive: semantic fail-closed, packaging provisional (Recommended)" + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "4C — capability-sensitive: semantic fail-closed, packaging provisional (Recommended)" + final_actor: user + original_recommendation: "4C — capability-sensitive: semantic fail-closed, packaging provisional (Recommended)" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected capability-sensitive compatibility with fail-closed semantic boundaries and provisional packaging-only compatibility. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:9d56a4cec456a5958dbefc581a6fe1ac046278c265f19685240d902cbf817948 + phase_id: phase-4 + gate_type: research-convergence + question: Jaką bramkę jakości przyjąć dla overlay i instalacji Claude Code bez dostępnego runtime? + options: + - 5A — blokować ukończenie zadania bez Claude E5/E6 + - 5B — wymagać E1–E4 + shared-core E3, a E5/E6 oznaczyć jako unavailable (Recommended) + - 5C — community/canary certification przed stable promotion + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Need more info + final_actor: user + original_recommendation: 5B — wymagać E1–E4 + shared-core E3, a E5/E6 oznaczyć jako unavailable (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User rejected retaining an untestable Claude Code target and requested removing it until a real need and runtime exist. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:af63e4bae8d90431fe69ac253a4d766f0f4d06f92f0b0310a72f2fa59edfae1a + phase_id: phase-4 + gate_type: research-convergence + question: Co zrobić z targetem Claude Code w docelowej architekturze? + options: + - 5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie (Recommended) + - 5B — zachować Claude z E1–E4 i jawnym E5/E6 unavailable + - 5A — zachować Claude i blokować ukończenie bez E5/E6 + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie (Recommended) + final_actor: user + original_recommendation: 5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed removal of Claude Code from supported targets; future support will be a separate new-harness task driven by real need and available runtime. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:deff7dc9407e4bf7bd8e9827eea83f0943d11d5daa1793b43db636eb584db001 + phase_id: phase-4 + gate_type: phase-4-exit + question: Brainstorming complete. Continue to high-level design? + options: + - Continue to high-level design + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to high-level design + final_actor: user + original_recommendation: Continue to high-level design + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly chose to continue from completed solution convergence to high-level design. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:27838d495a10abcfeb14322b18149cd45829a1c61bda25c3992a388e58244645 + phase_id: phase-5 + gate_type: research-clarification + question: "Założenia projektu: wspieramy Codex, Cursor i Kiro CLI; Claude Code i marketplace są poza zakresem; generic skills są kopiowane bez transformacji; jawne host overlays zawierają hooks, agents, commands, manifests i settings; custom installer składa i instaluje wynik transakcyjnie; legacy generated trees znikają przed zamknięciem zadania. Czy potwierdzasz te założenia?" + options: + - Confirm assumptions + - Correct assumptions + - Provide more context + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Confirm assumptions + final_actor: user + original_recommendation: Confirm assumptions + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed the consolidated architecture assumptions without corrections. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:6bdf08499f5ea52adcb109887df08612b87fed5c1a2a6ba779d4fc70c9cb160e + phase_id: phase-5 + gate_type: phase-5-exit + question: Design complete. Continue to output generation? + options: + - Continue to output generation + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to output generation + final_actor: user + original_recommendation: Continue to output generation + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly chose to continue from the completed high-level design to final output generation. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b35883e703798a8680ccae7ccae72418a71acd780faaa9c19d3a12a5723f17ce + phase_id: phase-6 + gate_type: final-handoff-approval + question: Research workflow complete. Complete workflow? + options: + - Complete workflow + - Keep workflow open + policy: manual + safety_classification: denylisted + status: decided + selected_option: Complete workflow + final_actor: user + original_recommendation: Complete workflow + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly approved the final research handoff and completion of the workflow. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:aa3bd0f18b9311593067d380929d9f07dfe632faf4dd36a02904bf603026be24 + phase_id: phase-2 + gate_type: optional-phase-selection + question: Badanie wykazało cztery realne warianty oraz nierozstrzygnięte decyzje dotyczące IR, marketplace artifacts, momentu usunięcia generated trees i polityki nieznanych wersji hostów. Would you like to explore solution alternatives? + options: + - Yes, explore alternatives + - No, skip brainstorming + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, explore alternatives + final_actor: user + original_recommendation: Yes, explore alternatives + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User accepted the recommendation to explore alternatives. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:65ca0aed2a12829399eaccb4883a2f0dd909b2b475c9172a924d5be41018fae3 + phase_id: phase-2 + gate_type: optional-phase-selection + question: Rekomendacja obejmuje nową granicę portable core/Host Contract/materializer, transakcyjną instalację, przebudowę CI oraz etapową migrację dystrybucji, więc high-level design jest wartościowy. Would you like to generate a high-level design? + options: + - Yes, generate design + - No, skip design + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, generate design + final_actor: user + original_recommendation: Yes, generate design + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User accepted the recommendation to generate a high-level design after solution convergence. + confidence: high + escalate_to_user: false + user_override: false + error: null + implementation_approval: + status: not_required + approved_by: null + approved_at: null + approved_scope: [] + +task: + title: Uproszczenie i uniezależnienie Maister od platformy + description: Przeanalizować, jak zastąpić generowanie i osobne testowanie wariantów dla wielu hostów jednym rozwiązaniem niezależnym od narzędzia, z rozróżnieniem platformy możliwym na etapie instalacji. + status: completed + tags: [research, architecture, portability, installation, testing] + priority: high + +phases: + - id: phase-1 + name: Research foundation + status: completed + blocked_by: [] + started: "2026-07-14T13:25:50Z" + completed: "2026-07-14T14:15:37Z" + gate: + question: Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? + answer: Continue to brainstorming evaluation + - id: phase-2 + name: Evaluate brainstorming value + status: completed + blocked_by: [phase-1] + started: "2026-07-14T14:15:37Z" + completed: "2026-07-14T14:24:33Z" + gate: + question: Rekomendacja obejmuje nową granicę portable core/Host Contract/materializer, transakcyjną instalację, przebudowę CI oraz etapową migrację dystrybucji, więc high-level design jest wartościowy. Would you like to generate a high-level design? + answer: Yes, generate design + - id: phase-3 + name: Generate solution alternatives + status: completed + blocked_by: [phase-2] + started: "2026-07-14T14:24:33Z" + completed: "2026-07-14T14:33:56Z" + gate: + question: Continue to solution convergence? + answer: Continue to solution convergence + - id: phase-4 + name: Evaluate brainstorming alternatives + status: completed + blocked_by: [phase-3] + started: "2026-07-14T14:33:56Z" + completed: "2026-07-14T15:38:33Z" + gate: + question: Brainstorming complete. Continue to high-level design? + answer: Continue to high-level design + - id: phase-5 + name: Design high-level architecture + status: completed + blocked_by: [phase-4] + started: "2026-07-14T15:38:33Z" + completed: "2026-07-14T16:19:37Z" + gate: + question: Design complete. Continue to output generation? + answer: Continue to output generation + - id: phase-6 + name: Summarize research and suggest next steps + status: completed + blocked_by: [phase-5] + started: "2026-07-14T16:19:37Z" + completed: "2026-07-14T16:25:57Z" + gate: + question: Research workflow complete. Complete workflow? + answer: Complete workflow + +research_context: + research_type: mixed + research_question: W jaki sposób uprościć Maister i uniezależnić go od platform AI coding hostów, tak aby utrzymywać jedno testowalne rozwiązanie, a ewentualne różnice wybierać dopiero podczas instalacji — również dla Claude Code, gdzie nie mamy dostępnego runtime do testów? + scope: + included: + - Kanoniczne źródła pluginu, adaptery platformowe i generowane warianty + - Różnice kontraktów Claude Code, Codex, Cursor i Kiro + - Instalacja, manifesty, discovery skills/agents/commands i host-native runtime + - Obecny build, test matrix, walidacja oraz luki testowe Claude Code + - Możliwe architektury jednego artefaktu lub instalacyjnej materializacji targetu + - Ścieżka migracji ograniczająca duplikację i ryzyko regresji + excluded: + - Implementacja wybranego rozwiązania w tym workflow + - Zmiana funkcjonalnego zakresu workflow Maister niezwiązana z przenośnością + - Deklarowanie pełnej zgodności bez dowodów kontraktowych lub runtime + - Utrzymywanie Claude Code jako wspieranego targetu w docelowej architekturze; może zostać dodany później jako nowy harness + constraints: + - Zachować natywne wymagania każdego hosta i jego mechanizm instalacji + - Zachować audytowalność, resumability i bezpieczeństwo bramek + - Nie opierać gwarancji Claude Code na runtime, którego projekt nie może uruchomić + - Preferować jeden kanoniczny model zachowania i deterministyczne granice platformowe + methodology: + - Mixed technical, requirements, and literature research + - Layer decomposition across behavior, portable runtime, host contract, packaging, installation, and assurance + - Multi-source triangulation with evidence levels E0-E6 + - Comparative scorecard across current build-time generation, install-time materialization, shared core with thin adapters, and optional neutral IR + sources: + - planning/sources.md + - Canonical plugin sources and shared runtime helpers + - Platform adapters, installers, generated target shapes, and host-owned official documentation + - Make, CI, contract/install/smoke/E2E tests, and host capability matrix + confidence_level: high + gathering_strategy: + categories: + - canonical-core-transform-boundary + - host-contracts-installation + - test-assurance-runtime-gap + count: 3 + source: planner + project_doc_paths: + - .maister/docs/project/vision.md + - .maister/docs/project/roadmap.md + - .maister/docs/project/tech-stack.md + - .maister/docs/project/architecture.md + phase_summaries: + phase-1: + summary: Jeden neutralny behavior/runtime core i jeden bundle są wykonalne; host-native drzewa pozostają różne i powinny być materializowane przez typowane, wersjonowane adaptery podczas instalacji. Kierunek ma wysoką pewność, natomiast dokładny descriptor/IR i integracja marketplace wymagają dalszej konwergencji. + steps_completed: [initialize, plan, gather, synthesize] + decisions: + - decision: "Typ badania: mixed — technical, requirements i literature research." + rationale: Wymagane jest połączenie analizy kodu, kontraktów hostów i źródeł oficjalnych. + - decision: Jednostką porównania będzie kontrakt zachowania, packagingu, instalacji i weryfikacji, a nie tylko układ plików wygenerowanych pluginów. + rationale: Sam filesystem shape nie dowodzi parity semantycznej. + - decision: Gathering Strategy ma trzy stabilne, niezależne kategorie, aby zmieścić analizę w dostępnym limicie agentów i umożliwić późniejsze łączenie ustaleń po identyfikatorach. + rationale: Kategorie pokrywają core/transforms, host contracts/installation oraz assurance/runtime gap. + - decision: Hipoteza „różnice dopiero przy instalacji” będzie oceniana obok co najmniej dwóch alternatyw, a nie traktowana jako z góry wybrana architektura. + rationale: Rekomendacja musi wynikać z porównywalnych dowodów. + - decision: "Docelowo: portable behavior/runtime core + typed host contracts + install-time materializer." + rationale: Maksymalizuje jednokrotne testowanie wspólnej semantyki i ogranicza adaptery do wymaganych kontraktów hostów. + - decision: „Jedno rozwiązanie” oznacza jedno źródło, jeden testowalny core i jeden dystrybuowany bundle; nie oznacza jednego host runtime. + rationale: Hosty wymagają różnych manifestów, discovery, agents, hooks i MCP placement. + - decision: Neutralny IR rozwijać ewolucyjnie dla gates/roles/hooks/capabilities, zamiast budować pełny DSL przed migracją. + rationale: Ogranicza koszt i ryzyko over-design. + - decision: Instalacja musi używać staging, validation, receipt, atomic swap i byte-exact rollback. + rationale: Materializacja na maszynie użytkownika musi być transakcyjna. + - decision: Commitowane target trees usunąć dopiero po potwierdzonej parity i stabilnych release artifacts. + rationale: Pozwala migrować shadow-first i zachować rollback. + - decision: Continue to brainstorming evaluation + rationale: User explicitly chose to continue after reviewing the completed research foundation and report. + risks: + - Dokumentacja hostów może opisywać możliwości nowsze niż dostępne lokalnie CLI lub marketplace; wersje i daty muszą być zapisane przy dowodzie. + - Brak runtime Claude Code uniemożliwia uczciwe potwierdzenie pełnego E2E; trzeba oddzielić dowód semantyczny, instalacyjny, statyczny i runtime. + - Tekstowe transformacje mogą zawierać ukryte różnice semantyczne, których nie ujawni samo porównanie struktury katalogów. + - Termin „jedno rozwiązanie” może oznaczać jedno źródło, jeden artefakt dystrybucyjny albo jeden runtime; synteza musi rozdzielić te poziomy. + - Semantyka gate/delegation/progress może dryfować mimo poprawnego layoutu; globalne substytucje tekstu są głównym źródłem ryzyka. + - Cursor i Kiro contracts są ruchome, a Kiro CLI/IDE wymagają osobnych, precyzyjnie nazwanych targetów. + - Compiler na maszynie użytkownika zwiększa koszt awarii, jeśli nie jest transakcyjny i odtwarzalny offline. + - Claude Code E5/E6 nie może być deklarowane bez realnej binarki, auth, wersji i wykonanego scenariusza. + - Native marketplaces mogą wymagać prebuilt artifacts; wspólny installer powinien z nimi współistnieć, nie koniecznie je zastępować. + artifacts: + - path: planning/research-brief.md + label: Research brief + html: null + - path: planning/research-plan.md + label: Research plan + html: null + - path: planning/sources.md + label: Source plan + html: null + - path: analysis/findings/canonical-core-boundary.md + label: Canonical core boundary findings + html: null + - path: analysis/findings/host-contracts-installation.md + label: Host contracts and installation findings + html: null + - path: analysis/findings/test-assurance-runtime-gap.md + label: Test assurance and runtime gap findings + html: null + - path: analysis/synthesis.md + label: Research synthesis + html: null + - path: outputs/research-report.md + label: Research report + html: outputs/research-report.html + - path: outputs/decision-summary.md + label: Decision summary + html: outputs/decision-summary.html + phase-3: + summary: Wygenerowano pięć obszarów decyzyjnych i piętnaście znacząco różnych alternatyw. Spójna rekomendacja to minimalne typed primitives, hybrydowa materializacja, shadow-first migration, capability-sensitive compatibility oraz jawny Claude evidence ceiling. + decisions: + - decision: Recommend minimal, evolutionary typed primitives plus host-aware templates instead of a full neutral IR at migration start. + rationale: Ogranicza ryzyko over-design i pozwala migrować stopniowo. + - decision: Recommend a hybrid distribution model in which local installation and CI-prebuilt marketplace artifacts invoke the same deterministic materializer and bundle. + rationale: Łączy jeden compiler path z wymaganiami marketplace. + - decision: Recommend removing committed generated trees only after two consecutive stable releases satisfy E1, E2, E4, installed-path E3 canary, reproducible artifact, rollback, and zero unresolved semantic-parity exceptions for every target. + rationale: Zapewnia mierzalne, odwracalne exit criteria. + - decision: "Recommend capability-sensitive unknown-version handling: fail closed for semantic or safety-sensitive mappings, and allow packaging-only provisional compatibility after validation with explicit warning and expiring evidence." + rationale: Unika zarówno nadmiernego blokowania, jak i ryzykownego best-effort. + - decision: Recommend Claude Code releases use E1–E4 plus shared-core E3 as the enforceable gate, while E5/E6 remain explicitly unavailable until a versioned native probe runs. + rationale: Utrzymuje uczciwy evidence ceiling bez blokowania całego projektu. + - decision: Recommend the coherent architecture combination 1A + 2C + 3B + 4C + 5B. + rationale: Wybrane rekomendacje wzajemnie się wspierają. + risks: + - The boundary between a typed primitive and a host-aware template can drift and become another implicit transformation layer without an exception-review policy. + - Marketplace packaging or signing constraints may require prebuilt artifacts, so local materialization cannot be the only supported distribution channel. + - Textual parity does not prove semantic parity; the migration oracle must validate inventory, references, descriptors, semantic goldens, and installed-path canaries. + - Two-release shadow operation temporarily increases CI and maintenance cost and needs a precise definition of a stable release. + - Capability classification can be wrong; misclassifying a semantic mapping as packaging-only could permit unsafe provisional compatibility. + - Claude Code E5/E6 remain unverified without a real binary, authentication, version, and executed scenario; unavailable evidence must never be shown as passing. + - External host documentation and marketplaces can change faster than adapter evidence, so compatibility records need version, scenario, timestamp, and freshness policy. + artifacts: + - path: outputs/solution-exploration.md + label: Solution exploration + html: outputs/solution-exploration.html + phase-4: + summary: "Konwergencja zakończona zestawem 1A + 2D + 3D + 4C + 5D: neutralne minimalne primitives, custom installer, jawne host overlays, task-scoped shadow removal, capability-sensitive compatibility i usunięcie Claude Code." + decisions: + - decision: 1A — minimalne typed primitives + host-aware templates + rationale: Low-level tool selection normally remains with the host harness; explicit bindings cover control-flow, safety, persistence, and capability-sensitive operations. + - decision: Marketplace jest poza zakresem docelowego modelu instalacji. + rationale: Instalacja ma działać z lokalnego lub GitHub repo przez własny installer pod pełną kontrolą projektu. + - decision: 2D — custom installer + wspólne skille + jawne host overlays w repo + rationale: Generic skills są kopiowane bez transformacji, a hooks, agents, commands, manifests i settings pozostają jawnie zdefiniowane per harness. + - decision: Okres shadow nie powinien wykraczać poza zadanie implementacyjne. + rationale: Legacy trees służą do porównania podczas implementacji, ale muszą zniknąć przed Definition of Done. + - decision: 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania + rationale: User confirmed task-scoped shadow comparison with mandatory removal before implementation completion. + - decision: "4C — capability-sensitive: semantic fail-closed, packaging provisional" + rationale: Semantic and safety-sensitive incompatibilities block installation; packaging-only differences may proceed provisionally after validation. + - decision: Claude Code nie powinien pozostać wspieranym targetem bez możliwości testowania i realnej potrzeby. + rationale: Target można później dodać przez ten sam kontrakt host overlay, gdy pojawi się runtime i uzasadniony use case. + - decision: 5D — usunąć Claude Code ze wspieranych targetów + rationale: Future Claude support is a separate new-harness task driven by real need and available runtime. + risks: + - Zbyt szerokie mapowanie nazw narzędzi stworzy kosztowną warstwę translacji; zbyt wąskie mapowanie może oddać harnessowi operacje wpływające na kontrolę przepływu i bezpieczeństwo. + - Jawne host overlays mogą dryfować, jeśli wspólne skille zaczną zawierać ukryte zależności od nazw narzędzi konkretnego harnessu. + - Usunięcie legacy oracle w tym samym zadaniu wymaga mocniejszej bramki parity, ponieważ nie będzie dwóch release obserwacji. + artifacts: [] + decision_areas: + - area: Głębokość reprezentacji kanonicznej / IR + alternatives_count: 3 + chosen_approach: 1A — minimalne typed primitives + host-aware templates + - area: Dystrybucja i miejsce materializacji + alternatives_count: 3 + chosen_approach: 2D — custom installer + wspólne skille + jawne host overlays w repo + - area: Przejście i kryteria usunięcia generated trees + alternatives_count: 3 + chosen_approach: 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania + - area: Polityka nieznanych wersji harnessu + alternatives_count: 3 + chosen_approach: "4C — capability-sensitive: semantic fail-closed, packaging provisional" + - area: Claude Code assurance bez runtime + alternatives_count: 3 + chosen_approach: 5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie + deferred_ideas: + - Pełny neutralny workflow IR, jeśli minimalne primitives przestaną wystarczać. + - Ponowne dodanie Claude Code jako nowego harnessu po pojawieniu się realnej potrzeby, runtime i testów E5/E6. + - Integracje marketplace pozostają poza zakresem; instalacja odbywa się z lokalnego lub GitHub repo. + phase-5: + summary: "Zaprojektowano modularny monolit dystrybuowany jako repozytoryjny bundle: portable documentation core, jawne Host Overlay Contracts dla Codex/Cursor/Kiro CLI oraz transakcyjny custom installer. Decision log zawiera siedem zaakceptowanych ADR-ów." + decisions: + - decision: "Architektura: portable documentation core with explicit host overlays, nie pełny workflow DSL ani install-time compiler promptów." + rationale: Minimalizuje semantyczną translację i utrzymuje generic skills jako jedno źródło. + - decision: Harness sam wybiera zwykłe narzędzia wykonawcze; jawne bindings obejmują wyłącznie control flow, safety, persistence i capability-sensitive behavior. + rationale: Unika mapowania implementacyjnych nazw narzędzi. + - decision: Jedna kopia generic skills/runtime jest instalowana bez transformacji, a host-native assets są utrzymywane wprost w hosts/codex, hosts/cursor i hosts/kiro-cli. + rationale: Różnice harnessów pozostają jawne i reviewowalne. + - decision: Własny installer obsługuje lokalne repo i GitHub source, staging, validation, lock, receipt, atomic commit, update, uninstall i rollback. + rationale: Instalacja pozostaje kontrolowana i transakcyjna. + - decision: Nieznana wersja hosta blokuje niepotwierdzone capabilities semantyczne; packaging-only może otrzymać jawny status provisional. + rationale: Fail-closed chroni semantykę bez sztucznego blokowania packagingu. + - decision: Legacy build adapters, committed generated trees i Claude Code zostają usunięte w tym samym zadaniu po shadow comparison i spełnieniu Definition of Done. + rationale: Tymczasowy oracle nie staje się drugą architekturą produkcyjną. + risks: + - Docelowe ścieżki discovery i format settings każdego hosta trzeba potwierdzić aktualnymi testami contract/runtime przed implementacją overlayu. + - Atomowa podmiana całego managed tree jest prosta; wieloplikowy merge do współdzielonych ustawień użytkownika wymaga journalu i byte-exact rollbacku. + - Neutralna proza może z czasem zacząć przemycać słownik jednego hosta; potrzebny jest forbidden-vocabulary contract oraz review wyjątków. + - Błędna klasyfikacja capability jako packaging zamiast semantic może przepuścić niezgodność; klasyfikacja musi być jawna i przeglądana. + - Usunięcie legacy w jednym zadaniu zwiększa wagę końcowej bramki parity, szczególnie dla hooks, agents i invocation semantics. + artifacts: + - path: outputs/high-level-design.md + label: High-level design + html: outputs/high-level-design.html + - path: outputs/decision-log.md + label: Decision log + html: outputs/decision-log.html + architecture_style: modular monolith distributed as a repository bundle with portable documentation core, declarative Host Overlay Contracts, and a transactional installer adapter + decisions_count: 7 + phase-6: + summary: Zakończono research, konwergencję i high-level design. Finalny kierunek to neutralny portable core, jawne overlays Codex/Cursor/Kiro CLI, transakcyjny custom installer, task-scoped removal legacy, capability-sensitive compatibility oraz usunięcie Claude Code. + decisions: + - decision: Complete workflow + rationale: User explicitly approved the final research handoff and completion of the workflow. + risks: + - Implementacja powinna rozpocząć się w świeżej sesji i traktować high-level design oraz decision log jako źródło zakresu. + artifacts: + - path: outputs/research-report.md + label: Research report + html: outputs/research-report.html + - path: outputs/solution-exploration.md + label: Solution exploration + html: outputs/solution-exploration.html + - path: outputs/high-level-design.md + label: High-level design + html: outputs/high-level-design.html + - path: outputs/decision-log.md + label: Decision log + html: outputs/decision-log.html + - path: outputs/decision-summary.md + label: Decision summary + html: outputs/decision-summary.html diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/research-report.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/research-report.md new file mode 100644 index 00000000..167dc5d6 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/research-report.md @@ -0,0 +1,181 @@ +# Raport badawczy: jedno, platformowo niezależne rozwiązanie Maister + +## TL;DR +Rekomenduję jedno źródło zachowania i jeden bundle, z którego `maister install --target ` tworzy natywny pakiet wybranego narzędzia. +Rdzeń state/gates/continuation testujemy raz; per host zostają tylko adapter, materializer, install i runtime probes. +Nie rekomenduję jednego identycznego installed tree ani prostego przeniesienia obecnych regex buildów do instalatora. +Claude Code bez runtime może osiągnąć E4 instalacji, ale discovery i wykonanie E5/E6 pozostają jawnie niezweryfikowane. + +## Key Decisions +- Docelowo: portable behavior/runtime core + typed host contracts + install-time materializer. +- „Jedno rozwiązanie” oznacza jedno źródło, jeden testowalny core i jeden dystrybuowany bundle; nie oznacza jednego host runtime. +- Neutralny IR rozwijać ewolucyjnie dla gates/roles/hooks/capabilities, zamiast budować pełny DSL przed migracją. +- Instalacja musi używać staging, validation, receipt, atomic swap i byte-exact rollback. +- Commitowane target trees usunąć dopiero po potwierdzonej parity i stabilnych release artifacts. + +## Open Questions / Risks +- Semantyka gate/delegation/progress może dryfować mimo poprawnego layoutu; globalne substytucje tekstu są głównym źródłem ryzyka. +- Cursor i Kiro contracts są ruchome, a Kiro CLI/IDE wymagają osobnych, precyzyjnie nazwanych targetów. +- Compiler na maszynie użytkownika zwiększa koszt awarii, jeśli nie jest transakcyjny i odtwarzalny offline. +- Claude Code E5/E6 nie może być deklarowane bez realnej binarki, auth, wersji i wykonanego scenariusza. +- Native marketplaces mogą wymagać prebuilt artifacts; wspólny installer powinien z nimi współistnieć, nie koniecznie je zastępować. + +## Odpowiedź wprost + +Tak — projekt można znacząco uprościć i uniezależnić od narzędzia. Najlepszy model to: + +```text +jedno canonical behavior/runtime core + + +małe, wersjonowane adaptery hostów + + +jeden installer/materializer --target + = +różne, natywne pakiety instalacyjne +``` + +Nie da się bezpiecznie osiągnąć pełnej niezależności jako jednego identycznego katalogu. Hosty wymagają różnych manifestów, discovery, agents, hooks, MCP placement i sposobów interakcji (`analysis/findings/host-contracts-installation.md:29-63`). Niezależność powinna oznaczać wspólne **zachowanie i źródło**, nie identyczną fizyczną integrację. + +## Dlaczego obecny model jest kosztowny + +- Canonical source jest Claude-native, nie neutralny (`analysis/findings/canonical-core-boundary.md:33-55`). +- Trzy adaptery mają łącznie 1 780 linii, generator Kiro kolejne 160, a inventory wykazał około 320 tekstowych substytucji (`analysis/findings/canonical-core-boundary.md:101-112`). +- Cztery drzewa pluginów to 610 plików i ok. 5,08 MB wersjonowanych projekcji; nie są niezależnymi implementacjami behavior (`analysis/findings/canonical-core-boundary.md:125-133`). +- Pełny runner contract jest wykonywany cztery razy dla byte-identical copies, mimo że edge cases mogą działać raz na core (`analysis/findings/test-assurance-runtime-gap.md:48-58`). +- PR CI sprawdza głównie rebuild/diff, a pełne `make validate` dopiero release (`analysis/findings/test-assurance-runtime-gap.md:125-134`). + +## Warianty + +| Wariant | Wynik /25 | Największa zaleta | Główny problem | Rekomendacja | +|---|---:|---|---|---| +| Build-time generated variants | 15 | niski koszt przejścia, czytelny diff | duplikacja i regex coupling | baza migracji | +| Install-time compiler 1:1 | 13 | prosty `--target` | przenosi kruche regexy do użytkownika | odrzucić | +| Portable core + typed adapters | **23** | test core raz, minimalna macierz hostów | wymaga nowego kontraktu | **wybrać** | +| Pełny neutralny IR | 20 | najsilniejsza separacja | wysoki koszt i ryzyko over-design | stosować selektywnie | + +Scorecard opiera się na wspólnych kryteriach planu oraz triangulacji transformacji, host contracts i assurance (`analysis/findings/canonical-core-boundary.md:83-133`; `analysis/findings/host-contracts-installation.md:29-158`; `analysis/findings/test-assurance-runtime-gap.md:150-250`). + +## Architektura docelowa + +### 1. Portable behavior/runtime core + +Zawiera fazy, state schema/repository, gates, safety invariants, continuation, role intents, artifact contracts i wspólne bodies skills. Pięć modułów ESM już jest byte-identical w targetach i ma executable contracts, więc to nie jest czysto teoretyczny kierunek (`analysis/findings/canonical-core-boundary.md:57-81`). + +### 2. Versioned Host Contract + +Descriptor definiuje `host_id`, zakres wersji, capabilities, layout, invocation mapping, agent/hook emitters, fallbacki i native evidence target. Nieznane capabilities są fail-closed. + +### 3. Typed/structural materializer + +Materializer generuje manifest, layout, namespaces, agent MD/TOML/JSON, hooks, MCP placement i help. Działa na jawnych fields/primitives/templates, a nie na dowolnej prozie. + +### 4. Jeden bundle i prebuilt artifacts + +Bundle zawiera core, adapters, schemas, assets, installer i golden fixtures. CI materializuje wszystkie targety i może publikować prebuilt marketplace artifacts z dokładnie tego samego compiler path. + +## Co pozostaje platformowe + +| Common | Adapter-required | +|---|---| +| workflow invariants, durable state, gate semantics | manifest, catalog, discovery root | +| portable ESM runtime/helpers | invocation names i commands/skills collapse | +| skill bodies, assets, references | agent schema, tools, trust, concurrency | +| role intent i hook intent | user gate, progress, planning, headless policy | +| neutral MCP server data bez credentials | hook schema/env, MCP placement/security | +| evidence record schema | native marketplace, install scope, session UX | + +Oficjalne kontrakty potwierdzają różne entry points: [Claude plugins reference](https://code.claude.com/docs/en/plugins-reference), [Codex build plugins](https://learn.chatgpt.com/docs/build-plugins), [Cursor plugins](https://cursor.com/changelog/2-5), [Kiro custom agents](https://kiro.dev/docs/cli/custom-agents/configuration-reference/). Są to dowody kontraktu, nie dowody udanego Maister runtime. + +## Kontrakt instalacji + +```text +maister install --target claude|codex|cursor|kiro-cli + [--scope user|project|local] + [--dest PATH] + [--with-mcp NAME] + [--host-version VERSION] + [--offline] +``` + +1. Jawnie wybierz target; autodetection jedynie potwierdza. +2. Zweryfikuj descriptor/schema i compatibility policy. +3. Materializuj do pustego staging directory. +4. Sprawdź manifest, inventory, referencje, paths, permissions, forbidden vocabulary, semantic golden i installed-path canary. +5. Utwórz receipt: source/adapter/contract/host version, options, destination i hashes. +6. Zrób atomic swap managed tree; config mutations wykonaj transakcyjnie. +7. Przy failure przywróć tree, receipt, modes, symlinks i config byte-exact. +8. Update używa tego samego compile; uninstall usuwa wyłącznie managed files z receipt. + +Obecne instalatory Cursor i Kiro czyszczą destination przed copy, więc nie spełniają takiego rollback contract (`analysis/findings/test-assurance-runtime-gap.md:136-148`). + +## Testowanie: co raz, co per host + +### Raz na każdą zmianę core + +- state schema/repository, transactional rejection; +- gate evaluator/policy/denylist; +- continuation/outbox/idempotency/reclaim; +- report projection i portable workflow invariants; +- failure injection. + +### Dla każdego hosta + +- E1 descriptor/adapter contract; +- E2 deterministic materialization + semantic golden + canary; +- E4 isolated install/update/uninstall/rollback; +- E5 prawdziwe discovery + sentinel invocation, gdy binary/auth dostępne; +- E6 wersjonowany krytyczny scenario E2E. + +Rekomendowane targety CI: `test-core` na każdy PR; `test-materializer`, `test-adapter-contract HOST` i `test-install HOST` na każdy PR; `test-host-smoke` nightly/manual; `test-host-e2e` scheduled/release (`analysis/findings/test-assurance-runtime-gap.md:241-250`). + +## Claude Code bez runtime + +W tym badaniu `claude` nie był dostępny. Claude Code oficjalnie oferuje tryb programistyczny `claude -p` i plugin loading ([headless docs](https://code.claude.com/docs/en/headless)), ale sama dokumentacja nie jest runtime proof. + +| Dowód | Aktualnie | Możliwe bez runtime | +|---|---|---| +| E1 static/schema | tak | tak | +| E2 deterministic materialization | canonical n/a / przyszły adapter | tak | +| E3 shared core executable | tak | tak | +| E4 isolated install/rollback | brak dla Claude | **tak, cel** | +| E5 host discovery/smoke | brak | nie | +| E6 scenario runtime | `exit 77 unavailable` | nie | + +Zatem release może jawnie raportować: `Claude host-specific E4; shared-core E3; E5/E6 unavailable`. Nie może raportować „pełna parity Claude”. To ograniczenie jest dobrze zdefiniowanym evidence ceiling, nie blokadą dla całej migracji (`analysis/findings/test-assurance-runtime-gap.md:150-175`). + +## Migracja + +| Etap | Exit criterion | Rollback | +|---|---|---| +| M0 Baseline | `test-core` w PR CI, evidence inventory | powrót do dotychczasowego CI | +| M1 Host Contract v1 | E1 dla 4 targetów, pierwsze typed primitives | emituj legacy text, stare buildy aktywne | +| M2 Shadow materializer | deterministyczna semantic parity z obecnymi outputami | wyłącz shadow job | +| M3 Opt-in installer | E4 dla 4 hostów, byte-exact injected rollback | legacy install path + previous receipt | +| M4 Jedna release path | dwa stabilne release z odtwarzalnymi artifacts | republish legacy artifact | +| M5 Usuń committed variants | offline rebuild, audit diff, E1–E4 stabilne | odtwórz z bundle/tagu | + +## Explicit non-goals + +- Jeden identyczny installed tree. +- Jeden wspólny host runtime. +- Pełna parity bez host-native evidence. +- Regexowe emulowanie brakujących capabilities. +- Pełny DSL/IR jako warunek startu. +- Usunięcie wszystkich testów per platform. + +## Decyzje do konwergencji + +1. Minimalne typed primitives + templates czy pełny IR od początku? **Rekomendacja: minimalne primitives.** +2. CI-prebuilt marketplace artifacts czy compiler zawsze u użytkownika? **Rekomendacja: prebuilt z tego samego materializera.** +3. Kiedy usunąć generated trees? **Rekomendacja: po dwóch stabilnych release z parity oracle.** +4. Co robić z nieznaną wersją hosta? **Rekomendacja: fail dla semantycznych mappings, warning dla packaging-only.** +5. Czy Claude E4 wystarcza jako release gate? **Rekomendacja: tak, przy jawnym E5/E6 unavailable.** + +## Ryzyka i confidence + +- **High confidence:** portable core istnieje; installed outputs muszą być różne; jeden bundle + target materialization jest wykonalny; Claude E5/E6 jest obecnie niezweryfikowane. +- **Medium confidence:** format descriptor/IR, atomic integration z marketplaces, moment usunięcia generated trees. +- **Low/unknown:** pełna runtime parity Claude bez realnego testu. + +Najważniejsze ryzyka to semantic drift w prozie, zmienność host contracts, nietransakcyjny install i mylące zielone statusy dla testów unavailable. Każdy evidence record powinien zawierać host, capability, version, level, status, scenario, timestamp i target. + diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/solution-exploration.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/solution-exploration.md new file mode 100644 index 00000000..b2906a68 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/research-context/solution-exploration.md @@ -0,0 +1,371 @@ +# Eksploracja rozwiązania: platformowo niezależny Maister + +## TL;DR +Najbardziej spójny wariant to jeden portable core i jeden bundle, z małym wersjonowanym Host Contract oraz strukturalnym materializerem. +Instalator powinien domyślnie materializować target lokalnie, a CI ma publikować opcjonalne artefakty marketplace z dokładnie tej samej ścieżki kompilacji. +Commitowane drzewa należy usunąć dopiero po dwóch stabilnych wydaniach z deterministyczną parity, E1–E4 i odtwarzalnym rollbackiem. +Claude Code może być uczciwie wydawany przy E4 bez runtime, o ile E5/E6 pozostają jawnie `unavailable`, a okresowe zewnętrzne probe'y nie blokują zwykłego release. + +## Key Decisions +- **Rekomendacja:** minimalny, ewolucyjny IR: typed primitives + host-aware templates, rozszerzane wyłącznie dla udowodnionych różnic semantycznych. +- **Rekomendacja:** hybrydowa dystrybucja: lokalny materializer jako referencyjna ścieżka oraz CI-prebuilt marketplace artifacts z tego samego wejścia i kompilatora. +- **Rekomendacja:** shadow-first migration i usunięcie generated trees po dwóch stabilnych release oraz spełnieniu jawnej macierzy exit criteria. +- **Rekomendacja:** dwupoziomowa kompatybilność nieznanych wersji: fail-closed dla mapowań semantycznych, ostrzeżenie dla zmian packaging-only potwierdzonych walidacją. +- **Rekomendacja:** Claude release gate E1–E4 + shared E3, z E5/E6 raportowanymi jako `unavailable` i oddzielnym programem okresowych native probes. + +## Open Questions / Risks +- Granica między typed primitive a template może z czasem dryfować; potrzebny jest przegląd każdego nowego wyjątku adaptera. +- Marketplace może wymuszać podpisany lub prebuilt artefakt, więc lokalny materializer nie może być jedynym kanałem dystrybucji. +- Parity tekstowa nie dowodzi parity semantycznej; oracle musi porównywać inventory, descriptor, referencje i canary, nie tylko pełny diff. +- Brak Claude runtime pozostawia twardy evidence ceiling na E4; statusu `unavailable` nie wolno prezentować jako sukcesu. +- Nieznane wersje hostów mogą zmienić semantykę bez zmiany schematu; polityka kompatybilności wymaga wersjonowanego evidence record i daty ważności. + +## 1. Ramy eksploracji + +### Pytania HMW +- Jak moglibyśmy testować całą semantykę workflow raz, zachowując natywne kontrakty czterech hostów? +- Jak moglibyśmy przesunąć rozróżnienie hosta do instalacji bez przenoszenia kruchych transformacji tekstowych na maszynę użytkownika? +- Jak moglibyśmy wydać Claude Code uczciwie, mimo braku runtime, bez blokowania zmian wspólnego core? +- Jak moglibyśmy usunąć 610 commitowanych projekcji, zachowując audytowalność release i prosty rollback? + +### SCAMPER — użyte kierunki +- **Substitute:** zastąpić globalne `sed`/regex typed primitives i host-aware templates. +- **Combine:** połączyć lokalną instalację i prebuilt marketplace artifacts jednym deterministycznym materializerem. +- **Adapt:** wykorzystać obecne fixtures, manifesty i testy jako oracle migracji, zamiast przepisywać je od razu. +- **Modify:** zmniejszyć macierz testów do pełnego E3 raz oraz krótkich E1/E2/E4 per host. +- **Put to another use:** użyć generated trees jako tymczasowych golden fixtures i rollback artifacts. +- **Eliminate:** po okresie shadow usunąć commitowane target trees i czterokrotne uruchamianie identycznych core contracts. +- **Reverse:** zamiast generować wszystko przed release, materializować host-native tree z wersjonowanego bundle przy instalacji; CI wykonuje tę samą operację dla marketplace. + +### Pięć perspektyw oceny + +Każdy wariant oceniono jakościowo z pięciu perspektyw: **maintainer** (prostota i koszt zmian), **installer/user** (niezawodność i offline), **host contract** (natywność i kompatybilność), **assurance/release** (dowód E0–E6 i rollback) oraz **evolution** (dodawanie hostów i zmiany kontraktów). Pewność rekomendacji jest ważona jako wysoka dla granicy core/adapters/materializer i średnia dla dokładnego IR, marketplace oraz polityki wersji. + +## 2. Obszar decyzyjny 1 — głębokość reprezentacji kanonicznej / IR + +Ta decyzja określa, czy wspólne źródło będzie nadal głównie dokumentacją z lepszymi punktami rozszerzeń, czy stanie się pełnym modelem pośrednim. Ma największy wpływ na koszt migracji i ryzyko stworzenia drugiego języka workflow. + +### Alternatywa 1A — minimalne typed primitives + host-aware templates **(REKOMENDOWANA)** + +Behavior pozostaje w obecnych Markdown/YAML i przenośnych modułach ESM, lecz host-sensitive miejsca dostają jawne, walidowane pola: gate, role intent, delegation, progress, hooks, capabilities, invocation i layout. Adapter emituje natywne pliki przez małe strukturalne renderery oraz templates; IR rośnie dopiero, gdy konkretna różnica semantyczna powtórzy się w co najmniej dwóch miejscach. + +**Pros** +- Najmniejsza migracja z obecnego canonical source; zachowuje czytelność dokumentacji-as-code. +- Eliminuje najbardziej ryzykowne globalne substytucje bez projektowania pełnego DSL. +- Pozwala wcześnie uruchomić wspólny core contract i parametryczny adapter harness. +- Dobrze pasuje do zasady minimal implementation oraz istniejącego stosu Markdown/YAML/ESM. + +**Cons** +- Granica primitive/template wymaga dyscypliny i może z czasem stać się niespójna. +- Część prozy nadal pozostaje trudna do walidacji semantycznej. +- Nowa capability może początkowo wymagać kontrolowanego wyjątku adaptera. + +**Dowody / założenia:** pięć modułów runtime jest byte-identical, a wspólna semantyka gate/state/continuation ma E3; największe ryzyko stanowią ponad 20 transformacji tekstowych. Zakładamy, że większość różnic daje się zamknąć w jawnych primitives i templates bez pełnego AST. + +### Alternatywa 1B — pełny neutralny workflow IR od początku + +Wszystkie workflow, role, fazy, gates, artifacts, hooks i invocation są opisane w nowym, wersjonowanym schemacie, z którego renderowane są również ludzkie instrukcje. Markdown staje się projekcją lub polem content w IR, a każdy host implementuje kompletny backend emitera. + +**Pros** +- Najsilniejsza separacja semantyki od reprezentacji hosta. +- Umożliwia bogatą walidację, migracje schematu i narzędzia analityczne. +- Długoterminowo może uprościć dodawanie wielu kolejnych hostów. + +**Cons** +- Wysoki koszt początkowy i ryzyko zbudowania własnego języka workflow. +- Podwójna migracja: najpierw obecnych instrukcji do IR, potem adapterów do nowych emitterów. +- Proza i zachowanie modeli nie zawsze dają się sensownie sprowadzić do AST. +- Opóźnia szybkie usunięcie obecnej duplikacji. + +**Dowody / założenia:** research scorecard ocenił pełny IR na 20/25, lecz z medium confidence i wysokim ryzykiem over-design. Wariant opłaca się dopiero, jeśli typed primitives nie potrafią opisać rosnącej liczby hostów lub potrzebne są formalne transformacje całych workflow. + +### Alternatywa 1C — canonical Markdown + ulepszone regex/golden snapshots + +Zachowujemy obecny model generacji, porządkujemy skrypty transformacji, dodajemy markery sekcji i większe snapshoty/golden fixtures. Nie powstaje osobny Host Contract ani strukturalny model; bezpieczeństwo pochodzi głównie z diffów. + +**Pros** +- Najniższy koszt krótkoterminowy i minimalna zmiana narzędzi. +- Wykorzystuje istniejące skrypty i doświadczenie zespołu. +- Pełne generated diffs są łatwe do ręcznego przeglądu. + +**Cons** +- Nie usuwa podstawowego coupling do tekstu i host vocabulary. +- Snapshoty wykrywają zmianę, lecz nie dowodzą semantycznej poprawności. +- Koszt rośnie z każdym hostem i każdym nowym wyjątkiem. +- Nie realizuje celu jednego instalowanego bundle. + +**Dowody / założenia:** obecny rebuild/diff wykrywa drift, ale PR CI nie uruchamia pełnego `make validate`, a cztery drzewa mają 610 plików. To rozsądny rollback baseline, lecz słaby model docelowy. + +**Rekomendacja:** wybrać **1A**, z jawną zasadą „promote to primitive after repeated semantic divergence” i kwartalnym przeglądem wyjątków adapterów. + +## 3. Obszar decyzyjny 2 — dystrybucja i miejsce materializacji + +Host-native drzewa muszą się różnić, ale nie muszą być niezależnie utrzymywane. Decyzja dotyczy tego, czy tree powstaje na maszynie użytkownika, w CI, czy w obu miejscach z jednego deterministycznego compiler path. + +### Alternatywa 2A — lokalny materializer jako jedyna ścieżka + +Jeden bundle zawiera core, descriptors, schemas, templates i installer; `maister install --target HOST` tworzy staging tree lokalnie, waliduje i atomowo instaluje. Marketplace otrzymuje wyłącznie bootstrap lub nie jest wspierany. + +**Pros** +- Najprostszy model źródłowy i jednoznaczny wybór hosta przy instalacji. +- Działa offline po pobraniu bundle i łatwo zapisuje receipt z dokładnymi opcjami. +- Nie wymaga przechowywania prebuilt target trees w repozytorium. + +**Cons** +- Przenosi compiler i jego zależności do środowiska użytkownika. +- Awaria materializacji staje się awarią instalacji; rollback musi być perfekcyjny. +- Niektóre marketplace wymagają gotowego, podpisanego lub indeksowanego artefaktu. + +**Dowody / założenia:** install-time compiler 1:1 otrzymał 13/25, głównie przez ryzyko przeniesienia kruchych transformacji. Wariant staje się bezpieczniejszy dopiero po zastąpieniu regexów strukturalnym materializerem. + +### Alternatywa 2B — wyłącznie CI-prebuilt artifacts + +CI materializuje i publikuje osobny artefakt dla każdego hosta; użytkownik lub marketplace pobiera już gotowy tree. Repo nie przechowuje generated trees, ale release nadal ma cztery paczki. + +**Pros** +- Minimalne wymagania na maszynie użytkownika i przewidywalne marketplace integration. +- Każdy opublikowany artefakt można podpisać, zahaszować i zachować do audytu. +- Błąd compilera jest wykrywany przed publikacją, nie podczas instalacji. + +**Cons** +- Instalacja spoza marketplace nadal wymaga wyboru i pobrania odpowiedniej paczki. +- Ryzyko rozjazdu między release artifacts i lokalnym developerskim install path. +- Dodanie targetu zwiększa liczbę publikowanych artefaktów i jobs. + +**Dowody / założenia:** native marketplaces mogą wymagać prebuilt artifacts, a obecny release już publikuje platformowe warianty. Sam prebuild nie realizuje w pełni żądania jednego bundle. + +### Alternatywa 2C — hybryda: referencyjny lokalny materializer + prebuild z tego samego path **(REKOMENDOWANA)** + +Jeden wersjonowany bundle i jedna implementacja materializera są źródłem prawdy. Installer uruchamia materializer lokalnie, natomiast CI wywołuje dokładnie ten sam entry point z tym samym bundle, by stworzyć podpisane marketplace artifacts i zapisać receipt/SBOM/hash; parity test porównuje semantyczny output local vs CI. + +**Pros** +- Łączy jedno rozwiązanie i wybór targetu przy instalacji z wymaganiami marketplace. +- Jeden compiler path zapobiega rozjazdowi logiki local/prebuilt. +- Umożliwia offline install, szybki marketplace install i reprodukowalny audit. +- Staging/validation/atomic swap pozostają wspólnym kontraktem E4. + +**Cons** +- Dwa kanały dystrybucji zwiększają liczbę scenariuszy release/install. +- Wymaga deterministycznego build metadata i jednoznacznej polityki preferencji artefaktu. +- Należy pilnować identycznej wersji bundle, descriptor i materializera. + +**Dowody / założenia:** raport rekomenduje jeden bundle i prebuilt artifacts z tego samego compiler path; confidence jest wysokie dla materializera, średnie dla konkretnej integracji marketplace. Zakładamy możliwość publikowania host-specific projections bez ich commitowania. + +**Rekomendacja:** wybrać **2C**. Lokalny materializer jest referencją, a marketplace artifact jest cache'owaną, podpisaną projekcją z identycznym receipt. + +## 4. Obszar decyzyjny 3 — przejście i kryteria usunięcia generated trees + +Dzisiejsze drzewa są jednocześnie kosztem utrzymania, wizualnym diffem i awaryjnym artefaktem dystrybucyjnym. Ich usunięcie powinno być konsekwencją dowiedzionej zastępowalności, nie daty kalendarzowej. + +### Alternatywa 3A — natychmiastowe usunięcie po uruchomieniu materializera + +Gdy nowy compiler potrafi wygenerować cztery targety, commitowane drzewa znikają w tym samym wydaniu. Rollback opiera się na tagu sprzed migracji lub odtworzeniu z bundle. + +**Pros** +- Natychmiast usuwa 610 plików i drift-check overhead. +- Wymusza używanie nowej architektury bez długiego dual path. +- Upraszcza regułę własności repozytorium. + +**Cons** +- Brak czasu na wykrycie semantycznych różnic i problemów marketplace. +- Rollback podczas pierwszych wydań jest trudniejszy operacyjnie. +- Może ukryć regresje, jeśli parity oracle porównuje tylko strukturę. + +**Dowody / założenia:** obecne fixtures i target trees są wartościowym baseline; research jawnie odradza usunięcie przed potwierdzoną parity i stabilnymi release artifacts. + +### Alternatywa 3B — shadow-first, dwa stabilne release i jawne exit criteria **(REKOMENDOWANA)** + +Nowy materializer działa w shadow CI obok legacy build, a generated trees służą jako oracle oraz rollback artifact. Usunięcie następuje po dwóch kolejnych stabilnych release, gdy każdy target ma deterministic E2, adapter E1, isolated transactional E4, installed-path canary E3, reprodukowalny marketplace artifact i zero nierozwiązanych semantic parity exceptions. + +**Pros** +- Najlepszy balans między szybkim uproszczeniem i kontrolowanym ryzykiem. +- Exit criteria są mierzalne i niezależne od dostępności host runtime. +- Umożliwia byte-exact rollback i porównanie dwóch ścieżek. +- Daje czas na walidację lokalnego oraz marketplace install. + +**Cons** +- Przez co najmniej dwa release utrzymujemy dual path i podwójne CI. +- Wymaga semantic parity oracle oraz rejestru zaakceptowanych różnic. +- „Stabilny release” musi mieć precyzyjną definicję i ownera decyzji. + +**Dowody / założenia:** raport proponuje M2 shadow, M3 opt-in, M4 dwa stabilne release, M5 removal. Zakładamy, że dwa release obejmują rzeczywiste instalacje oraz brak rollback-triggering defects, nie tylko zielony pipeline. + +### Alternatywa 3C — pozostawić generated trees jako stale publikowane snapshots + +Materializer staje się główną implementacją, ale wszystkie target trees nadal są commitowane po każdym buildzie jako audytowalne snapshoty. CI wymusza brak diffu tak jak obecnie. + +**Pros** +- Najłatwiejszy ręczny review outputu i szybka inspekcja host-native plików. +- Zachowuje obecną ścieżkę marketplace i rollback. +- Niski koszt zmiany procesu release. + +**Cons** +- Nie usuwa dużej części repozytoryjnej duplikacji ani drift workflow. +- Zachęca do traktowania projekcji jako równorzędnego źródła. +- Skaluje się słabo z liczbą hostów i wersji kontraktów. + +**Dowody / założenia:** obecna architektura działa w ten sposób i daje deterministyczność, ale jest dokładnie źródłem zgłaszanego kosztu generowania/testowania wielu platform. + +**Rekomendacja:** wybrać **3B**. Po usunięciu drzew zachować release artifacts, receipts, semantyczne manifesty i możliwość offline rebuild z tagu. + +## 5. Obszar decyzyjny 4 — polityka nieznanych wersji hosta + +Hosty ewoluują niezależnie i sama zgodność schematu nie gwarantuje zgodności zachowania. Polityka musi unikać zarówno niepotrzebnego blokowania patch releases, jak i cichego uruchamiania niezweryfikowanych mapowań bramek czy delegacji. + +### Alternatywa 4A — zawsze fail-closed poza zadeklarowanym zakresem + +Installer odrzuca każdą wersję hosta spoza `min_version..max_tested_version`, niezależnie od rodzaju użytych capabilities. Użytkownik musi zaktualizować adapter lub jawnie użyć niebezpiecznego override. + +**Pros** +- Najprostsza, audytowalna reguła bezpieczeństwa. +- Nie pozwala pomylić braku dowodu z kompatybilnością. +- Chroni safety-sensitive gates, delegation i continuation. + +**Cons** +- Blokuje prawdopodobnie kompatybilne patch/minor releases. +- Wymaga bardzo szybkich aktualizacji adapterów. +- Zachęca użytkowników do globalnego override, jeśli false positives są częste. + +**Dowody / założenia:** fail-closed jest właściwy na safety boundaries, lecz wersja hosta nie zawsze koreluje ze zmianą używanego kontraktu. + +### Alternatywa 4B — zawsze warning i best-effort install + +Każda nieznana wersja otrzymuje ostrzeżenie, ale materializacja i instalacja postępują po przejściu walidacji strukturalnej. Evidence record zapisuje niezweryfikowaną wersję. + +**Pros** +- Najmniej blokuje użytkowników i nowe wydania hostów. +- Dobrze toleruje zmiany packaging-only oraz backward-compatible additions. +- Prosty UX instalacji. + +**Cons** +- Może dopuścić cichy semantic drift w gate, agent lub hook behavior. +- Static validation nie wykryje zmian runtime/discovery. +- Osłabia wiarygodność deklaracji compatibility. + +**Dowody / założenia:** dokumentacja hostów jest ruchoma, a E1/E2 nie dowodzą E5/E6. Globalny warning jest zbyt słaby dla safety-sensitive mappings. + +### Alternatywa 4C — capability-sensitive policy: semantic fail, packaging warning **(REKOMENDOWANA)** + +Host Contract klasyfikuje mapowania jako `semantic/safety-sensitive` albo `packaging-only` i zapisuje zweryfikowany zakres wersji/capability fingerprint. Nieznana wersja blokuje instalację, jeśli dotyka gates, delegation, continuation, tool trust lub hooks; dla niezmienionego packagingu może przejść z ostrzeżeniem po E1/E2/E4, tworząc `provisional` evidence record i ograniczony czas ważności. + +**Pros** +- Zachowuje fail-closed dokładnie tam, gdzie błąd zmienia bezpieczeństwo lub workflow. +- Nie blokuje bez potrzeby czysto strukturalnych patch releases. +- Łączy wersję z capability/evidence zamiast globalnego booleanu. +- Dostarcza jasny mechanizm aktualizacji confidence po native probe. + +**Cons** +- Wymaga klasyfikacji capabilities i utrzymania fingerprintów. +- Błędna klasyfikacja packaging vs semantic może być źródłem ryzyka. +- UX musi jasno wyjaśnić `supported`, `provisional` i `unavailable`. + +**Dowody / założenia:** obecny boolean capability ukrywa wersję, scenariusz i świeżość; badanie rekomenduje record `{host, capability, version, evidence_level, timestamp, target}`. Zakładamy, że adapter potrafi jawnie oznaczyć safety-sensitive mappings. + +**Rekomendacja:** wybrać **4C**, bez globalnego `--force`; ewentualny override ma być per capability, jawnie audytowany i niedostępny dla denylisted safety invariants. + +## 6. Obszar decyzyjny 5 — release assurance Claude Code bez runtime + +Brak binarki/auth nie uniemożliwia testowania wspólnego core, materializacji i instalacji, ale uniemożliwia dowód discovery oraz runtime. Decyzja dotyczy uczciwego progu wydania, nie sposobu udawania E5/E6. + +### Alternatywa 5A — blokować każdy release bez Claude E5/E6 + +Każde wydanie wieloplatformowe wymaga uruchomienia Claude host discovery i krytycznego scenariusza E2E. Brak runtime zatrzymuje release albo usuwa Claude ze wsparcia. + +**Pros** +- Najsilniejsza deklaracja parity dla każdego wydania. +- Natychmiast wykrywa host-native regressions. +- Nie dopuszcza niezweryfikowanego artefaktu Claude. + +**Cons** +- Obecnie praktycznie blokuje wszystkie release niezależnie od zakresu zmiany. +- Uzależnia wspólny produkt od zewnętrznej binarki, auth i model behavior. +- Nie rozróżnia zmian core, packaging i Claude-specific adapter. + +**Dowody / założenia:** repo nie ma Claude runtime; E5/E6 są nieosiągalne lokalnie, a obecny sentinel zwraca 77. To polityka możliwa dopiero po zapewnieniu stabilnego środowiska native evidence. + +### Alternatywa 5B — E1–E4 jako release gate, jawne unavailable E5/E6 + okresowe native probes **(REKOMENDOWANA)** + +Każdy release wymaga Claude adapter E1, deterministic materialization E2, wspólnego core E3, izolowanego transactional install/update/uninstall E4 i installed-path canary. E5/E6 są zapisywane jako `unavailable`, nigdy `passed`; niezależny scheduled/manual probe na realnym Claude zbiera wersjonowany evidence, a Claude-specific zmiany mogą wymagać takiego probe przed oznaczeniem pełnej kompatybilności. + +**Pros** +- Umożliwia rozwój i release bez fałszywego claimu runtime parity. +- Maksymalizuje testy możliwe bez hosta, w tym brakujący dziś Claude E4. +- Status evidence jest precyzyjny, scenariuszowy i audytowalny. +- Native probe można uruchomić w innym środowisku bez włączania credentials do zwykłego PR CI. + +**Cons** +- Regresja discovery/runtime może dotrzeć do użytkownika między probe'ami. +- Wymaga komunikowania różnych poziomów assurance zamiast jednego zielonego badge. +- Należy określić freshness window i zasady dla Claude-specific changes. + +**Dowody / założenia:** E1–E4 są wykonalne bez runtime; E5/E6 wymagają prawdziwego hosta. `exit 77` ma pozostać jawnym `unavailable`, a nie cichym sukcesem. + +### Alternatywa 5C — community/canary certification przed stable promotion + +CI publikuje Claude artifact jako candidate po E1–E4. Zaufany maintainer lub grupa canary uruchamia podpisany sentinel/discovery i jeden workflow scenario; dopiero ich evidence promuje artifact do stable, podczas gdy inne hosty mogą wydać się wcześniej. + +**Pros** +- Dostarcza realne E5/E6 bez centralnego runtime w projekcie. +- Oddziela publikację candidate od deklaracji stable compatibility. +- Może skalować na hosty wymagające płatnych lub interaktywnych credentials. + +**Cons** +- Złożony, częściowo manualny release i ryzyko opóźnienia Claude artifact. +- Wymaga zaufania, podpisów, provenance i ochrony przed zmanipulowanym reportem. +- Asynchroniczne wersje per host komplikują wsparcie i komunikację. + +**Dowody / założenia:** zewnętrzny probe jest technicznie możliwy, ale projekt nie ma dziś zdefiniowanego trust/provenance modelu. Ten wariant może uzupełnić 5B dla krytycznych wydań, lecz nie powinien być warunkiem startu migracji. + +**Rekomendacja:** wybrać **5B**. Dla zmian wyłącznie core release jest dozwolony przy E1–E4; dla zmian Claude semantic adapter status kompatybilności pozostaje `provisional` aż do świeżego E5/E6. + +## 7. Spójna kombinacja rekomendowana + +Rekomendacje **1A + 2C + 3B + 4C + 5B** tworzą jeden model: + +1. Canonical Markdown/YAML/ESM pozostaje jednym portable behavior core. +2. Minimalny, wersjonowany Host Contract opisuje wyłącznie realne różnice semantyczne i packagingowe. +3. Jeden strukturalny materializer tworzy target w staging; lokalny installer i CI-prebuild używają tego samego entry pointu. +4. PR CI uruchamia pełne E3 raz oraz E1/E2/E4 i installed-path canary dla każdego hosta. +5. Shadow parity wykorzystuje obecne generated trees przez dwa release, po czym projekcje znikają z repo, lecz zostają w release artifacts. +6. Unknown-version policy działa per capability; safety-sensitive semantics są fail-closed. +7. Claude wydaje się uczciwie z E1–E4, a E5/E6 pozostają widocznie `unavailable` do czasu prawdziwego probe. + +Z perspektywy pięciu interesariuszy ten zestaw ma najlepszy bilans: maintainer testuje core raz, użytkownik wybiera host przy instalacji, host zachowuje natywny layout, release ma reprodukowalny evidence chain, a nowe hosty wymagają descriptor/emittera zamiast kopii produktu. + +## 8. Porównanie rekomendacji + +| Obszar | Rekomendowany wariant | Maintainer | Installer/user | Host contract | Assurance | Evolution | Confidence | +|---|---|---|---|---|---|---|---| +| Canonical representation | 1A minimal typed primitives | wysoki | neutralny | wysoki | wysoki | wysoki | medium-high | +| Distribution | 2C hybrid same compiler path | wysoki | wysoki | wysoki | wysoki | wysoki | medium-high | +| Generated-tree removal | 3B two-release shadow | średni krótkoterminowo | wysoki | wysoki | bardzo wysoki | wysoki | medium-high | +| Unknown host versions | 4C capability-sensitive | średni | średni | bardzo wysoki | bardzo wysoki | wysoki | medium | +| Claude assurance | 5B E1–E4 + explicit unavailable | wysoki | uczciwy status | wysoki | wysoki w granicy dowodu | wysoki | high | + +## 9. Pomysły odroczone + +- Pełny neutralny DSL/IR dla wszystkich workflow — odroczyć do czasu, gdy rejestr wyjątków typed primitives pokaże mierzalną potrzebę. +- Zdalny hosted compiler/materialization service — niepotrzebny przy wymaganiu local/offline i zwiększa powierzchnię zaufania. +- Jeden identyczny installed tree dla wszystkich hostów — sprzeczny z natywnymi manifestami, discovery, agents, hooks i MCP placement. +- Automatyczny target detection bez jawnego `--target` — może potwierdzać wybór, ale nie powinien sam decydować przy wielu hostach. +- Globalny compatibility `--force` — zbyt szeroki; ewentualne override musi być per capability i audytowane. +- Community certification jako jedyny release gate — możliwy później jako uzupełnienie programu native probes. + +## Decisions (verbatim handoff) + +- Recommend minimal, evolutionary typed primitives plus host-aware templates instead of a full neutral IR at migration start. +- Recommend a hybrid distribution model in which local installation and CI-prebuilt marketplace artifacts invoke the same deterministic materializer and bundle. +- Recommend removing committed generated trees only after two consecutive stable releases satisfy E1, E2, E4, installed-path E3 canary, reproducible artifact, rollback, and zero unresolved semantic-parity exceptions for every target. +- Recommend capability-sensitive unknown-version handling: fail closed for semantic or safety-sensitive mappings, and allow packaging-only provisional compatibility after validation with explicit warning and expiring evidence. +- Recommend Claude Code releases use E1–E4 plus shared-core E3 as the enforceable gate, while E5/E6 remain explicitly unavailable until a versioned native probe runs. +- Recommend the coherent architecture combination 1A + 2C + 3B + 4C + 5B. + +## Risks (verbatim handoff) + +- The boundary between a typed primitive and a host-aware template can drift and become another implicit transformation layer without an exception-review policy. +- Marketplace packaging or signing constraints may require prebuilt artifacts, so local materialization cannot be the only supported distribution channel. +- Textual parity does not prove semantic parity; the migration oracle must validate inventory, references, descriptors, semantic goldens, and installed-path canaries. +- Two-release shadow operation temporarily increases CI and maintenance cost and needs a precise definition of a stable release. +- Capability classification can be wrong; misclassifying a semantic mapping as packaging-only could permit unsafe provisional compatibility. +- Claude Code E5/E6 remain unverified without a real binary, authentication, version, and executed scenario; unavailable evidence must never be shown as passing. +- External host documentation and marketplaces can change faster than adapter evidence, so compatibility records need version, scenario, timestamp, and freshness policy. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/technical-clarifications.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/technical-clarifications.md new file mode 100644 index 00000000..6928ad16 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/analysis/technical-clarifications.md @@ -0,0 +1,19 @@ +# Technical Clarifications: Platform-independent Maister distribution + +## TL;DR + +The architecture is already decided by the research handoff and Phase 2 gates: one portable common layer, explicit Codex/Cursor/Kiro CLI overlays, and a transactional installer. The remaining technical constraints are encoded as requirements rather than open forks. Native evidence may remain unavailable, but it must never be represented as passing evidence. + +## Resolved technical decisions + +- **Source ownership**: common behavior is maintained once; host-specific behavior is explicit overlay data and native assets. +- **Semantic abstraction**: use minimal typed primitives only at control-flow, safety, persistence, delegation, continuation, and capability boundaries; do not introduce a full DSL. +- **Installation lifecycle**: resolve, stage, validate, snapshot, commit atomically, publish receipt, and recover/rollback through a journal. +- **Settings ownership**: prefer dedicated whole-file ownership; use narrowly allowlisted managed keys for unavoidable shared settings, with drift detection and exact rollback. +- **Compatibility**: fail closed for semantic, safety, persistence, and rollback capabilities; allow provisional status only for packaging-only differences. +- **Evidence**: require E1/E2/E4 for each host plus shared-core E3; record E5/E6 as unavailable when no runtime exists. Evidence expires per capability. +- **Migration exit**: use legacy generated outputs as shadow oracle, require zero unresolved semantic/inventory/reference/hook/permission/topology differences, then delete legacy infrastructure. + +## No unresolved architectural fork + +The host-contract, settings-ownership, native-evidence, evidence-freshness, and documentation-boundary choices were presented as Phase 2 gates and accepted by the user. Specification creation should encode those choices, not reopen them. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/dashboard-data.js b/.maister/tasks/development/2026-07-14-platform-independent-plugin/dashboard-data.js new file mode 100644 index 00000000..2b80360c --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/dashboard-data.js @@ -0,0 +1,68 @@ +window.MAISTER_DATA = { + generated: "2026-07-16T10:33:37Z", + task: { + title: "Implement platform-independent Maister distribution", + type: "development", + status: "completed", + description: "Replace host-specific generation and duplicated testing with one portable source and install-time target selection.", + path: ".maister/tasks/development/2026-07-14-platform-independent-plugin", + current_activity: "Workflow completed; ready for commit and pull-request review" + }, + characteristics: { + has_reproducible_defect: false, + modifies_existing_code: true, + creates_new_entities: true, + involves_data_operations: true, + ui_heavy: false + }, + phases: [ + { id: "phase-1", name: "Analyze codebase & clarify requirements", icon_hint: "analysis", status: "completed", started: "2026-07-14T16:32:58Z", completed: "2026-07-14T16:56:57Z", skip_reason: null, summary: "The repository is a build-time generated architecture: one Claude-oriented source feeds three rewrite-heavy builders and committed projections. Portable ESM runtime and transactional configuration tests are reusable foundations; overlay contracts, target-aware assembly, receipt-backed installation, and rollback are missing. The user confirmed the research-approved Codex/Cursor/Kiro-only scope and required legacy deletion before completion.", decisions: ["Treat the five byte-identical orchestrator runtime modules as the initial portable-core boundary.", "Move host-specific semantic behavior into explicit overlays instead of global prose rewrites.", "Run common behavior tests once and retain host-specific seam/evidence tests.", "Support Codex, Cursor, and Kiro CLI only; remove Claude and committed generated trees before completion."], risks: ["Current installers mutate or clear destinations before transactional validation.", "CI and docs still assume generated trees and four hosts, including Claude.", "Deleting legacy trees before parity could lose behavior hidden in Claude-native files.", "Parity and deletion criteria must be explicit before legacy removal."], artifacts: [{ path: "analysis/codebase-analysis.md", label: "Codebase analysis", html: null }, { path: "analysis/clarifications.md", label: "Phase 1 clarifications", html: null }], gate: { question: "Continue to Phase 2?", answer: "Continue to Phase 2" } }, + { id: "phase-2", name: "Analyze gaps & clarify scope", icon_hint: "analysis", status: "completed", started: "2026-07-14T16:56:57Z", completed: "2026-07-14T17:55:57Z", skip_reason: null, summary: "The repository remains organized around a Claude-oriented source, three rewrite-heavy builders, three committed generated projections, and host-specific installers. The byte-identical runtime modules and existing transactional tests provide reusable foundations, but the common overlay contract, target-aware installer lifecycle, structured evidence model, and final three-host topology are missing. This is a high-risk, high-effort migration because source ownership, installation safety, compatibility policy, CI/release behavior, and documentation change together.", decisions: ["Use minimal typed primitives rather than a full workflow DSL.", "Use one common layer with explicit Codex, Cursor, and Kiro CLI overlays and a custom installer.", "Use legacy generated trees only as a migration shadow oracle, then remove them before task completion.", "Remove Claude Code from supported targets and require a separate future host-integration task for reintroduction.", "Apply capability-sensitive compatibility: semantic boundaries fail closed and packaging-only differences may be provisional.", "Test the portable core once and retain per-host overlay, materialization, installation, and available native evidence tests."], risks: ["Semantic drift in gates, delegation, hooks, progress, and continuation can survive structural parity.", "Partial installation or settings mutation can damage user state without journaled byte-exact recovery.", "Incorrect semantic-versus-packaging classification can permit unsafe provisional compatibility.", "Removing legacy before post-release observation increases the importance of parity and failure-injection gates.", "Stale documentation and CI can continue directing users toward unsupported Claude and generated-tree workflows."], artifacts: [{ path: "analysis/gap-analysis.md", label: "Gap analysis report", html: null }], gate: { type: "routing", id: "phase-2-routing", question: "Continue to Phase 5: Technical Approach, Requirements & Specification?", options: ["Continue to Phase 5: Technical Approach, Requirements & Specification", "Pause workflow"], recommendation: "Continue to Phase 5: Technical Approach, Requirements & Specification", answer: "Continue to Phase 5: Technical Approach, Requirements & Specification", status: "decided" } }, + { id: "phase-3", name: "Write failing test (TDD Red)", icon_hint: "verify", status: "skipped", started: null, completed: "2026-07-14T17:55:57Z", skip_reason: "Skipped by routing: the task is not defect-driven and the workflow routes directly to requirements and specification.", summary: null, decisions: [], risks: [], artifacts: [], gate: null }, + { id: "phase-4", name: "Generate UI mockups", icon_hint: "spec", status: "skipped", started: null, completed: "2026-07-14T17:55:57Z", skip_reason: "Skipped by routing: gap analysis found no UI-heavy scope.", summary: null, decisions: [], risks: [], artifacts: [], gate: null }, + { id: "phase-5", name: "Gather requirements & create specification", icon_hint: "spec", status: "completed", started: "2026-07-14T17:55:57Z", completed: "2026-07-14T18:19:59Z", skip_reason: null, summary: "The specification defines a portable common source, explicit Codex/Cursor/Kiro CLI overlays, and a shared target-aware installer with immutable provenance, staged validation, journaled receipts, hybrid settings ownership, capability-sensitive evidence, rollback, and legacy deletion criteria. It also aligns core-once/per-host testing and all documentation, standards, CI, and release paths with the new topology.", decisions: ["Use a portable common layer plus explicit host overlays because native layouts remain host-specific while behavior should be owned once.", "Treat the installer as a transaction manager because user state and settings require staged validation, receipts, recovery, and rollback.", "Use capability-sensitive compatibility because semantic boundaries must fail closed while packaging-only differences can be provisional.", "Delete Claude and generated trees only after zero-unresolved-difference shadow parity and failure-injection evidence."], risks: ["Native E5/E6 evidence may remain unavailable for Cursor and Kiro.", "Shared settings and shell files can be damaged without journaled ownership and exact rollback.", "Textual parity can conceal semantic drift in gates, delegation, hooks, and continuation.", "Legacy deletion removes the current rollback oracle and depends on complete parity evidence."], artifacts: [{ path: "analysis/requirements.md", label: "Requirements", html: null }, { path: "analysis/technical-clarifications.md", label: "Technical clarifications", html: null }, { path: "implementation/spec.md", label: "Specification", html: "implementation/spec.html" }], gate: { type: "phase-exit", id: "phase-5-exit", question: "Continue to specification audit?", options: ["Continue to specification audit", "Pause workflow"], recommendation: "Continue to specification audit", answer: "Continue to specification audit", status: "decided" } }, + { id: "phase-6", name: "Audit specification", icon_hint: "verify", status: "completed", started: "2026-07-14T18:19:59Z", completed: "2026-07-14T18:36:21Z", skip_reason: null, summary: "The specification is Mostly Compliant as a pre-implementation contract: all 17 requirements map to the research decisions, current-state gaps, and migration exit criteria. There are no critical or high-severity specification defects; two medium clarifications remain around the exact installer/receipt contract and the field-level overlay schema.", decisions: ["Treat current legacy implementation gaps as expected pre-implementation state because the specification explicitly covers migration and deletion criteria.", "Freeze exact installer/receipt and overlay schema contracts in the implementation plan before implementation approval."], risks: ["Native E5/E6 evidence may remain unavailable for Cursor and Kiro.", "Shared settings and shell files require exact journaled rollback.", "Textual parity can conceal semantic drift."], artifacts: [{ path: "verification/spec-audit.md", label: "Specification audit", html: null }], gate: { type: "phase-exit", id: "phase-6-exit", question: "Continue to implementation planning?", options: ["Continue to implementation planning", "Pause workflow"], recommendation: "Continue to implementation planning", answer: "Continue to implementation planning", status: "decided" } }, + { id: "phase-7", name: "Plan implementation", icon_hint: "plan", status: "completed", started: "2026-07-14T18:36:21Z", completed: "2026-07-14T18:54:09Z", skip_reason: null, summary: "The plan organizes the migration into four serialized implementation groups plus a focused test-review group. It freezes overlay v1 and the installer CLI/error/receipt/journal contracts, preserves legacy outputs until parity and failure-injection evidence pass, and caps the feature suite at 34 tests.", decisions: ["Keep plugins/maister as the single common source and represent host differences in strict versioned overlays.", "Serialize overlay, materializer, installer, and legacy-removal groups because each freezes an interface consumed by the next.", "Use one Node ESM lifecycle command with stable machine-readable errors, receipt v1, and journal v1.", "Delete Claude support, old builders, and generated trees only after zero-unresolved parity and exact recovery evidence."], risks: ["Cursor and Kiro E5/E6 may remain unavailable and must never be promoted to passed.", "Shared settings require journaled multi-file recovery in addition to atomic managed-tree replacement.", "A real immutable GitHub smoke probe depends on release-environment network availability.", "No performance threshold is introduced in this migration."], artifacts: [{ path: "implementation/implementation-plan.md", label: "Implementation plan", html: "implementation/implementation-plan.html" }], gate: { type: "phase-exit", id: "phase-7-exit", question: "Continue to implementation approval?", options: ["Continue to implementation approval", "Pause workflow"], recommendation: "Continue to implementation approval", answer: "Continue to implementation approval", status: "decided" } }, + { id: "phase-8", name: "Execute implementation", icon_hint: "code", status: "completed", started: "2026-07-14T19:08:52Z", completed: "2026-07-14T22:12:26Z", skip_reason: null, summary: "All five approved groups are complete. The feature suite passes 34/34, all targets materialize, parity has zero unresolved differences, and final topology is clean.", decisions: [], risks: [], artifacts: [], gate: { question: "Continue to verification?", answer: "Continue to verification" } }, + { id: "phase-9", name: "Verify test passes (TDD Green)", icon_hint: "verify", status: "skipped", started: null, completed: "2026-07-15T12:40:53Z", skip_reason: "Phase 3 TDD Red was not executed because the task was not defect-driven.", summary: null, decisions: [], risks: [], artifacts: [], gate: null }, + { id: "phase-10", name: "Prompt verification options", icon_hint: "verify", status: "completed", started: "2026-07-15T12:40:53Z", completed: "2026-07-15T12:47:27Z", skip_reason: null, summary: "All four standard verification tracks and user documentation are enabled; E2E browser verification is skipped.", decisions: [], risks: [], artifacts: [], gate: { question: "Generate user documentation?", answer: "Yes (Recommended)" } }, + { id: "phase-11", name: "Verify implementation & resolve issues", icon_hint: "verify", status: "completed", started: "2026-07-15T18:46:53Z", completed: "2026-07-15T22:30:35Z", skip_reason: null, summary: "Final verification passes all 39 plan steps and 17 requirements with 114/114 authoritative tests, 20/20 focused evidence/topology checks, make validate, package lifecycle 4/4, and clean strict parity for all three targets with zero unresolved differences. Both former P1s, stale test contracts, and the topology contract issue are resolved with zero regressions.", decisions: ["Carry one immutable source binding through overlay selection, materialization, evidence, and receipts.", "Keep supported-target ownership in the central Node registry.", "Use tracked plus non-ignored untracked Git candidates for repository topology while retaining raw fixture traversal.", "Separate the passed implementation verdict from exact-tag publication controls."], risks: ["The exact tag commit must repeat the complete clean release sequence before publication.", "Native E6 remains unavailable where no reviewed host scenario exists.", "Unsigned provenance and cooperative-writer limits remain documented release boundaries."], artifacts: [{ path: "verification/implementation-verification.md", label: "Implementation verification", html: "verification/implementation-verification.html" }, { path: "verification/test-suite-results.md", label: "Test suite results", html: null }, { path: "verification/code-review-report.md", label: "Code review", html: null }, { path: "verification/production-readiness-report.md", label: "Production readiness", html: null }, { path: "verification/reality-check.md", label: "Reality assessment", html: null }], gate: { question: "Continue to Phase 12?", answer: "Continue to Phase 12" } }, + { id: "phase-12", name: "Run E2E tests", icon_hint: "verify", status: "skipped", started: null, completed: "2026-07-16T08:13:13Z", skip_reason: "E2E verification disabled by the selected Phase 10 verification options.", summary: "No browser verifier was dispatched because e2e_enabled is false.", decisions: ["Honor the configured E2E skip and preserve Phase 13 documentation as enabled."], risks: [], artifacts: [], gate: { question: "E2E complete. Continue to Phase 13?", answer: "Continue to Phase 13" } }, + { id: "phase-13", name: "Generate user documentation", icon_hint: "docs", status: "completed", started: "2026-07-16T08:30:49Z", completed: "2026-07-16T08:40:06Z", skip_reason: null, summary: "The CLI-focused user guide covers all supported targets and lifecycle commands, source forms, safety boundaries, result codes, evidence limitations, and troubleshooting. Eight command shapes, all links, all anchors, Markdown structure, and diff hygiene pass.", decisions: ["Omit screenshots because the product is CLI-only and Phase 12 was skipped.", "Treat copy-paste CLI commands as user actions rather than developer code.", "Validate every documented command and flag against the live parser and implementation."], risks: ["Native E5/E6 evidence remains unavailable where no reviewed host scenario exists."], artifacts: [{ path: "documentation/user-guide.md", label: "User guide", html: null }], gate: { question: "Documentation complete. Continue to Phase 14?", answer: "Continue to Phase 14" } }, + { id: "phase-14", name: "Finalize workflow", icon_hint: "done", status: "completed", started: "2026-07-16T09:17:19Z", completed: "2026-07-16T10:33:37Z", skip_reason: null, summary: "The canonical 31-record decision ledger and self-contained HTML companion are complete. The user approved the protected final handoff and the workflow completion checkpoint is durable.", decisions: ["Generate final summaries only from canonical gate history.", "Preserve every decision option, rationale, confidence, model/retry/arbitration field, override, and idempotency key.", "Require and persist protected final-handoff approval before task completion."], risks: ["Production publication remains conditional on the exact clean tag workflow."], artifacts: [{ path: "outputs/decision-summary.md", label: "Decision summary", html: "outputs/decision-summary.html" }], gate: { question: "Complete workflow or keep it open?", answer: "Complete workflow" } } + ], + verification: { status: "passed", issues: [], fixes: ["Phase 11 fix iteration 1 completed; 60/60 focused tests pass", "Phase 11 fix iteration 2 completed; 91/91 suite and release checks pass", "Phase 11 fix iteration 3 completed; 109/109 suite, make validate, package lifecycle, and diagnostic parity pass", "Iteration 3 independently resolved or downgraded persisted-state reads, final-byte mutation checks, overlay fallback, direct E3, parser grammar, and validated release inputs", "Resumed iteration 1 carries one immutable source binding through lifecycle and materialization and rejects A/B mismatch before state mutation", "Resumed iteration 1 removes Make target interpolation and rejects SUPPORTED_TARGETS overrides before evaluation", "Resumed iteration 2 updates the topology contract for Node registry ownership", "Resumed iteration 2 supplies immutable Git identity to the overlay-negative fixture", "Resumed iteration 3 centralizes Git-aware repository topology and passes 114/114 tests plus clean strict parity 3/3"], reverify_count: 3 }, + gate_history: [ + { phase_id: "phase-1", gate_type: "phase-1-clarification", question: "I assume the implementation scope is Codex, Cursor, and Kiro CLI only, with Claude and committed generated trees removed before completion. Is that correct?", answer: "Confirm assumptions" }, + { phase_id: "phase-1", gate_type: "phase-1-exit", question: "Continue to Phase 2?", answer: "Continue to Phase 2" }, + { phase_id: "phase-2", gate_type: "phase-2-decision-host-contract-closure", question: "Which host-contract closure policy should the implementation adopt?", answer: "Contract-first overlay v1 with E1/E2/E4 for every host and E5/E6 when runtime exists" }, + { phase_id: "phase-2", gate_type: "phase-2-decision-settings-ownership", question: "Which settings and shell-configuration ownership contract should the implementation adopt?", answer: "Hybrid whole_file and managed_keys ownership with journal, backup, drift detection, and exact rollback" }, + { phase_id: "phase-2", gate_type: "phase-2-decision-native-evidence-policy", question: "Which minimum release-evidence policy should apply to hosts without native runtime?", answer: "Require E1-E4 and shared-core E3; record E5/E6 as unavailable, never pass" }, + { phase_id: "phase-2", gate_type: "phase-2-decision-evidence-freshness", question: "Which evidence freshness policy should the implementation adopt?", answer: "Per-capability expiry with host, version, scenario, and timestamp renewal" }, + { phase_id: "phase-2", gate_type: "phase-2-decision-documentation-boundary", question: "Which documentation and release migration boundary should the implementation adopt?", answer: "Update all affected documentation, standards, Make/CI/release paths, and support matrices in this task" }, + { phase_id: "phase-2", gate_type: "phase-2-routing", question: "Continue to Phase 5: Technical Approach, Requirements & Specification?", answer: "Continue to Phase 5: Technical Approach, Requirements & Specification" }, + { phase_id: "phase-5", gate_type: "phase-5-exit", question: "Continue to specification audit?", answer: "Continue to specification audit" }, + { phase_id: "phase-6", gate_type: "phase-6-exit", question: "Continue to implementation planning?", answer: "Continue to implementation planning" }, + { phase_id: "phase-7", gate_type: "phase-7-exit", question: "Continue to implementation approval?", answer: "Continue to implementation approval" }, + { phase_id: "phase-7", gate_type: "implementation-approval", question: "Approve this complete implementation scope?", answer: "Approve complete implementation scope" }, + { phase_id: "phase-8", gate_type: "group-failure-recovery", question: "Group 4 implementation failed: materialization parity gate is red for Codex, Cursor, and Kiro CLI inventory/vocabulary contracts. How to proceed?", answer: "Try suggested fix" }, + { phase_id: "phase-8", gate_type: "group-failure-recovery", question: "Group 4 implementation failed: materialization is green but real shadow parity still has 573 unresolved differences across Codex, Cursor, and Kiro CLI. How to proceed?", answer: "Try suggested fix" }, + { phase_id: "phase-8", gate_type: "group-failure-recovery", question: "Group 1 implementation failed: delegated agent timed out without a report. How to proceed?", answer: "Try suggested fix" } + ,{ phase_id: "phase-8", gate_type: "phase-8-exit", question: "Continue to verification?", answer: "Continue to verification" } + ,{ phase_id: "phase-10", gate_type: "verification-options", question: "Which standard verifications to run?", answer: "All recommended standard verifications" } + ,{ phase_id: "phase-10", gate_type: "optional-phase-selection/e2e", question: "Enable E2E browser verification?", answer: "No, skip" } + ,{ phase_id: "phase-10", gate_type: "optional-phase-selection/user-docs", question: "Generate user documentation?", answer: "Yes (Recommended)" } + ,{ phase_id: "phase-11", gate_type: "verification-fix-selection", question: "Which issues should I fix?", answer: "Fix all fixable issues" } + ,{ phase_id: "phase-11", gate_type: "verification-rerun", question: "Re-run verification to check fixes?", answer: "Yes, re-run verification" } + ,{ phase_id: "phase-11", gate_type: "verification-fix-selection", question: "Which issues should I fix?", answer: "Fix all fixable issues" } + ,{ phase_id: "phase-11", gate_type: "verification-rerun", question: "Re-run verification to check fixes?", answer: "Yes, re-run verification" } + ,{ phase_id: "phase-11", gate_type: "verification-rerun", question: "Re-run verification to check fixes?", answer: "Yes, re-run verification" } + ,{ phase_id: "phase-11", gate_type: "verification-fix-selection", question: "Which issues should I fix?", answer: "Fix all fixable issues" } + ,{ phase_id: "phase-11", gate_type: "unresolved-critical", question: "Proceed with known issues?", answer: "Stop workflow" } + ,{ phase_id: "phase-11", gate_type: "verification-fix-selection", question: "Which issues should I fix?", answer: "Fix all fixable issues" } + ,{ phase_id: "phase-11", gate_type: "phase-11-exit", question: "Continue to Phase 12?", answer: "Continue to Phase 12" } + ,{ phase_id: "phase-12", gate_type: "phase-12-exit", question: "E2E complete. Continue to Phase 13?", answer: "Continue to Phase 13" } + ,{ phase_id: "phase-13", gate_type: "phase-13-exit", question: "Documentation complete. Continue to Phase 14?", answer: "Continue to Phase 14" } + ,{ phase_id: "phase-14", gate_type: "final-handoff-approval", question: "Complete workflow or keep it open?", answer: "Complete workflow" } + ] +}; diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/dashboard.html b/.maister/tasks/development/2026-07-14-platform-independent-plugin/dashboard.html new file mode 100644 index 00000000..9f5ea812 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/dashboard.html @@ -0,0 +1,629 @@ + + + + + +Maister Workflow Dashboard + + + + +
+
+ Waiting for dashboard-data.js… If this persists, the workflow has not written data yet. +
+
+ + + + diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/documentation/user-guide.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/documentation/user-guide.md new file mode 100644 index 00000000..2ccce493 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/documentation/user-guide.md @@ -0,0 +1,519 @@ +# Install and manage Maister on Codex, Cursor, or Kiro CLI + +**Last updated:** 2026-07-16 +**Applies to:** Maister 2.2.1 platform-independent distribution + +## TL;DR + +Maister uses one installer for three targets: Codex, Cursor, and Kiro CLI. You +choose the target with `--target`, install from a clean local source or an +immutable GitHub commit, and use the same command for updates, checks, +uninstall, rollback, and recovery. + +The examples in this guide are complete terminal actions. This is a CLI-only +feature with no web interface, so screenshots are not applicable and this +guide intentionally contains no image references. + +## Key decisions + +- Use `codex`, `cursor`, or `kiro-cli` exactly as the target name. +- Prefer a full 40-character Git commit for every install and update. +- Keep the target home and its Maister state directory private and backed up. +- Stop the host and other programs that may write its settings before a + lifecycle command. +- Treat `provisional` compatibility and `unavailable` native evidence as + limitations, not as successful native verification. + +## Open questions and risks + +- Native E5/E6 checks can remain unavailable when the selected host, login, or + safe native test scenario is missing. +- The installer coordinates other Maister installer processes, but it cannot + stop an editor, sync tool, backup tool, or another process from changing the + same files. +- An unsigned checksum or provenance file proves integrity only when you got it + through a trusted release channel. + +## Contents + +- [What Maister installs](#what-maister-installs) +- [Before you start](#before-you-start) +- [Choose a target](#choose-a-target) +- [Set up your terminal](#set-up-your-terminal) +- [Install from a clean local source](#install-from-a-clean-local-source) +- [Install from an immutable GitHub source](#install-from-an-immutable-github-source) +- [Check status and verify the installation](#check-status-and-verify-the-installation) +- [Update Maister](#update-maister) +- [Uninstall Maister](#uninstall-maister) +- [Roll back to the previous receipt](#roll-back-to-the-previous-receipt) +- [Recover an interrupted transaction](#recover-an-interrupted-transaction) +- [Protect your home and state](#protect-your-home-and-state) +- [Understand results and exit codes](#understand-results-and-exit-codes) +- [Understand compatibility evidence](#understand-compatibility-evidence) +- [Troubleshooting](#troubleshooting) + +## What Maister installs + +Maister combines one common source with the overlay for your selected host. It +stages and validates the result before changing the target directory. + +| Target | Use with `--target` | Default installed location | +| --- | --- | --- | +| Codex | `codex` | `$HOME/.codex/plugins/local/maister` | +| Cursor | `cursor` | `$HOME/.cursor/plugins/local/maister` | +| Kiro CLI | `kiro-cli` | `$HOME/.kiro-maister` | + +Claude and the old generated or marketplace layouts are not supported targets. + +The installer records which files and settings it owns. Receipt-listed files +and explicitly managed settings keys are Maister-owned. Other files and +settings remain yours. + +## Before you start + +You will need: + +- Node.js 22, which is the version used by the project's validation jobs. +- Git on your `PATH` for a local Git checkout or GitHub source. +- The selected host: Codex, Cursor, or Kiro CLI. +- A trusted Maister installer or extracted Maister package. +- For `install` and `update`, a current, passed E3 portable-core attestation + that matches the exact source commit and source bytes. A self-contained + release archive can include this record; otherwise, use `--attestation`. +- Write access to your chosen home and state directories. + +⚠️ Do not run the installer with `sudo` into another user's home. Do not use +the filesystem root as `--home`; the installer rejects it. + +Before any command that changes files, close the selected host and pause any +editor, sync, backup, or automation process that may write the target or shared +settings. + +The commands below use POSIX shell syntax for macOS and Linux. Replace the +example paths with real absolute paths on your computer. + +## Choose a target + +Pick one of these exact values: + +```sh +export MAISTER_TARGET="codex" +``` + +Use `cursor` or `kiro-cli` instead when installing for those hosts. Each target +has separate installed files, receipts, journals, backups, and a lock. + +## Set up your terminal + +Point the commands at the trusted installer you obtained and the home where the +host stores its configuration: + +```sh +export MAISTER_INSTALLER_ROOT="/path/to/maister" +export MAISTER_INSTALLER="$MAISTER_INSTALLER_ROOT/plugins/maister/bin/maister-install.mjs" +export MAISTER_HOME="$HOME" +export MAISTER_TARGET="codex" +export MAISTER_ATTESTATION="/path/to/e3-portable-core.json" + +test -f "$MAISTER_INSTALLER" +node --version +git --version +``` + +✅ The first command should be silent, and the version commands should print +the installed Node.js and Git versions. + +If you use a custom state location, set it before the first command and keep +the same value for every later command: + +```sh +export XDG_STATE_HOME="$HOME/.local/state" +``` + +## Install from a clean local source + +Use this flow for a clean Git checkout. The source must be the checkout root, +its checked-out `HEAD` must match the selected commit, and it must have no +changed, untracked, or ignored inputs. + +```sh +export MAISTER_SOURCE="/path/to/clean/maister-checkout" +export MAISTER_REF="$(git -C "$MAISTER_SOURCE" rev-parse HEAD)" + +test "$MAISTER_SOURCE" = "$(git -C "$MAISTER_SOURCE" rev-parse --show-toplevel)" +test -z "$(git -C "$MAISTER_SOURCE" status --porcelain=v1 --untracked-files=all --ignored=matching --no-renames)" + +node "$MAISTER_INSTALLER" install \ + --target "$MAISTER_TARGET" \ + --source "local:$MAISTER_SOURCE" \ + --ref "$MAISTER_REF" \ + --attestation "$MAISTER_ATTESTATION" \ + --home "$MAISTER_HOME" \ + --json +``` + +✅ A successful result has `"ok":true`, `"code":0`, and a non-null +`receipt_path`. Keep that receipt path for audit and support. + +### Install from a self-contained archive + +An approved extracted release archive has a `.maister-source.json` manifest and +can contain its matching E3 attestation. Point both the installer and source at +the extracted root: + +```sh +export MAISTER_SOURCE="/path/to/extracted/maister-package" +export MAISTER_INSTALLER="$MAISTER_SOURCE/plugins/maister/bin/maister-install.mjs" +export MAISTER_REF="$(node --input-type=module -e 'import fs from "node:fs"; console.log(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).source_commit)' "$MAISTER_SOURCE/plugins/maister/.maister-source.json")" + +node "$MAISTER_INSTALLER" install \ + --target "$MAISTER_TARGET" \ + --source "local:$MAISTER_SOURCE" \ + --ref "$MAISTER_REF" \ + --home "$MAISTER_HOME" \ + --json +``` + +The installer automatically looks for an embedded E3 record in recognized +package locations. If your approved archive stores the matching attestation +separately, add `--attestation "$MAISTER_ATTESTATION"`. + +## Install from an immutable GitHub source + +Use a full 40-character commit whenever possible. The installer resolves the +ref, creates a temporary detached checkout, checks its identity and contents, +uses the overlay from that same checkout, and removes the temporary checkout +after the transaction. + +```sh +export MAISTER_GITHUB_SOURCE="github:SkillPanel/maister" +export MAISTER_REF="0123456789012345678901234567890123456789" + +node "$MAISTER_INSTALLER" install \ + --target "$MAISTER_TARGET" \ + --source "$MAISTER_GITHUB_SOURCE" \ + --ref "$MAISTER_REF" \ + --attestation "$MAISTER_ATTESTATION" \ + --home "$MAISTER_HOME" \ + --json +``` + +Replace the example commit with the full commit that matches your attestation. +A safe branch or tag is accepted, but it is resolved to a full commit and that +commit is written to the receipt. Short commit IDs are rejected. + +Git operations time out after 30 seconds by default. If your connection needs +longer, set a whole number of milliseconds from 1 through 600000: + +```sh +export MAISTER_GIT_TIMEOUT_MS="120000" +``` + +## Check status and verify the installation + +### Check status + +`status` reads the current receipt. It does not change installed files. + +```sh +node "$MAISTER_INSTALLER" status \ + --target "$MAISTER_TARGET" \ + --home "$MAISTER_HOME" \ + --json +``` + +✅ An active installation has `"ok":true`, `"code":0`, and a non-null +`receipt_path`. If no active receipt exists, the command still completes but +returns `receipt_path:null`. + +### Verify files and managed settings + +`verify` checks receipt-listed files and the settings owned by Maister. Use the +same trusted installer package you used for the lifecycle operation. + +```sh +node "$MAISTER_INSTALLER" verify \ + --target "$MAISTER_TARGET" \ + --home "$MAISTER_HOME" \ + --json +``` + +✅ For an installed target, success is `"ok":true`, `"code":0`, and a +non-null `receipt_path`. Like `status`, `verify` returns a successful empty +result when there is no active receipt, so check the receipt path. + +Verification checks installed integrity and drift. It does not turn unavailable +host-native E5/E6 evidence into a pass. + +## Update Maister + +An update needs a source and a matching, current E3 attestation, just like the +first install. It refuses unexpected changes to managed files or settings. + +For a clean local source: + +```sh +export MAISTER_REF="$(git -C "$MAISTER_SOURCE" rev-parse HEAD)" + +node "$MAISTER_INSTALLER" update \ + --target "$MAISTER_TARGET" \ + --source "local:$MAISTER_SOURCE" \ + --ref "$MAISTER_REF" \ + --attestation "$MAISTER_ATTESTATION" \ + --home "$MAISTER_HOME" \ + --json +``` + +For GitHub, use the same command with `--source "$MAISTER_GITHUB_SOURCE"` and +set `MAISTER_REF` to the new full commit. Supply the E3 attestation created for +that exact commit and portable-core content. + +If you are updating from a self-contained archive that embeds its matching E3 +record, omit `--attestation` and use its extracted root as `MAISTER_SOURCE` and +`MAISTER_INSTALLER`. + +✅ A successful update publishes a new receipt. Run `verify` immediately and +retain both the new and previous receipts so rollback remains auditable. + +## Uninstall Maister + +Uninstall removes only the managed inventory and managed settings recorded by +the active receipt. It refuses unsafe drift rather than overwriting a change it +does not understand. + +```sh +node "$MAISTER_INSTALLER" uninstall \ + --target "$MAISTER_TARGET" \ + --home "$MAISTER_HOME" \ + --json +``` + +✅ A successful uninstall returns code 0 and publishes an `uninstalled` +receipt. Unlisted files and unmanaged settings are preserved. + +Do not delete the state directory after uninstall if you may need its audit +history, backups, or rollback information. + +## Roll back to the previous receipt + +Rollback restores the immediately previous receipt and its exact backed-up +state. It is useful after an update or an uninstall when the current receipt +points to a prior transaction. + +1. Stop the host and every other writer. +2. Preserve a copy of the target's Maister state directory. +3. Run: + +```sh +node "$MAISTER_INSTALLER" rollback \ + --target "$MAISTER_TARGET" \ + --home "$MAISTER_HOME" \ + --json +``` + +4. Run `verify` and confirm the returned `receipt_path` is the receipt you + expected. + +Rollback returns code 7 when no previous receipt is available or exact restore +cannot be completed. Do not repeatedly retry a failed rollback. Preserve its +journal and backups, correct the reported permission, missing-backup, or drift +problem, and follow the recovery steps. + +## Recover an interrupted transaction + +`recover` selects the newest unresolved journal for the target and restores +from its recorded backup. If no unresolved journal exists, it returns the +current active receipt without changing it. + +1. Confirm the failed installer process and every external writer have stopped. +2. Preserve the complete target state directory. +3. Make sure its `journals/` and `backups/` entries are readable. +4. Run: + +```sh +node "$MAISTER_INSTALLER" recover \ + --target "$MAISTER_TARGET" \ + --home "$MAISTER_HOME" \ + --json +``` + +5. Inspect `journal_path` and `receipt_path` in the response. +6. Run `verify` with the same trusted installer before another install or + update. + +⚠️ If recovery returns code 7, stop. Do not delete the lock, journal, receipt, +or backup, and do not claim the installation is restored. Copy the state +directory for diagnosis and correct the underlying filesystem problem first. + +## Protect your home and state + +By default, state is stored separately from installed plugin files: + +```text +$XDG_STATE_HOME/maister// +``` + +When `XDG_STATE_HOME` is unset, it defaults below the selected `--home`: + +```text +$MAISTER_HOME/.local/state/maister// +``` + +Each target state directory contains: + +```text +active-receipt.json +receipts/ +journals/ +backups/ +staging/ +install.lock +``` + +Follow these safety rules: + +- Keep state directories at mode `0700` and receipt, journal, backup metadata, + settings snapshots, and lock files at mode `0600`. +- Use the same `--home` and `XDG_STATE_HOME` values for every command. Changing + either selects different target or state paths. +- Never hand-edit receipts, journals, backups, or the active receipt pointer. +- Never remove `install.lock` while its owning process may still be running. +- Back up the whole target state directory before manual recovery work. +- Treat files listed in a receipt and its managed settings keys as + Maister-owned. Make changes through an update rather than editing them during + a lifecycle operation. +- Stop the host, editor, shell automation, and sync tools before install, + update, uninstall, rollback, or recovery. + +The lock prevents two cooperating Maister lifecycle processes from changing +the same target and state root at once. It cannot lock unrelated programs or +protect against a malicious process running as the same user or as an +administrator. + +## Understand results and exit codes + +The commands in this guide return a JSON object. Important fields are: + +- `ok`: `true` only when the command exited successfully. +- `code`: the same number used as the process exit status. +- `message`: a short result or error description. +- `error.kind`: the specific error category when `ok` is false. +- `error.details`: paths, conflicts, or other details needed to fix the issue. +- `receipt_path`: the active or newly published receipt, when available. +- `journal_path`: the transaction journal, when available. +- `evidence`: the evidence copied from the receipt. + +| Code | Meaning | What to do | +| ---: | --- | --- | +| 0 | Success | Check the receipt path, provenance, compatibility, and evidence. | +| 2 | Command usage or settings format | Correct the command, target, option, path, or settings format. Do not retry unchanged. | +| 3 | Source or Git resolution | Use a clean source, full commit, safe ref, and matching checkout. | +| 4 | Overlay, materialization, settings, provenance, or evidence validation | Use a valid source/overlay and the E3 attestation that matches it. | +| 5 | Managed file or settings drift | Review the reported conflict. Preserve your change and reconcile it before retrying. | +| 6 | Target lock busy | Confirm whether another installer is running. Retry only after it exits. | +| 7 | Transaction, rollback, or recovery failure | Stop, preserve state and journals, and follow the recovery procedure. | +| 8 | Integrity verification failure | Do not continue. Preserve the receipt and journal and investigate the changed files. | + +All unknown options are rejected. `--evidence` and `--attestation` are aliases +for the E3 attestation path, but you may supply only one. They are accepted only +for `install` and `update`. + +`--failure-point` is a test-only option. It is rejected unless failure +injection is explicitly enabled and must not be used in normal operation. + +## Understand compatibility evidence + +Every installation receipt records evidence by capability: + +- **E1:** source, schema, and overlay validation. +- **E2:** deterministic materialization, inventory, paths, syntax, and modes. +- **E3:** shared portable-core behavior. Install and update require a current, + passed E3 attestation bound to the source commit and portable-core hash. +- **E4:** installer transaction, receipt, settings ownership, drift, recovery, + and rollback behavior. +- **E5:** host-native discovery and integration. +- **E6:** a host-native runtime scenario. + +`passed`, `failed`, and `unavailable` have different meanings. E5 or E6 can be +`unavailable` because the host executable, authentication, safe probe, or +configured scenario is missing. Unavailable never means passed. + +The normal offline policy can report the installation as `provisional` when +the structural and transactional evidence passes but native evidence is not +available. This can be enough to assemble and install the package, but it does +not certify native host discovery or runtime behavior. Re-run an approved +native probe when its prerequisite becomes available or the evidence expires. + +## Troubleshooting + +### The command says an E3 attestation is missing, stale, failed, or does not match + +Use the attestation supplied for the exact source commit and source bytes. Do +not reuse one from another commit, edit it, or substitute a native E5/E6 record. +For an approved self-contained archive, confirm that exactly one recognized E3 +record exists inside it or pass the matching file with `--attestation`. + +### The local source is reported as dirty + +Run: + +```sh +git -C "$MAISTER_SOURCE" status --porcelain=v1 --untracked-files=all --ignored=matching --no-renames +``` + +Commit, move, or remove every reported changed, untracked, or ignored input, +then retry from the clean checkout. `MAISTER_ALLOW_DIRTY_LOCAL=1` exists only +for deliberate development experiments; it is not production provenance and +must not be used for a release or support reproduction. + +### A GitHub ref is rejected + +Use a full lowercase 40-character commit. Safe branch and tag names are also +accepted, but short commits, ambiguous refs, and unsafe characters are not. If +Git is timing out, set `MAISTER_GIT_TIMEOUT_MS` within the supported 1–600000 ms +range and retry after checking network access. + +### Install says the target is already installed + +Use `update`, not `install`. First run `status`, preserve the active receipt, +and confirm that the source and matching E3 attestation are for the intended +new version. + +### A drift conflict is reported + +Do not force the operation or delete the changed file. Read +`error.details.conflicts` or the reported path, preserve your change, and +compare it with the active receipt. Reconcile the managed file or managed +settings key before retrying. + +### The lock is busy + +Check whether another Maister installer is running for the same target and +state root. Wait for it to finish. If the process is confirmed gone, preserve a +copy of `install.lock` and the journals before any cleanup; do not delete a live +process's lock. + +### Status or verify returns code 0 with no receipt + +Check `receipt_path`. A null value means no active receipt was found under the +selected target, home, and state root. Confirm `--target`, `--home`, and +`XDG_STATE_HOME` match the original install. + +### Verify reports integrity failure + +Stop the host and other writers. Preserve the installed target, receipt, +journal, and backups. Do not update or uninstall until you understand the +changed receipt-listed file or setting. + +### Rollback or recovery returns code 7 + +Stop. Preserve the entire target state directory and the installed target. Do +not repeatedly invoke rollback, hand-edit the journal, or treat a later code-0 +command as proof of restoration. Correct the reported permission, path, or +backup problem, run recovery once it is safe, then require a non-null receipt +and a successful verify. + +## Related documentation + +- [Platform-independent distribution specification](../implementation/spec.md) +- [Implementation verification report](../verification/implementation-verification.md) diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/implementation-plan.html b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/implementation-plan.html new file mode 100644 index 00000000..a91c7dc6 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/implementation-plan.html @@ -0,0 +1,336 @@ + + + + + + Implementation Plan · Platform-independent Maister distribution + + + +
+ + +
+

Phase 7 · Implementation planning

+

Platform-independent Maister distribution

+

Four serialized implementation groups freeze the overlay, materializer, installer, and migration boundaries; a fifth group reviews feature-test coverage. Claude support and committed generated trees are removed only after parity and transaction evidence are green.

+
+
5task groups
+
39tracked steps
+
26–34focused tests
+
17/17requirements mapped
+
+
+ Markdown source + Specification + Specification audit +
+
+ +
+

Execution shape

+
+ 1 · Overlay v1→2 · Materializer→3 · Installer→4 · Evidence & migration→5 · Test review +
+
+
+

Key decisions

+
    +
  • plugins/maister/ remains the single maintained common source.
    • +
  • Overlay v1 is frozen before materialization work begins.
    • +
  • One Node ESM CLI owns all lifecycle commands and machine-readable outcomes.
    • +
  • Receipts and journals live in target-scoped state, separate from workflow state.
    • +
  • Legacy projections are read-only parity fixtures until Group 4.
    • +
+
+
+

Open questions / risks

+
    +
  • Cursor/Kiro E5/E6 may be unavailable and must never appear as passed.
    • +
  • Real GitHub smoke evidence depends on network availability; unit tests inject the resolver boundary.
    • +
  • Shared settings require journaled multi-file recovery despite atomic managed-tree replacement.
    • +
  • No release timing threshold is added; determinism remains mandatory.
    • +
+
+
+
+ +
+

Frozen implementation contracts

+
+
+

Overlay v1

+

The strict schema rejects unknown fields and freezes:

+
    +
  • schema_version, overlay_id, overlay_version, and target identity/version/discovery roots.
    • +
  • Ordered layout entries with source, destination, kind, mode, and ownership.
    • +
  • Settings path/format/ownership/managed keys and preserve_unmanaged_refuse_drift.
    • +
  • Exactly six semantic bindings: user gate, delegation, progress, task root, persistence, and continuation.
    • +
  • Required/optional/forbidden inventory, validation rules, capability evidence, and hashed native assets.
    • +
+

Per-host inventory is explicit: Codex owns its plugin manifest and OpenAI metadata; Cursor owns its plugin manifest, rules, Markdown agents, and hooks; Kiro owns steering, JSON agents, hooks, and agent-tools.

+
+
+

Installer v1

+ 
node plugins/maister/bin/maister-install.mjs
+  <install|update|status|verify|uninstall|rollback|recover>
+  --target <codex|cursor|kiro-cli>
+  [--source <path|github:owner/repo>] [--ref <ref>]
+  [--home <path>] [--json]
+

Stable exit codes: 0 success, 2 usage/schema, 3 provenance, 4 validation, 5 drift, 6 lock, 7 transaction, 8 integrity.

+

JSON output freezes schema version, command, target, code, message, structured error, receipt/journal paths, and evidence.

+
+
+

Receipt v1

+

Identity/status, target/overlay/host, immutable source provenance, active root, managed inventory, settings ownership and hashes, capability evidence, and journal/backup/previous-receipt metadata.

+
+
+

Journal v1

+

Transaction identity, command/target, stage and destination roots, prior/candidate receipts, lock, failure, and durable steps. States: prepared → staged → snapshotted → committing → committed → verified, with rolled-back, recovered, and failed terminals.

+

State root: ${XDG_STATE_HOME:-$HOME/.local/state}/maister/<target>/.

+
+
+
+ +
+

Requirement coverage

+ + + + + + + + + + + + +
RequirementsPrimary groupBoundary
R1–R3Group 1Common source, primitives, portable runtime
R2Group 1Host overlays and inventories
R4Group 2Immutable source provenance
R5–R6Groups 2–3Lifecycle, staging, validation, path/symlink safety
R7–R10Group 3Transactions, receipts, settings ownership, drift
R11–R13Group 4Capability evidence and freshness
R14Groups 1–5Core-once and per-host seam tests
R15–R17Group 4Parity, deletion, docs, Make, CI, release
+
+ +
+

Task groups

+ +
+
+

Group 1 · Portable core and overlay v1 contracts

Dependencies: None · 7 steps · 6 tests

+ +
+
+
plugins/maister/common/primitives.ymlplugins/maister/overlays/**overlay-loader.mjsvalidate-overlay.mjsoverlay-contract.test.mjs
+
    +
  • 1.0 Complete the portable-core and overlay-contract layer.
    • +
  • 1.1 Write 6 tests: three valid hosts plus unknown/missing fields, path/ownership/collision failures, and forbidden vocabulary.
    • +
  • 1.2 Define six primitives and map them to the five single-source orchestrator ESM modules.
    • +
  • 1.3 Add strict overlay v1 schema and stable E_OVERLAY_* errors.
    • +
  • 1.4 Create explicit Codex, Cursor, and Kiro CLI overlays and inventory fixtures.
    • +
  • 1.5 Extract only host-native assets; retain legacy outputs as read-only oracle.
    • +
  • 1.6 Run only the 6 overlay contract tests.
    • +
+
Acceptance: All targets validate; every primitive binds once; portable runtime remains single-source; unsafe paths, ownership, bindings, and vocabulary fail structurally.
+
+
+ +
+
+

Group 2 · Immutable source resolution and deterministic materialization

Dependencies: Group 1 · 8 steps · 6 tests

+ +
+
+
source-resolver.mjsprovenance.mjsmaterializer.mjshash-tree.mjspath-safety.mjssource-materializer.test.mjs
+
    +
  • 2.0 Complete source resolution and materialization.
    • +
  • 2.1 Write 6 tests for local/GitHub provenance, determinism, containment/symlinks, collisions, and full stage validation.
    • +
  • 2.2 Resolve local and GitHub sources to immutable provenance and full commit identity.
    • +
  • 2.3 Freeze dirty-worktree, missing/ambiguous ref, escaping submodule/worktree, unsupported scheme, and symlink-cycle behavior.
    • +
  • 2.4 Build a normalized, sorted assembly plan and reject case-fold/duplicate collisions.
    • +
  • 2.5 Materialize common plus native assets into caller-provided same-filesystem staging.
    • +
  • 2.6 Validate inventory, references, syntax, modes, hashes, and symlinks.
    • +
  • 2.7 Run only the 6 source/materializer tests.
    • +
+
Acceptance: Identical source plus overlay is byte-deterministic; provenance is immutable; unsafe or invalid inputs fail before destination mutation; no unresolved templates or foreign vocabulary remain.
+
+
+ +
+
+

Group 3 · Transactional installer, ownership, receipt, and recovery

Dependencies: Group 2 · 10 steps · 8 tests

+ +
+
+
maister-install.mjstransaction-manager.mjsreceipt-schema.mjsjournal-schema.mjssettings-owner.mjsrecovery.mjsinstaller-transaction.test.mjs
+
    +
  • 3.0 Complete the shared installer lifecycle and transaction layer.
    • +
  • 3.1 Write 8 lifecycle, drift, lock, failure-injection, recovery, and exact-topology tests.
    • +
  • 3.2 Implement the frozen lifecycle CLI, JSON envelope, error kinds, and exit codes.
    • +
  • 3.3 Resolve target paths and enforce same-filesystem staging with sandboxable home/state roots.
    • +
  • 3.4 Add locks, durable journals, exact backups, atomic tree replacement, integrity verification, and receipt publication.
    • +
  • 3.5 Implement and validate receipt v1 and journal v1 exactly.
    • +
  • 3.6 Add whole-file and allowlisted managed-key ownership while preserving unmanaged content.
    • +
  • 3.7 Add gated failure injection and idempotent recovery for every durable state.
    • +
  • 3.8 Enforce drift-aware update, uninstall, and rollback with E_DRIFT_CONFLICT.
    • +
  • 3.9 Run only the 8 installer transaction tests.
    • +
+
Acceptance: The frozen command/receipt/journal contracts hold; no pre-validation mutation exists; every injected failure restores bytes, modes, symlinks, existence, settings, and topology without deleting unmanaged content.
+
+
+ +
+
+

Group 4 · Capability evidence, shadow parity, topology migration, and release/docs

Dependencies: Groups 1–3 · 9 steps · 6 tests

+ +
+
+
evidence-schema.mjshost-probes/*.mjsshadow-parity.mjsMakefile.github/workflows/**README.md.maister/docs/**legacy trees/builders (delete last)
+
    +
  • 4.0 Complete compatibility evidence and legacy-removal migration.
    • +
  • 4.1 Write 6 tests for E1-E6, unavailable semantics, freshness, fail-closed policy, parity, and final topology.
    • +
  • 4.2 Implement evidence schema/policy with E1/E2/E4 per host, shared E3, and explicit E5/E6 availability.
    • +
  • 4.3 Implement host probes and expiry on time, host, overlay, source, or scenario change.
    • +
  • 4.4 Compare semantic, inventory, references, hooks, permissions, symlinks, and topology against legacy fixtures.
    • +
  • 4.5 Capture clean-checkout lifecycle, failure, drift, and available native evidence for all targets.
    • +
  • 4.6 Replace Make/CI/release generated-tree paths with core and target-seam entry points.
    • +
  • 4.7 Update all operator, project, standards, support, migration, and recovery documentation.
    • +
  • 4.8 Only after green parity/recovery: delete Claude, marketplaces, builders, committed projections, and stale references; rerun the 6 tests.
    • +
+
Acceptance: Evidence is provenance- and expiry-aware; unavailable never passes; parity is zero-unresolved before deletion; generated trees/builders/Claude/marketplaces are absent; Make, CI, release, docs, and support matrices agree.
+
+
+ +
+
+

Group 5 · Test review and gap analysis

Dependencies: Groups 1–4 · 5 steps · up to 8 additional tests

+ +
+
+
tests/platform-independent/*.test.mjstests/fixtures/platform-independent/**Makefile
+
    +
  • 5.0 Review and fill critical feature-test gaps.
    • +
  • 5.1 Map the 26 tests to all 17 requirements and every deletion criterion.
    • +
  • 5.2 Audit negative source/path, binding, ownership, recovery, freshness, and topology boundaries.
    • +
  • 5.3 Add no more than 8 strategic tests; cap the feature suite at 34.
    • +
  • 5.4 Run only the platform-independent feature suite and record its inventory.
    • +
+
Acceptance: All 26–34 tests pass; every requirement and deletion criterion is asserted; core behavior runs once and host parameterization covers only true seams.
+
+
+
+ +
+

Standards and operating rules

+
+
+

Standards

+
    +
  • Minimal implementation: six primitives, no general workflow DSL.
    • +
  • Error handling: structured fail-closed outcomes with recovery diagnostics.
    • +
  • Validation: source through receipt validation before mutation/publication.
    • +
  • Build pipeline: deterministic common/overlay/materializer/install boundaries.
    • +
  • Testing: assert bytes, modes, symlinks, existence, topology, and rollback.
    • +
+
+
+

Execution rules

+
    +
  • Start every implementation group with its 2–8 tests.
    • +
  • Run only group tests until the final focused feature-suite review.
    • +
  • Reuse proven runtime and transaction patterns.
    • +
  • Keep Markdown checkboxes and HTML progress markers synchronized.
    • +
  • Delete legacy artifacts last, after parity and recovery evidence.
    • +
+
+
+
+ +
Generated for the Phase 7 implementation-approval checkpoint. This report is self-contained and uses relative task links only.
+
+ + diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/implementation-plan.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/implementation-plan.md new file mode 100644 index 00000000..39d5f1f2 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/implementation-plan.md @@ -0,0 +1,272 @@ +# Implementation Plan: Platform-independent Maister distribution + +## TL;DR + +The migration is organized into four implementation groups followed by one focused test-review group. Work is intentionally serialized through the overlay contract, deterministic materializer, transactional installer, and final parity/deletion boundary because each group freezes an interface consumed by the next. The plan expects 26 focused tests from the implementation groups and permits up to 8 strategic gap tests, for a maximum of 34 feature tests. Claude support, legacy builders, and committed generated trees are removed only in Group 4 after parity and failure-injection evidence is green. + +## Key Decisions + +- Keep `plugins/maister/` as the single maintained common source and add explicit `plugins/maister/overlays/` contracts — this avoids a disruptive second source move while removing Claude-specific ownership from the common boundary. +- Freeze overlay v1 before writing the materializer — source layout, semantic bindings, settings ownership, inventory, forbidden vocabulary, and evidence requirements become validated data rather than rewrite-script behavior. +- Expose one Node ESM entry point, `plugins/maister/bin/maister-install.mjs`, for every lifecycle operation — one command contract gives install, update, verify, rollback, recovery, and automation the same error and receipt semantics. +- Keep receipt and journal state under a target-scoped state root, separate from workflow `orchestrator-state.yml` — installation recovery must not depend on development workflow state. +- Treat legacy outputs as read-only parity fixtures until Group 4 — deletion is an acceptance step, not an early cleanup step. + +## Open Questions / Risks + +- Cursor and Kiro CLI may not be installed in the verification environment. Their E5/E6 records must remain `unavailable`; E1-E4 and shared E3 still gate release. +- GitHub source resolution may require network access in CI. Tests use a local fixture repository and a stubbed resolver boundary; one release smoke test should exercise a real immutable GitHub ref when credentials/network are available. +- Atomic rename protects the managed tree only when staging and destination share a filesystem. Shared settings remain a journaled multi-file transaction and therefore require exact recovery tests at every durable step. +- No performance threshold is introduced in this task. Determinism and bounded inventory are required, while timing regressions remain observable rather than release-gating. + +## Overview + +- Total Steps: 39 +- Task Groups: 5 +- Expected Tests: 26-34 +- Testing Group: Yes +- Visual Coverage: Not applicable; no design context exists + +## Frozen Contracts + +### Overlay v1 + +`plugins/maister/overlays/schema/overlay-v1.schema.json` is the canonical schema. Each `plugins/maister/overlays//overlay.yml` must contain these fields and reject unknown fields: + +- `schema_version`: integer `1`. +- `overlay_id`: stable string `maister/`. +- `overlay_version`: semantic version. +- `target`: `{ id, host_version_constraint, discovery_roots[] }`, where `id` is `codex`, `cursor`, or `kiro-cli` and roots are target-home-relative templates with no absolute paths or `..` traversal. +- `layout`: ordered entries `{ source, destination, kind, mode, ownership }`; `kind` is `file`, `tree`, or `template`, `mode` is an octal file mode, and `ownership` is `whole_file` or `managed_keys`. +- `settings`: entries `{ path, format, ownership, managed_keys[], merge_policy }`; `managed_keys` must be empty for `whole_file`, non-empty and allowlisted for `managed_keys`, and `merge_policy` is `preserve_unmanaged_refuse_drift`. +- `semantic_bindings`: exactly the required primitive IDs `user_gate`, `delegate_agent`, `track_progress`, `resolve_task_root`, `persist_state`, and `continue_workflow`, each with `{ adapter, capability, fail_closed }`. +- `inventory`: `{ required[], optional[], forbidden[] }`, using normalized target-relative paths or anchored glob patterns. +- `validation`: `{ forbidden_vocabulary[], executable_paths[], syntax_checks[] }`. +- `capabilities`: a map from capability ID to `{ class, required_evidence[] }`, where `class` is `semantic`, `safety`, `persistence`, `rollback`, or `packaging` and evidence IDs are E1-E6. +- `native_assets`: entries `{ source, destination, mode, sha256 }` for host-only manifests, rules, hooks, templates, or agent metadata. + +The per-host inventory fixtures are explicit and versioned in `plugins/maister/overlays//inventory.yml`: + +- Codex requires `.codex-plugin/plugin.json`, `skills/**/SKILL.md`, applicable `skills/**/agents/openai.yaml`, `hooks/hooks.json`, and the Codex native gate adapter; it forbids Cursor rules, Kiro steering/JSON agents, Claude manifests, and Claude hook vocabulary. +- Cursor requires `.cursor-plugin/plugin.json`, `skills/maister-*/SKILL.md`, `agents/*.md`, `rules/*.mdc`, and `hooks/hooks.json`; it forbids Codex agent metadata, Kiro steering/JSON agents, Claude manifests, and Claude hook vocabulary. +- Kiro CLI requires `skills/**/SKILL.md`, `agents/*.json`, `steering/*.md`, `hooks/*.sh`, and `agent-tools.json`; it forbids Codex/Cursor manifests, Cursor rules/Markdown agents, Claude manifests, and Claude hook vocabulary. + +### Installer CLI, errors, receipt, and journal + +The public entry point is: + +```text +node plugins/maister/bin/maister-install.mjs \ + --target [--source ] [--ref ] \ + [--home ] [--json] [--failure-point ] +``` + +`install` and `update` require `--source`; GitHub sources require `--ref` and must resolve to a full commit SHA before materialization. `--failure-point` is accepted only when `MAISTER_ENABLE_FAILURE_INJECTION=1`. JSON output uses `{ schema_version, ok, command, target, code, message, error, receipt_path, journal_path, evidence }`; `error`, when present, is `{ kind, details, retryable }`. + +Exit codes are stable: `0` success, `2` usage/schema, `3` source/provenance, `4` overlay/materialization/compatibility validation, `5` drift or ownership conflict, `6` lock busy, `7` transaction/recovery failure, and `8` post-commit integrity failure. + +Receipt schema v1 contains: + +- `schema_version`, `receipt_id`, `installer_version`, `status`, `installed_at`. +- `target: { id, overlay_id, overlay_version, host_version }`. +- `source: { kind, requested, requested_ref, resolved_commit, source_version, content_hash }`. +- `active_root` and `managed_inventory[]: { path, type, mode, sha256, link_target, ownership }`. +- `settings[]: { path, format, ownership, managed_keys, before_sha256, after_sha256, backup_ref }`. +- `evidence[]: { target, capability, host_version, scenario, timestamp, result, provenance, expires_at }`. +- `transaction: { journal_id, backup_root, previous_receipt_id }`. + +Journal schema v1 contains `schema_version`, `journal_id`, `command`, `target`, `started_at`, `state`, `stage_root`, `destination_root`, `previous_receipt`, `candidate_receipt`, `lock`, `steps[]`, and `failure`. `state` is one of `prepared`, `staged`, `snapshotted`, `committing`, `committed`, `verified`, `rolled_back`, `recovered`, or `failed`; each step records `{ name, status, timestamp, before_ref, after_hash }`. Receipt publication is the final durable step after integrity verification. + +Target-scoped state defaults to `${XDG_STATE_HOME:-$HOME/.local/state}/maister//`; the lock, journals, receipts, backups, and active-receipt pointer live below that root. Tests always pass `--home` and `XDG_STATE_HOME` sandbox paths. + +## Requirement Coverage + +| Requirement | Primary Group(s) | +| --- | --- | +| R1-R3 common source, primitives, portable runtime | Group 1 | +| R2 host overlays and inventories | Group 1 | +| R4 immutable source provenance | Group 2 | +| R5 lifecycle operations | Groups 2-3 | +| R6 staged validation and symlink/path safety | Group 2 | +| R7 transaction, recovery, exact rollback | Group 3 | +| R8 receipt ownership and provenance | Group 3 | +| R9-R10 settings ownership and drift | Group 3 | +| R11-R13 capability evidence and freshness | Group 4 | +| R14 core-once/per-host tests | Groups 1-5 | +| R15 shadow parity and zero unresolved differences | Group 4 | +| R16 Claude/generated-tree/builder removal | Group 4 | +| R17 docs, standards, Make, CI, release, support matrix | Group 4 | + +## Implementation Steps + +### Task Group 1: Portable core and overlay v1 contracts + +**Dependencies:** None +**Files to Modify:** `plugins/maister/common/primitives.yml`, `plugins/maister/overlays/schema/overlay-v1.schema.json`, `plugins/maister/overlays/codex/overlay.yml`, `plugins/maister/overlays/codex/inventory.yml`, `plugins/maister/overlays/cursor/overlay.yml`, `plugins/maister/overlays/cursor/inventory.yml`, `plugins/maister/overlays/kiro-cli/overlay.yml`, `plugins/maister/overlays/kiro-cli/inventory.yml`, `plugins/maister/overlays/*/assets/**`, `plugins/maister/lib/distribution/overlay-loader.mjs`, `plugins/maister/lib/distribution/errors.mjs`, `plugins/maister/bin/validate-overlay.mjs`, `tests/platform-independent/overlay-contract.test.mjs`, `tests/fixtures/platform-independent/overlays/**` +**Estimated Steps:** 7 + +- [x] 1.0 Complete the portable-core and overlay-contract layer. + - [x] 1.1 Write 6 focused overlay-contract tests. + - Accept one valid fixture for each target and assert the required per-host inventory categories. + - Reject unknown fields, missing semantic bindings, invalid ownership combinations, absolute/traversing destinations, collisions in normalized inventory paths, and foreign-host/Claude vocabulary. + - [x] 1.2 Define the six minimal semantic primitives in `common/primitives.yml` and map them to the five proven orchestrator ESM modules without copying those modules. + - Reuse: `gate-evaluator.mjs`, `orchestrator-state-repository.mjs`, `orchestrator-state-schema.mjs`, `phase-continue.mjs`, and `workflow-continuation.mjs`. + - [x] 1.3 Add the strict overlay v1 JSON Schema and typed error helpers. + - Enforce the field-level contract in the Frozen Contracts section and stable `E_OVERLAY_*` error kinds. + - [x] 1.4 Create Codex, Cursor, and Kiro CLI overlay and inventory fixtures from the current generated outputs. + - Make native discovery roots, layout roots, settings destinations, semantic adapters, required inventory, executable paths, forbidden vocabulary, and E1-E6 claims explicit. + - [x] 1.5 Extract only host-native manifests, hooks, templates, rules/steering, and agent metadata into overlay-owned assets. + - Do not delete or rewrite legacy generated trees in this group; they remain the comparison oracle. + - [x] 1.6 Run only `tests/platform-independent/overlay-contract.test.mjs` and make all 6 tests pass. + +**Acceptance Criteria:** + +- All 6 focused tests pass. +- Every target validates against overlay v1 and has an explicit inventory fixture. +- Every required semantic primitive has exactly one target adapter and fail-closed capability classification. +- The five portable runtime modules remain single-source under `plugins/maister/skills/orchestrator-framework/bin/`. +- Invalid paths, ownership declarations, incomplete bindings, and foreign vocabulary fail with stable machine-readable errors. + +### Task Group 2: Immutable source resolution and deterministic materialization + +**Dependencies:** Group 1 +**Files to Modify:** `plugins/maister/lib/distribution/source-resolver.mjs`, `plugins/maister/lib/distribution/provenance.mjs`, `plugins/maister/lib/distribution/materializer.mjs`, `plugins/maister/lib/distribution/hash-tree.mjs`, `plugins/maister/lib/distribution/path-safety.mjs`, `plugins/maister/bin/materialize.mjs`, `tests/platform-independent/source-materializer.test.mjs`, `tests/fixtures/platform-independent/source-repos/**`, `tests/fixtures/platform-independent/materialized/**` +**Estimated Steps:** 8 + +- [x] 2.0 Complete source resolution and materialization. + - [x] 2.1 Write 6 focused source/materializer tests. + - Cover local checkout resolution, GitHub ref-to-commit resolution through an injected resolver, deterministic repeated output, path containment/symlink escape refusal, normalized collision refusal, and inventory/syntax/mode/hash validation. + - [x] 2.2 Implement local and `github:owner/repo` source adapters with immutable provenance. + - Record requested source/ref, full resolved commit, source version, overlay version, host version, and source/content hashes. + - Reject a mutable GitHub ref that cannot be resolved to a full commit. + - [x] 2.3 Implement source resolver edge behavior explicitly. + - Reject dirty local worktrees unless `--allow-dirty-local` is explicitly supplied to the internal materializer command; include a deterministic dirty-tree content hash when allowed. + - Reject missing refs, ambiguous short SHAs, submodule/worktree paths escaping the source root, unsupported source schemes, and symlink cycles. + - [x] 2.4 Implement deterministic overlay loading and normalized assembly planning. + - Sort by normalized destination, reject duplicate/case-fold collisions, and prevent writes outside the selected target root. + - [x] 2.5 Materialize common files plus native overlay assets into a caller-provided same-filesystem staging root. + - Preserve declared modes and safe symlinks; never mutate a user destination. + - [x] 2.6 Validate required/forbidden inventory, internal references, JSON/YAML/Markdown/frontmatter syntax, executable modes, file hashes, and symlink targets. + - [x] 2.7 Run only `tests/platform-independent/source-materializer.test.mjs` and make all 6 tests pass. + +**Acceptance Criteria:** + +- All 6 focused tests pass for all three overlays using parameterized fixtures. +- Identical source commit plus overlay version produces byte-identical inventory and hashes. +- Local and GitHub provenance records are complete and immutable before staging is accepted. +- Traversal, collisions, unsafe symlinks, invalid syntax/modes, and missing inventory fail before destination mutation. +- Materialized output contains no unresolved template tokens or forbidden host vocabulary. + +### Task Group 3: Transactional installer, ownership, receipt, and recovery + +**Dependencies:** Group 2 +**Files to Modify:** `plugins/maister/bin/maister-install.mjs`, `plugins/maister/lib/distribution/cli-contract.mjs`, `plugins/maister/lib/distribution/transaction-manager.mjs`, `plugins/maister/lib/distribution/receipt-schema.mjs`, `plugins/maister/lib/distribution/journal-schema.mjs`, `plugins/maister/lib/distribution/settings-owner.mjs`, `plugins/maister/lib/distribution/drift-detector.mjs`, `plugins/maister/lib/distribution/recovery.mjs`, `plugins/maister/lib/distribution/target-paths.mjs`, `plugins/maister/overlays/*/overlay.yml`, `tests/platform-independent/installer-transaction.test.mjs`, `tests/fixtures/platform-independent/user-homes/**` +**Estimated Steps:** 10 + +- [x] 3.0 Complete the shared installer lifecycle and transaction layer. + - [x] 3.1 Write 8 focused installer tests. + - Cover clean install/verify/uninstall, update with prior receipt, whole-file drift refusal, managed-key preservation/conflict refusal, lock contention, failure after snapshot, failure during commit, and recovery/rollback with exact bytes/modes/symlinks/existence/topology. + - [x] 3.2 Implement the frozen CLI and JSON/error contract for `install`, `update`, `status`, `verify`, `uninstall`, `rollback`, and `recover`. + - Preserve exit codes 0/2/3/4/5/6/7/8 and never emit a success envelope for a failed or unavailable semantic boundary. + - [x] 3.3 Implement target path resolution and same-filesystem staging. + - Resolve host discovery destinations from the selected overlay and sandbox all tests through `--home` plus `XDG_STATE_HOME`. + - [x] 3.4 Implement exclusive target locks, durable journal transitions, exact backups, candidate receipt generation, atomic tree replacement, integrity verification, and final active-receipt publication. + - Reuse repository lock/fsync/atomic-replace patterns from `orchestrator-state-repository.mjs` without coupling installer state to workflow state. + - [x] 3.5 Implement receipt schema v1 and journal schema v1 exactly as frozen above. + - Validate every read and write; retain previous receipts and backup references required for rollback. + - [x] 3.6 Implement `whole_file` and allowlisted `managed_keys` ownership. + - Preserve unmanaged keys and formatting where the format adapter supports it; compare before/after hashes; refuse destructive drift or ambiguous ownership. + - [x] 3.7 Implement failure injection and idempotent recovery for every durable transaction state. + - Restore bytes, modes, symlink targets, prior existence/non-existence, empty directories needed by prior topology, settings, previous active receipt, and cleanup of staging artifacts. + - [x] 3.8 Implement update, uninstall, and rollback conflict policy. + - Managed unmodified paths may change; modified owned paths and overlapping managed keys fail with `E_DRIFT_CONFLICT`; unrelated user content is never removed. + - [x] 3.9 Run only `tests/platform-independent/installer-transaction.test.mjs` and make all 8 tests pass. + +**Acceptance Criteria:** + +- All 8 focused tests pass across parameterized Codex, Cursor, and Kiro CLI target homes. +- The command, error, receipt, and journal contracts exactly match the Frozen Contracts section. +- No supported command mutates target files before source, overlay, stage, and snapshot validation complete. +- Failure injection at each durable boundary restores byte-exact prior state and leaves an auditable terminal journal. +- Update, uninstall, and rollback preserve unmanaged content and refuse unsafe drift. + +### Task Group 4: Capability evidence, shadow parity, topology migration, and release/docs + +**Dependencies:** Groups 1, 2, and 3 +**Files to Modify:** `plugins/maister/lib/distribution/evidence-schema.mjs`, `plugins/maister/lib/distribution/evidence-policy.mjs`, `plugins/maister/lib/distribution/host-probes/*.mjs`, `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml`, `plugins/maister/bin/shadow-parity.mjs`, `tests/platform-independent/evidence-parity-topology.test.mjs`, `tests/fixtures/platform-independent/evidence/**`, `Makefile`, `.github/workflows/validate-generated-variants.yml`, `.github/workflows/cursor-cli-smoke.yml`, `.github/workflows/release.yml`, `README.md`, `docs/README.md`, `.maister/docs/project/vision.md`, `.maister/docs/project/architecture.md`, `.maister/docs/project/tech-stack.md`, `.maister/docs/project/roadmap.md`, `.maister/docs/standards/global/build-pipeline.md`, `.maister/docs/standards/global/validation.md`, `.maister/docs/standards/testing/test-writing.md`, `platforms/codex-cli/**`, `platforms/cursor/**`, `platforms/kiro-cli/**`, `.claude-plugin/marketplace.json`, `.cursor-plugin/marketplace.json`, `.agents/plugins/marketplace.json`, `plugins/maister/.claude-plugin/**`, `plugins/maister/CLAUDE.md`, `plugins/maister/hooks/**`, `plugins/maister-codex/**`, `plugins/maister-cursor/**`, `plugins/maister-kiro/**`, `tests/host-continuation/claude.e2e.sh` +**Estimated Steps:** 9 + +- [x] 4.0 Complete compatibility evidence and the legacy-removal migration. + - [x] 4.1 Write 6 focused evidence/parity/topology tests. + - Cover E1-E6 record validation, `unavailable` never satisfying `passed`, per-capability expiry/renewal, semantic fail-closed versus packaging provisional policy, classified zero-unresolved shadow parity, and final negative topology/Claude/legacy-reference checks. + - [x] 4.2 Implement evidence schema and policy evaluation. + - Require `{ target, capability, host_version, scenario, timestamp, result, provenance, expires_at }`; result is `passed`, `failed`, or `unavailable`. + - Require E1/E2/E4 per target plus shared E3; execute E5/E6 only when a native runtime probe is available, otherwise record `unavailable` without promotion. + - [x] 4.3 Implement per-target native probe adapters and freshness renewal. + - Expire on `expires_at`, host-version mismatch, overlay-version mismatch, source commit change, or scenario-version change. + - [x] 4.4 Implement the shadow parity baseline and classifier against the three legacy generated trees. + - Compare semantic bindings, inventory, internal references, hooks, permissions, symlinks, and topology; classify expected packaging/deletion differences and fail while any semantic or unexplained difference remains. + - [x] 4.5 Run clean-checkout lifecycle and failure-injection evidence for all three targets. + - Capture install, verify, update, uninstall, rollback, recovery, settings drift, and available native scenarios in receipts/evidence fixtures. + - [x] 4.6 Replace Make and CI/release entry points with `test-core`, `test-overlay TARGET`, `test-materializer TARGET`, `test-install TARGET`, `test-evidence TARGET`, `test-topology`, and target-aware packaging/install commands. + - Remove generated-tree drift jobs and marketplace publishing/install assumptions. + - [x] 4.7 Update all operator/project/standards/support documentation to the one-source, three-overlay, transactional-installer model. + - Document local and immutable GitHub usage, receipt/state locations, drift behavior, recovery, evidence meanings, Cursor/Kiro E5/E6 availability, migration, and explicit Claude removal. + - [x] 4.8 After 4.1-4.7 are green and parity reports zero unresolved differences, delete Claude manifests/hooks/vocabulary/support rows, marketplace paths, old host builders/installers, committed generated trees, Claude continuation tests, and every stale reference to them; then run the 6 focused tests again. + +**Acceptance Criteria:** + +- All 6 focused tests pass. +- Every capability record has provenance and expiry; `unavailable` is visible and never counted as a pass. +- Shadow parity reports zero unresolved semantic, inventory, reference, hook, permission, symlink, or topology differences before deletion. +- `plugins/maister-codex/`, `plugins/maister-cursor/`, `plugins/maister-kiro/`, old builders, Claude support, marketplace paths, and generated-drift CI are absent. +- Make, CI, release, README, project docs, standards, and support matrices all describe the same Codex/Cursor/Kiro architecture. +- A repository-wide negative scan finds no active legacy path, Claude support, or generated-tree installation instruction. + +### Task Group 5: Test review and gap analysis + +**Dependencies:** Groups 1, 2, 3, and 4 +**Files to Modify:** `tests/platform-independent/*.test.mjs`, `tests/fixtures/platform-independent/**`, `Makefile` +**Estimated Steps:** 5 + +- [x] 5.0 Review and fill critical feature-test gaps. + - [x] 5.1 Review the 26 focused tests from Groups 1-4 against all 17 requirements and the legacy-deletion exit criteria. + - [x] 5.2 Check specifically for missing negative cases at source/path, semantic-binding, settings ownership, journal recovery, evidence freshness, and final topology boundaries. + - [x] 5.3 Add no more than 8 strategic tests, keeping the total feature suite at 34 or fewer. + - [x] 5.4 Run only the platform-independent feature suite through the new Make target and record the final test inventory. + +**Acceptance Criteria:** + +- All 26-34 platform-independent feature tests pass. +- Every requirement and legacy deletion criterion maps to at least one focused assertion. +- Core behavior runs once; target parameterization is limited to actual overlay/materializer/installer/evidence seams. +- No more than 8 additional tests are added in this group. + +## Execution Order + +1. Group 1: Portable core and overlay v1 contracts (7 steps, no dependencies). +2. Group 2: Immutable source resolution and deterministic materialization (8 steps, depends on Group 1). +3. Group 3: Transactional installer, ownership, receipt, and recovery (10 steps, depends on Group 2). +4. Group 4: Capability evidence, shadow parity, topology migration, and release/docs (9 steps, depends on Groups 1-3). +5. Group 5: Test review and gap analysis (5 steps, depends on all implementation groups). + +The default executor may parallelize tests or documentation work inside a group when file ownership is disjoint, but it must not run these groups concurrently: the shared overlay, installer, Make, and topology boundaries require the declared order. + +## Standards Compliance + +Follow standards from `.maister/docs/standards/`: + +- `global/minimal-implementation.md` — introduce only the six proven semantic primitives and avoid a general workflow DSL. +- `global/error-handling.md` — use stable structured errors, fail closed, and preserve recovery diagnostics. +- `global/validation.md` — validate source, overlay, staging, ownership, evidence, and receipts before mutation or publication. +- `global/build-pipeline.md` — replace generated projections and drift checks with deterministic common/overlay/materializer/install boundaries. +- `global/coding-style.md` and `global/conventions.md` — use repository ESM, Bash, YAML, Markdown, naming, and path conventions. +- `testing/test-writing.md` — assert content bytes, modes, symlinks, existence, topology, failure points, and rollback rather than exit status alone. + +## Notes + +- Test-Driven: Every implementation group starts with 2-8 focused tests. +- Run Incrementally: Run only the group tests while implementing that group; the focused feature suite runs in Group 5. +- Mark Progress: Check off both parent and child steps and keep the HTML progress markers synchronized. +- Reuse First: Reuse the existing orchestrator runtime, atomic-state repository patterns, advisor reconciliation transaction tests, and Kiro reproducibility patterns. +- Delete Last: Legacy projections, builders, and Claude support remain read-only until Group 4 parity and recovery gates are green. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/spec.html b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/spec.html new file mode 100644 index 00000000..cab0eaee --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/spec.html @@ -0,0 +1,88 @@ + + + + +Specification — Platform-independent Maister distribution + + + + +
Specification

Platform-independent Maister distribution

Technical approach and requirements for one portable source with install-time target selection.

+ +
17requirements
10reusable patterns
7new boundaries
Highrisk level
+ +

TL;DR

Maister will have one portable common source, explicit Codex/Cursor/Kiro CLI overlays, and one target-aware installer that selects the host at installation time.

The installer will resolve immutable source provenance, validate an overlay, stage the result, commit transactionally, and publish receipt-backed ownership with exact rollback.

Common runtime behavior will be tested once; host overlays, materialization, installation, settings ownership, and available native evidence will retain targeted tests.

Claude support and committed generated trees are migration-only and are removed after zero-unresolved-difference shadow parity.

Key Decisions

  • Portable common layer plus explicit host overlays.
  • Minimal typed semantic primitives, not a workflow DSL.
  • Installer as transaction manager with journal, receipt, recovery, and rollback.
  • Hybrid whole-file and managed-key settings ownership.
  • Capability-sensitive compatibility with semantic fail-closed behavior.
  • Codex, Cursor, and Kiro CLI only; Claude is removed after migration parity.

Open Questions / Risks

  • Cursor and Kiro native E5/E6 evidence may remain unavailable and must never pass.
  • Host discovery roots and inventories must be frozen in versioned overlays.
  • Shared settings require journal recovery and byte-exact failure tests.
  • Scenario evidence is required because textual parity can hide semantic drift.
  • Legacy deletion must wait for parity and failure-injection exit criteria.
+ +

Contents: Scope · Requirements · Compatibility · Reuse · Technical Approach · Testing · Success Criteria

+ +

Goal and Scope

In scope

  • Portable common source and runtime ownership.
  • Codex, Cursor, and Kiro CLI overlays.
  • Target-aware source resolution, materialization, installation, update, status/verify, uninstall, rollback, and recovery.
  • Receipt, journal, settings, evidence, schema, parity, CI, release, and documentation migration.
  • Removal of Claude support and committed generated infrastructure.

Out of scope

  • Re-adding Claude support.
  • A full workflow DSL or prompt compiler.
  • Native evidence that cannot run in the current environment.
  • New GUI surfaces or visual design.
  • Unrelated feature redesign.
+ +

User Stories

As a maintainer, I want to edit common behavior once and host behavior in a visible overlay so synchronized generated trees are unnecessary.
As an installer operator, I want to select a target and local or immutable GitHub source so the correct host layout is assembled safely.
As a user, I want update, uninstall, rollback, and recovery to respect my files and settings.
As a host integrator, I want capability evidence per host and capability so missing native behavior cannot look green.
As a release owner, I want one core suite and focused host seams so CI validates behavior without committed projections.
+ +

Core Requirements

+ + + + + + + + + + + + + + + + + +
IDRequirementPriority
R1One neutral common layer for portable skills, references, assets, runtime, and primitives.Critical
R2Versioned Codex, Cursor, and Kiro CLI overlays with inventories, bindings, paths, settings, and forbidden vocabulary.Critical
R3One maintained portable orchestrator runtime, without generated copies.Critical
R4Immutable local/GitHub source and ref provenance in every installation.Critical
R5Shared install, update, status/verify, uninstall, rollback, and recovery lifecycle.Critical
R6Pre-mutation staging and validation for schema, containment, collisions, inventory, syntax, modes, hashes, and symlinks.Critical
R7Locks, journal, backups, atomic commit, cleanup, recovery, and exact failure restoration.Critical
R8Receipt with managed inventory, provenance, target/overlay identity, settings ownership, evidence, hashes, and rollback metadata.Critical
R9Hybrid whole-file and allowlisted managed-key settings ownership.Critical
R10Drift/conflict detection that preserves unmanaged content and refuses unsafe destructive changes.Critical
R11Per-capability compatibility records with semantic fail-closed behavior and packaging-only provisional status.Critical
R12E1/E2/E4 plus shared E3 for each host; E5/E6 unavailable is explicit and never passing.Critical
R13Per-capability evidence expiry and re-probe metadata.High
R14Common-core-once testing plus focused host overlay, materializer, installer, settings, topology, and native evidence tests.Critical
R15Shadow parity with zero unresolved semantic, inventory, reference, hook, permission, and topology differences before deletion.Critical
R16Remove Claude, generated trees, old builders, marketplace paths, and generated-tree drift CI.Critical
R17Align README, docs, standards, Make, CI, release, and support matrices with the three-host model.High
+ +

Compatibility, Evidence, and Rollback

Supported targets: Codex, Cursor, and Kiro CLI. Semantic, safety, persistence, delegation, continuation, and rollback capabilities fail closed. Packaging-only differences may be provisional after structural and transactional evidence.

Evidence: E1 schema/overlay validation; E2 deterministic materialization; E3 shared core; E4 installer/settings/rollback; E5 host-native discovery; E6 host-native runtime scenarios. Every record includes target, capability, host version, scenario, timestamp, result, provenance, and expiry. unavailable is distinct from passed.

Rollback: A separate journal and receipt govern installation state. The installer stages and validates before snapshotting and atomic commit. Recovery restores the previous receipt, exact bytes/modes/symlinks/topology, owned settings, and removes temporary artifacts without deleting unmanaged user content.

+ +

Legacy Deletion Exit Criteria

  1. Baseline manifest covers common behavior, host assets, hooks, settings, permissions, references, and generated inventory.
  2. Three-host shadow materialization has zero unresolved differences.
  3. Core, overlay, materializer, installer, settings, rollback, recovery, and available-native tests pass.
  4. Clean install, verify, update, uninstall, rollback, and recovery succeed for every target.
  5. User changes and settings drift are preserved.
  6. Make, CI, release, docs, manifests, evidence, and tests use the new boundaries.
  7. No active references remain to generated trees, Claude, marketplace installation, or legacy builders.
+ +

Reusable Components

Existing pathReuse
orchestrator-state-repository.mjsLocks, CAS/revisions, safe paths, fsync, atomic replacement, metadata, cleanup.
orchestrator-state-schema.mjsStrict validation, canonical serialization, legal transitions.
gate-evaluator.mjsGate validation, idempotency, attempts, terminal outcomes.
workflow-continuation.mjsDurable inventory, claims, leases, checkpoints, acknowledgements.
reconcile-advisor-config.shCandidate staging, backup, atomic rename, modes, rollback diagnostics.
Existing transactional testsphase-continue-contract, advisor lifecycle/reconciliation, repository, and Kiro reproducibility tests provide failure-injection and exact-state assertions.

New boundaries: neutral common source, three overlay schemas, deterministic materializer/source resolver, transaction manager, evidence/freshness schema, and migration topology/parity checks.

+ +

Technical Approach

The common layer expresses portable intent and runtime behavior. Overlays own only host-native layout, assets, bindings, settings policy, and capability claims. The materializer combines one immutable source with one validated overlay into a deterministic staging tree and does not apply arbitrary global prose rewrites.

The installer resolves source/ref, probes the host, classifies capabilities, stages and validates output, snapshots state, commits atomically, publishes a receipt, and recovers from failure. Workflow state remains in orchestrator-state.yml; installation receipts and journals use separate schemas.

Legacy outputs remain read-only shadow oracles until every difference is classified and all deletion criteria pass.

+ +

Implementation Guidance and Testing

Each implementation step group contains 2-8 focused tests and runs new tests first. Common behavior is covered once; per-target tests cover only host seams.

GroupFocusTests
Common source/primitivesSchema, vocabulary, runtime, binding completeness4-8
Overlay/materializerValidation, containment, collisions, inventory, syntax, modes, hashes5-8 per host
Resolver/transactionProvenance, locks, staging, receipts, journal recovery, rollback6-8 per host
Settings ownershipWhole-file, managed keys, drift, conflicts, exact restore4-8
Capability evidenceE1-E6, unavailable, expiry, renewal, fail-closed policy4-8
Migration/topologyShadow parity, deletion, negative topology, Make/CI/release4-8

Standards Compliance

  • minimal-implementation.md: proven seams, no speculative DSL.
  • error-handling.md and validation.md: fail closed, validate before mutation, structured evidence.
  • build-pipeline.md: deterministic common/overlay/materializer checks.
  • test-writing.md: bytes, modes, existence, topology, symlinks, and rollback—not exit codes alone.
  • coding-style.md and conventions.md: project language and file-boundary conventions.
+ +

Success Criteria

  • One common source and three explicit overlays are the only maintained distribution inputs.
  • One installer handles local/immutable GitHub sources and safe lifecycle operations.
  • No supported install path mutates destructively before validation.
  • Core behavior is tested once and host seams have focused tests.
  • Evidence has provenance and expiry; unavailable never passes.
  • Shadow parity has zero unresolved differences before legacy deletion.
  • Claude, generated trees, old builders, marketplace paths, generated drift CI, and stale documentation are absent.
  • Docs, standards, Make, CI, release, and support matrices describe the same architecture.
+ + diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/spec.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/spec.md new file mode 100644 index 00000000..dd559e51 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/spec.md @@ -0,0 +1,168 @@ +# Specification: Platform-independent Maister distribution + +## TL;DR + +Maister will have one portable common source, explicit Codex/Cursor/Kiro CLI overlays, and one target-aware installer that selects the host at installation time. +The installer will resolve immutable source provenance, validate an overlay, stage the result, commit transactionally, and publish receipt-backed ownership with exact rollback. +Common runtime behavior will be tested once; host overlays, materialization, installation, settings ownership, and available native evidence will retain targeted tests. +Claude support and committed generated trees are migration-only and are removed after zero-unresolved-difference shadow parity. + +## Key Decisions + +- Use a portable common layer plus explicit host overlays — this removes duplicated generated ownership while preserving native host layouts. +- Use minimal typed semantic primitives, not a workflow DSL — only control flow, safety, persistence, delegation, continuation, and capability boundaries need host bindings. +- Treat the installer as a transaction manager — staging, validation, journal, receipt, atomic commit, recovery, and rollback are core behavior. +- Use hybrid settings ownership — dedicated files are whole-file owned; unavoidable shared files use narrowly allowlisted managed keys with drift detection. +- Use capability-sensitive compatibility — semantic, safety, persistence, and rollback capabilities fail closed; packaging-only differences may be provisional. +- Support Codex, Cursor, and Kiro CLI only — Claude and committed generated projections are temporary comparison oracles and are deleted before completion. + +## Open Questions / Risks + +- Native E5/E6 runtime evidence for Cursor and Kiro may remain unavailable; the implementation must record that state explicitly and never treat it as a pass. +- Exact host discovery roots and native inventories must be frozen in versioned overlays before legacy deletion. +- Shared settings and shell files do not provide multi-file filesystem atomicity; journal recovery and byte-exact failure tests are mandatory. +- Textual parity can hide semantic drift in gates, delegation, hooks, progress, and continuation; scenario evidence is required. +- Removing legacy trees eliminates the current rollback oracle, so parity and failure-injection exit criteria must be met first. + +## Goal + +Replace build-time host-specific generation and duplicated runtime testing with a portable Maister source, explicit host contracts, and safe install-time target selection. + +## User Stories + +- As a maintainer, I want to edit common behavior once and host behavior in a visible overlay so that changes do not require synchronized generated trees. +- As an installer operator, I want to select `codex`, `cursor`, or `kiro-cli` and a local or immutable GitHub source so that the correct host layout is assembled safely. +- As a user, I want updates, uninstall, rollback, and recovery to respect my files and settings so that an interrupted install cannot destroy unrelated state. +- As a host integrator, I want capability evidence per host and capability so that unsupported native behavior cannot be mistaken for a green result. +- As a release owner, I want one core test suite and focused host seams so that CI validates behavior without rebuilding committed projections. + +## Core Requirements + +1. Maintain one neutral common layer containing portable skills, references, assets, runtime modules, and minimal semantic primitive definitions. +2. Maintain versioned `codex`, `cursor`, and `kiro-cli` overlays containing native manifests/assets, discovery roots, layout allowlists, settings destinations, semantic bindings, required inventory, and forbidden vocabulary. +3. Preserve the portable orchestrator runtime behavior from the five proven ESM modules under `plugins/maister/skills/orchestrator-framework/bin/` without maintaining generated copies. +4. Resolve a local checkout or GitHub source/ref to immutable provenance, including requested ref, resolved commit, source version, overlay version, host version, and content hashes. +5. Provide one target-aware install lifecycle covering install, update, status/verify, uninstall, rollback, and recovery for the three supported targets. +6. Assemble into a same-filesystem staging area and validate source, overlay schema, path containment, collisions, inventory, references, syntax, modes, hashes, and symlink safety before mutation. +7. Protect commits with locks, journal entries, exact backups, atomic rename, cleanup, recovery, and failure injection; restore bytes, modes, symlinks, existence, and directory topology on failure. +8. Publish a receipt containing managed inventory, source/ref provenance, target and overlay identity, settings ownership, evidence, hashes, and rollback metadata. +9. Use `whole_file` ownership for dedicated Maister files and narrowly allowlisted `managed_keys` ownership for unavoidable shared settings and shell files. +10. Detect user drift and conflicts, preserve unmanaged content, and refuse unsafe destructive updates or uninstall operations. +11. Represent compatibility per capability with host/version/scenario/timestamp/provenance records. Semantic and safety boundaries fail closed; packaging-only differences may be provisional. +12. Require E1/E2/E4 for every host plus shared-core E3. Record E5/E6 as `unavailable` when runtime evidence cannot be executed; never promote unavailable to passed. +13. Expire and re-probe evidence per capability using host, version, scenario, and timestamp metadata. +14. Run common behavior tests once and retain per-host overlay, materializer, installer, settings, topology, and available native evidence tests. +15. Use legacy generated trees and builders only as a shadow parity oracle. Explain every difference and require zero unresolved semantic, inventory, reference, hook, permission, and topology differences before deletion. +16. Remove Claude manifests, hooks, vocabulary, marketplace paths, capability rows, support instructions, committed generated trees, old builders, and generated-tree drift CI before completion. +17. Update README, host support docs, project docs, standards, Make targets, CI, release packaging, support matrices, and migration notes to describe the new model. + +## Compatibility and Evidence Policy + +The supported target set is Codex, Cursor, and Kiro CLI. Compatibility is evaluated per capability rather than as a single host boolean. Semantic, safety, persistence, delegation, continuation, and rollback capabilities are fail-closed: a missing or failed binding blocks support for that capability. Packaging-only differences may be marked provisional when their structural and transactional evidence passes. + +Evidence levels are defined as follows: + +- E1: source/schema and overlay contract validation. +- E2: deterministic materialization, inventory, containment, collision, syntax, and permission validation. +- E3: shared portable-core behavior suite. +- E4: isolated installer transaction, receipt, settings ownership, drift, recovery, and rollback evidence. +- E5: host-native discovery and integration evidence. +- E6: host-native runtime scenario evidence. + +Every record includes target, capability, host version, scenario, timestamp, result, provenance, and expiry. `passed`, `failed`, and `unavailable` are distinct outcomes. E5/E6 may be unavailable when the host runtime is absent, but that result remains visible and cannot satisfy a semantic capability by implication. + +## Rollback Plan + +The installer owns a journal and a receipt separate from workflow state. It resolves source and overlay, acquires a target lock, creates a staging tree, validates it, snapshots the managed tree and owned settings, and commits only through same-filesystem atomic replacement. The receipt is published only after the commit and integrity verification complete. + +On any injected or observed failure, recovery uses the journal to determine the last durable step, restores the prior receipt and active pointer, restores exact file bytes/modes/symlinks/topology, restores owned settings according to their ownership mode, removes staging artifacts, and reports the failure without deleting unmanaged user content. Updates and uninstall refuse to overwrite detected drift unless the operation is explicitly safe under the ownership contract. + +## Legacy Deletion Exit Criteria + +The following must all pass before removing legacy generated trees and Claude support: + +- A baseline manifest identifies all common behavior, host assets, hooks, settings, permissions, references, and generated inventory. +- Codex, Cursor, and Kiro shadow materialization has zero unresolved semantic, inventory, reference, hook, permission, and topology differences. +- Core, overlay, materializer, installer, settings, rollback, recovery, and available native evidence tests pass with unavailable outcomes explicit. +- Clean-checkout install, verify, update, uninstall, rollback, and recovery scenarios succeed for each target. +- User modifications and shared settings drift are preserved according to the ownership contract. +- Make, CI, release, docs, manifests, capability records, and tests use the new source/overlay/installer boundaries. +- No active references remain to committed generated trees, Claude support, marketplace installation, or legacy builders. + +## Reusable Components + +### Existing Code to Leverage + +| Existing path | Reuse | +| --- | --- | +| `plugins/maister/skills/orchestrator-framework/bin/gate-evaluator.mjs` | Gate identity, validation, idempotency, attempts, and safe terminal outcomes. | +| `plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-repository.mjs` | Locks, CAS/revisions, safe paths, fsync, atomic replacement, metadata, and cleanup. | +| `plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-schema.mjs` | Strict schema validation, canonical serialization, and legal transitions. | +| `plugins/maister/skills/orchestrator-framework/bin/workflow-continuation.mjs` | Durable inventory, claims, leases, checkpoints, acknowledgements, and idempotent dispatch. | +| `plugins/maister/skills/init/bin/reconcile-advisor-config.sh` | Candidate staging, backups, same-directory rename, mode preservation, and rollback diagnostics. | +| `tests/phase-continue-contract.test.sh` | Byte-exact non-mutation and rollback assertions. | +| `tests/advisor-config-reconciliation.test.sh` and `tests/advisor-init-lifecycle.test.sh` | Failure-injection coverage for configuration transactions and lifecycle recovery. | +| `tests/orchestrator-state-repository.test.sh` | Durable lock, revision, path, and persistence scenarios. | +| `platforms/kiro-cli/tests/reproducible-build.test.sh` | Stable inventory, hashing, build locking, and reproducibility patterns. | +| `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` | Existing capability vocabulary and explicit unavailable semantics, reshaped per capability. | + +### New Components Required + +- A neutral common source boundary and portable primitive contract. +- Versioned Codex, Cursor, and Kiro CLI overlay schemas and native asset inventories. +- A deterministic materializer with source/ref resolver, containment checks, collision policy, and provenance manifest. +- A shared transaction manager with lock, journal, receipt, settings ownership, drift detection, recovery, and rollback services. +- Capability evidence and freshness schema plus per-target probe adapters. +- Core-once, overlay, materializer, installer, topology, and native evidence test entry points. +- Migration parity tooling and final negative topology checks. + +## Technical Approach + +The common layer expresses portable intent and runtime behavior. Overlays own only host-native layout, assets, bindings, settings policy, and capability claims. The materializer combines one immutable source with one validated overlay into a deterministic staging tree; it does not apply arbitrary global prose rewrites. + +The installer is the boundary between repository artifacts and user state. It performs source/ref resolution, overlay selection, host probing, capability classification, staging, validation, snapshotting, atomic commit, receipt publication, and recovery. Workflow state remains in `orchestrator-state.yml`; installation receipts and journals use separate schemas. + +The migration is validated in parallel against legacy generated outputs. Differences are classified as semantic, inventory/reference, hook/permission, packaging, or expected deletion. The legacy system remains a read-only oracle until the deletion exit criteria pass. + +## Implementation Guidance + +### Testing Approach + +Each implementation step group should contain 2-8 focused tests and should run the new tests first. Common behavior is covered once; per-target tests cover only genuine host seams. + +| Step group | Focus | Expected tests | +| --- | --- | ---: | +| Common source and primitives | Schema, neutral vocabulary, portable runtime contracts, binding completeness | 4-8 | +| Overlay and materializer | Overlay validation, containment, collisions, deterministic inventory, syntax, modes, hashes | 5-8 per host | +| Source resolver and installer transaction | Local/GitHub provenance, locks, staging, commit, receipts, journal recovery, rollback | 6-8 per host | +| Settings ownership | Whole-file ownership, managed keys, drift, conflict refusal, exact restore | 4-8 | +| Capability evidence | E1-E6 classification, unavailable semantics, expiry, renewal, fail-closed decisions | 4-8 | +| Migration and topology | Shadow parity, deletion boundary, negative generated-tree/Claude checks, Make/CI/release paths | 4-8 | + +### Standards Compliance + +- Follow `.maister/docs/standards/global/minimal-implementation.md`: prefer proven seams and avoid a general-purpose DSL or speculative APIs. +- Follow `.maister/docs/standards/global/error-handling.md`: fail closed at safety and persistence boundaries and preserve actionable diagnostics. +- Follow `.maister/docs/standards/global/validation.md`: validate before mutation and report structured evidence. +- Follow `.maister/docs/standards/global/build-pipeline.md`: replace generated-tree drift ownership with deterministic common/overlay/materializer checks. +- Follow `.maister/docs/standards/testing/test-writing.md`: assert bytes, modes, existence, topology, symlinks, and rollback—not just exit codes. +- Follow `.maister/docs/standards/global/coding-style.md` and `.maister/docs/standards/global/conventions.md` for Bash, JavaScript, Markdown, YAML, naming, and file boundaries. + +## Out of Scope + +- Re-adding Claude support; that is a separate future host-integration task. +- A full workflow DSL, prompt compiler, or arbitrary prose transformation framework. +- Native E5/E6 evidence that cannot be run in the current environment; those outcomes remain unavailable. +- New GUI surfaces, pages, forms, or visual design work. +- Unrelated feature redesign outside portability, distribution, installation safety, host integration, and migration governance. + +## Success Criteria + +- One neutral common source and three explicit host overlays are the only maintained distribution inputs. +- A target-aware installer supports local and immutable GitHub sources with deterministic staging, receipt, update, uninstall, rollback, and recovery. +- No destructive pre-validation mutation remains in supported install paths. +- Core behavior is tested once; host seams have focused overlay, materializer, installer, and evidence tests. +- All capability evidence includes provenance and expiry, and unavailable never passes. +- Shadow parity has zero unresolved differences before legacy deletion. +- Claude support, committed generated trees, old builders, generated drift CI, marketplace paths, and stale documentation are absent from the final topology. +- Documentation, standards, Make, CI, release, and support matrices describe the same three-host architecture. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/work-log.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/work-log.md new file mode 100644 index 00000000..f0f4de48 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/implementation/work-log.md @@ -0,0 +1,210 @@ +# Work Log + +## 2026-07-14T19:08:52Z - Implementation Started + +**Total Steps**: 39 +**Task Groups**: 1-5, dependency-ordered +**Implementation Approval**: Explicitly approved by user at 2026-07-14T19:08:52Z + +## Standards Reading Log + +### Loaded Per Group +(Entries added as groups execute) + +## 2026-07-14T19:14:22Z - Group 1 Delegation Recovery + +The delegated implementer initially exceeded the observation window without a report. The same session was resumed; it completed successfully and returned no out-of-scope changes. No rollback or manual completion was required. + +## 2026-07-14T19:15:38Z - Group 1 Delegation Resumed + +The prior implementer was observed as `running` when it was shut down. The same agent session was resumed after user correction; no new group was dispatched. + +## 2026-07-14T19:30:06Z - Group 1 Complete + +**Steps**: 1.1 through 1.6 completed +**Standards Applied**: +- From plan: `global/minimal-implementation.md`, `global/error-handling.md`, `global/validation.md`, `global/coding-style.md`, `global/conventions.md`, `testing/test-writing.md` +- From INDEX.md: the same standards were confirmed as the relevant project standards for overlay contracts, validation, and tests +- Discovered: no additional standards required +**Tests**: `node --test tests/platform-independent/overlay-contract.test.mjs` — 6 passed, 0 failed +**Additional validation**: all three `validate-overlay.mjs --target ... --json` commands returned `ok: true` +**Files Modified**: Group 1 declared ownership only; core contracts, schemas, loaders, validators, fixtures, and Codex/Cursor/Kiro assets +**Notes**: Legacy generated trees and the five portable runtime modules remain unchanged as comparison or reuse oracles. + +## 2026-07-14T19:31:32Z - Group 2 Dispatched + +Group 2 was dispatched to agent Harvey after re-reading the approved implementation state. Group 1 is complete; Group 2 owns source resolution, provenance, materialization, path safety, and its six focused tests. + +## 2026-07-14T19:47:05Z - Group 2 Complete + +**Steps**: 2.1 through 2.7 completed +**Standards Applied**: +- From plan: `global/minimal-implementation.md`, `global/error-handling.md`, `global/validation.md`, `global/coding-style.md`, `global/conventions.md`, `testing/test-writing.md` +- From INDEX.md: Group 2 followed the validation, error-handling, build/convention, and transactional testing guidance +- Discovered: Group 1 overlay loading and typed errors were reused; no additional standards required +**Tests**: `node --test tests/platform-independent/source-materializer.test.mjs` — 6 passed, 0 failed +**Files Modified**: Group 2 declared ownership only; source resolver, provenance, materializer, hash/path safety, internal materialize CLI, and source fixtures/tests +**Notes**: The current Cursor `assets/skills` declaration has an explicit common-source compatibility fallback when the host-specific directory is absent. + +## 2026-07-14T19:48:03Z - Group 3 Dispatched + +Group 3 was dispatched to agent Lagrange after Group 2's focused suite passed and the protected implementation approval was revalidated. The group owns the installer CLI, transaction journal/receipt, settings ownership, drift detection, recovery, and eight focused tests. + +## 2026-07-14T20:05:40Z - Group 3 Complete + +**Steps**: 3.1 through 3.9 completed +**Standards Applied**: +- From plan: `global/minimal-implementation.md`, `global/error-handling.md`, `global/validation.md`, `global/coding-style.md`, `global/conventions.md`, `testing/test-writing.md` +- From INDEX.md: high-risk filesystem and settings work followed validation, error-handling, conventions, and byte/topology-exact transactional test guidance +- Discovered: existing repository lock/fsync/atomic-replace patterns were reused without coupling installer state to workflow state +**Tests**: `node --test tests/platform-independent/installer-transaction.test.mjs` — 8 passed, 0 failed +**Additional validation**: all Group 3 modules passed `node --check`; three-host lifecycle smoke flows passed +**Files Modified**: Group 3 declared ownership only; installer CLI, transaction manager, schemas, settings/drift/recovery/path modules, fixtures, and tests +**Notes**: Stable exit codes 0/2/3/4/5/6/7/8 and receipt/journal v1 contracts are implemented. + +## 2026-07-14T20:07:17Z - Group 4 Dispatched + +Group 4 was dispatched to agent Erdos after Group 3's focused suite and module syntax checks passed. The group owns evidence policy, parity, topology migration, deletion of legacy/Claude artifacts after proof, and documentation/CI/release alignment. + +## 2026-07-14T20:22:01Z - Group 4 Partial / Recovery Pending + +The six evidence/parity/topology tests pass, but real materializer validation is red for all three targets: Codex is missing the declared openai.yaml inventory, Cursor is missing the declared maister skill inventory, and Kiro CLI contains a forbidden Claude vocabulary file. Legacy and generated trees remain preserved. The shared group-failure-recovery gate is pending before repair, retry, manual completion, rollback, or stop. + +## 2026-07-14T20:24:20Z - Group 4 Recovery Approved + +The user selected `Try suggested fix`. Recovery scope is limited to reconciling the three common-source/overlay inventory and vocabulary failures, rerunning real materialization and shadow parity, and deleting legacy topology only after all required gates are green. + +## 2026-07-14T20:44:27Z - Group 4 Recovery Reverification Failed + +The first recovery attempt ended without a report. Local verification found 18/26 focused tests passing and 8 failing. The root failure is a duplicate `skills/orchestrator-framework/agents/openai.yaml` assembly destination; installer failures cascade from the same materialization exit. Erdos was re-engaged under the existing user-approved recovery decision. Legacy remains preserved. + +## 2026-07-14T20:58:29Z - Group 4 Materialization Recovered / Parity Recovery Pending + +Local verification confirms all 26 focused tests pass, failure injection is green, and Codex/Cursor/Kiro CLI materialize successfully. Real shadow parity remains red with 573 unresolved differences: Codex 148, Cursor 71, Kiro CLI 354. Legacy and marketplace paths remain preserved; a new group-failure-recovery decision is pending before further parity work. + +## 2026-07-14T21:19:26Z - Group 4 Parity Recovery Approved + +The user selected `Try suggested fix` by directing the workflow to analyze and repair the reported differences. Recovery must distinguish actual behavioral omissions from intentional packaging changes and comparator false positives, fix the responsible implementation or test contract, and retain the legacy trees until zero unexplained differences remain. + +## 2026-07-14T22:04:23Z - Group 4 Complete + +**Steps**: 4.1 through 4.8 completed +**Standards Applied**: +- From plan: `global/minimal-implementation.md`, `global/error-handling.md`, `global/validation.md`, `global/build-pipeline.md`, `global/coding-style.md`, `global/conventions.md`, `testing/test-writing.md` +- From INDEX.md: evidence, fail-closed compatibility, exact filesystem observations, validation-before-deletion, and repository topology guidance +- Discovered during independent review: parity exceptions must pin both sides of each observed difference and track every expanded path independently; schema v2 now enforces this contract +**Tests**: independent focused suite — 26 passed, 0 failed; `make validate` passed; `git diff --check` passed +**Real materialization**: Codex 217 entries, Cursor 143 entries, Kiro CLI 178 entries; inventory, syntax, modes, and native hashes passed for all three +**Parity**: reviewed schema-v2 baselines contain 148 Codex, 71 Cursor, and 354 Kiro CLI exact observations; zero patterns and zero missing fingerprints; pre-deletion real shadow parity had zero unresolved differences +**Topology**: legacy generated trees, builders, Claude support, and marketplace paths were deleted only after parity/recovery gates passed; final topology reports zero violations +**Notes**: independent review caught and repaired two baseline masking defects: per-rule rather than per-path stale tracking, and missing immutable content/mode/side fingerprints. + +## 2026-07-14T22:05:36Z - Group 5 Dispatched + +Group 5 was dispatched to agent Sagan after Group 4 passed independent focused tests, schema-v2 parity-baseline audit, three-host real materialization, final topology, and `make validate`. The group owns the final 17-requirement test mapping, strategic gap tests (maximum 8), and focused feature-suite entry point. + +## 2026-07-14T22:12:26Z - Group 5 Complete / Phase 8 Complete + +**Steps**: 5.1 through 5.4 completed +**Standards Applied**: `testing/test-writing.md`, `global/validation.md`, `global/build-pipeline.md`, and `global/minimal-implementation.md` +**Gap review**: all 17 requirements and every legacy-deletion exit criterion map to focused assertions +**Tests added**: exactly 8 strategic tests covering portable primitive ownership, strict bindings, source provenance failures, traversal/symlink cycles, evidence renewal, uninstall drift non-mutation, auditable/idempotent recovery, and real repository/CI/release/docs topology +**Tests**: independent `make test-platform-independent` — 34 passed, 0 failed; suite remains within the approved 34-test cap +**Review note**: journal tests isolate the intended failed transaction instead of assuming UUID filenames encode chronology; recovery behavior remains tested through exact state restoration and repeated recovery +**Phase 8 outcome**: all five implementation groups are complete; Phase 9 is not applicable because Phase 3 was skipped by routing. The required Phase 8 exit gate is pending before Phase 10 verification options. + +## 2026-07-15T13:05:34Z - Phase 11 Verification Failed / Fix Selection Pending + +Five delegated read-only checks completed. Plan completion remains 39/39 and focused tests pass 34/34, but the canonical verdict is `failed`: five critical production blockers, sixteen warning groups, and four informational groups remain. Confirmed blockers include out-of-root writes through target symlinks, unrunnable release archives, incomplete immutable source resolution, non-atomic crash recovery, and incomplete rollback/journal restoration. The user must choose the fix scope before any source changes. + +## 2026-07-15T13:20:51Z - Phase 11 Fix Loop Iteration 1 Started + +The user selected `Fix all fixable issues`. The decision was persisted in the canonical gate history, `skip_test_suite` was set to `false`, and five disjoint repair tracks were delegated without closing any existing agent session: transaction/recovery safety, release packaging and immutable source resolution, materializer validation, evidence/provenance probes, and CI/operator documentation. Cross-cutting integration and remaining maintainability findings will be handled after these non-overlapping changes return. + +## 2026-07-15T14:17:02Z - Phase 11 Fix Loop Iteration 1 Complete / Re-Verification Pending + +All fixable critical and warning groups were addressed across transaction containment and durability, recovery and rollback, immutable source resolution, release package closure, evidence/provenance, materialization validation, Cursor source ownership, target-policy duplication, CI supply-chain behavior, fixture isolation, parity-test maintenance, and operator documentation. Independent local validation passed: `make validate` completed for all three targets with 45/45 core tests and 13/13 evidence/topology tests, the extracted deterministic archive suite passed 2/2, and `make test-platform-independent` passed 60/60. Native E5/E6 remain environment-dependent and explicit `unavailable` outcomes are not promoted to passing evidence. The required re-verification gate is pending. + +## 2026-07-15T14:50:44Z - Phase 11 Re-Verification Iteration 1 Failed / Fix Selection Pending + +Sequential test verification passed 60/60 and all five independent review tracks completed. Completeness is 39/39, pragmatic review recommends merge, production/reality permit provisional distribution, and native E6 remains explicitly unavailable. The independent code review nevertheless found four residual release blockers: staging-parent/TOCTOU containment, backup-integrity binding before rollback, independently attested E3 and correctly finalized E4 evidence, and a reproducible clean-checkout parity release gate. Ten warning groups and three informational items remain. Canonical Markdown and HTML reports were rewritten with the post-fix verdict and Fix & Re-Verification History. A second fix-selection gate is pending. + +## 2026-07-15T15:00:17Z - Phase 11 Fix Loop Iteration 2 Started + +The user selected `Fix all fixable issues`. The terminal gate decision is persisted, the complete test suite remains enabled, and the second repair iteration covers the four residual critical blockers plus fixable warning groups. Existing agent sessions remain available and are not treated as failed merely because an observation window expires. + +## 2026-07-15T16:28:11Z - Phase 11 Fix Loop Iteration 2 Complete / Re-Verification Pending + +All fixable residuals were addressed. Path mutation now uses descriptor and identity snapshots with fail-closed pre/post revalidation; cryptographic backup manifests bind bytes, modes, symlink targets, existence, and complete topology; recovery verifies before and after restore and cleans successful staging/orphan receipt residue. E3 is supplied by a strict deterministic portable-core attestation generated only after `make test-core`, while E4 is finalized after commit and integrity verification before the final receipt is published. The injected GitHub resolver, frontmatter/reference validation, central target registry, immutable parity oracle, CI pins, archive ordering, active wording, checksums, SBOM, provenance, and package lifecycle were also completed. Independent local evidence is green: 91/91 platform-independent tests, 4/4 extracted package lifecycle tests, 11/11 release/parity/topology tests, zero unresolved parity differences for Codex/Cursor/Kiro CLI, `make validate`, and `git diff --check`. Native E5/E6 remains explicitly environment-dependent. The required independent re-verification gate is pending. + +## 2026-07-15T16:34:10Z - Phase 11 Re-Verification Iteration 2 Approved + +The user selected `Yes, re-run verification`. The terminal gate decision is persisted before execution. Verification will run the complete test suite first, followed by the completeness, code review, pragmatic, production-readiness, and reality checks in one parallel batch. Existing agent sessions will not be terminated because an observation timeout expires. + +## 2026-07-15T16:56:06Z - Phase 11 Re-Verification Iteration 2 Failed / Fix Selection Pending + +Sequential test verification passed 91/91, `make validate` passed, release-package lifecycle passed 4/4, and diagnostic parity found zero unresolved entries for all three targets. Completeness is 39/39 with 17/17 specification coverage; pragmatic, production-readiness, and reality checks permit only conditional/provisional release. Independent code review resolved the previous backup-integrity, public E3/E4, and immutable parity-wiring blockers but found four critical residuals: pathname TOCTOU, post-resolution local-source mutation, split local source/overlay provenance, and Make recipe injection boundaries. The canonical Markdown and HTML reports were rewritten with the iteration-2 verdict and Fix & Re-Verification History. A third fix-selection gate is pending. + +## 2026-07-15T17:02:52Z - Phase 11 Fix Loop Iteration 3 Started + +The user selected `Fix all fixable issues`. The terminal gate decision is persisted before implementation. This final repair iteration addresses pathname TOCTOU, local-source materialization rebinding, single-root overlay provenance, Make recipe injection boundaries, and the remaining fixable warning groups. Existing agent sessions remain open and observation timeouts will not be treated as agent failure. + +## 2026-07-15T17:36:38Z - Phase 11 Fix Loop Iteration 3 Complete / Re-Verification Pending + +All four iteration-2 blockers and the fixable warning groups were addressed. Persisted-state reads and lifecycle mutations now use descriptor-backed no-follow reads, identity revalidation, and documented ownership boundaries; local and injected source bytes are rebound before and after assembly; install/update overlays must come from the same resolved source root; direct lifecycle E3 is independently hash-bound; and caller-controlled Make values cross a validated Node argv/environment boundary instead of executable shell or inline-JavaScript interpolation. Frontmatter/reference validation and operator documentation were also hardened. Integrated validation is green: 109/109 platform-independent tests, `make validate`, deterministic package lifecycle coverage, three-target diagnostic parity with zero unresolved differences, module syntax checks, and `git diff --check`. Strict release parity still requires a clean checkout and native E6 remains explicitly unavailable where no scenario is configured. Independent re-verification is pending. + +## 2026-07-15T17:45:34Z - Phase 11 Re-Verification Iteration 3 Approved + +The user selected `Yes, re-run verification`. The terminal decision is persisted before execution and `reverify_count` is now 3. The complete test suite will run first; only after it finishes will completeness, code review, pragmatic review, production readiness, and reality assessment run in parallel. Existing agent sessions remain open and observation timeouts will not be treated as failures. + +## 2026-07-15T18:10:33Z - Phase 11 Re-Verification Iteration 3 Failed / Unresolved-Critical Decision Pending + +The sequential test verification passed 109/109, `make validate` passed, release-package lifecycle passed 4/4, and dirty-local diagnostic parity found zero unresolved differences for all three targets; strict parity correctly refused the dirty checkout. Completeness remains 39/39 with 17/17 requirement mapping, and pragmatic review recommends merge with residuals. Independent code review nevertheless found two P1 blockers: lifecycle evidence/overlay root A can diverge from independently resolved materialized root B, and caller-controlled `SUPPORTED_TARGETS` is expanded by GNU Make inside a shell recipe before Node validation. Production and reality assessments prohibit publication from the current workspace and allow only a conditional clean-release flow. The canonical Markdown and HTML verdicts were refreshed with two critical and ten warning findings. Because the maximum three repair iterations are exhausted, an explicit unresolved-critical decision is pending. + +## 2026-07-15T18:31:27Z - Workflow Stopped by User + +The user selected `Stop workflow` at the protected unresolved-critical gate. Phase 11 and the overall development task are marked failed; Phases 12 through 14 are skipped because continuation was explicitly declined. Both P1 blockers remain preserved in canonical state and verification reports. Agent sessions were not closed. + +## 2026-07-15T20:35:06Z - Phase 11 Resumed / Repair Loop Reset + +The workflow resumed explicitly from Phase 11 with `--reset-attempts`. Prior gate and repair history remains immutable, while the Phase 11 repair counter and re-verification count restarted at zero. Fresh delegated verification passed 109/109 automated tests, integrated validation, release-package lifecycle 4/4, and diagnostic parity, but independently reconfirmed the lifecycle A/B source-binding split and pre-validation `SUPPORTED_TARGETS` Make evaluation as P1 blockers. + +## 2026-07-15T20:57:56Z - Resumed Phase 11 Fix Iteration 1 Complete / Re-Verification Pending + +The user selected `Fix all fixable issues`. Lifecycle install/update now resolves or accepts one immutable source binding before creating target state, verifies any caller-supplied root and local source against it, carries that exact binding into materialization, and compares the final materialized binding field by field. A direct A/B regression proves mismatch rejection before state or target mutation. Make no longer owns or interpolates a target list: any `SUPPORTED_TARGETS` override is rejected before its value is evaluated, while `release-interface.mjs validate-overlays` enumerates the central Node registry directly. Make-function and shell-metacharacter regressions prove no sentinel execution, and a normal-path test locks the Codex/Cursor/Kiro registry order. + +Verification is green: the focused adversarial set passes 3/3, the complete platform-independent suite passes with the three new regressions, `make validate` passes, deterministic packaged lifecycle passes 4/4, diagnostic parity reports zero unresolved differences for all three targets, module syntax checks pass, and `git diff --check` passes. Strict parity continues to fail closed with `E_SOURCE_DIRTY` in the shared working tree, as required. Independent re-verification is pending. + +## 2026-07-15T21:34:52Z - Resumed Phase 11 Fix Iteration 2 Complete / Final Re-Verification Pending + +The first independent post-fix cycle accepted both production repairs and found zero production regressions, but the authoritative suite was 110/112 because two tests retained pre-fix assumptions. The existing `Fix all fixable issues` gate decision was reused idempotently. Test-only maintenance updated the topology contract to assert the non-configurable Make guard and Node-owned `validate-overlays` command, and supplied the overlay-negative fixture with a valid source-bound Git identity so it reaches the intended overlay error. The combined focused set now passes 5/5, including both P1 regressions and both formerly red tests; the complete suite and `make validate` are green. The existing `Yes, re-run verification` decision was reused idempotently for the final independent cycle. + +## 2026-07-15T22:30:35Z - Resumed Phase 11 Fix Iteration 3 Complete / Verification Passed + +The final independent cycle found one environment-coupled verification contract: raw repository traversal treated ignored `.idea/workspace.xml` changelist history as release topology. Completeness and code/security classified the file as operator residue; pragmatic review recommended a Git-aware boundary, and an independent arbiter selected tracked plus non-ignored untracked enumeration while retaining raw recursive traversal for fixtures. The final repair centralizes one fail-closed repository topology policy, scans force-added ignored and ordinary untracked files, rejects Git/read failures, and adds focused regressions without an editor-specific exclusion. + +Final evidence is green: 114/114 authoritative tests, 20/20 focused evidence/topology checks, `make validate`, direct topology with zero violations, package lifecycle 4/4, module syntax checks, and `git diff --check`. A history-preserving clean committed clone passed strict parity for Codex, Cursor, and Kiro CLI with zero unresolved differences, remained Git-clean, and generated all three packages in isolated output directories. Final completeness, code/security, pragmatic, production-readiness, reality, and implementation-verifier tracks report zero open implementation defects or regressions. Phase 11 is complete; the required `Continue to Phase 12?` gate is pending. Exact-tag publication still requires the full clean release sequence, explicit release write permission, and an emptied allowlisted same-job artifact set. + +## 2026-07-16T08:13:13Z - Phase 11 Exit Approved / Phase 12 Skipped + +The user selected `Continue to Phase 12` at the persisted Phase 11 exit gate. Phase 12 E2E browser verification was then skipped exactly as configured because `orchestrator.options.e2e_enabled` is `false`; no browser verifier was dispatched and no screenshots were created. The mandatory Phase 12 exit gate, `E2E complete. Continue to Phase 13?`, is persisted and awaiting the user's response. Phase 13 user documentation remains enabled and pending. + +## 2026-07-16T08:30:49Z - Phase 13 User Documentation Started + +The user selected `Continue to Phase 13` at the persisted Phase 12 exit gate. Phase 13 is durably in progress before delegation. The user-documentation generator will receive the absolute task path, specification path, and a CLI-only `base_url` marker; no E2E screenshot directory is supplied because Phase 12 was skipped. Outputs are restricted to the task's `documentation/` directory. + +## 2026-07-16T08:40:06Z - Phase 13 User Documentation Complete + +The CLI-focused user guide is complete at `documentation/user-guide.md`. It covers Codex, Cursor, and Kiro CLI selection; prerequisites; clean local, extracted-package, and immutable GitHub sources; install, update, status, verify, uninstall, rollback, and recovery; state/ownership/lock safety; JSON results and exit codes; E1-E6 evidence and provisional limitations; and troubleshooting. All eight documented command shapes pass the live CLI parser, every option exists, both local links and all 15 table-of-contents anchors resolve, Markdown fences are balanced, and `git diff --check` passes. Screenshots are intentionally absent because the product surface is CLI-only and Phase 12 produced none. The mandatory Phase 13 exit gate is pending. + +## 2026-07-16T09:17:19Z - Phase 14 Finalization Started + +The user selected `Continue to Phase 14` at the persisted Phase 13 exit gate. Phase 14 is durably in progress. Finalization will generate the Markdown decision summary directly from canonical `orchestrator.gate_history`, create the required HTML companion, register both artifacts, and then stop at the protected `final-handoff-approval` gate before changing the task to completed. + +## 2026-07-16T09:25:10Z - Decision Summary Complete / Final Handoff Pending + +`outputs/decision-summary.md` was generated directly from all 30 terminal canonical gate records and includes every ordered option, recommendation, selected value, actor, rationale, confidence, model configuration, retry/arbitration state, override state, idempotency key, resume history, and full-context link. All 38 relative links resolve. The required HTML companion preserves the 30/30 decision ledger and 30/30 keys in a self-contained 32,833-byte report; whitespace validation passes. Both artifacts are registered in workflow state. The denylisted `final-handoff-approval` gate is persisted as `user_pending`; the task remains in progress until the user explicitly selects `Complete workflow` or `Keep workflow open`. + +## 2026-07-16T10:33:37Z - Workflow Completed + +The user selected `Complete workflow` at the protected final-handoff gate. The terminal record is persisted as decision 31 with no advisor, arbiter, retry, override, or error. The decision summary and HTML companion were refreshed to include 31/31 decisions and idempotency keys, then the Phase 14 and overall task completion checkpoints were persisted. Final validation confirms canonical YAML parses, dashboard JavaScript parses, all summary links resolve, the HTML is self-contained and below the size limit, and `git diff --check` passes. The implementation is ready for commit and pull-request review; production publication remains conditional on the exact clean tag workflow documented in the verification and decision reports. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/orchestrator-state.yml b/.maister/tasks/development/2026-07-14-platform-independent-plugin/orchestrator-state.yml new file mode 100644 index 00000000..b49fd70c --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/orchestrator-state.yml @@ -0,0 +1,1664 @@ +orchestrator: + started_phase: phase-1 + current_phase: phase-14 + completed_phases: [phase-1, phase-2, phase-5, phase-6, phase-7, phase-8, phase-10, phase-11, phase-13, phase-14] + failed_phases: [] + auto_fix_attempts: + phase-1: 0 + phase-2: 0 + phase-3: 0 + phase-4: 0 + phase-5: 0 + phase-6: 0 + phase-7: 0 + phase-8: 0 + phase-9: 0 + phase-10: 0 + phase-11: 3 + phase-12: 0 + phase-13: 0 + phase-14: 0 + options: + html_output: true + spec_audit_enabled: true + skip_test_suite: false + e2e_enabled: false + user_docs_enabled: true + code_review_enabled: true + pragmatic_review_enabled: true + reality_check_enabled: true + production_check_enabled: true + sequential: false + advisor: + enabled: true + gate_policies: + phase-exit: fully_automatic + optional-phase: fully_automatic + clarify: fully_automatic + convergence: fully_automatic + verify-matrix: fully_automatic + advisor_agent: advisor + advisor_model: gpt-5.6-sol + arbiter_agent: arbiter + arbiter_model: gpt-5.6-sol + arbiter_enabled_on_disagreement: true + retry: + advisor_attempts: 3 + arbiter_attempts: 3 + backoff: exponential + created: "2026-07-14T16:32:58Z" + updated: "2026-07-16T10:33:37Z" + task_path: .maister/tasks/development/2026-07-14-platform-independent-plugin + task_ids: + phase-1: development-phase-1 + phase-2: development-phase-2 + phase-3: development-phase-3 + phase-4: development-phase-4 + phase-5: development-phase-5 + phase-6: development-phase-6 + phase-7: development-phase-7 + phase-8: development-phase-8 + phase-9: development-phase-9 + phase-10: development-phase-10 + phase-11: development-phase-11 + phase-12: development-phase-12 + phase-13: development-phase-13 + phase-14: development-phase-14 + gate_history: + - schema_version: 1 + idempotency_key: sha256:ec02c7f9f82f78391846592009ec9aee11bb8cb1d6d24dc1c4a45208d9328a78 + phase_id: phase-1 + gate_type: phase-1-clarification + question: "I assume the implementation scope is Codex, Cursor, and Kiro CLI only, with Claude and committed generated trees removed before completion. Is that correct?" + options: + - Confirm assumptions + - Correct assumptions + - Provide more context + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Confirm assumptions + final_actor: user + original_recommendation: Confirm assumptions + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The user confirmed the research-approved target set and migration/deletion scope." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:ba5d887d0c4265cbcbe1c13696ffdc0cf70e09b9b115fd0cea577002cb7aee7a + phase_id: phase-1 + gate_type: phase-1-exit + question: "Continue to Phase 2?" + options: + - Continue to Phase 2 + - Pause workflow + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to Phase 2 + final_actor: user + original_recommendation: Continue to Phase 2 + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The user chose to continue the development workflow into gap analysis." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:9e22d1cd8c8c8ccd768742a06292a9988d36f58656d7964e7799638229d15117 + phase_id: phase-2 + gate_type: phase-2-decision-host-contract-closure + question: "Which host-contract closure policy should the implementation adopt?" + options: + - "Contract-first overlay v1 with E1/E2/E4 for every host and E5/E6 when runtime exists" + - "Host-doc-first overlay using legacy outputs only as semantic comparison fixtures" + - "Runtime-gated support until native discovery and critical scenario evidence exist" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Contract-first overlay v1 with E1/E2/E4 for every host and E5/E6 when runtime exists" + final_actor: user + original_recommendation: "Contract-first overlay v1 with E1/E2/E4 for every host and E5/E6 when runtime exists" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The gap analyzer found that host discovery roots, native inventories, settings destinations, and semantic bindings are not yet encoded in a versioned overlay contract." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:d6c3f6d878255f05159dce1edbaff998b8ea79e84c59a7cecfe5ca12aeb92970 + phase_id: phase-2 + gate_type: phase-2-decision-settings-ownership + question: "Which settings and shell-configuration ownership contract should the implementation adopt?" + options: + - "Hybrid whole_file and managed_keys ownership with journal, backup, drift detection, and exact rollback" + - "Dedicated files only, with manual configuration where unavailable" + - "Managed-key merging for every shared settings file" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Hybrid whole_file and managed_keys ownership with journal, backup, drift detection, and exact rollback" + final_actor: user + original_recommendation: "Hybrid whole_file and managed_keys ownership with journal, backup, drift detection, and exact rollback" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The gap analyzer found that shared settings and shell configuration need explicit ownership and rollback semantics." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:a0da58fe5a1961fb662f7592b49c157c182bb70d3929cb36b7a5376a78c54e50 + phase_id: phase-2 + gate_type: phase-2-decision-native-evidence-policy + question: "Which minimum release-evidence policy should apply to hosts without native runtime?" + options: + - "Require E1-E4 and shared-core E3; record E5/E6 as unavailable, never pass" + - "Require E5/E6 before labeling any host supported" + - "Keep hosts provisional or unsupported until fresh native evidence exists" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Require E1-E4 and shared-core E3; record E5/E6 as unavailable, never pass" + final_actor: user + original_recommendation: "Require E1-E4 and shared-core E3; record E5/E6 as unavailable, never pass" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The gap analyzer found that Cursor and Kiro native continuation evidence is currently unavailable and must not be represented as a passing result." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:cc8019c200d90a666bb76ac3bae53660de40b4ed9ece30fd3779ea4351bc1064 + phase_id: phase-2 + gate_type: phase-2-decision-evidence-freshness + question: "Which evidence freshness policy should the implementation adopt?" + options: + - "Per-capability expiry with host, version, scenario, and timestamp renewal" + - "Release-bound expiry when Maister or host contract versions change" + - "No expiry beyond recorded host version and manual review" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Per-capability expiry with host, version, scenario, and timestamp renewal" + final_actor: user + original_recommendation: "Per-capability expiry with host, version, scenario, and timestamp renewal" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The gap analyzer found that capability records need explicit expiry and re-probe policy because host contracts and external binaries change independently." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:7049cc17ddbd24dd6410f8e24ac74d5fae4ccb63534d828b41f1244006b45172 + phase_id: phase-2 + gate_type: phase-2-decision-documentation-boundary + question: "Which documentation and release migration boundary should the implementation adopt?" + options: + - "Update all affected documentation, standards, Make/CI/release paths, and support matrices in this task" + - "Defer documentation migration to a follow-up" + - "Retain legacy instructions as a compatibility guide" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Update all affected documentation, standards, Make/CI/release paths, and support matrices in this task" + final_actor: user + original_recommendation: "Update all affected documentation, standards, Make/CI/release paths, and support matrices in this task" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The gap analyzer found that stale documentation and release paths would continue prescribing generated trees and Claude/marketplace workflows after the migration." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:cb8d23e0e7ad2eb2968a831e300e4a2f2c77b56b18216abfeff974cd16f1ab52 + phase_id: phase-2 + gate_type: phase-2-routing + question: "Continue to Phase 5: Technical Approach, Requirements & Specification?" + options: + - "Continue to Phase 5: Technical Approach, Requirements & Specification" + - "Pause workflow" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Continue to Phase 5: Technical Approach, Requirements & Specification" + final_actor: user + original_recommendation: "Continue to Phase 5: Technical Approach, Requirements & Specification" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The task modifies existing code, creates new installation and schema entities, and involves filesystem data operations, but has no reproducible defect or UI-heavy scope; route directly to requirements and specification." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:8358f6a9980394365c8e29349d3538166c7645e2aeb8875de965b725f22f292f + phase_id: phase-5 + gate_type: phase-5-exit + question: "Continue to specification audit?" + options: + - "Continue to specification audit" + - "Pause workflow" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Continue to specification audit" + final_actor: user + original_recommendation: "Continue to specification audit" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The specification artifacts are present and the local structural checks passed; an independent specification audit is the next recommended phase." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:eeba59811d29c2483cca234227ab77fd47023e60becab582b5c75f9a3d6994fe + phase_id: phase-6 + gate_type: phase-6-exit + question: "Continue to implementation planning?" + options: + - "Continue to implementation planning" + - "Pause workflow" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Continue to implementation planning" + final_actor: user + original_recommendation: "Continue to implementation planning" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The specification audit found the contract ready for planning with no critical or high-severity defects; two medium implementation-contract clarifications must be resolved in the plan." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:3816e7b010ce22a0a421f05dde1915496a6c69d60c72a8a783a82a76a8361265 + phase_id: phase-7 + gate_type: phase-7-exit + question: "Continue to implementation approval?" + options: + - "Continue to implementation approval" + - "Pause workflow" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Continue to implementation approval" + final_actor: user + original_recommendation: "Continue to implementation approval" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The implementation plan covers all 17 requirements in five dependency-ordered groups, freezes the two medium audit contracts, and passes structural validation with 39 synchronized progress steps." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:663a42aa519cf64427fd11758ef12c313a7364b973068f67fc85f046e6b8e17b + phase_id: phase-7 + gate_type: implementation-approval + question: "Approve this complete implementation scope?" + options: + - "Approve complete implementation scope" + - "Reject implementation scope" + - "Request scope changes" + policy: manual + configured_policy: fully_automatic + safety_classification: denylisted + status: decided + selected_option: "Approve complete implementation scope" + final_actor: user + original_recommendation: "Approve complete implementation scope" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The complete five-group implementation scope is ready for explicit protected approval; no advisor or automatic policy may authorize implementation." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:8427cbf0e377cd8f234e79d9f5346062d6bd293fe524dc517f25db71193408de + phase_id: phase-8 + gate_type: group-failure-recovery + question: "Group 1 implementation failed: delegated agent timed out without a report. How to proceed?" + options: + - "Try suggested fix" + - "Retry group" + - "Complete manually" + - "Rollback changes" + - "Stop" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Try suggested fix" + final_actor: system + original_recommendation: "Retry group" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The same Group 1 implementer session was resumed after an observation timeout and completed successfully; no retry, manual completion, rollback, or stop action was needed." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:0e17e4a7c76e0fca66e93b36dd463df1e18f93bfcfa027baae084a83f0503922 + phase_id: phase-8 + gate_type: group-failure-recovery + question: "Group 4 implementation failed: materialization parity gate is red for Codex, Cursor, and Kiro CLI inventory/vocabulary contracts. How to proceed?" + options: + - "Try suggested fix" + - "Retry group" + - "Complete manually" + - "Rollback changes" + - "Stop" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Try suggested fix" + final_actor: user + original_recommendation: "Try suggested fix" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The focused evidence/parity tests pass, but clean materializer validation fails for all three targets because Group 1-2 inventory/common-source contracts are inconsistent with the retained source tree." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:7f3c4d56a3554cb24346cdbc9f46a6e8c551345121ef316d84827f26966be760 + phase_id: phase-8 + gate_type: group-failure-recovery + question: "Group 4 implementation failed: materialization is green but real shadow parity still has 573 unresolved differences across Codex, Cursor, and Kiro CLI. How to proceed?" + options: + - "Try suggested fix" + - "Retry group" + - "Complete manually" + - "Rollback changes" + - "Stop" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Try suggested fix" + final_actor: user + original_recommendation: "Try suggested fix" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The user directed the workflow to analyze every parity difference and fix either the test when it reports an intentional packaging difference or the implementation when behavior is actually missing." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:19568792996c419f61acb934284693bd396df535db9c9b4ac814b5f6c528d7a5 + phase_id: phase-8 + gate_type: phase-8-exit + question: "Continue to verification?" + options: + - "Continue to verification" + - "Pause workflow" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Continue to verification" + final_actor: user + original_recommendation: "Continue to verification" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "All five approved implementation groups are complete; 34 focused tests pass, all three targets materialize, reviewed parity has zero unresolved differences, and final topology is clean." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:239981881b195b61ea682efd83565288e6737e9def74584192f949dbc6d517e9 + phase_id: phase-10 + gate_type: verification-options + question: "Which standard verifications to run?" + options: + - "Code review (Recommended)" + - "Pragmatic review (Recommended)" + - "Reality check (Recommended)" + - "Production readiness (Recommended)" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Code review (Recommended); Pragmatic review (Recommended); Reality check (Recommended); Production readiness (Recommended)" + final_actor: user + original_recommendation: "Run all recommended standard verifications" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The migration changes architecture, installers, filesystem transactions, CI/release behavior, and supported hosts, so all four standard verification tracks are recommended." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:98c61b5e2542abb49b807564e2ad43644f9b6443be62cba708dc99c212945c5a + phase_id: phase-10 + gate_type: optional-phase-selection/e2e + question: "Enable E2E browser verification?" + options: + - "Yes (Recommended)" + - "No, skip" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "No, skip" + final_actor: user + original_recommendation: "Yes (Recommended)" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The implementation changes installation and host integration behavior; an optional end-to-end pass can validate the assembled user-facing lifecycle beyond focused contract tests." + confidence: medium + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:430715d582c5f8acbf15c124fe155cb078622e8f8ea39e2c79f92d9958b04bb4 + phase_id: phase-10 + gate_type: optional-phase-selection/user-docs + question: "Generate user documentation?" + options: + - "Yes (Recommended)" + - "No, skip" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Yes (Recommended)" + final_actor: user + original_recommendation: "Yes (Recommended)" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The installer, supported-host set, source layout, recovery workflow, and release commands changed materially; dedicated user documentation can consolidate the new operating model." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:4faf97df6ac300025973a0db05ef2a15baaf46b02c225599fc10464dd193d969 + phase_id: phase-11 + gate_type: verification-fix-selection + question: "Which issues should I fix?" + options: + - "Fix all fixable issues" + - "Let me choose specific issues" + - "Skip fixes, proceed as-is" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Fix all fixable issues" + final_actor: user + original_recommendation: "Fix all fixable issues" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "Verification failed with five critical production blockers and sixteen warning groups despite 34/34 focused tests; all critical issues and most warnings are fixable within the approved architecture." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:198f8c6133aeb3ec728a3f71473293f3f72dcc7f7e72b7aa48b0e9c4367dd9c1 + phase_id: phase-11 + gate_type: verification-rerun + question: "Re-run verification to check fixes?" + options: + - "Yes, re-run verification" + - "No, proceed to the next phase" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Yes, re-run verification" + final_actor: user + original_recommendation: "Yes, re-run verification" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "Fix iteration 1 changed transaction safety, release packaging, immutable source resolution, evidence, materialization validation, target policy, Cursor projection, CI, tests, and documentation; 60/60 focused tests and make validate now pass, so independent re-verification is recommended." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:6921f6d132122613094ce1e600a5d075a682cd0557d4341a33ffcaf2e39815ec + phase_id: phase-11 + gate_type: verification-fix-selection + question: "Which issues should I fix?" + options: + - "Fix all fixable issues" + - "Let me choose specific issues" + - "Skip fixes, proceed as-is" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Fix all fixable issues" + final_actor: user + original_recommendation: "Fix all fixable issues" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "Re-verification passes 60/60 tests but found four residual critical blockers and ten warnings; the critical issues are fixable within a second repair iteration." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:34eed63ef305b80ab06583847d5489291da6c39ed01a71bbb088ebb412d433be + phase_id: phase-11 + gate_type: verification-rerun + question: "Re-run verification to check fixes?" + options: + - "Yes, re-run verification" + - "No, proceed to the next phase" + policy: manual + configured_policy: manual + safety_classification: configurable + status: decided + selected_option: "Yes, re-run verification" + final_actor: user + original_recommendation: "Yes, re-run verification" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "Fix iteration 2 closes the four residual critical findings and the fixable warning groups; 91/91 platform-independent tests, 4/4 packaged lifecycle tests, clean-checkout three-target parity with zero unresolved differences, make validate, and git diff --check now pass. Independent re-verification is recommended." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b0651b64f08d41434582be22a7b6f1b659a40d0f9faa356884dc366d93300f2a + phase_id: phase-11 + gate_type: verification-fix-selection + question: "Which issues should I fix?" + options: + - "Fix all fixable issues" + - "Let me choose specific issues" + - "Skip fixes, proceed as-is" + policy: manual + configured_policy: manual + safety_classification: configurable + status: decided + selected_option: "Fix all fixable issues" + final_actor: user + original_recommendation: "Fix all fixable issues" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "Re-verification iteration 2 passes 91/91 tests and resolves backup integrity, public E3/E4 ordering, and immutable parity wiring, but independent code review found four new or residual P1 blockers: pathname TOCTOU, post-resolution local-source mutation, split local source/overlay provenance, and Make recipe injection boundaries. All four are fixable." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:0ff4b47f90b0bdeac3716368d31f017fae20a732dc012d511834a5c49d1f7c0e + phase_id: phase-11 + gate_type: verification-rerun + question: "Re-run verification to check fixes?" + options: + - "Yes, re-run verification" + - "No, proceed to the next phase" + policy: manual + configured_policy: manual + safety_classification: configurable + status: decided + selected_option: "Yes, re-run verification" + final_actor: user + original_recommendation: "Yes, re-run verification" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "Fix iteration 3 addresses all four iteration-2 blockers and the fixable warning groups. Integrated validation passes 109/109 platform-independent tests, make validate, deterministic package lifecycle coverage, three-target diagnostic parity with zero unresolved differences, syntax checks, and git diff --check. Independent re-verification is recommended." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:3c9a3ae5d02a4d3badb43d3c03f40df5149a06021c9bcc48e3bed2d32803015d + phase_id: phase-11 + gate_type: unresolved-critical + question: "Proceed with known issues?" + options: + - "Proceed with known issues" + - "Stop workflow" + policy: manual + configured_policy: manual + safety_classification: protected + status: decided + selected_option: "Stop workflow" + final_actor: user + original_recommendation: "Stop workflow" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "Independent re-verification iteration 3 passes 109/109 tests but finds two P1 blockers: lifecycle source binding can split overlay/evidence root A from materialized root B, and caller-controlled SUPPORTED_TARGETS is expanded by GNU Make before Node validation. The maximum three repair iterations are exhausted." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b38801fbc024277030edaf7d11b3461eac96c4fcb2402dda48ee0d161f5f1f01 + phase_id: phase-11 + gate_type: verification-fix-selection + question: "Which issues should I fix?" + options: + - "Fix all fixable issues" + - "Let me choose specific issues" + - "Skip fixes, proceed as-is" + policy: manual + configured_policy: manual + safety_classification: configurable + status: decided + selected_option: "Fix all fixable issues" + final_actor: user + original_recommendation: "Fix all fixable issues" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The user selected the recommended option to repair both remaining P1 trust-boundary defects." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:949c1c70eecbf5b542f80cfb36dc9f5090ec10164e69582d0727f8e47ed16346 + phase_id: phase-11 + gate_type: phase-11-exit + question: "Continue to Phase 12?" + options: + - "Continue to Phase 12" + - "Pause workflow" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Continue to Phase 12" + final_actor: user + original_recommendation: "Continue to Phase 12" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The user selected option 1 at the mandatory Phase 11 exit gate after final implementation verification passed." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:5d3db71e7a2ecdaf6c5f3b8638d2ffd3418ea06b44e4aa52e4220cfe59c4992c + phase_id: phase-12 + gate_type: phase-12-exit + question: "E2E complete. Continue to Phase 13?" + options: + - "Continue to Phase 13" + - "Pause workflow" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Continue to Phase 13" + final_actor: user + original_recommendation: "Continue to Phase 13" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The user selected option 1 at the mandatory Phase 12 exit gate after E2E was skipped by configuration." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:4190f0156e5926ddbfbb8dc4a7f936990fca079a77de6d4a9b2fd6262f1193ba + phase_id: phase-13 + gate_type: phase-13-exit + question: "Documentation complete. Continue to Phase 14?" + options: + - "Continue to Phase 14" + - "Pause workflow" + policy: manual + configured_policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "Continue to Phase 14" + final_actor: user + original_recommendation: "Continue to Phase 14" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The user selected option 1 at the mandatory Phase 13 exit gate after the validated CLI user guide was completed." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:6d7f6ae8df3ed9da15c045e924b897b137471f0083602540051e6cd0bb590c6e + phase_id: phase-14 + gate_type: final-handoff-approval + question: "Complete workflow or keep it open?" + options: + - "Complete workflow" + - "Keep workflow open" + policy: manual + configured_policy: fully_automatic + safety_classification: denylisted + status: decided + selected_option: "Complete workflow" + final_actor: user + original_recommendation: "Complete workflow" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "The user selected option 1 and explicitly approved the final implementation, verification, documentation, and decision-summary handoff." + confidence: high + escalate_to_user: false + user_override: false + error: null + implementation_approval: + status: approved + approved_by: user + approved_at: "2026-07-14T19:08:52Z" + approved_scope: + - implementation/implementation-plan.md + - "Group 1: portable common contracts and versioned host overlays" + - "Group 2: immutable source resolver and host materializer" + - "Group 3: transactional installer, settings ownership, receipts, and recovery" + - "Group 4: evidence, parity, legacy deletion, documentation, and release updates" + - "Group 5: focused test review and completion evidence" + - "All 17 requirements mapped by the implementation plan" + task_context: + risk_level: high + clarifications_resolved: true + scope_expanded: true + architecture_decision: "Portable common core with explicit host overlays and transactional installer" + tech_clarified: true + task_characteristics: + has_reproducible_defect: false + modifies_existing_code: true + creates_new_entities: true + involves_data_operations: true + ui_heavy: false + research_reference: + path: .maister/tasks/research/2026-07-14-platform-independent-plugin + research_question: "Przeanalizować, jak zastąpić generowanie i osobne testowanie wariantów dla wielu hostów jednym rozwiązaniem niezależnym od narzędzia, z rozróżnieniem platformy możliwym na etapie instalacji." + research_type: mixed + confidence_level: high + design_reference: + source: null + product_design_path: null + mockup_count: 0 + has_brief: false + index_path: null + phase_summaries: + research: + summary: "Research recommends one portable behavior/runtime core, explicit Codex/Cursor/Kiro CLI overlays, and a transactional install-time assembler. Legacy generated trees and Claude support are migration-only scope and must be removed before completion." + key_findings: + - "Generic skills and core runtime can be shared; installed layouts remain host-native." + - "Typed semantic primitives should be introduced selectively for control flow, safety, persistence, and capability-sensitive operations." + - "The installer needs staging, validation, receipt ownership, atomic commit, recovery, and byte-exact rollback." + - "Core tests run once; overlay, materialization, installation, and available host probes remain per host." + recommended_approach: "Portable common core plus repository-owned host overlays and a custom transactional installer." + decisions_made: + - "Use minimal semantic primitives rather than a full workflow DSL." + - "Support Codex, Cursor, and Kiro CLI with explicit overlays; remove Claude from this task." + - "Use legacy generated trees only as a shadow comparison oracle, then delete them before completion." + codebase_analysis: + summary: "The repository is a build-time generated architecture: a Claude-oriented canonical tree feeds three rewrite-heavy host builders and three committed projections. Portable ESM state/gate/continuation modules and transactional configuration tests are reusable foundations, while overlay contracts, target-aware assembly, receipt-backed installation, and topology-safe rollback are missing." + key_files: + - plugins/maister/skills/orchestrator-framework/bin/gate-evaluator.mjs + - plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-repository.mjs + - plugins/maister/skills/orchestrator-framework/bin/orchestrator-state-schema.mjs + - plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs + - plugins/maister/skills/orchestrator-framework/bin/workflow-continuation.mjs + - platforms/codex-cli/build.sh + - platforms/cursor/build.sh + - platforms/kiro-cli/build.sh + - Makefile + - tests/phase-continue-contract.test.sh + - tests/advisor-config-reconciliation.test.sh + - tests/advisor-init-lifecycle.test.sh + - plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml + primary_language: "Markdown/YAML with Bash and JavaScript ESM" + decisions: + - "The five byte-identical orchestrator runtime modules are the initial portable-core boundary." + - "Host-specific semantic behavior belongs in explicit overlays rather than global prose rewrites." + - "Core behavior is tested once; host seams retain targeted contract, install, and native evidence tests." + risks: + - "Current installers mutate or clear destinations before a complete transactional validation boundary." + - "Current CI and docs assume committed generated trees and four hosts, including Claude." + - "Deleting legacy trees before parity evidence could lose portable behavioral content hidden in Claude-native files." + artifacts: + - path: analysis/codebase-analysis.md + label: Codebase analysis + html: null + clarifications: + summary: "The user confirmed the research-approved target set and migration scope: Codex, Cursor, and Kiro CLI are supported; Claude and committed generated trees are temporary migration oracles and must be removed before completion." + decisions: + - "Support Codex, Cursor, and Kiro CLI only in the completed implementation." + - "Use legacy generated trees/builders for shadow comparison only, then delete them before completion." + risks: + - "Parity and deletion criteria must be explicit and testable before legacy removal." + artifacts: + - path: analysis/clarifications.md + label: Phase 1 clarifications + html: null + clarifications: [] + gap_analysis: + summary: "The repository remains organized around a Claude-oriented source, three rewrite-heavy builders, three committed generated projections, and host-specific installers. The byte-identical runtime modules and existing transactional tests provide reusable foundations, but the common overlay contract, target-aware installer lifecycle, structured evidence model, and final three-host topology are missing. This is a high-risk, high-effort migration because source ownership, installation safety, compatibility policy, CI/release behavior, and documentation change together." + risk_level: high + effort_estimate: high + change_type: modificative + compatibility_requirements: strict + task_characteristics: + has_reproducible_defect: false + modifies_existing_code: true + creates_new_entities: true + involves_data_operations: true + ui_heavy: false + integration_points: + - common portable source and runtime ownership + - Codex, Cursor, and Kiro CLI host overlays + - target-aware installer and source resolver + - overlay, primitive, evidence, receipt, and journal schemas + - Makefile, CI, release, and repository-topology validation + - host settings, MCP, hooks, manifests, and native evidence + - README, host support docs, project docs, and standards + decisions: + - "Use minimal typed primitives rather than a full workflow DSL." + - "Use one common layer with explicit Codex, Cursor, and Kiro CLI overlays and a custom installer." + - "Use legacy generated trees only as a migration shadow oracle, then remove them before task completion." + - "Remove Claude Code from supported targets and require a separate future host-integration task for reintroduction." + - "Apply capability-sensitive compatibility: semantic boundaries fail closed and packaging-only differences may be provisional." + - "Test the portable core once and retain per-host overlay, materialization, installation, and available native evidence tests." + risks: + - "Semantic drift in gates, delegation, hooks, progress, and continuation can survive structural parity." + - "Partial installation or settings mutation can damage user state without journaled byte-exact recovery." + - "Incorrect semantic-versus-packaging classification can permit unsafe provisional compatibility." + - "Removing legacy before post-release observation increases the importance of parity and failure-injection gates." + - "Stale documentation and CI can continue directing users toward unsupported Claude and generated-tree workflows." + decisions_needed: + critical: + - id: host-contract-closure + issue: "Exact discovery roots, native inventories, settings destinations, and semantic bindings are not yet encoded in versioned overlays." + options: + - "Contract-first overlay v1 with E1/E2/E4 for every host and E5/E6 when runtime exists" + - "Host-doc-first overlay using legacy outputs only as semantic comparison fixtures" + - "Runtime-gated support until native discovery and critical scenario evidence exist" + recommendation: "Contract-first overlay v1" + - id: settings-ownership + issue: "Shared settings and shell configuration require explicit ownership and rollback semantics." + options: + - "Hybrid whole_file and managed_keys ownership with journal, backup, drift detection, and exact rollback" + - "Dedicated files only, with manual configuration where unavailable" + - "Managed-key merging for every shared settings file" + recommendation: "Hybrid ownership contract" + important: + - id: native-evidence-policy + issue: "Cursor and Kiro native continuation evidence is currently unavailable." + options: + - "Require E1-E4 and shared-core E3; record E5/E6 as unavailable, never pass" + - "Require E5/E6 before labeling any host supported" + - "Keep hosts provisional or unsupported until fresh native evidence exists" + default: "Require E1-E4 and shared-core E3; record E5/E6 as unavailable" + - id: evidence-freshness + issue: "Capability records need an explicit expiry and re-probe policy." + options: + - "Per-capability expiry with host, version, scenario, and timestamp renewal" + - "Release-bound expiry when Maister or host contract versions change" + - "No expiry beyond recorded host version and manual review" + default: "Per-capability expiry" + - id: documentation-boundary + issue: "Documentation, standards, CI, and release paths still prescribe generated trees and Claude/marketplace workflows." + options: + - "Update all affected documentation, standards, Make/CI/release paths, and support matrices in this task" + - "Defer documentation migration to a follow-up" + - "Retain legacy instructions as a compatibility guide" + default: "Update all affected documentation and release paths in this task" + scope_expansion_recommended: true + critical_issues: + - "No neutral common/host overlay, shared installer, receipt, journal, or schema implementation exists." + - "Cursor and Kiro installers delete or clear destinations before complete validation and commit." + - "Host semantics are implemented through large global rewrite lists without a shared binding-completeness contract." + - "Claude, committed generated trees, generated-tree CI, and legacy documentation still conflict with the accepted target architecture." + artifacts: + - path: analysis/gap-analysis.md + label: Gap analysis report + html: null + scope_clarifications: + summary: null + scope_expanded: null + decisions: [] + risks: [] + artifacts: [] + ui_mockups: + summary: null + components_designed: [] + decisions: [] + risks: [] + artifacts: [] + design: + summary: null + screen_count: 0 + component_count: 0 + index_path: null + decisions: [] + risks: [] + artifacts: [] + specification: + summary: "The specification defines a portable common source, explicit Codex/Cursor/Kiro CLI overlays, and a shared target-aware installer with immutable provenance, staged validation, journaled receipts, hybrid settings ownership, capability-sensitive evidence, rollback, and legacy deletion criteria. It also aligns core-once/per-host testing and all documentation, standards, CI, and release paths with the new topology." + goal: "Replace generated host variants with one portable source and safe install-time target selection." + requirements_count: 17 + reusable_components: 10 + new_components_needed: 7 + visual_assets_referenced: 0 + test_groups_estimated: 6 + decisions: + - "Use a portable common layer plus explicit host overlays because native layouts remain host-specific while behavior should be owned once." + - "Treat the installer as a transaction manager because user state and settings require staged validation, receipts, recovery, and rollback." + - "Use capability-sensitive compatibility because semantic boundaries must fail closed while packaging-only differences can be provisional." + - "Delete Claude and generated trees only after zero-unresolved-difference shadow parity and failure-injection evidence." + risks: + - "Native E5/E6 evidence may remain unavailable for Cursor and Kiro." + - "Shared settings and shell files can be damaged without journaled ownership and exact rollback." + - "Textual parity can conceal semantic drift in gates, delegation, hooks, and continuation." + - "Legacy deletion removes the current rollback oracle and depends on complete parity evidence." + artifacts: + - path: analysis/requirements.md + label: Requirements + html: null + - path: analysis/technical-clarifications.md + label: Technical clarifications + html: null + - path: implementation/spec.md + label: Specification + html: implementation/spec.html + spec_audit: + summary: "The specification is Mostly Compliant as a pre-implementation contract: all 17 requirements map to the research decisions, current-state gaps, and migration exit criteria. There are no critical or high-severity specification defects; two medium clarifications remain around the exact installer/receipt contract and the field-level overlay schema." + compliance_status: "Mostly Compliant" + requirements_checked: 17 + requirements_passed: 17 + finding_counts: + critical: 0 + high: 0 + medium: 2 + low: 2 + decisions: + - "Treat current legacy implementation gaps as expected pre-implementation state because the specification explicitly covers migration and deletion criteria." + - "Freeze exact installer/receipt and overlay schema contracts in the implementation plan before implementation approval." + risks: + - "Native E5/E6 evidence may remain unavailable for Cursor and Kiro." + - "Shared settings and shell files require exact journaled rollback." + - "Textual parity can conceal semantic drift." + artifacts: + - path: verification/spec-audit.md + label: Specification audit + html: null + implementation_plan: + summary: "The plan organizes the migration into four serialized implementation groups plus a focused test-review group. It freezes overlay v1 and the installer CLI/error/receipt/journal contracts, preserves legacy outputs until parity and failure-injection evidence pass, and caps the feature suite at 34 tests." + task_groups: 5 + total_steps: 39 + expected_tests: "26-34" + has_testing_group: true + has_visual_coverage: false + decisions: + - "Keep plugins/maister as the single common source and represent host differences in strict versioned overlays." + - "Serialize overlay, materializer, installer, and legacy-removal groups because each freezes an interface consumed by the next." + - "Use one Node ESM lifecycle command with stable machine-readable errors, receipt v1, and journal v1." + - "Delete Claude support, old builders, and generated trees only after zero-unresolved parity and exact recovery evidence." + risks: + - "Cursor and Kiro E5/E6 may remain unavailable and must never be promoted to passed." + - "Shared settings require journaled multi-file recovery in addition to atomic managed-tree replacement." + - "A real immutable GitHub smoke probe depends on release-environment network availability." + - "No performance threshold is introduced in this migration." + artifacts: + - path: implementation/implementation-plan.md + label: Implementation plan + html: implementation/implementation-plan.html + architecture_decision: + decision: "Portable common core with explicit host overlays and transactional installer" + summary: "Use typed semantic bindings only where host choice can change control flow, safety, persistence, or capability evidence." + decisions: [] + risks: [] + artifacts: [] + implementation_verification: + summary: "Final Phase 11 verification passes all 39 plan steps and 17 requirements with 114/114 authoritative tests, 20/20 focused evidence/topology checks, make validate, package lifecycle 4/4, and clean strict parity for all three targets with zero unresolved differences. Both former P1s, both stale test contracts, and the environment-coupled topology contract are resolved with zero production or test regressions." + status: passed + issue_counts: + critical: 0 + warning: 0 + info: 0 + decisions: + - "Carry one immutable source binding through overlay selection, materialization, evidence, and receipt publication." + - "Keep supported-target ownership in the central Node registry and reject Make-level target-list overrides." + - "Scan repository topology through tracked plus non-ignored untracked Git candidates while retaining raw fixture traversal." + - "Separate the passed implementation verdict from exact-tag publication controls." + risks: + - "The exact tag commit must repeat the complete clean release sequence before publication." + - "Native E6 remains unavailable where no reviewed host runtime scenario exists." + - "Unsigned provenance and cooperative-writer limits remain explicit release boundaries." + artifacts: + - path: verification/implementation-verification.md + label: Implementation verification + html: verification/implementation-verification.html + - path: verification/test-suite-results.md + label: Test suite results + html: null + - path: verification/completeness-check.md + label: Completeness check + html: null + - path: verification/code-review-report.md + label: Code review + html: null + - path: verification/pragmatic-review.md + label: Pragmatic review + html: null + - path: verification/production-readiness-report.md + label: Production readiness + html: null + - path: verification/reality-check.md + label: Reality assessment + html: null + finalization: + summary: "The canonical 31-record decision ledger and its self-contained HTML companion are complete. The user explicitly approved the denylisted final handoff, and the workflow completion checkpoint is durable." + decisions: + - "Generate the final summary only from canonical gate history." + - "Preserve all alternatives, recommendations, rationales, confidence, retry/arbitration state, overrides, and idempotency keys." + - "Do not mark the task completed before protected final-handoff approval." + risks: + - "Production publication remains conditional on the exact clean tag workflow." + artifacts: + - path: outputs/decision-summary.md + label: Decision summary + html: outputs/decision-summary.html + advisor: + summary: null + decisions: [] + risks: [] + artifacts: [] + project_context: + project_doc_paths: + - .maister/docs/project/vision.md + - .maister/docs/project/roadmap.md + - .maister/docs/project/tech-stack.md + - .maister/docs/project/architecture.md + +task: + title: "Implement platform-independent Maister distribution" + description: "Przeanalizować, jak zastąpić generowanie i osobne testowanie wariantów dla wielu hostów jednym rozwiązaniem niezależnym od narzędzia, z rozróżnieniem platformy możliwym na etapie instalacji." + status: completed + tags: [development, architecture, portability, installation, testing] + priority: high + +verification_context: + last_status: passed + issues_found: [] + fixes_applied: + - "Resumed iteration 3: replaced checkout-wide raw topology validation with one shared fail-closed Git-aware repository policy covering tracked, non-ignored untracked, and force-added ignored files while preserving raw fixture traversal." + - "Resumed iteration 2: updated the topology contract to assert the non-configurable Make guard and Node validate-overlays delegation instead of the removed unsafe target declaration." + - "Resumed iteration 2: supplied the overlay-negative fixture with a valid source-bound Git identity so it reaches the intended E_OVERLAY_IO boundary." + - "Resumed iteration 1: bound lifecycle overlay, E3, and materialization to one prevalidated immutable source binding; direct A/B mismatch now fails before target-state creation." + - "Resumed iteration 1: removed Make-owned target enumeration, rejected SUPPORTED_TARGETS overrides before evaluation, and delegated all-target validation to the central Node registry." + - "Rejected symlink and persisted-path escapes across target, state, staging, settings, receipts, journals, backups, recovery, uninstall, and rollback." + - "Made managed-tree publication atomic by staged rename and hardened durability with fsync and private state/backup modes." + - "Made recovery and rollback ordered, idempotent, pointer-complete, transition-validated, and explicitly failure-journaled." + - "Preserved existing settings modes and use secure defaults for new settings files." + - "Implemented strict receipt/journal schemas and bound full source, overlay, materialized, and provenance hashes to complete E1-E6 evidence." + - "Added bounded host and Git timeouts; unavailable native evidence remains explicit and never becomes passed." + - "Made release archives self-contained, deterministic, checksumed, target-isolated, and lifecycle-tested after extraction." + - "Implemented bounded immutable GitHub resolution and strict clean local-ref provenance from the same checkout used for overlays." + - "Pinned release actions, removed unpinned swallowed Cursor installation, and validate all three targets in release CI." + - "Hardened complete-output materialization validation for containment, vocabulary, syntax, references, inventories, types, modes, and hashes." + - "Converted Cursor skills into a deterministic versioned projection with drift checking and hash-locked exceptions." + - "Centralized supported-target policy and linked Make's declarative target list to registry tests." + - "Removed brittle parity exact-count assertions while retaining immutable fingerprints and strong safety invariants." + - "Isolated mutable source fixtures so concurrent focused runs do not interfere." + - "Removed stale active Claude instructions and documented package, source, recovery, permissions, evidence, and operator workflows accurately." + - "Added descriptor-backed path identity snapshots and fail-closed pre/post mutation revalidation, including adversarial staging-parent symlink-swap coverage." + - "Cryptographically bound backup bytes, modes, symlink targets, existence, and directory topology; verify backups before restore and restored state afterward." + - "Clean successful recovery staging/orphan receipt residue while preserving forensic artifacts and code-7 rollback_failed state on recovery failure." + - "Replaced synthesized E3 with a strict portable-core attestation and finalize E4 only after commit and integrity verification before final receipt publication." + - "Verified injected GitHub resolver roots, commits, cleanliness, and hashes; strengthened strict frontmatter and internal-reference validation." + - "Added immutable clean-checkout three-target parity reconstruction with zero unresolved differences and made it a release dependency." + - "Made archive ordering explicit, pinned validation actions, removed active stale Claude wording, and generated verified checksums, CycloneDX SBOM, and provenance metadata." + - "Generated and embedded one deterministic E3 attestation after make test-core, bound it into all packages and release metadata, and proved fail-closed negative cases." + - "Removed remaining duplicated target policy from journal and CLI validation in favor of the central target registry." + - "Added descriptor-backed no-follow reads and mutation ownership boundaries for receipts, journals, recovery manifests, backups, settings, active pointers, and transaction publication, with adversarial parent/leaf replacement coverage." + - "Rebound local and injected source bytes before and after assembly, including dirty-local status fingerprints, and bound transaction E3 directly to the independently recomputed portable-core hash." + - "Removed running-checkout overlay fallback for install/update so source and overlay share one resolved root; verify, uninstall, and rollback retain receipt/package-backed lifecycle behavior." + - "Moved Make packaging, E3, parity, topology, and install inputs through a validated Node argv/environment boundary and added shell/JavaScript injection tests." + - "Normalized and validated BOM/CRLF frontmatter and rejected malformed or unsupported internal-reference grammar." + decisions_made: + - "All four standard verification tracks enabled; E2E skipped; user documentation enabled." + - "Re-verification iteration 1 failed with 4 critical, 10 warning, and 3 informational residuals despite 60/60 tests." + - "The user selected all fixable residual issues for Phase 11 fix iteration 2." + - "Fix iteration 2 completed with 91/91 platform-independent tests, 4/4 packaged lifecycle tests, zero-unresolved three-target parity, make validate, and git diff --check passing; independent re-verification is pending." + - "Re-verification iteration 2 failed with 4 critical blockers and 10 warnings despite 91/91 tests; backup integrity, public E3/E4 ordering, and immutable parity wiring are independently resolved." + - "The user selected all fixable issues for the final Phase 11 fix iteration 3." + - "Fix iteration 3 completed with 109/109 platform-independent tests, make validate, zero-unresolved three-target diagnostic parity, syntax checks, and git diff --check passing; independent re-verification is pending." + - "The user approved independent re-verification iteration 3 after the final repair loop." + - "Re-verification iteration 3 failed with 2 critical blockers and 10 warnings despite 109/109 tests; the three-attempt repair loop is exhausted and unresolved-critical approval is required." + - "The user selected Stop workflow at the unresolved-critical gate; Phase 11 and the overall task are failed with both P1 blockers preserved." + - "The resumed Phase 11 baseline independently reconfirmed both P1 blockers with 109/109 tests otherwise passing; fix selection is pending." + - "The user selected all fixable issues for resumed Phase 11 repair iteration 1." + - "Resumed fix iteration 1 completed with focused adversarial tests 3/3, full suite, make validate, package lifecycle 4/4, zero-unresolved diagnostic parity, syntax checks, and patch hygiene passing." + - "The existing terminal verification-rerun decision was reused idempotently: Yes, re-run verification." + - "Resumed fix iteration 2 repaired both stale test contracts; focused combined coverage passes 5/5 and the complete suite plus make validate are green." + - "The existing terminal verification-rerun decision was reused idempotently for final independent verification." + - "The final topology-contract repair passed 114/114 authoritative tests, 20/20 focused topology/evidence checks, make validate, clean strict parity 3/3 with zero unresolved differences, clean topology, and all three package builds." + - "Final independent verification passed with zero critical, warning, informational, production, or test-regression findings; exact-tag publication controls remain separate release conditions." + reverify_count: 3 + +phases: + - id: phase-1 + name: Analyze codebase & clarify requirements + status: completed + blocked_by: [] + started: "2026-07-14T16:32:58Z" + completed: "2026-07-14T16:56:57Z" + gate: + question: "Continue to Phase 2?" + options: + - Continue to Phase 2 + - Pause workflow + answer: Continue to Phase 2 + status: decided + - id: phase-2 + name: Analyze gaps & clarify scope + status: completed + blocked_by: [phase-1] + started: "2026-07-14T16:56:57Z" + completed: "2026-07-14T17:55:57Z" + gate: + question: "Continue to Phase 5: Technical Approach, Requirements & Specification?" + options: + - "Continue to Phase 5: Technical Approach, Requirements & Specification" + - "Pause workflow" + recommendation: "Continue to Phase 5: Technical Approach, Requirements & Specification" + answer: "Continue to Phase 5: Technical Approach, Requirements & Specification" + status: decided + - id: phase-3 + name: Write failing test (TDD Red) + status: skipped + blocked_by: [phase-2] + started: null + completed: "2026-07-14T17:55:57Z" + skip_reason: "Skipped by routing: the task is not defect-driven and the workflow routes directly to requirements and specification." + gate: null + - id: phase-4 + name: Generate UI mockups + status: skipped + blocked_by: [phase-2] + started: null + completed: "2026-07-14T17:55:57Z" + skip_reason: "Skipped by routing: gap analysis found no UI-heavy scope." + gate: null + - id: phase-5 + name: Gather requirements & create specification + status: completed + blocked_by: [phase-2, phase-3, phase-4] + started: "2026-07-14T17:55:57Z" + completed: "2026-07-14T18:19:59Z" + gate: + question: "Continue to specification audit?" + options: + - "Continue to specification audit" + - "Pause workflow" + recommendation: "Continue to specification audit" + answer: "Continue to specification audit" + status: decided + - id: phase-6 + name: Audit specification + status: completed + blocked_by: [phase-5] + started: "2026-07-14T18:19:59Z" + completed: "2026-07-14T18:36:21Z" + gate: + question: "Continue to implementation planning?" + options: + - "Continue to implementation planning" + - "Pause workflow" + recommendation: "Continue to implementation planning" + answer: "Continue to implementation planning" + status: decided + - id: phase-7 + name: Plan implementation + status: completed + blocked_by: [phase-6] + started: "2026-07-14T18:36:21Z" + completed: "2026-07-14T18:54:09Z" + gate: + question: "Continue to implementation approval?" + options: + - "Continue to implementation approval" + - "Pause workflow" + recommendation: "Continue to implementation approval" + answer: "Continue to implementation approval" + status: decided + - id: phase-8 + name: Execute implementation + status: completed + blocked_by: [phase-7] + started: "2026-07-14T19:08:52Z" + completed: "2026-07-14T22:12:26Z" + gate: + question: "Continue to verification?" + options: + - "Continue to verification" + - "Pause workflow" + recommendation: "Continue to verification" + answer: "Continue to verification" + status: decided + - id: phase-9 + name: Verify test passes (TDD Green) + status: skipped + blocked_by: [phase-8] + started: null + completed: "2026-07-15T12:40:53Z" + skip_reason: "Skipped by routing: Phase 3 TDD Red was not executed because the task was not defect-driven." + gate: null + - id: phase-10 + name: Prompt verification options + status: completed + blocked_by: [phase-8, phase-9] + started: "2026-07-15T12:40:53Z" + completed: "2026-07-15T12:47:27Z" + gate: + question: "Generate user documentation?" + options: + - "Yes (Recommended)" + - "No, skip" + recommendation: "Yes (Recommended)" + answer: "Yes (Recommended)" + status: decided + - id: phase-11 + name: Verify implementation & resolve issues + status: completed + blocked_by: [phase-10] + started: "2026-07-15T18:46:53Z" + completed: "2026-07-15T22:30:35Z" + gate: + idempotency_key: sha256:949c1c70eecbf5b542f80cfb36dc9f5090ec10164e69582d0727f8e47ed16346 + gate_type: phase-11-exit + question: "Continue to Phase 12?" + options: + - "Continue to Phase 12" + - "Pause workflow" + recommendation: "Continue to Phase 12" + answer: "Continue to Phase 12" + status: decided + - id: phase-12 + name: Run E2E tests + status: skipped + blocked_by: [phase-11] + started: null + completed: "2026-07-16T08:13:13Z" + skip_reason: "Skipped by configured verification options: orchestrator.options.e2e_enabled is false." + gate: + idempotency_key: sha256:5d3db71e7a2ecdaf6c5f3b8638d2ffd3418ea06b44e4aa52e4220cfe59c4992c + gate_type: phase-12-exit + question: "E2E complete. Continue to Phase 13?" + options: + - "Continue to Phase 13" + - "Pause workflow" + recommendation: "Continue to Phase 13" + answer: "Continue to Phase 13" + status: decided + - id: phase-13 + name: Generate user documentation + status: completed + blocked_by: [phase-12] + started: "2026-07-16T08:30:49Z" + completed: "2026-07-16T08:40:06Z" + skip_reason: null + gate: + idempotency_key: sha256:4190f0156e5926ddbfbb8dc4a7f936990fca079a77de6d4a9b2fd6262f1193ba + gate_type: phase-13-exit + question: "Documentation complete. Continue to Phase 14?" + options: + - "Continue to Phase 14" + - "Pause workflow" + recommendation: "Continue to Phase 14" + answer: "Continue to Phase 14" + status: decided + - id: phase-14 + name: Finalize workflow + status: completed + blocked_by: [phase-11, phase-12, phase-13] + started: "2026-07-16T09:17:19Z" + completed: "2026-07-16T10:33:37Z" + skip_reason: null + gate: + idempotency_key: sha256:6d7f6ae8df3ed9da15c045e924b897b137471f0083602540051e6cd0bb590c6e + gate_type: final-handoff-approval + question: "Complete workflow or keep it open?" + options: + - "Complete workflow" + - "Keep workflow open" + recommendation: "Complete workflow" + answer: "Complete workflow" + status: decided diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/outputs/decision-summary.html b/.maister/tasks/development/2026-07-14-platform-independent-plugin/outputs/decision-summary.html new file mode 100644 index 00000000..292402e2 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/outputs/decision-summary.html @@ -0,0 +1,275 @@ + + + + +Decision Summary — Platform-Independent Maister Distribution + + + + + +
+
+ Decision Summary +

Platform-Independent Maister Distribution

+
Generated 2026-07-16 · Development workflow · Implement platform-independent Maister distribution
+
+
+ Current status + Completed +
+
+ +
+
17/17requirements
+
39/39plan steps
+
114/114authoritative tests
+
20/20focused tests
+
31terminal gates
+
+ +
+

TL;DR

+

The workflow implemented and independently verified one portable Maister source with explicit Codex, Cursor, and Kiro CLI overlays, a transactional installer, immutable source and evidence binding, deterministic packaging, and removal of Claude and committed generated host trees.

+

Implementation verification passed with 39/39 plan steps, 17/17 requirements, 114/114 authoritative tests, 20/20 focused evidence/topology tests, package lifecycle 4/4, and clean strict parity for all three targets with zero unresolved differences. Phase 12 E2E browser verification was intentionally skipped by user choice; Phase 13 produced a validated CLI user guide. The user approved the denylisted final handoff, and Phase 14 plus the overall task are durably completed.

+
+ +
+
+

Key Decisions

+
    +
  • Support exactly Codex, Cursor, and Kiro CLI; remove Claude and generated/marketplace projections.
    • +
  • Use one common portable source plus strict, versioned target overlays.
    • +
  • Use hybrid whole_file and managed_keys settings ownership with receipts, journals, backups, drift detection, recovery, and exact rollback.
    • +
  • Require E1–E4 and shared-core E3; record unavailable E5/E6 honestly and never promote unavailable evidence to passed.
    • +
  • Bind install/update overlay selection, materialization, E3 evidence, and receipts to one immutable source identity.
    • +
  • Keep supported-target enumeration in the central Node registry, outside caller-controlled Make expansion.
    • +
  • Validate repository topology through Git-tracked plus non-ignored untracked candidates, while preserving raw recursive scans for fixtures.
    • +
  • Treat the implementation as ready to merge; production publication remains conditional on the exact clean tag workflow.
    • +
+
+
+

Open Questions and Release Conditions

+
    +
  • Native E5/E6 remains unavailable where no reviewed host runtime scenario exists.
    • +
  • Checksums, SBOM, and provenance are unsigned and require a trusted release channel.
    • +
  • Installer locks coordinate cooperating Maister processes, not arbitrary external writers.
    • +
  • The exact tag commit must rerun the complete clean release sequence, explicitly request contents: write, and publish only a recreated allowlisted same-job artifact set.
    • +
+
+
+ + + +
+
+

Outcome and Evidence

+
+ + + + + + + + + + + + +
AreaOutcomeContext
Specification17/17 requirements coveredSpecification
Plan39/39 steps across 5 groupsImplementation plan
Implementation logAll groups and repair cycles recordedWork log
VerificationPassed; zero open implementation findingsImplementation verification
Tests114/114 authoritative; 20/20 focused; package lifecycle 4/4Test results
Production readinessImplementation GO; exact-tag publication conditionalProduction readiness
User documentationCLI guide complete and validatedUser guide
Canonical workflow statePhase 14 and task completedOrchestrator state
+
+
+ +
+

Decision-Engine Audit

+
+
    +
  • The ledger below contains all 31 terminal gate records currently in canonical orchestrator.gate_history, in persisted order.
    • +
  • Every record has status decided; 30 were finalized by the user and one recovery reconciliation was finalized by the system after the original agent session completed.
    • +
  • Advisor model gpt-5.6-sol and arbiter model gpt-5.6-sol were configured on every record, but no advisor or arbiter response was used. Every attempts list is empty, no retry was scheduled, and neither agent was exhausted.
    • +
  • No arbitration occurred, no user override was recorded, and every terminal record has error: null.
    • +
  • Decision 13 differs from its original recommendation because the same timed-out Group 1 session recovered and completed; the durable system reconciliation records the actual outcome.
    • +
  • Decision 18 explicitly chose to skip optional browser E2E against the recommendation. The later Phase 12 exit correctly records that configured skip.
    • +
  • Decision 26 stopped the original exhausted repair loop. The workflow was later explicitly resumed from Phase 11 with repair counters reset while preserving this historical decision.
    • +
  • Reused idempotent decisions were not duplicated: the canonical re-verification decision and resumed fix-selection decision retained their original keys.
    • +
  • Decision 31 is the protected final-handoff approval. It was finalized by the user without advisor or automatic authority.
    • +
+
+
+ +
+

Complete Decision Ledger

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
#Phase / gateQuestion and ordered optionsRecommendation → selectionActor / confidenceRationale and context
1Phase 1 / clarificationQuestion: Confirm Codex, Cursor, Kiro CLI only, with Claude and generated trees removed?
Options: Confirm assumptions · Correct assumptions · Provide more context		Confirm assumptions → Confirm assumptionsUser / highConfirmed the research-approved target and deletion scope. Analysis
2Phase 1 / exitQuestion: Continue to Phase 2?
Options: Continue to Phase 2 · Pause workflow		Continue to Phase 2 → Continue to Phase 2User / highContinued into gap analysis. Codebase analysis
3Phase 2 / host-contract closureQuestion: Which host-contract closure policy?
Options: Contract-first overlay v1 with E1/E2/E4 for every host and E5/E6 when runtime exists · Host-doc-first overlay using legacy outputs only as semantic comparison fixtures · Runtime-gated support until native discovery and critical scenario evidence exist		Contract-first overlay v1… → Contract-first overlay v1…User / highDiscovery roots, inventories, settings destinations, and bindings required a versioned overlay contract. Gap analysis
4Phase 2 / settings ownershipQuestion: Which settings and shell-configuration ownership contract?
Options: Hybrid whole_file and managed_keys ownership with journal, backup, drift detection, and exact rollback · Dedicated files only, with manual configuration where unavailable · Managed-key merging for every shared settings file		Hybrid ownership → Hybrid ownershipUser / highShared settings required explicit ownership and rollback semantics. Gap analysis
5Phase 2 / native evidenceQuestion: Minimum release evidence without native runtime?
Options: Require E1-E4 and shared-core E3; record E5/E6 as unavailable, never pass · Require E5/E6 before labeling any host supported · Keep hosts provisional or unsupported until fresh native evidence exists		Require E1-E4… → Require E1-E4…User / highCursor and Kiro native evidence was unavailable and could not be represented as passing. Gap analysis
6Phase 2 / evidence freshnessQuestion: Which evidence freshness policy?
Options: Per-capability expiry with host, version, scenario, and timestamp renewal · Release-bound expiry when Maister or host contracts change · No expiry beyond recorded host version and manual review		Per-capability expiry → Per-capability expiryUser / highHost contracts and binaries change independently, requiring explicit renewal. Gap analysis
7Phase 2 / documentation boundaryQuestion: Which documentation and release migration boundary?
Options: Update all affected documentation, standards, Make/CI/release paths, and support matrices in this task · Defer documentation migration · Retain legacy instructions as compatibility guide		Update all affected paths → Update all affected pathsUser / highStale instructions would preserve removed generated-tree and Claude workflows. Gap analysis
8Phase 2 / routingQuestion: Continue to Phase 5?
Options: Continue to Phase 5: Technical Approach, Requirements & Specification · Pause workflow		Continue to Phase 5 → Continue to Phase 5User / highThe task required specification but had no defect-driven TDD-red or UI-heavy phase. Requirements
9Phase 5 / exitQuestion: Continue to specification audit?
Options: Continue to specification audit · Pause workflow		Continue → ContinueUser / highSpecification artifacts and structural checks were ready for independent audit. Specification
10Phase 6 / exitQuestion: Continue to implementation planning?
Options: Continue to implementation planning · Pause workflow		Continue → ContinueUser / highAudit found no critical/high defects; two medium contract clarifications moved into planning. Spec audit
11Phase 7 / exitQuestion: Continue to implementation approval?
Options: Continue to implementation approval · Pause workflow		Continue → ContinueUser / highThe five-group plan covered all requirements and 39 synchronized steps. Plan
12Phase 7 / protected implementation approvalQuestion: Approve this complete implementation scope?
Options: Approve complete implementation scope · Reject implementation scope · Request scope changes		Approve → Approve complete implementation scopeUser / highExplicit user authority was required before implementation. Plan
13Phase 8 / Group 1 recoveryQuestion: Group 1 agent timed out; how to proceed?
Options: Try suggested fix · Retry group · Complete manually · Rollback changes · Stop		Retry group → Try suggested fixSystem / highThe same session recovered and completed, so the durable record reconciled the observed outcome without duplicate work. Work log
14Phase 8 / Group 4 recoveryQuestion: Materialization parity red for all three target inventory/vocabulary contracts; how to proceed?
Options: Try suggested fix · Retry group · Complete manually · Rollback changes · Stop		Try suggested fix → Try suggested fixUser / highCommon-source and inventory contracts required reconciliation. Work log
15Phase 8 / Group 4 parity recoveryQuestion: Materialization green but 573 shadow-parity differences remain; how to proceed?
Options: Try suggested fix · Retry group · Complete manually · Rollback changes · Stop		Try suggested fix → Try suggested fixUser / highDirected review of every difference to distinguish intentional packaging changes from missing behavior. Work log
16Phase 8 / exitQuestion: Continue to verification?
Options: Continue to verification · Pause workflow		Continue → ContinueUser / highFive groups completed, 34 tests passed, targets materialized, parity had zero unresolved, and topology was clean. Work log
17Phase 10 / verification matrixQuestion: Which standard verifications?
Options: Code review · Pragmatic review · Reality check · Production readiness		Run all recommended → All four tracksUser / highArchitecture, installer, filesystem, CI/release, and host changes warranted every standard review. Verification
18Phase 10 / optional E2EQuestion: Enable E2E browser verification?
Options: Yes (Recommended) · No, skip		Yes → No, skipUser / mediumOptional browser E2E was declined; Phase 12 was later skipped as configured. State
19Phase 10 / optional user docsQuestion: Generate user documentation?
Options: Yes (Recommended) · No, skip		Yes → YesUser / highInstaller, hosts, sources, recovery, and release operation changed materially. User guide
20Phase 11 / fix selection 1Question: Which issues should be fixed?
Options: Fix all fixable issues · Let me choose specific issues · Skip fixes, proceed as-is		Fix all → Fix allUser / highInitial verification found five critical blockers and sixteen warning groups. Verification history
21Phase 11 / rerun 1Question: Re-run verification?
Options: Yes, re-run verification · No, proceed		Yes → YesUser / highFirst hardening pass produced 60/60 tests and integrated validation. Verification history
22Phase 11 / fix selection 2Question: Which issues should be fixed?
Options: Fix all fixable issues · Let me choose specific issues · Skip fixes, proceed as-is		Fix all → Fix allUser / highRe-verification found four critical blockers and ten warnings. Verification history
23Phase 11 / rerun 2Question: Re-run verification?
Options: Yes, re-run verification · No, proceed		Yes → YesUser / highSecond hardening pass reached 91/91 tests, package lifecycle 4/4, clean parity, and make validate. Verification history
24Phase 11 / fix selection 3Question: Which issues should be fixed?
Options: Fix all fixable issues · Let me choose specific issues · Skip fixes, proceed as-is		Fix all → Fix allUser / highReview found pathname TOCTOU, source mutation, split provenance, and Make injection boundaries. Verification history
25Phase 11 / rerun 3Question: Re-run verification?
Options: Yes, re-run verification · No, proceed		Yes → YesUser / highThird hardening pass reached 109/109 tests and zero-unresolved diagnostic parity. Verification history
26Phase 11 / unresolved criticalQuestion: Proceed with known issues?
Options: Proceed with known issues · Stop workflow		Stop → Stop workflowUser / highTwo P1s remained after the three-attempt limit, so the workflow stopped safely. Verification history
27Phase 11 resumed / fix selectionQuestion: Which issues should be fixed?
Options: Fix all fixable issues · Let me choose specific issues · Skip fixes, proceed as-is		Fix all → Fix allUser / highExplicit resume/reset authorized repair of both remaining P1 trust boundaries. Work log
28Phase 11 / exitQuestion: Continue to Phase 12?
Options: Continue to Phase 12 · Pause workflow		Continue → ContinueUser / highFinal verifier passed with 114/114 tests and zero open findings. Final verification
29Phase 12 / exitQuestion: E2E complete. Continue to Phase 13?
Options: Continue to Phase 13 · Pause workflow		Continue → ContinueUser / highE2E was skipped by configuration and the workflow continued to enabled documentation. State
30Phase 13 / exitQuestion: Documentation complete. Continue to Phase 14?
Options: Continue to Phase 14 · Pause workflow		Continue → ContinueUser / highThe CLI guide was complete and validated before finalization. User guide
31Phase 14 / protected final handoffQuestion: Complete workflow or keep it open?
Options: Complete workflow · Keep workflow open		Complete workflow → Complete workflowUser / highThe user explicitly approved the final implementation, verification, documentation, and decision-summary handoff. Canonical state
+
+
+ +
+

Idempotency Keys

+
+ Show all 31 canonical keys +
    +
  1. sha256:ec02c7f9f82f78391846592009ec9aee11bb8cb1d6d24dc1c4a45208d9328a78
    2. +
  2. sha256:ba5d887d0c4265cbcbe1c13696ffdc0cf70e09b9b115fd0cea577002cb7aee7a
    3. +
  3. sha256:9e22d1cd8c8c8ccd768742a06292a9988d36f58656d7964e7799638229d15117
    4. +
  4. sha256:d6c3f6d878255f05159dce1edbaff998b8ea79e84c59a7cecfe5ca12aeb92970
    5. +
  5. sha256:a0da58fe5a1961fb662f7592b49c157c182bb70d3929cb36b7a5376a78c54e50
    6. +
  6. sha256:cc8019c200d90a666bb76ac3bae53660de40b4ed9ece30fd3779ea4351bc1064
    7. +
  7. sha256:7049cc17ddbd24dd6410f8e24ac74d5fae4ccb63534d828b41f1244006b45172
    8. +
  8. sha256:cb8d23e0e7ad2eb2968a831e300e4a2f2c77b56b18216abfeff974cd16f1ab52
    9. +
  9. sha256:8358f6a9980394365c8e29349d3538166c7645e2aeb8875de965b725f22f292f
    10. +
  10. sha256:eeba59811d29c2483cca234227ab77fd47023e60becab582b5c75f9a3d6994fe
    11. +
  11. sha256:3816e7b010ce22a0a421f05dde1915496a6c69d60c72a8a783a82a76a8361265
    12. +
  12. sha256:663a42aa519cf64427fd11758ef12c313a7364b973068f67fc85f046e6b8e17b
    13. +
  13. sha256:8427cbf0e377cd8f234e79d9f5346062d6bd293fe524dc517f25db71193408de
    14. +
  14. sha256:0e17e4a7c76e0fca66e93b36dd463df1e18f93bfcfa027baae084a83f0503922
    15. +
  15. sha256:7f3c4d56a3554cb24346cdbc9f46a6e8c551345121ef316d84827f26966be760
    16. +
  16. sha256:19568792996c419f61acb934284693bd396df535db9c9b4ac814b5f6c528d7a5
    17. +
  17. sha256:239981881b195b61ea682efd83565288e6737e9def74584192f949dbc6d517e9
    18. +
  18. sha256:98c61b5e2542abb49b807564e2ad43644f9b6443be62cba708dc99c212945c5a
    19. +
  19. sha256:430715d582c5f8acbf15c124fe155cb078622e8f8ea39e2c79f92d9958b04bb4
    20. +
  20. sha256:4faf97df6ac300025973a0db05ef2a15baaf46b02c225599fc10464dd193d969
    21. +
  21. sha256:198f8c6133aeb3ec728a3f71473293f3f72dcc7f7e72b7aa48b0e9c4367dd9c1
    22. +
  22. sha256:6921f6d132122613094ce1e600a5d075a682cd0557d4341a33ffcaf2e39815ec
    23. +
  23. sha256:34eed63ef305b80ab06583847d5489291da6c39ed01a71bbb088ebb412d433be
    24. +
  24. sha256:b0651b64f08d41434582be22a7b6f1b659a40d0f9faa356884dc366d93300f2a
    25. +
  25. sha256:0ff4b47f90b0bdeac3716368d31f017fae20a732dc012d511834a5c49d1f7c0e
    26. +
  26. sha256:3c9a3ae5d02a4d3badb43d3c03f40df5149a06021c9bcc48e3bed2d32803015d
    27. +
  27. sha256:b38801fbc024277030edaf7d11b3461eac96c4fcb2402dda48ee0d161f5f1f01
    28. +
  28. sha256:949c1c70eecbf5b542f80cfb36dc9f5090ec10164e69582d0727f8e47ed16346
    29. +
  29. sha256:5d3db71e7a2ecdaf6c5f3b8638d2ffd3418ea06b44e4aa52e4220cfe59c4992c
    30. +
  30. sha256:4190f0156e5926ddbfbb8dc4a7f936990fca079a77de6d4a9b2fd6262f1193ba
    31. +
  31. sha256:6d7f6ae8df3ed9da15c045e924b897b137471f0083602540051e6cd0bb590c6e
    32. +
+
+
+ +
+

Final-Handoff Decision

+

The protected gate was resolved by the user as Complete workflow. No advisor, arbiter, or automatic continuation was permitted to authorize this boundary. The terminal record, Phase 14 completion, overall task completion, Markdown summary, and HTML companion are durable.

+
+
+ + diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/outputs/decision-summary.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/outputs/decision-summary.md new file mode 100644 index 00000000..06c91cb1 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/outputs/decision-summary.md @@ -0,0 +1,129 @@ +# Decision Summary — Platform-Independent Maister Distribution + +**Generated:** 2026-07-16 +**Workflow:** Development +**Current status:** Completed +**Task:** Implement platform-independent Maister distribution + +## TL;DR + +The workflow implemented and independently verified one portable Maister source with explicit Codex, Cursor, and Kiro CLI overlays, a transactional installer, immutable source and evidence binding, deterministic packaging, and removal of Claude and committed generated host trees. + +Implementation verification passed with **39/39 plan steps**, **17/17 requirements**, **114/114 authoritative tests**, **20/20 focused evidence/topology tests**, package lifecycle **4/4**, and clean strict parity for all three targets with zero unresolved differences. Phase 12 E2E browser verification was intentionally skipped by user choice; Phase 13 produced a validated CLI user guide. The user approved the denylisted final handoff, and Phase 14 plus the overall task are durably completed. + +## Key Decisions + +- Support exactly Codex, Cursor, and Kiro CLI; remove Claude and generated/marketplace projections. +- Use one common portable source plus strict, versioned target overlays. +- Use hybrid `whole_file` and `managed_keys` settings ownership with receipts, journals, backups, drift detection, recovery, and exact rollback. +- Require E1–E4 and shared-core E3; record unavailable E5/E6 honestly and never promote unavailable evidence to passed. +- Bind install/update overlay selection, materialization, E3 evidence, and receipts to one immutable source identity. +- Keep supported-target enumeration in the central Node registry, outside caller-controlled Make expansion. +- Validate repository topology through Git-tracked plus non-ignored untracked candidates, while preserving raw recursive scans for fixtures. +- Treat the implementation as ready to merge; production publication remains conditional on the exact clean tag workflow. + +## Open Questions and Release Conditions + +- Native E5/E6 remains unavailable where no reviewed host runtime scenario exists. +- Checksums, SBOM, and provenance are unsigned and require a trusted release channel. +- Installer locks coordinate cooperating Maister processes, not arbitrary external writers. +- The exact tag commit must rerun the complete clean release sequence, explicitly request `contents: write`, and publish only a recreated allowlisted same-job artifact set. + +## Outcome and Evidence + +| Area | Outcome | Context | +| --- | --- | --- | +| Specification | 17/17 requirements covered | [Specification](../implementation/spec.md) | +| Plan | 39/39 steps across 5 groups | [Implementation plan](../implementation/implementation-plan.md) | +| Implementation log | All groups and repair cycles recorded | [Work log](../implementation/work-log.md) | +| Verification | Passed; zero open implementation findings | [Implementation verification](../verification/implementation-verification.md) | +| Tests | 114/114 authoritative; 20/20 focused; package lifecycle 4/4 | [Test results](../verification/test-suite-results.md) | +| Production readiness | Implementation GO; exact-tag publication conditional | [Production readiness](../verification/production-readiness-report.md) | +| User documentation | CLI guide complete and validated | [User guide](../documentation/user-guide.md) | +| Canonical workflow state | Phase 14 and task completed | [Orchestrator state](../orchestrator-state.yml) | + +## Decision-Engine Audit + +- The ledger below contains all **31 terminal gate records** currently in canonical `orchestrator.gate_history`, in persisted order. +- Every record has status `decided`; 30 were finalized by the user and one recovery reconciliation was finalized by the system after the original agent session completed. +- Advisor model `gpt-5.6-sol` and arbiter model `gpt-5.6-sol` were configured on every record, but no advisor or arbiter response was used. Every attempts list is empty, no retry was scheduled, and neither agent was exhausted. +- No arbitration occurred, no user override was recorded, and every terminal record has `error: null`. +- Decision 13 differs from its original recommendation because the same timed-out Group 1 session recovered and completed; the durable system reconciliation records the actual outcome. +- Decision 18 explicitly chose to skip optional browser E2E against the recommendation. The later Phase 12 exit correctly records that configured skip. +- Decision 26 stopped the original exhausted repair loop. The workflow was later explicitly resumed from Phase 11 with repair counters reset while preserving this historical decision. +- Reused idempotent decisions were not duplicated: the canonical re-verification decision and resumed fix-selection decision retained their original keys. +- Decision 31 is the protected final-handoff approval. It was finalized by the user without advisor or automatic authority. + +## Complete Decision Ledger + +| # | Phase / gate | Question and ordered options | Recommendation → selection | Actor / confidence | Rationale and context | +| ---: | --- | --- | --- | --- | --- | +| 1 | Phase 1 / clarification | **Question:** Confirm Codex, Cursor, Kiro CLI only, with Claude and generated trees removed?
**Options:** Confirm assumptions · Correct assumptions · Provide more context | Confirm assumptions → **Confirm assumptions** | User / high | Confirmed the research-approved target and deletion scope. [Analysis](../analysis/clarifications.md) | +| 2 | Phase 1 / exit | **Question:** Continue to Phase 2?
**Options:** Continue to Phase 2 · Pause workflow | Continue to Phase 2 → **Continue to Phase 2** | User / high | Continued into gap analysis. [Codebase analysis](../analysis/codebase-analysis.md) | +| 3 | Phase 2 / host-contract closure | **Question:** Which host-contract closure policy?
**Options:** Contract-first overlay v1 with E1/E2/E4 for every host and E5/E6 when runtime exists · Host-doc-first overlay using legacy outputs only as semantic comparison fixtures · Runtime-gated support until native discovery and critical scenario evidence exist | Contract-first overlay v1… → **Contract-first overlay v1…** | User / high | Discovery roots, inventories, settings destinations, and bindings required a versioned overlay contract. [Gap analysis](../analysis/gap-analysis.md) | +| 4 | Phase 2 / settings ownership | **Question:** Which settings and shell-configuration ownership contract?
**Options:** Hybrid whole_file and managed_keys ownership with journal, backup, drift detection, and exact rollback · Dedicated files only, with manual configuration where unavailable · Managed-key merging for every shared settings file | Hybrid ownership → **Hybrid ownership** | User / high | Shared settings required explicit ownership and rollback semantics. [Gap analysis](../analysis/gap-analysis.md) | +| 5 | Phase 2 / native evidence | **Question:** Minimum release evidence without native runtime?
**Options:** Require E1-E4 and shared-core E3; record E5/E6 as unavailable, never pass · Require E5/E6 before labeling any host supported · Keep hosts provisional or unsupported until fresh native evidence exists | Require E1-E4… → **Require E1-E4…** | User / high | Cursor and Kiro native evidence was unavailable and could not be represented as passing. [Gap analysis](../analysis/gap-analysis.md) | +| 6 | Phase 2 / evidence freshness | **Question:** Which evidence freshness policy?
**Options:** Per-capability expiry with host, version, scenario, and timestamp renewal · Release-bound expiry when Maister or host contracts change · No expiry beyond recorded host version and manual review | Per-capability expiry → **Per-capability expiry** | User / high | Host contracts and binaries change independently, requiring explicit renewal. [Gap analysis](../analysis/gap-analysis.md) | +| 7 | Phase 2 / documentation boundary | **Question:** Which documentation and release migration boundary?
**Options:** Update all affected documentation, standards, Make/CI/release paths, and support matrices in this task · Defer documentation migration · Retain legacy instructions as compatibility guide | Update all affected paths → **Update all affected paths** | User / high | Stale instructions would preserve removed generated-tree and Claude workflows. [Gap analysis](../analysis/gap-analysis.md) | +| 8 | Phase 2 / routing | **Question:** Continue to Phase 5?
**Options:** Continue to Phase 5: Technical Approach, Requirements & Specification · Pause workflow | Continue to Phase 5 → **Continue to Phase 5** | User / high | The task required specification but had no defect-driven TDD-red or UI-heavy phase. [Requirements](../analysis/requirements.md) | +| 9 | Phase 5 / exit | **Question:** Continue to specification audit?
**Options:** Continue to specification audit · Pause workflow | Continue → **Continue** | User / high | Specification artifacts and structural checks were ready for independent audit. [Specification](../implementation/spec.md) | +| 10 | Phase 6 / exit | **Question:** Continue to implementation planning?
**Options:** Continue to implementation planning · Pause workflow | Continue → **Continue** | User / high | Audit found no critical/high defects; two medium contract clarifications moved into planning. [Spec audit](../verification/spec-audit.md) | +| 11 | Phase 7 / exit | **Question:** Continue to implementation approval?
**Options:** Continue to implementation approval · Pause workflow | Continue → **Continue** | User / high | The five-group plan covered all requirements and 39 synchronized steps. [Plan](../implementation/implementation-plan.md) | +| 12 | Phase 7 / protected implementation approval | **Question:** Approve this complete implementation scope?
**Options:** Approve complete implementation scope · Reject implementation scope · Request scope changes | Approve → **Approve complete implementation scope** | User / high | Explicit user authority was required before implementation. [Plan](../implementation/implementation-plan.md) | +| 13 | Phase 8 / Group 1 recovery | **Question:** Group 1 agent timed out; how to proceed?
**Options:** Try suggested fix · Retry group · Complete manually · Rollback changes · Stop | Retry group → **Try suggested fix** | System / high | The same session recovered and completed, so the durable record reconciled the observed outcome without duplicate work. [Work log](../implementation/work-log.md) | +| 14 | Phase 8 / Group 4 recovery | **Question:** Materialization parity red for all three target inventory/vocabulary contracts; how to proceed?
**Options:** Try suggested fix · Retry group · Complete manually · Rollback changes · Stop | Try suggested fix → **Try suggested fix** | User / high | Common-source and inventory contracts required reconciliation. [Work log](../implementation/work-log.md) | +| 15 | Phase 8 / Group 4 parity recovery | **Question:** Materialization green but 573 shadow-parity differences remain; how to proceed?
**Options:** Try suggested fix · Retry group · Complete manually · Rollback changes · Stop | Try suggested fix → **Try suggested fix** | User / high | Directed review of every difference to distinguish intentional packaging changes from missing behavior. [Work log](../implementation/work-log.md) | +| 16 | Phase 8 / exit | **Question:** Continue to verification?
**Options:** Continue to verification · Pause workflow | Continue → **Continue** | User / high | Five groups completed, 34 tests passed, targets materialized, parity had zero unresolved, and topology was clean. [Work log](../implementation/work-log.md) | +| 17 | Phase 10 / verification matrix | **Question:** Which standard verifications?
**Options:** Code review · Pragmatic review · Reality check · Production readiness | Run all recommended → **All four tracks** | User / high | Architecture, installer, filesystem, CI/release, and host changes warranted every standard review. [Verification](../verification/implementation-verification.md) | +| 18 | Phase 10 / optional E2E | **Question:** Enable E2E browser verification?
**Options:** Yes (Recommended) · No, skip | Yes → **No, skip** | User / medium | Optional browser E2E was declined; Phase 12 was later skipped as configured. [State](../orchestrator-state.yml) | +| 19 | Phase 10 / optional user docs | **Question:** Generate user documentation?
**Options:** Yes (Recommended) · No, skip | Yes → **Yes** | User / high | Installer, hosts, sources, recovery, and release operation changed materially. [User guide](../documentation/user-guide.md) | +| 20 | Phase 11 / fix selection 1 | **Question:** Which issues should be fixed?
**Options:** Fix all fixable issues · Let me choose specific issues · Skip fixes, proceed as-is | Fix all → **Fix all** | User / high | Initial verification found five critical blockers and sixteen warning groups. [Verification history](../verification/implementation-verification.md) | +| 21 | Phase 11 / rerun 1 | **Question:** Re-run verification?
**Options:** Yes, re-run verification · No, proceed | Yes → **Yes** | User / high | First hardening pass produced 60/60 tests and integrated validation. [Verification history](../verification/implementation-verification.md) | +| 22 | Phase 11 / fix selection 2 | **Question:** Which issues should be fixed?
**Options:** Fix all fixable issues · Let me choose specific issues · Skip fixes, proceed as-is | Fix all → **Fix all** | User / high | Re-verification found four critical blockers and ten warnings. [Verification history](../verification/implementation-verification.md) | +| 23 | Phase 11 / rerun 2 | **Question:** Re-run verification?
**Options:** Yes, re-run verification · No, proceed | Yes → **Yes** | User / high | Second hardening pass reached 91/91 tests, package lifecycle 4/4, clean parity, and `make validate`. [Verification history](../verification/implementation-verification.md) | +| 24 | Phase 11 / fix selection 3 | **Question:** Which issues should be fixed?
**Options:** Fix all fixable issues · Let me choose specific issues · Skip fixes, proceed as-is | Fix all → **Fix all** | User / high | Review found pathname TOCTOU, source mutation, split provenance, and Make injection boundaries. [Verification history](../verification/implementation-verification.md) | +| 25 | Phase 11 / rerun 3 | **Question:** Re-run verification?
**Options:** Yes, re-run verification · No, proceed | Yes → **Yes** | User / high | Third hardening pass reached 109/109 tests and zero-unresolved diagnostic parity. [Verification history](../verification/implementation-verification.md) | +| 26 | Phase 11 / unresolved critical | **Question:** Proceed with known issues?
**Options:** Proceed with known issues · Stop workflow | Stop → **Stop workflow** | User / high | Two P1s remained after the three-attempt limit, so the workflow stopped safely. [Verification history](../verification/implementation-verification.md) | +| 27 | Phase 11 resumed / fix selection | **Question:** Which issues should be fixed?
**Options:** Fix all fixable issues · Let me choose specific issues · Skip fixes, proceed as-is | Fix all → **Fix all** | User / high | Explicit resume/reset authorized repair of both remaining P1 trust boundaries. [Work log](../implementation/work-log.md) | +| 28 | Phase 11 / exit | **Question:** Continue to Phase 12?
**Options:** Continue to Phase 12 · Pause workflow | Continue → **Continue** | User / high | Final verifier passed with 114/114 tests and zero open findings. [Final verification](../verification/implementation-verification.md) | +| 29 | Phase 12 / exit | **Question:** E2E complete. Continue to Phase 13?
**Options:** Continue to Phase 13 · Pause workflow | Continue → **Continue** | User / high | E2E was skipped by configuration and the workflow continued to enabled documentation. [State](../orchestrator-state.yml) | +| 30 | Phase 13 / exit | **Question:** Documentation complete. Continue to Phase 14?
**Options:** Continue to Phase 14 · Pause workflow | Continue → **Continue** | User / high | The CLI guide was complete and validated before finalization. [User guide](../documentation/user-guide.md) | +| 31 | Phase 14 / protected final handoff | **Question:** Complete workflow or keep it open?
**Options:** Complete workflow · Keep workflow open | Complete workflow → **Complete workflow** | User / high | The user explicitly approved the final implementation, verification, documentation, and decision-summary handoff. [Canonical state](../orchestrator-state.yml) | + +## Idempotency Keys + +1. `sha256:ec02c7f9f82f78391846592009ec9aee11bb8cb1d6d24dc1c4a45208d9328a78` +2. `sha256:ba5d887d0c4265cbcbe1c13696ffdc0cf70e09b9b115fd0cea577002cb7aee7a` +3. `sha256:9e22d1cd8c8c8ccd768742a06292a9988d36f58656d7964e7799638229d15117` +4. `sha256:d6c3f6d878255f05159dce1edbaff998b8ea79e84c59a7cecfe5ca12aeb92970` +5. `sha256:a0da58fe5a1961fb662f7592b49c157c182bb70d3929cb36b7a5376a78c54e50` +6. `sha256:cc8019c200d90a666bb76ac3bae53660de40b4ed9ece30fd3779ea4351bc1064` +7. `sha256:7049cc17ddbd24dd6410f8e24ac74d5fae4ccb63534d828b41f1244006b45172` +8. `sha256:cb8d23e0e7ad2eb2968a831e300e4a2f2c77b56b18216abfeff974cd16f1ab52` +9. `sha256:8358f6a9980394365c8e29349d3538166c7645e2aeb8875de965b725f22f292f` +10. `sha256:eeba59811d29c2483cca234227ab77fd47023e60becab582b5c75f9a3d6994fe` +11. `sha256:3816e7b010ce22a0a421f05dde1915496a6c69d60c72a8a783a82a76a8361265` +12. `sha256:663a42aa519cf64427fd11758ef12c313a7364b973068f67fc85f046e6b8e17b` +13. `sha256:8427cbf0e377cd8f234e79d9f5346062d6bd293fe524dc517f25db71193408de` +14. `sha256:0e17e4a7c76e0fca66e93b36dd463df1e18f93bfcfa027baae084a83f0503922` +15. `sha256:7f3c4d56a3554cb24346cdbc9f46a6e8c551345121ef316d84827f26966be760` +16. `sha256:19568792996c419f61acb934284693bd396df535db9c9b4ac814b5f6c528d7a5` +17. `sha256:239981881b195b61ea682efd83565288e6737e9def74584192f949dbc6d517e9` +18. `sha256:98c61b5e2542abb49b807564e2ad43644f9b6443be62cba708dc99c212945c5a` +19. `sha256:430715d582c5f8acbf15c124fe155cb078622e8f8ea39e2c79f92d9958b04bb4` +20. `sha256:4faf97df6ac300025973a0db05ef2a15baaf46b02c225599fc10464dd193d969` +21. `sha256:198f8c6133aeb3ec728a3f71473293f3f72dcc7f7e72b7aa48b0e9c4367dd9c1` +22. `sha256:6921f6d132122613094ce1e600a5d075a682cd0557d4341a33ffcaf2e39815ec` +23. `sha256:34eed63ef305b80ab06583847d5489291da6c39ed01a71bbb088ebb412d433be` +24. `sha256:b0651b64f08d41434582be22a7b6f1b659a40d0f9faa356884dc366d93300f2a` +25. `sha256:0ff4b47f90b0bdeac3716368d31f017fae20a732dc012d511834a5c49d1f7c0e` +26. `sha256:3c9a3ae5d02a4d3badb43d3c03f40df5149a06021c9bcc48e3bed2d32803015d` +27. `sha256:b38801fbc024277030edaf7d11b3461eac96c4fcb2402dda48ee0d161f5f1f01` +28. `sha256:949c1c70eecbf5b542f80cfb36dc9f5090ec10164e69582d0727f8e47ed16346` +29. `sha256:5d3db71e7a2ecdaf6c5f3b8638d2ffd3418ea06b44e4aa52e4220cfe59c4992c` +30. `sha256:4190f0156e5926ddbfbb8dc4a7f936990fca079a77de6d4a9b2fd6262f1193ba` +31. `sha256:6d7f6ae8df3ed9da15c045e924b897b137471f0083602540051e6cd0bb590c6e` + +## Final-Handoff Decision + +The protected gate was resolved by the user as **Complete workflow**. No advisor, arbiter, or automatic continuation was permitted to authorize this boundary. The terminal record, Phase 14 completion, overall task completion, Markdown summary, and HTML companion are durable. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/code-review-report.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/code-review-report.md new file mode 100644 index 00000000..eb0b4c41 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/code-review-report.md @@ -0,0 +1,223 @@ +# Phase 11 Independent Code Quality and Security Review — Final Re-Verification + +## TL;DR + +**Patch security verdict: APPROVED. Verification verdict: PASSED WITH ENVIRONMENT ISSUE. Current-workspace release verdict: DO NOT RELEASE.** +Both prior P1 defects are closed in their reported interfaces, the two test-only repairs are correct, and no production or test regression was found. +The sole 111/112 failure is ignored local IDE residue in `.idea/workspace.xml`, not repository product state; strict release parity also correctly refuses the dirty checkout. +Run the unchanged release gates from a clean isolated checkout before publication. + +## Key Decisions + +- Close P1-01 — install/update now establishes one immutable source binding before lifecycle state creation and carries that exact binding through overlay selection, materialization, revalidation, evidence, and receipt provenance. +- Close P1-02 for the reported threat — the Makefile no longer expands a caller-controlled target list, rejects ordinary `SUPPORTED_TARGETS=` overrides without reading the value, and delegates enumeration to the central Node registry. +- Accept both test-only repairs — the overlay-negative fixture now reaches its intended immutable-source boundary, and the topology contract now checks fixed Make-to-Node delegation rather than requiring duplicate Make ownership. +- Classify `.idea/workspace.xml` as environment residue — it is ignored, untracked, and outside production/test/package inputs; its stale changelist text does not reproduce a product defect. +- Do not add an editor-specific `.idea` exclusion — prefer a clean checkout or Git-aware topology enumeration so all tracked and non-ignored candidate files are checked without creating a blind spot for a future force-added IDE file. + +## Open Questions / Risks + +- Strict parity has not passed in this shared dirty checkout; the dirty-local zero-unresolved result is diagnostic only. +- Native E6 remains unavailable where no reviewed host scenario exists; unavailable is not a semantic pass. +- GNU Make immediately evaluates arbitrary command-line `:=`/`!=` assignments before it reads the Makefile. The repaired boundary is safe for untrusted values passed through a fixed assignment/environment interface, but arbitrary Make argv must remain trusted. +- Four previously recorded hardening limits remain unchanged: cooperative-writer pathname guarantees, broad materializer exceptions, broad topology exclusions, and caller-supplied package commit identity outside the protected release flow. + +## Scope and Evidence + +- Repository: `/Users/mrapacz/Workspace/maister` +- Task: `.maister/tasks/development/2026-07-14-platform-independent-plugin` +- Review scope: final Phase 11 production/security delta, two prior P1s, the iteration-2 test-only repairs, final test report, and ignored IDE topology residue. +- Inputs reviewed: project standards, `orchestrator-state.yml`, specification, implementation plan, work log, current working-tree delta, prior review, and final `test-suite-results.md`. +- Independent focused execution: source-binding A/B rejection, overlay-outside-source failure ordering, Make override rejection, and central registry enumeration all passed (5/5 Node test records; four named contracts plus the loaded topology test file). +- Canonical test evidence: 111/112 authoritative tests; package lifecycle 4/4; dirty-local parity 3/3 with zero unresolved; strict parity failed closed with `E_SOURCE_DIRTY`. +- Reviewer mutations: production code, tests, and IDE state were not modified. Only this report was replaced. + +## Prior P1 Re-Verification + +### P1-01 — Split lifecycle/materializer source binding: resolved + +| Field | Result | +| --- | --- | +| Prior severity | P1 — source provenance and installed-byte integrity | +| Current status | Resolved | +| Production locations | `transaction-manager.mjs:476-554`, `747-784`, `1036-1069`; `materializer.mjs:842-935`; `source-resolver.mjs:551-649` | +| Regression | `installer-transaction.test.mjs:395-424` | + +`executeLifecycle()` resolves or revalidates the source before `getTargetPaths()` and `ensureDirectories()` (`transaction-manager.mjs:1036-1046`). `assertSourceRootBinding()` realpath-normalizes the resolved root, any direct `resolvedSourceRoot`, and a local/file source argument and rejects disagreement (`transaction-manager.mjs:476-493`). This closes the original direct A/B path before lifecycle state is created. + +Install/update selects overlays only from that bound root (`transaction-manager.mjs:521-554`, `747-754`) and passes the frozen resolved binding to `materialize()` (`transaction-manager.mjs:770-775`). The materializer revalidates the same checkout rather than resolving source text again, verifies it before and after copying, and returns the resulting identity (`materializer.mjs:847-850`, `889-933`; `source-resolver.mjs:551-649`). The lifecycle compares the provenance-significant binding fields before advancing the transaction (`transaction-manager.mjs:496-519`, `776`) and separately rechecks the portable-core hash (`transaction-manager.mjs:759-784`). + +The adversarial A/B regression passed and proved `E_SOURCE_ROOT` occurs before both the state root and active target exist. No overlay-root fallback remains for source-bound install/update. No regression was found. + +### P1-02 — Pre-validation `SUPPORTED_TARGETS` recipe expansion: resolved within the reported interface + +| Field | Result | +| --- | --- | +| Prior severity | P1 — Make recipe command injection | +| Current status | Resolved for fixed assignment/environment values; arbitrary Make argv remains a trusted boundary | +| Production locations | `Makefile:3-6`, `63-65`; `release-interface.mjs:298-302`, `372-380`; `targets.mjs:1-26` | +| Regressions | `make-interface.test.mjs:43-70` | + +The Makefile does not own or interpolate a target list. Its guard expands only `$(origin SUPPORTED_TARGETS)` and emits a constant error (`Makefile:3-6`); `validate` invokes a fixed Node command (`Makefile:63-65`). Node enumerates `SUPPORTED_TARGET_IDS` from the central frozen registry and invokes validation with argument arrays (`release-interface.mjs:298-302`; `targets.mjs:1-26`). The existing Make-function, shell-metacharacter, and exact-registry regressions passed without producing their sentinels. + +An additional adversarial probe showed that `make validate 'SUPPORTED_TARGETS:=$(shell ...)'` executes the shell function while GNU Make parses its command line, before any Makefile can guard it. This does **not** recreate the reported product flaw: arbitrary Make command-line syntax is itself executable input, and the same primitive works under any variable name independently of this repository. It does mean the phrase “any override is rejected before evaluation” is too broad. CI or wrappers must pass untrusted data only as values through a fixed assignment/environment field and must never accept arbitrary extra Make argv. If arbitrary argv ever becomes an input requirement, validation must occur in a wrapper before GNU Make starts. + +## Test-Only Repair Assessment + +### Repair T-01 — Make/topology contract: correct + +`evidence-parity-topology.test.mjs:927-937` now asserts all of the intended properties: + +- no Make-owned `SUPPORTED_TARGETS` declaration; +- a constant non-configurable-origin guard; +- fixed `release-interface.mjs validate-overlays` delegation; +- the focused platform-independent test entry point; +- Cursor projection enforcement; and +- absence of legacy generated-tree vocabulary. + +`make-interface.test.mjs:64-70` remains the executable owner of the exact `codex`, `cursor`, `kiro-cli` enumeration contract. The repair removes the stale duplicate-registry expectation without weakening production behavior. The Make assertions are currently masked in the combined real-checkout test by the earlier `.idea` topology failure, but direct source inspection and the independently executed registry test confirm them. + +### Repair T-02 — Missing-overlay fixture identity: correct + +`installer-transaction.test.mjs:362-393` supplies the copied fixture with a source-bound Git seam whose top-level root, full commit, and clean status satisfy immutable-source resolution. The fixture still lacks its selected overlay, so it now reaches the intended `E_OVERLAY_IO` boundary. The assertions retain the important transactional contract: neither active content nor an active receipt exists after rejection. + +The focused test passed. The repair changes only test setup; it does not weaken production source resolution or reorder production errors. + +## Ignored `.idea` Topology Residue + +### Classification: environment residue; not a production defect and not a test-contract defect + +| Evidence | Result | +| --- | --- | +| Path | `.idea/workspace.xml` | +| Git status | Ignored by `.gitignore:5` (`.idea/`) | +| Tracking | `git ls-files --error-unmatch` confirms it is untracked | +| Stale text | 554 legacy-path matches in local IDE changelist/history state | +| Scanner behavior | `scanTopology()` recursively reads every non-excluded file from the filesystem (`shadow-parity.mjs:485-510`) | +| Product/package reachability | None shown; package lifecycle passes 4/4 and the file is not a repository input | + +The topology gate is correctly fail-closed for the filesystem tree it was asked to scan, but the real-checkout test couples repository-topology validation to ignored operator state. That makes the current run environment-sensitive; it does not establish stale production topology. The 111/112 result should therefore be reported as `passed_with_environment_issue`, not as a production regression and not as a green release gate. + +An explicit `.idea` entry in `excludePaths` is **not recommended**. It would fix one editor symptom while allowing a future tracked or force-added `.idea` file to bypass topology policy. Preferred remedies are: + +1. Run the unchanged topology and strict parity gates in the required clean isolated checkout; or +2. Make real-repository topology enumeration Git-aware: scan tracked files plus non-ignored untracked files, excluding ignored files generically. This still catches newly added implementation files while avoiding editor/cache-specific exclusions. + +No production, test, or IDE mutation is warranted in this read-only review. + +## Regression, Quality, Security, and Performance Assessment + +- No source A / materialized source B route remains through the reviewed install/update interface. +- No caller-controlled target-list value reaches a Make recipe, shell interpolation, or inline JavaScript boundary. +- Both repaired production boundaries fail before persistent target mutation in their covered adversarial cases. +- The two test-only changes preserve stronger fail-fast ordering and transactional no-mutation assertions. +- No new secret, credential, unsafe remote-script, dynamic shell construction, unbounded retry, N+1 I/O pattern, or material performance regression was found in the final delta. +- The final 111/112 failure and strict-parity refusal are checkout-state conditions, not evidence that either prior P1 persists. + +## Findings + +### Warning W-ENV-01 — Ignored IDE state blocks the real-checkout topology acceptance test + +- Category: verification environment +- Location: `.idea/workspace.xml`; scanner at `plugins/maister/bin/shadow-parity.mjs:485-510` +- Production defect: no +- Test defect: no stale behavioral assertion; the test is environment-coupled +- Effect: authoritative suite remains 111/112 and `make validate` remains non-zero in this checkout +- Action: rerun unchanged gates in a clean isolated checkout, or separately adopt Git-aware topology enumeration; do not special-case `.idea` alone + +### Info I-REL-01 — Strict parity is not established in the current checkout + +- Category: release precondition +- Evidence: `test-parity-release` correctly returns `E_SOURCE_DIRTY`; dirty-local diagnostic parity is 3/3 with zero unresolved +- Effect: no publication authorization from this workspace +- Action: run strict parity and same-job package checks from a clean isolated checkout + +### Info I-THREAT-01 — Arbitrary GNU Make argv is executable input + +- Category: threat-model boundary +- Evidence: immediate `:=` assignment expansion occurs before the Makefile guard +- Production defect: no, provided callers control the assignment syntax and pass untrusted text only as a value +- Action: never expose arbitrary Make argv to untrusted input; use a pre-Make wrapper if that requirement changes + +## Carried Non-Blocking Hardening Risks + +The following pre-existing risks were not introduced or worsened by the final repairs: + +1. Pathname guarantees rely on the documented cooperative-writer boundary, not protection from arbitrary malicious same-user or privileged mutation. +2. Materializer generic text/reference exceptions remain broader than ideal. +3. Existing topology exclusions are broad enough to hide future product content placed below excluded roots. +4. Package/E3 commit identity is caller-supplied outside the protected CI release flow. + +These are hardening debt and claim-boundary constraints, not regressions in the reviewed final delta. + +## Structured Result + +```yaml +status: passed_with_environment_issue +verdict: approved +patch_security_verdict: approved +verification_verdict: passed_with_environment_issue +release_verdict: do_not_release_from_current_checkout +report_path: verification/code-review-report.md +summary: + critical: 0 + warning: 1 + info: 2 + production_regressions: 0 + test_regressions: 0 +issues: + - id: W-ENV-01 + source: code_review + severity: warning + category: verification_environment + description: ignored local IDE state blocks the real-checkout topology test + location: .idea/workspace.xml + production_defect: false + classification: environment_residue + fixable: true + suggestion: rerun in a clean isolated checkout or use Git-aware topology enumeration; do not add an editor-specific exclusion + - id: I-REL-01 + source: code_review + severity: info + category: release_precondition + description: strict parity correctly refuses the dirty shared checkout + location: repository_worktree + production_defect: false + fixable: true + suggestion: run strict parity and same-job release checks in a clean isolated checkout + - id: I-THREAT-01 + source: code_review + severity: info + category: security_claim_boundary + description: arbitrary GNU Make argv can execute during Make command-line parsing before any Makefile guard + location: Make invocation boundary + production_defect: false + fixable: false + suggestion: keep Make argv trusted and pass untrusted data only through fixed value fields +issue_counts: + critical: 0 + warning: 1 + info: 2 +carried_hardening_risks: + warning: 4 +repaired_boundaries: + lifecycle_materializer_source_binding: resolved + supported_targets_recipe_expansion: resolved_for_fixed_value_interface +test_only_repairs: + make_topology_contract: correct + immutable_overlay_fixture: correct +tests: + authoritative: 111/112 + focused_independent: passed + release_package: 4/4 + parity_dirty_local_diagnostic: 3/3_zero_unresolved + parity_strict: failed_closed_dirty_checkout +idea_topology: + classification: environment_residue + production_defect: false + test_contract_defect: false + explicit_idea_exclusion_recommended: false +production_code_modified: false +tests_modified: false +ide_state_modified: false +``` diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/completeness-check.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/completeness-check.md new file mode 100644 index 00000000..6ff82b69 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/completeness-check.md @@ -0,0 +1,268 @@ +# Implementation Completeness Check — Resumed Phase 11 Final Re-Verification + +## TL;DR + +**Verdict: `passed_with_issues`; 0 critical, 1 warning, and 2 informational findings.** The approved implementation is complete at **39/39 plan steps** and **17/17 specification requirements**, and both former P1 trust-boundary defects remain resolved. +The two stale test contracts from the preceding cycle are repaired: the overlay-negative case passes, and the replacement Make/registry assertions are supported by passing constituent tests and code inspection; the authoritative suite is **111/112 (99.11%)** with no production or repaired-security regression. +The sole red test is the correct fail-closed topology check finding 554 legacy-path mentions in ignored, operator-owned `.idea/workspace.xml`; production code, test code, tracked topology, and IDE state were not changed by this review. +Release publication remains conditional on the unchanged strict parity and release sequence passing from a clean isolated checkout. + +## Key Decisions + +- Mark completeness `passed_with_issues` — plan and requirement coverage are complete, the pass rate exceeds the workflow threshold, and the only test failure is unrelated ignored IDE state rather than a product or test-code defect. +- Keep both former P1 findings resolved — lifecycle/materialization share one immutable source binding, and Make rejects `SUPPORTED_TARGETS` overrides without expanding their values. +- Accept both test-contract repairs — the topology test now asserts the non-configurable Make guard plus Node-owned target enumeration, and the overlay-negative fixture now reaches its intended source-bound overlay failure. +- Preserve topology and parity fail-closed behavior — ignored workspace residue must not be allowlisted merely to make the shared checkout green. + +## Open Questions / Risks + +- `.idea/workspace.xml` continues to block the real-checkout topology test and therefore `make validate`; re-run unchanged verification in a clean isolated checkout or after the operator removes that IDE residue. +- Strict release parity has not passed in this dirty shared checkout. The zero-unresolved three-target result is diagnostic only and does not authorize publication. +- Native E5/E6 remains environment-dependent and unavailable where no reviewed host scenario is configured; it must not be represented as passed evidence. + +## Scope and Inputs + +- Repository: `/Users/mrapacz/Workspace/maister` +- Task: `.maister/tasks/development/2026-07-14-platform-independent-plugin` +- Generated: `2026-07-15T21:57:59Z` +- Workflow state: Phase 11 in progress; resumed fix iteration 2 complete; final independent re-verification in progress +- Reviewed: `RTK.md`, `.maister/docs/INDEX.md`, all nine indexed standards, project vision/architecture/tech stack, orchestrator state, specification, implementation plan, work log, current production and test code, Make/release interfaces, and final `verification/test-suite-results.md` +- Independently executed: five repaired-boundary/contract cases and direct topology/Git-ignore diagnostics +- Production code modified: no +- Test code modified: no +- IDE state modified: no +- Artifact replaced: `verification/completeness-check.md` only + +## Structured Verdict + +| Dimension | Result | Assessment | +| --- | ---: | --- | +| Overall completeness | `passed_with_issues` | Complete implementation with one environment-specific suite warning | +| Plan steps | 39/39 | Complete; 0 unchecked | +| Task groups | 5/5 | Each has implementation and test evidence | +| Specification requirements | 17/17 | Implemented; release/native-evidence qualifications remain explicit | +| Authoritative suite | 111/112 (99.11%) | One ignored-IDE topology failure; 0 product regressions | +| Independent repaired contracts | 4/5 | Four product/test contracts pass; the same IDE residue blocks only the topology case | +| Former P1 blockers | 2/2 resolved | No exploit regression reproduced | +| Former stale test contracts | 2/2 repaired | Both intended assertions pass independently | +| Packaged lifecycle | 4/4 | Deterministic extracted install/verify/uninstall evidence is green | +| Dirty-local parity | 3/3 targets; 0 unresolved | Diagnostic only | +| Strict release parity | Failed closed with `E_SOURCE_DIRTY` | Correct release precondition, not a release pass | +| Issue counts | 0 critical / 1 warning / 2 info | No production blocker found by completeness review | + +## Final Assessment of the Two Prior P1 Findings + +### P1-001 — Lifecycle source root A could diverge from materialized root B + +**Resolved.** + +The current install/update path establishes a singular source binding before target state is created: + +1. `executeLifecycle()` resolves or revalidates one source object and calls `assertSourceRootBinding()` before `getTargetPaths()` and `ensureDirectories()` (`transaction-manager.mjs:1037-1046`). +2. A caller-supplied `resolvedSourceRoot` or local/file source must resolve to the same real root or fails with `E_SOURCE_ROOT` (`transaction-manager.mjs:476-493`). +3. Source-bound overlay lookup uses only the resolved source root and does not fall back to the running checkout (`transaction-manager.mjs:521-547`, `747-753`). +4. `materialize()` receives the same `resolvedSource`, revalidates it before and after assembly, and returns the final source binding (`materializer.mjs:847-849`, `889-922`). +5. `assertMaterializedSourceBinding()` compares root, commit, version, content hash, dirtiness, and status fingerprint before the transaction proceeds (`transaction-manager.mjs:496-519`, `776`). + +Independent execution of `direct lifecycle rejects split resolved and materialized source roots before state mutation` passed. The adversarial A/B input is rejected before either target state or target content exists (`installer-transaction.test.mjs:395-426`). + +### P1-002 — GNU Make expanded caller-controlled `SUPPORTED_TARGETS` before validation + +**Resolved.** + +The Makefile no longer owns or interpolates a supported-target list. Its parse-time guard inspects only `$(origin SUPPORTED_TARGETS)` and errors when the variable is defined (`Makefile:3-6`); it never expands the caller-controlled value. All-target overlay validation delegates to `release-interface.mjs validate-overlays` (`Makefile:63-65`), which enumerates the immutable registry exported by `targets.mjs`. + +Independent execution passed both relevant contracts: + +- `SUPPORTED_TARGETS=$(shell touch ...)` is rejected without creating its marker. +- Shell-metacharacter input is rejected without creating its marker. +- Normal registry enumeration returns `codex`, `cursor`, and `kiro-cli`, all valid (`make-interface.test.mjs:43-70`). + +No Make-owned target declaration should be restored; doing so would reopen the rejected ownership and evaluation boundary. + +## Final Assessment of the Two Test-Contract Repairs + +| Prior defect | Repair | Independent result | Assessment | +| --- | --- | --- | --- | +| Topology test required a literal Make-owned `SUPPORTED_TARGETS := ...` registry | It now forbids that declaration, asserts the non-configurable guard, and checks `release-interface.mjs validate-overlays` delegation (`evidence-parity-topology.test.mjs:927-934`) | The central-registry contract passed; the combined topology case advances through those assertions only when the real-checkout scan is clean | Repaired; current failure occurs earlier on `.idea`, not on the new contract | +| Overlay-outside-source test used a copied non-Git fixture and failed at `E_SOURCE_GIT` before its intended assertion | The fixture now supplies a valid source-bound Git identity and retains no-target/no-receipt assertions | `install fails closed when the overlay is outside the resolved source root and leaves no target` passed | Repaired and behavior-focused | + +The repairs align with `testing/test-writing.md`: they exercise the intended boundary and verify rejection/non-mutation, without weakening immutable source validation or restoring unsafe Make ownership. + +## Sole Remaining Test Failure + +### COMP-W-001 — Ignored IDE workspace residue blocks the real-checkout topology gate + +- **Severity:** `warning` +- **Location:** `.idea/workspace.xml` +- **Git ownership:** ignored by `.gitignore:5`; absent from `git ls-files` and normal tracked status +- **Failing test:** `the real repository topology and focused Make entry point use only registered hosts` at `evidence-parity-topology.test.mjs:918` +- **Observed error:** `E_TOPOLOGY_STALE` +- **Scanner result:** two forbidden-reference violations, both for `.idea/workspace.xml` +- **Raw residue count:** 554 mentions matching `plugins/maister-(codex|cursor|kiro)` or `platforms/(codex-cli|cursor|kiro-cli)` +- **Product/test impact:** none found; no production or test file contains the reported failing bytes +- **Regression risk:** low; the other four repaired contracts passed and neither former P1 exploit reproduced + +**Classification: environment residue — not a production/spec defect and not a test defect. An explicit `.idea` exclusion is inappropriate.** The scanner deliberately examines the real filesystem because ignored inputs are part of local source hashing and strict release cleanliness. The safe resolution is an unchanged run from an isolated clean checkout or operator cleanup of the IDE-owned residue. This review did not modify `.idea`. + +## Plan Completion and Code Spot Checks + +| Task group | Plan state | Representative evidence | Result | +| --- | ---: | --- | --- | +| 1. Portable core and overlay contracts | 7/7 | `common/primitives.yml`, overlay v1 schema/loader, three target overlays, overlay tests | Complete | +| 2. Source resolution and materialization | 8/8 | `source-resolver.mjs`, `materializer.mjs`, provenance/hash/path validation, source/materializer tests | Complete | +| 3. Transactional lifecycle | 10/10 | CLI contract, transaction manager, journal/receipt schemas, settings/drift/recovery modules and tests | Complete | +| 4. Evidence, parity, topology, release/docs | 9/9 | evidence schema/policy/probes, immutable parity oracle, release interface, Make/CI/docs, deleted legacy topology | Complete with clean-release qualification | +| 5. Test review and gap analysis | 5/5 | ten platform-independent test files and requirement-oriented regressions | Complete; current real-checkout failure is local IDE state | + +All 39 checkboxes are marked complete, and the declared components exist. Group 5's original 34-test cap describes the initial implementation pass; Phase 11 security repair and regression work expanded the authoritative suite to 112. That expansion is justified by newly discovered high-risk boundaries and should be recorded as final accounting rather than reversed. + +## Specification Alignment + +| Requirements | Result | Evidence / qualification | +| --- | --- | --- | +| R1-R3: portable common source, overlays, single runtime | Pass | One common source and three explicit target overlays are present; no generated runtime copies remain supported. | +| R4: immutable source provenance | Pass | Singular source binding is revalidated through overlay selection and materialization; P1-001 is closed. | +| R5: target-aware lifecycle | Pass | Install, update, status/verify, uninstall, rollback, and recovery exist for all registry targets. | +| R6: staged validation before mutation | Pass | Source identity is checked before state creation; assembly validates containment, inventory, syntax, modes, hashes, references, and symlinks. | +| R7-R10: transaction, receipt, ownership, drift | Pass on current evidence | Journals, exact backups, receipts, whole-file/managed-key ownership, rollback/recovery, and no-mutation rejection tests exist. | +| R11-R13: capability evidence and freshness | Pass | Passed/failed/unavailable, provenance, expiry, renewal, and fail-closed policy are implemented; unavailable is not promoted. | +| R14: core-once and focused host seams | Pass with environment warning | 111/112 authoritative tests pass; the sole failure is ignored IDE topology residue. | +| R15: zero-unresolved parity | Conditional release pass | Dirty-local diagnostic parity is zero-unresolved for all three targets; strict clean evidence remains required. | +| R16: remove Claude/generated/marketplace topology | Pass in tracked implementation | The scanner's only finding is ignored IDE history; active production/docs/test topology has no reported violation. | +| R17: docs, standards, Make, CI, release alignment | Pass | Current architecture and operator guidance use the common-source/three-overlay model and Node-owned target registry. | + +No specification requirement is missing from the implementation. + +## Standards Compliance + +| Standard | Applies? | Result | Reasoning | +| --- | --- | --- | --- | +| `global/build-pipeline.md` | Yes | Pass | Node owns target enumeration; target-aware validation, parity, package, and lifecycle boundaries are present. | +| `global/coding-style.md` | Yes | Pass by spot check | Repaired helpers are focused, descriptive, and consistent with the ESM codebase. | +| `global/commenting.md` | Yes | Pass by spot check | Source revalidation comments explain lasting invariants rather than change history. | +| `global/conventions.md` | Yes | Pass | Clean-source, disposable-dist, ownership/concurrency, recovery, and supported-target rules remain explicit. | +| `global/error-handling.md` | Yes | Pass | Both repaired boundaries fail with typed actionable errors before target mutation. | +| `global/language-md-convention.md` | No | Not applicable | This migration does not adopt or modify DDD `language.md` boundaries. | +| `global/minimal-implementation.md` | Yes | Pass | Repairs reuse the existing source binding and central target registry without a second policy layer. | +| `global/validation.md` | Yes | Pass | Source identity is validated/revalidated around assembly; Make rejects unsafe configuration before value evaluation. | +| `testing/test-writing.md` | Yes | Pass | Former stale contracts now reach their intended boundaries; P1 tests prove sentinel non-execution and exact pre-mutation rejection. | + +Standards status is `compliant`: all eight applicable indexed standards are followed on the inspected boundaries. The `.idea` failure demonstrates that topology validation remains fail closed; it is not a standards violation in product or test code. + +## Documentation Completeness + +The specification, plan, and work log are intact. All five task groups have dated implementation entries, the resumed P1 repairs and both test-contract repairs are recorded, and the final entry accurately marks independent verification as pending. README, project documentation, standards, Make, CI, release instructions, and support descriptions consistently use the common-source/three-overlay architecture. + +Documentation status is `complete` for the implementation handoff. Two bookkeeping notes remain informational: + +1. The orchestrator should append the final Phase 11 result after all independent reviews complete; the current work-log entry correctly does not pre-claim that verdict. +2. Final accounting should preserve the original Group 5 limit as the initial-scope decision while recording that approved Phase 11 security regressions expanded the suite to 112. + +## Findings Requiring Attention + +### COMP-W-001 — Ignored `.idea` topology residue + +- **Source:** test suite / environment +- **Severity:** `warning` +- **Fixable:** `true` by operator or isolated-checkout execution +- **Suggestion:** Re-run unchanged verification in a clean isolated checkout or remove the operator-owned `.idea/workspace.xml` residue. Do not weaken scanner exclusions. + +### COMP-I-001 — Strict clean release evidence remains pending + +- **Source:** release precondition +- **Severity:** `info` +- **Fixable:** `true` in the release environment +- **Location:** repository worktree / `verification/test-suite-results.md` +- **Suggestion:** Run strict parity and all same-job package checks from a clean isolated checkout before publication. + +### COMP-I-002 — Native E5/E6 evidence remains environment-dependent + +- **Source:** specification / capability evidence +- **Severity:** `info` +- **Fixable:** `true` when reviewed native scenarios and required runtimes are available +- **Location:** capability evidence records and release claims +- **Suggestion:** Renew evidence against configured versioned scenarios before making native discovery or semantic support claims. + +## Structured Result + +```yaml +status: passed_with_issues +report_path: verification/completeness-check.md +generated: 2026-07-15T21:57:59Z +plan_completion: + status: complete + total_steps: 39 + completed_steps: 39 + completion_percentage: 100 + missing_steps: [] + task_groups_complete: 5 +standards_compliance: + status: compliant + standards_checked: 9 + standards_applicable: 8 + standards_followed: 8 + gaps: [] +documentation: + status: complete + issues: [] +requirements: + mapped: 17 + total: 17 +tests: + authoritative_total: 112 + authoritative_passed: 111 + authoritative_failed: 1 + pass_rate: 99.11 + production_regressions: 0 +prior_p1_blockers: + total: 2 + resolved: 2 + lifecycle_source_binding_ab: resolved + supported_targets_make_expansion: resolved +test_contract_repairs: + total: 2 + repaired: 2 + topology_make_registry_contract: passed_before_environment_precondition + overlay_negative_fixture_contract: passed +sole_failure: + test: the real repository topology and focused Make entry point use only registered hosts + classification: environment_specific_ignored_ide_state + path: .idea/workspace.xml + ignored_by_git: true + stale_reference_matches: 554 + topology_violations: 2 +release_evidence: + package_lifecycle: passed_4_of_4 + dirty_local_parity: passed_3_of_3_zero_unresolved + strict_parity: failed_closed_dirty_checkout +issues: + - id: COMP-W-001 + source: test_suite + severity: warning + description: Ignored IDE workspace state blocks the real-checkout topology gate. + location: .idea/workspace.xml + fixable: true + suggestion: Re-run in a clean isolated checkout or remove the operator-owned IDE residue; do not weaken topology scanning. + - id: COMP-I-001 + source: release_precondition + severity: info + description: Strict clean-checkout release parity remains pending. + location: repository worktree + fixable: true + suggestion: Run the unchanged strict release sequence from a clean isolated checkout. + - id: COMP-I-002 + source: documentation + severity: info + description: Native E5/E6 evidence remains unavailable where no reviewed versioned scenario is configured. + location: capability evidence + fixable: true + suggestion: Renew native evidence before making native support claims. +issue_counts: + critical: 0 + warning: 1 + info: 2 +production_code_modified: false +test_code_modified: false +ide_state_modified: false +``` diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/completeness-report.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/completeness-report.md new file mode 100644 index 00000000..17e7794f --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/completeness-report.md @@ -0,0 +1,149 @@ +# Implementation Completeness Report — Phase 11 Re-verification + +## TL;DR + +Status: `passed_with_issues`; implementation-plan completion is 100% (39/39 checked steps). +The post-fix test evidence is green: 60/60 feature tests, 58/58 validation tests, all three overlays, topology, parity, deterministic archives, and extracted lifecycles pass. +The two prior completeness warnings are resolved: `docs/commands.md` is host-neutral and source-materializer symlink fixtures are per-test copies. +Residual issues are documentation contradictions about already-fixed GitHub/recovery behavior, plus unqualified active Claude wording in common instruction files. + +## Key Decisions + +- Count implementation completeness from the approved Markdown plan: 39 checked, 0 unchecked, 0 skipped. The HTML companion independently contains 39 `done` steps and 5 `done` groups. +- Treat the 60-test post-fix suite as valid additional regression coverage, not as missing implementation. The fix loop added tests beyond the original Group 5 cap to cover release closure, provenance, transaction durability, evidence, and fixture isolation. +- Treat E6 as an explicit permitted availability state: all three native E6 outcomes are `unavailable` with `scenario-not-configured`; none is promoted to `passed`. +- Treat the original `docs/commands.md` stale-wording warning and shared-fixture warning as closed. Do not carry them forward as active findings. +- Keep documentation contradictions as current completeness issues because they are in active operator/project documentation and conflict with the post-fix implementation and verification evidence. +- Do not treat the intentionally dirty/shared worktree as a clean-checkout release claim; the test-suite report explicitly records that limitation. + +## Open Questions / Risks + +- Native E6 scenario probes remain unavailable for Codex, Cursor, and Kiro CLI. This is allowed by `spec.md`, but a release requiring native runtime scenarios still needs bounded host-specific probes. +- No real-network GitHub fetch was used in the repository test suite. The production resolver exists and the public CLI test injects the resolver boundary, which is appropriate for offline-safe tests; a network-enabled release smoke would add operational confidence. +- Verification evidence was collected in a shared, intentionally dirty worktree with concurrent activity. It proves the current observed tree and tests, not a clean-checkout build claim. +- The original plan expected 26–34 feature tests, while the post-fix suite contains 60. The extra tests are justified by the fix loop but the plan/log do not explicitly record this cap exception. + +## Scope and Evidence Sources + +This is a read-only completeness audit. Only this report was overwritten. No source, test, plan, state, dashboard, work log, documentation, or other verification report was modified. + +Reviewed: + +- `implementation/spec.md` +- `implementation/implementation-plan.md` +- `implementation/work-log.md` +- `.maister/docs/INDEX.md` and the indexed global/testing standards relevant to this task +- `verification/test-suite-results.md` +- current implementation, test, workflow, documentation, and topology files + +The current workflow state remains Phase 11 `in_progress`; later E2E, user-documentation, and finalization phases are pending. Those workflow phases are not counted as unchecked implementation-plan steps. + +## Implementation Percentage and Plan Audit + +**Implementation percentage: 100% — 39/39 checked implementation steps.** + +| Group | Checked steps | Current evidence | Assessment | +| --- | ---: | --- | --- | +| 1. Portable core and overlay v1 | 1.0–1.6 | `common/primitives.yml`, strict overlay schema, three overlays/inventories/assets, `overlay-loader.mjs`, `errors.mjs`, validator, overlay tests | Complete. Nine current overlay-contract tests pass; all three direct validators report `ok=true`. | +| 2. Immutable source and materialization | 2.0–2.7 | `source-resolver.mjs`, `hash-tree.mjs`, materializer/path safety, source tests and fixtures | Complete. Fifteen current source/materializer tests pass, including ref/HEAD equality, dirty/ignored rejection, timeout typing, containment, symlinks, inventory, syntax, modes, references, and hashes. | +| 3. Transactional installer | 3.0–3.9 | installer, transaction/recovery/settings/receipt/journal modules and installer tests | Complete. Twenty-one current installer tests pass, including exact rollback/recovery, receipt/evidence provenance, settings ownership, drift, locks, and failure boundaries. | +| 4. Evidence, parity, topology, release/docs | 4.0–4.8 | evidence/parity/topology implementation, Make/CI/release, documentation, deletion/topology checks | Complete as implementation. Thirteen evidence/topology tests pass; all overlays, Cursor projection, parity/topology, release package, and documentation gates are represented. Documentation contradictions remain as findings below. | +| 5. Test review and gap analysis | 5.0–5.4 | work-log mapping, current platform-independent suite, targeted regression tests | Complete. The 17 requirements and legacy-deletion criteria are represented by focused assertions; the fix loop expanded regression coverage beyond the original cap. | + +The Markdown plan contains exactly 39 checked checkbox lines and no unchecked or skipped checkbox lines. The HTML companion contains 39 `class="step done"` entries and 5 `class="group done"` entries. + +## Requirement Mapping + +| Requirement | Evidence | Result | +| --- | --- | --- | +| R1–R3: common source, six primitives, single-source runtime | `plugins/maister/common/primitives.yml`; overlay-contract primitive ownership test; canonical runtime under `plugins/maister/skills/orchestrator-framework/bin/` | Pass. No copied portable runtime modules are used as maintained distribution inputs. | +| R2: target overlays and inventories | `plugins/maister/overlays/{codex,cursor,kiro-cli}`; strict schema; three validator runs; overlay tests | Pass. Target, discovery/layout roots, settings, bindings, inventory, vocabulary, executable paths, and E1–E6 claims are explicit. | +| R4: immutable local/GitHub provenance | `source-resolver.mjs:30-43,78-123,210-265,273-318,333-387`; source tests; injected public-CLI GitHub test | Pass with offline-smoke limitation. Safe refs, full commits, clean/ignored status, HEAD equality, bounded Git, one detached checkout, cleanup, and same source/overlay root are implemented. | +| R5: lifecycle operations | installer tests and release archive lifecycle test | Pass. Install, update, status/verify, uninstall, rollback, and recovery are covered; packaged install/verify/uninstall runs for all targets. | +| R6: validation before mutation | materializer/path-safety/overlay loader and source/materializer tests | Pass. Paths, collisions, inventories, references, syntax, modes, hashes, symlinks, source fallback, and staging containment are exercised. | +| R7: transaction/recovery/rollback safety | installer tests for locks, snapshots, commit failure, failed journals, journal selection, rollback, exact bytes/modes/links/topology | Pass according to current implementation and `test-suite-results.md`. | +| R8: receipt ownership/provenance | receipt/journal schema, transaction manager, installer provenance/evidence tests | Pass. Receipts carry target/source/hash/evidence/transaction data and are validated around lifecycle transitions. | +| R9–R10: settings ownership and drift | settings-owner/drift-detector implementation; whole-file and managed-key tests; uninstall/update drift tests | Pass. Unmanaged content is preserved and unsafe owned drift is refused. | +| R11–R13: capability evidence/freshness | evidence schema/policy/probes and 13 evidence/topology tests | Pass. Evidence has provenance/expiry; renewal and fail-closed semantics are covered; unavailable is never a pass. | +| R14: core-once and host-seam testing | Make targets; 60-test suite split into common/host seams; current test-suite results | Pass. Core behavior is not copied into per-host runtime suites. | +| R15: parity and zero unresolved differences | versioned per-target parity baselines; parity tests; work-log pre-deletion parity record; topology gate | Pass on recorded current evidence: zero unresolved differences and zero topology violations. | +| R16: removal of Claude/generated/marketplace support | deleted legacy paths and marketplace files; topology test; current topology result `violations=[]` | Pass for supported topology. Residual unqualified Claude wording in active common instructions is a documentation/source-hygiene issue below, not a supported install path. | +| R17: docs, standards, Make, CI, release, support alignment | updated README/docs/project/standards, Make all-target validation, release archive/checksum smoke, pinned release actions | Pass with documentation residuals. The release path is aligned, but several operator/project paragraphs still describe old recovery/GitHub behavior. | + +## Standards Assessment + +The standards listed by `.maister/docs/INDEX.md` were read and compared with the current tree. + +| Standard | Result | Evidence / qualification | +| --- | --- | --- | +| `global/minimal-implementation.md` | Pass | Six semantic primitives and narrow source/overlay/release seams; no general workflow DSL or speculative runtime abstraction. | +| `global/error-handling.md` | Pass | Typed `E_SOURCE_*`, `E_OVERLAY_*`, transaction/recovery errors, retryable timeout behavior, fail-closed boundaries, and cleanup in `finally`. | +| `global/validation.md` | Pass | Allowlists and early validation for overlays, paths, sources, staging, inventory, permissions, hashes, evidence, parity, and release artifacts. | +| `global/build-pipeline.md` | Pass with documentation qualification | `make validate` loops all targets; package and extracted lifecycle are release gates; deterministic archives, checksums, and pinned release actions are present. | +| `global/coding-style.md` / `commenting.md` | Pass by inspection | Focused ESM modules, descriptive names, and no change-log-style implementation comments observed. | +| `global/conventions.md` | Pass with documentation qualification | Production clean-source rules and explicit development dirty mode are documented, but stale operator wording remains in README/docs (DOC-001). | +| `testing/test-writing.md` | Pass for current tests | Tests assert bytes, modes, symlinks, existence, topology, rollback, evidence state, archive closure, deterministic hashes, and fixture isolation. | +| `language-md-convention.md` | Not applicable | This task does not create or change a bounded-context language model. | +| Frontend/backend standards | Not applicable | The INDEX states these standards are not initialized for this project. | + +## Test and Evidence Mapping + +The current platform-independent test inventory is 60 tests: + +| Test file | Count | Coverage | +| --- | ---: | --- | +| `overlay-contract.test.mjs` | 9 | v1 schema, primitives, Cursor projection, ownership, paths, collisions, vocabulary | +| `source-materializer.test.mjs` | 15 | immutable source, Git/ref/timeout behavior, deterministic materialization, containment, symlinks, inventory, syntax, modes, hashes, references | +| `installer-transaction.test.mjs` | 21 | lifecycle, settings, locks, drift, transaction failure, recovery/rollback, receipt/evidence provenance | +| `evidence-parity-topology.test.mjs` | 13 | E1–E6, expiry, unavailable/fail-closed policy, host probes, parity, topology | +| `release-package.test.mjs` | 2 | deterministic self-contained archives, target isolation, extracted three-target lifecycle, same injected GitHub checkout | +| **Total** | **60** | **60 passed according to `test-suite-results.md`** | + +Recorded post-fix commands and results: + +- `make test-platform-independent`: 60 passed, 0 failed, 0 skipped (`verification/test-suite-results.md:44-74`). +- `make validate`: all three overlays passed; core 45/45; evidence/parity 13/13; topology `violations=[]` (`verification/test-suite-results.md:76-110`). +- `node --test tests/platform-independent/release-package.test.mjs`: 2 passed; two deterministic builds per target and extracted install/verify/uninstall for all targets (`verification/test-suite-results.md:112-135`). +- Installed native probes: E5 passed for Codex, Cursor, and Kiro CLI; E6 unavailable for all three with `scenario-not-configured` (`verification/test-suite-results.md:154-176`). +- `make test-topology`: independently rerun during this audit and returned `{"ok":true,"violations":[]}`. +- `git diff --check`: independently rerun during this audit with no diagnostics. + +## Original Completeness Warning Closure + +| Original warning | Current result | Evidence | +| --- | --- | --- | +| Stale Claude wording in `docs/commands.md:209` | **Resolved** | Current line 209 says “the host's built-in plan mode”; the former Claude-specific sentence is gone. | +| Mutable shared source fixture in symlink tests | **Resolved** | `cloneFixtureSource()` is used at `source-materializer.test.mjs:233` and `:264`; symlink/cycle mutations occur only under per-test temporary copies and are cleaned in `finally`. | +| Missing final verification log entry | **Not an implementation issue** | Phase 11 is still `in_progress`, later finalization is pending, and this report is the current re-verification artifact. The assignment prohibits editing `work-log.md`. | + +## Residual Issues + +### COMP-001 — Active documentation contradicts the post-fix GitHub/recovery implementation + +- **Severity:** `warning` +- **Location:** `README.md:67,77,93`; `docs/README.md:12`; `.maister/docs/project/architecture.md:11` +- **Fixable:** `true` +- **Suggestion:** Update these paragraphs to describe the implemented bounded GitHub resolver and current tested recovery/rollback behavior. If process-signal recovery remains intentionally unverified, state that as an evidence limitation rather than claiming that GitHub is unavailable or that known recovery gaps remain release blockers. +- **Evidence:** `README.md:17-54` documents and the current `source-resolver.mjs` implement GitHub checkout resolution, while `README.md:77` still says “GitHub CLI resolution is not currently available.” `README.md:93`, `docs/README.md:12`, and `architecture.md:11` still call process interruption, journal selection, and rollback failure journaling known release blockers. `verification/test-suite-results.md:36-40,67-74` records passing transaction/recovery/release gates, and `work-log.md:126` says fix iteration 1 addressed transaction/recovery durability. These are active operator/project statements, not historical/parity sections. + +### COMP-002 — Unqualified Claude wording remains in active common instructions + +- **Severity:** `warning` +- **Location:** `plugins/maister/skills/quick-plan/SKILL.md:9`; `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:68`; `plugins/maister/agents/e2e-test-verifier.md:472`; `plugins/maister/skills/init/SKILL.md:215,224`; `plugins/maister/skills/standards-discover/SKILL.md:177`; related `standards-update` and migration-reference files found by the current repository scan +- **Fixable:** `true` +- **Suggestion:** Replace host-specific prose with host-neutral wording, or explicitly mark a compatibility/parity reference as historical. Do not alter intentional forbidden-vocabulary patterns in overlay contracts or parity fixtures; those are validation data and are not this issue. +- **Evidence:** The current repository scan still finds direct active instructions such as “Claude Code's built-in plan mode” and “Configure MCP server in Claude Code.” `.maister/docs/standards/global/conventions.md:17` permits migration-era names only in clearly labeled historical/parity sections, while these files are active common skills/agent instructions. The topology test passes because it validates repository topology/path classes, not every semantic mention in common instruction prose. + +### COMP-003 — Post-fix test inventory exceeds the approved plan cap without an explicit exception record + +- **Severity:** `info` +- **Location:** `implementation/spec.md:135-140`; `implementation/implementation-plan.md:226-243`; current `tests/platform-independent/*.test.mjs`; `verification/test-suite-results.md:3-5` +- **Fixable:** `true` +- **Suggestion:** Record the Phase 11 regression-test expansion as an approved exception or revise the test-count documentation in a later workflow phase. Preserve the additional tests; they cover real fix-loop risks and all currently pass. +- **Evidence:** The plan describes a 26–34 feature-test range and Group 5 says no more than eight strategic additions. The current inventory is 60 tests: 9 overlay, 15 source/materializer, 21 installer, 13 evidence/topology, and 2 release. The work log records the original 34-test cap but does not record the subsequent fix-loop expansion. + +## Final Assessment + +The implementation is complete against the checked implementation plan: **39/39 steps, 100%**. The current repository also has strong post-fix executable evidence: **60/60 feature tests**, **58/58 validation tests**, all target overlays, deterministic self-contained package smoke, parity/topology, and E5 probes pass; E6 is explicitly unavailable and remains non-passing. + +The correct post-fix completeness status is **`passed_with_issues`**, not failed: the remaining findings are fixable documentation/source-hygiene and plan-accounting issues, not missing implementation steps or failing executable gates. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/implementation-verification.html b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/implementation-verification.html new file mode 100644 index 00000000..fd2bdfb3 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/implementation-verification.html @@ -0,0 +1,277 @@ + + + + +Implementation Verification — Platform-independent Maister distribution + + + + + +
+ Final Phase 11 +

Implementation Verification

+

Platform-independent Maister distribution · Generated 2026-07-15T22:26:39Z

+
+ +
+
Passedimplementation
+
114/114authoritative tests
+
39/39plan steps
+
17/17requirements
+
0open issues
+
+ +
+

✅ Passed — Phase 11 may advance

+

The implementation is complete at 39/39 plan steps and 17/17 requirements. The authoritative suite passes 114/114, focused evidence/topology passes 20/20, make validate is green, package lifecycle passes 4/4, and clean committed-clone strict parity passes for all three targets with zero unresolved differences.

+

Both former P1 defects, both stale test contracts, and the environment-coupled topology contract are resolved. There are 0 critical, 0 warning, and 0 informational implementation findings.

+

Key Decisions

+
    +
  • Set the canonical implementation verdict to Passed and allow Phase 11 to advance.
    • +
  • Close the source-binding and Make target-expansion P1 findings.
    • +
  • Approve the Git-aware topology repair without an editor-specific exclusion.
    • +
  • Track exact-tag publication controls outside the implementation issue count.
    • +
+

Open Questions / Risks

+
    +
  • Native E6 remains unavailable where no reviewed host runtime/scenario exists.
    • +
  • Unsigned sidecars require a trusted release channel.
    • +
  • Filesystem safety uses the documented cooperative-writer model.
    • +
  • Free-form GNU Make argv remains trusted executable input.
    • +
  • The exact tag must repeat the clean release sequence and publication controls.
    • +
+
+ + + +
+
+

Overall Assessment

+
+ + + + + + + + + + + + + + +
CheckFinal resultEvidence
Overall implementationPassed0 open implementation findings
Plan / specificationPassed39/39 steps; 17/17 requirements
Authoritative suitePassed114/114; 100%
Integrated validationPassedmake validate exit 0
Evidence / topologyPassed20/20; zero direct violations
Package lifecyclePassed4/4 extracted-package tests
Strict clean parityPassed for release candidate3/3 targets; zero unresolved
Syntax / patch hygienePassed8/8 syntax; diff check clean
Code and securityApprovedBoth P1s closed; 0 regressions
Production / realityImplementation GOExact-tag publication conditional
+
+
+ +
+

Implementation Plan, Requirements, Standards, and Documentation

+
+

The approved plan is complete at 39/39 steps across 5/5 groups, and all 17/17 requirements map to implemented behavior and executable evidence. Phase 11 intentionally expanded the initial test estimate to cover trust boundaries discovered by independent review.

+ + + + + + + + + +
Task groupCompletionAssessment
Portable core and overlay contracts7/7Complete
Source resolution and materialization8/8Complete
Transactional lifecycle10/10Complete
Evidence, parity, topology, release, docs9/9Complete
Test review and gaps5/5Complete; security regressions retained
+

Standards: compliant. Build-pipeline, validation, error-handling, minimal-implementation, coding/commenting, conventions, and exact transactional testing rules are satisfied.

+

Documentation: complete for implementation handoff. The common-source/three-overlay architecture and clean-source, ownership, recovery, evidence, and publication boundaries are documented. Workflow state and the work log receive their normal completion update after this verifier returns.

+
+
+ +
+

Test and Release-Candidate Evidence

+
+ + + + + + + + + + + + + +
EnvironmentCheckResult
Shared checkoutmake test-platform-independent114/114
Shared checkoutmake validatePassed
Shared checkoutFocused evidence/topology20/20
Shared checkoutDirect topologyZero violations
Shared checkoutPackage lifecycle4/4
Shared checkoutSyntax / diff hygiene8/8 / passed
Clean committed cloneStrict parity3/3; zero unresolved
Clean committed cloneTopology / cleanlinessPassed / clean
Clean committed cloneIsolated packagesCodex, Cursor, Kiro CLI
+

Strict parity continues to reject the dirty shared checkout with E_SOURCE_DIRTY. That is required fail-closed behavior, not a failing implementation check.

+
+
+ +
+

Independent Review Results

+
+ + + + + + + + + +
TrackStatusFinal conclusion
CompletenessPassed39/39 steps and 17/17 requirements; interim IDE warning superseded.
Code / securityApprovedBoth P1s closed; repaired tests reach intended boundaries; no regression.
PragmaticApproved after repairComplexity proportionate; recommended Git-aware topology contract implemented.
Production readinessImplementation GORelease-candidate ready; tag publication retains process conditions.
RealityREADY / GOFunctional and clean-clone evidence proves intended supported scope.
+
+
+ +
+

Fix & Re-Verification History

+
+ + + + + + + + + + + + +
CycleIssue and fixOutcome
Initial / fix 1Target containment, archive closure, immutable source, recovery, and rollback/journal hardening.60/60; four deeper blockers remained.
Reverify 1 / fix 2Descriptor identity, backup manifests, recovery, E3/E4, parity, release metadata, and validation.91/91; four trust-boundary blockers remained.
Reverify 2 / fix 3No-follow state reads, source rebinding, same-root overlay, E3 binding, safe Make boundary, syntax/reference hardening.109/109; two P1s remained.
Reverify 3Confirmed split lifecycle/materializer source and pre-validation Make expansion.2 P1s preserved when prior workflow stopped.
Resumed repair 1One immutable source binding; Node-owned target registry and fixed Make delegation.Both P1s resolved; 0 regressions.
Resumed repair 2Updated Make/topology contract and source-bound overlay-negative fixture.Both stale test contracts resolved.
Final topology repairGit-aware repository candidates, raw fixture traversal, typed Git/read failures, adversarial coverage.114/114; topology 20/20; validate green.
Clean release-candidate verificationCommitted-clone strict parity, topology, cleanliness, isolated packages.3/3, zero unresolved; all packages.
+
+
+ +
+

Open Implementation Findings

+
+ + + + + + + +
SeverityCountStatus
Critical0None open
Warning0None open
Info0None open
+
+
+ +
+

Exact-Tag Publication Conditions

+
+

These are publication controls, not implementation findings. Before production publication, the release job must:

+
    +
  1. Repeat 114/114, integrated validation, strict three-target parity, topology, package generation/lifecycle, checksums, SBOM, and provenance verification at the exact clean tag commit.
    2. +
  2. Declare permissions: contents: write explicitly for the release publisher.
    3. +
  3. Recreate an isolated output directory, reject unexpected files, and publish only an explicit same-job allowlist of three archives and named verified sidecars.
    4. +
+

Release claims must preserve E5/E6 availability, unsigned-provenance, trusted-channel, cooperative-writer, and trusted-Make-argv boundaries. A failed tag condition blocks publication but changes the Phase 11 verdict only if it exposes a new implementation defect.

+
+
+ +
+

Verification Checklist

+
+
    +
  • Specification, plan, and work log present
    • +
  • 39/39 plan steps complete
    • +
  • 17/17 requirements covered
    • +
  • Authoritative suite 114/114
    • +
  • make validate passes
    • +
  • Evidence/topology 20/20
    • +
  • Direct topology zero violations
    • +
  • Package lifecycle 4/4
    • +
  • Clean strict parity 3/3
    • +
  • All three clean packages generated
    • +
  • Syntax and diff hygiene pass
    • +
  • Both P1 findings resolved
    • +
  • Both stale contracts resolved
    • +
  • Topology repair approved
    • +
  • No implementation issue remains
    • +
  • Exact-tag controls — release phase
    • +
+
+
+ +
+

Recommendation

+
+

Advance Phase 11. Continue the orchestrator's configured Phase 12/13 routing. Add the three publication controls before the next production release, renew native E5/E6 only against reviewed scenarios, and repeat the clean-clone evidence at the exact tag.

+
+
+
+ + diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/implementation-verification.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/implementation-verification.md new file mode 100644 index 00000000..01058382 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/implementation-verification.md @@ -0,0 +1,214 @@ +# Implementation Verification — Final Phase 11 Verdict + +## TL;DR + +**✅ Passed — 0 critical, 0 warning, and 0 informational implementation findings remain.** +The approved implementation is complete at **39/39 plan steps** and **17/17 requirements**; the authoritative suite passes **114/114**, focused evidence/topology passes **20/20**, `make validate` is green, and packaged lifecycle coverage passes **4/4**. +Both former P1 trust-boundary defects, both stale test contracts, and the environment-coupled topology contract are resolved. A clean committed clone also passed strict parity for all three targets with zero unresolved differences, stayed Git-clean, and generated all three packages. +**Phase 11 may advance.** Production publication remains conditional on repeating the complete release sequence at the exact tag commit and closing three release-workflow controls; those are publication conditions, not implementation failures. + +## Key Decisions + +- Set the canonical Phase 11 implementation verdict to **Passed**: implementation, tests, standards, documentation, security, pragmatic fit, and release-candidate reality all satisfy the verifier threshold. +- Close the two former P1 findings: install/update now carries one immutable source binding through overlay selection, materialization, evidence, and receipt publication; Make no longer owns or evaluates a caller-controlled target list. +- Close the two stale test-contract findings: the topology assertion now verifies Node-owned target enumeration, and the overlay-negative fixture reaches its intended immutable-source boundary. +- Approve the final Git-aware topology repair: repository checks scan tracked plus non-ignored untracked files, retain force-added ignored coverage, and fail closed on Git or read errors without an editor-specific exclusion. +- Keep exact-tag release controls separate from the implementation issue count. The verified tree is ready to merge and advance; publication is authorized only after the tag workflow reproduces the clean evidence and applies its release controls. + +## Open Questions / Risks + +- Native E6 remains `unavailable` where no reviewed host runtime/scenario exists. Packaging and transactional support must not be promoted to native semantic certification. +- Checksums, SBOM, and provenance are unsigned and establish integrity only through a trusted release channel. +- Installer locking coordinates cooperating Maister processes, not arbitrary host/editor/synchronization or privileged writers; operators must quiesce external writers. +- GNU Make command-line syntax is executable input before a Makefile loads. Automation must keep Make argv trusted and expose untrusted content only through fixed value fields. +- The exact release tag must repeat the complete clean-source validation and publication controls listed below. + +## Executive Summary + +Phase 11 independently verifies that the platform-independent distribution works for its approved scope: one portable source, explicit Codex/Cursor/Kiro CLI overlays, immutable source identity, deterministic materialization and packaging, receipt-backed transactional lifecycle operations, exact rollback/recovery evidence, capability evidence, and a clean parity/topology boundary. No critical, high, or lower-severity implementation defect remains open. + +The implementation is ready to merge and proceed through the remaining workflow phases. This verdict does not authorize publishing from the dirty shared checkout or from a pre-existing `dist/`; release publication is a separate exact-tag operation with three outstanding workflow controls. + +## Overall Assessment + +| Check | Final result | Evidence | +| --- | --- | --- | +| Overall implementation | **✅ Passed** | 0 open implementation findings | +| Implementation plan | **Passed** | 39/39 steps; 5/5 groups | +| Specification coverage | **Passed** | 17/17 requirements | +| Authoritative suite | **Passed** | 114/114; 100%; no skipped/cancelled/todo | +| Integrated validation | **Passed** | `make validate` exit 0 | +| Focused evidence/topology | **Passed** | 20/20; direct topology has zero violations | +| Packaged lifecycle | **Passed** | 4/4 deterministic extracted-package tests | +| Strict clean parity | **Passed for release candidate** | 3/3 targets; zero unresolved in a history-preserving committed clone | +| Package generation | **Passed** | Codex, Cursor, and Kiro CLI packages generated in isolated outputs | +| Syntax and patch hygiene | **Passed** | 8/8 syntax checks; `git diff --check` clean | +| Code/security review | **Approved** | Both P1s closed; 0 production/test regressions | +| Pragmatic review | **Approved after scoped repair** | Recommended Git-aware topology contract implemented and verified | +| Production readiness | **Implementation GO** | Release-candidate ready; exact-tag publication remains conditional | +| Reality assessment | **Ready / GO** | Functional and clean-clone release-candidate evidence green | + +## Implementation Plan and Requirements + +The approved plan is complete at **39/39 checked steps across 5/5 task groups**. All **17/17 specification requirements** are mapped to implemented behavior and executable evidence. The Phase 11 hardening work expanded the original feature-test estimate because independent reviews found additional trust boundaries; the additional tests are risk-driven regression coverage and are retained. + +| Task group | Completion | Final assessment | +| --- | ---: | --- | +| Portable core and overlay contracts | 7/7 | Complete | +| Immutable source resolution and materialization | 8/8 | Complete | +| Transactional installer, ownership, receipt, and recovery | 10/10 | Complete | +| Evidence, parity, topology, release, and documentation | 9/9 | Complete | +| Test review and gap analysis | 5/5 | Complete; later security regressions intentionally extend coverage | + +## Test Suite Results + +The authoritative command, `make test-platform-independent`, passed **114/114 tests across 10 files** with no failures, skips, cancellations, or todo cases. The final shared-checkout tree also passed `make validate`, the focused evidence/topology suite at **20/20**, direct topology validation, deterministic package lifecycle at **4/4**, eight JavaScript syntax checks, and patch hygiene. + +A separate history-preserving clone containing the final committed patch passed strict release parity for Codex, Cursor, and Kiro CLI with zero unresolved differences, passed topology validation, remained clean after validation, and generated all three target packages in isolated output directories. The dirty shared checkout continues to reject strict parity with `E_SOURCE_DIRTY`, which is the required fail-closed behavior. + +## Standards Compliance + +**Status: compliant.** The final implementation follows the applicable build-pipeline, validation, error-handling, minimal-implementation, coding/commenting, conventions, and transactional testing standards. In particular: + +- target enumeration has one Node-owned policy and fixed Make entry points; +- source, overlay, staging, ownership, evidence, receipt, journal, parity, and topology boundaries validate before mutation or publication; +- filesystem rejection and recovery tests assert bytes, modes, symlinks, existence, topology, and non-mutation; +- release output is deterministic, target-isolated, self-contained, and treated as disposable until same-job verification; and +- native `unavailable` evidence, unsigned provenance, and cooperative-writer limits remain explicit rather than being overclaimed. + +## Documentation Completeness + +**Status: complete for implementation handoff.** The specification, plan, work log, README/operator guidance, project documentation, standards, Make targets, CI, release instructions, and support model describe the common-source/three-overlay architecture and its clean-source, ownership, recovery, evidence, and publication boundaries. The workflow state and work log still require the orchestrator's normal Phase 11 completion update after this read-only verifier returns. + +## Independent Review Results + +### Completeness + +The implementation is complete at 39/39 steps and 17/17 requirements. The intermediate ignored-IDE warning is superseded by the approved Git-aware topology repair and final 114/114 evidence. + +### Code quality and security + +The patch is approved. The lifecycle/materializer source-binding split and pre-validation Make target expansion are closed, the repaired tests exercise their intended boundaries, and no production or test regression remains. Free-form GNU Make argv remains a trusted language-level boundary and is documented as such. + +### Pragmatic fit + +The implementation's complexity is proportionate to installing into user-owned host configuration with immutable provenance, multi-file transactions, exact rollback, three native layouts, capability evidence, and deterministic packaging. The pragmatic review's scoped Git-aware topology recommendation was implemented without a `.idea` exception and is now covered by passing ignored, untracked, force-added, Git-failure, and read-failure cases. + +### Production readiness + +The implementation and merge decisions are **GO**. Production publication is **conditional** because the exact tag workflow must explicitly request release permission, run the full suite, and publish a recreated allowlisted artifact set. These are process controls outside the implementation verdict. + +### Reality assessment + +The implementation is **READY**, the merge/release-candidate decision is **GO**, and exact-tag publication is **CONDITIONAL GO**. The clean committed-clone parity, topology, cleanliness, and package results prove that the final patch can satisfy its clean-source release boundary. + +## Fix & Re-Verification History + +| Cycle | Issue and fix | Re-check outcome | +| --- | --- | --- | +| Initial verification | Five critical groups exposed target-path containment, archive closure, immutable source, crash recovery, and rollback/journal gaps. The first hardening pass addressed transaction safety, release packages, resolver behavior, evidence, materialization, CI, and documentation. | **Resolved in part:** suite 60/60; four deeper blockers remained. | +| Re-verification 1 / fix 2 | Descriptor-backed path identity, cryptographic backup manifests, ordered recovery, independently generated E3, correctly finalized E4, immutable parity wiring, release metadata, and stricter validation were added. | **Resolved in part:** suite 91/91; four trust-boundary blockers remained. | +| Re-verification 2 / fix 3 | Persisted-state no-follow reads, local/injected source rebinding, same-root overlay selection, direct E3 hash binding, safe Make argv/environment boundaries, and stronger frontmatter/reference validation were added. | **Resolved in part:** suite 109/109; two P1 findings remained. | +| Re-verification 3 | P1-01 showed overlay/E3 root A could diverge from materialized root B. P1-02 showed `SUPPORTED_TARGETS` could be expanded by Make before Node validation. The prior workflow stopped after the exhausted loop, preserving both findings. | **Confirmed unresolved:** 2 P1s; 109/109 tests otherwise green. | +| Resumed baseline and repair 1 | One immutable source binding now drives overlay selection, materialization, evidence, and receipt provenance; direct A/B mismatch fails before state mutation. Make-owned enumeration was removed, overrides are rejected through a constant origin guard, and Node owns the target registry. | **Both P1s resolved:** adversarial regressions and independent review passed; 0 production regressions. | +| Resumed repair 2 | The topology test was updated to assert the new Make/Node ownership contract, and the overlay-negative fixture received valid source-bound Git identity. | **Both stale tests resolved:** combined focused coverage passed; no production change required. | +| Final topology repair | Repository-facing topology enumeration changed from raw filesystem traversal to tracked plus non-ignored untracked Git candidates; raw traversal remains for fixtures. Typed Git/read failures, force-added ignored coverage, and ignored-residue regressions were added. | **Resolved:** authoritative suite 114/114, focused topology 20/20, `make validate` green, zero topology violations. | +| Final release-candidate verification | The final patch was committed in a history-preserving clean clone and subjected to strict parity, topology, cleanliness, and isolated package generation. | **Passed:** 3/3 targets, zero unresolved differences, clean tree, all three packages generated. | + +## Open Implementation Issues + +None. + +| Severity | Count | Status | +| --- | ---: | --- | +| Critical | 0 | None open | +| Warning | 0 | None open | +| Informational | 0 | None open | + +## Exact-Tag Publication Conditions — Not Implementation Findings + +Before publishing a production release, the release job must: + +1. Repeat the **114/114** authoritative suite, `make validate`, strict three-target parity, topology, package generation, extracted lifecycle, checksums, SBOM, and provenance verification at the exact clean tag commit. +2. Declare `permissions: contents: write` explicitly for the release publisher. +3. Recreate an empty/isolated output directory, reject unexpected files, and publish only an explicit allowlist of the three archives and named verified sidecars generated in that job. + +The release record must preserve native E5/E6 availability, unsigned-provenance, trusted-channel, and cooperative-writer claim boundaries. Failure of an exact-tag condition blocks publication but does not change this Phase 11 implementation verdict unless it exposes a new implementation defect. + +## Recommendations + +- Advance Phase 11 and continue the orchestrator's configured Phase 12/13 routing. +- Add the three publication controls to the tag workflow before the next production release. +- Renew E5/E6 against reviewed native scenarios when runtimes and safe adapters are available; never convert `unavailable` to `passed` by implication. +- Preserve the clean-clone parity/package evidence with the release candidate and repeat it at the exact tag. + +## Verification Checklist + +- [x] Prerequisite specification, plan, and work log present +- [x] 39/39 plan steps complete +- [x] 17/17 requirements covered +- [x] Authoritative suite passes 114/114 +- [x] `make validate` passes +- [x] Focused evidence/topology passes 20/20 +- [x] Direct topology returns zero violations +- [x] Package lifecycle passes 4/4 +- [x] Clean committed-clone strict parity passes 3/3 with zero unresolved +- [x] All three target packages generate from clean committed history +- [x] Syntax and patch hygiene pass +- [x] Both former P1 findings are resolved +- [x] Both stale test contracts are resolved +- [x] Final Git-aware topology repair independently approved +- [x] No critical or warning implementation issue remains +- [ ] Exact-tag publication controls completed — release-phase condition, not Phase 11 blocker + +## Structured Result + +```yaml +status: passed +report_path: verification/implementation-verification.md +html_path: verification/implementation-verification.html +generated: 2026-07-15T22:26:39Z +implementation: + verdict: passed + may_advance_phase_11: true + plan_steps: 39/39 + requirements: 17/17 + standards: compliant + documentation: complete +tests: + authoritative: 114/114 + focused_evidence_topology: 20/20 + make_validate: passed + direct_topology_violations: 0 + package_lifecycle: 4/4 + clean_committed_clone_strict_parity: 3/3_zero_unresolved + clean_committed_clone_packages: codex_cursor_kiro_cli + syntax: 8/8 + diff_hygiene: passed +reviews: + completeness: passed + code_security: approved + pragmatic: approved_after_scoped_topology_repair + production_implementation: GO + reality: READY_GO +resolved: + prior_p1_findings: 2/2 + stale_test_contracts: 2/2 + environment_coupled_topology_contract: resolved +issue_counts: + critical: 0 + warning: 0 + info: 0 +publication: + verdict: conditional_go_at_exact_clean_tag_commit + implementation_finding: false + conditions: + - repeat_complete_clean_release_sequence_at_exact_tag_commit + - declare_contents_write_permission + - recreate_and_publish_only_allowlisted_same_job_artifacts +claim_boundaries: + - native_e6_unavailable_is_not_passed + - unsigned_sidecars_require_trusted_channel + - filesystem_safety_uses_cooperative_writer_model + - free_form_make_argv_is_trusted_executable_input +``` diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/pragmatic-review.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/pragmatic-review.md new file mode 100644 index 00000000..0c9ad75b --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/pragmatic-review.md @@ -0,0 +1,259 @@ +# Pragmatic Review — Resumed Phase 11 Final Re-Verification + +## TL;DR + +**Verdict: PASSED WITH ISSUES.** The production implementation is approved: its high complexity is proportionate to the approved transactional distribution, immutable provenance, three-host overlay, exact rollback, evidence, and packaging requirements. Both former P1 defects are resolved, and no production regression or speculative framework was found. + +The authoritative suite is **111/112** only because ignored, untracked IDE history in `.idea/workspace.xml` contains 554 references to deleted legacy paths. This is **environment/user-state residue, not a production defect and not a stale assertion**. It does expose an environment-coupled repository-topology contract. The contract should be repaired generically to inspect Git tracked files plus non-ignored untracked files; it should not add an editor-specific `.idea` exclusion. + +## Key Decisions + +- Approve both prior P1 repairs as minimal and maintainable: one immutable source binding across lifecycle/materialization, and one Node-owned supported-target registry. +- Classify the sole topology failure primarily as ignored environment residue. It cannot enter the repository or release package, and packaged lifecycle verification passes 4/4. +- Change the repository-facing topology candidate set to Git tracked files plus non-ignored untracked files. Preserve raw filesystem traversal for isolated fixture tests. +- Do not special-case `.idea`, weaken forbidden patterns, delete operator IDE state, or treat a clean-checkout rerun as the permanent fix. +- Keep strict parity and same-job release verification as publication conditions; the current dirty checkout correctly fails closed with `E_SOURCE_DIRTY`. + +## Open Questions / Risks + +- `make validate` remains non-zero in this checkout until the repository-facing topology contract is repaired or verification is run from an isolated checkout without ignored residue. +- Publication remains blocked until strict parity and the complete release sequence pass from a clean isolated checkout. +- Native E5/E6 evidence remains environment-dependent; unavailable evidence must remain explicit and never be promoted to passed. +- `executeLifecycle()` retains the compatibility inputs `source`, `resolvedSource`, and `resolvedSourceRoot`. They now fail safely on disagreement, so contracting this seam should wait for an intentional breaking revision. + +## Review Scope + +Generated: `2026-07-15T22:04:50Z` + +The independent pragmatic specialist reviewed the project scale and architecture, the 17-requirement specification, all 39 implementation-plan steps, the current production and test changes, and the final Phase 11 verification artifacts. Particular attention was given to: + +- `plugins/maister/lib/distribution/transaction-manager.mjs` +- `plugins/maister/lib/distribution/materializer.mjs` +- `plugins/maister/bin/maister-install.mjs` +- `plugins/maister/bin/release-interface.mjs` +- `plugins/maister/bin/shadow-parity.mjs` +- `plugins/maister/lib/distribution/targets.mjs` +- `Makefile` +- the repaired platform-independent regression and topology tests +- `.idea/workspace.xml` only as the ignored path reported by the test runner + +No production code, test code, dependency, ignored IDE state, or workflow state was modified by this review. This canonical report is the only mutation. + +## Overall Complexity and Project Fit + +**Complexity: high, but proportionate to the approved risk and current requirements.** The implementation installs into user-owned host configuration, binds immutable source identity, applies three versioned host overlays, manages shared and dedicated settings, journals multi-file transactions, promises byte-exact rollback, records capability evidence, and builds deterministic release packages. The code serving those boundaries is called and tested; it is not speculative infrastructure. + +No unnecessary service tier, general workflow DSL, external state store, factory hierarchy, dependency-injection framework, or new third-party dependency was introduced. The latest P1 repairs reduce competing ownership: + +- Source identity changed from independently resolvable values to one binding that is revalidated at trust boundaries. +- Supported-target enumeration changed from a duplicated Make/Node policy to a fixed Make delegation backed by the Node registry. + +The platform-independent suite has grown beyond the original estimate, but its cases cover distinct filesystem, provenance, recovery, packaging, and hostile-input boundaries. A fixed test-count ceiling would be less pragmatic than risk-based coverage for this installer. The roughly 107-second acceptance suite and roughly 85-second core suite are acceptable release gates; focused Make targets remain the appropriate developer feedback loop. + +Immediate production-code reduction potential is negligible, and no dependency is safely removable. The remaining simplification opportunity is localized to repository-topology enumeration and policy ownership. + +## Prior P1 Resolution Assessment + +### P1-01 — Lifecycle source root A versus materialized source root B + +**Status: resolved. Current severity: none.** + +The lifecycle now resolves or accepts one source binding before destination state is created, validates caller-provided source/root compatibility, passes the same binding through overlay selection and materialization, revalidates it around assembly, and compares the returned materialized identity before transaction progress. The direct A/B regression proves rejection before target or state mutation. + +This repeated checking is deliberate trust-boundary verification of one value, not redundant ownership or over-engineering. + +### P1-02 — GNU Make expands caller-controlled `SUPPORTED_TARGETS` before Node validation + +**Status: resolved for the fixed supported-target interface. Current severity: none.** + +The Makefile no longer declares or interpolates a caller-controlled target list. It rejects a defined `SUPPORTED_TARGETS` origin without evaluating its value, invokes a fixed `validate-overlays` command, and lets `targets.mjs` own the exact `codex`, `cursor`, `kiro-cli` registry. Hostile Make-function and shell-metacharacter regressions pass without creating sentinels. + +GNU Make can still evaluate arbitrary command-line assignment syntax before reading a Makefile; callers able to supply arbitrary extra Make arguments remain trusted. That language-level boundary is not a defect in the fixed project interface. + +## Sole `.idea/workspace.xml` Failure + +### Classification + +| Question | Answer | +| --- | --- | +| Primary cause | Environment/user-state residue | +| Production defect | No | +| Stale test assertion | No | +| Environment-coupled verification contract | Yes | +| Contract change recommended | Yes | +| Explicit `.idea` exclusion recommended | No | + +Evidence supporting this classification: + +- `.idea/workspace.xml` is ignored by `.gitignore` and is not tracked by Git. +- Its 554 matches are IDE changelist/history references to paths deliberately deleted by this migration, not live repository topology. +- Ignored IDE metadata is not a package input; the extracted package lifecycle passes 4/4. +- The two prior P1 regressions and both repaired stale test contracts pass independently. +- `scanTopology()` currently sees all recursively walked filesystem entries except manually excluded names, so the real-repository result varies with editor/cache state that cannot enter a commit or release artifact. + +The topology assertion is valuable and correctly reports the bytes it was asked to scan. The problem is the candidate universe used by the repository-facing gate, not the forbidden patterns and not the generic scanner used by fixtures. + +### Recommended Contract Repair + +For the real repository, enumerate: + +```text +Git tracked files ++ untracked files not ignored by Git +``` + +An equivalent candidate boundary is: + +```text +git ls-files --cached --others --exclude-standard -z +``` + +This contract excludes ignored IDE/cache/operator state generically while retaining the important cases: + +- every tracked file is scanned, including a force-added editor file; +- new non-ignored untracked implementation files are scanned before commit; +- future forbidden legacy paths and references still fail; +- release-relevant repository topology remains fail-closed. + +The raw recursive `scanTopology()` API should remain available for isolated fixtures. The repository-facing command should provide the Git-derived candidate set. Regression coverage should prove that ignored residue is skipped, while tracked and non-ignored untracked stale references still fail. + +## Findings + +### M-01 — Repository topology validation is coupled to ignored operator state + +- **Severity:** Medium +- **Type:** Suite-blocking developer-experience / verification-contract issue +- **Production defect:** No +- **Observed path:** `.idea/workspace.xml` + +Raw recursive traversal makes `make validate` depend on local editor/cache contents that cannot become a release artifact. The result is a false negative for repository state and creates pressure for accumulating tool-specific exclusions. Git-aware candidate enumeration is both narrower and more accurate without weakening tracked-content validation. + +### L-01 — Repository topology policy is duplicated + +- **Severity:** Low +- **Locations:** topology policy at the `shadow-parity.mjs` CLI seam and `release-interface.mjs` + +Forbidden-path, forbidden-pattern, and exclusion policy is represented in more than one repository-facing entry point. While repairing candidate enumeration, export one repository-topology policy and consume it from both commands. This is a small consolidation, estimated at roughly 20–40 lines, and requires no new dependency. + +Before: + +```text +shadow-parity CLI policy +release-interface topology policy +``` + +After: + +```text +one repositoryTopologyPolicy() +→ shadow-parity CLI +→ release-interface topology +``` + +### L-02 — Lifecycle source compatibility surface is wider than the canonical model + +- **Severity:** Low +- **Location:** `executeLifecycle()` options + +The public seam accepts `source`, `resolvedSource`, and `resolvedSourceRoot`. The implementation now validates disagreement and preserves compatibility safely. Immediate contraction would create migration risk without resolving a current defect. In a planned breaking revision, prefer one `sourceBinding` input and keep source-string parsing at the CLI boundary. + +### I-01 — Strict parity correctly rejects the current dirty checkout + +- **Severity:** Informational + +The current shared workspace is not suitable for release-grade parity, and strict mode returns `E_SOURCE_DIRTY`. The explicit dirty-local diagnostic passes all three targets with zero unresolved differences, but it is not a substitute for the clean isolated release gate. + +### I-02 — Native semantic evidence remains intentionally provisional + +- **Severity:** Informational + +Unavailable native E5/E6 evidence is represented explicitly rather than promoted to passed. This is an honest environment limitation and does not justify adding emulation infrastructure in this task. + +## Requirements and Plan Alignment + +The implementation aligns with **17/17 specification requirements** and **39/39 implementation-plan steps**. In particular: + +- immutable source identity binds overlay selection, materialized bytes, portable-core evidence, provenance, and final receipt publication; +- Node owns supported-target policy while Make exposes fixed commands; +- receipts, journals, recovery, settings ownership, and rollback implement current persisted-contract requirements; +- legacy host trees were removed only after parity, packaging, and adversarial lifecycle coverage existed; +- native evidence limitations remain visible rather than being overclaimed. + +No requirement appears to have been implemented through a materially more general abstraction than needed. + +## Developer Experience + +The repaired architecture has a simple operational explanation: + +1. Resolve one source. +2. Revalidate that source at trust boundaries. +3. Select the overlay from that source. +4. Materialize and compare the resulting identity. +5. Let Node own the target registry. + +Typed failures, focused Make targets, and deterministic package checks are positive developer-experience features. The remaining avoidable friction is that `make validate` currently changes outcome based on ignored local editor history. A Git-aware repository boundary fixes that without weakening security or adding editor-specific policy. + +## Top Three Actions + +1. **Make repository topology enumeration Git-aware.** Scan tracked plus non-ignored untracked candidates, retain raw traversal for fixtures, and add ignored/tracked/untracked regression cases. Do not special-case `.idea`. +2. **Rerun the full acceptance sequence after the scoped repair.** Require 112/112, `make validate`, package lifecycle 4/4, and strict parity from a clean isolated checkout. +3. **Centralize repository-topology policy while touching that seam.** Use one forbidden-path/pattern policy for both CLI entry points. Defer lifecycle `sourceBinding` API contraction until an intentional breaking revision. + +## Merge and Release Recommendation + +**Production-code recommendation: approve.** Both P1 repairs are correct, proportionate, and maintainable. + +**Merge recommendation: changes required for a green canonical suite.** Repair the repository-facing topology candidate contract and rerun verification; do not merge while the authoritative suite is 111/112. + +**Release recommendation: no-go from the current checkout.** Release requires a green full suite, `make validate`, package lifecycle, and strict parity in the clean isolated release environment. Native semantic claims remain provisional while E5/E6 evidence is unavailable. + +## Structured Result + +```yaml +status: passed_with_issues +verdict: production_approved_scoped_verification_contract_repair_recommended +merge_recommendation: changes_required_for_green_suite +release_recommendation: no_go_from_current_checkout +report_path: verification/pragmatic-review.md +complexity: + level: high + assessment: proportionate_to_approved_transactional_distribution_risk +requirements: + implemented: 17 + total: 17 +plan: + completed_steps: 39 + total_steps: 39 +issue_counts: + critical: 0 + high: 0 + medium: 1 + low: 2 + info: 2 +production_regressions: 0 +prior_p1: + lifecycle_source_binding_split: resolved + supported_targets_make_expansion: resolved_for_fixed_value_interface +tests: + authoritative_platform_independent: 111/112 + package_lifecycle: 4/4 + dirty_local_parity: 3/3_zero_unresolved + strict_parity: failed_closed_dirty_checkout +idea_topology: + primary_classification: environment_user_state_residue + production_defect: false + stale_test_assertion: false + environment_coupled_contract: true + topology_contract_change_recommended: true + recommended_scope: tracked_plus_nonignored_untracked + explicit_idea_exclusion_recommended: false +simplification: + immediate_production_loc_removal: negligible + topology_policy_loc_reduction_estimate: 20_to_40 + removable_dependencies: 0 +review_mutations: + production_code: false + tests: false + ide_state: false + report_only: true +``` diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/production-readiness-report.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/production-readiness-report.md new file mode 100644 index 00000000..ed046dac --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/production-readiness-report.md @@ -0,0 +1,223 @@ +# Production Readiness Report — Final Phase 11 Verification + +## TL;DR + +**Implementation verdict: GO. Production publication verdict: CONDITIONAL NO-GO.** + +The platform-independent distribution is ready to merge and advance as a release candidate. The authoritative suite passes **114/114**, `make validate` passes, focused topology coverage passes **20/20**, deterministic package lifecycle coverage passes **4/4**, and both former P1 trust-boundary defects are resolved. + +The final Git-aware topology repair is production-suitable: repository validation now scans tracked files and non-ignored untracked files using NUL-delimited Git enumeration, still detects force-added ignored files, and fails closed when Git enumeration or candidate reads fail. Raw filesystem traversal remains available for fixture-level safety tests. This removes dependency on ignored `.idea/workspace.xml` state without introducing an editor-specific exclusion or weakening repository policy. + +Do not publish directly from a dirty shared checkout. A history-preserving clean clone of the final patch passed strict parity for all three targets with zero unresolved differences, passed topology validation, remained Git-clean, and produced all three clean packages in isolated output directories. Production publication remains conditional on repeating those gates at the exact tag commit and closing the tag-workflow permission, full-suite, and artifact-allowlist controls. + +## Deployment Decision + +| Boundary | Decision | Rationale | +| --- | --- | --- | +| Production implementation | **GO** | No critical/high production defect remains; both P1 findings are closed. | +| Merge/release-candidate preparation | **GO** | 114/114 tests, 20/20 topology coverage, `make validate`, package lifecycle, syntax, and patch hygiene pass. | +| Publication from a dirty shared checkout | **NO-GO** | Strict release parity correctly refuses dirty source state. | +| Publication from the exact release commit | **CONDITIONAL GO** | Clean-clone strict parity/packageability is proven; repeat it at the tag commit with full-suite evidence, explicit release permission, and an allowlisted same-job artifact set. | + +Overall readiness score: **83/100 — ready as a release candidate, not yet authorized for production publication.** + +## Evidence Reviewed + +| Evidence | Result | +| --- | --- | +| Current authoritative suite | **114/114 passed** | +| Current integrated validation | **Passed** | +| Cursor projection | **56 files, 0 drift** | +| Overlay validation | **3/3 targets passed** | +| Focused topology suite | **20/20 passed** | +| Deterministic packaged lifecycle | **4/4 passed** | +| Syntax checks | **Passed** | +| `git diff --check` | **Passed** | +| Prior clean history-preserving clone | **112/112 and `make validate` passed before the two topology regressions were added** | +| Final patch in a clean committed clone | **Strict parity 3/3 targets with 0 unresolved; topology passed; tree remained clean; Codex/Cursor/Kiro CLI packages produced in isolated output directories** | +| Dirty-local diagnostic parity | **3/3 targets, 0 unresolved differences** | +| Strict parity in dirty shared checkout | Correctly fails closed with `E_SOURCE_DIRTY` | +| Former source-binding P1 | **Resolved** | +| Former Make target-expansion P1 | **Resolved within the fixed-value interface** | +| Production regressions | **0 found** | + +## Final Topology Repair Assessment + +The repair is approved. + +`scanRepositoryTopology()` enumerates candidates with: + +```text +git ls-files --cached --others --exclude-standard -z +``` + +This has the intended behavior: + +- tracked repository files remain covered; +- non-ignored untracked implementation files remain covered; +- ignored operator/cache state is excluded generically; +- force-added ignored files remain covered because they are tracked; +- NUL-delimited enumeration handles spaces and unusual valid pathnames; +- path containment is rechecked before filesystem access; +- Git failures produce typed `E_TOPOLOGY_GIT` errors; +- unexpected candidate read failures produce typed `E_TOPOLOGY_READ` errors; +- repository CLI entry points share one topology policy; +- raw recursive traversal is retained for isolated fixture tests. + +The repair does not add a `.idea` exception and does not weaken the forbidden legacy-path patterns. + +## Category Scores + +| Category | Score | Assessment | +| --- | ---: | --- | +| Configuration and validation | **9/10** | Target IDs, overlays, paths, modes, source refs, evidence, settings ownership, and release inputs are bounded and fail closed. | +| Monitoring and supportability | **8/10** | Structured JSON, stable exit codes, receipts, journals, evidence records, integrity hashes, and recovery diagnostics are appropriate for a local CLI. Server metrics and health endpoints are not applicable. | +| Error handling and resilience | **9/10** | Typed failures, bounded commands, durable journals, integrity-bound backups, drift refusal, idempotent recovery, and explicit unresolved code-7 state are strong. | +| Performance and scalability | **8/10** | Operations are bounded, deterministic, and suitable for a local filesystem installer. No formal large-tree performance budget or stress threshold exists. | +| Security | **9/10** | Both P1 boundaries are fixed; source identity is singular and revalidated, unsafe target enumeration is removed, paths/settings/backups are hardened, and workflow actions are commit-pinned. | +| Deployment and supply chain | **8/10** | Clean committed-clone strict parity and isolated package generation pass, but explicit token permissions, full-suite CI coverage, artifact allowlisting, and repetition at the tag commit remain release conditions. | + +## Production Publication Conditions + +These are release-process blockers, not production-code defects. + +### Satisfied evidence — clean committed-clone strict parity and packaging + +The dirty shared checkout correctly fails with `E_SOURCE_DIRTY`; its dirty-local parity remains diagnostic only. Independently, the final patch was synchronized into a history-preserving clean clone and committed. In that clean clone: + +- strict `make test-parity-release` passed for Codex, Cursor, and Kiro CLI with zero unresolved differences; +- topology validation passed; +- the Git tree remained clean after validation; +- packages for all three targets were produced successfully in isolated output directories. + +This closes the prior source-cleanliness/parity uncertainty for the release candidate. Publication must still repeat the same sequence at the exact tag commit and retain its reports and artifact hashes. + +### PR-B01 — Release publication permission is implicit + +The publish job does not declare: + +```yaml +permissions: + contents: write +``` + +Release creation therefore depends on repository-level `GITHUB_TOKEN` defaults. Declare the permission explicitly before relying on the workflow for production publication. + +### PR-B02 — The complete authoritative suite is not part of the tag workflow + +`make validate` covers core, evidence, topology, overlays, and Cursor projection, while release CI separately runs package lifecycle and strict parity. It does not invoke the complete `make test-platform-independent` suite, which owns additional Make-interface, registry, release-interface, and adversarial contracts. + +Run **114/114 at the exact release commit**, preferably by adding `make test-platform-independent` to PR and release CI. + +### PR-B03 — Release artifacts are published through a broad `dist/*` glob + +The hosted runner is normally clean, but project standards require an explicitly empty/isolated output directory and a verified allowlist. The workflow currently uses `mkdir -p dist` and publishes `dist/*`. + +Before publication: + +- recreate `dist/` explicitly; +- generate all files in the same validation job; +- upload and publish only the three target archives and named verified sidecars; +- reject unexpected files before upload. + +## Residual Concerns + +These do not block implementation approval when their claim boundaries remain explicit. + +1. E6 native runtime evidence remains unavailable where no reviewed host scenario/runtime exists. Packaging and transactional support must remain provisional rather than being described as native semantic certification. +2. `SHA256SUMS`, the CycloneDX SBOM, and `PROVENANCE.json` are unsigned. They provide integrity and reproducibility only when obtained through a trusted release channel. +3. Installer locking coordinates cooperating Maister processes, not arbitrary host/editor/synchronization writers. Operators must quiesce external writers. +4. No abrupt process-kill, power-loss, hostile continuous-writer, or live-network GitHub drill was recorded. +5. Some materializer text/reference exceptions and repository topology exclusions remain broader than ideal. +6. Local package/E3 commit identity remains caller-supplied outside protected CI. Only protected clean-release jobs should authorize publication. +7. Arbitrary GNU Make command-line syntax is executable before a Makefile loads. Automation must keep Make argv trusted and pass untrusted content only through fixed value interfaces. +8. Cursor's behavior-bearing projection remains explicit, drift-checked migration debt. + +## Rollback and Recovery Criteria + +### Release rollback + +Rollback or withdraw a release if: + +- archive hashes or metadata verification differ after publication; +- an extracted archive fails install/verify/uninstall; +- the receipt source, overlay, materialized, E3, or provenance binding differs; +- a target contains cross-target assets or missing required inventory; +- evidence is promoted beyond its recorded `passed`/`unavailable` status; +- a newly observed parity difference is unresolved. + +Operational response: + +1. Stop further downloads or installation guidance. +2. Remove or mark the affected GitHub release as invalid. +3. Restore the prior known-good release artifacts and documentation. +4. Preserve the failing archives, checksums, provenance, parity report, and logs for diagnosis. +5. Correct the source and create a new immutable release; do not silently replace bytes under an existing version. + +### Installer rollback/recovery + +Before lifecycle operations, stop host/editor/synchronization writers. If an operation fails: + +- preserve state, receipts, journals, backups, staging, and lock evidence; +- distinguish lock `6`, drift `5`, unresolved transaction/recovery `7`, source/validation `3/4`, and integrity `8`; +- use receipt-backed rollback or journal-backed recovery; +- after code `7`, do not delete state or repeatedly retry rollback; +- verify the resulting active receipt and managed inventory before continuing. + +## Post-Deployment Verification + +After publishing each release: + +- Verify the tag commit and release-channel authenticity. +- Verify `SHA256SUMS` for all three archives. +- Verify SBOM and provenance bindings against the archive hashes and embedded E3 bytes. +- Confirm only the allowlisted release files were published. +- Extract each archive into a clean directory. +- Run install, status/verify, and uninstall for Codex, Cursor, and Kiro CLI with isolated home/state roots. +- Inspect receipts for the exact source commit, source version, overlay ID/version, materialized hash, evidence hashes, and compatibility status. +- Confirm E5/E6 `unavailable` values remain visible and are not represented as passes. +- Confirm no Claude, legacy generated-tree, marketplace, or cross-target asset appears. +- Exercise one controlled rollback/recovery scenario and verify exact restoration. +- Retain the strict parity report, package lifecycle result, checksums, SBOM, provenance, and workflow logs with the release record. + +## Finding Counts + +```yaml +status: conditionally_ready +overall_score: 83 +implementation_decision: GO +merge_decision: GO +shared_checkout_publication_decision: NO_GO_when_dirty +clean_release_commit_decision: CONDITIONAL_GO +finding_counts: + critical_production_defects: 0 + high_production_defects: 0 + production_release_blockers: 3 + residual_concerns: 8 + production_regressions: 0 +resolved_p1_findings: + lifecycle_materializer_source_binding: resolved + supported_targets_prevalidation_evaluation: resolved_for_fixed_value_interface +evidence: + authoritative_suite: 114/114 + focused_topology: 20/20 + make_validate: passed + cursor_projection: 56_files_0_drift + overlays: 3/3 + package_lifecycle: 4/4 + dirty_local_parity: 3/3_zero_unresolved_diagnostic_only + strict_parity: 3/3_zero_unresolved_in_clean_committed_clone_repeat_at_exact_tag_commit + syntax: passed + diff_hygiene: passed +release_conditions: + - repeat_clean_strict_parity_and_package_generation_at_exact_tag_commit + - run_114_of_114_at_exact_release_commit + - declare_contents_write_permission + - recreate_and_allowlist_same_job_release_artifacts + - preserve_provisional_e6_unsigned_provenance_and_cooperative_writer_claim_boundaries +production_code_modified_by_checker: false +tests_modified_by_checker: false +ide_state_modified_by_checker: false +workflow_state_modified_by_checker: false +canonical_reports_modified_by_checker: false +``` diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/reality-check.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/reality-check.md new file mode 100644 index 00000000..14482eed --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/reality-check.md @@ -0,0 +1,212 @@ +# Reality Check — Final Phase 11 Verification + +## TL;DR + +**Implementation verdict: ✅ READY. Merge/release-candidate verdict: ✅ GO. Production publication verdict: ⚠️ CONDITIONAL GO.** +The final platform-independent distribution passes **114/114**, `make validate`, focused topology **20/20**, and packaged lifecycle **4/4**; both former P1 trust-boundary defects remain resolved. +A clean history-preserving committed clone also passed strict parity for all three targets with zero unresolved differences, passed topology, remained clean, and generated all three target packages. +Publication is authorized only after the exact tag commit repeats these gates and closes three release-workflow controls: explicit release permission, full-suite execution, and an empty allowlisted artifact set. + +## Key Decisions + +- Approve the implementation and merge — no critical or high production defect remains, all functional and release-candidate evidence is green, and both former P1s are closed. +- Approve the Git-aware topology repair — it scans tracked plus non-ignored untracked files, detects force-added ignored files, and fails closed without adding an editor-specific exclusion. +- Treat clean-clone strict parity as satisfied release-candidate evidence — it proves the final patch can pass the three-target release boundary from clean committed history. +- Make publication conditional — the tag workflow must explicitly request release permission, run the complete 114-test suite, and publish only a verified same-job allowlist from a recreated output directory. + +## Open Questions / Risks + +- Native E6 remains unavailable where no reviewed host scenario/runtime exists; host-native semantic support must remain provisional. +- Checksums, SBOM, and provenance are unsigned and authenticate nothing unless obtained through a trusted release channel. +- Filesystem guarantees retain the documented cooperative-writer boundary; host/editor/synchronization writers must be stopped during lifecycle and recovery operations. +- Arbitrary GNU Make command-line syntax is executable input before a Makefile loads; automation must expose fixed value fields, never untrusted free-form Make argv. + +## Scope and Evidence + +- Task: `.maister/tasks/development/2026-07-14-platform-independent-plugin` +- Phase: final resumed Phase 11 verification +- Assessment mode: read-only except replacement of this report +- Reviewed: final production and test code, specification, plan, work log, workflow state, standards, canonical verification reports, release workflow, and clean-clone release evidence +- Independently rechecked by this assessor: evidence/topology **20/20**, repository topology command, JavaScript syntax for both topology entry points, and `git diff --check` — all passed +- Production code, tests, IDE state, and workflow state modified by this assessor: no + +The interim 111/112 report is superseded by the final Git-aware repair and final evidence. The authoritative implementation result is now **114/114**, and `make validate` is green in the original checkout. + +## Decisive Reality Verdict + +The platform-independent distribution now works for its intended supported scope. It has one portable source boundary, explicit Codex/Cursor/Kiro CLI overlays, immutable source identity, deterministic materialization and packages, transaction receipts, ownership and drift enforcement, rollback/recovery, explicit capability evidence, and a release-grade parity boundary. + +| Decision surface | Verdict | Reality basis | +| --- | --- | --- | +| Production implementation | **✅ READY** | 114/114, green integrated validation, 20/20 topology, 4/4 packaged lifecycle, zero production regressions. | +| Merge / release candidate | **✅ GO** | Both P1s are resolved; final topology repair is fail-closed and production-suitable. | +| Publication from dirty shared checkout | **❌ NO-GO** | Strict release operations must originate from clean committed source, not the active migration worktree or existing `dist/`. | +| Publication from exact tag commit | **⚠️ CONDITIONAL GO** | Repeat clean strict parity/package verification and close the three tag-workflow controls below. | +| Native host semantics | **⚠️ PROVISIONAL** | E6 unavailable is explicit and is not a semantic pass. | + +This is a release-process qualification, not an implementation qualification. The code is ready; production publication is not authorized until the release workflow enforces the exact evidence already demonstrated manually in the clean committed clone. + +## Former P1 Findings + +### P1-01 — Lifecycle root A could diverge from materialized root B: resolved + +Install/update establishes one immutable source binding before target state creation. Caller-supplied roots and local/file source paths must match that binding; source-bound overlay selection has no running-checkout fallback; the same binding is revalidated before and after assembly; and the lifecycle compares the materialized identity before transaction progress. + +The adversarial A/B regression proves disagreement fails with `E_SOURCE_ROOT` before either lifecycle state or target content is created. Overlay selection, portable-core evidence, installed bytes, and receipt provenance therefore share one reviewed source identity. + +### P1-02 — `SUPPORTED_TARGETS` could execute before Node validation: resolved for the supported interface + +Make no longer owns or interpolates a target list. A defined `SUPPORTED_TARGETS` origin is rejected through a constant guard, `validate` invokes a fixed Node command, and Node enumerates the frozen central target registry. Make-function and shell-metacharacter regressions prove fixed-field overrides do not execute their payloads, while normal enumeration validates exactly Codex, Cursor, and Kiro CLI. + +Free-form Make argv remains trusted because GNU Make itself evaluates some command-line assignment forms before loading any Makefile. This is a documented invocation boundary, not a residual repository defect; CI and wrappers must pass untrusted data only as values through fixed fields. + +## Final Git-Aware Topology Repair + +The previous `.idea/workspace.xml` failure was ignored operator residue, not live repository topology. The final repair correctly changes the repository-facing candidate universe rather than weakening forbidden patterns or adding an editor-specific exclusion. + +`scanRepositoryTopology()` now uses NUL-delimited Git enumeration equivalent to: + +```text +git ls-files --cached --others --exclude-standard -z +``` + +This produces the correct release-relevant behavior: + +- tracked files are always scanned, including force-added ignored paths; +- non-ignored untracked implementation files are scanned before commit; +- ignored editor/cache/operator state is excluded generically; +- unusual valid filenames are preserved through NUL delimiting; +- candidate containment is rechecked before access; +- Git enumeration failures raise `E_TOPOLOGY_GIT`; +- candidate inspection/read failures raise `E_TOPOLOGY_READ`; +- the repository CLI and release interface share one topology policy; +- raw recursive traversal remains available for isolated fixture tests. + +Independent final execution passed all **20/20** evidence/topology cases and returned `{"ok":true,"violations":[]}` from the production topology command. + +## Functional Reality by Workflow + +| Workflow | Assessment | Evidence and qualification | +| --- | --- | --- | +| Install / update | **Ready** | One immutable source binding drives overlay, evidence context, materialization, provenance, and receipt creation; unsafe disagreement fails before mutation. | +| Status / verify | **Ready** | Receipt-backed inventory, settings ownership, drift, modes, hashes, symlinks, and integrity are covered. | +| Uninstall | **Ready** | Extracted target packages uninstall cleanly; unmanaged content and ownership conflicts remain protected. | +| Rollback / recovery | **Ready within documented threat model** | Backup integrity, exact topology restoration, journal transitions, tamper rejection, idempotency, and unresolved code-7 handling are covered. | +| Package | **Ready** | Deterministic, sorted, self-contained, target-isolated archives pass extracted lifecycle **4/4**. | +| Parity / topology | **Ready** | Clean committed-clone strict parity passes 3/3 with zero unresolved; current topology and focused suite are green. | +| Publication automation | **Conditional** | Functional artifacts are proven, but the tag workflow still needs the three controls below. | +| Native runtime semantics | **Provisional** | E6 remains unavailable where scenarios/runtimes are absent and must not be advertised as passed. | + +## Clean Release-Candidate Evidence + +The final patch was applied to a history-preserving clean clone and committed. In that environment: + +- strict `make test-parity-release` passed for Codex, Cursor, and Kiro CLI; +- all three targets reported zero unresolved differences; +- topology validation passed; +- validation left the Git tree clean; +- Codex, Cursor, and Kiro CLI packages were generated in isolated output directories. + +Combined with current **114/114**, green `make validate`, focused topology **20/20**, and package lifecycle **4/4**, this closes the prior uncertainty about whether the implementation can actually satisfy its clean-source release boundary. + +## Publication Conditions + +These three conditions block production publication, not merge or release-candidate preparation: + +1. **Declare release permission explicitly.** Add `permissions: contents: write` at the appropriate workflow/job scope before relying on the GitHub release publisher. +2. **Run the complete authoritative suite at the exact release commit.** The tag workflow currently runs `make validate`, strict parity, and package lifecycle, but not the additional Make-interface, registry, release-interface, and adversarial contracts owned by `make test-platform-independent`. Require **114/114** at the tag commit. +3. **Recreate and allowlist the same-job artifact set.** Start with an absent/empty isolated output directory, generate all artifacts in the validation job, reject unexpected files, and upload/publish only the three named target archives plus the named parity, E3, checksum, SBOM, and provenance sidecars. Replace broad `dist/*` publication. + +At the exact tag commit, repeat strict three-target parity and package generation/lifecycle, retain reports and hashes, and publish only after all three controls pass. + +## Residual Claim and Operational Boundaries + +The following eight concerns are non-blocking for implementation approval but must remain visible: + +1. E6 native runtime semantics are unavailable where no reviewed scenario/runtime exists. +2. `SHA256SUMS`, CycloneDX SBOM, and `PROVENANCE.json` are unsigned and require a trusted channel. +3. Installer locking coordinates cooperating Maister processes, not arbitrary external or privileged writers. +4. No abrupt process-kill, power-loss, hostile continuous-writer, or live-network GitHub drill is recorded. +5. Some materializer text/reference exceptions and repository topology exclusions remain broader than ideal. +6. Local package/E3 commit identity is caller-supplied outside protected CI; publication authority belongs to the protected clean-release job. +7. Arbitrary GNU Make argv is executable input and must not be exposed to untrusted callers. +8. Cursor's behavior-bearing projection remains explicit drift-checked migration debt, not a second intended source of truth. + +## Supported and Unsupported Claims + +Supported now: + +- one maintained portable source with three explicit supported-host overlays; +- deterministic target-isolated archives for Codex, Cursor, and Kiro CLI; +- install, update, verify, uninstall, rollback, and recovery at the tested transactional boundary; +- immutable source-to-overlay-to-materialization-to-receipt binding; +- exact ownership, drift refusal, backup integrity, and fail-closed recovery behavior; +- clean strict three-target parity with zero unresolved differences; +- Git-aware final topology that ignores non-release operator residue without hiding tracked or non-ignored implementation files. + +Not supported without qualification: + +- publication directly from the dirty shared checkout or pre-existing local `dist/`; +- production publication before the three tag-workflow controls are closed; +- native semantic certification while E6 is unavailable; +- publisher authentication from unsigned sidecars; +- safety against arbitrary malicious same-user or privileged concurrent mutation. + +## Structured Verdict + +```yaml +status: ready_with_publication_conditions +implementation_verdict: READY +merge_verdict: GO +release_candidate_verdict: GO +publication_verdict: CONDITIONAL_GO +dirty_shared_checkout_publication: NO_GO +exact_clean_tag_commit_publication: GO_AFTER_CONDITIONS +report_path: verification/reality-check.md +assessment_mode: read_only_except_report +issue_counts: + critical_production_defects: 0 + high_production_defects: 0 + implementation_blockers: 0 + publication_process_blockers: 3 + residual_concerns: 8 + production_regressions: 0 +evidence: + authoritative_suite: 114/114 + make_validate: passed + focused_topology: 20/20 + package_lifecycle: 4/4 + clean_clone_strict_parity: + targets: 3/3 + unresolved: 0 + clean_clone_topology: passed + clean_clone_tree_after_validation: clean + clean_clone_packages_generated: + - codex + - cursor + - kiro-cli + syntax: passed + diff_hygiene: passed +prior_p1_findings: + lifecycle_materializer_source_binding: resolved + supported_targets_prevalidation_evaluation: resolved_for_fixed_value_interface +topology_repair: + verdict: approved + candidate_set: tracked_plus_nonignored_untracked + ignored_operator_residue: excluded + force_added_ignored_files: scanned + git_failure: fail_closed_E_TOPOLOGY_GIT + read_failure: fail_closed_E_TOPOLOGY_READ +publication_conditions: + - explicit_contents_write_permission + - full_114_test_suite_at_exact_tag_commit + - recreated_allowlisted_same_job_artifact_set +claim_boundaries: + e6: provisional_when_unavailable + provenance: unsigned_trusted_channel_required + filesystem: cooperative_writer_model +production_code_modified: false +tests_modified: false +ide_state_modified: false +workflow_state_modified: false +``` diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/spec-audit.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/spec-audit.md new file mode 100644 index 00000000..2b0dea58 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/spec-audit.md @@ -0,0 +1,110 @@ +# Specification Audit: Platform-independent Maister distribution + +## TL;DR + +The specification is **Mostly Compliant** as a pre-implementation contract: all 17 stated requirements map to the confirmed research decisions, current-state gaps, and measurable migration exit criteria. +There are no critical or high-severity specification defects; two medium clarifications remain around the exact installer/receipt contract and the versioned overlay schema. +The repository is still in the intentional legacy state, so missing common/overlay/installer code is an expected implementation gap, not an audit failure. +The specification is actionable for planning, provided the remaining contract details are frozen before implementation starts. + +## Key Decisions + +- Treat the audit as a pre-implementation specification audit — the task is expected to have legacy code until Phase 8. +- Classify missing implementation as expected rather than non-compliant — `spec.md` explicitly defines migration, parity, rollback, and deletion exit criteria. +- Classify exact CLI/schema details as medium clarification items — they affect implementability but do not contradict the accepted architecture. + +## Open Questions / Risks + +- The exact command surface, receipt/journal locations, schema versions, and machine-readable exit/error contract are not frozen in `spec.md`. +- Overlay v1 names required categories but does not yet provide a field-by-field schema or a complete Codex/Cursor/Kiro inventory. +- GitHub source resolution needs explicit authentication, offline, shallow-clone, and missing-ref behavior before implementation. +- The specification HTML companion is a condensed visual representation; it should be kept synchronized if the Markdown specification changes. + +## Summary + +- **Compliance status**: Mostly Compliant +- **Requirements checked**: 17 +- **Requirements mapped**: 17 +- **Critical findings**: 0 +- **High findings**: 0 +- **Medium findings**: 2 +- **Low findings**: 2 +- **Audit mode**: Pre-implementation contract audit + +## Audit Basis + +The audit compared `implementation/spec.md` and its HTML companion with `analysis/requirements.md`, `analysis/codebase-analysis.md`, `analysis/gap-analysis.md`, the research handoff, and the project documentation indexed by `.maister/docs/INDEX.md`. The repository was independently inspected at the existing runtime, builder, installer, test, Make, CI, and documentation paths. The audit report was completed locally after the delegated auditor remained unavailable; no specification or implementation files were changed during the inspection. + +## Requirement Coverage + +| Requirement group | Spec coverage | Evidence / assessment | +| --- | --- | --- | +| R1-R3: common source, overlays, portable runtime | Pass | `spec.md` Core Requirements 1-3 and Technical Approach; the five byte-identical runtime modules are identified in `spec.md` Reusable Components. | +| R4: immutable source/ref provenance | Pass with clarification | Core Requirement 4 and the receipt requirement cover requested ref, resolved commit, source/overlay/host versions, and hashes. Exact resolver CLI/error behavior remains open. | +| R5-R8: lifecycle, staging, transaction, receipt | Pass with clarification | Core Requirements 5-8, Rollback Plan, and deletion criteria cover install/update/status/uninstall/rollback/recovery, validation-before-mutation, journals, receipts, and exact restoration. Exact command and schema contracts are not yet frozen. | +| R9-R10: settings ownership and drift | Pass | Hybrid ownership, managed keys, conflict detection, preservation, and refusal of unsafe destructive changes are explicit in Core Requirements 9-10 and Rollback Plan. | +| R11-R13: capability compatibility and evidence freshness | Pass with clarification | Compatibility and Evidence Policy defines E1-E6, fail-closed semantics, unavailable outcomes, provenance, and expiry. Overlay field-level evidence schema is still to be frozen. | +| R14: test topology | Pass | Implementation Guidance defines six focused groups, 2-8 tests per group, core-once coverage, and per-host seam coverage. | +| R15-R16: parity and deletion | Pass | Legacy Deletion Exit Criteria require baseline inventory, zero unresolved differences, failure evidence, rewired paths, and removal of Claude/generated infrastructure. | +| R17: documentation and release migration | Pass | Core Requirement 17, Standards Compliance, and deletion criteria require README, docs, standards, Make, CI, release, and support-matrix alignment. | + +## Current-State Verification + +The following are intentional pre-implementation gaps that the specification correctly covers: + +- No neutral `common/`, versioned host-overlay schema, shared installer, receipt, journal, or evidence schema currently exists; this is the stated work boundary in `spec.md` Core Requirements 1-8 and New Components Required. +- `platforms/cursor/smoke-install.sh`, `platforms/kiro-cli/smoke-install.sh`, and `platforms/codex-cli/smoke-install.sh` remain host-specific and unsafe compared with the target lifecycle; `spec.md` Rollback Plan and Success Criteria explicitly require their replacement. +- `plugins/maister-cursor/`, `plugins/maister-kiro/`, and `plugins/maister-codex/` remain generated projections; `spec.md` Legacy Deletion Exit Criteria treats them as shadow oracles until parity passes. +- `Makefile`, `.github/workflows/validate-generated-variants.yml`, capability records, README, support docs, and project standards still describe the legacy four-host/generated-tree workflow; `spec.md` Core Requirement 17 and deletion criteria explicitly include their migration. +- Native Cursor/Kiro evidence is unavailable in the current environment; `spec.md` defines `unavailable` as distinct from `passed` and requires it to remain visible. + +## Important Gaps + +### Medium — Installer command and receipt contract needs one implementation-time freeze + +- **Specification reference**: Core Requirements 4-8, Rollback Plan, Success Criteria. +- **Evidence**: The specification requires install, update, status/verify, uninstall, rollback, recovery, source/ref provenance, receipts, journals, and machine-safe ownership, but does not name the exact command syntax, receipt/journal paths, schema versions, active-receipt pointer, or exit/error protocol. +- **Category**: Ambiguous implementation contract. +- **Impact**: Different task groups could implement incompatible lifecycle interfaces or make recovery tooling unable to discover state. +- **Recommendation**: Freeze the CLI command matrix, receipt/journal schema versions and locations, state transitions, and machine-readable error/exit contract in the implementation plan before Phase 8. + +### Medium — Overlay v1 schema and per-host inventory need field-level acceptance criteria + +- **Specification reference**: Core Requirements 2, 6, 11-13; Compatibility and Evidence Policy. +- **Evidence**: The specification names discovery roots, native inventories, bindings, settings ownership, capability records, forbidden vocabulary, expiry, and required evidence, but does not enumerate the exact required/optional fields or the complete initial Codex/Cursor/Kiro inventory. +- **Category**: Incomplete acceptance detail. +- **Impact**: An overlay could satisfy the prose while omitting a native asset, binding, or safety-relevant path. +- **Recommendation**: Define schema field allowlists, required inventories, collision rules, and one contract fixture per target before materializer implementation. + +## Minor Discrepancies + +### Low — Source resolver edge behavior is named but not acceptance-tested + +`analysis/requirements.md` names authentication, offline mode, shallow clones, missing refs, and temporary cleanup as technical considerations, while `spec.md` requires immutable local/GitHub provenance without enumerating those edge-case outcomes. Add focused resolver scenarios to the implementation plan. + +### Low — Performance and scale thresholds are intentionally absent + +The specification defines correctness, safety, determinism, and evidence criteria but no installation-size or timing thresholds. This is acceptable for the current migration, but a later plan may add bounded performance checks if repository size or host startup time makes them material. + +## Clarification Needed + +These are implementation-time contract details, not unresolved architectural choices: + +1. What exact installer commands and flags expose target, scope, source/ref, offline mode, status, rollback, and recovery? +2. Where do receipt, journal, backup, and active-receipt files live for each target and scope? +3. What are the versioned overlay schema fields, required inventories, and initial native asset manifests for Codex, Cursor, and Kiro CLI? +4. What machine-readable exit codes and JSON error/evidence format do lifecycle commands expose? + +The accepted Phase 2 decisions already resolve the architecture, settings ownership, evidence policy, freshness policy, documentation boundary, and supported target set; these questions should not reopen those decisions. + +## Recommendations + +- Add the four contract details above to `implementation/implementation-plan.md` before implementation approval. +- Make the plan create one overlay schema fixture and one receipt/journal fixture per target before the materializer and installer workers start. +- Keep the existing byte-exact transaction tests as the baseline for installer failure injection, extending assertions to receipts, journals, settings keys, and topology. +- Preserve the explicit `unavailable` outcome in all capability and release summaries. +- Run the final negative topology check after docs/CI/release migration and before deleting the legacy oracle. + +## Audit Conclusion + +The specification is ready for planning and independent implementation review. It has no critical or high-severity defect, and it correctly describes the current repository as a migration starting point. Phase 7 should resolve the medium contract details before the protected implementation approval gate is presented. diff --git a/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/test-suite-results.md b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/test-suite-results.md new file mode 100644 index 00000000..32798406 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-platform-independent-plugin/verification/test-suite-results.md @@ -0,0 +1,236 @@ +# Test Suite Results — Final Phase 11 Re-Verification + +## TL;DR + +**Passed: 114/114 authoritative platform-independent tests passed, with zero failures or regressions.** + +The final shared-checkout tree also passes `make validate`, the focused evidence/topology suite at 20/20, direct repository topology validation, deterministic package lifecycle coverage at 4/4, JavaScript syntax checks, and `git diff --check`. A separate history-preserving committed clone passed strict parity for Codex, Cursor, and Kiro CLI with zero unresolved differences, passed topology validation, remained Git-clean, and generated all three packages in isolated output directories. + +The implementation is green for Phase 11. Production publication is still conditional on repeating the complete release sequence at the exact tag commit; that is a release-process condition, not a test failure. + +## Key Decisions + +- Treat `make test-platform-independent` as the authoritative suite and count its 114 tests once. Focused and release-boundary checks overlap with it and are reported separately. +- Accept the Git-aware repository topology repair: tracked and non-ignored untracked files are scanned, ignored operator residue is excluded generically, force-added ignored files remain covered, and Git/read failures fail closed. +- Treat the clean committed-clone strict-parity result as release-candidate evidence, while requiring the same checks to be repeated at the exact release tag. +- Keep dirty-checkout rejection, unavailable native E6 evidence, and unsigned provenance as explicit claim boundaries rather than test failures. + +## Scope + +- Repository: `/Users/mrapacz/Workspace/maister` +- Task: `.maister/tasks/development/2026-07-14-platform-independent-plugin` +- Generated: `2026-07-15T22:22:21Z` +- Authoritative execution environment: original shared checkout +- Strict release-parity environment: history-preserving clean committed clone containing the final patch +- Production code modified by this reporter: no +- Test code modified by this reporter: no +- IDE or workflow state modified by this reporter: no + +## Verdict + +| Dimension | Result | +| --- | --- | +| Structured status | `passed` | +| Authoritative suite | **114/114 passed** | +| Failed, skipped, cancelled, or todo tests | **0** | +| Production regressions | **0 found** | +| Former P1 regressions | **0 reproduced; both repaired boundaries pass** | +| Integrated validation | **Passed** | +| Focused evidence/topology coverage | **20/20 passed** | +| Direct topology command | **Passed; zero violations** | +| Deterministic package lifecycle | **4/4 passed** | +| Clean committed-clone strict parity | **3/3 targets passed; zero unresolved differences** | +| Clean committed-clone package generation | **Codex, Cursor, and Kiro CLI passed** | +| Syntax and patch hygiene | **Passed** | + +## Command and Result Matrix + +| Environment | Command or check | Result | +| --- | --- | --- | +| Original checkout | `make test-platform-independent` | **Passed: 114/114** across 10 test files; 0 failed/skipped/cancelled/todo | +| Original checkout | `make validate` | **Passed**: Cursor projection, all overlays, core, evidence, and topology gates green | +| Original checkout | `node --test tests/platform-independent/evidence-parity-topology.test.mjs` | **Passed: 20/20**, 0 failed/skipped/cancelled/todo; 357.615542 ms on final report refresh | +| Original checkout | `make test-topology` | **Passed**: `{"ok":true,"violations":[]}` | +| Original checkout | `node --test tests/platform-independent/release-package.test.mjs` | **Passed: 4/4** deterministic packaged lifecycle tests | +| Original checkout | JavaScript `node --check` set | **Passed: 8/8** checked implementation/test entry points | +| Original checkout | `git diff --check` | **Passed** with no diagnostics | +| Clean committed clone | `make test-parity-release` | **Passed: 3/3 targets**, zero unresolved differences | +| Clean committed clone | `make test-topology` | **Passed** with zero violations | +| Clean committed clone | Git cleanliness after validation | **Passed**; tree remained clean | +| Clean committed clone | Isolated `make package TARGET=` for all registered targets | **Passed**; Codex, Cursor, and Kiro CLI packages generated | + +## Detailed Results + +### 1. Authoritative platform-independent suite + +```text +make test-platform-independent +``` + +Underlying command: + +```text +node --test tests/platform-independent/*.test.mjs +``` + +| Metric | Result | +| --- | ---: | +| Test files | 10 | +| Tests | 114 | +| Passed | 114 | +| Failed | 0 | +| Cancelled | 0 | +| Skipped | 0 | +| Todo | 0 | +| Pass rate | 100% | + +This is the final authoritative count for Phase 11. It includes the two additional repository-topology regressions introduced with the final generic ignored-residue repair, raising the prior 112-test suite to 114. + +### 2. Integrated validation + +```text +make validate +``` + +Result: exit code 0. + +The integrated gate passed Cursor projection drift checking, registry-owned validation for Codex/Cursor/Kiro CLI overlays, common-core tests, evidence tests, and direct topology validation. The earlier `.idea/workspace.xml` failure is closed without an editor-specific exclusion: repository scanning now follows Git repository membership while fixture-level raw traversal remains available for explicit safety tests. + +### 3. Focused evidence and topology coverage + +```text +node --test tests/platform-independent/evidence-parity-topology.test.mjs +``` + +Final refresh result: exit code 0; 20/20 passed; 0 failed, cancelled, skipped, or todo; 357.615542 ms. + +The focused set proves: + +- E1-E6 validation, freshness, renewal, precedence, and fail-closed capability semantics; +- complete source/overlay/materialized/provenance hashing; +- explicit provisional treatment of unavailable native outcomes; +- zero-unresolved versioned packaging parity classification; +- rejection of Claude, generated-tree, and legacy references; +- generic exclusion of ignored operator residue while scanning non-ignored untracked and force-added ignored files; +- typed fail-closed behavior when Git enumeration is unavailable; and +- the real repository topology and central Make/Node target-registry contract. + +The direct production entry point also passed: + +```text +make test-topology +{"ok":true,"violations":[]} +``` + +### 4. Former P1 regression boundaries + +Both independently confirmed Phase 11 P1 defects remain closed: + +| Boundary | Final result | +| --- | --- | +| Lifecycle overlay/E3 root A versus independently materialized source root B | Passed: one immutable source binding is revalidated and an A/B mismatch is rejected before target-state mutation | +| Caller-controlled `SUPPORTED_TARGETS` evaluated by GNU Make before Node validation | Passed: the override is rejected without evaluating caller syntax; all-target enumeration belongs to the central Node registry | + +The repaired stale contracts also pass: the topology test asserts the non-configurable Make guard plus Node delegation, and the outside-root overlay fixture reaches the intended `E_OVERLAY_IO` boundary without target mutation. + +### 5. Deterministic package lifecycle + +```text +node --test tests/platform-independent/release-package.test.mjs +``` + +Result: exit code 0; 4/4 passed. + +Coverage includes deterministic self-contained archives, extracted install/verify/uninstall for Codex/Cursor/Kiro CLI, E3 attestation rejection and binding, release metadata checks, target isolation, and one injected GitHub checkout shared by public source and overlay resolution. + +### 6. Clean committed-clone release evidence + +The final patch was synchronized into a history-preserving clone and committed before the strict checks. In that clean environment: + +- strict `make test-parity-release` passed for Codex, Cursor, and Kiro CLI; +- each target reported zero unresolved differences; +- `make test-topology` passed; +- the Git tree remained clean after validation; and +- isolated package commands generated all three target archives. + +This is materially stronger than the earlier dirty-local diagnostic parity result. The shared checkout still correctly refuses strict parity with `E_SOURCE_DIRTY`; that behavior is expected and protects the release boundary. + +### 7. Syntax and patch hygiene + +The final check set passed all 8 JavaScript syntax checks and `git diff --check`. A fresh `git diff --check` and focused 20-test run were repeated while refreshing this report and remained green. + +## Fix and Re-Verification History + +| Cycle | Evidence | Outcome | +| --- | --- | --- | +| Prior implementation iterations | Suite grew from 34 to 60 to 91 to 109 tests | Hardening closed earlier installer, recovery, evidence, packaging, parity, and source-resolution defects; two P1 boundaries remained | +| Resumed baseline | 109/109 plus independent reproduction | Lifecycle/materializer split-source binding and pre-validation Make expansion reconfirmed as P1 blockers | +| Resumed repair 1 | Singular immutable source binding; Node-owned target enumeration; focused regressions green | Both P1 production defects closed; two stale test contracts remained | +| Resumed repair 2 | Updated topology Make contract and source-bound overlay-negative fixture | Stale test contracts closed; shared-checkout suite reached 111/112 because ignored IDE residue was still traversed | +| Final topology repair | Git-aware repository enumeration plus two adversarial regressions | Ignored operator residue no longer affects repository policy; non-ignored untracked, tracked ignored, Git-failure, and read-failure boundaries remain covered; authoritative suite **114/114** | +| Final release-candidate verification | Clean committed clone strict parity, topology, cleanliness, and three isolated packages | **3/3 targets, zero unresolved; release-candidate evidence green** | + +## Release Conditions — Not Test Failures + +Phase 11 testing is complete and green. The following remain exact-tag publication controls: + +1. Repeat the 114/114 authoritative suite at the exact release commit. +2. Repeat clean strict parity, topology, same-job package generation, package lifecycle, checksums, SBOM, and provenance verification at that commit. +3. Declare the release workflow's required `contents: write` permission explicitly. +4. Recreate the output directory and publish only an explicit allowlist of the three archives and verified sidecars. +5. Keep E5/E6 unavailable outcomes, unsigned provenance, and cooperative-writer limits explicit in release claims. + +None of these conditions represents a failing test or a remaining critical/high production defect in the verified tree. + +## Structured Result + +```yaml +status: passed +report_path: verification/test-suite-results.md +generated: 2026-07-15T22:22:21Z +authoritative_suite: + command: make test-platform-independent + files: 10 + total: 114 + passing: 114 + failing: 0 + cancelled: 0 + skipped: 0 + todo: 0 + pass_rate: 100 +additional_checks: + make_validate: passed + focused_evidence_topology: + status: passed + tests: 20/20 + direct_topology: + status: passed + violations: 0 + release_package_lifecycle: + status: passed + tests: 4/4 + clean_committed_clone: + strict_parity: passed_3_of_3_zero_unresolved + topology: passed + git_tree_after_validation: clean + isolated_packages: codex_cursor_kiro_cli_generated + hygiene: + syntax_checks: passed_8_of_8 + git_diff_check: passed +regressions: + production: 0 + former_p1: 0 +issue_counts: + critical: 0 + warning: 0 + info: 0 +release_conditions: + - repeat_complete_release_sequence_at_exact_tag_commit + - declare_release_contents_write_permission + - publish_only_allowlisted_same_job_artifacts + - preserve_native_evidence_and_provenance_claim_boundaries +production_code_modified_by_reporter: false +test_code_modified_by_reporter: false +ide_state_modified_by_reporter: false +workflow_state_modified_by_reporter: false +``` diff --git a/.maister/tasks/development/2026-07-14-remove-obsolete-command-hook/orchestrator-state.yml b/.maister/tasks/development/2026-07-14-remove-obsolete-command-hook/orchestrator-state.yml new file mode 100644 index 00000000..2c518cf0 --- /dev/null +++ b/.maister/tasks/development/2026-07-14-remove-obsolete-command-hook/orchestrator-state.yml @@ -0,0 +1,78 @@ +orchestrator: + started_phase: phase-1 + current_phase: phase-14 + completed_phases: [phase-1, phase-2, phase-5, phase-6, phase-7, phase-8, phase-10, phase-11, phase-14] + failed_phases: [] + created: "2026-07-14T13:01:09Z" + updated: "2026-07-14T13:01:09Z" + task_path: .maister/tasks/development/2026-07-14-remove-obsolete-command-hook + task_context: + risk_level: medium + scope: Remove the obsolete command optimization hook, installer switches, generated wiring, and historical command prefixes from every project target. + clarifications_resolved: true + options: + html_output: true + spec_audit_enabled: true + e2e_enabled: false + user_docs_enabled: false + advisor: + enabled: true + gate_policies: + phase-exit: fully_automatic + optional-phase: fully_automatic + clarify: fully_automatic + convergence: fully_automatic + verify-matrix: fully_automatic + implementation_approval: + status: approved + final_actor: user + rationale: User explicitly confirmed removal across all platforms and requested automatic execution. + approved_scope: Complete removal from canonical sources, generated targets, install options, and repository documentation. + phase_summaries: + phase-1: + summary: The integration was limited to the Kiro adapter, its generated agent, two hook files, installer switches, and three historical research artifacts. + artifacts: [] + decisions: [] + risks: [] + phase-2: + summary: Scope confirmed as source-first removal followed by deterministic regeneration and cross-platform validation. + artifacts: [] + decisions: [] + risks: [] + phase-8: + summary: Removed the hook and its generated wiring, deleted installer enable/disable branches, and normalized historical command examples. + artifacts: + - platforms/kiro-cli/build.sh + - platforms/kiro-cli/smoke-install.sh + - plugins/maister-kiro/agents/maister.json + decisions: [] + risks: [] + phase-11: + summary: Full build and validation passed for all four target platforms; the Kiro smoke suite passed all 13 cases. + artifacts: [] + decisions: [] + risks: [] + phase-14: + summary: Final repository audit found no remaining references, files, installer options, or generated hook wiring for the removed integration. + artifacts: [] + decisions: [] + risks: [] + gate_history: + - schema_version: 1 + phase_id: implementation-approval + gate_type: implementation-approval + question: Approve complete implementation scope? + options: + - Approve complete implementation scope + - Reject implementation scope + - Request scope changes + policy: manual + safety_classification: denylisted + status: decided + selected_option: Approve complete implementation scope + final_actor: user + original_recommendation: Approve complete implementation scope + rationale: User confirmation in the task request authorizes the complete removal scope. + confidence: high + escalate_to_user: false + user_override: false diff --git a/.maister/tasks/init/2026-07-13-initialize-maister/analysis/project-analysis.md b/.maister/tasks/init/2026-07-13-initialize-maister/analysis/project-analysis.md new file mode 100644 index 00000000..9398a035 --- /dev/null +++ b/.maister/tasks/init/2026-07-13-initialize-maister/analysis/project-analysis.md @@ -0,0 +1,73 @@ +# Project Analysis: Maister + +## Classification + +- Project maturity: existing, mature, actively developed +- Architecture type: Standard, multi-platform +- Architecture: single-source, multi-target plugin transformation and distribution pipeline +- Source of truth: `plugins/maister/` +- Generated variants: `plugins/maister-cursor/`, `plugins/maister-kiro/`, `plugins/maister-codex/` + +## Purpose + +Maister provides standards-aware, resumable SDLC workflows for AI coding hosts. It covers requirements, specification, planning, implementation, verification, research, migration, performance, and product design while maintaining consistent behavior across Claude Code, Codex, Cursor, and Kiro. + +## Technology + +- Markdown with YAML frontmatter for skills, agents, commands, references, and documentation +- Bash, `sed`, `awk`, `grep`, `find`, and `jq` for platform transforms and validation +- JavaScript ESM on Node.js for continuation and product-design runtime components +- JSON, YAML, TOML, HTML, CSS, and Cursor MDC assets +- GNU Make for build and validation orchestration +- GitHub Actions for drift validation, releases, and smoke checks +- Shell contract tests, fixtures, generated-output assertions, and host-specific smoke tests + +There is no conventional frontend/backend application, database, container stack, root package manager, or traditional unit-test framework. + +## Core Conventions + +- Edit the canonical source and platform adapters; never edit generated variants directly. +- Keep skills and agents kebab-cased with validated YAML frontmatter. +- Keep commands thin and orchestration in `SKILL.md`. +- Use fail-fast, portable shell code with safe temporary-file and rollback behavior. +- Validate boundary inputs with allowlists and fail closed on ambiguity. +- Treat `orchestrator-state.yml` as the authoritative resumable state. +- Require explicit user confirmation for rollback and safety-sensitive gates. +- Keep source and marketplace versions synchronized. + +## Strengths + +- Clear source/generated boundary and deterministic platform adapters +- Broad host coverage with explicit native contracts +- Strong fixture-based safety, state, and configuration validation +- Automated drift detection and release checks +- Minimal dependency footprint +- Strict atomic Advisor/Arbiter configuration and read-only roles + +## Opportunities + +- Reduce fragility in large text-transform pipelines with semantic helpers or stronger golden fixtures. +- Add focused runtime tests for the Node continuation runner and product-design HTTP behavior. +- Pin optional Playwright MCP versions where reproducibility matters. +- Document required local tool versions and capabilities. +- Add an architecture document for source-to-target flow, state ownership, and Advisor/Arbiter decisions. + +## Inferred Context + +- Primary goals: cross-host semantic consistency; safe, auditable, resumable decisions; deterministic generation; Advisor/Arbiter automation without bypassing protected user gates. +- Team: small maintainer group with two dominant contributors and several additional contributors/automation. +- Requirements: macOS/Linux portability, exact generated-output drift checks, host-native vocabulary, read-only Advisor/Arbiter roles, explicit hard-denylisted gates, local installs, and synchronized versions. + +## Recommended Defaults + +- Documentation per Standard rule: Vision, Roadmap, Tech Stack, and Architecture +- Standards: global and testing +- Exclude frontend and backend standards + +## User Correction + +The initial Umbrella classification was corrected to Standard, multi-platform. The generated platform variants are artifacts of one cohesive product rather than independent systems. + +## Evidence + +Key sources inspected include `README.md`, `CLAUDE.md`, `Makefile`, plugin manifests and instructions, platform build scripts, Advisor and gate-engine tests, GitHub Actions workflows, workflow documentation, repository history, and semantic tags through v2.2.1. Analysis was read-only; no runtime tests were executed. diff --git a/.maister/tasks/init/2026-07-13-initialize-maister/orchestrator-state.yml b/.maister/tasks/init/2026-07-13-initialize-maister/orchestrator-state.yml new file mode 100644 index 00000000..82ece446 --- /dev/null +++ b/.maister/tasks/init/2026-07-13-initialize-maister/orchestrator-state.yml @@ -0,0 +1,152 @@ +schema_version: 1 +workflow: maister:init +status: completed +created_at: 2026-07-13 +updated_at: 2026-07-13 +current_phase: completed +advisor: + enabled: true + capability_posture: capability-matrix-controlled +phases: + - id: phase-1-pre-flight + name: Pre-flight checks + status: completed + metadata: + existing_content_removed: true + backup_created: false + blocked_by: [] + - id: phase-2-project-analysis + name: Analyze project codebase + status: completed + metadata: + report: analysis/project-analysis.md + blocked_by: [phase-1-pre-flight] + - id: phase-3-project-context + name: Present findings and gather context + status: completed + metadata: + analysis_confirmed: true + project_context_confirmed: true + project_architecture_type: Standard + architecture_qualifier: multi-platform + selected_documentation: [vision, roadmap, tech-stack, architecture] + blocked_by: [phase-2-project-analysis] + - id: phase-4-standards-selection + name: Select standards to initialize + status: completed + metadata: + selection_mode: smart-defaults + source: built-in + selected_categories: [global, testing] + blocked_by: [phase-3-project-context] + - id: phase-5-docs-structure + name: Initialize documentation structure + status: completed + metadata: + standards_categories: [global, testing] + index_created: true + project_directory_created: true + blocked_by: [phase-4-standards-selection] + - id: phase-6-project-docs + name: Generate project documentation + status: completed + metadata: + generated_documents: [vision.md, roadmap.md, tech-stack.md, architecture.md] + blocked_by: [phase-5-docs-structure] + - id: phase-7-validation + name: Validate initialization + status: completed + metadata: + validation_result: passed + indexed_documents: 12 + broken_references: 0 + git_diff_check: passed + blocked_by: [phase-6-project-docs] + - id: phase-8-standards-discovery + name: Discover coding standards + status: completed + blocked_by: [phase-7-validation] + metadata: + scope: full + confidence_threshold: 60 + auto_apply: false + skip_external: false + pr_count: 20 + phases: + - id: standards-1-plan + name: Plan discovery scope + status: completed + metadata: + user_approved: true + temp_directory: /tmp/maister-standards-discover.3hOEyM + blocked_by: [] + - id: standards-2-config + name: Analyze configuration files + status: completed + metadata: + findings: 0 + output: /tmp/maister-standards-discover.3hOEyM/config.yml + blocked_by: [standards-1-plan] + - id: standards-3-code + name: Mine code patterns + status: completed + metadata: + findings: 10 + output: /tmp/maister-standards-discover.3hOEyM/code.yml + blocked_by: [standards-1-plan] + - id: standards-4-docs + name: Extract documentation standards + status: completed + metadata: + findings: 22 + documents_analyzed: 13 + output: /tmp/maister-standards-discover.3hOEyM/docs.yml + blocked_by: [standards-1-plan] + - id: standards-5-external + name: Analyze external sources + status: completed + metadata: + findings: 3 + github_available: true + merged_prs_available: 2 + output: /tmp/maister-standards-discover.3hOEyM/external.yml + blocked_by: [standards-1-plan] + - id: standards-6-aggregate + name: Aggregate and deduplicate findings + status: completed + metadata: + raw_findings: 35 + unique_standards: 31 + conflicts: 0 + high_confidence: 1 + medium_confidence: 2 + low_confidence: 28 + report: standards-discovery/findings.md + blocked_by: [standards-2-config, standards-3-code, standards-4-docs, standards-5-external] + - id: standards-7-review + name: Review findings with user + status: completed + metadata: + approved: [H1, M1, M2] + skipped: [L1-L28] + conflicts_resolved: 0 + blocked_by: [standards-6-aggregate] + - id: standards-8-apply + name: Apply approved standards + status: completed + metadata: + created: 1 + updated: 2 + approved_applied: [H1, M1, M2] + index_regenerated: true + agents_integration_verified: true + blocked_by: [standards-7-review] + - id: standards-9-summary + name: Generate summary report + status: completed + metadata: + report: standards-discovery/summary.md + sources_analyzed: [config, code-patterns, documentation, ci-config, pull-requests] + standards_applied: 3 + standards_skipped: 28 + blocked_by: [standards-8-apply] diff --git a/.maister/tasks/init/2026-07-13-initialize-maister/standards-discovery/findings.md b/.maister/tasks/init/2026-07-13-initialize-maister/standards-discovery/findings.md new file mode 100644 index 00000000..37aad624 --- /dev/null +++ b/.maister/tasks/init/2026-07-13-initialize-maister/standards-discovery/findings.md @@ -0,0 +1,67 @@ +# Standards Discovery Findings + +## TL;DR + +Full discovery analyzed configuration, code patterns, documentation, CI, and available pull requests. It produced 35 raw findings and 31 semantic standards after deduplication. One finding scored high confidence, two scored medium confidence, and 28 remained below the configured 60% threshold. No contradictory findings were detected. + +## Scoring + +Scores follow the bundled aggregation strategy: unique source count (45 maximum), observed consistency (20), explicitness (15), evidence strength (20), and repeated PR feedback (10). The score does not reuse analyzer-provided confidence values. + +## High Confidence (>=80%) + +| # | Standard | Category | Score | Sources | Description | +|---|---|---|---:|---|---| +| H1 | Canonical source and reproducible generated variants | global/generated-artifacts | 95 | code-patterns, documentation, ci-config | Edit `plugins/maister/` or `platforms/`, run the build, and commit drift-free generated variants; never edit generated targets directly. | + +## Medium Confidence (60–79%) + +| # | Standard | Category | Score | Sources | Description | +|---|---|---|---:|---|---| +| M1 | Build and validate every platform before release | testing/release | 65 | documentation, ci-config | Every `v*` release must rebuild all platform variants and pass `make validate` before publication. | +| M2 | Prove rejected transactional mutations leave state unchanged | testing/safety | 60 | code-patterns | Snapshot transactional files and assert exact non-mutation or rollback, including modes where relevant. | + +## Low Confidence (<60%) + +| # | Standard | Category | Score | Sources | Description | +|---|---|---|---:|---|---| +| L1 | Fail fast in non-hook shell scripts | global/error-handling | 55 | code-patterns | Start non-hook build, install, smoke, generator, and test scripts with fail-fast shell behavior. | +| L2 | Use snake_case for shell functions | global/coding-style | 55 | code-patterns | Name shell functions with lowercase snake_case. | +| L3 | Use lowercase kebab-case shell filenames | global/coding-style | 55 | code-patterns | Use lowercase kebab-case, reserving dot suffixes for `.test` and `.e2e`. | +| L4 | Resolve repository paths from script location | global/portability | 40 | code-patterns | Derive `ROOT` or `SCRIPT_DIR` from `$0`, independent of the caller's working directory. | +| L5 | Use ESM and node-prefixed built-in imports | global/javascript | 55 | code-patterns | Write Node runtime modules as `.mjs` and import built-ins through `node:`. | +| L6 | Use lowerCamelCase for JavaScript functions | global/javascript | 55 | code-patterns | Name JavaScript function declarations with lowerCamelCase. | +| L7 | Encode shell test scope in filename | testing/naming | 55 | code-patterns | Use `.test.sh` for contract/structural tests and `.e2e.sh` for end-to-end tests. | +| L8 | Emit explicit shell test outcomes | testing/reporting | 40 | code-patterns | Print a `PASS` marker or final passed-count summary. | +| L9 | Read project documentation before work | global | 40 | documentation | Read `.maister/docs/INDEX.md`, then relevant standards, before work. | +| L10 | Evolve standards with user approval | global | 30 | documentation | Suggest recurring conventions and update standards only after approval. | +| L11 | Keep commands as thin skill wrappers | global | 35 | documentation | Put orchestration in `SKILL.md`; keep commands as delegators. | +| L12 | Scaffold plugin components consistently | global | 30 | documentation | Use documented locations and update the component catalog. | +| L13 | Write principle-based plugin documentation | global | 35 | documentation | Explain what, when, and why; avoid verbose implementation manuals. | +| L14 | Keep references conceptual and bounded | global | 35 | documentation | Keep references short, conceptual, and free of production implementations. | +| L15 | Require user confirmation before rollback | global | 35 | documentation | Never automatically revert changes; obtain explicit confirmation. | +| L16 | Keep Advisor and Arbiter read-only | global | 30 | documentation | Treat their output as recommendations, never mutation authority. | +| L17 | Use orchestrator-state.yml as source of truth | global | 40 | documentation | Use persistent orchestrator state for phases, gates, artifacts, and resume. | +| L18 | Keep workflow artifacts under task directory | global | 30 | documentation | Store reports and dashboards under `.maister/tasks///`. | +| L19 | Use standard task directory names | global | 30 | documentation | Use `YYYY-MM-DD-task-name` with a concise slug. | +| L20 | Use workflow artifact summary contract | global | 35 | documentation | Start workflow Markdown with bounded TL;DR and decision/risk sections. | +| L21 | Require explicit invocation for on-demand skills | global | 35 | documentation | Do not auto-run explicit-request-only skills. | +| L22 | Keep Playwright MCP opt-in | global | 35 | documentation | Enable browser MCP only for workflows that require it. | +| L23 | Do not pin host model settings | global | 35 | documentation | Inherit host/session model settings unless users opt into overrides. | +| L24 | Treat hooks as defense in depth | global | 30 | documentation | Hooks complement rather than replace sandbox and approval policy. | +| L25 | Guard new agents from destructive commands by default | global | 35 | documentation | Whitelist unrestricted shell access only when genuinely required. | +| L26 | Verify incrementally, then run the full suite | testing | 40 | documentation | Run focused tests per task group and the full suite before completion. | +| L27 | Use fresh workspaces for full E2E runs | testing | 35 | documentation | Prevent prior workflow state from contaminating E2E verification. | +| L28 | Monitor Cursor CLI parity weekly without blocking main CI | testing/platform-parity | 50 | ci-config | Run scheduled/manual parity smoke with recoverable skips for unavailable prerequisites. | + +## Conflicts + +No conflicts were detected among the aggregated findings. + +## Source Summary + +- Configuration: 0 findings; no supported classic linter/compiler/package-manager config was present. +- Code patterns: 10 findings; generated copies were not treated as independent evidence. +- Documentation: 22 findings from 13 documents. +- External/CI: 3 findings from three GitHub Actions workflows. +- Pull requests: only two merged PRs were available and neither contained review feedback; the three-PR evidence threshold was not met. diff --git a/.maister/tasks/init/2026-07-13-initialize-maister/standards-discovery/summary.md b/.maister/tasks/init/2026-07-13-initialize-maister/standards-discovery/summary.md new file mode 100644 index 00000000..9993f417 --- /dev/null +++ b/.maister/tasks/init/2026-07-13-initialize-maister/standards-discovery/summary.md @@ -0,0 +1,46 @@ +# Standards Discovery Summary + +## TL;DR + +Full discovery analyzed configuration, code patterns, documentation, CI, and available pull requests. Three standards were approved and applied: canonical/generated ownership, full cross-platform release validation, and exact transactional non-mutation/rollback testing. Twenty-eight findings below the 60% threshold were skipped by user choice. The documentation index and agent integrations validate successfully. + +## Key Decisions + +- Apply H1: canonical source and reproducible generated variants. +- Apply M1: build and validate every platform before a tagged release. +- Apply M2: prove rejected transactional mutations leave complete state unchanged. +- Skip all L1–L28 low-confidence findings. + +## Sources Analyzed + +- Configuration files: no supported classic linter/compiler/package-manager configs; 0 findings. +- Code patterns: 10 findings from canonical source, adapters, runtime modules, and shell tests. +- Documentation: 22 findings from 13 documents. +- External/CI: 3 findings from three GitHub Actions workflows. +- Pull requests: GitHub available; only two merged PRs and no qualifying review pattern. + +## Applied Standards + +- Created/recreated `standards/global/build-pipeline.md` and added two approved standards. +- Updated `standards/testing/test-writing.md` with transactional safety testing. +- Regenerated `INDEX.md` with 13 valid non-index document references. +- Verified `AGENTS.md` and `CLAUDE.md` integration; no final integration edit was needed. + +## Skipped Standards + +All 28 findings below the configured confidence threshold were skipped after review. They remain documented in `findings.md` for future reconsideration. + +## Verification + +- All indexed documentation paths resolve. +- Advisor is enabled for all five configured gate policies. +- Arbiter disagreement handling is enabled. +- Codex Advisor TOML exists. +- `git diff --check` passes. + +## Next Steps + +1. Review the generated project documents and standards. +2. Commit the initialization artifacts when ready. +3. Re-run standards discovery as the codebase and review history evolve. +4. Start structured work with `$maister:work`. diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/01-gate-state-contract.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/01-gate-state-contract.md new file mode 100644 index 00000000..1360378e --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/01-gate-state-contract.md @@ -0,0 +1,190 @@ +# Kanoniczny kontrakt gate engine i stanu workflow + +## TL;DR + +Normatywna logika jest jednoznaczna: zgodność rekomendacji kończy gate decyzją advisora, a rozbieżność tworzy jeden rekord arbitra, którego kolejne wywołania są retry tego samego arbitra. +Obecny `phase-continue.mjs` nie wykonuje tej logiki; otrzymuje już wybraną opcję i zapisuje uboższą, syntetyczną historię bez odpowiedzi, modeli i prób advisora/arbitra. +Realny state workflow używa `started_phase`, lecz przejście runnera wymaga `current_phase`; z kolei pełny rekord wymagany przez gate engine jest odrzucany przez allowlistę runnera. +Kanonicznym kursorem fazy powinien zostać `orchestrator.current_phase`, weryfikowany względem `phases[]`; `gate_history[]` powinno przechowywać bezstratny pełny rekord engine, a runner tylko wykonywać utrwalony wynik. + +## Key Decisions + +- Przyjąć `orchestrator.current_phase` jako jedyne mutowalne źródło bieżącej fazy; `phases[]` jest rejestrem statusów i musi spełniać inwariant dokładnie jednej fazy `in_progress` wskazywanej przez `current_phase`. +- Przechowywać jedną mapę `advisor` i jedną mapę `arbiter` w rekordzie gate; retry dopisują `attempts[]`, nigdy nie tworzą kolejnego obiektu arbitra ani nie wracają do advisora. +- Ujednolicić `gate_history[]` jako pełny, bezstratny rekord wyniku engine wraz z tożsamością gate i informacją continuation; nie rekonstruować audytu z wąskiego payloadu runnera. +- Zachować kolejność: pending/attempt przed modelem, terminalny gate przed raportami, raporty przed dispatch/transition. Retry po awarii raportu lub transition wykorzystuje ten sam terminalny rekord. + +## Open Questions / Risks + +- Pełny `normalized_gate_result` z dokumentacji nie zawiera dziś `phase_id`, `gate_type`, `question`, `options`, `policy`, `safety_classification` ani `continuation`, choć te dane są wymagane w `gate_history`; trzeba formalnie rozszerzyć wynik albo zdefiniować jawny envelope historii. +- Dokumentacja mówi jednocześnie, że awaria raportu ma być terminalnym `failed`, i że po trwałym `decided` retry ma odtworzyć raport oraz dokończyć transition. Drugi model odpowiada istniejącym testom; status decyzji nie powinien być degradowany przez awarię projekcji. +- `phase-continue.mjs` zapisuje fazy przez tekstową transformację i nie aktualizuje `updated`, `phases[].completed` ani `phases[].started`; pełny kontrakt przejścia wymaga ustalenia właściciela tych pól. +- Ten finding definiuje stan decyzji i przejścia fazowego. Trwały cursor kolejnego problemu w tej samej fazie wymaga osobnego kontraktu dispatchu. + +## 1. Obowiązujący algorytm decyzji + +Źródłem normatywnym jest `gate-decision-engine.md`, ponieważ `orchestrator-patterns.md` jawnie deleguje do niego schemat i przejścia (`plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:94-101`). + +### 1.1 Agreement + +Advisor może zakończyć bezpieczny gate bez arbitra i użytkownika wtedy i tylko wtedy, gdy: + +1. gate nie jest denylisted; +2. policy to `fully_automatic`; +3. odpowiedź jest poprawną mapą czteropolową, a `selected_option` jest dokładnym elementem uporządkowanych `options` (`gate-decision-engine.md:104-120`); +4. rekomendacja advisora jest równa `original_recommendation` albo rekomendacji pierwotnej nie było; +5. confidence to `high` lub `medium`; +6. `escalate_to_user` jest `false`; +7. adapter posiada zweryfikowane `phase_continue(selected_option)` (`gate-decision-engine.md:266-270`). + +Wynik to jeden terminalny rekord `status: decided`, `final_actor: advisor`; nie ma wywołania arbitra ani user gate. W trybie `advisor`, nawet przy zgodności, aktorem końcowym pozostaje użytkownik (`gate-decision-engine.md:271-272`). + +**Wniosek — confidence: high.** To dokładnie realizuje regułę użytkownika „gdy główny agent i advisor się zgadzają, bierzemy tę decyzję”, ale tylko dla bezpiecznej, wystarczająco pewnej ścieżki `fully_automatic`. + +### 1.2 Disagreement i dokładnie jeden logiczny arbiter + +Rozbieżność przy włączonym arbitrażu przechodzi `advisor_pending → arbiter_pending`. Engine tworzy jedną mapę `arbiter`, przekazuje obie różne rekomendacje i oba uzasadnienia, a kolejne nieudane wywołania dopisuje do `arbiter.attempts[]`. Nie wolno tworzyć drugiego obiektu arbitra ani wracać do advisora (`gate-decision-engine.md:256-259,273-289`). Arbiter może wybrać wyłącznie jedną z dwóch konkurujących rekomendacji (`gate-decision-engine.md:115-120`). + +Poprawny wynik `high|medium`, bez eskalacji, dla bezpiecznego gate daje `status: decided`, `final_actor: arbiter`. Wyczerpanie prób, low confidence lub eskalacja przechodzi do user gate w hoście interaktywnym albo do `blocked` bez interakcji (`gate-decision-engine.md:280-300`). + +**Wniosek — confidence: high.** „Jeden arbiter” oznacza jedną logiczną decyzję i jeden trwały obiekt `arbiter`; limit `arbiter_attempts` oznacza retry tej decyzji, a nie N niezależnych arbitrów. + +### 1.3 Resume i idempotency + +Klucz jest SHA-256 kanonicznego JSON `[phase_id, gate_type, question, ordered_options]`; rekomendacja, policy i output modeli nie należą do klucza (`gate-decision-engine.md:202-220`). Przed każdym wywołaniem hosta engine musi odczytać historię. Terminalne `decided|blocked|failed` zwraca bez kolejnego modelu, użytkownika i bez duplikatu (`gate-decision-engine.md:222-229`). + +Resume z `advisor_pending` wraca do tego samego advisora i zachowuje próby; z `arbiter_pending` wraca wyłącznie do tej samej mapy arbitra. Niedokończona próba `status: started` jest zamykana jako timeout/interruption i zużywa slot retry (`gate-decision-engine.md:332-346`). + +**Wniosek — confidence: high.** Idempotency gate oraz pojedyncze mapy ról wystarczają, aby nie uruchomić drugiego logicznego arbitra, pod warunkiem że pending i każda próba są naprawdę zapisywane przed wywołaniem. + +## 2. Dokładne rozjazdy schematu + +### 2.1 `started_phase` kontra `current_phase` kontra `phases[]` + +- Wspólny schemat dokumentuje `orchestrator.started_phase` (`orchestrator-patterns.md:275-283`). +- Realny stan bieżącego researchu ma `started_phase: phase-1`, nie ma `current_phase`, a rootowe `phases[]` oznacza phase-1 jako `in_progress` (`.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/orchestrator-state.yml:1-4,57-67`). +- Runner dopuszcza brak `current_phase` w ogólnym preflight (`phase-continue.mjs:529-561`), lecz każde przejście z `next_phase` wymaga `model.currentPhase === phaseId` (`phase-continue.mjs:564-576`). W efekcie realny state przejdzie część walidacji, a następnie failnie przy transition. +- Wszystkie pozytywne fixtures runnera używają `current_phase`, np. `tests/fixtures/phase-continue/valid-empty.yml:1-11`; aktywne testy przejścia asertują zmianę `current_phase` (`tests/fully-automatic-phase-continue.test.sh:13-38`). + +**Rekomendacja — confidence: high.** Kanoniczne pole to `current_phase`, bo opisuje zmienny cursor wykonania i jest już wymagane przez wykonywalny transition oraz hostowe resume hooks. `started_phase` należy usunąć z wspólnego schematu i generatorów stanów; jeśli potrzebna jest informacja historyczna o wejściu, powinna być niemutowalnym `initial_phase`, nie konkurencyjnym kursorem. `phases[]` pozostaje źródłem statusów, ale nie powinno samodzielnie zastępować kursora: wyprowadzanie fazy z listy utrudnia walidację uszkodzonego stanu. + +### 2.2 Pełny wynik engine kontra wąska historia runnera + +Normatywny wynik ma zagnieżdżone `advisor` i `arbiter`, w tym agent, model, response, wszystkie attempts oraz exhausted (`gate-decision-engine.md:136-166`). Orchestrator ma zapisać kompletny wynik, a wzorzec dodatkowo wymaga question, options, gate type, policy/safety, odpowiedzi, modeli, retries i override (`orchestrator-patterns.md:121-126`). + +Runner przyjmuje tylko `selected_option`, `actor` i `confidence` jako dane decyzji (`phase-continue.mjs:18-35,209-234`). Sam tworzy rationale `Validated fully automatic continuation`, ustawia `original_recommendation` na wybraną opcję i nie posiada surowej odpowiedzi ani prób (`phase-continue.mjs:765-782`). Jego `HISTORY_FIELDS` nie obejmuje `policy`, `safety_classification`, `advisor` ani `arbiter` (`phase-continue.mjs:281-298`), a walidator odrzuca każdy nieznany field (`phase-continue.mjs:502-527`). + +**Wniosek — confidence: high.** To nie jest tylko różnica szerokości: runner traci provenance i może fałszywie zapisać `original_recommendation = selected_option` po arbitrażu. Obecny runner nie może być producentem kanonicznego rekordu decyzji. Powinien konsumować wcześniej utrwalony, zwalidowany terminalny rekord i wykonywać continuation; ewentualnie payload musi nieść klucz/oczekiwany wybór do weryfikacji, a nie dane do rekonstrukcji historii. + +### 2.3 Testy nie wykonują advisora ani arbitra + +`gate-decision-fixtures.yml` deklaruje agreement, dwa wyniki arbitra i resume (`gate-decision-fixtures.yml:4-15,48-63`), ale test tylko sprawdza, czy odpowiednie linie istnieją w YAML (`tests/gate-decision-engine.test.sh:70-109`). Reguła jednego arbitra również jest weryfikowana przez wyszukiwanie fraz w Markdown (`tests/gate-decision-engine.test.sh:173-180`). + +Runnerowe testy wykonują persistence, raporty, transition i retry awarii, lecz przekazują już finalne `actor` i `selected_option`; nie uruchamiają state machine modeli (`tests/fully-automatic-phase-continue.test.sh:32-46`). Lokalny baseline przeszedł: 28 testów prose/fixture engine, smoke phase continuation oraz 21 przypadków kontraktu runnera. Zielony baseline potwierdza obecny wąski kontrakt, nie agreement/arbitration end-to-end. + +**Wniosek — confidence: high.** Fixture agreement/arbitration jest specyfikacją deklaratywną, nie wykonywalnym dowodem. Potrzebny jest deterministyczny evaluator testujący kolejne durable stany i liczbę wywołań ról. + +## 3. Proponowany kanoniczny schemat + +Poniższy envelope scala tożsamość gate, politykę, pełny `normalized_gate_result` i continuation bez utraty danych: + +```yaml +orchestrator: + current_phase: phase-4 + completed_phases: [] + failed_phases: [] + gate_history: + - schema_version: 1 + idempotency_key: "sha256:<64 lowercase hex>" + phase_id: phase-4 + gate_type: research-convergence + question: "Które podejście wybrać?" + options: ["A", "B", "Need more info"] + original_recommendation: "A" + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "B" + final_actor: arbiter + advisor: + agent: advisor + model: gpt-5.6-sol + response: + selected_option: "B" + rationale: "..." + confidence: high + escalate_to_user: false + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: + selected_option: "B" + rationale: "..." + confidence: high + escalate_to_user: false + attempts: [] + exhausted: false + rationale: "..." + confidence: high + escalate_to_user: false + user_override: false + continuation: + kind: same_phase # same_phase | phase_transition | none + target: "decision-area:2" + status: pending # pending | applied | blocked + error: null +``` + +Zasady: + +- Rekord pending i terminalny mają ten sam envelope i idempotency key; aktualizacja rekordu nie dodaje drugiego wpisu. +- `advisor` i `arbiter` zawsze są pojedynczymi mapami (nullable response, lista prób). Nie modelować arbitra jako listy. +- `continuation` jest durable intent/receipt, a nie tylko string `phase_continue`; umożliwia rozróżnienie decyzji od wykonanego dispatchu i dokładne resume. Szczegóły targetu same-phase należą do kontraktu dispatchera. +- `current_phase` musi wskazywać jedyną fazę `in_progress`; wszystkie identyfikatory w `completed_phases` muszą odpowiadać fazom `completed`. +- Exact-schema validation pozostaje, ale allowlista musi być wspólna dla evaluator/runner/fixtures zamiast utrzymywania dwóch niezgodnych ręcznych list. + +**Confidence: medium-high.** Pełny audyt i `current_phase` wynikają bezpośrednio z kontraktu. Strukturalny obiekt `continuation` jest rekomendowanym rozszerzeniem, ponieważ obecny scalar nie odróżnia durable intent od applied receipt; ostateczny kształt powinien zostać uzgodniony z modelem dispatchu kolejnych problemów. + +## 4. Tabela przejść stanu gate + +| Stan źródłowy | Zdarzenie | Trwały zapis przed akcją | Stan docelowy | Aktor / dalsza akcja | +|---|---|---|---|---| +| brak | valid gate, manual/denylist | `user_pending` | `user_pending` | user gate | +| brak | valid gate, advisor/fully automatic | `advisor_pending` + attempt `started` | `advisor_pending` | invoke advisor | +| `advisor_pending` | malformed/timeout, retry pozostaje | zakończona próba + backoff + nowa próba `started` | `advisor_pending` | ten sam advisor | +| `advisor_pending` | advisor agrees, high/medium, no escalation, supported AUTO | pełny terminalny rekord | `decided` | `final_actor: advisor`; raport, potem continuation | +| `advisor_pending` | advisor disagrees, arbitration enabled | advisor valid + jedna mapa arbitra + attempt `started` | `arbiter_pending` | invoke arbiter | +| `arbiter_pending` | malformed/timeout, retry pozostaje | zakończona próba + backoff + nowa próba w tej samej mapie | `arbiter_pending` | ten sam logiczny arbiter | +| `arbiter_pending` | valid high/medium, no escalation, supported AUTO | pełny terminalny rekord | `decided` | `final_actor: arbiter`; raport, potem continuation | +| `advisor_pending` / `arbiter_pending` | low/escalation/exhaustion | wynik/exhausted | `user_pending` albo `blocked` | user jeśli interaktywny, inaczej stop | +| dowolny pending | błąd trwałości/contract | pełny błąd, jeśli zapis możliwy | `failed` | stop | +| `decided|blocked|failed` | resume z tym samym kluczem | brak nowego wpisu i brak modeli | ten sam terminalny stan | odtwórz brakujące projekcje/continuation tylko zgodnie z receipt | + +## 5. Kolejność trwałości i atomowość + +Normatywna kolejność to: state read/key → pending/attempt atomic write → dashboard → model → updated attempt lub terminal atomic write → dashboard → raporty ze stanu → continuation (`gate-decision-engine.md:418-438`). Runner realizuje terminal state → ponowny odczyt → raporty → transition (`phase-continue.mjs:784-792`) i ma indywidualne atomic writes przez temp file, `fsync` i rename (`phase-continue.mjs:597-617`). Testy potwierdzają, że awaria raportu zostawia jeden terminalny wpis do regeneracji, a awaria transition jest dokańczana dokładnie raz (`tests/phase-continue-contract.test.sh:432-462`). + +Nie jest to jedna transakcja obejmująca trzy pliki; bezpieczeństwo pochodzi z trwałego terminalnego checkpointu i idempotentnego recovery. Minimalny wymagany porządek: + +1. przed modelem: utrwal pending i `attempt: started`; +2. po modelu: utrwal wynik próby; +3. po końcowym wyborze: utrwal kompletny terminalny rekord z `continuation.status: pending`; +4. odśwież dashboard i wygeneruj raporty wyłącznie z kanonicznego stanu; +5. wykonaj dispatch/transition; +6. utrwal `continuation.status: applied` i nowy cursor/status fazy w jednym atomicznym zapisie stanu albo zapewnij równoważny inwariant rozpoznawalny na resume. + +**Confidence: high dla kolejności 1-5, medium dla receipt w kroku 6.** Obecny phase transition wykrywa applied po `current_phase` i statusach (`phase-continue.mjs:579-588`), ale same-phase dispatch będzie wymagał jawnego receipt/cursora. + +## 6. Minimalne źródła prawdopodobnie wymagające zmiany + +1. `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` — jeden pełny schema/envelope, jawna semantyka pending update vs append, continuation receipt i usunięcie sprzeczności `failed` po awarii raportu. +2. `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` — zastąpić `started_phase` przez `current_phase`, dopisać inwariant względem `phases[]` i wskazać pełny record. +3. `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` — konsumować pełny istniejący terminalny rekord zamiast syntetyzować uboższą historię; walidować wspólny schema i aktualizować kanoniczny cursor/receipt. +4. `plugins/maister/skills/orchestrator-framework/references/gate-decision-fixtures.yml` — rozwinąć deklaracje do pełnych input/state/expected transitions dla agreement, obu wyników arbitra, retry i resume. +5. `tests/gate-decision-engine.test.sh` — zastąpić lub uzupełnić grep-tests wykonywalnym deterministic evaluator harness, z licznikami advisor/arbiter/user i asercją jednego obiektu historii. +6. `tests/fixtures/phase-continue/*.yml`, `tests/phase-continue-contract.test.sh`, `tests/fully-automatic-phase-continue.test.sh` — użyć realnego pełnego stanu tworzonego przez workflow oraz testować migration/inwariant `current_phase`. +7. Źródłowe `plugins/maister/skills/{research,product-design,development,migration,performance}/SKILL.md` — generowanie i resume muszą używać tego samego kursora i pełnego rekordu; generated variants powinny powstać dopiero przez build. + +Minimalny pierwszy pion zmian to schema + real fixtures + evaluator test. Dopiero na tym kontrakcie runner i adapter Codex mogą bezpiecznie wykonywać decyzję bez utraty audytu. diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/02-continuation-dispatch.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/02-continuation-dispatch.md new file mode 100644 index 00000000..c851cb0c --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/02-continuation-dispatch.md @@ -0,0 +1,218 @@ +# Kontynuacja i dispatch następnej jednostki pracy + +## TL;DR +`phase-continue.mjs` jest bezpiecznym writerem terminalnego gate'u, raportów i opcjonalnej zmiany statusu fazy, ale nie jest dispatcherem: po wypisaniu JSON proces kończy się. +Bez `next_phase` runner nie przesuwa żadnego kursora; z `next_phase` jedynie atomowo zmienia `current_phase` i statusy faz, lecz nie uruchamia kodu następnej fazy. +Najlepszy seam to: runner odpowiada za trwały commit, adapter hosta za transport i zwrot dyrektywy `continue`, a pętla workflow za semantyczny cursor, projekcję wyboru i natychmiastowy dispatch kolejnego problemu w tej samej turze. +Dokładnie-jednorazowy resume wymaga trwałych identyfikatorów work itemów i stanu `ready/in_progress/completed`; sam indeks lub samo `next_phase` nie wystarcza. + +## Key Decisions +- Nie rozszerzać `phase-continue.mjs` do wykonywania workflowów ani wywoływania agentów. Runner nie zna domenowej kolejności decision areas, zależności między nimi ani hostowych narzędzi. +- Rozdzielić `commit` od `dispatch`: sukces runnera oznacza „decyzja i wymagane projekcje są trwałe”, a nie „następna praca została wykonana”. +- Trzymać canonical continuation cursor w `orchestrator-state.yml`, ale jego semantykę i wyliczanie następnego work itemu pozostawić workflowowi. Adapter Codex jedynie utrzymuje tę samą turę i przekazuje wynik runnera do pętli. +- Używać stabilnego `work_item_id`, `source_gate_key` i statusu itemu zamiast samego numeru indeksu. Indeks może być informacyjny, lecz zmiana artefaktu nie może skierować resume na inny problem. +- Phase entry self-check musi akceptować terminalny automatyczny rekord i trwałe przejście jako alternatywę dla historycznego call ID `AskUserQuestion`; obecny warunek wymusza UI mimo poprawnego `fully_automatic`. + +## Open Questions / Risks +- Bieżące workflowy zapisują `orchestrator.started_phase`, a transition runner wymaga `orchestrator.current_phase`; realny stan aktywnego researchu nie przejdzie transition preflight (`orchestrator-state.yml:2`, `phase-continue.mjs:555,569`). To musi zostać ujednolicone przed adapterem. +- Runner tworzy własny wąski rekord gate, mimo że kontrakt engine wymaga wcześniej pełnego terminalnego rekordu. Bez ujednolicenia własności zapisu powstaje ryzyko dwóch writerów i utraty danych advisor/arbiter (`gate-decision-engine.md:301-314`, `phase-continue.mjs:766-785`). +- Ścisłe „exactly once” dla zewnętrznego model call/Task dispatch jest niemożliwe bez transakcyjnego host API. Można zagwarantować dokładnie jeden logiczny work item i idempotentny resume; fizyczne wywołanie po przerwaniu może być retry i musi używać tego samego `dispatch_id`/gate key. +- Produktowy refinement może wracać do wcześniejszej fazy, podczas gdy runner jawnie odrzuca backward transition (`product-design/SKILL.md:526-534`, `phase-continue.mjs:574-576`). Ten routing wymaga jawnego workflow resetu, nie `next_phase` obecnego runnera. + +## 1. Co robi runner dzisiaj + +### Payload bez `next_phase` + +1. Payload przechodzi exact-schema validation; `next_phase` jest jedynie polem opcjonalnym (`phase-continue.mjs:18-35,209-244`). +2. Runner czyta i waliduje canonical state, oblicza idempotency key i szuka terminalnego rekordu (`phase-continue.mjs:741-749`). +3. Przy nowej decyzji appenduje terminalny rekord i atomowo zapisuje stan (`phase-continue.mjs:766-787`). +4. Generuje żądane raporty z ponownie odczytanego, persisted state (`phase-continue.mjs:786-788`, `711-739`). +5. Ponieważ brak `next_phase`, pomija `updatePhaseState` i wypisuje kompaktowy JSON (`phase-continue.mjs:789-794`). Potem `main()` wraca, a proces Node kończy się (`phase-continue.mjs:797-800`). + +Skutek: gate jest trwały, lecz `current_phase`, statusy faz, domenowy wybór (`chosen_approach`) i pozycja w pętli nie zmieniają się. Test kontraktowy potwierdza tę odrębność: bez transition faza 1 pozostaje aktywna, faza 2 pending (`tests/phase-continue-contract.test.sh:417-429`). + +### Payload z `next_phase` + +1. Przed jakimkolwiek zapisem runner wymaga: `current_phase == phase_id`, bieżącej fazy `in_progress`, targetu `pending`, targetu późniejszego w `phases[]` (`phase-continue.mjs:564-577`). +2. Po terminalnym zapisie i raportach `updatePhaseState` ustawia źródło na `completed`, target na `in_progress`, podmienia `current_phase` i dopisuje źródło do `completed_phases` (`phase-continue.mjs:661-700,784-792`). +3. Na retry wykrywa już zastosowane przejście po kombinacji `current_phase`, dwóch statusów i nie wykonuje go ponownie (`phase-continue.mjs:579-589,751-761`). +4. Następnie ponownie tylko wypisuje JSON i kończy proces. Nie importuje workflow SKILL, nie wywołuje host toola i nie posiada callbacka dispatch (`phase-continue.mjs:741-800`). + +Skutek: trwała maszyna stanów wskazuje nową fazę, ale execution turn nie przechodzi sam do kodu tej fazy. Istniejący test nazywa to „continuation”, choć obserwuje wyłącznie state/report, nie dispatch: asercje sprawdzają `current_phase`, statusy i JSON (`tests/fully-automatic-phase-continue.test.sh:32-46`). + +## 2. Dokładne miejsce zatrzymania tury + +```text +workflow call site + │ evaluate_gate(...) / advisor / arbiter + │ terminal normalized result + ▼ +Codex host adapter ← obecnie brak wykonywalnej warstwy + │ exact JSON + ▼ +phase-continue.mjs + ├─ validate state + idempotency + ├─ persist terminal record + ├─ render reports + ├─ [optional] transition phase state + └─ stdout {status, key, selected_option, continuation} + │ + └─ process exits ← konkretny punkt zatrzymania + +BRAK: + stdout consumer → apply gate effect → advance cursor → dispatch next item +``` + +Historyczna diagnoza identyfikuje brak mapowania `valid advisor result → runner → observed transition` w Codex (`codex-fully-automatic-diagnosis.md:62-79`). Analiza runnera doprecyzowuje, że nawet po dodaniu tego mapowania pozostaje drugi brak: nie istnieje konsument sukcesu, który kontynuuje workflow w tej samej turze. + +Kontrakt frameworka nakazuje przy AUTO-CONTINUE nie kończyć tury i natychmiast wykonać następną fazę (`orchestrator-patterns.md:130-139`). Jest to wymaganie wobec hosta/orchestratora, nie zachowanie wykonywane przez Node runner. + +## 3. Dlaczego `next_phase` nie rozwiązuje kolejnego problemu w tej samej fazie + +`next_phase` musi być innym, późniejszym elementem rootowego `phases[]` (`phase-continue.mjs:571-576`). Decision area w research Phase 4 nadal należy do `phase-4`, więc użycie `next_phase: phase-4` jest jawnie odrzucane. Payload nie ma `next_work_item`, `cursor` ani domenowej mutacji (`phase-continue.mjs:18-35`). + +Call site research wymaga sekwencyjnego przetwarzania, bo późniejsze obszary zależą od wcześniejszych (`research/SKILL.md:340-350`). Jednocześnie resume sprawdza `phase_summaries.phase-4.decision_areas[].chosen_approach` (`research/SKILL.md:331-332`), którego runner nigdy nie zapisuje. Produktowy workflow ma ten sam wzorzec „record choice, move to next area” (`product-design/SKILL.md:514-524`). + +Wniosek: „gate decided” i „gate effect applied to workflow work item” są dziś dwiema różnymi operacjami, ale nie mają jawnego protokołu pomiędzy sobą. + +## 4. Rekomendowany podział odpowiedzialności + +| Warstwa | Powinna posiadać | Nie powinna posiadać | +|---|---|---| +| Runner | strict validation, terminal idempotency, atomowy zapis, raporty, idempotentny phase transition/checkpoint | wybór kolejnego decision area, czytanie alternatyw, wywoływanie agentów, kończenie/utrzymywanie host turn | +| Adapter hosta Codex | mapowanie normalized result → exact runner JSON, uruchomienie runnera, sprawdzenie exit/stdout, zwrot dyrektywy `continue` bez UI i bez zakończenia tury | domenowy routing, modyfikacja artifactów, własna kopia state machine | +| Pętla workflow | stabilne work itemy, zastosowanie wybranej opcji, next-item computation, phase routing, natychmiastowe wykonanie kolejnej jednostki | ponowne implementowanie gate validation, arbitrażu i bezpieczeństwa runnera | + +To jest najgłębszy bezpieczny seam: runner pozostaje deterministycznym persistence boundary, adapter jest cienkim hostowym wykonawcą, a workflow zachowuje wiedzę domenową. Wpychanie dispatchu do runnera sprzęgnęłoby wspólny skrypt z Codex tool API oraz prose-defined fazami; wpychanie kursora do adaptera utworzyłoby drugie source of truth obok `orchestrator-state.yml`. + +## 5. Proponowany cursor i kontrakt dispatchu + +Przykładowy canonical fragment stanu: + +```yaml +orchestrator: + current_phase: phase-4 + continuation: + schema_version: 1 + revision: 7 + source_gate_key: "sha256:..." + dispatch_id: "sha256:..." # hash(task, phase, work_item_id, logical iteration) + status: ready # ready | in_progress | completed | blocked + target: + kind: same_phase_work_item # same_phase_work_item | phase_entry + phase_id: phase-4 + work_item_type: decision_area + work_item_id: persistence-boundary + ordinal: 2 +``` + +Domenowy cursor powinien być oparty na stabilnym inventory: + +```yaml +research_context: + phase_summaries: + phase-4: + decision_areas: + - id: execution-owner + ordinal: 1 + status: completed + gate_key: "sha256:..." + chosen_approach: host-workflow-loop + - id: persistence-boundary + ordinal: 2 + status: ready + gate_key: null + chosen_approach: null +``` + +Zasady kontraktu: + +1. Workflow materializuje listę work itemów z artefaktu przed pierwszym gate'em. `work_item_id` jest stabilny i unikalny w fazie; ordinal nie jest tożsamością. +2. Przed oceną gate'u workflow ustawia item i `continuation` na `in_progress`, potem engine zapisuje `advisor_pending`/`arbiter_pending` przed model call zgodnie z normatywnym resume (`gate-decision-engine.md:244-259,316-346`). +3. Terminalny gate jest source of truth dla wyboru. Po sukcesie runnera pętla ponownie czyta stan i idempotentnie projektuje `selected_option` do itemu, zapisując `gate_key`. +4. W tym samym atomowym checkpointcie workflow oznacza item `completed` i ustawia następny nierozwiązany item na `ready`. Jeśli nie ma kolejnego itemu, ustawia target `phase_entry` i przekazuje runnerowi prawidłowy `next_phase`. +5. Adapter otrzymuje wyłącznie wynik typu `continue | user_gate | blocked`. `continue` nie kończy assistant turn; pętla natychmiast czyta `continuation.target` i wykonuje go. +6. Dispatch zawsze nosi `dispatch_id`. Powtórzenie tego samego id po resume jest wznowieniem jednego logicznego dispatchu, nie nowym itemem. + +Runner może zapisywać generyczny envelope `orchestrator.continuation`, ale nie powinien sam wyliczać targetu. Target powstaje w call site/workflow i musi być zwalidowany względem bieżącego phase/work-item inventory. Alternatywnie pierwsza implementacja może pozostawić runner bez nowego pola, pod warunkiem że workflow zapisze powyższy checkpoint zaraz po idempotentnym terminal reuse; envelope jest jednak czytelniejszy i testowalny przy crashach. + +## 6. Failure i resume — wymagane zachowanie + +| Punkt przerwania | Trwały stan | Zachowanie resume | +|---|---|---| +| Przed advisor call | item `in_progress`, gate `advisor_pending`, attempt `started` | wznowić ten sam gate; zamknąć przerwany attempt jako timeout i zużyć slot | +| Po terminal state, przed raportem | terminal gate istnieje, item może być `in_progress` | runner reuse regeneruje raport; nie duplikuje gate; dopiero potem workflow aplikuje effect | +| Po raporcie, przed gate effect/cursor | terminal gate + raport, stary cursor | workflow odczytuje terminal selection, idempotentnie uzupełnia item i ustawia następny target | +| Po cursor advance, przed dispatch | next item `ready` z `dispatch_id` | adapter/workflow dispatchuje dokładnie ten target | +| Po dispatch start, przed odpowiedzią modelu | item `in_progress`, pending gate/attempt | resume tego samego logicznego gate'u; ewentualny fizyczny retry zachowuje key i retry budget | +| Po phase transition, przed phase body | stara faza `completed`, nowa `in_progress`, `phase_entry` ready | wejść do nowej fazy bez ponownego transition i bez user UI | +| Transition write failure | terminal gate i raport istnieją, fazy niezmienione | retry runnera stosuje transition raz; istniejący test to potwierdza (`tests/phase-continue-contract.test.sh:447-462`) | + +Obecny runner już dobrze realizuje dwa fragmenty: report failure pozostawia terminalny record do regeneracji (`tests/phase-continue-contract.test.sh:432-445`), a transition failure wraca do tej samej decyzji i przechodzi raz (`tests/phase-continue-contract.test.sh:447-462`). Brakuje analogicznych testów dla effect/cursor/dispatch. + +## 7. Call-site’y wymagające korekty + +### Research + +- `research/SKILL.md:93-107`: kontrakt runnera powinien opisywać nie tylko durable phase transition, lecz także obowiązek konsumowania sukcesu i utrzymania tury. +- `research/SKILL.md:331-357`: pętla decision areas powinna mówić „terminal result”, nie „If user picks”, oraz zapisywać item/cursor przed przejściem dalej. +- `research/SKILL.md:367` i `416`: phase entry self-check musi uznać terminalny auto gate + trwały transition, a nie wymagać wyłącznie call ID user gate. + +### Product design + +- `product-design/SKILL.md:514-524`: ta sama pętla same-phase decision areas potrzebuje wspólnego cursor contractu. +- `product-design/SKILL.md:526-545`: refinement/return-to-Phase-4 potrzebuje osobnej, jawnej reset transition, bo obecny runner obsługuje tylko forward pending target. +- `product-design/SKILL.md:551-559`: entry check i routing muszą konsumować persisted terminal/continuation, nie zakładać user click. + +### Development + +- `development/SKILL.md:121-149`: wspólny call-site contract kończy się na runnerze; trzeba dopisać konsumpcję JSON, re-read state i dispatch w tej samej turze. +- `development/SKILL.md:256-290`: wiele `phase-2-scope-decision` jest kolejnymi problemami w jednej fazie i wymaga identycznego stable work-item cursor. +- Powtarzające się phase entry self-checks, np. `development/SKILL.md:296-315`, muszą odróżniać poprawne `fully_automatic` od pominiętego gate'u. + +## 8. Testy, których dziś brakuje + +Istniejący contract matrix dowodzi strict payload/state validation, rozdzielenia no-transition/transition oraz recovery report/transition (`tests/phase-continue-contract.test.sh:365-462`). Nie dowodzi kontynuacji execution turn ani kolejnego same-phase itemu. Minimalne nowe przypadki: + +1. **same-phase two-item contract**: advisor kończy area A; state ma A completed i B ready; adapter w tej samej turze uruchamia gate B; brak user gate. +2. **crash after terminal before effect**: retry nie dopisuje gate, aplikuje A raz i dispatchuje B raz logicznie. +3. **crash after cursor before dispatch**: resume dispatchuje B z tym samym `dispatch_id`. +4. **phase-entry continuation**: runner przechodzi fazę, adapter konsumuje stdout, workflow faktycznie tworzy pierwszy checkpoint/artifact następnej fazy — sama zmiana statusu nie wystarcza. +5. **auto entry self-check**: persisted automatic exit gate nie wywołuje user UI; brak terminalnego rekordu nadal fail-closed odpala gate. +6. **dependent area recomputation**: wybór A może zmienić dozwolone warianty B; inventory/cursor waliduje B dopiero po zaaplikowaniu A, nie pre-renderuje wszystkich gate'ów. +7. **duplicate dispatch rejection**: drugi `dispatch_id` dla tego samego source gate/item jest odrzucony bez mutacji; retry tego samego id jest reuse. + +Host-native E2E powinien obserwować nie tylko `current_phase`, lecz konkretny side effect następnego dispatchu (np. trwały marker pierwszego work itemu kolejnej fazy lub drugiego decision area) oraz brak wywołania user gate. + +## 9. Pliki prawdopodobnie wymagające zmiany + +### Źródła kanoniczne + +- `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` — ujednolicony state schema; ewentualny generyczny continuation checkpoint i bogatszy wynik stdout. +- `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` — jednoznaczna granica terminal persistence vs gate effect/dispatch oraz resume cursor. +- `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` — canonical `current_phase`/cursor i auto phase-entry self-check. +- `plugins/maister/skills/research/SKILL.md` — same-phase loop i auto transition consumer. +- `plugins/maister/skills/product-design/SKILL.md` — wspólna pętla decision areas oraz refinement reset. +- `plugins/maister/skills/development/SKILL.md` — sekwencja scope decisions i phase routing. + +### Adapter Codex + +- Nowy wykonywalny wrapper/adapter pod `platforms/codex-cli/` — transport normalized result, runner invocation, stdout validation i dyrektywa continue bez UI. +- `platforms/codex-cli/build.sh` — projekcja adaptera do generated pluginu. +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` — prawdziwy same-turn/same-phase oraz next-phase dispatch zamiast `exit 77`. + +### Testy wspólne + +- `tests/phase-continue-contract.test.sh` i `tests/fixtures/phase-continue/*.yml` — realny state, cursor, crash windows i byte-exact rejection. +- Nowy deterministic workflow-loop/dispatch contract test — dwa same-phase work itemy i jeden phase entry. +- `tests/gate-decision-engine.test.sh` — wymagania prose/fixture na terminal → effect → cursor → dispatch. + +Generated variants (`plugins/maister-codex/`, Cursor, Kiro) powinny powstać przez `make build`, nie być edytowane bezpośrednio. + +## 10. Confidence + +- **High** — runner bez `next_phase` nie wykonuje żadnego advance; z `next_phase` mutuje wyłącznie phase state i kończy proces. Dowód jest bezpośrednio w kodzie i testach. +- **High** — obecne same-phase convergence call-site’y nie mają wykonywalnego durable cursor/dispatch contractu. +- **High** — właściwy owner domenowego next-item computation to workflow loop; runner i adapter nie mają wymaganej wiedzy. +- **High** — obecne phase-entry self-checks są sprzeczne z automatycznym terminal gate'em, bo wymagają call ID `AskUserQuestion`. +- **Medium** — dokładny kształt generycznego `orchestrator.continuation` powinien zostać potwierdzony podczas designu state schema; kluczowe inwarianty (`work_item_id`, `source_gate_key`, `dispatch_id`, status) są konieczne niezależnie od finalnej serializacji. diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/03-codex-host-adapter.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/03-codex-host-adapter.md new file mode 100644 index 00000000..cf3deb6c --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/03-codex-host-adapter.md @@ -0,0 +1,136 @@ +# Codex host adapter i capability projection + +## TL;DR +Codex nie ma dziś wykonywalnego adaptera `evaluate gate → advisor/arbiter → runner → następna praca`; ma tylko instrukcję w TOML i smoke test obecności tekstu. +Minimalna naprawa wymaga hostowej pętli, która wywołuje natywnego subagenta, waliduje jego czteropolowy YAML, a po terminalnej decyzji uruchamia runner i bez kończenia tury dispatchuje trwały continuation target. +Shared `phase-continue.mjs` może pozostać granicą trwałego zapisu decyzji i transition fazy, ale nie może być jedynym dispatcherem: brak `next_phase` nie przesuwa kolejnego decision area. +Codex wolno oznaczyć jako `supported` dopiero po E2E uruchamiającym rzeczywisty host Codex, z deterministycznym fake advisorem/arbitrem i obserwowalnym kolejnym dispatch’em bez UI. + +## Key Decisions +- Umieścić host-specific orchestration w `platforms/codex-cli/`, a wspólny schema/evaluator/runner w `plugins/maister/`; `plugins/maister-codex/` pozostaje wyłącznie projekcją builda. +- Traktować wywołanie subagenta jako hostową prymitywę, nie próbować ukrywać go w `phase-continue.mjs`: skrypt Node nie ma API do przejęcia aktywnej tury Codex ani natywnego delegation tool. +- Wprowadzić jeden jawny continuation target: `same_phase_work_item` (kolejny problem/decision area) albo `next_phase`; terminalna decyzja bez targetu nie jest dowodem kontynuacji. +- Fake advisor i arbiter mają implementować dokładnie ten sam port co natywny Codex invoker oraz prowadzić call log; fixture wybiera agreement, disagreement i wynik arbitra bez udziału modelu. +- Nie zmieniać `declared_status: unsupported`, dopóki host-native target nie kończy się kodem `0` i nie obserwuje całego przepływu. + +## Open Questions / Risks +- Dokładna stabilna komenda Codex CLI do headless E2E musi zostać potwierdzona przy implementacji; jeśli runtime nie jest dostępny, target ma nadal zwracać `77`, a nie symulować sukces shared harness’em. +- Obecny gate engine jest normatywnym Markdowniem, nie biblioteką wykonywalną. Bez wydzielenia deterministycznego evaluatora część walidacji agreement/arbitration pozostaje zależna od poprawnego wykonania instrukcji przez głównego agenta. +- Aktywny stan używa `orchestrator.started_phase`, podczas gdy runner transition wymaga `orchestrator.current_phase`; adapter nie powinien wykonywać ad-hoc transformacji stanu, bo utworzyłby drugie źródło prawdy. +- Dokładnie-once dla dispatchu wymaga trwałego identyfikatora/cursora i idempotentnego odbiorcy. Sam fakt, że runner ponownie użył terminalnego gate, nie dowodzi braku ponownego uruchomienia kolejnego problemu. + +## 1. Stan obecny i miejsce zatrzymania + +### 1.1 Template opisuje zachowanie, ale niczego nie wykonuje + +`platforms/codex-cli/templates/advisor.toml:5-18` definiuje read-only rolę i czteropolowy YAML. Linie 10-15 twierdzą, że adapter wywoła tego samego advisora jako arbitra oraz wykona `phase_continue(selected_option)`, lecz jest to wyłącznie `developer_instructions`. + +`platforms/codex-cli/build.sh:135-151` tylko kopiuje TOML do wygenerowanego skilla `init`. Ten sam build transformuje prose skills na Codex vocabulary (`platforms/codex-cli/build.sh:44-90`) i generuje tekstowe utility skills (`:182-212`, `:236-275`), ale nie emituje executable gate adaptera, wrappera odpowiedzi ani continuation loop. Linie `:327-329` jedynie sprawdzają, że capability row i ścieżka E2E istnieją. + +`platforms/codex-cli/smoke-cli.sh:66-89` sprawdza obecność plików i fraz (`phase_continue(selected_option)`, role, denylist). Nie wywołuje advisora, arbitra, runnera ani kolejnej jednostki pracy. **Wniosek (high confidence):** faktyczny punkt zatrzymania leży w brakującej warstwie host adapter/loop, pomiędzy otrzymaniem rekomendacji a wykonaniem/ponownym wejściem w workflow. + +### 1.2 Runner kończy persistence/phase transition, nie hostową turę + +Runner przyjmuje tylko exact JSON z ośmioma polami wymaganymi i trzema opcjonalnymi (`plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs:18-35,209-244`). Po zapisie terminalnym generuje raporty i opcjonalnie zmienia fazę (`:741-795`). Stdout zwraca tylko `status`, key, selection i `continuation`; nie uruchamia skilla ani następnego decision area. + +Bez `next_phase` runner celowo pozostawia fazę bez zmian (`tests/phase-continue-contract.test.sh`, named test `test_no_transition_and_forward_transition_are_distinct`, linie 417-430). To jest poprawne dla decyzji wewnątrz fazy, lecz oznacza, że następny problem musi dispatchować hostowa pętla. Research prose mówi „record choice, move to next area” (`plugins/maister/skills/research/SKILL.md:340-355`), ale nie ma durable cursor ani executable consumer. **Wniosek (high confidence):** `phase_continue` jest persistence/phase-transition runnerem, nie pełnym dispatcherem następnej pracy. + +### 1.3 Codex capability prawidłowo pozostaje unsupported + +Target Codex jest pięcioliniowym placeholderem, który zawsze kończy się `77` (`platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh:1-5`). Capability matrix deklaruje `unsupported` (`plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml:16-18`). Make interpretuje tylko exit `0` jako `passed/supported`, `77` jako unavailable, a wszystko inne jako unsupported (`Makefile:29-42`); odrzuca shared runner test jako host-native evidence (`Makefile:44-52`). + +Normatywny kontrakt potwierdza ten próg: target musi istnieć, być executable i przejść do końca; skip, `77` i shared tests nie wystarczają (`gate-decision-engine.md:30-42`). **Wniosek (high confidence):** zmiana samego YAML byłaby fałszywą deklaracją i zostanie wykryta przez `validate-host-capabilities`. + +## 2. Minimalny wykonywalny model adaptera + +### 2.1 Podział na hostową prymitywę i deterministyczny rdzeń + +Minimalny interfejs powinien być jawny i testowalny: + +```text +CodexGateAdapter.evaluate_and_continue(request, ports) -> outcome + +request: + gate_context # exact ordered options + original recommendation + state_path + continuation_target # {kind: same_phase_work_item, cursor...} | {kind: next_phase, phase_id...} + report paths + +ports: + invoke_role(role, immutable_context) -> raw four-field YAML + run_phase_continue(exact_json) -> compact JSON + dispatch(target, dispatch_id) -> acknowledged + present_user_gate(...) # never called on valid fully_automatic path +``` + +Hostowa implementacja `invoke_role` używa natywnej delegacji Codex w tej samej turze. Advisor dostaje pełny read-only context; przy rozbieżności adapter zapisuje `arbiter_pending` i wykonuje jedną logiczną rolę arbiter, której retries pozostają próbami tego samego rekordu. Zgodność oznacza exact string equality pomiędzy `original_recommendation` i zwalidowanym `selected_option`; nie wolno fuzzy matching. + +Deterministyczny rdzeń powinien: + +1. odczytać canonical state i wykonać idempotency preflight; +2. zapisać `advisor_pending` oraz rozpoczęcie każdej próby przed `invoke_role`; +3. zwalidować dokładnie cztery klucze, option membership, confidence i escalation; +4. zakończyć advisorem przy agreement albo utworzyć jeden logical arbiter przy disagreement; +5. zbudować exact runner JSON dopiero dla `high|medium`, `escalate_to_user: false`, configurable/non-denylisted gate; +6. po sukcesie runnera kontynuować hostową pętlę do `dispatch(target, dispatch_id)` bez emitowania plain-text user question; +7. przy low confidence, exhaustion, invalid capability albo non-zero runner stopować/fail-closed. + +Normatywny algorytm już określa agreement i arbitration (`gate-decision-engine.md:266-300`), ale musi otrzymać executable realization. Najmniejsza bezpieczna struktura to wspólny evaluator pod `plugins/maister/skills/orchestrator-framework/bin/` plus cienkie Codex binding/loop pod `platforms/codex-cli/`; kopiowanie całego algorytmu do adaptera zwiększyłoby ryzyko driftu między hostami. + +### 2.2 Continuation target i brak końca tury + +Adapter nie może utożsamiać `runner exit 0` z zakończeniem pracy. Po stdout `status: decided|reused` powinien odczytać z canonical state trwały target: + +- `same_phase_work_item`: phase id, ordered collection id, next index/item id, `dispatch_id`; +- `next_phase`: source phase, target phase i `dispatch_id` (runner może wykonać status transition); +- `none`: legalne tylko dla decyzji, która semantycznie niczego nie kontynuuje; nie spełnia acceptance dla fully automatic workflow gate. + +Research convergence wymaga sekwencyjności, ponieważ późniejsze alternatywy zależą od wcześniejszych (`plugins/maister/skills/research/SKILL.md:340-350`). Dlatego host po zaakceptowaniu area N ma najpierw trwale zapisać choice/cursor, ponownie odczytać artefakt/state, a dopiero potem renderować i oceniać area N+1. Nie wolno pre-dispatchować wszystkich areas. + +### 2.3 Deterministyczny fake advisor/arbiter + +Fake powinien używać identycznej granicy co native role invoker: + +```text +fake-role --role advisor|arbiter +stdin: immutable gate/competition JSON +stdout: dokładnie czteropolowy YAML +side effect test-only: append {logical_gate_key, role, attempt, input_hash} to call log +``` + +Fixture mapuje `(scenario, role, attempt)` na: valid agreement, valid disagreement, arbiter-original, arbiter-advisor, timeout/malformed, low confidence lub escalation. Arbiter input assertion wymaga obu konkurencyjnych opcji i rationales; output może należeć tylko do tego dwuelementowego zbioru. Call log pozwala dowieść `advisor=1`, `logical_arbiter=1` niezależnie od liczby retry attempts oraz że resume nie wywołało zakończonej roli ponownie. + +Fake nie może zapisywać workflow state ani reports, zgodnie z read-only kontraktem (`platforms/codex-cli/templates/advisor.toml:6-18`; `plugins/maister/agents/advisor.md:12-23`). E2E nadal musi uruchamiać rzeczywisty Codex adapter/session; fake zastępuje tylko niedeterministyczną decyzję modelu. + +## 3. Build projection i proponowane źródła zmian + +Prawdopodobny minimalny zestaw canonical source files: + +- `plugins/maister/skills/orchestrator-framework/bin/gate-evaluate.mjs` — nowy wspólny executable evaluator lub równoważne rozszerzenie istniejącego rdzenia; +- `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` — canonical schema/continuation receipt i kompatybilność z durable target; +- `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` — zsynchronizowany kontrakt executable behavior; +- `plugins/maister/skills/research/SKILL.md` oraz analogiczne convergence call sites — jawny same-phase cursor i usunięcie założenia, że każda obowiązkowa bramka musi mieć UI call ID; +- `platforms/codex-cli/` nowy host binding/loop i deterministyczny test harness; +- `platforms/codex-cli/build.sh` — projekcja bindingu/harness-required runtime files do generated pluginu; +- `platforms/codex-cli/templates/advisor.toml` — pozostaje role profile, lecz odsyła do rzeczywistego adaptera zamiast tylko deklarować zachowanie; +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` — zastępuje placeholder; +- `tests/fixtures/` i contract tests — real state, agreement/arbitration/cursor/outbox fixtures; +- `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` — `supported` dopiero w ostatnim kroku. + +Build musi nadal wykonywać edycje wyłącznie w `plugins/maister/` i `platforms/`, następnie `make build`; generated `plugins/maister-codex/` służy do porównania reprodukowalności (`.maister/docs/standards/global/build-pipeline.md`). Obecny build usuwa i odtwarza cały target (`platforms/codex-cli/build.sh:15-16`), więc bez jawnej reguły copy nowy binding zniknie. + +## 4. Exact criteria dla `declared_status: supported` + +Codex można zadeklarować jako supported wyłącznie gdy wszystkie poniższe warunki są jednocześnie spełnione: + +1. Target z capability matrix jest executable i na dostępnej instalacji uruchamia rzeczywisty Codex host/entrypoint, nie tylko Node runner. +2. Agreement kończy się aktorem `advisor`, jednym terminalnym history recordem, raportem i realnym następnym dispatch’em bez user-question/UI. +3. Disagreement uruchamia dokładnie jednego logical arbitra; osobne fixtures dowodzą obu legalnych rozstrzygnięć. +4. E2E obserwuje oba target kinds: następny problem/decision area w tej samej fazie oraz następną fazę. +5. Resume po awarii report/transition/dispatch nie powtarza terminal history ani ukończonego dispatchu. +6. Denylista, low confidence, escalation, exhaustion i invalid output pozostają fail-closed. +7. Shared contract matrix przechodzi dla source i wszystkich generated runners, `make build` jest reprodukowalny, a `make validate-host-capabilities` projektuje `supported` z exit `0`. +8. Gdy Codex runtime jest niedostępny, test zwraca `77`, a deklaracja pozostaje `unsupported`; brak runtime nie może być zamaskowany fake-only sukcesem. + +**Confidence:** high dla diagnozy braku adaptera, build projection i capability threshold; medium dla dokładnego kształtu nowego pliku/bindingu, bo stabilny headless Codex invocation nie istnieje jeszcze w repo i wymaga implementacyjnego spike’a. + diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/04-verification-safety.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/04-verification-safety.md new file mode 100644 index 00000000..3a531c47 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/findings/04-verification-safety.md @@ -0,0 +1,171 @@ +# Weryfikacja, resume i granice bezpieczeństwa + +## TL;DR +Istniejące testy dobrze dowodzą strict payload, terminal persistence, report recovery, phase transition i denylist w shared runnerze, ale testy gate engine są głównie asercjami na prose/fixtures, nie wykonaniem advisor/arbitration. +Brakuje testu, który uruchamia Codex, obserwuje brak user UI i potwierdza realny dispatch kolejnego problemu; obecny target zawsze zwraca `77`. +Macierz akceptacji musi osobno pokryć agreement, oba wyniki arbitra, same-phase cursor, next phase, retry/resume oraz transactional failure. +Bezpieczeństwo wymaga byte-exact non-mutation dla odrzuceń przed commit oraz trwałego, idempotentnego recovery dla awarii po terminalnym commit; tych dwóch klas nie wolno mieszać. + +## Key Decisions +- Rozdzielić testy na executable evaluator/unit, runner contract, adapter integration i prawdziwy Codex host-E2E; tylko ostatni poziom jest dowodem capability. +- Używać deterministic fake role invoker z call logiem oraz deterministic fake dispatcher z `dispatch_id`, zamiast rzeczywistego modelu. +- Dla same-phase continuation dodać durable cursor/dispatch receipt; asercja tylko na `gate_history` nie dowodzi przejścia do następnego problemu. +- Dla invalid input/changed selection/invalid transition wymagać byte-exact state, reports, modes i directory topology; dla report/dispatch failure wymagać zachowania już zatwierdzonego terminal recordu i dokładnie-jednego recovery. +- Denylisted gate ma dowodzić braku wywołania advisora, arbitra, runner continuation i dispatchu; nie wystarczy sam non-zero exit. + +## Open Questions / Risks +- Exactly-once zewnętrzny dispatch nie jest osiągalny samym zapisem state; odbiorca musi deduplikować `dispatch_id`. Test powinien deklarować gwarancję jako „exactly one logical dispatch/effect”, nie zakładać magicznego exactly-once transportu. +- Obecny runner zapisuje terminal record przed raportami. Report failure celowo mutuje state i jest naprawiany na resume; zastosowanie byte-exact non-mutation do tej ścieżki przeczyłoby istniejącemu recovery contractowi. +- `tests/gate-decision-engine.test.sh` nazywa przypadek „fully automatic continuation is executable”, ale sprawdza wyłącznie frazy w Markdownzie; nazwa może dawać fałszywe poczucie pokrycia. +- Real state zawiera bogatsze pola i `started_phase`, których obecne runner fixtures nie reprezentują; nowe testy muszą używać stanów wygenerowanych przez workflow, nie ręcznie zawężonego YAML. + +## 1. Baseline z 2026-07-13 + +| Polecenie | Exit | Wynik | Co faktycznie dowodzi | +|---|---:|---|---| +| `bash tests/gate-decision-engine.test.sh` | 0 | 28 passed | Spójność normatywnego prose, katalog fixtures, wiring i syntax; nie wykonuje modelowego evaluator flow. | +| `bash tests/fully-automatic-phase-continue.test.sh` | 0 | PASS | Terminal decision, raport, phase-1 → phase-2, reuse i denylist dla shared runnera. | +| `bash tests/phase-continue-contract.test.sh` | 0 | 21 passed | Exact transport/schema, canonical-state validation, deterministic reports, non-mutation, recovery i phase transition dla source runnera. | +| `bash platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` | 77 | UNAVAILABLE | Brak deterministycznego host-native Codex harnessu. | +| `make -s print-host-capabilities` | 0 | Codex declared/projected unsupported | Capability projection prawidłowo odpowiada niedostępnemu targetowi. | + +Baseline był read-only względem źródeł. Exit `77` jest oczekiwanym fail-closed dowodem braku capability, nie niepowodzeniem shared runnera. + +## 2. Co pokrywają istniejące testy + +### 2.1 Shared runner: mocne dowody + +`tests/fully-automatic-phase-continue.test.sh:32-46` wykonuje runner, sprawdza stdout, terminal state, raport, transition oraz reuse. Linie `48-51` potwierdzają blokadę denylisted gate. + +`tests/phase-continue-contract.test.sh` ma zachowaniowe przypadki: + +- `test_accepts_canonical_state_fixtures` (`:259-268`) — akceptacja dwóch wąskich fixtures; +- `test_normal_decision_writes_deterministic_reports` (`:365-374`) — deterministyczny MD/HTML i escaping; +- `test_denylist_stays_blocked_on_retry` (`:376-390`) — blocked persistence i unchanged retry; +- `test_changed_selection_is_rejected_without_mutation` (`:392-400`) — byte-exact state/report preservation; +- `test_no_transition_and_forward_transition_are_distinct` (`:417-430`) — decyzja bez `next_phase` vs transition; +- `test_report_failure_leaves_terminal_record_for_regeneration` (`:432-445`) — terminal commit przetrwał, retry regeneruje raport; +- `test_transition_failure_recovers_exactly_once` (`:447-463`) — retry transition i kolejny idempotentny reuse. + +Helpery `snapshot_files`, `state_and_reports_unchanged` i `state_reports_and_directories_unchanged` (`:136-156`) realizują standard byte-exact rejection. Payload generator wprost odrzuca low confidence i obcego aktora (`:66-96`), ale nie dowodzi, kto i jak podjął decyzję przed wejściem do runnera. + +Runner sam gwarantuje terminal write → reports → optional phase transition (`phase-continue.mjs:784-794`), a resume najpierw rozpoznaje terminal record, regeneruje raporty i aplikuje brakujący transition (`:741-762`). To jest dobry kontrakt durability dla faz. + +### 2.2 Gate engine: deklaratywne, nie executable + +`tests/gate-decision-engine.test.sh:65-110` odczytuje katalog 19 fixtures przy pomocy `awk` i potwierdza oczekiwane label/status/actor. Testy agreement/arbitration (`:173-180`), resume (`:197-203`) i persistence ordering (`:205-213`) używają `contains`/`in_order` na Markdownzie. Nie uruchamiają fake advisora ani state machine. + +Szczególnie `test_fully_automatic_continuation_is_executable` (`:259-264`) sprawdza obecność fraz, nie execution. **Luka (high confidence):** agreement, oba rozstrzygnięcia arbitra, retry slots i resume pending są dziś specyfikacją, nie działającym testem algorytmu. + +### 2.3 Host Codex: brak dowodu + +`platforms/codex-cli/smoke-cli.sh:73-87` sprawdza template i prose. `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh:4-5` zawsze zwraca `77`. Nie ma asercji na advisor calls, arbiter calls, brak UI, runner invocation ani next dispatch. + +Makefile celowo nie uznaje shared runner tests za native evidence (`Makefile:50`) i projektuje support tylko z exit `0` targetu (`Makefile:35-41`). To zabezpieczenie należy zachować. + +## 3. Docelowa macierz weryfikacji + +| Scenariusz | Poziom | Setup / stimulus | Pozytywne asercje | Negatywne / safety asercje | +|---|---|---|---|---| +| Advisor zgadza się | evaluator contract + Codex E2E | original=A, fake advisor=A/high/no escalation | actor=advisor; jeden terminal record; reports; cursor/transition; dispatch następnej pracy | arbiter=0; user gate/UI=0; brak duplicate history/dispatch | +| Arbiter wybiera original | evaluator contract + adapter integration | original=A, advisor=B, arbiter=A/high | jeden logical arbiter; terminal actor=arbiter, selected=A; continuation | brak drugiego arbitra; brak powrotu do advisora; UI=0 | +| Arbiter wybiera advisor | evaluator contract + adapter integration | original=A, advisor=B, arbiter=B/high | analogicznie, selected=B | brak trzeciej opcji; UI=0 | +| Kolejny decision area/problem | workflow integration + Codex E2E | area N accepted, durable collection z N+1 | choice N zapisana; cursor=N+1; `dispatch_id` ack; N+1 rzeczywiście rozpoczęty w tej samej turze | faza nie kończy się przedwcześnie; N+1 nie dispatchowany dwa razy; brak user click | +| Następna faza | runner contract + Codex E2E | phase-exit z `next_phase` | source completed; target in_progress; current_phase target; target handler rozpoczęty | brak transition przed reports; brak backward/self transition | +| Advisor transient retries | evaluator unit | timeout/malformed na próbach, potem valid | każda próba i backoff trwale zapisana; final actor advisor | liczba wywołań ≤ limit; nie tworzy arbitra bez disagreement | +| Arbiter transient retries | evaluator unit | disagreement, arbiter timeout potem valid | jeden logical arbiter record, wiele attempt records | advisor nie jest ponawiany; brak drugiego logical arbitra | +| Retry exhaustion | evaluator + adapter | wszystkie próby failure | interactive → user_pending; noninteractive → terminal blocked | runner/dispatch=0; automatic approval=0 | +| Resume `advisor_pending` | evaluator resume | interrupted started attempt | attempt zamknięty jako interruption i zużywa slot; resume następnej próby | nie restartuje completed attempt; nie zeruje backoff | +| Resume `arbiter_pending` | evaluator resume | persisted disagreement + pending arbiter | resume tego samego logical arbiter id | advisor=0 po resume; nowy logical arbiter=0 | +| Report failure | runner contract + adapter integration | inject report failure po terminal write | terminal record durable; phase/cursor nieprzesunięty; retry generuje raport i kontynuuje raz | stary raport pozostaje nieuszkodzony; duplicate history/dispatch=0 | +| Phase transition failure | runner contract | inject transition failure | terminal+reports durable; retry aplikuje transition raz | brak duplicate history; brak partially active dwóch faz | +| Same-phase dispatch failure | adapter integration | inject failure przed/po receiver ack | durable dispatch intent/receipt pozwala resume; ten sam `dispatch_id` | nie tworzy kolejnego gate; efekt logiczny dokładnie raz | +| Denylist | evaluator + runner + Codex E2E | gate_type z hard denylist | user_pending/manual albo blocked noninteractive | advisor=0; arbiter=0; automatic runner=0; dispatch=0 | +| Low confidence / escalation | evaluator | valid option, low lub escalate=true | manual/user_pending albo blocked | nie wolno obniżyć do medium; runner/dispatch=0 | +| Invalid/extra YAML, invalid option | evaluator unit | malformed fake output | retry lub terminal fallback zgodnie z limitem | state/report/source files unchanged przed pending/attempt commit poza auditem błędu; żadnego selection commit | +| Changed terminal selection | runner contract | ten sam idempotency key, inna selection | non-zero | byte-exact state, reports, modes i directories unchanged | +| Unsupported capability | adapter + capability test | phase_continuation_supported=false | manual/user_pending albo blocked | nie wywołuje automatic runner/dispatch; declared supported niemożliwe | +| Build projection | build test | clean `make build-codex` dwa razy | adapter/runtime/test references w generated target; drugi build no diff | brak bezpośredniej edycji generated tree; brak stale contract | + +## 4. Fixtures i obserwowalność + +Minimalny nowy katalog fixture powinien zawierać nie tylko oczekiwany actor/status, lecz pełne executable inputs i call expectations: + +- `advisor-agrees.yml`; +- `arbiter-selects-original.yml`; +- `arbiter-selects-advisor.yml`; +- `advisor-retry-then-valid.yml`, `advisor-exhausted.yml`; +- `arbiter-retry-then-valid.yml`, `resume-advisor-pending.yml`, `resume-arbiter-pending.yml`; +- `same-phase-next-item.yml`, `next-phase.yml`; +- `denylisted.yml`, `low-confidence.yml`, `escalated.yml`; +- real workflow states: empty history, rich advisor terminal history, rich arbiter terminal history, pending dispatch, acknowledged dispatch. + +Każdy fixture powinien definiować: + +```yaml +role_script: # response/error per role + attempt +expected_calls: # advisor attempts, one logical arbiter, UI count +expected_terminal_record: # complete normalized audit +expected_continuation: # target + dispatch_id + final receipt +expected_files: # content hashes/modes/topology where relevant +``` + +Call log musi rozróżniać `logical_arbiter_id` od `attempt_no`: dwa retry to dwa calls, ale jeden logical arbiter. UI spy powinien failować test natychmiast po każdym `present_user_gate` na pozytywnej fully-automatic ścieżce. Dispatcher spy zapisuje próbę przed efektem i acknowledgement po efekcie; receiver deduplikuje po `dispatch_id`. + +## 5. Transactional safety i kolejność commitów + +Docelowa kolejność: + +```text +pending/attempt state +→ validated terminal gate record (atomic) +→ dashboard/report projection (atomic per file) +→ continuation intent + cursor/phase transition (atomic canonical state) +→ dispatch(target, dispatch_id) +→ durable acknowledgement/completed receipt +``` + +Granice asercji: + +1. **Przed pierwszym dozwolonym commit** — malformed payload/state, invalid option, changed selection, invalid transition: non-zero oraz byte-exact non-mutation wszystkich state/report files, modes i topology. Obecne testy dają dobry wzorzec (`tests/phase-continue-contract.test.sh:136-156,226-256,392-400`). +2. **Po terminal commit, przed continuation** — report failure: terminal record ma pozostać durable, stare raporty nieuszkodzone, phase/cursor nieprzesunięty. Resume nie dopisuje historii, tylko regeneruje projekcje i kontynuuje (`test_report_failure_leaves_terminal_record_for_regeneration`). +3. **Po continuation intent, przed ack** — dispatch failure: resume ponawia ten sam `dispatch_id`; idempotent receiver nie wykonuje drugi raz efektu. Bez receipt test nie może stwierdzić, czy efekt zaszedł przed przerwaniem. +4. **Denylist/low/escalation/exhaustion** — audyt pending/attempt/blocked może być legalną mutacją, ale selection, phase/cursor i dispatch pozostają niezmienione. + +Atomic write runnera używa temp directory, `fsync` i rename (`phase-continue.mjs:597-616`). To chroni pojedynczy plik, nie stan+raporty+dispatch jako jedną transakcję; dlatego recovery state machine i idempotency są częścią poprawności, a nie dodatkiem. + +## 6. Rozdział testów szybkie vs capability E2E + +### Szybkie, obowiązkowe w każdym validate + +- executable evaluator fixtures: agreement, arbitration, retry, resume, denylist; +- shared runner contract dla source i generated variants; +- adapter integration z fake role invoker i fake dispatcher; +- build/smoke assertions na obecność wykonywalnych artefaktów, nie tylko prose; +- failure injection i byte-exact/recovery assertions. + +### Host-native Codex E2E — jedyny capability proof + +Target `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` powinien: + +1. wykryć actual Codex runtime; przy braku zwrócić `77`; +2. zbudować/zainstalować świeży plugin lub użyć jawnej izolowanej testowej instalacji; +3. uruchomić rzeczywisty workflow/adapter Codex z fake role portem; +4. przeprowadzić co najmniej agreement + arbiter disagreement oraz same-phase + next-phase continuation; +5. obserwować canonical state, reports, role call log, UI spy i dispatch receipts; +6. sprawdzić resume/re-run bez duplicate history/dispatch; +7. zakończyć `0` tylko po wszystkich asercjach. + +Nie wystarczy uruchomić `phase-continue.mjs` bez Codex hosta ani sprawdzić tekstu w generated SKILL/TOML. Ten wymóg jest już egzekwowany przez `Makefile:44-52` i `gate-decision-engine.md:36-42`. + +## 7. Prawdopodobne pliki testowe do zmiany + +- `tests/gate-decision-engine.test.sh` — zastąpić/uzupełnić prose-only przypadki executable evaluator tests; +- `tests/phase-continue-contract.test.sh` i `tests/fixtures/phase-continue/` — rich real-state schema, cursor/receipt i nowe failure paths; +- nowy katalog `tests/fixtures/gate-evaluator/` oraz executable evaluator suite; +- nowy adapter integration test pod `platforms/codex-cli/tests/`; +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` — real host test zamiast exit 77; +- `platforms/codex-cli/smoke-cli.sh` — sprawdzenie executable binding/build projection; +- `Makefile` — wiring szybkich testów bez osłabienia osobnej capability projection. + +**Confidence:** high dla luk istniejącego pokrycia, baseline i wymaganych scenariuszy safety; medium dla dokładnego mechanizmu actual Codex E2E/fake injection, ponieważ repo nie zawiera jeszcze stabilnego host harnessu. diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/synthesis.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/synthesis.md new file mode 100644 index 00000000..5467c788 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/analysis/synthesis.md @@ -0,0 +1,135 @@ +# Synteza: naprawa automatycznej kontynuacji Codex + +## TL;DR + +Naprawa wymaga wykonywalnego evaluatora bramek, cienkiego adaptera Codex oraz trwałego kursora pracy; sama zmiana `phase-continue.mjs` nie wystarczy. +Zgodność rekomendacji kończy gate aktorem `advisor`; rozbieżność tworzy dokładnie jeden logiczny rekord `arbiter`, którego kolejne wywołania są retry. +Terminalny wynik musi zostać zapisany przed raportami i continuation, a sukces adaptera musi oddać sterowanie pętli workflow bez kończenia tury. +Runner wykonuje commit i opcjonalny transition fazy — nie jest dispatcherem kolejnego problemu ani fazy. + +## Key Decisions + +- Ustanowić jeden wykonywalny evaluator jako właściciela agreement, arbitration, retry, denylisty i terminalnego rekordu. +- Użyć `orchestrator.current_phase` jako kanonicznego kursora fazy oraz trwałego `work_item_id`/`dispatch_id` dla pracy wewnątrz fazy. +- Rozdzielić odpowiedzialności: evaluator wybiera, runner utrwala, adapter Codex wykonuje transport, workflow loop stosuje efekt i dispatchuje następną pracę. +- Nie zmieniać capability Codex na `supported`, dopóki rzeczywisty host-native E2E nie potwierdzi braku UI i realnego następnego dispatchu. + +## Open Questions / Risks + +- Stabilna, headless komenda Codex i port wstrzykiwania fake roli wymagają krótkiego spike'a implementacyjnego. +- Finalny kształt pełnego rekordu `gate_history` i continuation receipt musi być jeden dla dokumentacji, evaluatora, runnera i fixtures. +- Fizyczne exactly-once wywołania hosta nie jest gwarantowalne bez transakcyjnego API; wymagany jest exactly-once logiczny efekt przez trwały `dispatch_id` i deduplikację. + +## 1. Triangulowany root cause + +Wszystkie cztery strumienie badania wskazują ten sam łańcuch: + +1. Kanoniczne Markdowny opisują prawidłowy algorytm agreement/disagreement, lecz nie ma wykonywalnego evaluatora, który go egzekwuje. Test `tests/gate-decision-engine.test.sh` głównie sprawdza tekst i katalog fixtures, nie uruchamia state machine modeli. +2. Codex posiada read-only profil roli w `platforms/codex-cli/templates/advisor.toml`, ale nie ma kodu mapującego odpowiedź roli na terminalny wynik, runner i dalszy dispatch. Smoke test sprawdza frazę, nie zachowanie. +3. `phase-continue.mjs` przyjmuje już wybraną opcję. Trwale zapisuje wąski terminalny rekord, generuje raporty i opcjonalnie zmienia status fazy. Potem wypisuje JSON i proces się kończy. +4. Bez `next_phase` runner nie przesuwa niczego; z `next_phase` przesuwa `current_phase`, ale nie uruchamia handlera nowej fazy. Nie ma kursora kolejnego decision area ani konsumenta stdout, który wraca do workflow loop. +5. Obecne self-checki wejścia do fazy wymagają historycznego call ID pytania użytkownika, więc mogą wymusić UI nawet po poprawnej decyzji automatycznej. +6. Realny state używa `started_phase` i bogatego audytu, podczas gdy runner transition wymaga `current_phase` i odrzuca dodatkowe pola historii. + +**Synteza — confidence: high.** Pierwotna diagnoza „brak adaptera Codex” jest poprawna, ale niewystarczająca: po adapterze potrzebny jest jeszcze jawny zwrot sterowania do pętli workflow i trwały next-work cursor. + +## 2. Docelowa maszyna decyzji + +### Agreement + +Dla gate'u `fully_automatic`, który nie jest denylisted i ma wspieraną capability: + +1. Trwale zapisz `advisor_pending` i próbę `started` przed wywołaniem roli. +2. Zwaliduj exact czteropolowy output, membership opcji, `confidence: high|medium` i `escalate_to_user: false`. +3. Jeśli `advisor.selected_option === original_recommendation` (exact string), zapisz jeden terminalny rekord `decided`, `final_actor: advisor`. +4. Nie wywołuj arbitra i nie pokazuj user gate. + +### Disagreement + +1. Trwale zapisz poprawny wynik advisora i przejdź do `arbiter_pending`. +2. Utwórz dokładnie jedną logiczną mapę arbitra z jednym `logical_arbiter_id`. +3. Każdy timeout/malformed output dopisuje próbę do `arbiter.attempts[]`; nie tworzy drugiego arbitra i nie wraca do advisora. +4. Arbiter może wybrać wyłącznie rekomendację pierwotną albo advisora. +5. Poprawny `high|medium`, bez eskalacji, kończy gate aktorem `arbiter`. + +### Fail-closed + +Denylista omija modele i automatyczny runner. Low confidence, escalation, brak capability, retry exhaustion, invalid output po wyczerpaniu prób, błąd terminalnego zapisu lub niepoprawna continuation zatrzymują automatyzację: interaktywnie do `user_pending`, bez interakcji do `blocked`. Żaden z tych przypadków nie może przesunąć fazy ani kursora pracy. + +**Confidence: high.** Algorytm wynika bezpośrednio z `gate-decision-engine.md:266-300` i jest zgodny z wymaganiem użytkownika. + +## 3. Jeden kontrakt stanu i kontynuacji + +Potrzebny jest jeden pełny envelope `gate_history`, a nie uboższy rekord rekonstruowany przez runner. Musi zawierać tożsamość gate'u, uporządkowane opcje, pierwotną rekomendację, policy/safety, pełne wyniki i próby roli, terminalnego aktora oraz continuation intent/receipt. + +Kanoniczne inwarianty: + +- `orchestrator.current_phase` wskazuje dokładnie jedną fazę `in_progress` w `phases[]`; +- jeden idempotency key odpowiada jednemu rekordowi gate, aktualizowanemu pending → terminal, nigdy duplikowanemu; +- `advisor` i `arbiter` są pojedynczymi mapami, a retry są wpisami w `attempts[]`; +- same-phase praca ma stabilny `work_item_id`, `source_gate_key`, `dispatch_id` i status `ready|in_progress|completed|blocked`; +- continuation ma target `same_phase_work_item` albo `next_phase` i receipt `pending|applied|blocked`; +- raporty i dashboard są projekcjami canonical state, nigdy źródłem resume. + +Kolejność trwałości: + +```text +pending + attempt started +→ validated terminal gate record +→ reports/dashboard from persisted state +→ gate effect + cursor/phase transition intent +→ dispatch(target, dispatch_id) +→ durable acknowledgement / applied receipt +``` + +Awaria raportu pozostawia terminalny rekord do regeneracji. Awaria dispatchu wznawia ten sam `dispatch_id`. Odrzucone wejście przed legalnym commitem pozostawia state, raporty, tryby i topologię katalogów byte-exact bez zmian. + +**Confidence: high** dla własności i kolejności; **medium-high** dla finalnej serializacji continuation envelope. + +## 4. Ownership i continuation + +| Warstwa | Własność | Granica | +|---|---|---| +| Evaluator | policy, denylist, advisor/arbiter state machine, retry, pełny terminalny record | Nie dispatchuje domenowej pracy | +| Runner | strict preflight, idempotentny commit, raporty, opcjonalny forward phase transition | Nie zna decision areas ani hostowych narzędzi | +| Adapter Codex | native role invocation, exact transport do runnera, walidacja stdout, zwrot `continue|user_gate|blocked` | Nie utrzymuje własnego state machine ani routingu domenowego | +| Workflow loop | apply selected option, trwały work-item cursor, wyliczenie następnego targetu, natychmiastowy dispatch | Nie implementuje ponownie safety/evaluatora | + +Kluczowy kontrakt: **sukces adaptera nie kończy assistant turn**. Adapter zwraca `continue`, workflow ponownie czyta stan, aplikuje wybór, ustawia następny target i wykonuje go natychmiast. + +- Same-phase: area N zostaje `completed`; dopiero wtedy workflow ponownie oblicza area N+1 i dispatchuje je z trwałym `dispatch_id`. +- Next-phase: runner atomowo ustawia source `completed`, target `in_progress`, `current_phase=target`; potem workflow loop uruchamia body nowej fazy. Sam commit runnera nie jest dispatch'em. + +**Confidence: high.** `phase-continue.mjs:741-800` kończy proces po stdout, a call sites research/product-design zawierają domenową wiedzę potrzebną do kolejnego problemu. + +## 5. Konwergencja findings i konsekwencje wdrożeniowe + +Nie ma konfliktu między findings: + +- Finding 01 wymaga pełnego schema i wykonywalnego evaluatora. +- Finding 02 pokazuje, że commit i dispatch to dwie operacje oraz definiuje cursor. +- Finding 03 lokuje host binding w `platforms/codex-cli/` i utrzymuje generated tree jako wynik builda. +- Finding 04 definiuje cztery poziomy dowodu i próg capability. + +Najmniejszy bezpieczny tracer bullet to: executable evaluator fixture agreement → pełny terminalny state → runner/report → same-phase cursor → fake dispatcher ack → ten sam loop uruchamia drugi item. Dopiero potem dodać arbiter, phase transition i prawdziwy Codex host E2E. + +## 6. Główne ryzyka + +1. **Podwójny writer historii:** evaluator i runner nie mogą oba syntetyzować rekordów; runner powinien konsumować i weryfikować wcześniej utrwalony terminalny rekord. +2. **Fałszywe exactly-once:** używać terminu „jeden logiczny dispatch/effect”; fizyczne retry jest dopuszczalne z tym samym `dispatch_id`. +3. **Generated drift:** zmiany tylko w `plugins/maister/` i `platforms/`, potem `make build`; nigdy bezpośrednio w `plugins/maister-codex/`. +4. **Przedwczesny capability flip:** wspólny runner i fake-only integration nie są host-native dowodem. +5. **Self-check regresja:** brak UI call ID nie może oznaczać pominiętej bramki, jeśli istnieje terminalny automatyczny rekord i poprawna continuation receipt. +6. **Backward routing:** product-design refinement do wcześniejszej fazy wymaga osobnego reset protocol; nie należy osłabiać runnera, który dziś akceptuje tylko forward pending transition. + +## 7. Źródła i poziom pewności + +| Wniosek | Główne dowody | Confidence | +|---|---|---| +| Brak wykonywalnego adaptera Codex | `platforms/codex-cli/templates/advisor.toml`, `build.sh`, `smoke-cli.sh`, placeholder E2E | High | +| Runner nie jest dispatcherem | `phase-continue.mjs:741-800`, `test_no_transition_and_forward_transition_are_distinct` | High | +| Agreement/arbitration nie są executable-tested | `tests/gate-decision-engine.test.sh` | High | +| Potrzebny pełny schema i `current_phase` | gate engine contract, real task state, runner preflight | High | +| Potrzebny durable same-phase cursor | research/product-design sequential loops, brak pola w payloadzie runnera | High | +| Finalny kształt host bindingu | brak istniejącego headless harnessu | Medium | + diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/dashboard-data.js b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/dashboard-data.js new file mode 100644 index 00000000..21024fe9 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/dashboard-data.js @@ -0,0 +1,35 @@ +window.MAISTER_DATA = { + generated: "2026-07-13T17:45:47Z", + task: { + title: "Naprawa automatycznej kontynuacji Codex", + type: "research", + status: "completed", + description: "Ustalić naprawę agreement → advisor, disagreement → arbiter oraz automatycznego przejścia do kolejnego problemu bez UI.", + path: ".maister/tasks/research/2026-07-13-fix-codex-auto-continuation", + current_activity: null + }, + characteristics: { research_type: "technical" }, + phases: [ + { id: "phase-1", name: "Research foundation", icon_hint: "analysis", status: "completed", started: "2026-07-13T16:29:57Z", completed: "2026-07-13T16:49:07Z", skip_reason: null, summary: "High-confidence fix: executable evaluator, canonical rich state, durable runner commit, Codex adapter returning continue, and workflow-owned next-work dispatch.", decisions: [{ decision: "Agreement terminates with advisor; disagreement uses one logical arbiter", rationale: "This is the normative safe fully_automatic state machine." }, { decision: "Separate runner commit from workflow dispatch", rationale: "Runner stdout/phase transition does not execute the next problem or phase body." }, { decision: "Keep Codex unsupported until native E2E passes", rationale: "Only the native test can prove no UI and actual same-turn continuation." }], risks: ["The exact headless Codex binding shape still needs an implementation spike.", "Logical exactly-once requires stable dispatch_id and receiver deduplication."], artifacts: [{ path: "planning/research-brief.md", label: "Research brief", html: null }, { path: "planning/research-plan.md", label: "Research plan", html: null }, { path: "planning/sources.md", label: "Sources", html: null }, { path: "analysis/findings/01-gate-state-contract.md", label: "Gate and state contract", html: null }, { path: "analysis/findings/02-continuation-dispatch.md", label: "Continuation dispatch", html: null }, { path: "analysis/findings/03-codex-host-adapter.md", label: "Codex host adapter", html: null }, { path: "analysis/findings/04-verification-safety.md", label: "Verification and safety", html: null }, { path: "analysis/synthesis.md", label: "Research synthesis", html: null }, { path: "outputs/research-report.md", label: "Research report", html: "outputs/research-report.html" }], gate: { question: "Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation?", answer: "Continue to brainstorming evaluation" } }, + { id: "phase-2", name: "Evaluate brainstorming value", icon_hint: "plan", status: "completed", started: "2026-07-13T16:49:07Z", completed: "2026-07-13T16:56:55Z", skip_reason: null, summary: "Brainstorming and high-level design are both enabled.", decisions: [{ decision: "Enable brainstorming", rationale: "The repair contains multiple coupled implementation seams and trade-offs." }, { decision: "Enable high-level design", rationale: "The solution spans canonical state, evaluator, runner, Codex adapter, and workflow loop boundaries." }], risks: [], artifacts: [{ path: "outputs/decision-summary.md", label: "Decision summary", html: "outputs/decision-summary.html" }], gate: { question: "The fix requires coordinated state-schema, evaluator, runner, Codex adapter, and workflow-loop decisions, so high-level design is valuable. Would you like to generate a high-level design?", answer: "Yes, generate design" } }, + { id: "phase-3", name: "Generate solution alternatives", icon_hint: "spec", status: "completed", started: "2026-07-13T16:56:55Z", completed: "2026-07-13T17:05:41Z", skip_reason: null, summary: "Sixteen alternatives across four decision areas; recommended package A3+B1+C1+D1.", decisions: [{ decision: "A3 — shared executable evaluator", rationale: "Executable and portable gate state machine with host role ports." }, { decision: "B1 — evaluator owns the rich gate record", rationale: "Preserves complete provenance before runner projections and transition." }, { decision: "C1 — workflow-owned durable outbox", rationale: "Supports dependent same-phase work items and logical exactly-once dispatch." }, { decision: "D1 — thin Codex native binding", rationale: "Keeps the active turn alive without duplicating state or routing logic." }], risks: ["The exact active-turn/headless Codex hook needs a spike.", "Concurrent YAML writers require revision/CAS or locking."], artifacts: [{ path: "outputs/solution-exploration.md", label: "Solution exploration", html: "outputs/solution-exploration.html" }], gate: { question: "Continue to solution convergence?", answer: "Continue to solution convergence" } }, + { id: "phase-4", name: "Evaluate brainstorming alternatives", icon_hint: "plan", status: "completed", started: "2026-07-13T17:05:41Z", completed: "2026-07-13T17:27:26Z", skip_reason: null, summary: "All convergence areas resolved with the coherent package A3+B1+C1+D1.", decisions: [{ decision: "A3 — shared executable evaluator with host ports", rationale: "Makes agreement, arbitration, retry, and resume deterministic without absorbing domain routing." }, { decision: "B1 — evaluator owns the rich terminal record", rationale: "The state-machine owner preserves complete provenance before runner effects." }, { decision: "C1 — workflow-owned durable outbox/receipt", rationale: "Stable work items and dispatch_id preserve dependent ordering and logical exactly-once resume." }, { decision: "D1 — thin Codex host-native binding", rationale: "Keeps the active turn alive while shared components remain canonical." }], risks: ["The exact active-turn/headless Codex hook still needs an implementation spike."], artifacts: [{ path: "outputs/solution-exploration.md", label: "Solution exploration", html: "outputs/solution-exploration.html" }], gate: { question: "Brainstorming complete. Continue to high-level design?", answer: "Continue to high-level design" } }, + { id: "phase-5", name: "Design high-level architecture", icon_hint: "spec", status: "completed", started: "2026-07-13T17:27:26Z", completed: "2026-07-13T17:43:21Z", skip_reason: null, summary: "Executable state machine plus ports-and-adapters design complete with 8 runtime components and 8 accepted ADRs.", decisions: [{ decision: "Shared executable gate evaluator", rationale: "Deterministic and portable agreement/arbitration state machine." }, { decision: "Evaluator-owned rich record; runner verifies", rationale: "Full provenance remains durable before continuation effects." }, { decision: "Workflow-owned durable outbox/receipt", rationale: "Stable work items and dispatch_id support logical exactly-once resume." }, { decision: "Thin Codex binding", rationale: "Returns continue to the active workflow loop without duplicating canonical logic." }], risks: ["Codex active-turn/headless hook requires an implementation spike.", "Schema v2 migration and dispatch deduplication require strict fixtures."], artifacts: [{ path: "outputs/high-level-design.md", label: "High-level design", html: "outputs/high-level-design.html" }, { path: "outputs/decision-log.md", label: "Decision log", html: "outputs/decision-log.html" }], gate: { question: "Design complete. Continue to output generation?", answer: "Continue to output generation" } }, + { id: "phase-6", name: "Summarize research and suggest next steps", icon_hint: "done", status: "completed", started: "2026-07-13T17:43:21Z", completed: "2026-07-13T17:45:47Z", skip_reason: null, summary: "All outputs and gate decisions are summarized; final handoff was explicitly approved by the user.", decisions: [{ decision: "Complete research workflow", rationale: "Research, convergence, high-level design, and final audit are complete." }], risks: ["Codex capability remains unsupported until real host-native E2E passes."], artifacts: [{ path: "outputs/decision-summary.md", label: "Decision summary", html: "outputs/decision-summary.html" }], gate: { question: "Research workflow complete. Complete workflow?", answer: "Complete workflow" } } + ], + verification: { status: null, issues: [], fixes: [], reverify_count: 0 }, + gate_history: [ + { idempotency_key: "sha256:8dc80ac772693c815f0dfac96f7baa45a3cded3e406f16c6f5a42756f1e157d4", phase_id: "phase-1", gate_type: "phase-1-exit", question: "Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation?", options: ["Continue to brainstorming evaluation", "Pause workflow"], status: "decided", selected_option: "Continue to brainstorming evaluation", final_actor: "user", rationale: "User confirmed continuation after reviewing the completed research report." }, + { idempotency_key: "sha256:947722f8e62401e5336692e2111b5e96368af8bed9af2b88b6901de279abeef5", phase_id: "phase-2", gate_type: "optional-phase-selection", question: "Multiple viable implementation seams and unresolved trade-offs make brainstorming valuable. Would you like to explore solution alternatives?", options: ["Yes, explore alternatives", "No, skip brainstorming"], status: "decided", selected_option: "Yes, explore alternatives", final_actor: "user", rationale: "User accepted the recommendation to explore alternatives." }, + { idempotency_key: "sha256:9370fe762f9aac3a82681193f9b4edf42ab09841dc696b521f77705a0ebc4549", phase_id: "phase-2", gate_type: "optional-phase-selection", question: "The fix requires coordinated state-schema, evaluator, runner, Codex adapter, and workflow-loop decisions, so high-level design is valuable. Would you like to generate a high-level design?", options: ["Yes, generate design", "No, skip design"], status: "decided", selected_option: "Yes, generate design", final_actor: "user", rationale: "User accepted high-level design for the coordinated architectural repair." }, + { idempotency_key: "sha256:b44cce49b270e039db9825c224697b82b1f7ac236d4a1a361cd36e21a6e3cd13", phase_id: "phase-3", gate_type: "phase-3-exit", question: "Continue to solution convergence?", options: ["Continue to solution convergence", "Pause workflow"], status: "decided", selected_option: "Continue to solution convergence", final_actor: "user", rationale: "User chose to continue to sequential convergence." }, + { idempotency_key: "sha256:062092ecba0c9acbea7029183919a6f17fbef223d18664a26cfb5a43abbc2048", phase_id: "phase-4", gate_type: "research-convergence", question: "Gdzie powinna być wykonywana logika agreement, arbitration, retry i resume?", options: ["A1 — logika wyłącznie w instrukcjach workflow hosta", "A2 — monolityczny phase-continue.mjs", "A3 — wspólny executable evaluator z portami hosta (Recommended)", "A4 — Codex-only evaluator w adapterze platformy", "Need more info"], status: "decided", selected_option: "A3 — wspólny executable evaluator z portami hosta (Recommended)", final_actor: "user", rationale: "User selected the shared executable evaluator with host ports." }, + { idempotency_key: "sha256:b5a379b7ee2f1713f0557c05206c537fc10ba237bcfabeec57daaba82febeb85", phase_id: "phase-4", gate_type: "research-convergence", question: "Kto powinien być właścicielem kanonicznego stanu i pełnego terminalnego rekordu gate?", options: ["B1 — evaluator zapisuje pełny rekord, runner konsumuje i weryfikuje (Recommended)", "B2 — runner jest jedynym writerem pełnego rekordu", "B3 — jeden zintegrowany command transaction dla gate i continuation", "B4 — append-only event log jako jedyne źródło prawdy", "Need more info"], status: "decided", selected_option: "B1 — evaluator zapisuje pełny rekord, runner konsumuje i weryfikuje (Recommended)", final_actor: "user", rationale: "User selected evaluator-owned terminal records." }, + { idempotency_key: "sha256:837b61a6dc98accdccf9714d197591c0b89916de73f0c281e1745d27a4a98e4b", phase_id: "phase-4", gate_type: "research-convergence", question: "Jak powinien działać trwały cursor i dispatch kolejnego problemu w tej samej fazie?", options: ["C1 — workflow-owned inventory plus durable outbox/receipt (Recommended)", "C2 — tylko liczbowy cursor/index w phase summary", "C3 — runner wylicza i zapisuje generyczny następny target", "C4 — ephemeral same-turn loop bez durable dispatch state", "Need more info"], status: "decided", selected_option: "C1 — workflow-owned inventory plus durable outbox/receipt (Recommended)", final_actor: "user", rationale: "User selected the workflow-owned durable outbox and receipt protocol." }, + { idempotency_key: "sha256:508e5ca0e153b0f0240fc7afaa47d291a3795392c4d504f11b989657c51bd5cb", phase_id: "phase-4", gate_type: "research-convergence", question: "Jak Codex powinien połączyć natywne role, wspólny evaluator/runner i workflow loop bez kończenia tury?", options: ["D1 — cienki host-native binding wokół wspólnych CLI (Recommended)", "D2 — lokalny MCP/tool server jako runtime adapter", "D3 — zewnętrzny headless Codex wrapper sterujący sesją", "D4 — Codex-specific background daemon/outbox consumer", "Need more info"], status: "decided", selected_option: "D1 — cienki host-native binding wokół wspólnych CLI (Recommended)", final_actor: "user", rationale: "User selected the thin Codex host-native binding." }, + { idempotency_key: "sha256:deff7dc9407e4bf7bd8e9827eea83f0943d11d5daa1793b43db636eb584db001", phase_id: "phase-4", gate_type: "phase-4-exit", question: "Brainstorming complete. Continue to high-level design?", options: ["Continue to high-level design", "Pause workflow"], status: "decided", selected_option: "Continue to high-level design", final_actor: "user", rationale: "User approved the converged solution package and continued to design." }, + { idempotency_key: "sha256:cb98ff2bc72c18e9b770811df2023a41e3c771d1173b795ee4a03aafb7e4aed8", phase_id: "phase-5", gate_type: "research-clarification", question: "Czy potwierdzasz założenia projektu: A3+B1+C1+D1, current_phase jako canonical cursor, evaluator-owned full gate record, workflow-owned durable outbox, thin Codex binding oraz brak zmian w denyliście?", options: ["Confirm assumptions", "Correct assumptions", "Provide more context"], status: "decided", selected_option: "Confirm assumptions", final_actor: "user", rationale: "User confirmed the converged high-level design assumptions." }, + { idempotency_key: "sha256:6bdf08499f5ea52adcb109887df08612b87fed5c1a2a6ba779d4fc70c9cb160e", phase_id: "phase-5", gate_type: "phase-5-exit", question: "Design complete. Continue to output generation?", options: ["Continue to output generation", "Pause workflow"], status: "decided", selected_option: "Continue to output generation", final_actor: "user", rationale: "User accepted the completed design and continued to final output generation." }, + { idempotency_key: "sha256:b35883e703798a8680ccae7ccae72418a71acd780faaa9c19d3a12a5723f17ce", phase_id: "phase-6", gate_type: "final-handoff-approval", question: "Research workflow complete. Complete workflow?", options: ["Complete workflow", "Keep workflow open"], status: "decided", selected_option: "Complete workflow", final_actor: "user", rationale: "User explicitly approved final handoff and workflow completion." } + ] +}; diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/dashboard.html b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/dashboard.html new file mode 100644 index 00000000..9f5ea812 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/dashboard.html @@ -0,0 +1,629 @@ + + + + + +Maister Workflow Dashboard + + + + +
+
+ Waiting for dashboard-data.js… If this persists, the workflow has not written data yet. +
+
+ + + + diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/orchestrator-state.yml b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/orchestrator-state.yml new file mode 100644 index 00000000..84dc62c0 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/orchestrator-state.yml @@ -0,0 +1,650 @@ +orchestrator: + started_phase: phase-6 + completed_phases: [phase-1, phase-2, phase-3, phase-4, phase-5, phase-6] + failed_phases: [] + auto_fix_attempts: + phase-1: 0 + phase-2: 0 + phase-3: 0 + phase-4: 0 + phase-5: 0 + phase-6: 0 + options: + html_output: true + brainstorming_enabled: true + design_enabled: true + advisor: + enabled: true + gate_policies: + phase-exit: fully_automatic + optional-phase: fully_automatic + clarify: fully_automatic + convergence: fully_automatic + verify-matrix: fully_automatic + advisor_agent: advisor + advisor_model: gpt-5.6-sol + arbiter_agent: arbiter + arbiter_model: gpt-5.6-sol + arbiter_enabled_on_disagreement: true + retry: + advisor_attempts: 3 + arbiter_attempts: 3 + backoff: exponential + created: "2026-07-13T16:29:57Z" + updated: "2026-07-13T17:45:47Z" + task_path: .maister/tasks/research/2026-07-13-fix-codex-auto-continuation + task_ids: + phase-1: research-phase-1 + phase-2: research-phase-2 + phase-3: research-phase-3 + phase-4: research-phase-4 + phase-5: research-phase-5 + phase-6: research-phase-6 + gate_history: + - schema_version: 1 + idempotency_key: sha256:8dc80ac772693c815f0dfac96f7baa45a3cded3e406f16c6f5a42756f1e157d4 + phase_id: phase-1 + gate_type: phase-1-exit + question: Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? + options: + - Continue to brainstorming evaluation + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to brainstorming evaluation + final_actor: user + original_recommendation: Continue to brainstorming evaluation + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed continuation to optional-phase evaluation after reviewing the completed research report. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:947722f8e62401e5336692e2111b5e96368af8bed9af2b88b6901de279abeef5 + phase_id: phase-2 + gate_type: optional-phase-selection + question: Multiple viable implementation seams and unresolved trade-offs make brainstorming valuable. Would you like to explore solution alternatives? + options: + - Yes, explore alternatives + - No, skip brainstorming + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, explore alternatives + final_actor: user + original_recommendation: Yes, explore alternatives + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User accepted the recommendation to explore alternatives because the repair contains multiple coupled design seams and trade-offs. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:9370fe762f9aac3a82681193f9b4edf42ab09841dc696b521f77705a0ebc4549 + phase_id: phase-2 + gate_type: optional-phase-selection + question: The fix requires coordinated state-schema, evaluator, runner, Codex adapter, and workflow-loop decisions, so high-level design is valuable. Would you like to generate a high-level design? + options: + - Yes, generate design + - No, skip design + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, generate design + final_actor: user + original_recommendation: Yes, generate design + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User accepted high-level design because the repair coordinates multiple architectural seams and must preserve strict state, safety, and host boundaries. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b44cce49b270e039db9825c224697b82b1f7ac236d4a1a361cd36e21a6e3cd13 + phase_id: phase-3 + gate_type: phase-3-exit + question: Continue to solution convergence? + options: + - Continue to solution convergence + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to solution convergence + final_actor: user + original_recommendation: Continue to solution convergence + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User chose to continue from solution generation to sequential convergence. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:062092ecba0c9acbea7029183919a6f17fbef223d18664a26cfb5a43abbc2048 + phase_id: phase-4 + gate_type: research-convergence + question: Gdzie powinna być wykonywana logika agreement, arbitration, retry i resume? + options: + - A1 — logika wyłącznie w instrukcjach workflow hosta + - A2 — monolityczny phase-continue.mjs + - A3 — wspólny executable evaluator z portami hosta (Recommended) + - A4 — Codex-only evaluator w adapterze platformy + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: A3 — wspólny executable evaluator z portami hosta (Recommended) + final_actor: user + original_recommendation: A3 — wspólny executable evaluator z portami hosta (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected the shared executable evaluator because it makes agreement, arbitration, retry, and resume deterministic and portable without absorbing domain routing. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b5a379b7ee2f1713f0557c05206c537fc10ba237bcfabeec57daaba82febeb85 + phase_id: phase-4 + gate_type: research-convergence + question: Kto powinien być właścicielem kanonicznego stanu i pełnego terminalnego rekordu gate? + options: + - B1 — evaluator zapisuje pełny rekord, runner konsumuje i weryfikuje (Recommended) + - B2 — runner jest jedynym writerem pełnego rekordu + - B3 — jeden zintegrowany command transaction dla gate i continuation + - B4 — append-only event log jako jedyne źródło prawdy + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: B1 — evaluator zapisuje pełny rekord, runner konsumuje i weryfikuje (Recommended) + final_actor: user + original_recommendation: B1 — evaluator zapisuje pełny rekord, runner konsumuje i weryfikuje (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected evaluator-owned terminal records so the component executing the gate state machine also preserves full provenance before runner effects. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:837b61a6dc98accdccf9714d197591c0b89916de73f0c281e1745d27a4a98e4b + phase_id: phase-4 + gate_type: research-convergence + question: Jak powinien działać trwały cursor i dispatch kolejnego problemu w tej samej fazie? + options: + - C1 — workflow-owned inventory plus durable outbox/receipt (Recommended) + - C2 — tylko liczbowy cursor/index w phase summary + - C3 — runner wylicza i zapisuje generyczny następny target + - C4 — ephemeral same-turn loop bez durable dispatch state + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: C1 — workflow-owned inventory plus durable outbox/receipt (Recommended) + final_actor: user + original_recommendation: C1 — workflow-owned inventory plus durable outbox/receipt (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected the workflow-owned stable inventory and durable outbox/receipt to preserve domain ordering and logical exactly-once dispatch through resume. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:508e5ca0e153b0f0240fc7afaa47d291a3795392c4d504f11b989657c51bd5cb + phase_id: phase-4 + gate_type: research-convergence + question: Jak Codex powinien połączyć natywne role, wspólny evaluator/runner i workflow loop bez kończenia tury? + options: + - D1 — cienki host-native binding wokół wspólnych CLI (Recommended) + - D2 — lokalny MCP/tool server jako runtime adapter + - D3 — zewnętrzny headless Codex wrapper sterujący sesją + - D4 — Codex-specific background daemon/outbox consumer + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: D1 — cienki host-native binding wokół wspólnych CLI (Recommended) + final_actor: user + original_recommendation: D1 — cienki host-native binding wokół wspólnych CLI (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected the thin host-native Codex binding so the shared evaluator and runner remain canonical while successful execution returns control to the active workflow loop. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:deff7dc9407e4bf7bd8e9827eea83f0943d11d5daa1793b43db636eb584db001 + phase_id: phase-4 + gate_type: phase-4-exit + question: Brainstorming complete. Continue to high-level design? + options: + - Continue to high-level design + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to high-level design + final_actor: user + original_recommendation: Continue to high-level design + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User approved the converged A3+B1+C1+D1 package and continued to high-level design. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:cb98ff2bc72c18e9b770811df2023a41e3c771d1173b795ee4a03aafb7e4aed8 + phase_id: phase-5 + gate_type: research-clarification + question: "Czy potwierdzasz założenia projektu: A3+B1+C1+D1, current_phase jako canonical cursor, evaluator-owned full gate record, workflow-owned durable outbox, thin Codex binding oraz brak zmian w denyliście?" + options: + - Confirm assumptions + - Correct assumptions + - Provide more context + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Confirm assumptions + final_actor: user + original_recommendation: Confirm assumptions + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed the converged A3+B1+C1+D1 architecture assumptions, canonical cursor, full gate audit, durable outbox, thin Codex binding, and unchanged safety denylist. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:6bdf08499f5ea52adcb109887df08612b87fed5c1a2a6ba779d4fc70c9cb160e + phase_id: phase-5 + gate_type: phase-5-exit + question: Design complete. Continue to output generation? + options: + - Continue to output generation + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to output generation + final_actor: user + original_recommendation: Continue to output generation + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User accepted the completed high-level design and continued to final output generation. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b35883e703798a8680ccae7ccae72418a71acd780faaa9c19d3a12a5723f17ce + phase_id: phase-6 + gate_type: final-handoff-approval + question: Research workflow complete. Complete workflow? + options: + - Complete workflow + - Keep workflow open + policy: manual + safety_classification: denylisted + status: decided + selected_option: Complete workflow + final_actor: user + original_recommendation: Complete workflow + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly approved final handoff and completion of the research workflow. + confidence: high + escalate_to_user: false + user_override: false + error: null + implementation_approval: + status: not_required + approved_by: null + approved_at: null + approved_scope: [] + +task: + title: Naprawa automatycznej kontynuacji Codex + description: Ustalić precyzyjną naprawę fully_automatic dla zgodności rekomendacji, arbitrażu przy rozbieżności i automatycznego przechodzenia do kolejnego problemu bez kliknięcia użytkownika. + status: completed + tags: [research, codex, advisor, arbiter, continuation] + priority: high + +phases: + - id: phase-1 + name: Research foundation + status: completed + blocked_by: [] + started: "2026-07-13T16:29:57Z" + completed: "2026-07-13T16:49:07Z" + gate: + question: Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? + answer: Continue to brainstorming evaluation + - id: phase-2 + name: Evaluate brainstorming value + status: completed + blocked_by: [phase-1] + started: "2026-07-13T16:49:07Z" + completed: "2026-07-13T16:56:55Z" + gate: + question: The fix requires coordinated state-schema, evaluator, runner, Codex adapter, and workflow-loop decisions, so high-level design is valuable. Would you like to generate a high-level design? + answer: Yes, generate design + - id: phase-3 + name: Generate solution alternatives + status: completed + blocked_by: [phase-2] + started: "2026-07-13T16:56:55Z" + completed: "2026-07-13T17:05:41Z" + gate: + question: Continue to solution convergence? + answer: Continue to solution convergence + - id: phase-4 + name: Evaluate brainstorming alternatives + status: completed + blocked_by: [phase-3] + started: "2026-07-13T17:05:41Z" + completed: "2026-07-13T17:27:26Z" + gate: + question: Brainstorming complete. Continue to high-level design? + answer: Continue to high-level design + - id: phase-5 + name: Design high-level architecture + status: completed + blocked_by: [phase-4] + started: "2026-07-13T17:27:26Z" + completed: "2026-07-13T17:43:21Z" + gate: + question: Design complete. Continue to output generation? + answer: Continue to output generation + - id: phase-6 + name: Summarize research and suggest next steps + status: completed + blocked_by: [phase-5] + started: "2026-07-13T17:43:21Z" + completed: "2026-07-13T17:45:47Z" + gate: + question: Research workflow complete. Complete workflow? + answer: Complete workflow + +research_context: + research_type: technical + research_question: Jak naprawić Codex fully_automatic tak, aby zgodność rekomendacji głównego agenta i advisora automatycznie wybierała decyzję, rozbieżność uruchamiała arbitra dokładnie raz, a wynik automatycznie kontynuował do następnego problemu bez interakcji użytkownika? + scope: + included: + - Kanoniczny kontrakt orchestrator-state.yml i gate_history + - Gate decision engine oraz phase-continue.mjs + - Adapter i host-native E2E dla Codex + - Pętla automatycznego przechodzenia przez kolejne problemy lub decision areas + - Idempotencja, raportowanie, retry i bezpieczeństwo denylist + excluded: + - Implementacja poprawki + - Zmiana chronionych bramek wymagających zgody użytkownika + - Rozszerzenie funkcjonalności trackerów poza automatyczną kontynuację workflow + constraints: + - Zachować fail-closed dla denylisty i niskiej pewności + - Edytować wyłącznie źródła kanoniczne oraz adaptery, nie generated variants + - Udowodnić zachowanie testami kontraktowymi i host-native E2E + methodology: + - Codebase flow tracing + - State schema comparison + - Multi-source triangulation across code, tests, generated adapters, and prior diagnosis + sources: + - .maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/codex-fully-automatic-diagnosis.md + - plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md + - plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs + - platforms/codex-cli/ + - tests/ + confidence_level: high + gathering_strategy: + categories: + - gate-state-contract + - continuation-dispatch + - codex-host-adapter + - verification-safety + count: 4 + source: planner + project_doc_paths: + - .maister/docs/project/vision.md + - .maister/docs/project/roadmap.md + - .maister/docs/project/tech-stack.md + - .maister/docs/project/architecture.md + phase_summaries: + phase-1: + steps_completed: [initialize, plan, gather, synthesize] + summary: Wymagany jest wykonywalny łańcuch evaluator → durable runner commit → Codex adapter → workflow loop; zgodność kończy advisor, rozbieżność dokładnie jeden arbiter, a trwały cursor i dispatch_id przenoszą sterowanie do kolejnego problemu bez kończenia tury. + decisions: + - decision: Użyć current_phase i pełnego gate_history jako jednego canonical contractu. + rationale: Obecny started_phase i wąska historia runnera są niezgodne z realnym workflow i wymaganym audytem. + - decision: Rozdzielić commit runnera od dispatchu workflow. + rationale: Runner kończy proces po stdout i nie zna domenowej kolejności problemów. + - decision: Nie zmieniać Codex capability na supported przed zielonym host-native E2E. + rationale: Shared runner i fake integration nie dowodzą utrzymania tury ani rzeczywistego następnego dispatchu. + risks: + - Stabilny headless binding Codex wymaga krótkiego spike'a implementacyjnego. + - Exactly-once musi oznaczać logiczny efekt deduplikowany przez dispatch_id, nie brak fizycznego retry. + artifacts: + - path: planning/research-brief.md + label: Research brief + html: null + - path: planning/research-plan.md + label: Research plan + html: null + - path: planning/sources.md + label: Sources + html: null + - path: analysis/findings/01-gate-state-contract.md + label: Gate and state contract + html: null + - path: analysis/findings/02-continuation-dispatch.md + label: Continuation dispatch + html: null + - path: analysis/findings/03-codex-host-adapter.md + label: Codex host adapter + html: null + - path: analysis/findings/04-verification-safety.md + label: Verification and safety + html: null + - path: analysis/synthesis.md + label: Research synthesis + html: null + - path: outputs/research-report.md + label: Research report + html: outputs/research-report.html + phase-3: + summary: Przeanalizowano 16 wariantów w czterech obszarach; rekomendowany zestaw A3+B1+C1+D1 rozdziela executable evaluator, pełny audit, workflow-owned durable dispatch i cienki binding Codex. + decisions: + - decision: A3 — wspólny executable evaluator z portami hosta. + rationale: Zapewnia wykonywalną i przenośną state machine bez łączenia hosta z domenowym routingiem. + - decision: B1 — evaluator zapisuje pełny rekord, runner go weryfikuje i kontynuuje. + rationale: Zachowuje pełny provenance i umożliwia resume raportu/transition bez ponawiania modelu. + - decision: C1 — workflow-owned inventory plus durable outbox/receipt. + rationale: Pozwala sekwencyjnie przeliczać zależne work itemy oraz deduplikować logiczny efekt przez dispatch_id. + - decision: D1 — cienki host-native binding Codex. + rationale: Adapter utrzymuje turę i zwraca continue bez stawania się drugim źródłem prawdy. + risks: + - Headless i active-turn hook Codex wymaga krótkiego spike'a. + - Dwa procesy zapisujące YAML wymagają wspólnego repository, revision/CAS lub lockowania. + artifacts: + - path: outputs/solution-exploration.md + label: Solution exploration + html: outputs/solution-exploration.html + phase-4: + summary: Trwa sekwencyjna konwergencja czterech zależnych decyzji architektonicznych. + decision_areas: + - area: Evaluator ownership and packaging + alternatives_count: 4 + chosen_approach: A3 — wspólny executable evaluator z portami hosta + - area: Canonical state and terminal record ownership + alternatives_count: 4 + chosen_approach: B1 — evaluator zapisuje pełny rekord, runner konsumuje i weryfikuje + - area: Same-phase cursor and dispatch protocol + alternatives_count: 4 + chosen_approach: C1 — workflow-owned inventory plus durable outbox/receipt + - area: Codex binding and native E2E seam + alternatives_count: 4 + chosen_approach: D1 — cienki host-native binding wokół wspólnych CLI + deferred_ideas: [] + decisions: + - decision: A3 — wspólny executable evaluator z portami hosta. + rationale: Jeden wykonywalny i przenośny gate engine bez domenowego routingu. + - decision: B1 — evaluator zapisuje pełny rekord, runner konsumuje i weryfikuje. + rationale: Pełny provenance jest trwały przed raportami i continuation. + - decision: C1 — workflow-owned inventory plus durable outbox/receipt. + rationale: Stabilne ID i dispatch_id zapewniają sekwencyjność oraz logiczne exactly-once. + - decision: D1 — cienki host-native binding wokół wspólnych CLI. + rationale: Codex utrzymuje aktywną turę bez duplikowania state machine lub routingu. + risks: [] + artifacts: [] + phase-5: + summary: Zaprojektowano executable state machine w architekturze ports-and-adapters z ośmioma komponentami runtime, wspólnym state repository, durable dispatch oraz cienkim bindingiem Codex. + architecture_style: Executable state machine plus ports-and-adapters in a single-source multi-target plugin pipeline + decisions_count: 8 + decisions: + - decision: Shared executable gate evaluator. + rationale: Agreement, arbitration, retry and resume become deterministic and portable. + - decision: Evaluator-owned full gate record with runner verification. + rationale: Full provenance is durable before reports and continuation. + - decision: Workflow-owned inventory and durable outbox/receipt. + rationale: Stable work_item_id and dispatch_id support logical exactly-once resume. + - decision: Thin Codex binding returns continue to the active workflow loop. + rationale: Host integration remains thin and does not duplicate state or routing logic. + risks: + - Codex active-turn/headless hook requires an implementation spike. + - Schema v2 migration must fail closed for real existing workflow states. + - Dispatch receivers must deduplicate by dispatch_id. + artifacts: + - path: outputs/high-level-design.md + label: High-level design + html: outputs/high-level-design.html + - path: outputs/decision-log.md + label: Decision log + html: outputs/decision-log.html diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-log.html b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-log.html new file mode 100644 index 00000000..f9b834ed --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-log.html @@ -0,0 +1,31 @@ + + + + +Decision log — automatyczna kontynuacja Codex + + + + +
Decision log

Automatyczna kontynuacja Codex

MADR · Research / Phase 5

+
8ADR
8accepted
0superseded
A3+B1+C1+D1pakiet
+

TL;DR

Osiem decyzji tworzy jeden łańcuch: shared evaluator → pełny terminal record → runner commit → workflow-owned durable dispatch → thin Codex binding. Stan to pojedynczy YAML snapshot chroniony lockiem i revision/CAS; current_phase jest jedynym kursorem. Capability Codex pozostaje unsupported bez zielonego real host-native E2E.

Key Decisions

  • A3, B1, C1 i D1 accepted.
  • current_phase zamiast mutowalnego started_phase.
  • Shared lock + CAS repository.
  • Runner commit boundary; workflow routing boundary.
  • Capability flip wyłącznie na podstawie evidence.

Open Questions / Risks

  • Active-turn spike; MCP tylko po disproven D1.
  • Fail-closed schema v2 migration.
  • Receiver musi deduplikować dispatch_id.
+ +
ADRDecyzjaStatus
001Shared executable evaluatorAccepted
002Evaluator-owned full recordAccepted
003Workflow inventory + outboxAccepted
004Thin Codex bindingAccepted
005Canonical current_phaseAccepted
006Lock + revision/CAS repositoryAccepted
007Runner commits, workflow dispatchesAccepted
008Evidence-gated capability flipAccepted
+
+

ADR-001 — Shared executable gate evaluator (A3)

Accepted

Context
Markdown opisuje agreement/arbitration/retry/resume, ale testy nie wykonują tej FSM. Prose-only lub Codex-only utrwali drift.

Decision
Canonical framework dostaje executable evaluator z read-only role_invoker. Evaluator nie zna domain routingu ani host effects.

Consequences
FSM jest fixture-testable; potrzebny jest mały runtime i native delegation port.

Rejected
A1 nie usuwa root cause; A2 miesza domenę i host; A4 tworzy drugą semantykę.

+

ADR-002 — Evaluator-owned full gate record (B1)

Accepted

Context
Runner rekonstruuje uboższy record i traci recommendation, responses, models i attempts.

Decision
Evaluator aktualizuje jeden envelope pending→terminal. Runner reread/weryfikuje key, selection, actor, confidence i revision bez rekonstrukcji provenance.

Consequences
Decyzja jest durable przed reports/continuation; recovery nie ponawia modeli. Dwaj sekwencyjni writerzy współdzielą repository.

Rejected
B2 czyni runner RPC service; B3 nie transakcjonuje model call; B4 jest nieproporcjonalny.

+

ADR-003 — Workflow-owned inventory i durable outbox/receipt (C1)

Accepted

Context
Runner nie zna decision areas; indeks nie daje stabilnej identity ani recovery.

Decision
Workflow materializuje work itemy, zapisuje wybór i deterministyczny dispatch_id; receiver deduplikuje efekt i zapisuje checkpoint/ack.

Consequences
Same-phase i next-phase są obserwowalne/resumable; exactly-once oznacza logiczny efekt. Każdy workflow posiada lokalny routing.

Rejected
C2 niestabilny indeks; C3 domain-coupled runner; C4 nie rozstrzyga crash window.

+

ADR-004 — Thin host-native Codex binding (D1)

Accepted

Context
Brak executable consumer łączącego native roles, evaluator, runner i aktywną pętlę.

Decision
Binding w platforms/codex-cli/ dostarcza role port, waliduje shared runtime i zwraca continue | user_gate | blocked; bez policy i routingu.

Consequences
Core pozostaje portable; exact active-turn hook wymaga spike'a. MCP tylko jeśli spike obali D1.

Rejected
D2 service footprint; D3 niereprezentatywny wrapper; D4 nie zachowuje tej samej tury.

+

ADR-005 — current_phase jako canonical cursor

Accepted

Context
State używa started_phase, runner wymaga current_phase, a sama lista faz nie chroni przed split-brain.

Decision
Schema v2 ma jeden mutowalny current_phase; opcjonalny initial_phase jest historyczny. Cursor wskazuje jedyną fazę in-progress.

Consequences
Jedno źródło resume; konieczna wersjonowana migracja generatorów i realnych state files.

Rejected
Dwa cursory tworzą split-brain; derivation tylko z phases osłabia walidację.

+

ADR-006 — Lock + revision/CAS state repository

Accepted

Context
Evaluator i runner piszą sekwencyjnie; atomic rename nie zapobiega lost update między procesami.

Decision
Jeden mały repository zapewnia exclusive lock, schema/invariants, expected-revision CAS, temp+fsync+rename i mode preservation. Lock nie obejmuje modelu/dispatchu.

Consequences
Conflict → reread/idempotency resolution. Moduł jest wąski, ma bezpośrednich callerów i nie jest spekulacyjną abstrakcją.

Rejected
Last-write-wins traci dane; długi lock przez external calls nie tworzy transakcji.

+

ADR-007 — Runner commituje; workflow dispatchuje

Accepted

Context
Runner ma dobre preflight/persistence/recovery, ale nie zna domeny i nie utrzymuje hostowej tury.

Decision
Runner weryfikuje terminal record, regeneruje raporty i robi forward transition. Workflow stosuje wybór, materializuje target i dispatchuje.

Consequences
Recovery pozostaje centralne; sukces runnera nie oznacza wykonania następnej pracy, więc receipt/checkpoint jest obowiązkowy.

Rejected
Runner-dispatcher powtarza monolit A2/C3.

+

ADR-008 — Evidence-gated Codex capability flip

Accepted

Context
Obecny E2E zwraca 77; shared runner i prose/smoke nie dowodzą no UI ani real next dispatch.

Decision
Capability pozostaje unsupported do exit 0 real Codex E2E: agreement, disagreement, same/next phase, no UI, resume i dedupe. Brak runtime nadal daje 77.

Consequences
Rollout jest fail-closed; implementacja może istnieć przed aktywacją, a manual fallback zostaje.

Rejected
Flip po shared/fake/build-presence myli deklarację z runtime evidence.

+
+

Powiązania

High-level design · Design MD · Research report · Solution exploration

+ + diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-log.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-log.md new file mode 100644 index 00000000..e8a0cf32 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-log.md @@ -0,0 +1,105 @@ +# Decision log: automatyczna kontynuacja Codex + +## TL;DR + +Przyjęto osiem decyzji architektonicznych tworzących jeden spójny łańcuch: shared evaluator → pełny terminal record → runner commit → workflow-owned durable dispatch → thin Codex binding. +Stan pozostaje pojedynczym YAML snapshotem, zabezpieczonym lockiem, revision/CAS i atomic rename; `current_phase` jest jedynym kursorem fazy. +Runner nie dispatchuje pracy, a capability Codex nie zmienia się na `supported` bez zielonego, rzeczywistego host-native E2E. + +## Key Decisions + +- A3, B1, C1 i D1 zostały zaakceptowane bez zmian. +- `current_phase` zastępuje mutowalne znaczenie `started_phase`. +- Wspólne state repository zapewnia lock + CAS dla evaluatora i runnera. +- Runner pozostaje commit boundary, a workflow loop pozostaje routing boundary. +- Capability flip jest zmianą opartą na dowodzie, nie na deklaracji lub fake-only teście. + +## Open Questions / Risks + +- Active-turn binding Codex wymaga spike'a; MCP jest fallbackiem tylko po negatywnym dowodzie D1. +- Schema v2 i migracja uboższych historii muszą być fail-closed oraz przetestowane realnymi snapshots. +- Idempotentny receiver jest konieczny, aby `dispatch_id` zapewniał jeden logiczny efekt mimo fizycznego retry. + +## Status summary + +| ADR | Decyzja | Status | +|---|---|---| +| ADR-001 | Shared executable gate evaluator (A3) | Accepted | +| ADR-002 | Evaluator-owned full gate record (B1) | Accepted | +| ADR-003 | Workflow-owned inventory i outbox/receipt (C1) | Accepted | +| ADR-004 | Thin host-native Codex binding (D1) | Accepted | +| ADR-005 | `current_phase` jako canonical cursor | Accepted | +| ADR-006 | Lock + revision/CAS state repository | Accepted | +| ADR-007 | Runner commituje, workflow dispatchuje | Accepted | +| ADR-008 | Evidence-gated Codex capability flip | Accepted | + +## ADR-001 — Shared executable gate evaluator (A3) + +**Status:** Accepted +**Context:** Normatywny Markdown opisuje agreement, arbitration, retry i resume, ale obecne testy nie wykonują tej state machine. Umieszczenie algorytmu wyłącznie w prose lub w adapterze Codex utrwaliłoby drift. +**Decision:** Dodać wspólny executable evaluator w canonical orchestrator framework. Evaluator posiada state machine i używa wstrzykiwanego read-only `role_invoker`; nie zna domenowego routingu ani hostowych efektów. +**Consequences:** Agreement, jeden logiczny arbiter, retry i resume są deterministycznie testowalne. Powstaje nowy, mały runtime component i wymagany jest stabilny port native delegation. +**Rejected alternatives:** A1 prose-only nie usuwa root cause; A2 monolityczny runner miesza domenę i host; A4 Codex-only tworzy drugą semantykę. + +## ADR-002 — Evaluator-owned full gate record (B1) + +**Status:** Accepted +**Context:** Runner dziś otrzymuje już wybraną opcję i rekonstruuje uboższy record, tracąc original recommendation, role responses, models i attempts. +**Decision:** Evaluator aktualizuje jeden pełny envelope od pending do terminalnego wyniku. Runner ponownie czyta state i weryfikuje idempotency key, selected option, actor, confidence oraz revision; nie dopisuje ani nie rekonstruuje provenance. +**Consequences:** Terminalna decyzja jest trwała przed raportem i continuation, a recovery nie ponawia modeli. Evaluator i runner są sekwencyjnymi writerami i muszą współdzielić repository. +**Rejected alternatives:** B2 robi z runnera RPC state service; B3 nie daje transakcji przez model call; B4 event log jest nieproporcjonalny. + +## ADR-003 — Workflow-owned inventory i durable outbox/receipt (C1) + +**Status:** Accepted +**Context:** Runner potrafi opcjonalnie zmienić fazę, ale nie zna kolejności decision areas i kończy proces po stdout. Sam indeks nie daje stabilnej identity ani recovery po dispatchu. +**Decision:** Każdy workflow z pętlą materializuje stabilne work itemy. Po decyzji zapisuje wybór, następny target i deterministyczny `dispatch_id`; dispatcher/receiver deduplikuje efekt i zapisuje trwały checkpoint/ack. +**Consequences:** Same-phase i next-phase continuation są obserwowalne i resumable. Exactly-once oznacza logiczny efekt; fizyczne wywołanie może być retry'owane. Workflowy muszą implementować własne inventory/routing na wspólnym envelope. +**Rejected alternatives:** C2 indeks jest niestabilny; C3 sprzęga runner z domeną; C4 ephemeral loop nie rozstrzyga crash window. + +## ADR-004 — Thin host-native Codex binding (D1) + +**Status:** Accepted +**Context:** Codex ma read-only profile ról, ale nie ma executable consumer łączącego role, evaluator, runner i aktywną pętlę. Lokalny service lub wrapper zwiększałby footprint i nie gwarantował utrzymania tury. +**Decision:** Binding w `platforms/codex-cli/` dostarcza native role port, uruchamia shared evaluator/runner, waliduje ich kontrakty i zwraca wyłącznie `continue | user_gate | blocked`. Nie implementuje policy ani domain routing. +**Consequences:** Shared core pozostaje portable, a Codex zachowuje native delegation. Exact active-turn hook wymaga krótkiego spike'a. MCP można rozważyć wyłącznie, jeśli spike empirycznie obali D1. +**Rejected alternatives:** D2 dodaje runtime service; D3 wrapper może nie reprezentować realnej sesji; D4 daemon nie kontynuuje tej samej tury. + +## ADR-005 — `current_phase` jako jedyny canonical phase cursor + +**Status:** Accepted +**Context:** Realny state używa `started_phase`, runner transition wymaga `current_phase`, a `phases[]` może być niespójne bez jawnego kursora. +**Decision:** Schema v2 używa `orchestrator.current_phase` jako jedynego mutowalnego kursora. `initial_phase` może zachować niemutowalną informację historyczną. `current_phase` musi wskazywać jedyną fazę `in_progress`. +**Consequences:** Resume i transition mają jedno źródło prawdy. Wymagana jest wersjonowana migracja realnych state files oraz aktualizacja wszystkich generatorów/call sites. +**Rejected alternatives:** Utrzymanie obu pól tworzy split-brain; wyprowadzanie wyłącznie z `phases[]` osłabia walidację uszkodzonego stanu. + +## ADR-006 — Lock + revision/CAS state repository + +**Status:** Accepted +**Context:** Evaluator zapisuje pending/terminal records, a runner później zapisuje projekcje/transition. Atomic rename pojedynczego writera nie chroni przed lost update między procesami. +**Decision:** Oba komponenty używają jednego małego repository: project-local exclusive lock, exact-schema/invariant validation, `expected_revision` CAS, temp file + fsync + atomic rename i zachowanie mode. Lock nie jest trzymany podczas model call ani host dispatchu. +**Consequences:** Konflikt powoduje reread i idempotency resolution, nie overwrite. Repository jest nowym wspólnym dependency, ale ma bezpośrednich callerów i wąski zakres zgodny z minimal implementation. +**Rejected alternatives:** Blind last-write-wins grozi utratą historii; jeden długi lock przez model/dispatch blokuje workflow i nadal nie tworzy transakcji zewnętrznej. + +## ADR-007 — Runner commituje; workflow dispatchuje + +**Status:** Accepted +**Context:** `phase-continue.mjs` ma dobre mechanizmy preflight, terminal persistence, reports i forward transition, ale nie zna domeny i nie utrzymuje hostowej tury. +**Decision:** Runner pozostaje deterministic commit boundary: weryfikuje terminal record, regeneruje raporty i może atomowo przełączyć fazę. Workflow loop jest routing boundary: stosuje wybór, materializuje target i dispatchuje go przez binding. +**Consequences:** Recovery raportu/transition pozostaje centralne, a shared runner nie absorbuje decision areas. Sukces runnera nie może być interpretowany jako wykonanie następnej pracy; wymagany jest receipt/checkpoint. +**Rejected alternatives:** Runner-dispatcher wymagałby domenowego payloadu i hostowego API, powtarzając odrzucony monolit A2/C3. + +## ADR-008 — Capability Codex zmienia się tylko na podstawie host-native evidence + +**Status:** Accepted +**Context:** Obecny Codex E2E zwraca `77`, a shared runner i smoke/prose tests nie dowodzą braku UI ani realnego następnego dispatchu. Przedwczesne `supported` uruchomiłoby automatyzację bez bezpiecznego transportu. +**Decision:** Capability pozostaje `unsupported` przez implementację i adapter integration. Flip na `supported` jest osobnym krokiem dopiero po exit `0` rzeczywistego Codex host-E2E obejmującego agreement, disagreement, same-phase, next-phase, no UI, resume i dedupe. Brak runtime nadal daje `77`, nie fake success. +**Consequences:** Rollout jest fail-closed i mierzalny. Implementacja może być gotowa przed aktywacją; manual/user gate fallback pozostaje dostępny. +**Rejected alternatives:** Flip po shared testach lub po obecności plików w generated pluginie myli deklarację z runtime proof. + +## Powiązania + +- [High-level design](high-level-design.md) +- [Research report](research-report.md) +- [Solution exploration](solution-exploration.md) +- `../analysis/synthesis.md` diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.html b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.html new file mode 100644 index 00000000..c731c17c --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.html @@ -0,0 +1,21 @@ + +Decision summary — Codex continuation + + +

Decision summary

+
12gates
12decided
8accepted ADRs
0pending
+

TL;DR

Research, exploration and design are complete with package A3+B1+C1+D1. Configurable gates used interactive fallback because Codex native capability remains unsupported. The denylisted final handoff was explicitly approved by the user.

+

Key decisions

  • A3 — shared executable evaluator.
  • B1 — evaluator-owned full gate record; runner verifies.
  • C1 — workflow-owned durable outbox/receipt.
  • D1 — thin Codex binding returns control to the workflow loop.
+

Gate audit

+ + + + + + + + + +
#GateSelectionActorStatus
1Phase 1 exitContinue to brainstorming evaluationuserdecided
2Optional brainstormingYes, explore alternativesuserdecided
3Optional designYes, generate designuserdecided
4Phase 3 exitContinue to convergenceuserdecided
5–8ConvergenceA3 + B1 + C1 + D1userdecided
9Phase 4 exitContinue to designuserdecided
10Design assumptionsConfirm assumptionsuserdecided
11Phase 5 exitContinue to output generationuserdecided
12Final handoffComplete workflowuserdecided

Advisor/arbiter calls and retries: none; configurable gates fell back to the interactive user because Codex native continuation is unsupported. Final handoff is always manual.

+

Risks

  • Codex active-turn/headless hook needs a spike.
  • Schema v2 migration must fail closed.
  • Receivers must deduplicate by dispatch_id.
+ diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.md new file mode 100644 index 00000000..6af45977 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/decision-summary.md @@ -0,0 +1,59 @@ +# Decision summary: automatyczna kontynuacja Codex + +## TL;DR +Research, eksploracja wariantów i high-level design są kompletne; przyjęty zestaw to A3+B1+C1+D1. +Wszystkie konfigurowalne bramki użyły ręcznego fallbacku, ponieważ Codex host-native E2E nadal zwraca `77` i capability pozostaje `unsupported`. +Finalne zakończenie workflow zostało jawnie zatwierdzone przez użytkownika na denylisted bramce. + +## Key Decisions +- A3 — wspólny executable evaluator z portami hosta. +- B1 — evaluator zapisuje pełny rekord gate, runner go weryfikuje i kontynuuje. +- C1 — workflow-owned stable inventory oraz durable outbox/receipt z `dispatch_id`. +- D1 — cienki binding Codex zwraca `continue | user_gate | blocked` do aktywnej pętli. +- `current_phase`, schema v2, revision/CAS i evidence-gated capability flip są częścią projektu. + +## Open Questions / Risks +- Active-turn/headless hook Codex wymaga krótkiego spike'a implementacyjnego. +- Migracja realnych stanów do schema v2 musi być wersjonowana i fail-closed. +- Receiver musi deduplikować logiczny efekt po `dispatch_id`. + +## Audit summary + +Wspólny kontekst dla bramek 1–11: policy skonfigurowana jako `fully_automatic`, lecz capability Codex była `unsupported`, więc modeli advisor/arbiter nie wywołano, retry nie wystąpiły, a użytkownik dokonał wyboru przez interaktywny fallback. `user_override: false` dla wszystkich decyzji. Pełny kontekst: [research report](research-report.md), [solution exploration](solution-exploration.md), [high-level design](high-level-design.md), [decision log](decision-log.md). + +| # | Phase / gate | Recommendation | Selected option | Actor | Confidence | Status | +|---:|---|---|---|---|---|---| +| 1 | Phase 1 exit | Continue to brainstorming evaluation | Continue to brainstorming evaluation | user | high | decided | +| 2 | Optional brainstorming | Yes, explore alternatives | Yes, explore alternatives | user | high | decided | +| 3 | Optional design | Yes, generate design | Yes, generate design | user | high | decided | +| 4 | Phase 3 exit | Continue to solution convergence | Continue to solution convergence | user | high | decided | +| 5 | Evaluator ownership | A3 | A3 — shared executable evaluator | user | high | decided | +| 6 | Terminal record ownership | B1 | B1 — evaluator-owned full record | user | high | decided | +| 7 | Same-phase dispatch | C1 | C1 — workflow-owned durable outbox/receipt | user | high | decided | +| 8 | Codex binding | D1 | D1 — thin host-native binding | user | high | decided | +| 9 | Phase 4 exit | Continue to high-level design | Continue to high-level design | user | high | decided | +| 10 | Design assumptions | Confirm assumptions | Confirm assumptions | user | high | decided | +| 11 | Phase 5 exit | Continue to output generation | Continue to output generation | user | high | decided | +| 12 | Final handoff approval | Complete workflow | Complete workflow | user | high | decided | + +## Decision rationales + +1. Research foundation was accepted because it established a high-confidence, evidence-backed root cause and implementation sequence. +2. Brainstorming was enabled because four coupled architectural seams had meaningful alternatives. +3. High-level design was enabled because the fix spans state, evaluator, runner, workflow and host boundaries. +4. Sequential convergence was selected to resolve dependent decision areas one at a time. +5. A3 makes agreement, arbitration, retry and resume executable and portable without absorbing domain routing. +6. B1 preserves full provenance in the component that owns the gate state machine; runner effects can resume independently. +7. C1 preserves domain ordering and logical exactly-once through stable IDs, outbox intent and receipt. +8. D1 keeps Codex integration thin and returns control to the active workflow loop without duplicating canonical logic. +9. The coherent A3+B1+C1+D1 package warranted architecture generation. +10. Design assumptions were explicitly confirmed, including unchanged fail-closed safety boundaries. +11. The completed design with eight components and eight ADRs was accepted for final output generation. +12. Final handoff was explicitly approved by the user; no advisor or arbiter participated in this denylisted decision. + +## Generated outputs + +- [Research report](research-report.md) ([HTML](research-report.html)) +- [Solution exploration](solution-exploration.md) ([HTML](solution-exploration.html)) +- [High-level design](high-level-design.md) ([HTML](high-level-design.html)) +- [Decision log](decision-log.md) ([HTML](decision-log.html)) diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/high-level-design.html b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/high-level-design.html new file mode 100644 index 00000000..7bd422a5 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/high-level-design.html @@ -0,0 +1,64 @@ + + + + +High-level design — automatyczna kontynuacja Codex + + + + +
High-level design

Automatyczna kontynuacja Codex

Research / Phase 5 · A3 + B1 + C1 + D1

+
8komponentów
8decyzji ADR
FSM + Portsstyl
2rodzaje targetu
Fail-closedsafety
+

TL;DR

Wspólny evaluator podejmuje i zapisuje decyzję, runner ją weryfikuje i commituje projekcje/transition, a workflow loop automatycznie dispatchuje kolejną pracę. Agreement kończy gate aktorem advisor; disagreement uruchamia dokładnie jednego logicznego arbitra. Trwałe work_item_id, dispatch_id i receipt zapewniają logiczne exactly-once. Codex pozostaje unsupported do zielonego host-native E2E.

Key Decisions

  • A3 executable evaluator.
  • B1 evaluator-owned full record.
  • C1 workflow inventory + outbox.
  • D1 thin Codex binding.
  • current_phase + revision/CAS.
  • Runner commituje, workflow dispatchuje.

Open Questions / Risks

  • Active-turn hook wymaga spike'a; MCP tylko po disproven D1.
  • Schema v2 wymaga fail-closed migracji.
  • Exactly-once jest logiczne, nie transportowe.
  • Wszyscy writerzy muszą używać lock + CAS.
+ +
+

1. Styl i komponenty

Wykonywalna state machine w ports-and-adapters, osadzona w single-source/multi-target plugin pipeline. Bez usługi, daemona lub bazy.

Workflow loop→Gate evaluator↔Role port↔State repository→Runner→Codex binding→Dispatcher
+
#KomponentWłasnośćGranica
1Workflow loopInventory, apply, routingBez agreement/arbitration
2Gate evaluatorPolicy, retry, arbiter, terminal recordBez raportów i routingu
3Role invokerRead-only native role callsBez mutacji
4State repositoryLock, schema, CAS, atomic writeBez semantyki domeny
5RunnerVerify, reports, forward transitionBez modeli i dispatchu
6Codex bindingTransport i directiveBez własnej FSM
7Dispatcher/receiverEffect, dedupe, ackBez next-target logic
8Projection generatorDashboard/summaryNie jest resume source
+

2. Porty i zamknięte kontrakty

evaluateGate

Stable context → pending/attempts → exact role validation → full terminal envelope. Arbiter dostaje tylko dwie konkurujące opcje i rationales.

continuePhase

Gate key + expected selection/revision → reread terminal record → reports → opcjonalny forward transition. Bez rekonstrukcji provenance.

dispatch

dispatch_id + same_phase_work_item | phase_entry → checkpoint + ack; receiver deduplikuje ID.

Host directive

continue, user_gate albo blocked. Poprawny continue wraca do pętli i nie kończy tury.

+

3. Kanoniczny stan

orchestrator:
+  schema_version: 2
+  revision: 42
+  current_phase: phase-4
+  gate_history:
+    - idempotency_key: sha256:gate-key
+      status: decided
+      selected_option: B
+      final_actor: arbiter
+      advisor: { logical_role_id, response, attempts, exhausted }
+      arbiter: { logical_role_id, response, attempts, exhausted }
+      continuation:
+        kind: same_phase_work_item
+        target_id: decision-area:persistence-boundary
+        dispatch_id: sha256:dispatch-id
+        status: acknowledged
+  work:
+    phase-4:
+      inventory_version: sha256:artifact-version
+      items: [{ id, ordinal, status, source_gate_key, selected_option }]
+  dispatch_outbox:
+    - { dispatch_id, source_gate_key, kind, phase_id, target_id,
+        status: acknowledged, attempts: 1, checkpoint }

Inwarianty: jedna aktywna faza wskazywana przez current_phase; jeden record per gate key; jeden logical arbiter; niezmienny target per dispatch_id; forward item lifecycle; projekcje nie sterują resume.

+

4. Agreement, disagreement i fail-closed

Agreement

  1. Persist advisor_pending + attempt.
  2. Advisor zwraca original/high|medium/no escalation.
  3. Persist decided(actor=advisor).
  4. Runner projektuje, loop dispatchuje.

Arbiter=0, UI=0.

Disagreement

  1. Persist advisor response.
  2. Utwórz jeden logical_arbiter_id.
  3. Retry dopisują attempts tego ID.
  4. Persist legalny wynik arbitra.
  5. Runner + workflow kontynuują.

Fail-closed

Denylist, low confidence, escalation, exhaustion, unsupported capability lub invalid output po limicie → user_gate albo blocked. Bez transition, cursor advance i dispatchu.

agreement:    pending → advisor(A) → decided/advisor → report → outbox → dispatch/ack → next item
+disagreement: pending → advisor(B) → one arbiter(A|B) → decided/arbiter → report → dispatch
+resume:       arbiter_pending → same logical arbiter next attempt; advisor is not repeated
+

5. Dwa rodzaje continuation

TargetDurable commitDowód wykonania
Same phaseItem N completed; N+1 ready; deterministic outbox IDCheckpoint N+1 + ack; loop od razu wykonuje/renderuje N+1
Next phaseSource completed; target in_progress; current_phase target; phase-entry outboxCheckpoint body target phase + ack

Phase-entry self-check uznaje terminalny auto record i zgodny receipt za dowód równoważny user-question call ID.

+

6. Persistence, crash recovery i concurrency

lock/read/validate
+ → pending + attempt started (revision++)
+ → role result (revision++)
+ → full terminal gate + intent (revision++)
+ → reports/dashboard
+ → apply choice + cursor/transition + outbox (revision++)
+ → dispatch(same dispatch_id)
+ → ack/checkpoint (revision++)
CrashRecovery
Attempt startedZamknąć jako interruption i zużyć slot.
Arbiter pendingTen sam logical arbiter, bez advisora.
Terminal przed reportRegenerować bez modelu i duplicate history.
Outbox przed efektemRetry ten sam dispatch ID.
Efekt przed ackReceiver dedupe, potem ten sam ack.

Repository zapewnia exclusive lock, exact validation, expected-revision CAS, temp+fsync+rename i mode preservation. Lock nie obejmuje model calls ani dispatchu. Konflikt CAS powoduje reread/idempotency resolution.

+

7. Migracja i build projection

  1. Canonical schema/runtime w plugins/maister/skills/orchestrator-framework/.
  2. Research Phase 4 jako pion z dwoma work itemami.
  3. Migracja pozostałych workflowów po jednym call site.
  4. Binding/harness w platforms/codex-cli/.
  5. make build generuje Codex target; bez bezpośrednich edycji generated variants.
  6. Source/generated contract matrix i clean double-build bez diff.

Backward refinement jest poza zakresem; forward-only runner pozostaje.

+

8. Security i safety

  • Denylista sprawdzana w evaluatorze i runnerze.
  • Exact allowlists dla context, output, actor, confidence i target.
  • Canonical task-root paths; reject traversal/symlink ambiguity.
  • Role bez writerów, shella i mutable handles.
  • Output modelu zawsze dane, nigdy shell.
  • Low/escalation nie są podwyższane ani wyciszane.
  • Bounded retries + exponential backoff.
  • Audit bez sekretów i zbędnych promptów.
+

9. Architektura testów

WarstwaDowód
EvaluatorAgreement, oba arbitra, retry/resume, low/escalation, denylist; fake role call log.
Repository/runnerRich states, CAS, recovery i byte-exact rejection.
WorkflowDwa same-phase itemy, next phase, crash/ack/dedupe.
Codex adapterDirective union, UI spy=0 na success, exact transport.
Build/parityClean double build i source/generated contracts.
Host-native E2EReal Codex; fake tylko role/dispatcher; agreement, disagreement, oba targety, resume.

Exit 77 oznacza niedostępny runtime; tylko exit 0 realnego entrypointu pozwala ustawić supported.

+

10. Tracer bullet i rollout

  1. Schema v2 + repository + real research fixture.
  2. Agreement evaluator + fake advisor.
  3. Runner consume/verify terminal record.
  4. Dwa research itemy + durable dispatch + no UI.
  5. Jeden logiczny arbiter i oba wyniki.
  6. Next-phase + failure injection.
  7. Codex binding przy capability unsupported.
  8. Real host-E2E; dopiero potem capability flip.
R0 schema→R1 runtime→R2 tracer→R3 binding→R4 native proof→R5 migration
+

11. Kryteria akceptacji

  • Agreement: actor advisor, arbiter=0, UI=0, następny target started.
  • Disagreement: jeden logical arbiter, legalny wynik, UI=0.
  • Resume bez duplicate history/role/effect.
  • Trwałe checkpointy same-phase i next-phase.
  • Fail-closed safety i byte-exact invalid rejection.
  • Source/generated parity.
  • supported wyłącznie po native E2E.
+

12. Decyzje i źródła

Decision log · Decision log MD · Research report · Solution exploration

+
+ diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/high-level-design.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/high-level-design.md new file mode 100644 index 00000000..763f6433 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/high-level-design.md @@ -0,0 +1,421 @@ +# High-level design: automatyczna kontynuacja Codex + +## TL;DR + +Docelowa architektura łączy wykonywalną maszynę stanów z ports-and-adapters: wspólny evaluator podejmuje i zapisuje decyzję, runner ją weryfikuje i commituje projekcje/transition, a workflow loop automatycznie dispatchuje następną pracę. +Zgodność rekomendacji kończy gate aktorem `advisor`; rozbieżność uruchamia dokładnie jednego logicznego arbitra, którego nieudane wywołania są retry tego samego rekordu. +Trwałe `work_item_id`, `dispatch_id` i receipt dają logiczne exactly-once dla następnego problemu oraz następnej fazy, także po crashu. +Codex pozostaje `unsupported`, dopóki realny host-native E2E nie udowodni braku UI, utrzymania aktywnej tury i rzeczywistego kolejnego dispatchu. + +## Key Decisions + +- **A3:** jeden wspólny executable gate evaluator, sterowany read-only portem ról hosta. +- **B1:** evaluator jest właścicielem pełnego rekordu `pending → terminal`; runner konsumuje i weryfikuje ten rekord bez rekonstrukcji provenance. +- **C1:** workflow jest właścicielem stabilnego inventory i durable outbox/receipt; receiver deduplikuje efekt po `dispatch_id`. +- **D1:** cienki binding Codex mapuje wynik na `continue | user_gate | blocked` i oddaje `continue` do aktywnej pętli. +- `orchestrator.current_phase` jest jedynym mutowalnym kursorem fazy; `revision` oraz wspólne repository zabezpieczają dwóch sekwencyjnych writerów. +- Runner jest granicą trwałego commitu i forward transition, ale nigdy dispatcherem domenowej pracy. + +## Open Questions / Risks + +- Stabilny active-turn hook i headless entrypoint prawdziwego Codex wymagają krótkiego spike'a. Jeśli D1 zostanie empirycznie disproven, dopiero wtedy można rozważyć lokalny MCP adapter. +- Migracja realnych stanów z `started_phase` i uboższych rekordów historii wymaga wersjonowanej, fail-closed migracji oraz fixtures z rzeczywistych workflowów. +- Exactly-once oznacza jeden logiczny efekt; transport może fizycznie retry'ować, lecz zawsze z tym samym `dispatch_id` i idempotentnym receiverem. +- Dwa procesy zapisujące YAML muszą używać tego samego locka, atomic rename i revision/CAS; bez tego możliwy jest lost update. + +## 1. Styl architektury i zakres + +**Styl:** wykonywalna state machine w architekturze ports-and-adapters, osadzona w istniejącym single-source/multi-target plugin pipeline. Nie powstaje usługa, daemon ani baza danych. + +Projekt obejmuje osiem komponentów runtime: + +| # | Komponent | Odpowiedzialność | Nie odpowiada za | +|---:|---|---|---| +| 1 | Workflow loop | Materializuje inventory, aplikuje wybór, wyznacza target i kontynuuje aż do terminalnego stopu | Reguły agreement/arbitration | +| 2 | Gate evaluator | Policy, denylista, walidacja outputu, retry, agreement, jeden logiczny arbiter, terminalny record | Raporty i domenowy routing | +| 3 | Role invoker port | Read-only wywołanie `advisor` lub `arbiter` przez host | Mutacje state i wybór polityki | +| 4 | State repository | Lock, odczyt schema, revision/CAS, invariant checks, atomic write | Semantyka workflowu | +| 5 | Continuation runner | Reuse terminal recordu, preflight, raporty/dashboard, forward phase transition | Wywołania modeli i dispatch pracy | +| 6 | Codex binding | Łączy native role port, evaluator i runner; zwraca dyrektywę do aktywnej tury | Własna state machine lub własny audit | +| 7 | Dispatcher/receiver | Wykonuje target z `dispatch_id`, deduplikuje logiczny efekt, zapisuje ack | Wyliczanie domenowego next targetu | +| 8 | Projection generator | Generuje decision summary/dashboard z canonical state | Źródło resume lub decyzji | + +```text +User / workflow invocation + | + v ++-------------------+ +---------------------+ +| 1. Workflow loop |------>| 2. Gate evaluator | +| inventory + route | | executable FSM | ++---------+---------+ +----+-----------+----+ + ^ | | + | continue | v + | +----v----+ +----------------+ + | | 3. Role | | 4. State repo | + | | port | | lock/CAS/write | + | +---------+ +-------+--------+ + | | + | +-------------------v--+ + +------------------| 6. Codex binding | + +----+-------------+--+ + | | + +---------v--+ +----v-------------+ + | 5. Runner | | 7. Dispatcher | + | commit | | receipt/dedupe | + +-----+-----+ +------------------+ + | + +-----v-------------+ + | 8. Projections | + +-------------------+ +``` + +## 2. Granice i porty + +### 2.1 `evaluateGate(gateContext, roleInvoker, stateRepository)` + +Wejście zawiera dokładny `phase_id`, stabilny `gate_type`, pytanie, uporządkowane opcje, `original_recommendation`, safety i read-only context. Evaluator: + +1. wylicza idempotency key; +2. reużywa terminalny rekord przed wywołaniem hosta; +3. zapisuje pending i każdą próbę przed call'em; +4. wywołuje role wyłącznie przez `roleInvoker`; +5. waliduje exact czteropolowy output; +6. zapisuje pełny terminalny envelope albo fail-closed stan. + +```js +roleInvoker.invoke({ + role: "advisor" | "arbiter", + logical_role_id: "sha256:...", + attempt: 1, + gate: { idempotency_key, question, options, original_recommendation }, + read_only_context: { task_path, phase_summaries, artifacts, prior_gate_history } +}) +// -> { selected_option, rationale, confidence, escalate_to_user } +``` + +Role port nie otrzymuje writerów, ścieżek wyjściowych ani prawa rozszerzenia scope. Arbiter dodatkowo otrzymuje dokładnie dwie konkurujące opcje wraz z uzasadnieniami i może zwrócić wyłącznie jedną z nich. + +### 2.2 `continuePhase(commitRequest, stateRepository)` + +Runner dostaje klucz istniejącego terminalnego recordu, oczekiwany wybór i opcjonalny forward target. Ponownie czyta state, sprawdza revision i inwarianty, generuje projekcje oraz zapisuje phase transition/receipt. Nie dostaje odpowiedzi modeli i nie syntetyzuje historii. + +```json +{ + "state": ".../orchestrator-state.yml", + "idempotency_key": "sha256:...", + "expected_selected_option": "A", + "expected_revision": 41, + "next_phase": "phase-5", + "report_md": ".../decision-summary.md", + "report_html": ".../decision-summary.html" +} +``` + +### 2.3 `dispatch(target, dispatchId)` + +Workflow wyznacza target, a Codex binding/dispatcher wykonuje go. Receiver sprawdza receipt przed efektem i atomowo zapisuje `acknowledged` po ustanowieniu obserwowalnego checkpointu targetu. + +```js +dispatcher.dispatch({ + dispatch_id: "sha256:...", + kind: "same_phase_work_item" | "phase_entry", + phase_id: "phase-4", + work_item_id: "decision-area:persistence-boundary" +}) +// -> { directive: "continue", dispatch_id, checkpoint } +``` + +### 2.4 Dyrektywa hosta + +Binding zwraca zamknięty union: + +- `continue` — terminalny gate i wymagane durable efekty są gotowe; workflow ma ponownie odczytać state i wykonać target; +- `user_gate` — gate jest manualny/denylisted albo bezpieczny fallback wymaga użytkownika; +- `blocked` — brak bezpiecznej automatycznej lub interaktywnej ścieżki. + +Żaden poprawny `continue` nie może zostać zamieniony w końcową odpowiedź assistant turn. + +## 3. Kanoniczny model stanu + +State pozostaje pojedynczym snapshotem YAML. `schema_version` umożliwia migrację, `revision` rośnie przy każdym legalnym atomicznym zapisie, a `current_phase` wskazuje dokładnie jedną fazę `in_progress`. + +```yaml +orchestrator: + schema_version: 2 + revision: 42 + current_phase: phase-4 + initial_phase: phase-1 + completed_phases: [phase-1, phase-2, phase-3] + failed_phases: [] + gate_history: + - schema_version: 2 + idempotency_key: sha256:gate-key + phase_id: phase-4 + gate_type: research-convergence + question: "Które podejście wybrać?" + options: [A, B, "Need more info"] + original_recommendation: A + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: B + final_actor: arbiter + advisor: + logical_role_id: sha256:advisor-id + agent: advisor + model: gpt-5.6-sol + response: {selected_option: B, rationale: "...", confidence: high, escalate_to_user: false} + attempts: + - {number: 1, status: completed, started_at: "...", completed_at: "...", error: null} + exhausted: false + arbiter: + logical_role_id: sha256:arbiter-id + agent: arbiter + model: gpt-5.6-sol + response: {selected_option: B, rationale: "...", confidence: high, escalate_to_user: false} + attempts: + - {number: 1, status: completed, started_at: "...", completed_at: "...", error: null} + exhausted: false + rationale: "..." + confidence: high + escalate_to_user: false + user_override: false + continuation: + kind: same_phase_work_item + target_id: decision-area:persistence-boundary + dispatch_id: sha256:dispatch-id + status: acknowledged + error: null + work: + phase-4: + inventory_version: sha256:artifact-derived-version + items: + - id: decision-area:execution-owner + ordinal: 1 + status: completed + source_gate_key: sha256:previous-gate + selected_option: A + - id: decision-area:persistence-boundary + ordinal: 2 + status: in_progress + source_gate_key: null + selected_option: null + dispatch_outbox: + - dispatch_id: sha256:dispatch-id + source_gate_key: sha256:gate-key + kind: same_phase_work_item + phase_id: phase-4 + target_id: decision-area:persistence-boundary + status: acknowledged + attempts: 1 + checkpoint: gate-context-materialized + error: null +``` + +### Inwarianty + +1. `current_phase` wskazuje dokładnie jedną fazę `in_progress`. +2. Jeden idempotency key odpowiada jednemu rekordowi historii, aktualizowanemu in-place pending → terminal. +3. Rekord `decided` ma legalną `selected_option`, terminalnego aktora i pełne provenance właściwe dla tego aktora. +4. Jedna rozbieżność ma jeden `arbiter.logical_role_id`; retry zwiększa `attempts[]`, nie liczbę arbitrów. +5. Jeden `dispatch_id` odpowiada jednemu source gate i targetowi; ponowna próba nie może zmienić targetu. +6. Item może przejść `ready → in_progress → completed|blocked`; nie wraca wstecz bez osobnego, jawnego reset protocol. +7. Dashboard i raporty są projekcjami `gate_history`; nigdy nie sterują resume. + +## 4. Sekwencje decyzji + +### 4.1 Zgodność głównego agenta i advisora + +```text +Workflow Evaluator Repository Advisor Runner Dispatcher + | gate | | | | | + |------------->| key/reuse | | | | + | |--lock+CAS----->| advisor_pending + attempt | | + | |-------------------------------->| invoke | | + | |<--------------------------------| A/high | | + | |--lock+CAS----->| decided(actor=advisor) | | + | |------------------------------->| | | + | |---------------------------------------------->| verify/report| + |<-------------| continue terminal+reports durable | | + | apply choice + enqueue same dispatch_id | | + |---------------------------------------------------------------------------->| + |<----------------------------------------------------------------------------| ack + | start next work item in the same turn | +``` + +Arbiter calls = 0, user-gate calls = 0. Zapis `decided` następuje przed raportami, cursorem i dispatch'em. + +### 4.2 Rozbieżność i jeden logiczny arbiter + +```text +Evaluator -> Repository: advisor_pending + advisor attempt started +Evaluator -> Advisor: original=A, ordered options +Advisor --> Evaluator: B/high/no escalation +Evaluator -> Repository: advisor response + arbiter_pending +Evaluator -> Repository: one logical_arbiter_id + attempt 1 started +Evaluator -> Arbiter: only {A + rationale, B + rationale} +Arbiter --> Evaluator: timeout +Evaluator -> Repository: attempt 1 failed; backoff; attempt 2 started +Evaluator -> Arbiter: same logical_arbiter_id +Arbiter --> Evaluator: A/high/no escalation +Evaluator -> Repository: decided(actor=arbiter, selected=A) +Evaluator -> Runner: verify terminal record and project +Runner --> Workflow: continue +``` + +Resume z `arbiter_pending` nie wywołuje advisora i nie tworzy nowego `logical_arbiter_id`. + +### 4.3 Fail-closed + +Denylista omija role i automatyczny runner. Low confidence, `escalate_to_user: true`, exhaustion, invalid output po limicie, unsupported capability lub błąd legalnego commitu kończą się `user_gate` w sesji interaktywnej albo `blocked`. Nie wolno przesunąć itemu/fazy ani utworzyć dispatchu. + +## 5. Same-phase i next-phase continuation + +### Same phase + +1. Workflow materializuje stabilne inventory z artefaktu i zapisuje `inventory_version`. +2. Po terminalnym gate idempotentnie zapisuje wybór w itemie N i oznacza go `completed`. +3. Ponownie oblicza zależne inventory; istniejące ID nie zmieniają znaczenia. +4. Następny item N+1 przechodzi do `ready`, a outbox otrzymuje deterministyczny `dispatch_id` związany z source gate i targetem. +5. Dispatcher ustanawia checkpoint N+1, receiver deduplikuje ID i zapisuje ack. +6. Binding zwraca `continue`; loop od razu renderuje lub wykonuje N+1 bez pytania o kontynuację. + +### Next phase + +1. Runner po raportach atomowo oznacza source `completed`, target `in_progress`, aktualizuje `current_phase`, timestamps i continuation intent. +2. Workflow tworzy `phase_entry` outbox item z deterministycznym `dispatch_id`. +3. Dispatcher uruchamia body target phase i zapisuje obserwowalny checkpoint startu. +4. Ack zamyka receipt. Samo ustawienie `current_phase` bez checkpointu nie jest dowodem wejścia do fazy. + +Phase-entry self-check akceptuje terminalny automatyczny rekord + zgodny applied transition/receipt jako równoważny dowód wobec historycznego user-question call ID. + +## 6. Persistence, awarie i recovery + +Kanoniczna kolejność: + +```text +1. lock + read + schema/invariant validation +2. pending + attempt started; revision++ ; atomic fsync+rename +3. role response/attempt result; revision++ +4. full terminal gate + continuation intent; revision++ +5. dashboard/report projection from persisted state +6. apply selection + work cursor or phase transition + outbox; revision++ +7. dispatch(target, same dispatch_id) +8. durable acknowledgement/checkpoint; revision++ +``` + +| Crash window | Stan po restarcie | Recovery | +|---|---|---| +| Przed pending write | Brak nowej historii | Bezpiecznie rozpocząć gate | +| Po `attempt: started` | Pending attempt | Zamknąć jako interruption/timeout i zużyć slot | +| Po odpowiedzi advisora | Persisted response | Nie ponawiać zakończonej roli | +| W `arbiter_pending` | Jeden logical arbiter | Ponowić wyłącznie jego następną próbę | +| Po terminalnym gate, przed raportem | `decided`, brak projekcji | Regenerować raport bez modelu i bez duplicate history | +| Po raporcie, przed outbox | Terminal + projekcje | Idempotentnie zastosować wybór i utworzyć target | +| Po outbox, przed efektem | `pending` dispatch | Retry ten sam `dispatch_id` | +| Po efekcie, przed ack | Niepewny transport | Receiver deduplikuje `dispatch_id`, następnie zapisuje ten sam ack | +| Po ack | Target checkpoint durable | Reuse i kontynuacja bez redispatchu | + +Invalid payload, changed terminal selection i invalid transition są odrzucane przed legalnym commitem z byte-exact zachowaniem state, raportów, modes i topologii katalogów. Awaria po terminalnym commicie nie cofa decyzji; recovery dokańcza projekcję lub continuation. + +## 7. Concurrency i state repository + +Wspólny `state-repository` jest małym, bezpośrednio używanym modułem, nie generyczną warstwą persistence. Zapewnia: + +- jeden project-local advisory/exclusive lock dla ścieżki state; +- timeout locka kończący się bez mutacji; +- parse + exact-schema + invariant validation pod lockiem; +- `expected_revision` compare-and-swap; +- zapis do pliku tymczasowego w tym samym katalogu, `fsync`, atomic rename i opcjonalny directory `fsync`; +- zachowanie mode/ownership zgodnie z istniejącym kontraktem; +- wzrost `revision` dokładnie raz na legalny commit. + +Evaluator zwalnia lock przed długim role call'em, ponieważ pending jest już trwały. Po odpowiedzi ponownie bierze lock i używa CAS; konflikt revision powoduje reread i idempotency resolution, nie blind overwrite. Runner działa dopiero na terminalnym recordzie i również używa CAS. Nie ma jednoczesnej, długo trzymanej transakcji przez model, raporty i host dispatch. + +## 8. Migracja call sites i build projection + +Migracja powinna następować pionami, bez bezpośrednich edycji generated variants: + +1. **Canonical schema/runtime:** `plugins/maister/skills/orchestrator-framework/` — evaluator, repository, runner i zsynchronizowane references/fixtures. +2. **Research tracer:** Phase 4 materializuje dwa work itemy, korzysta z binding result i usuwa wymaganie UI call ID na poprawnej ścieżce auto. +3. **Pozostałe call sites:** product-design, development, migration i performance przyjmują ten sam gate envelope; tylko workflow-specific inventory/routing pozostaje lokalne. +4. **Codex adapter:** nowe host binding/harness w `platforms/codex-cli/`; `advisor.toml` pozostaje read-only profilem. +5. **Build projection:** `platforms/codex-cli/build.sh` jawnie kopiuje wymagane runtime files; `make build` regeneruje `plugins/maister-codex/`. +6. **Parity:** wspólne contract tests uruchamiają source i generated runners; drugi clean build ma zero diff. + +Backward refinement z product-design nie jest częścią tej naprawy. Forward-only phase transition pozostaje niezmieniony; ewentualny reset protocol wymaga osobnej decyzji. + +## 9. Bezpieczeństwo + +- Hard denylista jest sprawdzana przez evaluator i ponownie przez runner; denylisted gate nie wywołuje roli, auto continuation ani dispatchu. +- Exact allowlists obejmują gate context, czteropolowy output ról, actor/confidence, terminal record, target kind i phase transition. +- Ścieżki state/report są canonicalizowane i ograniczone do task root; symlink/path traversal są odrzucane. +- Advisor i arbiter mają read-only context, nie dostają shella, writerów ani mutable artifact handles. +- Model output jest danymi, nigdy fragmentem komendy; runner przyjmuje JSON na stdin albo `--input-file`. +- Low confidence i eskalacja nie mogą zostać automatycznie podwyższone lub wyciszone. +- Retry ma skończony budżet i exponential backoff; exhaustion kończy się manual/block. +- Logi i decision summary przechowują provenance, ale nie powinny kopiować sekretów ani niepotrzebnego pełnego promptu. + +## 10. Architektura testów + +| Warstwa | Dowód | Kluczowe przypadki | +|---|---|---| +| Evaluator unit/contract | Wykonywalna FSM z fake role port i call logiem | agreement; oba wyniki arbitra; retry; resume pending; low/escalation; denylist | +| Repository/runner contract | Atomic writes, full record reuse, report/transition recovery | rich real-state fixtures; CAS conflict; changed selection; byte-exact rejection | +| Workflow integration | Fake dispatcher i trwały receipt | dwa zależne same-phase itemy; next phase; crash przed/po ack; dedupe | +| Codex adapter integration | Native binding z fake rolami/UI spy | `continue|user_gate|blocked`; UI=0 na success; dokładny payload/exit/stdout | +| Build/parity | Source → generated | clean double build; source/generated contract matrix; manifest/runtime wiring | +| Host-native Codex E2E | Rzeczywisty host, fake tylko role/dispatcher | agreement + disagreement; same-phase + next-phase; no UI; resume; real checkpoint | + +Capability E2E zwraca `77`, gdy runtime jest niedostępny. Tylko exit `0` z rzeczywistego Codex entrypointu jest dowodem `supported`; shared Node test ani smoke prose nie wystarcza. + +## 11. Rollout i tracer bullet + +### Tracer bullet + +1. Wprowadzić schema v2, `current_phase`, `revision` i repository oraz migrację jednego realnego research fixture. +2. Zaimplementować evaluator agreement z fake advisor portem i pełnym terminalnym recordem. +3. Zmienić runner na consume/verify terminal record, zachowując report recovery. +4. Zmaterializować dokładnie dwa research decision areas; po pierwszym gate utworzyć durable dispatch do drugiego i potwierdzić `continue` bez UI. +5. Dodać disagreement z jednym logicznym arbitrem i oboma legalnymi wynikami. +6. Dodać next-phase target oraz failure injection dla raportu, transition i dispatchu. +7. Włączyć cienki Codex binding za capability `unsupported`, uruchomić clean build i pełną walidację. +8. Wykonać realny Codex E2E; dopiero po zielonym dowodzie zmienić capability na `supported` i sprawdzić projekcję. + +### Rollout gates + +- **R0 — schema contract:** rich fixtures i migracja przechodzą; brak call-site flipu. +- **R1 — shared runtime:** evaluator/runner/repository tests zielone; stara manualna ścieżka nadal działa. +- **R2 — research tracer:** dwa itemy automatycznie przechodzą z logicznym exactly-once. +- **R3 — Codex binding:** adapter integration i build parity zielone, capability nadal `unsupported`. +- **R4 — native proof:** realny host-E2E obserwuje no UI i oba rodzaje dispatchu; capability flip w osobnym, małym commicie. +- **R5 — broader migration:** pozostałe workflowy migrowane po jednym, z własnym inventory testem. + +Rollback przed R4 polega na pozostawieniu capability `unsupported` i użyciu manualnego/user gate fallbacku. Nie należy degradować denylisty ani omijać terminalnego audit recordu, aby ratować automatyzację. + +## 12. Kryteria akceptacji projektu + +Projekt jest wdrożony poprawnie dopiero, gdy: + +- agreement daje `final_actor: advisor`, zero arbitra, zero UI i rozpoczyna następny target; +- disagreement daje jeden logical arbiter, legalny wynik, zero UI i następny target; +- resume nie powiela historii, zakończonych role calls ani logicznego efektu dispatchu; +- same-phase i next-phase mają obserwowalny, trwały checkpoint; +- denylista/low/escalation/exhaustion/unsupported pozostają fail-closed; +- invalid input i zmieniona terminalna decyzja zachowują byte-exact stan; +- source i generated variants przechodzą contract matrix oraz clean rebuild; +- capability Codex jest `supported` wyłącznie po zielonym host-native E2E. + +## 13. Powiązane decyzje i źródła + +- [Decision log](decision-log.md) +- [Research report](research-report.md) +- [Solution exploration](solution-exploration.md) +- `../analysis/synthesis.md` +- `../analysis/findings/01-gate-state-contract.md` +- `../analysis/findings/02-continuation-dispatch.md` +- `../analysis/findings/03-codex-host-adapter.md` +- `../analysis/findings/04-verification-safety.md` +- `.maister/docs/project/architecture.md` +- `.maister/docs/standards/global/build-pipeline.md` +- `.maister/docs/standards/testing/test-writing.md` diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/research-report.html b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/research-report.html new file mode 100644 index 00000000..bd1485d2 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/research-report.html @@ -0,0 +1,391 @@ + + + + +Automatyczna kontynuacja Codex — raport badawczy + + + + + +
+ Research report +

Jak naprawić automatyczną kontynuację Codex

+

Techniczne badanie control flow, canonical state, adaptera hosta, dispatchu i dowodów capability.

+
+ +
+
4strumienie findings
+
18scenariuszy testowych
+
Highconfidence root cause
+
77obecny Codex E2E
+
+ +
+

TL;DR

+

To powinno działać automatycznie: zgodność kończy gate decyzją advisora; rozbieżność uruchamia dokładnie jednego logicznego arbitra; poprawny wynik jest trwale commitowany i od razu przekazywany do następnego problemu lub fazy bez kliknięcia.

+

Brakuje wykonywalnego łańcucha evaluator → runner → adapter Codex → workflow loop. Runner commit nie jest dispatcherem. Po sukcesie adapter musi zwrócić sterowanie do workflow loop bez kończenia tury.

+

Key Decisions

+
    +
  • Wspólny executable evaluator dla agreement, arbitration, retry i denylisty.
    • +
  • Canonical current_phase, pełny gate_history, trwały work-item cursor i receipt.
    • +
  • Evaluator wybiera, runner utrwala, adapter transportuje, workflow loop routuje.
    • +
  • Dowód obejmuje next problem w tej samej fazie oraz body następnej fazy.
    • +
  • Capability flip dopiero po realnym Codex E2E.
    • +
+

Open Questions / Risks

+
    +
  • Headless entrypoint Codex i fake-role injection wymagają krótkiego spike'a.
    • +
  • Schema musi być jedno dla prose, runtime i fixtures.
    • +
  • Exactly-once oznacza logiczny efekt z dispatch_id, nie brak fizycznych retry.
    • +
  • Backward refinement wymaga osobnego reset protocol.
    • +
+
+ + + +
+
+

1. Odpowiedź: docelowe zachowanie

+
    +
  1. Główny agent tworzy stabilny gate context z dokładnymi opcjami i rekomendacją.
    2. +
  2. Evaluator utrwala advisor_pending i próbę started, potem wywołuje read-only advisora.
    3. +
  3. Agreement + high/medium + brak eskalacji kończy gate aktorem advisor; bez arbitra i UI.
    4. +
  4. Disagreement tworzy jeden logical arbiter; wszystkie retry należą do jego attempts[].
    5. +
  5. Arbiter wybiera tylko original albo advisor; poprawny wynik kończy gate aktorem arbiter.
    6. +
  6. Pełny terminal record jest trwały przed raportami i continuation.
    7. +
  7. Runner weryfikuje record, odtwarza raporty i opcjonalnie przełącza fazę.
    8. +
  8. Adapter zwraca continue, nie kończy tury i nie pyta użytkownika.
    9. +
  9. Workflow loop aplikuje wybór, przesuwa cursor i od razu dispatchuje następną pracę.
    10. +
  10. Automatyczny ciąg kończy dopiero brak pracy albo zawsze-user-controlled final gate.
    11. +
+
+ +
+

2. Obecny łańcuch awarii

+
workflow gate call site + → instrukcje agreement/arbitration w Markdown + → profil advisora w advisor.toml + → BRAK executable evaluatora/adaptera + → phase-continue.mjs (jeżeli wywołany) + ├─ terminal commit + ├─ raporty + ├─ opcjonalny current_phase transition + └─ stdout JSON + process exit + → BRAK consumer → effect → cursor → dispatch
+
+
Prompt only

advisor.toml opisuje zachowanie, ale nie wykonuje go.

+
Smoke only

smoke-cli.sh sprawdza frazy, nie role/runner/dispatch.

+
Unavailable

Codex E2E zawsze zwraca 77.

+
Commit only

phase-continue.mjs kończy się po stdout; nie uruchamia workflow.

+
+

High confidence Shared runner i contract tests są zielone; native Codex continuation nie ma dowodu.

+
+ +
+

3. Jednoznaczny algorytm

+
+
+

Agreement

+

Wymaga: non-denylisted, fully_automatic, supported capability, exact four-field output, exact option membership, exact equality z original, high/medium i brak eskalacji.

+

Efekt: 1 terminal record, actor advisor, arbiter 0, UI 0.

+
+
+

Disagreement

+

Najpierw trwały advisor result, potem jedna mapa i jeden logical_arbiter_id. Retry dopisują attempts. Arbiter może wybrać tylko dwie konkurujące rekomendacje.

+

Efekt: actor arbiter, bez powrotu do advisora i bez UI.

+
+
+ + + + + + + + + + +
WarunekZachowanieZakaz
Hard denylistuser_pending / blockedadvisor, arbiter, runner, dispatch
Low confidence / escalationmanual / blockedautomatic selection
Retry exhaustionmanual / blockedinfinite retry / approval
Invalid schema/optionbounded retry, potem fallbackselection commit
Unsupported capabilitymanual / blockedudawana kontynuacja
Persistence/runner errorstop + resumable statecursor/phase advance
+
+ +
+

4. Canonical state, history i durability

+
+
    +
  • orchestrator.current_phase wskazuje dokładnie jedną fazę in_progress.
    • +
  • started_phase znika albo staje się niemutowalnym initial_phase.
    • +
  • Jeden idempotency key = jeden gate record aktualizowany pending → terminal.
    • +
  • Pełny record zawiera context, policy/safety, ordered options, original, advisor/arbiter responses i attempts, actor, confidence i continuation.
    • +
  • Runner weryfikuje persisted record; nie rekonstruuje original/rationale.
    • +
+
+
+ Przykładowy pełny envelope +
schema_version: 1
+idempotency_key: sha256:...
+phase_id: phase-4
+gate_type: research-convergence
+options: [A, B, "Need more info"]
+original_recommendation: A
+policy: fully_automatic
+safety_classification: configurable
+status: decided
+selected_option: B
+final_actor: arbiter
+advisor: {agent: advisor, model: "...", response: {...}, attempts: [], exhausted: false}
+arbiter: {logical_arbiter_id: sha256:..., agent: arbiter, response: {...}, attempts: []}
+continuation: {kind: same_phase_work_item, target: decision-area:persistence-boundary, status: pending}
+
+
+ Stable same-phase inventory +
decision_areas:
+  - {id: execution-owner, ordinal: 1, status: completed, gate_key: sha256:..., chosen_approach: host-workflow-loop}
+  - {id: persistence-boundary, ordinal: 2, status: ready, gate_key: null, chosen_approach: null}
+

Target niesie work_item_id, source_gate_key, dispatch_id i status. Ordinal nie jest identity.

+
+
1 pending + attempt started +→ 2 role result +→ 3 full terminal gate + continuation pending +→ 4 reports/dashboard from persisted state +→ 5 apply selection + cursor/transition intent +→ 6 dispatch(target, dispatch_id) +→ 7 applied/completed receipt
+

Report failure nie cofa terminalnej decyzji; retry regeneruje. Odrzucenie przed legalnym commitem zachowuje byte-exact state, raporty, modes i topology.

+
+ +
+

5. Ownership split

+ + + + + + + + +
WarstwaOdpowiada zaNie odpowiada za
Evaluatorpolicy, denylist, roles, validation, agreement, one arbiter, retry, terminal recorddomenowy routing
Runnerpreflight, terminal reuse/verification, raporty, forward transitionmodele, decision areas, host turn
Codex adapternative delegation port, exact transport, stdout validation, continue/user_gate/blockedwłasny schema/cursor/routing
Workflow loopgate effect, cursor, next target, immediate dispatchponowna implementacja safety
+
Kontrakt krytyczny: successful adapter execution returns control to the workflow loop without ending the turn.
+
+ +
+

6. Same-phase vs next-phase continuation

+
+
+

Same phase

+
    +
  1. Commit gate area N.
  2. Zapisz choice/gate key/completed.
    3. +
  3. Ponownie wylicz area N+1.
  4. Ustaw ready + dispatch_id.
    5. +
  5. Adapter → continue; loop startuje N+1 w tej samej turze.
    6. +
+

Nie używać next_phase i nie pre-renderować zależnych areas.

+
+
+

Next phase

+
    +
  1. Runner ustawia source completed.
  2. Target in_progress.
    3. +
  3. current_phase=target.
  4. Adapter → continue.
    5. +
  5. Loop uruchamia body i zapisuje pierwszy checkpoint.
    6. +
+

Sama zmiana statusu nie jest dowodem dispatchu.

+
+
+
+ +
+

7. File-by-file change map

+ + + + + + + + + + + + + + + + + + + + +
Plik / grupaZmiana
.../bin/gate-evaluate.mjs (new)Executable agreement/arbitration/retry/resume + pełny record.
.../bin/phase-continue.mjsWeryfikacja terminal recordu, shared schema, current_phase, receipt, strict stdout; bez domenowego dispatchu.
gate-decision-engine.mdSchema zgodne z runtime, ownership i recovery.
orchestrator-patterns.mdcurrent_phase, cursor/dispatch, auto entry proof, do-not-end-turn.
gate-decision-fixtures.ymlExecutable inputs, expected state i call counts.
host-capabilities.ymlFlip dopiero po native E2E.
research/SKILL.mdTerminal result, stable area cursor, return to loop, auto self-check.
product-design/SKILL.mdShared loop + osobny backward reset.
development/SKILL.mdScope work items, runner consumer, auto entry proof.
Pozostałe orchestratoryInventory migration started_phase → current_phase i pełny gate envelope.
platforms/codex-cli/ bindingNative role port, evaluator, runner transport, stdout validation, continue without UI/end-turn.
advisor.tomlRead-only profile wskazujący real adapter.
build.sh / smoke-cli.shCopy i executable wiring assertions.
Codex E2EReal host test; 77 tylko gdy runtime faktycznie niedostępny.
Evaluator/runner/loop tests + fixturesFull state, failure injection, call/UI/dispatch counters i byte-exact assertions.
MakefileFast suites, bez osłabienia native capability proof.
+
Generated effects: plugins/maister-{codex,cursor,kiro}/ powstają przez make build. Nie edytować ich bezpośrednio.
+
+ +
+

8. Implementation order

+
    +
  1. Schema + real-state fixtures.
    2. +
  2. Executable evaluator.
    3. +
  3. Runner contract consuming persisted result.
    4. +
  4. Workflow-loop tracer bullet: dwa same-phase items.
    5. +
  5. Codex adapter integration z fake ports.
    6. +
  6. Call-site migration i self-check fix.
    7. +
  7. Build projection.
    8. +
  8. Native Codex E2E.
    9. +
  9. Capability flip.
    10. +
+
+ +
+

9. Executable test matrix

+ + + + + + + + + + + + + + + + + + + + + + +
ScenariuszPozytywne asercjeSafety asercje
Advisor agreesactor advisor; terminal; reports; next dispatcharbiter 0; UI 0; no duplicates
Arbiter chooses original1 logical arbiter; original; continuationno advisor return; UI 0
Arbiter chooses advisor1 logical arbiter; advisor; continuationno third option; UI 0
Next decision areaN complete; N+1 started; same turnno premature phase end/double dispatch
Next phasetransition + first target checkpointno stop after status only
Advisor retrypersisted attempts/backoffbounded; no arbiter without disagreement
Arbiter retryone logical record, many attemptsadvisor not reinvoked
Resume pendingsame key/role/budgetno reset/new role
Exhaustionuser_pending / blockedrunner/dispatch 0
Report failureterminal durable; one recoveryno duplicate history
Transition failureone resumed transitionno two active phases
Dispatch failuresame dispatch_id; idempotent effectno new gate/effect
Denylistmanual / blockedadvisor/arbiter/runner/dispatch 0
Low/escalationmanual / blockedno auto selection
Invalid outputbounded retry/fallbackno selection commit
Changed terminal selectionnon-zerobyte-exact all artifacts/modes/topology
Build projectionbinding present; second build no diffno manual generated edits
Runtime unavailableE2E 77cannot project supported
+
+

Deterministyczna obserwowalność

+

Fake role używa tego samego portu co native Codex i loguje gate key, role, logical arbiter, attempt i input hash. Fake dispatcher deduplikuje po dispatch_id i loguje attempt/ack. UI spy failuje każde pytanie na pozytywnej ścieżce. Native E2E nadal uruchamia prawdziwy Codex entrypoint; fake zastępuje tylko model.

+
+
+ +
+

10. Acceptance criteria

+
+
    +
  • Agreement: actor advisor, bez arbitra i UI.
    • +
  • Disagreement: jeden logical arbiter; oba wyniki executable-tested.
    • +
  • Pełny audyt i raporty trwałe przed continuation.
    • +
  • Następny problem faktycznie startuje w tej samej turze.
    • +
  • Next phase dowodzi body/checkpointu, nie tylko statusu.
    • +
  • Resume nie duplikuje gate, arbitra ani logicznego dispatchu.
    • +
  • Denylist/low/escalation/exhaustion/invalid/failure pozostają fail-closed.
    • +
  • Real workflow state przechodzi shared strict schema.
    • +
  • make build && make validate przechodzi bez driftu.
    • +
  • Native Codex E2E = 0; unavailable runtime = 77 + unsupported.
    • +
+
+
+ +
+

11. Rollout i capability flip

+
+
Gate 1

Shared contract

Evaluator, runner, schema, fixtures i loop integration zielone. Codex nadal unsupported.

+
Gate 2

Codex integration

Fake-port adapter integration i reproducible build zielone. Codex nadal unsupported.

+
Gate 3

Native evidence

Real Codex E2E: agreement, arbiter, same/next phase, UI=0, resume. Dopiero wtedy supported.

+
+

Smoke frazy, manual override i shared runner tests nie zastępują Gate 3. Zachować Makefile fail-closed projection dla exit 0/77/failure.

+
+ +
+

12. Risks, gaps i confidence

+ + + + + + + + + + + + +
FindingConfidenceRyzyko
Brak executable Codex adapteraHighBrak stabilnego native harnessu
Runner commit ≠ dispatcherHighStdout/transition może zostać mylnie uznany za continuation
Return to loop bez końca turyHighZależność od host execution turn
Agreement/one-arbiter algorithmHighDziś prose-tested
current_phase canonicalHighMigracja istniejących states
Durable cursor/dispatch_idHighFinalna serializacja wymaga review
Native binding shapeMediumPotrzebny headless spike
Exactly-once logical effectMedium-highReceiver musi deduplikować dispatch_id
+
+ +
+

13. Źródła

+
+

Źródła pierwszego rzędu: gate engine i orchestrator patterns, phase-continue.mjs, workflowy research/product-design/development, Codex advisor template/build/smoke/E2E, gate/runner contract tests oraz host capability matrix.

+

Pełne dowody cząstkowe:

+ +
+
+
+ + diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/research-report.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/research-report.md new file mode 100644 index 00000000..8111e99e --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/research-report.md @@ -0,0 +1,376 @@ +# Raport badawczy: jak naprawić automatyczną kontynuację Codex + +## TL;DR + +To powinno działać automatycznie i naprawa jest jednoznaczna: zgodność rekomendacji kończy gate decyzją advisora; rozbieżność uruchamia dokładnie jednego logicznego arbitra; poprawny wynik jest trwale commitowany i natychmiast przekazywany do następnego problemu lub fazy bez kliknięcia użytkownika. +Brakującym elementem nie jest sam wybór opcji, lecz wykonywalny łańcuch `evaluator → runner → adapter Codex → workflow loop`. +`phase-continue.mjs` pozostaje bezpieczną granicą commitu i transition — **runner commit nie jest dispatcherem**. +Po sukcesie adapter musi zwrócić sterowanie do pętli workflow w tej samej turze; zakończenie odpowiedzi po stdout runnera jest obecnym punktem awarii. + +## Key Decisions + +- Zaimplementować wspólny, wykonywalny evaluator agreement/arbitration zamiast polegać wyłącznie na instrukcjach Markdown. +- Ujednolicić canonical state: `current_phase`, pełny `gate_history`, trwały work-item cursor i continuation receipt. +- Zachować ścisły podział: evaluator wybiera, runner utrwala, Codex adapter wykonuje transport, workflow loop routuje następną pracę. +- Potwierdzić obie kontynuacje: kolejny problem w tej samej fazie i faktyczne wejście do następnej fazy. +- Flip `unsupported → supported` wykonać dopiero po zielonym, rzeczywistym Codex E2E. + +## Open Questions / Risks + +- Stabilny headless entrypoint Codex i mechanizm wstrzyknięcia fake role invokera wymagają implementacyjnego spike'a. +- Exact schema pełnego rekordu i receipt trzeba skonsolidować w jednym module/fixture, żeby uniknąć kolejnego rozjazdu prose–runtime. +- Exactly-once dotyczy logicznego efektu; fizyczny dispatch może być ponowiony po przerwaniu, ale zawsze z tym samym `dispatch_id` i deduplikacją. +- Product-design backward refinement wymaga osobnego reset protocol; nie powinien być przemycony jako osłabienie forward-only runnera. + +## 1. Odpowiedź: docelowe zachowanie + +Dla każdego bezpiecznego, niedenylistowanego gate'u `fully_automatic`: + +1. Główny agent tworzy stabilny gate context: `phase_id`, `gate_type`, dokładne pytanie, uporządkowane opcje, `original_recommendation`, safety i read-only context. +2. Evaluator zapisuje `advisor_pending` i próbę `started`, po czym wywołuje read-only advisora. +3. Jeśli advisor zwraca dokładnie `original_recommendation`, `confidence: high|medium` i `escalate_to_user: false`, evaluator zapisuje terminalne `decided`, `final_actor: advisor`. Arbiter i user UI nie są wywoływani. +4. Jeśli advisor wskazuje inną opcję, evaluator tworzy jeden logiczny rekord `arbiter` i wywołuje go. Retry są kolejnymi `attempts[]` tego samego arbitra; advisor nie jest wywoływany ponownie. +5. Arbiter może wybrać wyłącznie rekomendację głównego agenta albo advisora. Poprawny `high|medium`, bez eskalacji, kończy gate aktorem `arbiter`. +6. Pełny terminalny rekord jest trwale zapisany przed raportami i przed continuation. +7. Runner waliduje terminalny rekord, regeneruje raporty i — dla exit gate'u — atomowo przełącza fazę. +8. Adapter Codex sprawdza exit/stdout runnera i zwraca `continue`, nie kończy tury i nie pokazuje pytania. +9. Workflow loop ponownie czyta canonical state, stosuje wybór do bieżącego work itemu, przesuwa trwały cursor i natychmiast dispatchuje następny problem albo body następnej fazy. +10. Dopiero brak kolejnej pracy albo finalna, zawsze user-controlled bramka kończy automatyczny ciąg. + +To dokładnie realizuje regułę użytkownika. Nie należy symulować kliknięcia ani wywoływać user gate na ścieżce sukcesu. + +## 2. Obecny łańcuch awarii + +```text +workflow gate call site + → instrukcje agreement/arbitration w Markdown + → profil advisora w advisor.toml + → [BRAK wykonywalnego evaluatora/adaptera Codex] + → phase-continue.mjs (jeżeli zostanie wywołany ręcznie) + ├─ terminalny commit + ├─ raporty + ├─ opcjonalna zmiana current_phase + └─ stdout JSON + process exit + → [BRAK consumer → apply effect → advance cursor → dispatch] +``` + +Konkretnie: + +- `platforms/codex-cli/templates/advisor.toml:5-18` opisuje rolę i `phase_continue(selected_option)`, ale jest tylko promptem. +- `platforms/codex-cli/build.sh:135-151,315-331` kopiuje/generuje instrukcje i waliduje wpis capability, lecz nie buduje executable bindingu. +- `platforms/codex-cli/smoke-cli.sh:66-89` sprawdza frazy, nie wykonanie. +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` zawsze kończy się `77`. +- `phase-continue.mjs:741-800` po zapisie/raportach/transition wypisuje JSON i kończy proces. +- Bez `next_phase` runner nie przesuwa kursora. Z `next_phase` zmienia state fazy, ale nie uruchamia handlera fazy. +- Call sites research/product-design mają prose „record choice, move to next area”, lecz nie mają durable same-phase cursor ani executable dispatch consumer. +- Phase-entry self-checki wymagające call ID pytania użytkownika są sprzeczne z poprawnym terminalnym auto gate'em. + +**Finding: high confidence.** Baseline: gate prose tests, shared runner i contract tests przechodzą; Codex E2E zwraca `77`, a capability poprawnie pozostaje `unsupported`. + +## 3. Jednoznaczny algorytm decyzyjny + +### 3.1 Agreement + +Warunki konieczne jednocześnie: + +- gate nie jest na hard denyliście; +- effective policy to `fully_automatic`; +- host capability jest zweryfikowane; +- output advisora ma dokładnie cztery dozwolone pola; +- `selected_option` jest dokładnym elementem `options`; +- `selected_option === original_recommendation` (exact string); +- `confidence ∈ {high, medium}`; +- `escalate_to_user === false`. + +Efekt: jeden terminalny rekord, `status: decided`, `final_actor: advisor`; `arbiter_calls=0`, `user_gate_calls=0`. + +### 3.2 Disagreement + +Gdy poprawna rekomendacja advisora różni się od pierwotnej: + +- zapisz wynik advisora przed arbitrażem; +- utwórz jeden `logical_arbiter_id` i jedną mapę `arbiter`; +- przekaż obie opcje i oba uzasadnienia; +- dozwolony output arbitra to wyłącznie jedna z tych dwóch opcji; +- malformed/timeout to kolejna próba w `arbiter.attempts[]`, nie nowy arbiter; +- resume `arbiter_pending` nie wywołuje advisora i nie tworzy nowego logical arbitra; +- poprawny wynik kończy gate z `final_actor: arbiter`. + +### 3.3 Fail-closed + +| Warunek | Terminalne zachowanie | Czego nie wolno zrobić | +|---|---|---| +| Hard denylist | `user_pending` albo noninteractive `blocked` | advisor, arbiter, auto runner, dispatch | +| Low confidence | user fallback albo `blocked` | automatyczny wybór | +| `escalate_to_user: true` | user fallback albo `blocked` | obniżenie eskalacji | +| Retry exhaustion | user fallback albo `blocked` | nieskończony retry lub approval | +| Invalid option/schema | retry w limicie, potem fallback/block | terminalny selection commit | +| Unsupported capability | manual/block | udawana automatyczna kontynuacja | +| Persistence/runner error | stop i resumable state | przesunięcie kursora/fazy | + +**Finding: high confidence.** Reguły są już normatywnie opisane w `gate-decision-engine.md:266-300`; brak ich executable realization. + +## 4. Kanoniczny kontrakt state/history/continuation + +### 4.1 Faza + +Użyć `orchestrator.current_phase` jako jedynego mutowalnego kursora fazy. Musi wskazywać dokładnie jedną fazę `in_progress` w `phases[]`. `started_phase` należy usunąć albo zmienić na niemutowalne `initial_phase`; nie może konkurować z kursorem wykonania. + +### 4.2 Gate history + +Jeden gate = jeden rekord o stabilnym idempotency key. Rekord przechodzi pending → terminal przez update, nie append duplikatu. Pełny envelope powinien obejmować: + +```yaml +schema_version: 1 +idempotency_key: sha256:... +phase_id: phase-4 +gate_type: research-convergence +question: "..." +options: [A, B, "Need more info"] +original_recommendation: A +policy: fully_automatic +safety_classification: configurable +status: decided +selected_option: B +final_actor: arbiter +advisor: + agent: advisor + model: "..." + response: {selected_option: B, rationale: "...", confidence: high, escalate_to_user: false} + attempts: [] + exhausted: false +arbiter: + logical_arbiter_id: sha256:... + agent: arbiter + model: "..." + response: {selected_option: B, rationale: "...", confidence: high, escalate_to_user: false} + attempts: [] + exhausted: false +confidence: high +rationale: "..." +continuation: + kind: same_phase_work_item + target: decision-area:persistence-boundary + status: pending +error: null +``` + +Runner nie powinien syntetyzować `original_recommendation = selected_option` ani rationale zastępczego. Powinien odczytać pełny terminalny rekord i zweryfikować zgodność payloadu z nim. + +### 4.3 Same-phase cursor + +Lista decision areas/problemów musi zostać zmaterializowana w state ze stabilnymi identyfikatorami: + +```yaml +decision_areas: + - id: execution-owner + ordinal: 1 + status: completed + gate_key: sha256:... + chosen_approach: host-workflow-loop + - id: persistence-boundary + ordinal: 2 + status: ready + gate_key: null + chosen_approach: null +``` + +Continuation target zawiera `work_item_id`, `source_gate_key`, `dispatch_id` i status `ready|in_progress|completed|blocked`. Ordinal jest informacyjny, nie stanowi identity. + +### 4.4 Kolejność durability + +```text +1. pending + attempt started (atomic state) +2. role response / attempt result (atomic state) +3. pełny terminal gate + continuation pending (atomic state) +4. dashboard/report projections from persisted state +5. apply selection + cursor/phase transition intent (atomic state) +6. dispatch(target, dispatch_id) +7. applied/completed receipt (atomic state) +``` + +Awaria po kroku 3 nie cofa decyzji. Resume regeneruje brakujące projekcje i kontynuuje z tego samego rekordu. Odrzucenie przed legalnym commitem musi zachować byte-exact state/report/modes/topology. + +**Finding: high confidence** dla wymaganych danych i kolejności; **medium-high** dla dokładnego kształtu YAML. + +## 5. Podział odpowiedzialności + +| Komponent | Odpowiada za | Nie odpowiada za | +|---|---|---| +| `gate-evaluate` / evaluator | idempotency, policy, denylist, role calls, validation, agreement, jeden arbiter, retry, terminal result | domenowy next-item routing | +| `phase-continue.mjs` | canonical-state preflight, terminal reuse/commit verification, raporty, forward phase transition | wywoływanie modeli, decision-area selection, host turn | +| Codex adapter | native delegation port, exact JSON transport, runner exit/stdout validation, outcome `continue|user_gate|blocked` | własny schema, własny cursor, wybór następnego problemu | +| Workflow loop | apply gate effect, stable work-item cursor, next target, natychmiastowy dispatch | ponowna implementacja gate safety | + +Najważniejszy warunek implementacyjny: **successful adapter execution must return control to the workflow loop without ending the turn**. Jeśli adapter po runner exit `0` zwróci finalną odpowiedź użytkownikowi, błąd pozostanie mimo poprawnego commitu. + +## 6. Same-phase kontra next-phase + +### Same-phase: kolejny problem/decision area + +`next_phase` nie może być użyty, bo target jest tą samą fazą i runner odrzuca self-transition. Poprawny flow: + +1. Commit terminal gate dla area N. +2. Idempotentnie zapisz `chosen_approach`, `gate_key`, `status: completed`. +3. Po zastosowaniu wyboru ponownie wylicz dozwolone alternatywy area N+1. +4. Ustaw N+1 `ready` z trwałym `dispatch_id`. +5. Adapter zwraca `continue`; workflow loop natychmiast rozpoczyna N+1 w tej samej turze. + +Nie wolno pre-renderować wszystkich areas, bo późniejsze mogą zależeć od wcześniejszych wyborów. + +### Next-phase: przejście i wejście + +Runner może atomowo wykonać forward transition: source `completed`, target `in_progress`, `current_phase=target`. To nadal tylko commit. Po jego sukcesie adapter zwraca `continue`, a workflow loop uruchamia body target phase i zapisuje obserwowalny pierwszy checkpoint/artifact. Test wyłącznie na statusie fazy jest niewystarczający. + +**Finding: high confidence.** Runner commit nie jest dispatcherem; to wynika z kodu `main()` i braku domenowych/hostowych portów. + +## 7. Dokładna mapa zmian per plik + +### Canonical framework — edytować + +| Plik | Zmiana | +|---|---| +| `plugins/maister/skills/orchestrator-framework/bin/gate-evaluate.mjs` (nowy) | Wykonywalna state machine agreement/arbitration/retry/resume z portem role invoker i pełnym terminalnym rekordem. | +| `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` | Konsumowanie/weryfikacja pełnego terminalnego rekordu; wspólny schema; `current_phase`; continuation intent/receipt; bogatszy, ścisły stdout bez dispatchu domenowego. | +| `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` | Zsynchronizować schema z executable evaluatorem, ownership terminal recordu, retry jednego arbitra i recovery po projekcjach. | +| `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` | `current_phase` zamiast `started_phase`; cursor/dispatch contract; auto gate jako legalny phase-entry proof; wyraźny „do not end turn”. | +| `plugins/maister/skills/orchestrator-framework/references/gate-decision-fixtures.yml` | Pełne executable inputs/expected state/call counts zamiast samych deklaracji. | +| `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` | Bez zmiany na początku; `codex: supported` wyłącznie po zielonym native E2E. | + +### Workflow call sites — edytować + +| Plik | Zmiana | +|---|---| +| `plugins/maister/skills/research/SKILL.md` | Terminal result zamiast „If user picks”; stable decision-area inventory/cursor; sukces runnera wraca do loop; phase self-check akceptuje auto record/receipt. | +| `plugins/maister/skills/product-design/SKILL.md` | Ten sam shared same-phase loop; osobny jawny reset dla backward refinement. | +| `plugins/maister/skills/development/SKILL.md` | Scope decisions jako work items; runner success consumer; auto phase-entry proof. | +| Pozostałe orchestratory używające wspólnego kontraktu | Migracja `started_phase → current_phase`, pełny gate envelope i entry checks według inventory wyszukiwania. | + +### Codex adapter — edytować/dodać + +| Plik | Zmiana | +|---|---| +| `platforms/codex-cli/` nowy binding/loop | Port native role invocation, call evaluator, exact runner transport, validate stdout, return `continue` bez UI/end turn. | +| `platforms/codex-cli/templates/advisor.toml` | Pozostawić read-only profil; wskazać rzeczywisty adapter/port, nie udawać implementacji prose. | +| `platforms/codex-cli/build.sh` | Kopiować nowy runtime/binding do generated target i walidować jego obecność. | +| `platforms/codex-cli/smoke-cli.sh` | Sprawdzać executable binding i wiring, nie tylko frazy. | +| `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` | Zastąpić `exit 77` realnym host-native testem; `77` tylko gdy runtime naprawdę niedostępny. | + +### Testy — edytować/dodać + +| Plik | Zmiana | +|---|---| +| `tests/gate-decision-engine.test.sh` | Dodać executable evaluator tests z licznikami advisor/arbiter/UI. | +| `tests/fixtures/gate-evaluator/` (nowy) | Agreement, oba wyniki arbitra, retry, resume, denylist, low/escalation, full expected record. | +| `tests/phase-continue-contract.test.sh` | Rich real-state fixtures, continuation receipt, crash windows, byte-exact rejection. | +| `tests/fixtures/phase-continue/*.yml` | Stany zgodne z realnymi workflowami, pełny advisor/arbiter audit i `current_phase`. | +| Nowy workflow-loop/dispatch contract test | Dwa same-phase work items, phase entry, `dispatch_id` dedupe i resume. | +| Nowy Codex adapter integration test | Fake role invoker + fake dispatcher, bez rzeczywistego modelu. | +| `Makefile` | Włączyć szybkie testy; zachować host-native target jako jedyny capability proof. | + +### Generated effects — nie edytować bezpośrednio + +`plugins/maister-codex/`, `plugins/maister-cursor/` i `plugins/maister-kiro/` są wynikami `make build`. Po zmianie canonical/adapters uruchomić build, sprawdzić diff i `make validate`. Nowe bindingi Codex muszą mieć jawne reguły copy, bo build odtwarza target. + +## 8. Kolejność implementacji + +1. **Schema i fixtures:** ustalić pełny gate envelope, `current_phase`, continuation/work-item receipt; dodać real-state fixtures. +2. **Executable evaluator:** agreement, disagreement, jeden arbiter, retry/resume, denylist; testy bez hosta. +3. **Runner contract:** runner weryfikuje utrwalony terminal record, raporty i phase transition; nie rekonstruuje audytu. +4. **Workflow loop tracer bullet:** dwa zależne same-phase items, apply effect, cursor, `dispatch_id`, resume. +5. **Codex adapter integration:** native port abstraction + fake role/dispatcher; po runner success outcome `continue` wraca do loop. +6. **Call-site migration:** research, product-design, development i inne inventory; naprawa phase-entry self-checków. +7. **Build projection:** adapter runtime do generated Codex; shared variants regenerowane deterministycznie. +8. **Host-native Codex E2E:** agreement, arbiter, same-phase, next-phase, resume i UI spy. +9. **Capability flip:** dopiero po `exit 0`, reproducible build i pełnym validate. + +Ta kolejność ogranicza ryzyko: najpierw jeden kontrakt i szybkie dowody, potem host binding i capability. + +## 9. Wykonywalna macierz testów + +| Scenariusz | Poziom | Wymagane pozytywne asercje | Wymagane negatywne asercje | +|---|---|---|---| +| Advisor zgadza się | evaluator + Codex E2E | actor advisor; 1 terminal record; reports; next dispatch | arbiter 0; UI 0; brak duplikatów | +| Arbiter wybiera original | evaluator + adapter | 1 logical arbiter; selected original; continuation | advisor nie retry po disagreement; UI 0 | +| Arbiter wybiera advisor | evaluator + adapter | 1 logical arbiter; selected advisor | brak trzeciej opcji; UI 0 | +| Następny decision area | loop + Codex E2E | N completed; N+1 ready/started; ten sam turn | brak phase completion; brak double dispatch | +| Następna faza | runner + Codex E2E | transition + pierwszy checkpoint target phase | brak końca po samym transition | +| Advisor retry | evaluator | persisted attempts/backoff; final advisor | limit nieprzekroczony; brak arbitra bez disagreement | +| Arbiter retry | evaluator | jeden logical arbiter, wiele attempts | advisor nie wywołany ponownie | +| Resume pending | evaluator | ten sam key/role/budget | brak resetu prób/nowej roli | +| Retry exhaustion | evaluator + adapter | user_pending albo blocked | runner/dispatch 0 | +| Report failure | runner | terminal trwały; retry regeneruje i kontynuuje raz | brak duplicate history | +| Transition failure | runner | retry stosuje transition raz | brak dwóch active phases | +| Dispatch failure | adapter/loop | ten sam dispatch_id, idempotent effect | brak nowego gate/efektu logicznego | +| Denylist | wszystkie poziomy | manual/blocked | advisor 0; arbiter 0; runner 0; dispatch 0 | +| Low/escalation | evaluator | manual/blocked | brak automatic selection | +| Invalid output/option | evaluator | bounded retry/fallback | brak selection commit | +| Changed terminal selection | runner | non-zero | byte-exact state/reports/modes/topology | +| Build projection | build | adapter obecny; drugi build no diff | brak ręcznych generated edits | +| Unsupported runtime | capability | E2E exit 77 | declared/projected supported niemożliwe | + +### Deterministyczne porty testowe + +Fake role invoker przyjmuje ten sam immutable context co native Codex i zwraca dokładnie czteropolowy YAML. Call log zapisuje `gate_key`, rolę, `logical_arbiter_id`, attempt i input hash. Fake dispatcher deduplikuje po `dispatch_id` i zapisuje attempt/ack. UI spy failuje natychmiast, jeśli pozytywna ścieżka `fully_automatic` wywoła pytanie. + +Host-native E2E musi nadal uruchomić rzeczywisty Codex entrypoint; fake zastępuje tylko niedeterministyczny model, nie host ani workflow loop. + +## 10. Kryteria akceptacji + +Naprawa jest kompletna tylko wtedy, gdy: + +- zgodność original/advisor automatycznie wybiera opcję, z aktorem `advisor`, bez arbitra i UI; +- rozbieżność uruchamia jeden logical arbiter, a oba legalne rozstrzygnięcia mają executable test; +- pełny terminalny audyt i raporty są trwałe przed continuation; +- kolejny problem/decision area rzeczywiście zaczyna się w tej samej turze; +- next-phase test obserwuje body/checkpoint nowej fazy, nie tylko zmianę statusu; +- resume/retry nie duplikuje historii, logical arbitra ani logicznego dispatchu; +- denylista, low confidence, escalation, exhaustion, invalid state/output i failure paths pozostają fail-closed; +- realny workflow state przechodzi ten sam strict schema bez ad-hoc transformacji adaptera; +- `make build && make validate` przechodzi bez generated drift; +- Codex host-native E2E kończy się `0`; przy braku runtime kończy się `77` i capability pozostaje unsupported. + +## 11. Rollout i reguła capability flip + +Rollout powinien mieć trzy bramki: + +1. **Shared contract ready:** evaluator, runner, schema, fixtures i loop integration są zielone; Codex nadal `unsupported`. +2. **Codex integration ready:** fake-port adapter integration i reproducible build są zielone; Codex nadal `unsupported`. +3. **Native evidence ready:** realny Codex E2E obserwuje agreement, arbitration, same-phase i next-phase continuation, brak UI oraz resume; dopiero wtedy zmienić `host-capabilities.yml` na `supported`. + +Nie używać ręcznego override, smoke frazy ani shared runner testu jako substytutu bramki 3. Makefile już poprawnie odróżnia `exit 0`, `77` i failure — zachować ten fail-closed projection. + +## 12. Ryzyka, luki i confidence + +| Finding | Confidence | Ryzyko / luka | +|---|---|---| +| Brak executable Codex adaptera jest pierwotnym blockerem | High | Brak stabilnego native harnessu | +| Runner commit nie jest dispatcherem | High | Łatwo omyłkowo uznać stdout/transition za continuation | +| Potrzebny powrót do workflow loop bez końca tury | High | Zależność od hostowego modelu execution turn | +| Agreement/jeden arbiter algorytm jest jednoznaczny | High | Dziś tylko prose-tested | +| `current_phase` powinno być canonical | High | Migracja istniejących states/resume | +| Durable same-phase cursor i dispatch_id są konieczne | High | Finalna serializacja wymaga design review | +| Exact native Codex binding shape | Medium | Potrzebny spike headless CLI/tool port | +| Exactly-once logiczny efekt przez dedupe | Medium-high | Receiver musi honorować dispatch_id | + +## 13. Źródła + +Główne źródła pierwszego rzędu: + +- `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` +- `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` +- `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` +- `plugins/maister/skills/research/SKILL.md` +- `plugins/maister/skills/product-design/SKILL.md` +- `plugins/maister/skills/development/SKILL.md` +- `platforms/codex-cli/templates/advisor.toml` +- `platforms/codex-cli/build.sh` +- `platforms/codex-cli/smoke-cli.sh` +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` +- `tests/gate-decision-engine.test.sh` +- `tests/fully-automatic-phase-continue.test.sh` +- `tests/phase-continue-contract.test.sh` +- `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` +- `.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/codex-fully-automatic-diagnosis.md` + +Pełne dowody cząstkowe znajdują się w `../analysis/findings/01-gate-state-contract.md`, `02-continuation-dispatch.md`, `03-codex-host-adapter.md` i `04-verification-safety.md`. diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/solution-exploration.html b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/solution-exploration.html new file mode 100644 index 00000000..2e983e82 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/solution-exploration.html @@ -0,0 +1,82 @@ + + + + +Eksploracja rozwiązań — automatyczna kontynuacja Codex + + + + +
Solution exploration

Automatyczna kontynuacja Codex

Warianty architektury dla agreement, jednego arbitra i automatycznego dispatchu kolejnej pracy. Wygenerowano 2026-07-13T16:58:29Z.

+
4decision areas
16alternatives
4recommendations
Highroot-cause confidence
+

TL;DR

Najmocniejszy zestaw to wspólny wykonywalny evaluator z portami hosta, pełny terminalny rekord przed continuation oraz workflow-owned durable work-item cursor z outbox/receipt. Codex dostaje cienki binding, który oddaje continue do aktywnej pętli bez kończenia tury. Agreement kończy advisor, disagreement tworzy jeden logiczny arbiter, a capability pozostaje unsupported do zielonego host-native E2E.

+

Key Decisions

  • A3 — wspólny executable evaluator/CLI.
  • B1 — evaluator zapisuje pełny record; runner weryfikuje i kontynuuje.
  • C1 — workflow inventory + durable outbox/receipt.
  • D1 — cienki host-native binding Codex.
+

Open Questions / Risks

  • Stabilny same-turn/headless seam Codex wymaga spike'a.
  • Potrzebny jeden wersjonowany schema i migracja started_phase → current_phase.
  • Exactly-once jest logiczne przez dispatch_id, nie fizyczne.
  • Wspólne zapisy YAML wymagają revision/CAS lub ścisłej sekwencji.
+ +
+

1. Kryteria i ograniczenia

Warianty oceniono przez wykonalność, prostotę, ryzyko, przenośność oraz audyt/resume.

  1. Denylista, low confidence, escalation i retry exhaustion są fail-closed.
  2. Role są read-only; deterministyczny komponent zapisuje state.
  3. Jeden gate ma jeden key i record pending → terminal.
  4. Jeden logical arbiter; retry to attempts.
  5. Terminal selection jest trwałe przed reports/cursor/dispatch.
  6. Canonical i adapter source są edytowane; generated variants tylko przez build.
  7. Continuation wymaga obserwowalnego next work item/checkpoint, nie samego stdout.
+ +

2. Obszar A — wykonywalny evaluator

+

A1. Instrukcje workflow hosta

Każdy SKILL wykonuje state machine przez natywne subagenty, bez nowego programu.

Plusy
  • Mało kodu.
  • Naturalny dostęp do delegation i tury.
  • Szybki prototyp.
Minusy
  • Prose nadal nie jest deterministyczne.
  • Drift workflowów/hostów.
  • Słabe testy retry/resume.
  • Ryzyko UI po resume.

Feasibility high · simplicity high · risk high · portability low · audit low

+

A2. Monolit w phase-continue

Runner wywołuje role, wybiera, zapisuje, raportuje i dispatchuje.

Plusy
  • Jeden entrypoint.
  • Łatwy CLI test.
  • Mniej kontraktów.
Minusy
  • Brak native agent/turn API.
  • Miesza host, domenę i persistence.
  • Duży blast radius.
  • Nie zna same-phase semantyki.

Feasibility medium · simplicity medium · risk high · portability low · audit medium

+
Recommended

A3. Shared evaluator z host ports

Wspólny moduł/CLI posiada state machine; host dostarcza tylko role_invoker.

Plusy
  • Executable agreement/arbitration.
  • Jeden kontrakt platform.
  • Read-only role boundary.
  • Deterministic fake ports.
Minusy
  • Nowy port/IPC.
  • Schema migration.
  • Lock/revision state.

Feasibility high · simplicity medium · risk medium-low · portability high · audit high

+

A4. Codex-only evaluator

Algorytm trafia do platforms/codex-cli/, shared runner bez zmian.

Plusy
  • Natywna optymalizacja.
  • Wąski initial scope.
  • Szybki Codex delivery.
Minusy
  • Drugi gate engine.
  • Brak korzyści dla innych hostów.
  • Gruby adapter.
  • Ryzyko safety drift.

Feasibility high · simplicity medium · risk high · portability low · audit medium

+

Rekomendacja A3. A1 może być tylko spikiem portu, nie produkcyjnym kontraktem.

+ +

3. Obszar B — state i terminal record

+
Recommended

B1. Evaluator zapisuje; runner konsumuje

Evaluator prowadzi pełny envelope pending→terminal. Runner czyta po key, weryfikuje, raportuje i commituję continuation.

Plusy
  • Pełny provenance u właściciela decyzji.
  • Brak syntetycznego audytu.
  • Recovery bez model recall.
  • Decyzja przed efektem.
Minusy
  • Dwóch writerów.
  • Zmiana runner payload/schema.
  • Migracja starych records.

Feasibility high · simplicity medium · risk medium · portability high · audit high

+

B2. Runner jako jedyny writer

Evaluator zwraca envelopes, a runner zapisuje pending, attempts i terminal przez kolejne komendy.

Plusy
  • Jeden filesystem writer.
  • Centralne schema/modes.
  • Istniejące failure patterns.
Minusy
  • Wiele round-tripów.
  • Runner staje się state RPC.
  • Więcej partial states.
  • Złożony kontrakt.

Feasibility medium-high · simplicity low · risk medium · portability medium · audit high

+

B3. Jedna długa command transaction

Proces żyje przez model calls i zapisuje terminal, reports i target.

Plusy
  • Jedno API.
  • Centralny locking.
  • Prosty happy path.
Minusy
  • Brak transakcji przez model/host.
  • Pending nadal konieczny.
  • Monolityzacja.
  • Duży refactor.

Feasibility medium · simplicity medium-low · risk high · portability medium · audit medium

+

B4. Append-only event log

Pending, attempts, decision i dispatch są eventami; snapshot jest projekcją.

Plusy
  • Najpełniejszy audyt.
  • Naturalny recovery timeline.
  • Dobra diagnostyka concurrency.
Minusy
  • Nieproporcjonalna architektura.
  • Nowy projector/migracja.
  • Większy koszt.
  • Poza minimal fix.

Feasibility medium · simplicity low · risk high · portability high · audit very high

+

Rekomendacja B1 ze wspólnym małym state-repository helperem, atomic write, revision i invariant checks.

+ +

4. Obszar C — cursor i dispatch

+
Recommended

C1. Workflow inventory + outbox/receipt

Workflow materializuje work itemy; terminal choice kończy item i zapisuje następny target z dispatch_id; receiver deduplikuje i ackuje.

Plusy
  • Domena pozostaje w workflowie.
  • Logic exactly-once.
  • Same-phase i phase-entry.
  • Obserwowalny następny checkpoint.
Minusy
  • Więcej state/crash windows.
  • Migracja pętli workflowów.
  • Receiver dedupe contract.

Feasibility high · simplicity medium · risk medium-low · portability high · audit high

+

C2. Liczbowy index

Workflow zapisuje current_index i inkrementuje po wyborze.

Plusy
  • Minimalny schema.
  • Łatwy research demo.
  • Mało kodu.
Minusy
  • Reorder łamie identity.
  • Brak receipt.
  • Crash ambiguity.
  • Słabe dynamic inventory.

Feasibility very high · simplicity high · risk high · portability low · audit low

+

C3. Runner wylicza target

Payload niesie inventory, a runner waliduje i przesuwa cursor.

Plusy
  • Central durability.
  • Gotowy target.
  • Wspólne fixtures.
Minusy
  • Domenowa wiedza w runnerze.
  • Nie przelicza zależnych options.
  • Sprzęga phase summaries.
  • Nadal nie utrzymuje tury.

Feasibility medium · simplicity medium · risk medium-high · portability medium · audit high

+

C4. Ephemeral loop

Adapter wykonuje kolejne areas, a resume szuka pierwszego pustego choice bez durable dispatch.

Plusy
  • Mało zmian.
  • Naturalny current prose.
  • Szybki happy path.
Minusy
  • Crash ambiguity.
  • Brak dedupe/receipt.
  • Niestabilna re-derywacja.
  • Słaby E2E proof.

Feasibility high · simplicity very high · risk medium-high · portability medium · audit low

+

Rekomendacja C1. Tracer bullet może mieć tylko dwa items, ale od początku ze stabilnym ID i dispatch ID.

+ +

5. Obszar D — Codex binding i native E2E

+
Recommended

D1. Thin host-native binding

Generated skill używa natywnych subagentów, shared evaluator/runner i zwraca continue | user_gate | blocked do workflow loop.

Plusy
  • Native delegation/turn.
  • Shared testable core.
  • Bez usługi.
  • Zgodność z build model.
Minusy
  • Callback seam wymaga spike'a.
  • Częściowo instruction-driven.
  • E2E musi objąć real host.

Feasibility medium-high · simplicity medium · risk medium · portability high · audit high

+

D2. Lokalny MCP/tool server

Narzędzia evaluate_gate, continue_gate i dispatch_next są wykonywalnym API.

Plusy
  • Strict API/schema.
  • Locking i observability.
  • Cross-host potential.
Minusy
  • Nowy service lifecycle.
  • Tool nie wymusza same-turn.
  • Większy runtime.
  • Security surface.

Feasibility high · simplicity low · risk medium · portability high · audit high

+

D3. Headless Codex wrapper

Skrypt steruje codex exec i kolejnymi work items.

Plusy
  • Pełna kontrola loop.
  • Jasny CI entrypoint.
  • Niezależny od jednej odpowiedzi.
Minusy
  • Nested sessions/context loss.
  • Trudny fake role port.
  • Może nie reprezentować plugin UX.
  • CLI instability.

Feasibility medium · simplicity low · risk high · portability low · audit medium

+

D4. Background outbox daemon

Daemon obserwuje state i pobiera ready dispatches poza assistant turn.

Plusy
  • Natural durable consumer.
  • Retry i wiele workflowów.
  • Łatwe ack/metrics.
Minusy
  • Nowy model produktu.
  • Nie ta sama aktywna tura.
  • Lifecycle/concurrency.
  • Nadmiarowe.

Feasibility medium · simplicity low · risk high · portability low · audit high

+

Rekomendacja D1. D2 jest fallbackiem tylko jeśli spike wykaże brak stabilnego bindingu w aktywnej turze.

+ +

6. Zależności i macierz rekomendacji

A3 executable evaluator
+└── B1 full terminal envelope
+    └── runner projections / transition
+
+C1 workflow inventory + outbox
+├── consumes B1 terminal choice
+└── supplies target + dispatch_id to D1
+
+D1 Codex binding
+├── role_invoker → A3
+├── runner after B1
+└── continue → C1 workflow loop
+
WymiarA3B1C1D1
WykonalnośćWysokaWysokaWysokaŚrednia-wysoka
ProstotaŚredniaŚredniaŚredniaŚrednia
RyzykoŚrednie-niskieŚrednieŚrednie-niskieŚrednie
PortabilityWysokaWysokaWysokaWysoka
Audyt/resumeWysokiWysokiWysokiWysoki z native E2E
DowódExecutable fixturesFull-record recoveryCrash/resumeNo-UI real dispatch
+
Dlaczego nie pozostałe zestawy?
  • A1+C4 usuwa kliknięcie tylko w happy path i pozostawia prose-only root cause.
  • A2+C3 centralizuje host i domenę w runnerze.
  • A4 tworzy Codex-specific gate semantics.
  • B4+D4 jest nieproporcjonalną platformą eventową/daemonem.
  • D2 warto przyjąć dopiero, jeśli D1 okaże się niestabilne.
+ +

7. Proponowany tracer bullet

  1. Wersjonowany gate envelope, current_phase, revision, work item i dispatch ID.
  2. Evaluator agreement/disagreement z jednym logical arbiter i fake role port.
  3. Runner reużywa pełny terminal record.
  4. Dwa zależne research decision areas z durable choice → ready → dispatch/ack.
  5. Codex binding zwracający continue oraz UI spy.
  6. Testy agreement, oba wyniki arbitra, dwa crash windows, same-phase i next-phase.
  7. Build generated variants, reproducibility i validate.
  8. Real host-native Codex E2E; capability flip tylko po exit 0.
+ +

8. Stretch / poza zakresem

  • Machine-readable JSON Schema generujące validators/docs/fixtures.
  • Append-only diagnostyczny journal obok canonical snapshotu.
  • Generyczny work-item SDK po udanym tracer bullecie.
  • Chaos/failure-injection suite.
  • Capability rozbite na decision automation, same-phase i phase-entry.
  • Background outbox consumer dla przyszłych batch workflows.
+

Źródła

+
+ + diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/solution-exploration.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/solution-exploration.md new file mode 100644 index 00000000..61c90204 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/outputs/solution-exploration.md @@ -0,0 +1,434 @@ +# Eksploracja rozwiązań: automatyczna kontynuacja Codex + +## TL;DR + +Najmocniejszy wariant to wspólny wykonywalny evaluator z portami hosta, pełny terminalny rekord zapisywany przed continuation oraz workflow-owned durable work-item cursor z outbox/receipt. +Codex powinien dostać cienki binding, który uruchamia wspólne komponenty i oddaje `continue` do aktywnej pętli bez kończenia tury; nie powinien posiadać własnej kopii logiki decyzji ani routingu. +Zgodność original/advisor kończy gate aktorem `advisor`; rozbieżność tworzy jeden logiczny obiekt `arbiter`, a retry dopisują tylko attempts. +Capability pozostaje `unsupported`, dopóki host-native E2E nie zaobserwuje następnego same-phase work itemu i następnej fazy bez UI. + +## Key Decisions + +- Rekomendacja A3: wspólny executable evaluator/CLI z wstrzykiwanymi portami ról i bez wiedzy o domenowym routingu. +- Rekomendacja B1: evaluator jest jedynym właścicielem pełnego gate recordu; runner weryfikuje terminalny wybór, generuje projekcje i commituję transition/receipt. +- Rekomendacja C1: workflow materializuje stabilne work itemy, a durable outbox z `dispatch_id` prowadzi same-phase i next-phase continuation. +- Rekomendacja D1: cienki host-native binding Codex wokół wspólnych CLI i jawnego `continue | user_gate | blocked`, z fake portami w testach i realnym hostem w capability E2E. + +## Open Questions / Risks + +- Stabilny mechanizm utrzymania aktywnej tury i headless uruchomienia realnego Codex wymaga krótkiego spike'a; to wpływa na formę D1, ale nie na granice komponentów. +- Trzeba ustalić jeden wersjonowany schema/envelope używany przez evaluator, runner, workflowy i fixtures, łącznie z migracją `started_phase → current_phase`. +- Exactly-once oznacza jeden logiczny efekt deduplikowany przez `dispatch_id`; fizyczny retry hosta po przerwaniu pozostaje możliwy. +- Dwa procesy zapisujące ten sam YAML wymagają wspólnego repozytorium/lockowania lub ścisłej sekwencji z compare-and-swap po revision. + +## 1. Kryteria i niezmienne ograniczenia + +Każdy wariant oceniono w pięciu wymiarach: wykonalność techniczna, prostota, ryzyko, przenośność/skalowalność oraz poprawność audytu i resume. + +Niezmienne wymagania: + +1. Hard denylista, low confidence, eskalacja i wyczerpanie retry pozostają fail-closed. +2. Advisor i arbiter są read-only wobec artefaktów i stanu; zapis wykonuje deterministyczny komponent hosta/frameworka. +3. Jeden gate ma jeden idempotency key i jeden rekord przechodzący pending → terminal. +4. Rozbieżność tworzy dokładnie jeden logiczny arbiter; kolejne wywołania są attempts tego samego obiektu. +5. Terminalny wybór jest trwały przed raportami, cursorem i dispatch'em. +6. Edycje trafiają do `plugins/maister/` i `platforms/codex-cli/`; generated variants powstają przez build. +7. „Kontynuacja” jest udowodniona dopiero przez obserwowalny następny work item lub checkpoint nowej fazy, nie przez sam stdout lub zmianę statusu. + +## 2. Obszar A — właściciel i packaging wykonywalnego evaluatora + +Ta decyzja określa, gdzie naprawdę wykonywane są agreement, arbitration, retry, resume, denylista i walidacja czteropolowego outputu. + +### A1. Logika wyłącznie w instrukcjach workflow hosta + +Każdy SKILL opisuje state machine, a główny agent wykonuje ją przy użyciu natywnych subagentów i bez nowego programu. + +**Plusy** + +- Najmniej nowego kodu i zależności. +- Naturalny dostęp do natywnego delegation i aktywnej tury. +- Szybki prototyp jednego call site'u. + +**Minusy** + +- Obecny root cause pozostaje: prose nie jest wykonywalnym, deterministycznym kontraktem. +- Duplikacja i drift między research, product-design, development oraz hostami. +- Trudno dowieść retry budget, resume pending i jednego logicznego arbitra fixture'ami. +- Wysokie ryzyko ponownego wyświetlenia UI po compaction/resume. + +**Ocena:** wykonalność wysoka; prostota początkowa wysoka; ryzyko wysokie; przenośność niska; audyt/resume niski. + +### A2. Rozszerzyć `phase-continue.mjs` do monolitu gate + persistence + dispatch + +Runner wywołuje role, wybiera, zapisuje, generuje raporty i dispatchuje następny target. + +**Plusy** + +- Jeden entrypoint i pozornie jedna transakcja kontroli. +- Łatwy test CLI bez angażowania wielu procesów. +- Mniej transportowych kontraktów między komponentami. + +**Minusy** + +- Node runner nie ma natywnego API do subagentów ani utrzymania tury Codex. +- Łączy wspólną logikę decyzji z domenowym routingiem i hostem. +- Rozszerza blast radius sprawdzonego writer'a oraz komplikuje portability. +- Same-phase work item nadal wymaga wiedzy z konkretnego workflow. + +**Ocena:** wykonalność średnia; prostota średnia; ryzyko wysokie; przenośność niska; audyt/resume średni. + +### A3. Wspólny executable evaluator z portami hosta — rekomendowane + +Nowy wspólny moduł/CLI (np. `gate-evaluate.mjs`) posiada czystą state machine i korzysta z wstrzykiwanego `role_invoker`; host dostarcza wywołanie advisora/arbitra, ale nie implementuje reguł wyboru. + +**Plusy** + +- Agreement, jeden arbiter, retry i resume stają się executable i fixture-testable. +- Jeden kontrakt dla wszystkich workflowów i hostów. +- Role pozostają read-only, a wszystkie mutacje przechodzą przez deterministyczny state repository. +- Fake role port daje szybkie i pełne testy bez niedeterministycznego modelu. + +**Minusy** + +- Trzeba zdefiniować port natywnego delegation oraz granicę procesu/IPC. +- Wymaga wspólnego schema i ostrożnej migracji realnych states. +- Należy rozwiązać lock/revision przy wielu zapisach state. + +**Ocena:** wykonalność wysoka; prostota średnia; ryzyko średnie-niskie; przenośność wysoka; audyt/resume wysoki. + +### A4. Codex-only evaluator w adapterze platformy + +Cały algorytm trafia do `platforms/codex-cli/`; shared runner pozostaje bez zmian. + +**Plusy** + +- Można optymalizować dokładnie pod natywne możliwości Codex. +- Ograniczony początkowy zakres wdrożenia. +- Nie blokuje się na pełnej migracji innych hostów. + +**Minusy** + +- Powstaje drugi gate engine obok kanonicznego kontraktu. +- Inne hosty nie korzystają z testów i poprawek. +- Adapter przestaje być cienki, a generated parity staje się trudniejsza. +- Wysokie ryzyko różnej semantyki denylisty i resume. + +**Ocena:** wykonalność wysoka; prostota średnia; ryzyko wysokie; przenośność niska; audyt/resume średni. + +**Rekomendacja:** A3. Zapewnia wykonywalność bez wciskania hostowych ani domenowych odpowiedzialności do runnera. A1 może posłużyć tylko jako spike portu; nie powinno być rozwiązaniem produkcyjnym. + +## 3. Obszar B — właściciel kanonicznego stanu i terminalnego rekordu + +Ta decyzja usuwa obecny konflikt: gate engine wymaga pełnego audytu, a runner syntetyzuje uboższy record z już wybranej opcji. + +### B1. Evaluator zapisuje pełny rekord, runner konsumuje i weryfikuje — rekomendowane + +Evaluator aktualizuje jeden envelope od pending do terminal. Runner dostaje idempotency key i oczekiwany wybór, ponownie czyta state, weryfikuje terminalny rekord, generuje raporty i commituję continuation. + +**Plusy** + +- Komponent posiadający modelową state machine posiada także pełny provenance. +- Runner nie rekonstruuje rationale, original recommendation ani attempts. +- Resume może osobno naprawić raport/transition bez ponawiania modelu. +- Jasny inwariant: decyzja trwała przed efektami. + +**Minusy** + +- Evaluator i runner są dwoma writerami; potrzebują wspólnego repository API, revision/CAS lub ścisłej sekwencji. +- Payload runnera i schema history muszą zostać zmienione razem. +- Migracja istniejących wąskich terminal records wymaga decyzji kompatybilności. + +**Ocena:** wykonalność wysoka; prostota średnia; ryzyko średnie; przenośność wysoka; audyt/resume wysoki. + +### B2. Runner jest jedynym writerem pełnego recordu + +Evaluator zwraca kompletny immutable result envelope; runner zapisuje pending, attempts i terminal records przez kolejne komendy. + +**Plusy** + +- Jeden filesystem writer i jedno miejsce atomic write. +- Łatwiej kontrolować exact schema i permissions. +- Runner może zachować istniejące wzorce failure injection. + +**Minusy** + +- Wymaga wielokrotnych round-tripów do runnera przed i po każdym model call. +- Host/evaluator musi utrzymywać state machine między procesami, a runner staje się RPC state service. +- Większy transport i więcej stanów częściowego sukcesu. +- Trudniej zachować prosty kontrakt obecnego `phase-continue.mjs`. + +**Ocena:** wykonalność średnia-wysoka; prostota niska; ryzyko średnie; przenośność średnia; audyt/resume wysoki. + +### B3. Jeden zintegrowany command transaction dla gate i continuation + +Proces pozostaje żywy przez model calls, a na końcu zapisuje terminal record, raporty i target. + +**Plusy** + +- Jedno API wejściowe dla adaptera. +- Może centralizować locking i schema validation. +- Czytelny happy path. + +**Minusy** + +- Nie daje prawdziwej transakcji przez zewnętrzne model calls i host dispatch. +- Crash podczas długiego procesu nadal wymaga pending checkpointów. +- Zbliża się do monolitu A2 i utrudnia natywne delegation. +- Duży refactor przed uzyskaniem tracer-bullet proof. + +**Ocena:** wykonalność średnia; prostota średnia-niska; ryzyko wysokie; przenośność średnia; audyt/resume średni. + +### B4. Append-only event log jako jedyne źródło prawdy + +Każdy pending, attempt, decision i dispatch jest osobnym eventem; bieżący state jest projekcją. + +**Plusy** + +- Najpełniejszy audyt i naturalny recovery timeline. +- Brak update-in-place pojedynczego gate recordu. +- Dobra podstawa do diagnostyki concurrency. + +**Minusy** + +- Nieproporcjonalna zmiana architektury projektu dokumentacyjnego bez bazy. +- Wymaga projektora, migracji wszystkich workflowów i nowego modelu dashboardu. +- Trudniejsza exact-schema kompatybilność i większy koszt operacyjny. +- Łamie minimal implementation dla konkretnego buga. + +**Ocena:** wykonalność średnia; prostota niska; ryzyko wysokie; przenośność wysoka; audyt/resume bardzo wysoki. + +**Rekomendacja:** B1, uzupełnione wspólnym małym `state-repository` helperem z atomic write, revision i invariant checks. B4 jest atrakcyjnym kierunkiem długoterminowym, lecz wykracza poza naprawę. + +## 4. Obszar C — same-phase cursor i protokół dispatchu + +Ta decyzja odpowiada za automatyczne przejście od area N do N+1 oraz za realne wejście do kolejnej fazy. + +### C1. Workflow-owned inventory + durable outbox/receipt — rekomendowane + +Workflow materializuje stabilne work itemy. Po terminalnym gate idempotentnie aplikuje wybór, oznacza item completed i zapisuje następny target z `dispatch_id`; adapter dispatchuje, receiver deduplikuje i zapisuje ack. + +**Plusy** + +- Domenowa kolejność i zależne alternatywy pozostają w workflowie. +- Stabilny `work_item_id` i receipt dają logiczne exactly-once oraz precyzyjny resume. +- Ten sam protokół obsługuje `same_phase_work_item` i `phase_entry`. +- Test może obserwować rzeczywisty następny checkpoint, nie tylko status. + +**Minusy** + +- Więcej pól state i kilka crash windows do przetestowania. +- Każdy workflow z pętlą musi materializować inventory zgodnie ze wspólnym kontraktem. +- Receiver musi honorować deduplikację `dispatch_id`. + +**Ocena:** wykonalność wysoka; prostota średnia; ryzyko średnie-niskie; przenośność wysoka; audyt/resume wysoki. + +### C2. Tylko liczbowy cursor/index w phase summary + +Workflow zapisuje `current_index`, inkrementuje po wyborze i natychmiast wykonuje następny element. + +**Plusy** + +- Minimalny schema i prosty happy path. +- Łatwe wdrożenie dla research Phase 4. +- Mało kodu do pierwszego demo. + +**Minusy** + +- Zmiana/reorder artefaktu może skierować resume na inny problem. +- Brak identity, source gate key, dispatch intent i ack. +- Crash po inkrementacji nie rozstrzyga, czy kolejny efekt już wykonano. +- Słabo przenosi się na zależne lub dynamiczne inventory. + +**Ocena:** wykonalność bardzo wysoka; prostota wysoka; ryzyko wysokie; przenośność niska; audyt/resume niski. + +### C3. Runner wylicza i zapisuje generyczny następny target + +Payload zawiera pełną listę work itemów, a runner waliduje i przesuwa cursor. + +**Plusy** + +- Centralne durability i strict transition checks. +- Adapter dostaje gotowy target. +- Możliwe wspólne fixture'y dla cursora. + +**Minusy** + +- Runner musi znać semantykę itemów lub ufać dużemu payloadowi. +- Nie potrafi bez workflowu przeliczyć alternatyw zależnych od poprzedniego wyboru. +- Sprzęga shared runner z formatami phase summaries. +- Nadal nie dispatchuje aktywnej tury. + +**Ocena:** wykonalność średnia; prostota średnia; ryzyko średnie-wysokie; przenośność średnia; audyt/resume wysoki. + +### C4. Ephemeral same-turn loop bez durable dispatch state + +Po sukcesie adapter po prostu kontynuuje `for each area`, a resume wyznacza pierwsze `chosen_approach: null`. + +**Plusy** + +- Najmniej zmian w schema. +- Naturalnie pasuje do obecnego prose call site'u. +- Szybko usuwa widoczny user click w happy path. + +**Minusy** + +- Crash między efektem i kolejnym dispatch'em jest niejednoznaczny. +- Brak dispatch dedupe i observation receipt. +- Re-derywacja z mutującego artefaktu może być niestabilna. +- Host-native E2E nie ma trwałego dowodu dokładnie którego itemu podjęto. + +**Ocena:** wykonalność wysoka; prostota bardzo wysoka; ryzyko średnie-wysokie; przenośność średnia; audyt/resume niski. + +**Rekomendacja:** C1. Minimalny pierwszy pion może ograniczyć inventory do dwóch research decision areas, ale musi od początku używać stabilnego ID i `dispatch_id`, aby prototyp nie utrwalił wadliwego indeksowego kontraktu. + +## 5. Obszar D — binding Codex i seam host-native E2E + +Ta decyzja rozstrzyga, jak połączyć natywne role Codex, wspólny evaluator/runner i pętlę workflow bez kończenia tury. + +### D1. Cienki host-native binding wokół wspólnych CLI — rekomendowane + +Generated skill wywołuje natywne subagenty przez jawny port, przekazuje ich outputs do wspólnego evaluatora, uruchamia runner, waliduje stdout i zwraca do workflow loop `continue | user_gate | blocked`. + +**Plusy** + +- Zachowuje natywne delegation i aktywną turę Codex. +- Shared core pozostaje testowalny fake portami; adapter pozostaje cienki. +- Brak dodatkowego długo żyjącego serwisu. +- Najlepiej pasuje do istniejącego single-source/build modelu. + +**Minusy** + +- Exact mechanizm callbacku/utrzymania tury wymaga spike'a z realnym Codex. +- Część bindingu może nadal być instruction-driven, jeśli host nie wystawia stabilnego programmatic hooka. +- E2E musi odróżniać rzeczywisty host od testu samego Node CLI. + +**Ocena:** wykonalność średnia-wysoka; prostota średnia; ryzyko średnie; przenośność wysoka; audyt/resume wysoki. + +### D2. Lokalny MCP/tool server jako runtime adapter + +Plugin dostarcza narzędzia `evaluate_gate`, `continue_gate` i `dispatch_next`, a Codex wywołuje je w jednej turze. + +**Plusy** + +- Jawne, wykonywalne API i łatwe strict schemas. +- Dobre miejsce na locking, fake ports i observability. +- Potencjalnie przenośne na inne hosty z MCP. + +**Minusy** + +- Nowy proces/usługa, lifecycle i konfiguracja MCP zwiększają koszt instalacji. +- Tool nadal nie może sam zmusić modelu-host do kontynuacji po odpowiedzi; instrukcja loop pozostaje potrzebna. +- Wykracza poza minimalny dependency/runtime footprint. +- Większa powierzchnia bezpieczeństwa. + +**Ocena:** wykonalność wysoka; prostota niska; ryzyko średnie; przenośność wysoka; audyt/resume wysoki. + +### D3. Zewnętrzny headless Codex wrapper sterujący całą sesją + +Skrypt uruchamia `codex exec`, przechwytuje outputs i ponawia kolejne prompty/work items aż do completion. + +**Plusy** + +- Pełna kontrola nad loopem i łatwa automatyzacja CI. +- Jasny host-native E2E entrypoint. +- Niezależność od zachowania pojedynczej odpowiedzi skillu. + +**Minusy** + +- Ryzyko zagnieżdżonych sesji, utraty bieżącego kontekstu i różnic CLI/IDE. +- Trudne bezpieczne wstrzyknięcie fake role invokera. +- Może nie reprezentować realnego plugin invocation użytkownika. +- Wysokie ryzyko niestabilności wersji CLI. + +**Ocena:** wykonalność średnia; prostota niska; ryzyko wysokie; przenośność niska; audyt/resume średni. + +### D4. Codex-specific background daemon/outbox consumer + +Daemon obserwuje `orchestrator-state.yml`, pobiera ready dispatches i uruchamia kolejne zadania niezależnie od assistant turn. + +**Plusy** + +- Naturalny durable outbox consumer i recovery po zakończeniu tury. +- Może przetwarzać wiele workflowów i retry. +- Łatwe acknowledgement oraz metryki. + +**Minusy** + +- Zmienia model produktu z lokalnego pluginu bez usługi na proces w tle. +- Nie spełnia dosłownie wymogu kontynuacji w tej samej aktywnej turze. +- Problemy lifecycle, concurrency, uprawnień i instalacji. +- Nadmiarowe dla pojedynczego buga. + +**Ocena:** wykonalność średnia; prostota niska; ryzyko wysokie; przenośność niska; audyt/resume wysoki. + +**Rekomendacja:** D1, z D2 jako fallback tylko jeśli spike wykaże, że Codex nie zapewnia stabilnego portu/bindingu w aktywnej turze. Host-native E2E musi uruchomić realny Codex entrypoint, podczas gdy fake zastępuje wyłącznie role i dispatcher. + +## 6. Zależności między decyzjami + +```text +A3 executable evaluator + └── wymaga B1 pełnego terminalnego envelope + └── runner może bezstratnie commitować projekcje/transition + +C1 workflow inventory + outbox + ├── konsumuje terminalny wybór z B1 + └── dostarcza target i dispatch_id dla D1 + +D1 Codex binding + ├── dostarcza role_invoker do A3 + ├── uruchamia runner po B1 + └── oddaje continue do loopu realizującego C1 +``` + +Decyzje A3+B1 są fundamentem wspólnym. C1 może być wdrażane tracer-bulletem w research Phase 4. D1 zamyka ostatnią milę hosta i dopiero jego native E2E uprawnia capability flip. + +## 7. Macierz rekomendowanego zestawu + +| Wymiar | A3 evaluator | B1 ownership | C1 cursor/outbox | D1 Codex binding | +|---|---|---|---|---| +| Techniczna wykonalność | Wysoka | Wysoka | Wysoka | Średnia-wysoka | +| Prostota | Średnia | Średnia | Średnia | Średnia | +| Ryzyko | Średnie-niskie | Średnie | Średnie-niskie | Średnie | +| Portability | Wysoka | Wysoka | Wysoka | Wysoka przez cienki adapter | +| Audyt/resume | Wysoki | Wysoki | Wysoki | Wysoki przy native E2E | +| Krytyczny dowód | executable fixtures | full-record recovery | same-phase crash/resume | no-UI real host dispatch | + +## 8. Proponowany tracer bullet + +1. Ustalić wersjonowany gate envelope, `current_phase`, revision oraz `continuation` z `work_item_id` i `dispatch_id`. +2. Zaimplementować evaluator dla agreement i disagreement z jednym logicznym arbitrem oraz fake `role_invoker`. +3. Zmienić runner tak, by reużywał pełny terminalny record, a nie syntetyzował historię. +4. Zaimplementować dwa zależne work itemy w research Phase 4: area A → durable choice → area B ready → dispatch/ack. +5. Dodać cienki Codex binding zwracający `continue` do pętli oraz UI spy. +6. Udowodnić agreement, oba wyniki arbitra, crash po terminalu, crash po cursorze, same-phase i next-phase w testach. +7. Zbudować generated variants i uruchomić reproducibility/validate. +8. Uruchomić realny host-native Codex E2E; capability zmienić dopiero po exit `0`. + +## 9. Dlaczego nie pozostałe zestawy + +- A1+C4 usuwa kliknięcie w happy path, lecz nie naprawia deterministycznego resume i pozostawia root cause jako prose-only. +- A2+C3 centralizuje za dużo w runnerze, który nie zna domeny ani aktywnej tury hosta. +- A4 daje szybki Codex-only sukces kosztem drugiej semantyki gate i przyszłego driftu platform. +- B4+D4 tworzy solidną platformę eventową, ale jest nieproporcjonalne do lokalnego pluginu i obecnego minimalnego runtime. +- D2 jest technicznie czyste, lecz nowy MCP runtime warto przyjąć dopiero po dowodzie, że D1 nie może być stabilnie wykonane. + +## 10. Stretch ideas / poza zakresem + +- Wspólny machine-readable JSON Schema generujący validators, docs i fixtures dla gate/continuation envelope. +- Append-only diagnostyczny journal obok canonical snapshotu, bez zastępowania state jako source of truth. +- Generyczny workflow work-item SDK dla research, product-design i development po udanym tracer bullecie. +- Chaos/failure-injection suite dla wszystkich crash windows i filesystem modes. +- Capability manifest raportujący osobno `decision_automation`, `same_phase_continuation` i `phase_entry_continuation` zamiast jednego boolean. +- Background outbox consumer dla przyszłych nieinteraktywnych/batch workflowów; nie dla obecnej interaktywnej ścieżki. + +## 11. Źródła + +- `../analysis/synthesis.md` +- `research-report.md` +- `../analysis/findings/01-gate-state-contract.md` +- `../analysis/findings/02-continuation-dispatch.md` +- `../analysis/findings/03-codex-host-adapter.md` +- `../analysis/findings/04-verification-safety.md` +- `.maister/docs/project/architecture.md` +- `.maister/docs/project/vision.md` + diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/research-brief.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/research-brief.md new file mode 100644 index 00000000..e68f853a --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/research-brief.md @@ -0,0 +1,38 @@ +# Research brief: automatyczna kontynuacja Codex + +## TL;DR +Badanie ma przełożyć istniejącą diagnozę na konkretny, testowalny plan naprawy pełnej automatyzacji bramek Codex. +Oczekiwany algorytm: zgodność rekomendacji kończy decyzję przez advisora; rozbieżność uruchamia jednego arbitra; wynik zawsze trafia do trwałego runnera i następnego problemu bez UI. +Zakres obejmuje kontrakt stanu, adapter hosta, runner, pętlę problemów i testy; nie obejmuje implementacji. + +## Key Decisions +- Traktować oczekiwaną logikę użytkownika jako wymaganie nadrzędne dla bezpiecznych, niedenylistowanych bramek w trybie `fully_automatic` — interakcja użytkownika nie jest częścią ścieżki sukcesu. +- Wymagać jednego kanonicznego kontraktu stanu i jednego wykonywalnego punktu kontynuacji — eliminuje rozjazd między prose orchestratora, adapterem i runnerem. + +## Open Questions / Risks +- Trzeba ustalić, czy „następny problem” jest kolejnym decision area w tej samej fazie, następną fazą, czy oba przypadki muszą używać wspólnego mechanizmu dispatchu. +- Host-native Codex E2E może wymagać deterministycznego fake-advisora/arbiter harnessu zamiast zależności od rzeczywistego modelu. + +## Pytanie badawcze + +Jak naprawić Codex `fully_automatic` tak, aby: + +1. zgodność rekomendacji głównego agenta i advisora automatycznie zatwierdzała tę opcję; +2. rozbieżność wywoływała dokładnie jednego arbitra; +3. ważny wynik advisora lub arbitra był trwale zapisany przed kontynuacją; +4. workflow automatycznie przechodził do kolejnego problemu/decision area albo fazy bez pytania i kliknięcia użytkownika; +5. denylista, niska pewność, eskalacja i błędy nadal zatrzymywały się bezpiecznie. + +## Zakres + +Włączone: canonical state schema, gate engine, `phase-continue.mjs`, Codex host adapter, capability projection, dispatch kolejnego problemu, retry/resume/idempotencja, raporty i testy. + +Wyłączone: implementacja poprawki, automatyzacja chronionych bramek, rozszerzenie integracji trackerów. + +## Kryteria sukcesu + +- Jednoznaczna mapa aktualnego control flow z dokładnym miejscem zatrzymania. +- Docelowy algorytm agreement/disagreement/arbiter/continuation bez luki między decyzją a dispatch. +- Lista zmian per plik i kolejność wdrożenia bez edycji generated variants. +- Macierz testów obejmująca zgodność, obie decyzje arbitra, kolejny problem, kolejną fazę, resume, retry, denylistę i brak podwójnych wpisów. +- Jasne kryteria, po których Codex może zostać oznaczony jako `supported`. diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/research-plan.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/research-plan.md new file mode 100644 index 00000000..9143d425 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/research-plan.md @@ -0,0 +1,192 @@ +# Plan badania: naprawa automatycznej kontynuacji Codex + +## TL;DR +Badanie prześledzi pełny control flow od rekomendacji głównego agenta, przez advisora i opcjonalnego arbitra, do trwałego zapisu oraz dispatchu kolejnej jednostki pracy. +Cztery niezależne strumienie oddzielą: kontrakt gate/state, wykonanie i routing, adapter Codex oraz dowody testowe i bezpieczeństwo. +Wynikiem ma być jednoznaczny docelowy algorytm, mapa zmian per plik i macierz testów; bez implementowania poprawki. + +## Key Decisions +- Użyć technicznej metodologii iterative deepening oraz triangulacji kod–workflow prose–testy. +- Traktować „kontynuację” jako dwa osobne przypadki do udowodnienia: następny decision area/problem w tej samej fazie oraz następna faza. +- Oceniać `plugins/maister/` i `platforms/codex-cli/` jako źródła edytowalne; generated variants służą wyłącznie do weryfikacji reprodukowalności. +- Nie używać zewnętrznych źródeł: problem dotyczy lokalnego, normatywnego kontraktu Maister i hostowego adaptera Codex. + +## Open Questions / Risks +- Czy poprawny seam to rozszerzenie `phase-continue.mjs`, osobny ogólny continuation dispatcher, czy hostowa pętla nad niezmienionym runnerem fazowym? +- Kanoniczne workflowy zapisują `started_phase`, a runner wymaga `current_phase`; trzeba ustalić migrację bez dwóch źródeł prawdy. +- Normatywny rekord gate zawiera pełne dane advisora/arbitra, natomiast runner akceptuje obecnie węższy rekord; jego poszerzenie nie może osłabić walidacji exact-schema. +- Host-native E2E nie może zależeć od niedeterministycznej odpowiedzi rzeczywistego modelu; potrzebny może być fake adapter zgodny z rzeczywistym interfejsem Codex. + +## 1. Cel i oczekiwany rezultat + +Badanie ma odpowiedzieć, jak doprowadzić bezpieczny, niedenylistowany gate `fully_automatic` do następującego zachowania: + +1. Główny agent tworzy gate z dokładnymi opcjami i `original_recommendation`. +2. Advisor zwraca zwalidowaną rekomendację. +3. Gdy rekomendacje są zgodne, advisor staje się aktorem terminalnej decyzji. +4. Gdy są rozbieżne, tworzony jest dokładnie jeden logiczny arbiter; retry są próbami tego samego arbitra. +5. Terminalny wynik, pełny audit i wymagane raporty są trwale zapisane przed jakąkolwiek kontynuacją. +6. Dispatcher automatycznie uruchamia następny decision area/problem albo następną fazę, bez user gate i bez syntetycznego kliknięcia. +7. Denylista, `confidence: low`, eskalacja, wyczerpanie retry, nieobsługiwana capability lub błąd trwałego zapisu kończą ścieżkę fail-closed. + +Oczekiwane artefakty gathererów: + +- `analysis/findings/01-gate-state-contract.md` +- `analysis/findings/02-continuation-dispatch.md` +- `analysis/findings/03-codex-host-adapter.md` +- `analysis/findings/04-verification-safety.md` + +Każdy finding ma wskazać dowód `plik:linia` lub nazwę testu, confidence per wniosek, luki oraz minimalny zestaw plików, które prawdopodobnie trzeba zmienić. Gatherery nie implementują zmian. + +## 2. Metodologia + +### Etap A — broad discovery + +- Wyszukać wszystkie użycia `fully_automatic`, `evaluate_gate`, `phase_continue`, `current_phase`, `started_phase`, `gate_history`, `research-convergence`, `decision_areas` i capability matrix. +- Oddzielić źródła kanoniczne, adaptery platformowe, generated variants i test fixtures. +- Zbudować inventory producentów i konsumentów `orchestrator-state.yml`. + +### Etap B — targeted reading i flow tracing + +- Przeczytać normatywne sekcje gate engine oraz orchestrator patterns. +- Prześledzić `phase-continue.mjs` od payload validation, przez canonical-state preflight, zapis terminalny/raporty, do transition. +- Prześledzić konkretne call sites phase-exit i sekwencyjnej convergence w workflowach. +- Prześledzić generowanie Codex pluginu i dowody capability. + +### Etap C — porównanie kontraktów + +Zestawić w jednej macierzy: + +- wymagane pola state i gate history; +- aktorów i przejścia statusów; +- warunki agreement/disagreement/arbitration; +- moment trwałego zapisu; +- rezultat runnera; +- routing do kolejnej jednostki pracy; +- zachowanie resume/retry/failure. + +### Etap D — weryfikacja hipotez + +- Uruchamiać istniejące testy read-only, by potwierdzić obecny baseline. +- Dla brakujących przypadków opisać przyszłe deterministic fixtures i oczekiwane asercje. +- Nie zmieniać capability na `supported`, dopóki host-native E2E nie udowodni całej ścieżki. + +## 3. Gathering strategy — cztery niezależne kategorie + +### Kategoria 1 — Kanoniczny gate engine i schema stanu + +**Cel:** ustalić jedyny obowiązujący algorytm decyzji i znaleźć dokładne rozjazdy schema. + +**Źródła obowiązkowe:** + +- `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md:57-170, 222-330` +- `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:94-128, 275-325` +- `plugins/maister/skills/orchestrator-framework/references/gate-decision-fixtures.yml` — fixtures `advisor-agrees`, oba warianty arbitra, resume i `fully-automatic-phase-continue` +- `.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/orchestrator-state.yml` +- `.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/codex-fully-automatic-diagnosis.md` + +**Pytania:** + +1. Jaki dokładnie warunek pozwala advisorowi zakończyć gate bez arbitra i bez użytkownika? +2. Jak reprezentować „dokładnie jednego logicznego arbitra” oraz jego retry, żeby resume nie uruchomił drugiego arbitra ani advisora ponownie? +3. Który model fazy jest kanoniczny: `started_phase`, `current_phase`, czy pochodna statusów `phases[]`? +4. Czy pełny `normalized_gate_result` powinien być bezpośrednio rekordem `gate_history`, czy potrzebuje jawnej, bezstratnej projekcji runnera? +5. Które zapisy muszą być atomiczne i w jakiej kolejności przed dispatch? + +**Wynik:** proponowany canonical schema, tabela state transitions i lista niezgodności z dokładnymi producentami/konsumentami. + +### Kategoria 2 — Runner, call sites i dispatch następnej pracy + +**Cel:** znaleźć miejsce, w którym decyzja jest zapisana, lecz execution turn nie przechodzi do kolejnego problemu. + +**Źródła obowiązkowe:** + +- `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs:18-35, 210-244, 269-298, 502-589, 591-700, 711-805` +- `plugins/maister/skills/research/SKILL.md:91-120, 320-361` +- `plugins/maister/skills/product-design/SKILL.md:508-559` +- `plugins/maister/skills/development/SKILL.md:113-169, 275-290` +- `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:130-139` + +**Pytania:** + +1. Co runner robi dla payloadu bez `next_phase`, a co dla payloadu z `next_phase`? +2. Czy `phase_continue` jest właściwą abstrakcją dla kolejnego decision area w tej samej fazie, czy jedynie dla zmiany statusu faz? +3. Gdzie powinien żyć trwały continuation cursor, np. indeks decision area/problem, aby resume kontynuował dokładnie raz? +4. Kto po sukcesie runnera ma wykonywać następny dispatch: runner, host adapter czy pętla workflow orchestratora? +5. Jak rozróżnić „wybierz opcję” od „uruchom następną jednostkę pracy”, aby terminalny record nie był mylony z zakończeniem tury hosta? +6. Jak zachować sekwencyjność zależnych decision areas bez wracania do UI? + +**Wynik:** mapa control flow `gate → persistence → report → dispatch`, rekomendowany seam oraz osobne kontrakty dla same-phase advance i phase transition. + +### Kategoria 3 — Codex host adapter i capability projection + +**Cel:** ustalić minimalny host-native mechanizm, który wykonuje zwalidowany wynik, a nie tylko opisuje go w promptcie. + +**Źródła obowiązkowe:** + +- `platforms/codex-cli/templates/advisor.toml:1-18` +- `platforms/codex-cli/build.sh:182-212, 315-331` +- `platforms/codex-cli/smoke-cli.sh:66-89` +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh:1-5` +- `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` +- `Makefile:29-63` +- `plugins/maister-codex/` tylko jako wygenerowany rezultat do porównania z adapterem, nigdy jako miejsce proponowanej edycji źródłowej + +**Pytania:** + +1. Jakie rzeczywiste prymitywy Codex są dostępne do wywołania advisora/arbitra i natychmiastowej kontynuacji tej samej tury? +2. Jaki kanoniczny plik lub wrapper pod `platforms/codex-cli/` powinien mapować normalized result na dokładny JSON runnera? +3. Jak adapter odróżni zgodność od rozbieżności oraz zagwarantuje jednego logicznego arbitra? +4. Jak host ma obserwować sukces: terminal state, raport, same-phase cursor/phase transition oraz uruchomienie następnej jednostki pracy? +5. Jaki deterministyczny fake advisor/arbiter zachowuje hostowy kontrakt bez zależności od modelu? +6. Kiedy dokładnie można zmienić `declared_status` Codex z `unsupported` na `supported`? + +**Wynik:** projekt interfejsu adaptera, mapa build/generation oraz dowód wymagany przez capability matrix. + +### Kategoria 4 — Testy kontraktowe, E2E, resume i safety + +**Cel:** zbudować kompletną macierz dowodów zachowania i regresji bezpieczeństwa. + +**Źródła obowiązkowe:** + +- `tests/fully-automatic-phase-continue.test.sh:13-53` +- `tests/phase-continue-contract.test.sh` — `test_accepts_canonical_state_fixtures`, `test_normal_decision_writes_deterministic_reports`, `test_denylist_stays_blocked_on_retry`, `test_changed_selection_is_rejected_without_mutation`, `test_report_failure_leaves_terminal_record_for_regeneration`, `test_transition_failure_recovers_exactly_once` +- `tests/gate-decision-engine.test.sh` +- `tests/fixtures/phase-continue/*.yml` +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` +- `.maister/docs/standards/testing/test-writing.md` +- `.maister/docs/standards/global/build-pipeline.md` + +**Pytania:** + +1. Jakie istniejące testy dowodzą persistence i phase transition, a czego nie dowodzą w zakresie advisora, arbitra i kolejnego problemu? +2. Jakie fixtures są potrzebne dla: agreement, arbiter wybiera original, arbiter wybiera advisor, kolejny decision area, następna faza, interrupted resume i retry exhaustion? +3. Jak asercjami udowodnić: jeden wpis historii, jeden logical arbiter, brak user prompt, brak podwójnego dispatchu i byte-exact non-mutation po odrzuceniu? +4. Jak wstrzykiwać awarie state/report/dispatch, żeby wykazać właściwą kolejność trwałości? +5. Jak rozdzielić szybkie testy kontraktowe od host-native E2E, które jest jedynym dowodem capability? + +**Wynik:** macierz testów z poziomem (fixture/unit/contract/host-E2E), setupem, oczekiwanym stanem i negatywnymi asercjami. + +## 4. Plan syntezy + +Synteza ma scalić findings w następującej kolejności: + +1. **Aktualny control flow** — dokładny diagram od gate call site do miejsca zatrzymania tury. +2. **Rozjazdy kontraktowe** — state schema, gate record, runner payload, continuation target. +3. **Docelowy algorytm** — agreement, disagreement, jeden arbiter, fail-closed i idempotentny resume. +4. **Continuation model** — wspólny model kolejnego problemu i kolejnej fazy albo uzasadnione rozdzielenie tych mechanizmów. +5. **Zmiany per plik** — wyłącznie źródła kanoniczne i adapter Codex; generated variants jako wynik `make build`. +6. **Kolejność wdrożenia** — schema/fixtures → runner/dispatcher → adapter → workflow call sites → E2E/capability. +7. **Macierz akceptacji** — wszystkie ścieżki pozytywne, resume/retry oraz granice bezpieczeństwa. + +## 5. Kryteria zakończenia badania + +Badanie jest kompletne, gdy raport: + +- wskazuje jeden konkretny punkt obecnego zatrzymania oraz odpowiedzialną warstwę; +- podaje bezsprzeczny algorytm agreement/disagreement/arbitration; +- definiuje durable cursor/dispatch dla kolejnego decision area i transition dla kolejnej fazy; +- wskazuje dokładne pliki źródłowe do zmiany i generated outputs do regeneracji; +- zawiera test host-native, który kończy się kodem `0` i obserwuje brak UI oraz realny następny dispatch; +- zachowuje denylistę, low confidence, escalation, retry exhaustion i transactional failure jako fail-closed; +- nie rekomenduje `supported` przed przejściem pełnego Codex E2E. diff --git a/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/sources.md b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/sources.md new file mode 100644 index 00000000..9e1b015d --- /dev/null +++ b/.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/sources.md @@ -0,0 +1,247 @@ +# Źródła badania: automatyczna kontynuacja Codex + +## TL;DR +Źródłami pierwszego rzędu są kanoniczny gate engine, runner, workflow call sites, adapter Codex i ich testy. +Wcześniejsza diagnoza stanowi punkt startowy, ale każdy jej wniosek musi zostać ponownie potwierdzony kodem lub testem. +Generated variants są materiałem porównawczym; nie są źródłowym miejscem naprawy. + +## Key Decisions +- Priorytet dowodowy: wykonywalny kod i testy > normatywny kontrakt > dokumentacja architektury > wcześniejsza diagnoza. +- Nie planować researchu webowego, ponieważ oczekiwane zachowanie i capability są definiowane lokalnie przez Maister. +- Cytować `plik:linia` albo stabilną nazwę testu; dla generated variants wskazywać ich canonical origin. + +## Open Questions / Risks +- Część zachowania jest documentation-as-code, więc sprzeczność między prose i runnerem wymaga jawnego rozstrzygnięcia źródła normatywnego. +- Brak implementacji adaptera oznacza, że niektóre przyszłe pliki można wskazać tylko jako proponowany seam, nie jako istniejący dowód. +- Linijki mogą przesunąć się po równoległych zmianach; nazwy funkcji, sekcji i testów są stabilniejszym drugim identyfikatorem. + +## 1. Normatywne kontrakty + +### `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` + +Najważniejsze sekcje: + +- `evaluate_gate` i exact schemas: linie około 57-170; +- idempotency i terminal reuse: sekcja 2; +- agreement/disagreement/jeden arbiter: sekcja 3, zwłaszcza kroki 7-13; +- resume transitions: sekcja 4; +- denylista: sekcja 5. + +Pytanie źródłowe: czy implementacje i workflow call sites realizują normatywny algorytm bez user UI w ścieżce `fully_automatic`? + +### `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` + +Najważniejsze dowody: + +- linie 94-128: policy floor, capability, agreement, arbiter i trwałość; +- linie 130-139: zakaz zatrzymania tury dla AUTO-CONTINUE; +- linie 275-325: common state fields, w tym `started_phase` i `gate_history`. + +Pytanie źródłowe: gdzie prose kontraktu rozmija się z rzeczywistym schema runnera i z obowiązkowymi user-gate self-checks? + +### `plugins/maister/skills/orchestrator-framework/references/gate-decision-fixtures.yml` + +Fixtures do prześledzenia: + +- `advisor-agrees`; +- `advisor-disagrees-arbiter-original`; +- `advisor-disagrees-arbiter-advisor`; +- `advisor-timeout-retry` i `advisor-retry-exhausted`; +- `resume-advisor-pending` i `resume-arbiter-pending`; +- `fully-automatic-phase-continue`. + +Pytanie źródłowe: które fixtures są tylko deklaratywną specyfikacją, a które rzeczywiście uruchamia test harness? + +### `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` + +Dowód: wiersz `host: codex` deklaruje `unsupported` i wskazuje host-native target. + +Pytanie źródłowe: jakie dokładne kryteria przejścia targetu pozwalają bezpiecznie zmienić deklarację? + +## 2. Wykonywalny runner i state fixtures + +### `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` + +Punkty wejścia i funkcje: + +- linie 18-35 — wymagane i opcjonalne pola payloadu; jedynym routing field jest `next_phase`; +- `validatePayload` około linii 209-244 — exact membership, actor i confidence; +- `HISTORY_FIELDS` około linii 281-298 — wąski rekord persisted history; +- `validateHistoryRecord` linie 502-527 — odrzucenie dodatkowych pól; +- `validateCanonicalState` linie 529-562 — canonical anchors i opcjonalny `current_phase`; +- `validateTransition` linie 564-577 — przejście wyłącznie do późniejszej pending phase; +- `appendGateHistory` linie 642-659; +- `updatePhaseState` linie 661-700; +- `renderReports` około linii 711-739; +- `main` około linii 741-805 — terminal reuse, write ordering i transition. + +Pytania źródłowe: + +- Czy payload bez `next_phase` robi cokolwiek poza trwałym wyborem? +- Czy runner może bezpiecznie zaakceptować pełny rekord advisor/arbiter bez utraty exact-schema validation? +- Czy sequence terminal write → reports → transition jest naprawdę atomiczna na wszystkich failure paths? + +### `tests/fixtures/phase-continue/` + +Źródła fixture: + +- `valid-empty.yml` i `valid-populated.yml`; +- `invalid-history-record.yml`; +- fixtures missing/duplicate/misplaced anchors; +- fixtures malformed phases i unsupported YAML. + +Pytanie źródłowe: czy fixture przypomina realny state generowany przez aktywne workflowy, czy tylko węższy kontrakt runnera? + +## 3. Workflow call sites i routing + +### `plugins/maister/skills/research/SKILL.md` + +Najważniejsze sekcje: + +- linie 91-120 — JSON runner contract i inventory gate types; +- linie 320-361 — phase-3 exit, sekwencyjne decision areas i phase-4 exit; +- resume check przy `phase_summaries.phase-4.decision_areas`. + +Pytanie źródłowe: jak po terminalnym `research-convergence` wykonać automatycznie krok `record choice → move to next area` bez konieczności następnej wiadomości użytkownika? + +### `plugins/maister/skills/product-design/SKILL.md` + +Najważniejsze sekcje: convergence i routing około linii 508-559. + +Pytanie źródłowe: czy analogiczna pętla decision areas wymaga tego samego continuation cursor i czy poprawkę należy uogólnić na wszystkie call sites? + +### `plugins/maister/skills/development/SKILL.md` + +Najważniejsze sekcje: + +- gate engine i runner contract około linii 113-169; +- routing phase około linii 275-290. + +Pytanie źródłowe: czy istnieją już wzorce compute-and-persist routing, które mogą stanowić canonical seam dla automatycznej kontynuacji? + +## 4. Adapter Codex i generowanie + +### `platforms/codex-cli/templates/advisor.toml` + +Dowody: linie 6-18 definiują read-only output, jeden advisor używany również jako arbiter i prose `phase_continue(selected_option)`. + +Pytanie źródłowe: jaki wykonywalny komponent konsumuje ten czteropolowy YAML? Obecna diagnoza twierdzi, że żaden. + +### `platforms/codex-cli/build.sh` + +Najważniejsze dowody: + +- linie 182-212 generują `resume` i odwołują się do `current_phase`; +- linie 315-331 opisują state i jedynie walidują wpis capability matrix; +- brak jawnego generatora continuation wrappera należy potwierdzić pełnym flow skryptu. + +### `platforms/codex-cli/smoke-cli.sh` + +Dowody: linie 66-89 sprawdzają obecność prose i struktury, w tym tekst `phase_continue(selected_option)`, lecz nie wykonują continuation. + +### `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` + +Dowód: linie 1-5 bezwarunkowo wypisują `UNAVAILABLE` i kończą kodem `77`. + +### `plugins/maister-codex/` + +Użycie: tylko sprawdzić, czy `make build-codex` poprawnie projektuje canonical sources i adapter. Nie proponować bezpośrednich edycji. + +## 5. Testy i capability enforcement + +### `tests/fully-automatic-phase-continue.test.sh` + +Dowody: + +- linie 13-30 tworzą state z `current_phase`; +- linie 32-42 sprawdzają terminal decision, raport i transition phase-1 → phase-2; +- linie 44-46 sprawdzają terminal reuse; +- linie 48-51 sprawdzają denylistę. + +Luka do sprawdzenia: test nie uruchamia advisora, arbitra ani następnego decision area i nie jest host-native. + +### `tests/phase-continue-contract.test.sh` + +Stabilne test names: + +- `test_accepts_canonical_state_fixtures`; +- `test_normal_decision_writes_deterministic_reports`; +- `test_denylist_stays_blocked_on_retry`; +- `test_changed_selection_is_rejected_without_mutation`; +- `test_terminal_retry_validates_transition_before_reports`; +- `test_no_transition_and_forward_transition_are_distinct`; +- `test_report_failure_leaves_terminal_record_for_regeneration`; +- `test_transition_failure_recovers_exactly_once`. + +Pytanie źródłowe: jakie dodatkowe asercje są potrzebne dla one-arbiter, no-user-UI, same-phase cursor i exactly-once dispatch? + +### `tests/gate-decision-engine.test.sh` + +Użycie: ustalić, czy deklaratywne fixtures agreement/arbitration są wykonywane, a nie tylko grep-checkowane. + +### `Makefile` + +Dowody: + +- linie 3-7: runner contract jest wykonywany dla source i wszystkich generated variants; +- linie 29-42: exit `77` projektuje capability jako `unsupported`; +- linie 44-52: deklaracja musi odpowiadać host-native evidence; +- linie 54-63: shared runner matrix nie zastępuje host E2E. + +## 6. Dokumentacja projektu i standardy + +### `.maister/docs/project/architecture.md` + +Reguły: canonical plugin + platform adapters, `orchestrator-state.yml` jako jedyne source of truth, terminal persistence przed continuation, jeden logiczny arbiter. + +### `.maister/docs/project/vision.md` + +Reguły: audytowalność, resumability, fail-closed i zachowanie native host constraints. + +### `.maister/docs/project/roadmap.md` + +Priorytety: runtime continuation coverage i Advisor/Arbiter assurance. + +### `.maister/docs/project/tech-stack.md` + +Kontekst: Node.js ESM jako runtime continuation; Bash i Make jako build/test harness. + +### `.maister/docs/standards/global/build-pipeline.md` + +Reguła: edytować `plugins/maister/` lub `platforms/`, następnie `make build`; nie edytować generated variants bezpośrednio. + +### `.maister/docs/standards/global/validation.md` + +Reguła: strict allowlists, early validation i spójne enforcement na każdym entry point. + +### `.maister/docs/standards/testing/test-writing.md` + +Reguła: testować zachowanie oraz byte-exact non-mutation/rollback dla odrzuconych i przerwanych zapisów stanu. + +## 7. Materiał kontekstowy + +### `.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/codex-fully-automatic-diagnosis.md` + +Rola: wcześniejsza reprodukcja i hipoteza root cause. Nie traktować jej jako końcowego dowodu bez potwierdzenia aktualnymi plikami i testami. + +### `.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/planning/research-brief.md` + +Rola: zakres, wymagania użytkownika i kryteria sukcesu bieżącego badania. + +### `.maister/tasks/research/2026-07-13-fix-codex-auto-continuation/orchestrator-state.yml` + +Rola: realny przykład stanu wygenerowanego przez aktywny workflow; kluczowy do porównania z runner fixtures. + +## 8. Polecenia baseline do użycia przez gathererów + +Polecenia są diagnostyczne i nie zmieniają źródeł: + +```bash +bash tests/gate-decision-engine.test.sh +bash tests/fully-automatic-phase-continue.test.sh +bash tests/phase-continue-contract.test.sh +bash platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh +make -s print-host-capabilities +``` + +Oczekiwany baseline należy zapisać wraz z exit code. Kod `77` dla Codex E2E jest oczekiwanym dowodem obecnej niedostępności, nie sukcesem. diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/codex-fully-automatic-diagnosis.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/codex-fully-automatic-diagnosis.md new file mode 100644 index 00000000..de4c1d2d --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/codex-fully-automatic-diagnosis.md @@ -0,0 +1,130 @@ +# Diagnoza: `fully_automatic` nie kontynuuje workflowu na Codex + +## TL;DR +Wspólny runner `phase-continue.mjs` działa, lecz adapter Codex nie posiada host-native warstwy, która przekazuje zatwierdzoną decyzję advisora do runnera i obserwuje przejście fazy. +Codex E2E jest celowym placeholderem, który bezwarunkowo kończy się kodem `77`, więc macierz capability prawidłowo projektuje host jako `unsupported`. +Dodatkowym blockerem jest rozjazd kanonicznego schematu: aktywne workflowy używają `started_phase` i bogatych rekordów gate, podczas gdy runner oczekuje `current_phase` i węższego `gate_history`. +Naprawa wymaga najpierw ujednolicenia state contractu, następnie adaptera wykonawczego Codex i prawdziwego testu host-native E2E. + +## Key Decisions +- Nie oznaczać Codex jako `fully_automatic: supported` bez przechodzącego host-native E2E — wspólne testy runnera nie dowodzą integracji hosta. +- Ujednolicić jeden kanoniczny schema contract przed podłączeniem adaptera — obecny runner odrzuci stan generowany przez workflowy. +- Zachować ręczny fail-closed fallback do czasu uzyskania dowodu przejścia fazy na Codex. + +## Open Questions / Risks +- Trzeba wybrać kanoniczne pole aktywnej fazy: obecne `started_phase` czy wymagane przez runner `current_phase`. +- Trzeba rozstrzygnąć, czy pełne dane `advisor`/`arbiter` pozostają bezpośrednio w `gate_history`, czy runner ma zaakceptować rozszerzony rekord. +- Brakuje deterministycznego harnessu Codex, który uruchamia advisora, waliduje wynik, wywołuje runner i obserwuje trwałe przejście. +- Zmiana samego `declared_status` na `supported` ukryłaby lukę i złamała fail-closed capability contract. + +## 1. Objaw i deterministyczna reprodukcja + +Polecenie: + +```bash +bash platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh +``` + +Wynik: + +```text +UNAVAILABLE: no deterministic Codex adapter harness executes and observes native continuation +``` + +Proces kończy się kodem `77`. Reprodukcja jest natychmiastowa i deterministyczna, ponieważ test zawiera wyłącznie komunikat diagnostyczny oraz bezwarunkowe `exit 77`. + +Macierz interpretuje wynik `77` jako `evidence=unavailable`, a każdy wynik inny niż `passed` projektuje jako `unsupported`. `make -s print-host-capabilities` potwierdza: + +```text +HOST_CAPABILITY host=codex declared=unsupported projected=unsupported evidence=unavailable target=platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh +``` + +## 2. Co działa + +Wspólny runner nie jest przyczyną pierwotną. Polecenie: + +```bash +bash tests/fully-automatic-phase-continue.test.sh +``` + +przechodzi i potwierdza: + +- zapis terminalnej decyzji, +- `continuation: phase_continue`, +- przejście `phase-1 → phase-2`, +- idempotentne ponowienie, +- blokadę automatyzacji dla denylisted gate. + +To izoluje usterkę do integracji hosta Codex i zgodności jego realnego stanu z runnerem. + +## 3. Root cause + +### 3.1 Brak wykonywalnego adaptera Codex + +`platforms/codex-cli/templates/advisor.toml` opisuje w promptcie, że orchestrator ma wywołać `phase_continue(selected_option)`, ale opis nie stanowi implementacji. Poza template i smoke assertion w `platforms/codex-cli/` nie istnieje kod mapujący: + +```text +valid advisor result + → terminal persistence/report + → phase-continue.mjs + → observed phase transition +``` + +`platforms/codex-cli/build.sh` jedynie sprawdza, czy macierz zawiera wiersz Codex i ścieżkę targetu E2E. Nie generuje wrappera, hooka ani innego host-native continuation adaptera. + +### 3.2 E2E jest placeholderem + +`platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` nie próbuje uruchomić Codex ani adaptera. Jego treść celowo dokumentuje brak harnessu i zawsze zwraca `77`. + +Jest to prawidłowy fail-closed marker, ale oznacza, że capability nie zostało jeszcze zaimplementowane. + +### 3.3 Runner i workflow używają różnych schematów + +Runner waliduje: + +- rootowe `phases`, +- `orchestrator.current_phase` przy przejściu, +- dokładnie określony zestaw pól `gate_history`, w tym `continuation`, +- brak dodatkowych pól w rekordzie historii. + +Bieżące workflow zapisuje: + +- `orchestrator.started_phase`, bez `current_phase`, +- rootowe `phases`, +- rozszerzone rekordy z `policy`, `safety_classification`, `advisor` i `arbiter`, +- brak `continuation` w rekordach tworzonych przez orchestrator. + +W efekcie samo podłączenie istniejącego runnera do obecnego stanu nie wystarczy: preflight odrzuci state przed wykonaniem przejścia. + +## 4. Odrzucone hipotezy + +1. **Uszkodzony wspólny runner** — odrzucone, ponieważ test pełnego runner contractu przechodzi. +2. **Błędna konfiguracja advisora jako jedyna przyczyna** — odrzucone; nawet poprawna odpowiedź advisora nie ma obecnie host-native ścieżki wykonania. +3. **Wyłącznie błędny wpis capability matrix** — odrzucone; wpis `unsupported` odpowiada faktycznemu wynikowi targetu `77`. + +## 5. Zalecana kolejność naprawy + +1. Wybrać i udokumentować jeden kanoniczny schema state dla wszystkich orchestratorów i runnera. +2. Dostosować generator workflow state oraz `phase-continue.mjs` do tego samego schematu i dodać contract fixtures na realnych rekordach advisor/arbiter. +3. Zaimplementować adapter Codex, który przyjmuje wyłącznie zwalidowany wynik advisora i wywołuje runner przez dokładny JSON contract. +4. Zastąpić placeholder prawdziwym E2E obserwującym zapis stanu, raport oraz przejście fazy. +5. Dopiero po zielonym E2E zmienić `declared_status` Codex na `supported`. + +## 6. Kryteria akceptacji + +- Codex host-native E2E kończy się kodem `0`, a nie `77`. +- Advisor zgodny z rekomendacją automatycznie przechodzi przez bezpieczny gate bez pytania użytkownika. +- Stan i raport są trwałe przed zmianą fazy. +- Ponowne wykonanie tego samego gate nie duplikuje historii ani przejścia. +- Denylisted gate nadal wymaga użytkownika. +- Ten sam realny `orchestrator-state.yml` przechodzi walidację runnera bez transformacji ad hoc. + +## 7. Pliki dowodowe + +- `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh` +- `platforms/codex-cli/build.sh` +- `platforms/codex-cli/templates/advisor.toml` +- `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` +- `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` +- `tests/fully-automatic-phase-continue.test.sh` +- `Makefile` (`print-host-capabilities`, `validate-host-capabilities`) diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/01-maister-internals.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/01-maister-internals.md new file mode 100644 index 00000000..01d7eb5c --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/01-maister-internals.md @@ -0,0 +1,190 @@ +# Category 1 Findings: Maister Internals and Platform Adapters + +## TL;DR +Maister has a strong workflow-state boundary but no durable tracker boundary: `/work` recognizes issue-like inputs and `task-classifier` fetches them ad hoc, while research/development initialize only from prose or Maister task paths. `quick-plan` is not an orchestrated task and owns no `orchestrator-state.yml`. +The safest design is a small canonical issue-intake skill plus a dependency-free executable provider helper, with project defaults in `.maister/config.yml` and a normalized immutable snapshot/reference passed into each workflow before its existing initialization. +Tracker status, comments, assignments, and provider-native metadata must stay tracker-owned; workflow state should retain provenance and the start-time snapshot only. Canonical edits belong under `plugins/maister/` and `platforms/`, then flow through deterministic generated variants. +Platform adapters materially differ in commands, questions, planning, progress, agents, and argument injection, so a new public skill is safer than a command-only feature and still requires adapter/contract coverage. + +## Key Decisions +- Keep tracker intake outside phase execution state — `orchestrator-state.yml` becomes authoritative only after research/development starts, while the tracker remains authoritative for the live work item. +- Resolve and snapshot an issue before creating workflow state — downstream phases then operate reproducibly even if the provider is offline or the issue changes. +- Put shared provider execution in one canonical, dependency-light helper and expose it through a canonical public skill — this preserves documentation-as-code while avoiding four prose implementations of parsing, validation, and subprocess behavior. +- Preserve direct prose and existing Maister-task-path inputs — issue references are an additional intake form, not a replacement. + +## Open Questions / Risks +- `quick-plan` has divergent persistence: Claude/Codex use host planning, while Cursor/Kiro require `.maister/plans/*.md`; the product must decide where issue provenance is recorded on native-plan hosts. +- `/work` currently claims generic issue integration without a provider contract, stable reference grammar, authentication boundary, or durable transfer of fetched content. +- Cursor and Kiro use explicit command-collapse/argument allowlists; adding only a canonical command can silently omit or under-adapt the feature on those hosts. +- All four host-native automatic-continuation capabilities are currently declared unsupported, so provider logic must not assume automatic gate continuation or synthetic prompt answers. +- The documented/observed workflow state shape and executable continuation state shape currently disagree (`started_phase` plus nested `orchestrator.phases` versus `current_phase` plus root `phases`); adding issue provenance must not deepen this split. + +## Evidence and Verification Method + +This report treats `plugins/maister/` as canonical, `platforms/*` as adapter-owned, and `plugins/maister-{codex,cursor,kiro}/` as generated parity evidence only. That ownership is direct evidence in `.maister/docs/project/architecture.md` under **Architecture Pattern** and **Generated Variants**, and in `.maister/docs/standards/global/build-pipeline.md` under **Canonical Source and Reproducible Generated Variants**. + +Local verification on 2026-07-13 used `rg`, full-file/range reads, generated-output parity inspection, and these focused tests: + +- `tests/phase-continue-contract.test.sh`: **21 passed, 0 failed**. +- `tests/advisor-config-reconciliation.test.sh`: **13 passed**. +- `tests/host-capability-matrix.test.sh`: **6 passed, 0 failed**. + +No product code or generated plugin tree was modified. **Confidence: High (98%)** for the inspected current-state claims; recommendations are explicitly marked and capped lower where product choices remain. + +## 1. Current Intake, Initialization, and Resume Model + +### Workflow comparison + +| Entry point | Accepted context today | Initialization and persistence | Resume behavior | Evidence type and confidence | +|---|---|---|---|---| +| `/maister:research` | Research question; `--type`; brainstorming/design flags; an existing research task path plus `--from=PHASE` | Captures UTC time, creates phase tasks, creates `.maister/tasks/research/YYYY-MM-DD-*`, writes `orchestrator-state.yml`, snapshots project config into state, optionally creates dashboard files, then writes brief/plan/findings/report | Artifact-aware Phase 1 resume checks plus state-driven phase resume | Direct: `plugins/maister/skills/research/SKILL.md`, **Initialization**, **Phase 1: Research Foundation**, **Domain Context**, **Command Integration**. High (98%). | +| `/maister:quick-plan` | Task argument or a user question | Canonical Claude flow enters host plan mode and has **no task directory or `orchestrator-state.yml`**. Cursor/Kiro override it with `.maister/plans/YYYY-MM-DD-plan-name.md` plus an approval gate | No canonical resumable orchestrator; the plan artifact is the durable object only on Cursor/Kiro | Direct: `plugins/maister/skills/quick-plan/SKILL.md`, **Workflow**; `platforms/cursor/overrides/skills/quick-plan/SKILL.md`, **Workflow**; `platforms/kiro-cli/overrides/commands/quick-plan.md`, **Workflow**. High (97%). | +| `/maister:development` | Prose description; a research task folder; `--research=PATH`; a product-design task path or inline mockup path; phase and optional flags | Resolves research/design context, captures UTC time, creates phase tasks and `.maister/tasks/development/YYYY-MM-DD-*`, writes state containing task/research references, snapshots config, discovers project docs, and optionally creates dashboard/design-context files | Reads state and expected artifacts, restores ephemeral phase-task UI, and resumes at first incomplete phase | Direct: `plugins/maister/skills/development/SKILL.md`, **Initialization**, **Research-Based Development**, **Design-Informed Development**, **Command Integration**. High (98%). | +| `/work` | Existing task path/name, prose, no argument, or advertised GitHub/Jira/Azure issue forms (`#456`, `GH-456`, `PROJ-456`, `AB#123`, URLs) | Does not own workflow state. It detects an existing task and routes resume, or delegates classification and invokes the selected orchestrator with a description | Reads an existing task's state, derives status/next phase, asks how to resume, then passes `--resume`/`--from` to the owning orchestrator | Direct: `plugins/maister/commands/work.md`, **Input Types**, **Step 1**, **Step 2**, **Step 3**. High (96%). | + +### Existing issue intake is real but incomplete + +**Direct evidence.** `plugins/maister/commands/work.md` advertises issue identifiers and delegates new input to `plugins/maister/agents/task-classifier.md`. Under **Phase 1: Input Processing & Issue Fetching**, that agent recognizes GitHub, Jira, Azure DevOps, and generic URLs, then tries MCP, vendor CLI, `WebFetch`, and finally a user prompt. Its output schema under **Phase 5: Output Classification** retains only a small `issue_source` projection (`type`, `identifier`, `title`, `labels`). + +**Inference.** The fetched body/comments/state can influence classification in the isolated classifier, but `/work` subsequently routes with `args: "[description]"`; no canonical payload requires the enriched issue body, retrieval timestamp, provider identity, revision/digest, or normalized reference to reach the selected workflow. A routed workflow can therefore start from less context than the classifier used, and resume cannot reconstruct exactly what was fetched. **Confidence: High (92%)**, based on both command and agent contracts; there is no end-to-end test proving a richer hidden handoff. + +**Recommendation.** Replace classifier-owned retrieval with a shared intake result consumed by both classifier and routed workflow. The classifier should classify a normalized snapshot, not own provider fallback policy. **Confidence: Medium (84%)** because the boundary is strongly evidenced but the exact API is a design choice. + +### End-to-end current initialization trace: this research task + +The active task itself supplies an observed instance of the canonical research path: + +1. **Input becomes workflow context.** `/maister:research [question]` is parsed as a mixed research task (`plugins/maister/skills/research/SKILL.md`, **Initialization** and **Research Types**). +2. **The shared contract is loaded.** The skill reads `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md`; **§4 State Schema** and **§5 Initialization & Resume** define the canonical state and ordering. +3. **A real clock value is captured.** The current state records `created: "2026-07-13T13:53:40Z"`, not a guessed date (`.maister/tasks/research/2026-07-13-issue-tracker-workflow/orchestrator-state.yml`, `orchestrator.created`). +4. **Phase UI and task directory are created.** Six phase records are persisted under `.maister/tasks/research/2026-07-13-issue-tracker-workflow/`; Phase 1 is `in_progress`, later phases retain `blocked_by` edges. +5. **Project config is normalized into state once.** `.maister/config.yml` has `html_output: true` and Advisor policies; the task state contains the complete effective snapshot under `orchestrator.options`. The research skill's **Domain Context** explicitly says resume reads canonical state and does not reread project config. +6. **Authoritative and derived artifacts separate.** `orchestrator-state.yml` is authoritative; `dashboard.html` is a copied plugin asset and `dashboard-data.js` is a projection (`orchestrator-patterns.md`, **§8 Operator Dashboard**). +7. **Phase 1 artifacts accumulate with resume markers.** The brief, plan, and source register exist; state records `steps_completed: [initialize, plan]`. `research/SKILL.md`, **Phase 1**, resumes by checking these artifacts before gather/synthesis. +8. **A later resume starts from state.** Shared **§5 Task Restoration on Resume** recreates host task UI because host IDs are ephemeral, validates expected artifacts, and finds the first incomplete phase without making the dashboard authoritative. + +This is direct local evidence plus the canonical contract. **Confidence: High (99%)**. + +### Verified state-schema contradiction + +**Direct evidence.** `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md`, **§4 Common Fields**, specifies `orchestrator.started_phase`; the active research state follows that name and nests `phases` under `orchestrator`. In contrast, `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` `validateCanonicalState` requires exactly one root-level `phases` sequence, and `validateTransition` requires `orchestrator.current_phase`. `tests/fixtures/phase-continue/valid-empty.yml` and `tests/phase-continue-contract.test.sh` exercise the executable shape, including explicit rejection when root `phases` is absent. + +**Inference.** The active task state would not satisfy the continuation runner's canonical preflight. This does not currently create an automatic transition because every host is capability-matrix `unsupported`, but it is a real prerequisite for future automatic continuation and a warning against inventing a third location for `source_issue`. **Confidence: High (97%)**. + +**Recommendation.** Reconcile and fixture one canonical workflow-state schema before or in the same development tranche as issue provenance, then place `source_issue` at one shared, tested anchor. Do not make provider code compensate for both shapes. **Confidence: High (92%)**. + +## 2. State and Content Ownership + +### What must enter the workflow at initialization + +**Recommendation:** resolve issue input before the existing clock/task-directory/state sequence and persist the following normalized, immutable intake data: + +- `source_issue.ref`: canonical provider-qualified reference. +- `source_issue.provider`: selected provider key and provider kind, not credentials. +- `source_issue.retrieved_at`: real UTC timestamp. +- `source_issue.revision`: provider revision/update token when available, otherwise `null`. +- `source_issue.digest`: digest of the normalized snapshot for drift/audit checks. +- Snapshot fields needed to execute offline: native ID, title, body/description, labels/tags, state at retrieval, canonical URL if available, and selected acceptance criteria/context. +- Retrieval warnings and capabilities actually used, so degraded behavior is auditable. +- For research/development, a human-readable immutable artifact such as `analysis/intake/issue-snapshot.md`, referenced from state; for quick-plan, the same provenance/snapshot summary in the plan artifact or its host-native equivalent. + +This mirrors existing research-to-development behavior: `plugins/maister/skills/development/SKILL.md`, **Research-Based Development**, stores a compact `research_reference` in state and copies durable artifacts into `analysis/research-context/`. **Confidence: Medium-High (88%)**; the pattern is direct, field selection is recommended. + +### What must remain tracker-owned + +The provider remains authoritative for live status/workflow state, comments and discussion history, assignments, projects/milestones, dependencies, custom fields, attachments, reactions, and all later edits. Workflow phases must not mirror these mutable fields into `orchestrator-state.yml` as a second backlog. A later explicit refresh may compare provider revision/digest and append a new snapshot or drift notice; it must not silently rewrite the start-time snapshot. + +**Inference from current architecture.** `.maister/docs/project/architecture.md`, **Persistence Model**, makes `orchestrator-state.yml` the sole resume source for workflow execution, while the research brief explicitly separates persistent work intake from execution state. Therefore the state may own source provenance and the exact input used, but not the provider's live lifecycle. **Confidence: High (94%)**. + +### Canonical versus generated ownership + +- **Canonical and editable:** `plugins/maister/skills/**`, `plugins/maister/commands/**`, `plugins/maister/agents/**`, shared executable/reference files under `plugins/maister/skills/orchestrator-framework/**`, and host adaptations under `platforms/**`. +- **Project-owned runtime data:** `.maister/config.yml`, tracker-local data if local Markdown is selected, `.maister/tasks/**`, and `.maister/plans/**` where the host adapter uses file planning. +- **Generated, never edited directly:** `plugins/maister-codex/**`, `plugins/maister-cursor/**`, `plugins/maister-kiro/**`. + +Direct evidence: `.maister/docs/project/architecture.md`, **System Structure**; `.maister/docs/standards/global/build-pipeline.md`; `.github/workflows/validate-generated-variants.yml`, drift check. **Confidence: High (99%)**. + +## 3. Seam Map: Exact Proposed Integration Locations + +The paths marked “new” are recommendations, not existing files. + +| Concern | Safest canonical seam | Exact integration locations | Why this seam fits | +|---|---|---|---| +| Tracker configuration | `.maister/config.yml`; scaffold/upgrade in `plugins/maister/skills/init/SKILL.md`, **Advisor pre-flight** / **Phase 5: Initialize Documentation Structure** | Add a top-level tracker block and normalize it before workflows snapshot config. If strict mutation is needed, add a sibling helper rather than widening Advisor-specific `plugins/maister/skills/init/bin/reconcile-advisor-config.sh`. | Config is already project-local, optional, read-once at workflow initialization, and copied into state. The Advisor reconciler's `build_candidate`, `commit_file`, `restore_file`, and `run_init_transaction` are the atomic/fail-closed precedent, not a generic parser API. | +| Reference parsing and provider selection | **New:** `plugins/maister/skills/issue-tracker/references/issue-ref.md` plus `plugins/maister/skills/issue-tracker/bin/issue-tracker.mjs` | The helper should accept a strict JSON/stdin or narrow CLI contract, parse provider-qualified refs, resolve defaults, and emit normalized JSON/errors. | A single executable avoids inconsistent regex/shell quoting in four host prose variants. Node ESM is already an accepted dependency for `phase-continue.mjs`; no package dependency is needed. | +| Issue retrieval and capability discovery | Same new helper and provider modules/resources under `plugins/maister/skills/issue-tracker/` | Move MCP/CLI/HTTP/filesystem preference and validation out of `plugins/maister/agents/task-classifier.md`, **Phase 1**, so classifier consumes a snapshot. Provider-specific operations remain capability-gated. | Current MCP → CLI → WebFetch fallback is agent prose, has no stable error contract, and is not reusable by direct research/development/quick-plan invocation. | +| Fast capture, list, show, select | **New public skill:** `plugins/maister/skills/issue-tracker/SKILL.md` | Expose capture/read/list/select as explicit modes. Add thin files under `plugins/maister/commands/` only if Claude slash aliases are required; otherwise public skill invocation minimizes adapter work. | Architecture says orchestration belongs in skills and commands should delegate. Codex automatically converts every command, but Cursor/Kiro command collapse is allowlisted, so a skill-first surface is less fragile. | +| Unified `/work` intake | `plugins/maister/commands/work.md`, **Step 1** and **Step 3**; `plugins/maister/agents/task-classifier.md`, **Phase 1** and output schema | Resolve input once through issue-tracker skill/helper, pass normalized snapshot to classifier, then pass the same result to the routed workflow. Existing task-folder detection remains first and unchanged. | `/work` is already the only advertised issue-aware entry, but it currently discards the durable enriched handoff contract. | +| Research handoff | `plugins/maister/skills/research/SKILL.md`, **Initialization**, before current **Step 2: Initialize Workflow**; state schema under **Domain Context** | Accept explicit issue ref/snapshot, resolve before creating task state, derive the research question from snapshot when no override is supplied, persist `source_issue`, and write `analysis/intake/issue-snapshot.md`. | This preserves current question/flags and ensures the brief is built from the exact snapshot. | +| Development handoff | `plugins/maister/skills/development/SKILL.md`, after **Step 2: Detect Research Context** and before **Step 3: Initialize Workflow**; **Domain Context** | Add issue intake alongside research/design references; preserve research-folder precedence and direct prose. Persist `source_issue` and copy the snapshot before Phase 1 analysis. | It follows the existing `research_reference` + copied context pattern and keeps issue intake from becoming a phase. | +| Quick-plan handoff | `plugins/maister/skills/quick-plan/SKILL.md`, **Workflow step 1**, and both platform overrides | Resolve an issue before planning and require provenance in the plan. Cursor/Kiro write it into `.maister/plans/*`; Claude/Codex need an explicit native-plan provenance convention or an optional plan-side Markdown artifact. | Quick-plan has no orchestrator state, and its adapters replace the canonical planning mechanism rather than merely renaming tools. | +| Shared snapshot contract | `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md`, after **Shared: research_reference** | Add a shared `source_issue` shape and context-passing rule, but keep provider execution out of the orchestrator framework itself. | The framework is the canonical cross-workflow state/context contract; it is explicitly non-executable (`plugins/maister/skills/orchestrator-framework/SKILL.md`, **NOT an Executable Skill**). | +| Build and parity | `platforms/codex-cli/build.sh`, `platforms/cursor/build.sh`, `platforms/kiro-cli/build.sh`; `Makefile`; platform tests | Add only necessary semantic transforms, argument injection, command collapse, inventory counts, and fixtures. Regenerate all outputs with `make build`; validate with `make validate`. | The generated trees are deterministic artifacts and CI rejects drift. | + +**Recommendation confidence: Medium-High (86%).** The integration points are high-confidence; naming and whether aliases are needed are implementation choices. + +## 4. Platform Transformation and Capability Impact + +### Platform impact table + +| Host | Canonical-to-host transformation | Relevant host capabilities/differences | Issue-provider impact | Evidence and confidence | +|---|---|---|---|---| +| Claude Code | No generated adapter; `plugins/maister/` is Claude-oriented canonical source with skills, commands, Markdown agents, `AskUserQuestion`, `TaskCreate/TaskUpdate`, `Skill`/`Task`, `EnterPlanMode/ExitPlanMode`, and Bash/Read/Write vocabulary | Native user questions and plan mode; commands remain commands; provider subprocesses can be described through Bash, but writes still need explicit workflow/skill authorization | A canonical public skill/helper works directly. A thin capture command may delegate to it. Never place mutable provider credentials in plugin files or task snapshots. | Direct: canonical files and `orchestrator-patterns.md`, **§1 Delegation Rules**, **§5 Initialization**. High (96%). | +| Codex | `platforms/codex-cli/build.sh` `transform_markdown`/`transform_tree_markdown` removes Claude frontmatter and rewrites questions, task UI, plan mode, Skill/Task terminology, agent roles, instruction filename, and invocation syntax. Every canonical command becomes a skill. | No command component; no bundled custom-agent directory in current plugin MVP; source agents are expressed as native Codex subagent roles; canonical plan mode becomes “native planning flow”; `orchestrator-state.yml` remains progress authority | Put executable resources under the issue-tracker skill so `copy_skill` carries them. New canonical commands are automatically converted, but command and rich-skill name collisions must be avoided. Test strict transform residue and invocation syntax. | Direct: `platforms/codex-cli/build.sh` functions and command loop; `platforms/codex-cli/smoke-cli.sh`; `Makefile` `validate-codex`. High (98%). | +| Cursor | Copies canonical tree, renames `maister:` to `maister-`, `AskUserQuestion` to `AskQuestion`, Claude plan mode to file planning, Task UI to `TodoWrite`, commands to selected skills, framework/internal skills into `lib/`, and agents to host frontmatter/read-only policy | File-based quick plan at `.maister/plans/*`; custom agents; no default Playwright MCP; host user prompt and Todo semantics differ from canonical | New public skill directories are renamed automatically. New command aliases require edits to `merge_commands_to_skills`. A quick-plan issue handoff must update the Cursor override, not only canonical quick-plan. Provider helper subprocess/file assumptions need Cursor runtime smoke coverage. | Direct: `platforms/cursor/build.sh` `merge_commands_to_skills`, `apply_cursor_overrides`, `relocate_*`, `apply_todo_transforms`; Cursor quick-plan override and smoke Test 3. High (98%). | +| Kiro CLI | Copies/renames skills, merges an explicit command list, injects `$ARGUMENTS` only for an allowlist, replaces questions with chat gates, removes plan mode, rewrites Skill/Task/Explore/progress semantics, converts Markdown agents to JSON, and synthesizes TUI agents/hooks | No `AskQuestion`; chat-native gates; documented headless defaults for non-protected gates; `todo` TUI; slash skills/subagent tool; build lock; file-based quick plan; MCP moved to `settings/mcp.json` | Add issue skill to `skills_needing_args` or input can be lost. New command aliases require `merge_commands_to_skills`. Capture/update must never inherit a headless default that performs an external write; protected/ambiguous operations should stop. Update chat-gate, delegation, JSON generation, and inventory tests. | Direct: `platforms/kiro-cli/build.sh` functions `apply_chat_gate_transforms`, `apply_kiro_overrides`, `apply_delegation_transforms`, `apply_progress_transforms`; `transforms/askuser-to-chat-gate.md`; Kiro tests. High (99%). | + +### Cross-host automatic continuation posture + +`plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` declares Claude, Cursor, Kiro, and Codex `unsupported`. `Makefile` targets `print-host-capabilities`/`validate-host-capabilities` project missing, skipped, unavailable, inconclusive, or failed native evidence to `unsupported`; shared runner success is explicitly insufficient. The focused host-capability test passed all six cases. + +**Direct finding.** Provider operations cannot use “fully automatic workflow continuation exists” as an execution assumption. User prompts, external writes, and recovery must use each host's actual adapter and fail closed when unavailable. **Confidence: High (99%)**. + +## 5. Existing Fail-Closed and Test Patterns to Reuse + +| Existing precedent | Verified behavior | Provider behavior it should inspire | Confidence | +|---|---|---|---| +| `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` + `tests/phase-continue-contract.test.sh` | Exact payload allowlist/types/enums, duplicate-key rejection, canonical-state validation, path collision checks, stderr-only errors, byte/directory non-mutation on rejection, denylist blocking, deterministic reports, terminal idempotency, recoverable report/transition failures | Exact provider request/result schema; no shell interpolation; selected capability/operation membership; stable idempotency key for create/update; immutable state/files on validation or provider failure | High (99%); 21 cases passed locally. | +| `plugins/maister/skills/init/bin/reconcile-advisor-config.sh` (`build_candidate`, `commit_file`, `restore_file`, `run_init_transaction`) + reconciliation/lifecycle tests | Narrow YAML grammar, allowlists, portable identifiers, same-directory staging/rename, mode preservation, rollback across YAML and Codex TOML, injected-failure coverage | Validate tracker config before use; reject duplicate/ambiguous providers and unsafe paths; stage local tracker writes beside targets; preserve bytes/mode; roll back multi-file updates exactly | High (98%); 13 reconciliation cases passed locally. | +| `host-capabilities.yml`, `Makefile` capability targets, `tests/host-capability-matrix.test.sh` | Native evidence is mandatory; all uncertain outcomes project to unsupported; shared helper tests cannot prove host support | Provider capability discovery must distinguish configured/available/authenticated/supported; missing CLI/MCP/auth/network must not be treated as support | High (99%); 6 cases passed locally. | +| `platforms/*/build.sh`, `Makefile validate-*`, platform transform tests | Structural residue bans, naming/layout assertions, override checks, command inventory, chat-gate/Todo/delegation rewrites, generated runner matrix | Golden/structural tests for issue skill presence, argument preservation, ref grammar text, helper resource copying, and zero stale host vocabulary on every generated target | High (96%). | +| Cursor/Codex install tests for Playwright MCP opt-in | Optional external integration is absent by default and installed only when requested | Vendor CLI/MCP support should be capability-checked and opt-in where installation/config mutation is required; local Markdown must remain usable without it | Medium-High (89%); analogy is architectural rather than tracker-specific. | + +### Missing tests exposed by the trace + +No current test found by `rg` exercises `/work` issue forms through retrieval, classification, routing, task initialization, persisted provenance, or resume. `task-classifier` behavior is instruction-level only. This is a direct gap, **Confidence: High (96%)**. + +Minimum new behavior tests should cover: + +1. explicit prose remains byte-for-byte/semantically unchanged at each workflow entry; +2. unambiguous issue ref resolves once and the same snapshot reaches classifier plus research/development/quick-plan; +3. ambiguous shorthand, missing provider, unavailable auth/CLI/MCP, malformed provider output, and untrusted fields fail before task-state creation; +4. local Markdown create/update is atomic, path-confined, idempotent, and leaves complete state unchanged on injected failures; +5. workflow state owns snapshot/provenance but never silently mirrors later tracker mutations; +6. generated variants preserve arguments, helper resources, prompts, plan provenance, and skill discoverability; +7. external provider tests use mocks/fixtures and perform no real writes. + +## 6. Minimum Deterministic Change Set + +**Recommendation (v1):** + +1. Add one canonical public issue-tracker skill and one dependency-free helper under `plugins/maister/skills/issue-tracker/`; implement only local Markdown and GitHub operations required by actual capture/handoff journeys. +2. Extend `.maister/config.yml` and `plugins/maister/skills/init/SKILL.md` with validated provider/default configuration, excluding credentials. Reuse the Advisor reconciler's transactional techniques in a tracker-specific helper; do not overload its narrow Advisor schema. +3. Replace ad hoc retrieval in `plugins/maister/agents/task-classifier.md` with consumption of a normalized snapshot; update `plugins/maister/commands/work.md` to pass that snapshot through routing. +4. Add pre-initialization issue intake to research and development, and pre-planning intake to canonical/Cursor/Kiro quick-plan. Add a shared `source_issue` state/context schema to `orchestrator-patterns.md`. +5. Prefer a skill-first capture surface. If convenience commands/shortcuts are added, update Cursor/Kiro merge/argument allowlists explicitly; Codex's generic command conversion still needs collision and structure tests. +6. Add provider contract fixtures, transactional rejection tests, mocked GitHub tests, workflow handoff tests, and adapter golden/structural checks. Then run `make build`, inspect generated diffs, and run `make validate`; commit canonical, adapter, and generated changes together. +7. Update project/user documentation in the same change: config reference, issue reference grammar, tracker/workflow ownership, auth/offline behavior, and platform invocation examples. + +This preserves the current Markdown/YAML/Node/shell documentation-as-code architecture, adds no database or hosted service, keeps dependencies minimal, and leaves current direct prompt/task-path workflows intact. It also avoids speculative provider APIs: capability discovery can expose provider-native differences without implementing unused operations. This follows `.maister/docs/standards/global/minimal-implementation.md`, `.maister/docs/standards/global/validation.md`, `.maister/docs/standards/global/error-handling.md`, and `.maister/docs/standards/testing/test-writing.md`. + +**Recommendation confidence: Medium-High (87%).** The repository seams and safety patterns are strongly evidenced. Final confidence is limited by unresolved product choices around canonical issue-reference syntax, quick-plan provenance on native-plan hosts, and which external-write gates are protected. + +## Answers to the Six Category Questions + +1. **Current context/init/resume:** research and development are stateful orchestrators with task directories and `orchestrator-state.yml`; quick-plan is native planning or a host-specific plan file without orchestrator state; work is a stateless router that can inspect existing state and advertises ad hoc issue fetching. +2. **Safest seams:** project config/init for provider defaults; a new canonical issue-tracker skill/helper for parsing/retrieval/capture; `/work`, research/development pre-initialization, and all quick-plan variants for handoff; shared state shape in orchestrator patterns. +3. **Copy/link boundary:** persist provider-qualified ref, retrieval metadata/digest, capabilities/warnings, and an immutable execution snapshot; keep live status, comments, assignments, custom workflow, and subsequent edits tracker-owned. +4. **Platform transformations:** Claude is canonical; Codex performs generic command-to-skill/tool-vocabulary transforms; Cursor uses selected command collapse, AskQuestion/Todo, custom agents, and file planning; Kiro uses selected collapse plus `$ARGUMENTS`, chat gates, TUI todos, slash/subagent transforms, JSON agents, and file planning. +5. **Fail-closed patterns:** continuation schema/idempotency/transaction tests, Advisor config validation/staging/rollback, host capability projection, and adapter structural/install tests provide direct patterns; current issue intake lacks equivalent end-to-end tests. +6. **Minimum deterministic changes:** one canonical skill/helper, config/init extension, thin integration hooks, shared snapshot schema, adapter allowlist/override updates, behavior/transaction/platform tests, generated rebuild, and documentation updates—without a database or direct edits to generated variants. diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/02-mattpocock-skills.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/02-mattpocock-skills.md new file mode 100644 index 00000000..6c0ebc05 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/02-mattpocock-skills.md @@ -0,0 +1,318 @@ +# Category 2 Findings: Installed `mattpocock/skills` Prior Art + +## TL;DR + +The installed skills implement tracker portability through repository-local prose in `docs/agents/issue-tracker.md`, not through a typed provider API. GitHub and GitLab are substantially specified; local Markdown is useful prior art but internally inconsistent and unsafe for concurrent writers. The flow has strong handoff patterns—role labels, durable briefs, dependency frontiers, claim-before-work—but setup, spec/tickets, triage, and implementation are composable skills rather than one enforced state machine. Maister should reuse those user-facing conventions while making provider capabilities, references, snapshots, validation, and workflow-boundary state explicit. + +## Key Decisions + +- **Recommendation (92% confidence):** Keep tracker configuration repository-local and human-readable, but replace open-ended operational prose with a validated canonical provider configuration plus provider-specific instructions or adapters. +- **Recommendation (94% confidence):** Treat tracker items as persistent intake and provenance. At workflow start, capture an immutable source snapshot and stable reference; thereafter keep execution, gates, resume, and audit state in the workflow's own `orchestrator-state.yml`. +- **Recommendation (90% confidence):** Reuse readiness roles, acceptance-criterion briefs, dependency edges, frontier selection, and claim-before-work semantics, but make every operation capability-discoverable and fail closed when unsupported. +- **Recommendation (96% confidence):** Do not copy the installed local Markdown write protocol as-is. Define stable IDs, one canonical layout, atomic conditional writes, and explicit conflict behavior first. + +## Open Questions / Risks + +- Should Maister v1 expose tracker mutation after handoff (claim/comment/close), or remain read-only after capture except through an explicit completion command? +- Is `ready-for-agent` a tracker-owned intake state, a guarantee that a durable brief exists, or both? The installed skills use all three interpretations. +- Should a completed Maister workflow automatically resolve its source issue, or only propose a provider-specific completion action for approval? +- Native dependency and sub-issue capabilities vary by provider and plan. A fallback body convention is useful, but the source of truth and conflict rule must be explicit. + +## Scope and Evidence Basis + +This analysis treats the installed files under `/Users/mrapacz/.agents/skills/` as authoritative. I read the setup skill and all of its tracker seed templates in full, along with `to-spec`, `to-tickets`, `triage`, `triage/AGENT-BRIEF.md`, `implement`, and the directly referenced `wayfinder`, `domain-modeling`, `grilling`, `tdd`, and `code-review` skills. No upstream repository was inspected, so there are no upstream-only observations or version-difference claims in this artifact. + +Material claims are tagged as **Direct evidence**, **Inference**, or **Recommendation** and carry confidence according to `planning/research-plan.md` § “Confidence Rules.” Installed prose is direct evidence of the agent contract, but not proof that a vendor CLI currently supports every described command. + +## 1. Setup and Repository-Local Configuration + +### 1.1 Selection and persistence flow + +**Direct evidence (98% confidence):** Setup is an interactive, prompt-driven scaffold rather than a deterministic installer. It: + +1. Inspects remotes, root agent-instruction files, domain docs, `docs/agents/`, and `.scratch/`. +2. Walks the user through three decisions one at a time: tracker, triage label vocabulary, and domain-doc layout. +3. Proposes GitHub when a GitHub remote exists, GitLab for a GitLab remote, and otherwise offers GitHub, GitLab, local Markdown, or “Other.” “Other” is captured as free-form prose supplied by the user. +4. For GitHub/GitLab only, records whether external PRs/MRs are a triage request surface. +5. Shows drafts before writing. +6. Writes an `## Agent skills` discovery block to an existing root instruction file and writes `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, and `docs/agents/domain.md`. + +Source: `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/SKILL.md`, headings “Process,” “1. Explore,” “2. Present findings and ask,” “3. Confirm and edit,” and “4. Write.” + +**Direct evidence (97% confidence):** Root instruction-file precedence is deterministic: edit `CLAUDE.md` if present, otherwise `AGENTS.md`; if neither exists, ask. Existing `## Agent skills` content is updated in place and surrounding user edits must be preserved. Source: `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/SKILL.md`, “4. Write” → “Pick the file to edit.” + +**Direct evidence (96% confidence):** Provider persistence is prose-by-copy: + +- GitHub, GitLab, and local Markdown start from bundled seed templates. +- The selected template becomes `docs/agents/issue-tracker.md`. +- Other trackers are written from scratch using the user's paragraph. +- The generated root block points downstream skills at that document. + +Source: `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/SKILL.md`, “4. Write”; bundled templates `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md`, `issue-tracker-gitlab.md`, and `issue-tracker-local.md`. + +### 1.2 Repository-local configuration analysis for Maister + +**Direct evidence (99% confidence, observed 2026-07-13):** This repository is not currently configured for the installed skills. Both `/Users/mrapacz/Workspace/maister/CLAUDE.md` and `/Users/mrapacz/Workspace/maister/AGENTS.md` exist, but neither contains an `## Agent skills` block or a `docs/agents` reference; `docs/agents/` and `.scratch/` are absent. If the setup skill were run now, its precedence rule would target `CLAUDE.md`. This is analysis only; setup was not run and no configuration was written. + +**Inference (94% confidence):** The root block is a discovery pointer, while `docs/agents/*.md` is the operational configuration. This is a strong low-dependency pattern: instructions are versioned with the repository, reviewable in diffs, and available to any agent that reads the root file. It is not, however, machine-validatable configuration. + +**Recommendation (91% confidence):** Maister should preserve the same ownership and discoverability while separating data from guidance: + +- `.maister/config.yml`: selected provider, provider key, project/repository identity, defaults, and capability policy. +- A canonical provider contract: normalized operations, references, results, errors, and capability discovery. +- Provider-specific guidance: optional prose for host/CLI details and escape hatches. +- Root instructions: a short pointer, not duplicated operational configuration. + +### 1.3 Triage and domain configuration + +**Direct evidence (98% confidence):** `docs/agents/triage-labels.md` maps five canonical state roles to repository-specific label strings: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, and `wontfix`. Source: `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/triage-labels.md`, “Triage Labels.” + +**Direct evidence (96% confidence):** Domain configuration records single- versus multi-context layout and tells consumers to use glossary vocabulary and surface ADR conflicts. Domain files are created lazily only when terms or decisions are resolved. Sources: `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/domain.md`, “Before exploring, read these,” “Use the glossary's vocabulary,” and “Flag ADR conflicts”; `/Users/mrapacz/.agents/skills/domain-modeling/SKILL.md`, “File structure,” “Update CONTEXT.md inline,” and “Offer ADRs sparingly.” + +**Weakness—direct evidence plus inference (95% confidence):** Triage requires exactly one category role (`bug` or `enhancement`) and one state role, but setup only configures the five state-role strings. It neither maps nor verifies category labels. Sources: `/Users/mrapacz/.agents/skills/triage/SKILL.md`, “Roles”; `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/SKILL.md`, “Section B — Triage label vocabulary”; `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/triage-labels.md`. + +## 2. Implicit Provider Interface + +The provider interface is encoded as phrases downstream skills are expected to interpret using `docs/agents/issue-tracker.md`. There is no schema, executable interface, declared capability set, or normalized error model. + +### 2.1 Operation semantics + +| Phrase / operation | Installed semantic contract | Evidence | Confidence | +|---|---|---|---:| +| `publish` | Materialize a spec, ticket, or map in the selected tracker and return/use its native identity. | All three tracker templates, “When a skill says ‘publish to the issue tracker’”; `to-spec` process step 3; `to-tickets` process step 5. | 98% | +| `fetch` / `read` | Retrieve the full work item; callers often also require comments, labels, author/dates, or a PR diff. | Tracker templates, “Conventions” and “fetch the relevant ticket”; `to-tickets` step 1; `triage` step 1. | 97% | +| `list` / query | Return open items filtered by state/label; triage additionally needs age and reporter-activity ordering. | GitHub/GitLab templates, “List issues”; `triage`, “Show what needs attention.” | 94% | +| `label` / role | Map canonical triage roles to provider labels or local `Status:` values; enforce one category and one state during triage. | `triage-labels.md`; `triage`, “Roles”; tracker templates, label operations. | 96% | +| `comment` | Append durable discussion, triage notes, briefs, or resolution answers; triage-generated external text starts with an AI disclaimer. | Tracker templates, “Conventions”; `triage`, opening disclaimer and “Apply the outcome.” | 98% | +| `close` | Transition an external item out of the open queue, sometimes after a required explanatory comment. | GitHub/GitLab templates, “Close”; `triage`, “Apply the outcome.” | 97% | +| `blocking` | Store directed “blocked by” edges, preferring native UI-visible relationships and falling back to body metadata. A child is unblocked when every blocker is closed/resolved. | Tracker templates, “Wayfinding operations”; `wayfinder`, “Tickets.” | 97% | +| `frontier` | Query open children, remove blocked and claimed items, and choose the first remaining item in map order. | Tracker templates, “Frontier query/Frontier”; `wayfinder`, “Tickets” and “Work through the map.” | 98% | +| `claim` | Perform the session's first write before work so concurrent sessions skip the item; remote providers use assignee, local uses `Status: claimed`. | Tracker templates, “Claim”; `wayfinder`, “Tickets” and “Work through the map.” | 99% | +| `resolve` | Record the answer, close/mark resolved, then append a gist/link context pointer to the parent map's decision index. | Tracker templates, “Resolve”; `wayfinder`, “Work through the map.” | 98% | +| reference resolution | Interpret native number, URL, or local path in repository context; distinguish issue from PR where required. | GitHub/GitLab templates, PR/MR sections; `triage`, “Invocation”; `to-tickets`, step 1. | 88% | + +**Inference (91% confidence):** The minimum interface implied by all consumers is larger than CRUD. It includes `create`, `read-with-discussion`, `query`, `set-roles`, `comment`, `close`, `resolve-reference`, dependency operations, claim ownership, and capability/fallback selection. The installed templates leave this interface implicit, so each skill can silently assume a different subset. + +### 2.2 Provider operation matrix + +Legend: **Native** = explicitly backed by the provider CLI/native relationship; **Prose** = specified as file editing or convention; **Fallback** = native preferred but body metadata allowed; **Unspecified** = no usable contract in the installed template. + +| Operation | GitHub template | GitLab template | Local Markdown template | Other / free-form | +|---|---|---|---|---| +| Create/publish | Native: `gh issue create` | Native: `glab issue create` | Prose: create under `.scratch//` | User-authored prose | +| Resolve reference | Repo inferred from remote; `#n` probed as PR then issue | Repo inferred; issue/MR number spaces separate, but caller must know surface | Path or “issue number”; resolution algorithm unspecified | Unspecified unless user writes it | +| Read item | Native: `gh issue view --comments`; labels additionally required | Native: `glab issue view --comments`, optional JSON | Prose: read referenced file | User-authored prose | +| List/search | Native list with state/label filters | Native list with label filters | Unspecified generally; directory scan only for wayfinder frontier | User-authored prose | +| Add/remove role label | Native `gh issue edit` | Native `glab issue update` | Prose: edit `Status:` line | User-authored prose | +| Comment | Native `gh issue comment` | Native `glab issue note` | Prose: append under `## Comments` | User-authored prose | +| Close | Native close with comment | Native note then close | No generic close operation; wayfinder uses `resolved` | User-authored prose | +| PR/MR request surface | Optional; external-author filter; shared issue/PR number space | Optional; external-author filter; separate issue/MR spaces | Not supported | User-authored prose | +| Parent/child | Native sub-issue, task-list/body fallback | `Part of #map`; optional epic mentioned | Map file plus child files | Unspecified | +| Blocking | Native issue dependency; `Blocked by:` fallback | Native blocking link on paid tiers; `Blocked by:` fallback | `Blocked by: NN, NN` line | Unspecified | +| Frontier | Query children, drop open blockers and assignees | Query children, drop open blockers and assignees | Scan ordered files; drop blocked/claimed | Unspecified | +| Claim | Assign `@me` | Assign `@me` | Set `Status: claimed` | Unspecified | +| Resolve | Comment, close, update map pointer | Note, close, update map pointer | Append `## Answer`, set resolved, update map pointer | Unspecified | +| Capability discovery | Implicit fallback prose only | Tier-dependent fallback prose only | Not defined | Not defined | +| Concurrency / idempotency | Delegated to provider; no idempotency contract | Delegated to provider; no idempotency contract | Not defined | Not defined unless user supplies it | +| Error/auth/offline behavior | Unspecified | Unspecified | Offline-capable by inference, but conflict behavior unspecified | Unspecified | + +Sources: `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md`, `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md`, and `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md`, especially “Conventions,” request-surface, publication/fetch, and “Wayfinding operations” headings. **Confidence: 95%** for template contents; **60%** that all vendor commands work unchanged today because current vendor docs/CLI behavior were intentionally outside this installed-file analysis. + +## 3. Setup → Spec/Tickets → Triage → Implement Sequence + +### 3.1 What is actually enforced + +The installed skills support the following explicit sequence, but do not orchestrate it as one transactional pipeline: + +```text +setup + ├─ writes tracker + role + domain instructions + ├─ conversation/codebase ── to-spec ──> published spec + ready-for-agent + │ └─ to-tickets ──> approved vertical-slice tickets + │ + blocking edges + │ + ready-for-agent + └─ incoming issue/PR ── triage ──> category/state + verification + ├─ needs-info / wontfix / ready-for-human + └─ ready-for-agent + authoritative agent brief + +ready work / chosen frontier ticket ── implement ──> TDD + checks + code review + commit +``` + +#### Stage A — setup + +**Direct evidence (98% confidence):** Setup establishes where items live, how canonical state roles map to tracker labels/status, and which domain docs downstream skills read. It does not test CLI installation, authentication, permissions, label existence, or provider operations. Source: `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/SKILL.md`, “Process.” + +#### Stage B — specification + +**Direct evidence (96% confidence):** `to-spec` synthesizes existing conversation and codebase context without interviewing the user. It explores the codebase, agrees test seams with the user, writes a problem/solution/user-story/implementation/testing/out-of-scope spec, publishes it, and immediately applies `ready-for-agent` “with no need for additional triage.” Source: `/Users/mrapacz/.agents/skills/to-spec/SKILL.md`, “Process” and ``. + +#### Stage C — tickets + +**Direct evidence (98% confidence):** `to-tickets` accepts current context or fetches a referenced path/issue/URL with full body and comments. It drafts single-context-window tracer-bullet vertical slices, records blocking edges, quizzes the user until approved, then publishes blockers first so later edges can reference real IDs. Real trackers use native dependency/sub-issue relations when possible; tickets receive `ready-for-agent`. The parent issue is not modified or closed. Source: `/Users/mrapacz/.agents/skills/to-tickets/SKILL.md`, steps 1–5, ``, and ``. + +**Direct evidence (98% confidence):** The explicit implementation handoff is: “Work the frontier one ticket at a time with `/implement`, clearing context between tickets.” Source: `/Users/mrapacz/.agents/skills/to-tickets/SKILL.md`, final instruction. + +#### Stage D — triage + +**Direct evidence (97% confidence):** Triage is a separate intake state machine, not a mandatory post-publication phase. It gathers the full item, checks redundancy and prior rejection, recommends category/state, verifies the claim, optionally grills and updates the domain model, then applies an outcome. `ready-for-agent` posts an agent brief comment described as the authoritative implementation contract. Sources: `/Users/mrapacz/.agents/skills/triage/SKILL.md`, “Roles,” “Show what needs attention,” and “Triage a specific issue or PR”; `/Users/mrapacz/.agents/skills/triage/AGENT-BRIEF.md`, opening paragraphs and “Template.” + +#### Stage E — implementation + +**Direct evidence (95% confidence):** `implement` consumes whatever spec or ticket the user supplies, recommends TDD at pre-agreed seams, runs typechecks and focused/full tests, invokes code review, and commits to the current branch. Source: `/Users/mrapacz/.agents/skills/implement/SKILL.md`. + +**Direct evidence (95% confidence):** Supporting quality contracts require behavior tests at agreed public seams and a red→green vertical-slice loop, then a two-axis review against repository standards and the originating spec. Sources: `/Users/mrapacz/.agents/skills/tdd/SKILL.md`, “What a good test is,” “Seams,” and “Rules of the loop”; `/Users/mrapacz/.agents/skills/code-review/SKILL.md`, “Process” and “Why two axes.” + +### 3.2 Critical discontinuities + +**Inference (97% confidence):** `to-spec`/`to-tickets` and `triage` define competing routes to `ready-for-agent`: + +- `to-spec` applies readiness without additional triage. +- `to-tickets` says its tickets are agent-grabbable by construction. +- `triage` says a `ready-for-agent` item receives an authoritative agent brief. + +Nothing requires generated specs/tickets to contain that brief, and nothing says whether a later brief supersedes the spec, ticket body, or comments. Sources: the three skills cited above. + +**Inference (98% confidence):** `implement` is not tracker-aware. It does not resolve a reference, claim the item, check blockers, update status, post progress, close the item, or record a commit/PR link. Thus “frontier one ticket at a time” is a human/agent convention, not an enforced end-to-end workflow. Sources: `/Users/mrapacz/.agents/skills/to-tickets/SKILL.md`, final instruction; `/Users/mrapacz/.agents/skills/implement/SKILL.md` in full. + +**Recommendation (92% confidence):** Maister should make handoff a named boundary operation: `start workflow from IssueRef`. It should validate readiness only if policy requires it, fetch and snapshot the source, optionally claim after explicit authorization, initialize workflow state, and record the source reference. Completion should be a separate, auditable provider operation rather than an implicit side effect of implementation. + +## 4. Reusable Patterns + +### 4.1 Patterns worth carrying forward + +1. **Repository-local, reviewable configuration — direct evidence; recommendation (93% confidence).** The root pointer plus `docs/agents/*.md` keeps team decisions in version control and in agent discovery paths. Reuse the ownership model, adding schema validation and config versioning. Source: setup skill, “3. Confirm and edit” and “4. Write.” + +2. **Canonical roles mapped to provider vocabulary — direct evidence; recommendation (94% confidence).** A stable semantic role such as `ready-for-agent` can map to an existing repository label. Extend the map to category roles and provider workflow states, and validate one-to-one/allowlisted values. Source: `triage-labels.md`; `triage`, “Roles.” + +3. **Provider-neutral verbs with provider-specific realization — inference; recommendation (89% confidence).** “Publish,” “fetch,” “claim,” and “resolve” let workflow prose remain stable. Maister should retain the vocabulary but back it with typed requests/results and declared capabilities. Source: all three tracker templates. + +4. **Native feature first, explicit fallback — direct evidence; recommendation (91% confidence).** GitHub/GitLab dependency guidance prefers native UI-visible edges and falls back to body metadata. This is a good capability-negotiation UX if the chosen representation and fallback reason are recorded. Source: GitHub/GitLab templates, “Wayfinding operations” → “Blocking.” + +5. **Stable human display names wrapping native references — direct evidence; recommendation (88% confidence).** Wayfinder insists that humans see ticket names while IDs/URLs ride inside links. Keep a machine-stable `IssueRef` and a separate display title. Source: `/Users/mrapacz/.agents/skills/wayfinder/SKILL.md`, “Refer by name.” + +6. **Dependency graph and frontier — direct evidence; recommendation (93% confidence).** “Open, unblocked, unclaimed” is a compact provider-independent definition of takeable work. It supports parallel agents when claim is the first write. Sources: wayfinder “Tickets” and tracker “Wayfinding operations.” + +7. **Create first, wire second — direct evidence; recommendation (94% confidence).** Publishing blockers first and wiring edges after native IDs exist avoids fake references. Source: `to-tickets`, step 5; `wayfinder`, “Chart the map” step 4. + +8. **Parent as index, child as detail — direct evidence; recommendation (90% confidence).** Wayfinder prevents duplicated decisions by keeping one detailed answer in its ticket and only a gist/link in the map. This is directly relevant to avoiding tracker/workflow duplication. Source: wayfinder, “The Map.” + +9. **Durable behavioral handoff — direct evidence; recommendation (95% confidence).** Agent briefs specify current/desired behavior, interfaces, acceptance criteria, and scope without line numbers or implementation procedures. Maister specs and snapshots should preserve that structure. Source: `triage/AGENT-BRIEF.md`, “Principles” and “Template.” + +10. **Explicit approval before ticket publication — direct evidence; recommendation (91% confidence).** `to-tickets` shows title, blockers, and delivered behavior, then iterates on granularity and edges with the user. This is a strong external-write gate. Source: `to-tickets`, step 4. + +11. **Fresh-context, one-ticket execution — direct evidence; recommendation (86% confidence).** Tickets are sized for one context and the implementation handoff asks users to clear context between frontier items. Maister can translate this to one workflow task per external issue while using its own resume state inside that task. Sources: `to-tickets`, vertical-slice rules and final instruction; wayfinder, “Tickets.” + +12. **AI disclosure for external triage writes — direct evidence; recommendation (84% confidence).** Triage requires every generated issue/comment to begin with a disclosure. Maister should make disclosure provider/policy configurable but preserve an auditable authorship marker. Source: `triage`, opening disclaimer. + +## 5. Weaknesses and Underspecified Parts + +| Gap | Evidence / impact | Strengthening recommendation | Confidence | +|---|---|---|---:| +| Prose is the provider API | Setup writes free-form operational instructions; downstream skills infer commands and fields. Typos or omissions cannot be validated. | Define normalized operations, typed results/errors, config schema/version, and capability discovery; retain prose only as guidance. | 97% | +| “Other” has no minimum contract | The user supplies one paragraph; setup does not require create/read/list/comment/label/close/reference semantics. | Require a provider checklist and reject configuration missing operations needed by enabled workflows. | 98% | +| No setup verification | Setup does not test CLI presence/version, auth, repository resolution, permissions, or labels. | Add read-only preflight plus explicit opt-in for label creation/external writes. | 96% | +| No canonical reference | GitHub relies on repo context and probes `#42`; GitLab requires surface knowledge; local accepts a path or number without an algorithm. | Use a provider-qualified, project-qualified, kind-qualified `IssueRef`, with short forms only when resolution is unambiguous. | 96% | +| Local layout contradiction | Local template says PRD at `.scratch//PRD.md` and issues under `.scratch//issues/NN-*.md`; `to-tickets` instead mandates one root `tickets.md`. | Select one canonical local model and contract-test all publishing consumers against it. | 99% | +| Local publish is ambiguous | “Create a new file under `.scratch//`” does not choose PRD vs issue name, allocate a number, or define required metadata. | Provider owns naming/ID allocation and returns the resulting stable reference. | 98% | +| Local status vocabularies collide | Generic triage uses a `Status:` line with role strings; wayfinder uses the same field for `claimed`/`resolved`. | Separate lifecycle fields, e.g. `triage_role`, `work_state`, and `claim`, with schema validation. | 98% | +| Local writes are race-prone | “First by number,” edit-in-place claim, and append operations have no lock, compare-and-swap, atomic rename, or collision retry. | Allocate collision-resistant IDs or locked monotonic IDs; write temp+atomic rename; claim conditionally on expected revision; report conflicts. | 99% | +| No idempotency or retry semantics | Create/comment/close sequences can partially succeed, especially resolve's three writes. | Give mutations idempotency keys and return partial-result/reconciliation data. | 95% | +| Dependency source-of-truth ambiguity | Native edge and body fallback are both described, but migration/divergence precedence is not. | Persist the selected representation and capability decision; never silently merge conflicting edge sets. | 94% | +| Read/list result shape is unstable | Consumers need different combinations of body, comments, labels, author, dates, diff, blockers, and assignee; no normalized result exists. | Define base `Issue` plus optional capability-specific expansions and pagination metadata. | 95% | +| Readiness meaning diverges | Specs/tickets become ready automatically; triage says ready has an authoritative brief. | Define readiness invariants and validate them before handoff. | 98% | +| Parent/spec/brief authority diverges | `to-tickets` does not modify parent; agent brief says it is authoritative; no supersession marker connects versions. | Store explicit `derived_from` and `supersedes` references; identify one current handoff artifact. | 94% | +| Implementation does not close the loop | `implement` commits but does not claim/update/resolve the source ticket. | Add explicit start/claim and completion/report commands around, not inside, workflow execution. | 99% | +| Automatic commit is broad | `implement` instructs committing the current branch without stating dirty-tree, approval, or branch safeguards. | Let Maister's normal development safety policy govern commits; never infer tracker handoff as commit authorization. | 91% | +| Local “resolve” is not fully local | It requires a “gist + link” pointer without defining gist storage, availability, or offline fallback. | Link repository-local workflow artifacts or a provider-neutral artifact reference; external publication must be optional. | 96% | +| Comments lack durable metadata locally | Append-only comments have no required author, timestamp, ID, escaping, or concurrent merge rules. | Use structured frontmatter/records and atomic append or one-comment-per-file storage. | 95% | +| Security is absent | Templates do not discuss credential storage, command injection, untrusted issue text, path traversal, or secret redaction. | Keep credentials outside repo config; validate refs/paths; use argument arrays/structured APIs; treat fetched text as untrusted content. | 97% | +| Vendor behavior is assumed | Templates prescribe CLI commands and plan-dependent features but do not pin versions or run capability checks. | Treat installed prose as intent; verify provider behavior at runtime and degrade explicitly. | 91% | + +## 6. Concrete Mapping to Maister Semantics + +### 6.1 State ownership + +**Direct project constraint (100% confidence):** Issue tracking is persistent intake; `.maister/tasks/**/orchestrator-state.yml` becomes authoritative only after a workflow begins and must remain execution/resume state. Sources: `/Users/mrapacz/Workspace/maister/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-brief.md`, “Key Decisions” and “Scope”; `planning/research-plan.md`, “Research Objective.” + +**Recommendation (94% confidence):** At handoff, materialize four distinct things: + +| Concern | Owner | Stored in workflow? | Rationale | +|---|---|---|---| +| Current title/body/comments/labels | Tracker | Immutable normalized snapshot, captured time, and content hash | Reproducible input even if tracker changes later | +| Stable identity and URL | Tracker/provider | Canonical `IssueRef` plus provider/project/native ID | Provenance and later refresh/reporting | +| Readiness, assignee, provider status | Tracker | Snapshot only; optionally refresh and show drift | Avoid mirroring mutable backlog state | +| Phases, gates, attempts, decisions, artifacts, verification | Maister workflow | Authoritative in `orchestrator-state.yml` and task artifacts | Resume and audit are workflow concerns | +| Completion comment/close | Tracker | Operation receipt in audit state, not replicated status | External mutation is explicit and retryable | + +This follows the useful wayfinder principle that an index points to detail rather than duplicating it, while making a captured source reproducible. Source prior art: `/Users/mrapacz/.agents/skills/wayfinder/SKILL.md`, “The Map.” + +### 6.2 Installed semantics → Maister semantics + +| Installed concept | Maister mapping | Boundary rule | +|---|---|---| +| Repository-local tracker prose | Validated provider config in `.maister/config.yml` plus provider guidance | Config selects behavior; prose does not define executable semantics alone. | +| Native issue/path/URL | Canonical `IssueRef` accepted by capture/show/start commands | Resolve before creating workflow state; fail on ambiguity. | +| Triage `ready-for-agent` | Optional intake precondition/policy | Never encode it as a workflow phase or completion state. | +| Agent brief/spec/ticket body | Source snapshot and initial task description | Record which artifact is authoritative at capture time. | +| `to-spec` | Research/design output or a planning input published back to tracker | Publication is optional external output, not workflow state. | +| `to-tickets` blocking graph | External backlog/dependency graph | Do not replace development phase/task-group state; each selected ticket can start its own workflow. | +| Frontier query | Candidate-selection UX before workflow start | Claim only after selection and explicit write authorization. | +| Claim-before-work | Conditional provider mutation at workflow initialization | Store claim receipt; if claim conflicts, do not start or ask to proceed unclaimed. | +| `/implement` | `$maister:development` | Maister retains specification, approval, implementation, verification, resume, and audit semantics. | +| Local comments/resolution answer | Workflow artifacts plus optional completion report/comment | Tracker receives a concise pointer; detailed artifacts remain in the task directory. | +| Closed/resolved tracker item | Intake lifecycle | Never infer that `orchestrator-state.yml` is complete solely from tracker status, or vice versa. | + +**Direct evidence (98% confidence):** Maister research creates a task directory containing `orchestrator-state.yml`, planning artifacts, per-category findings, synthesis, and outputs. It can resume by task path and phase. Source: `/Users/mrapacz/Workspace/maister/plugins/maister/skills/research/SKILL.md`, “Task Structure,” “Integration with Other Workflows,” and “Command Integration.” + +**Direct evidence (97% confidence):** Maister development can ingest a completed research directory, copy/read research context, set a research reference, and use research to inform rather than skip its own phases. Source: `/Users/mrapacz/Workspace/maister/plugins/maister/skills/development/SKILL.md`, “Initialization” → “Detect Research Context,” and “Research-Based Development.” + +**Direct evidence (95% confidence):** Quick plan takes a task description, applies repository standards, and requires plan approval before implementation. It does not define a persisted tracker or orchestration state. Source: `/Users/mrapacz/Workspace/maister/plugins/maister/skills/quick-plan/SKILL.md`, “Workflow.” + +### 6.3 Explicit journey mapping + +#### Journey 1 — setup → issue → research + +1. Configure provider repository-locally and validate read/create capabilities. +2. Capture or select an issue and resolve it to canonical `IssueRef`. +3. Fetch full normalized content, record the source revision/time, and create a workflow-local snapshot. +4. Invoke `$maister:research` with the snapshot's task question and source metadata. +5. From this point, `orchestrator-state.yml` is the resume authority; tracker changes appear as optional drift, not hidden input mutation. +6. Optionally publish the research report link as a comment after an explicit external-write gate. + +**Recommendation confidence: 92%.** It combines installed publish/fetch conventions with Maister's existing research task structure and state boundary. + +#### Journey 2 — issue/spec → quick plan + +1. Resolve and snapshot the issue or published spec. +2. Feed the snapshot's authoritative brief into `$maister:quick-plan` as the task description/context. +3. Include source reference and captured acceptance criteria in the plan; apply relevant `.maister/docs` standards. +4. Approval remains quick-plan's gate. The tracker remains the owner of backlog/readiness state. +5. If implementation follows, start development with the approved plan and the same source provenance rather than reinterpreting a mutable issue silently. + +**Recommendation confidence: 86%.** Quick plan's current skill has no durable workflow task directory, so exact snapshot persistence needs a product decision. + +#### Journey 3 — ready ticket/frontier → development → resume/audit + +1. Query the tracker frontier if supported; select a ticket. +2. Conditionally claim it as the first external write. A failed/conflicting claim stops or requires an explicit override. +3. Snapshot the authoritative ticket/brief and initialize `$maister:development` with `IssueRef`, source revision, and acceptance criteria. +4. Development performs its own analysis, specification, approval, implementation, and verification; tracker blocking/readiness does not masquerade as phase state. +5. Resume always targets the Maister task directory and `orchestrator-state.yml`, even if the source issue has changed or closed. +6. Final audit records the source, snapshot, claim receipt, workflow decisions, verification, and any explicit completion mutation. Closing/commenting is idempotent and separately authorized. + +**Recommendation confidence: 94%.** This preserves the installed claim/frontier UX and Maister's stronger execution/resume/audit model. + +### 6.4 Why this avoids duplicated state + +**Inference (95% confidence):** Duplication is avoided by distinguishing a historical snapshot from a mutable replica. The snapshot answers “what input did this workflow act on?”; `IssueRef` answers “where did it come from?”; tracker fetch answers “what is true upstream now?”; `orchestrator-state.yml` answers “where is this workflow now?” These are different facts and should not overwrite one another. + +**Recommendation (93% confidence):** If the upstream issue changes after initialization, show a structured drift summary and offer refresh/restart/continue choices. Never silently rewrite accepted requirements or workflow state. + +## 7. Answers to the Exact Category 2 Questions + +1. **Selection/persistence:** Interactive setup detects remotes and existing conventions, asks tracker/PR-surface/label/domain decisions one at a time, previews drafts, then persists a root pointer plus three repository-local prose documents. GitHub/GitLab/local use templates; other trackers use free-form prose. +2. **Implicit interface:** The phrases encode create, resolve-reference, read-with-discussion, list/filter, role-label mutation, comment, close, dependency, frontier, claim, and multi-write resolution operations. Capabilities and errors are implicit. +3. **Flow:** Conversation can become a ready spec, then approved blocker-first vertical-slice tickets; incoming items can independently pass triage into an authoritative brief; implementation consumes selected work with TDD/review/commit. No skill enforces the entire chain or closes the tracker loop. +4. **Reusable conventions:** Repository-local discovery/config, canonical roles mapped to labels, provider-neutral verbs, native-plus-fallback relationships, human titles with machine refs, parent/child provenance, blocker frontiers, first-write claims, durable behavioral briefs, and explicit publication approval. +5. **Avoid/strengthen:** Replace unvalidated prose as executable contract, ambiguous refs, conflicting local layouts/status fields, non-atomic local writes, undefined idempotency/errors/security, unclear authority/readiness, and missing implementation completion integration. +6. **Maister mapping:** Use tracker items for intake and provenance; snapshot once at research/plan/development initialization; keep external lifecycle in the tracker and workflow execution/resume/audit in `orchestrator-state.yml`; synchronize only through explicit, receipted boundary operations. diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/03-tracker-providers.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/03-tracker-providers.md new file mode 100644 index 00000000..d83f0ed6 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/03-tracker-providers.md @@ -0,0 +1,250 @@ +# External Tracker Provider Contracts + +## TL;DR +The portable core is eight operations: resolve, create, read, list/search, update, comment, label/transition, and capability discovery. Persist a fully scoped `maister-issue://...` reference, while accepting short aliases only as input. Use filesystem operations for local Markdown and a preflight-selected API/CLI transport for hosted trackers; MCP is an optional host adapter, not the contract. For v1 GitHub, require conventional issue CRUD/comments/labels/open-close and reject PRs; discover hierarchy, dependencies, projects, issue types, and fields as optional capabilities. + +## Key Decisions + +- **Recommendation — High confidence (90%):** Define a small normalized contract plus a capability map and provider-specific escape hatch. Do not place hierarchy, blockers, projects, custom fields, or assignee rules in the portable core. +- **Recommendation — High confidence (92%):** Persist canonical references as `maister-issue://////`; parse convenient aliases and vendor URLs into that form before workflow initialization. +- **Recommendation — High confidence (90%):** Select one execution transport during read-only preflight. Reads may fall back after a definite “unsupported/unavailable” result; writes must not fail over after dispatch unless the provider proves idempotency or reconciliation proves the first write did not commit. +- **Recommendation — High confidence (93%):** Make the GitHub REST API version `2026-03-10` the normative v1 behavior and allow `gh` to supply authentication and/or execute equivalent calls. MCP remains optional because its availability and tool schemas vary by host and server version. + +## Open Questions / Risks + +- The exact short-alias grammar (`gh:owner/repo#123` versus another spelling) is a product choice; only the persisted canonical form needs to be stable. +- Hosted issue-create and comment endpoints reviewed here do not document a general client idempotency key. A timeout after dispatch is therefore an **ambiguous commit**, not a retryable failure. +- GitHub's newest issue fields, issue types, dependencies, and sub-issues are present in API version `2026-03-10`, but repository/organization enablement and permissions still vary; GitHub Enterprise Server parity was not verified. +- GitLab capabilities depend on deployment version, offering, and tier; Jira behavior depends on project type, issue type, fields, workflow, and permissions; Linear workflows are team-specific. Capability results need constraints, not booleans alone. + +## Scope, Method, and Source Currency + +**Direct evidence.** This comparison uses only current official vendor documentation and the installed local Markdown tracker convention. External sources were accessed **2026-07-13**. No real tracker writes were performed. The local environment had GitHub CLI `2.96.0` (released 2026-07-02); `glab`, Jira, and Linear CLIs were not installed, so their runtime behavior was not tested. + +| Provider | Reviewed contract / caveat | +|---|---| +| Local Markdown | Installed convention at `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md`, headings **Conventions**, **When a skill says “publish…”**, and **Wayfinding operations**. This is project-local prior art, not a standardized external API. | +| GitHub | REST API version `2026-03-10` is the current documented version; GitHub documents versioned breaking changes and advance notice. [API versions](https://docs.github.com/en/rest/about-the-rest-api/api-versions?apiVersion=2026-03-10). CLI observations use installed `gh 2.96.0`; CLI presence is not a product prerequisite. | +| GitLab | Current docs include history through GitLab 19.x and identify tier/offering per feature. Project-issue keyset pagination requires GitLab 18.3+. GitLab's own MCP server is **Beta**, Premium/Ultimate, introduced in 18.3 and changed substantially through 18.11. [REST API](https://docs.gitlab.com/api/rest/), [MCP server](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/). | +| Jira Cloud | REST API v3 is the latest Cloud API. This does not cover Jira Data Center. Atlassian's new points/quota rate-limit enforcement began 2026-03-02; the rate-limit page was updated 2026-07-10. [REST v3 introduction](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/), [rate limiting](https://developer.atlassian.com/cloud/jira/platform/rate-limiting/). | +| Linear | Public GraphQL API with introspection; limits are explicitly described as evolving. OAuth applications moved to the refresh-token system on 2026-04-01. The official remote MCP server advertises expanding functionality (“more functionality on the way”). [GraphQL getting started](https://linear.app/developers/graphql), [OAuth](https://linear.app/developers/oauth-2-0-authentication), [MCP](https://linear.app/docs/mcp). | + +## 1. Smallest Common Operation Set + +### Recommended portable interface + +**Recommendation — High confidence (92%).** Keep the mandatory semantic surface small, but return structured constraints and provenance from every operation: + +```text +resolve(input, context) -> IssueRef +create(containerRef, draft, operationId?) -> Issue +read(issueRef) -> Issue +list(containerRef, query, page?) -> IssuePage +update(issueRef, patch, precondition?) -> Issue +comment(issueRef, body, operationId?) -> Comment +setLabels(issueRef, add[], remove[], precondition?) -> Issue +transition(issueRef, targetCategoryOrNativeTransition, precondition?) -> Issue +capabilities(containerRef?, issueRef?) -> CapabilitySet +``` + +`Issue` should normalize only: canonical reference, provider URL, title, body (raw source form), coarse state category (`open`, `active`, `done`, `cancelled`, `unknown`), labels/tags, assignee display references, created/updated timestamps, and raw provider metadata. `update` should be a field patch, not a whole-object replacement. `transition` must accept either a coarse requested category or an explicit native transition; the result reports the actual native state. + +`CapabilitySet` should describe each operation as `native | emulated | unsupported | unknown`, with `transport`, `read/write`, required permission, tier/version/preview constraints, supported fields, and a human-readable reason. Capability discovery is therefore an operation of the Maister provider, not necessarily a vendor endpoint. It combines static adapter knowledge, configuration, transport availability, and cheap read-only probes. + +### Common-operation matrix + +Legend: **N** native; **E** safely emulatable by the provider; **C** native but constrained/configuration-dependent; **D** defined by Maister's local file format; **—** unsupported or not established by reviewed evidence. + +| Operation | Local Markdown | GitHub Issues | GitLab Issues | Jira Cloud | Linear | +|---|---|---|---|---|---| +| Resolve reference | **D** path/stable file ID | **N** host + owner/repo + number or URL | **N** host + project path + issue IID or URL | **N** site/cloud + project + issue key or ID | **N** workspace/team + identifier or UUID | +| Create | **D** exclusive file creation | **N** REST/`gh` | **N** REST/`glab` | **C** fields and issue type come from create metadata | **C** GraphQL; team is required and default state is team-dependent | +| Read | **D** file read | **N** | **N** | **N** with field/permission visibility | **N** GraphQL | +| List/filter | **D** directory scan | **N** repository endpoint | **N** project/group/global endpoints | **N** JQL search | **N** filtered GraphQL connections | +| Text search | **E** bounded content scan | **N** issue search | **N** `search` filters; advanced search separately limited | **N** JQL text predicates | **N** GraphQL filtering/search surface; exact parity is not assumed | +| Update title/body | **D** guarded file replace | **N** | **N** | **C** editable fields discovered per issue; ADF for rich text | **N** `issueUpdate` | +| Comment | **D** append under `## Comments` | **N** issue-comments API | **N** Notes API | **N** comments API, ADF body in v3 | **N** GraphQL; OAuth has `comments:create` scope | +| Labels/tags | **D** proposed frontmatter/list; absent from installed local convention | **N** labels API | **N** issue labels | **C** `labels` field may be absent/hidden; custom fields differ | **N** issue labels, including team/workspace semantics | +| State change | **D** explicit status field | **N** open/closed plus reason | **N** `state_event=close|reopen`; newer custom status varies | **C** must enumerate and execute allowed workflow transitions | **C** set a team-specific workflow-state ID | +| Capability discovery | **D** static format/version + filesystem probe | **E** adapter knowledge + API/repository/permission probes | **E** adapter + version/tier/permission probes | **E** metadata, fields, transitions, permissions | **E** GraphQL introspection + team/workflow queries | + +**Direct evidence — High confidence (95%).** GitHub's issue API exposes create/get/update/list, and separate official endpoints cover comments and labels. Pull requests can appear in issue responses and are identified by a `pull_request` key. [Issues](https://docs.github.com/en/rest/issues/issues?apiVersion=2026-03-10), [comments](https://docs.github.com/en/rest/issues/comments?apiVersion=2026-03-10), [labels](https://docs.github.com/en/rest/issues/labels?apiVersion=2026-03-10). + +**Direct evidence — High confidence (95%).** GitLab's Issues API supports create/update/list and uses project-scoped `iid`; close/reopen is an update with `state_event`. Comments are Notes. [Issues API](https://docs.gitlab.com/api/issues/), [Notes API](https://docs.gitlab.com/api/notes/). GitLab's official CLI exposes create/list/view/update/close/reopen/note with `--repo` targeting. [`glab issue`](https://docs.gitlab.com/cli/issue/). + +**Direct evidence — High confidence (95%).** Jira creation and editing are metadata-driven, and editing does not transition state; callers must query and execute available transitions. Comments are a separate resource and rich-text bodies use Atlassian Document Format in REST v3. [Issues and transitions](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/), [comments](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/), [REST v3 introduction](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/). + +**Direct evidence — High confidence (93%).** Linear documents `issueCreate` and `issueUpdate`; the update accepts either UUID or shorthand such as `BLA-123`. Creation requires a team and defaults to Triage or the first Backlog state depending on team configuration. All list queries use Relay-style cursor pagination. [GraphQL getting started](https://linear.app/developers/graphql), [pagination](https://linear.app/developers/pagination). + +## 2. Capabilities That Must Not Be Flattened + +| Capability | Why it is not safely normalizable | Provider evidence / v1 treatment | +|---|---|---| +| Issue versus PR/MR/work-item kind | GitHub Issues endpoints can return PRs; GitLab issue and MR IIDs are independently scoped; local Markdown has no intrinsic kind. | GitHub explicitly says every PR is an issue but not every issue is a PR. [GitHub Issues](https://docs.github.com/en/rest/issues/issues?apiVersion=2026-03-10). Persist `kind`; v1 GitHub rejects `pull_request` when an `issue` was requested. | +| Parent/sub-issue hierarchy | Depth, cross-project rules, and issue-type constraints differ. | GitHub allows up to 100 sub-issues and eight levels; Jira hierarchy is issue-type/project dependent, with extra hierarchy levels limited to Premium/Enterprise; Linear sub-issues can belong to another team. [GitHub sub-issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues), [Jira hierarchy](https://support.atlassian.com/jira-cloud-administration/docs/configure-the-issue-type-hierarchy/), [Linear teams](https://linear.app/docs/teams). Optional capability only. | +| Blocking/related/duplicate links | Direction, lifecycle effects, tiers, and duplicate semantics differ. | GitHub has issue-dependency endpoints in API `2026-03-10`; GitLab relation types include `blocks` and `is_blocked_by`, but blocking UI behavior is Premium/Ultimate; Jira link types are administrator-defined and issue linking can be disabled; Linear supports blocking/related/duplicate and moves resolved blockers under Related. [GitHub dependencies](https://docs.github.com/en/rest/issues/issue-dependencies?apiVersion=2026-03-10), [GitLab links API](https://docs.gitlab.com/api/issue_links/), [GitLab linked issues](https://docs.gitlab.com/user/project/issues/related_issues/), [Jira issue links](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-links/), [Linear relations](https://linear.app/docs/issue-relations). Expose typed native relations, not a portable `blocked` boolean. | +| State/workflow | Open/closed is not equivalent to a Jira transition or Linear team state. Validators, permissions, and transition screens can reject a seemingly valid target. | Jira returns only transitions the user can perform; Linear workflows are customizable per team. [Jira transitions](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/), [Linear teams/workflows](https://linear.app/docs/teams). Normalize only coarse state category for display; mutate through native transition IDs. | +| Projects/boards/cycles/milestones | “Project” means repository board metadata on GitHub, namespace/container on GitLab/Jira, and a planning object separate from team on Linear. | GitHub Projects can contain issues, PRs, and draft items with custom fields; a Linear issue can belong to only one project. [GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects), [Linear projects](https://linear.app/docs/projects). Provider extension only. | +| Issue types and custom fields | Names, IDs, value types, visibility, screens, and silent-drop behavior vary. | GitHub issue fields are organization-defined and unavailable in some contexts; issue-field/type values can be silently dropped without sufficient access. Jira create/edit fields must be discovered and multiline text uses ADF. [GitHub issue fields](https://docs.github.com/en/issues/planning-and-tracking-with-projects/understanding-fields/about-issue-fields), [GitHub Issues](https://docs.github.com/en/rest/issues/issues?apiVersion=2026-03-10), [Jira issues](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/). Never claim success without read-after-write verification for constrained metadata. | +| Assignees | Cardinality, eligibility, identity, and tier differ. | GitHub restricts who can be assigned; GitLab multiple assignees are Premium/Ultimate; Jira uses account IDs and permissions; Linear routing can depend on team triage rules and tier. [GitHub assignees](https://docs.github.com/en/rest/issues/assignees?apiVersion=2026-03-10), [GitLab multiple assignees](https://docs.gitlab.com/user/project/issues/multiple_assignees_for_issues/), [Linear assignment](https://linear.app/docs/assigning-issues). Return opaque provider user refs. | +| Rich body and comments | Markdown is native for GitHub/GitLab/Linear, while Jira v3 uses ADF for multiline content. Local files can contain arbitrary frontmatter/headings. | Preserve raw provider representation and an optional rendered/plain projection; do not round-trip all providers through Markdown. [Jira REST v3 introduction](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/). | +| Move/transfer semantics | A “move” can preserve identity, create a replacement, or be unavailable. | GitLab move closes and copies the issue, leaving notes on both; GitHub has transfer; Jira keys may change when moved. [GitLab manage issues](https://docs.gitlab.com/user/project/issues/managing_issues/). Return a replacement canonical ref when identity changes. | + +**Inference — High confidence (90%).** A single `supportsBlocking: true` or `status: in_progress` loses behavior needed for safe automation. The capability payload should expose native relation/state/type identifiers plus constraints, while the normalized issue view remains intentionally lossy. + +## 3. CLI, HTTP API, MCP, and Filesystem Trade-offs + +| Transport | Strengths | Costs / failure modes | Recommended role | +|---|---|---|---| +| Filesystem | Offline, auditable diffs, no credentials or service dependency, natural fit for local Markdown. | Concurrency, path traversal, Git conflicts, no server-side search/permissions/events. | Normative transport for `local`; use stable IDs, exclusive create, atomic replacement, and compare-before-write. | +| Vendor CLI | Excellent interactive auth and host selection; concise commands; often already installed. `gh issue` and `glab issue` cover the core. | Optional dependency; installed versions and output/features drift; prompts are unsafe for automation; exit codes can hide provider detail. | Convenience adapter. Require minimum version, non-interactive flags, structured JSON, explicit repository/host, and preflight auth. | +| HTTP/GraphQL API | Vendor's normative contract, structured errors/headers, testable with fixtures, works without shell quoting, version can be pinned. | Maister must handle tokens, pagination, retries, schemas, and cloud/self-hosted base URLs. | Normative semantics for hosted providers. Prefer API implementation or `gh api`-equivalent behavior for v1 GitHub. | +| MCP/connector | Reuses signed-in host sessions; capability/tool discovery is built in; official GitHub, GitLab, Jira, and Linear servers exist. | Host-dependent, remote availability, dynamic tool names/schema, user/tool approvals, less control over pagination/raw errors, and server tier/preview differences. | Optional host adapter. Never make core workflow correctness depend on MCP presence. Preserve raw tool result and provider URL. | + +**Direct evidence — High confidence (92%).** GitHub's official MCP server exposes issue tools and can enforce read-only mode; the currently indexed release is 0.31.0. [Official GitHub MCP server](https://github.com/github/github-mcp-server), [releases](https://github.com/github/github-mcp-server/releases). GitLab's MCP server is Beta and Premium/Ultimate. [GitLab MCP](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/). Atlassian's Rovo MCP server uses OAuth and organization-controlled read/write/search permissions, with plan-dependent site limits. [Rovo MCP](https://www.atlassian.com/platform/rovo-mcp), [permission controls](https://support.atlassian.com/security-and-access-policies/docs/Configure-Atlassian-Rovo-MCP-server-permission/). Linear's remote MCP server uses OAuth 2.1 and exposes finding/creating/updating issues, projects, and comments. [Linear MCP](https://linear.app/docs/mcp). + +**Recommendation — High confidence (90%).** Use a layered preference model, but resolve it before execution: + +1. `local` always selects filesystem. +2. Hosted provider preflight discovers configured transport(s), credentials, provider reachability, and capabilities without writing. +3. Select a single transport for the operation. Prefer the API-compatible adapter for reproducibility; allow CLI or MCP when project/host configuration explicitly prefers it. +4. A read may retry through another transport only after a definite non-dispatch failure. +5. A write may switch transport only before dispatch, or after reconciliation proves no mutation occurred. A timeout/connection loss after dispatch returns `ambiguous_commit`. + +This avoids both shell coupling and duplicate external writes while still exploiting host-native connectors. + +## 4. Canonical Reference Options + +### Options considered + +| Form | Example | Assessment | +|---|---|---| +| Vendor shorthand | `owner/repo#123`, `group/project#123`, `PROJ-123`, `ENG-123` | Fast but ambiguous across provider, host/workspace, kind, and current repository. Input alias only. | +| Vendor URL | `https://github.com/o/r/issues/123` | Globally meaningful and easy to paste, but provider-specific, may include mutable slugs, and does not give one parser contract. Accept and normalize; retain as `webUrl`. | +| URN | `urn:maister:issue:github:github.com:o%2Fr:issue:123` | Unambiguous and compact-ish, but percent encoding is hard to read/type. Viable persisted alternative, not preferred. | +| Maister URI | `maister-issue://github/github.com/o/r/issue/123` | One parser, provider explicit, hierarchy readable, URI path segments can be percent-encoded. Recommended persisted canonical form. | + +### Recommended grammar + +```text +maister-issue:////...// +``` + +Examples: + +```text +maister-issue://github/github.com/openai/codex/issue/123 +maister-issue://gitlab/gitlab.com/group/subgroup/project/issue/123 +maister-issue://jira/acme.atlassian.net/PROJ/issue/PROJ-123 +maister-issue://linear/acme-workspace/ENG/issue/ENG-123 +maister-issue://local/workspace/issues/issue/01J2M7Y7W4K8K0M6M4W8YV2R3Z +``` + +Rules: + +- Lowercase and allowlist `provider` and `kind`; preserve provider-native case in path segments where meaningful. +- Percent-encode each path segment; reject `.`/`..`, encoded separators, control characters, and unconfigured authorities. +- For GitHub/GitLab include host and full repository/project path because native issue numbers/IIDs are container-scoped. GitLab documents `id` as global but `iid` as project-scoped and normally used to fetch resources. [GitLab REST `id` vs `iid`](https://docs.gitlab.com/api/rest/#id-vs-iid). +- For Jira include site plus project and preserve the full issue key; Jira APIs accept issue ID or key, but the human key is not site-global without the site authority. [Jira issues](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/). +- For Linear include workspace and team key plus identifier; also retain immutable provider UUID in raw metadata when available. Linear accepts UUID or shorthand identifier for updates. [Linear GraphQL](https://linear.app/developers/graphql). +- For local, generate an immutable ULID/UUID independent of filename slug. The path is metadata, not identity. +- Keep both `canonicalRef` and current `webUrl`; do not infer one from the other forever because resources can move. + +Suggested input aliases are `gh:OWNER/REPO#123`, `gl:GROUP/PROJECT#123`, `jira:SITE/PROJ-123`, `lin:WORKSPACE/ENG-123`, and `local:`. Bare `#123` is accepted only when exactly one configured provider/container supplies context; otherwise fail as `ambiguous_reference` with candidate canonical refs. + +**Recommendation — High confidence (92%).** Persist only the canonical URI. Alias resolution is context-sensitive UI behavior and must never change the already-persisted identity silently. + +## 5. Boundary Semantics: Auth, Pagination, Limits, Errors, Idempotency, Offline + +### Provider constraints + +| Provider | Authentication | Pagination | Rate limits | Offline | +|---|---|---|---|---| +| Local | OS/filesystem permissions; Git remote auth is outside the provider operation | Deterministic sorted scan with explicit cursor/snapshot token | No service quota; enforce local result/time bounds | Full read/write offline; later Git sync may conflict | +| GitHub | Fine-grained PAT, GitHub App, OAuth, or Actions token; v1 issue writes need repository **Issues: write**. [Authentication](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api), [issue permissions](https://docs.github.com/en/rest/issues/issues?apiVersion=2026-03-10) | REST list defaults to 30; follow `Link`, request up to endpoint-supported `per_page`. [Pagination](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api) | 60/hour unauthenticated, generally 5,000/hour authenticated, plus secondary/content-generation limits; honor `Retry-After` and `X-RateLimit-*`. [Rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2026-03-10) | No; cached snapshots may be displayed as stale but cannot authorize writes | +| GitLab | OAuth2, PAT, project/group token, selected CI job tokens; invalid/missing credentials return 401 while inaccessible private resources can appear as 404. [Authentication](https://docs.gitlab.com/api/rest/authentication/), [Issues API](https://docs.gitlab.com/api/issues/) | Offset default 20/max 100; follow `Link`. Project issues support keyset in 18.3+. Large results can omit totals. [Pagination](https://docs.gitlab.com/api/rest/#pagination) | GitLab.com currently documents 2,000 authenticated API requests/minute, issue creation 200/minute, notes 60/minute; self-managed limits are configurable and layered. Honor 429, `Retry-After`, and `RateLimit-*`. [GitLab.com limits](https://docs.gitlab.com/user/gitlab_com/#rate-limits-on-gitlabcom), [rate-limit headers](https://docs.gitlab.com/administration/settings/user_and_ip_rate_limits/#response-headers) | No; same stale-cache rule | +| Jira Cloud | OAuth 2.0 3LO recommended for integrations; API-token basic auth is for personal/ad-hoc scripts. Password basic auth is deprecated. [REST auth model](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#authentication-and-authorization), [basic auth](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/) | Operation-specific `startAt`, `maxResults`, `total`/`isLast`; limits can change without notice. [Pagination](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#pagination) | Points/quota, burst, and per-issue write limits coexist; handle 429 and `Retry-After` instead of hard-coding a single quota. [Rate limiting](https://developer.atlassian.com/cloud/jira/platform/rate-limiting/) | No; same stale-cache rule | +| Linear | OAuth2 recommended for apps; personal API key for personal scripts. OAuth supports narrow `issues:create` and `comments:create` plus broader `write`. [OAuth](https://linear.app/developers/oauth-2-0-authentication), [GraphQL auth](https://linear.app/developers/graphql) | Relay cursors (`first/after`, `last/before`), default 50; follow `pageInfo`. [Pagination](https://linear.app/developers/pagination) | Current table: API key 2,500 requests/user/hour, OAuth app 5,000/user-or-app-user/hour, plus complexity and endpoint limits. GraphQL rate errors can be HTTP 400 with `extensions.code=RATELIMITED`; limits are evolving. [Rate limiting](https://linear.app/developers/rate-limiting) | No; same stale-cache rule | + +### Normalized error contract + +**Recommendation — High confidence (91%).** Return a typed error while retaining provider evidence: + +```text +kind: invalid_ref | ambiguous_ref | unauthenticated | forbidden | not_found | + validation | conflict | unsupported | rate_limited | unavailable | + offline | precondition_failed | ambiguous_commit | provider_error +retryable: boolean +retryAt: timestamp? +operationDispatched: boolean | unknown +providerStatus/providerCode/providerRequestId/rawSummary +capabilityOrConstraint: string? +``` + +- Do not collapse `403` and `404` based on guesswork: GitHub and GitLab may obscure private resources. Include remediation without revealing resource existence. +- Treat provider validation and unsupported capability separately. GitHub create can return 410 when issues are disabled and 422 for validation/spam; GitLab uses 400 validation and 429 limits; Linear can return partial GraphQL data with an `errors` array even on HTTP 200. [GitHub create statuses](https://docs.github.com/en/rest/issues/issues?apiVersion=2026-03-10), [GitLab status codes](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes), [Linear error handling](https://linear.app/developers/graphql#handling-errors). +- Retry only bounded reads and writes proven not dispatched. Honor provider reset/retry headers and exponential backoff with jitter. +- Preserve request IDs/headers where supplied for audit and support, while redacting credentials and untrusted bodies. + +### Idempotency and concurrency + +**Direct evidence — Medium confidence (78%).** The reviewed GitHub, GitLab, Jira, and Linear issue-create documentation does not specify a general client idempotency key for issue creation. This is an evidence-of-absence finding limited to the current official create contracts, not proof that no endpoint anywhere supports idempotency. Jira issue-link creation treats a duplicate link as created, but a repeated request with a comment adds the comment again. [GitHub create](https://docs.github.com/en/rest/issues/issues?apiVersion=2026-03-10), [GitLab create](https://docs.gitlab.com/api/issues/#create-an-issue), [Jira create](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post), [Linear create](https://linear.app/developers/graphql), [Jira issue links](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-links/). + +**Recommendation — Medium confidence (85%).** The provider boundary must: + +- Generate an `operationId` for every mutation and record it in the local workflow audit before dispatch. +- Where acceptable, embed a non-secret marker in created content/provider metadata and reconcile by marker after an ambiguous response. Search indexing is not proof of absence, so reconciliation should inspect recent container items directly and may still return `ambiguous_commit`. +- Never automatically retry create/comment after an unknown post-dispatch outcome. State-setting updates may be retryable only when a read proves the desired state and no lost-update risk exists. +- Support `expectedUpdatedAt`/ETag/native version when available; otherwise read-before-write, apply the smallest patch, and read-after-write. This mitigates but does not eliminate races. +- For local create, use immutable ULID/UUID identity and exclusive creation. For update/comment, lock per issue, verify an expected digest, write a same-directory temporary file, atomically replace, then release the lock. Bound paths to the configured root. Git conflicts remain a separate synchronization conflict. + +### Offline behavior + +**Recommendation — High confidence (94%).** Capability discovery must report `offlineRead` and `offlineWrite` independently. Local Markdown supports both. Hosted providers support neither authoritative read nor write offline; a cached issue snapshot can be handed to a workflow only when clearly marked `stale`, with source ref and snapshot time. Queueing silent future writes is out of v1 because it complicates authorization, ordering, idempotency, and user intent. + +## 6. Initial GitHub Provider Recommendation + +### Required v1 capability profile + +**Recommendation — High confidence (93%).** Implement these as the guaranteed GitHub profile: + +- Resolve full GitHub issue URLs, canonical Maister URIs, `OWNER/REPO#N`, and bare `#N` only with unambiguous configured repository context. +- Create an issue with title and optional Markdown body; labels may be included only after capability/permission validation. +- Read one issue and reject a response containing `pull_request` when kind `issue` was requested. +- List repository issues with state/label/assignee filters and bounded pagination; search with an explicit query and `type:issue` guard. +- Patch title/body; add/remove labels without replacing unrelated labels; add a comment; close/reopen with the supported state reason where available. +- Return canonical ref, current web URL, raw node/database IDs, timestamps, normalized coarse state, and provider request/rate metadata. +- Provide read-only `capabilities()` and auth/repository preflight. Require fine-grained repository **Issues: read** for reads and **Issues: write** for mutations, or equivalent GitHub App/OAuth permissions. +- Pin `X-GitHub-Api-Version: 2026-03-10` and `Accept: application/vnd.github+json`. GitHub states breaking changes ship in a new API version. [API versions](https://docs.github.com/en/rest/about-the-rest-api/api-versions?apiVersion=2026-03-10). + +The official REST surface directly guarantees the core operations, and the official `gh issue` family exposes create/list/view/edit/comment/close/reopen. [GitHub REST Issues](https://docs.github.com/en/rest/issues), [`gh issue`](https://cli.github.com/manual/gh_issue). Installed `gh 2.96.0` additionally exposed structured JSON for issue list/view and flags for parent/sub-issue/dependency/type operations; this confirms local executability but does not make those features portable requirements. + +### Optional, capability-gated in v1 + +- Assignees and milestones: permissions/eligibility can cause rejection or silent dropping. +- Issue types and organization issue fields: require feature enablement, organization ownership, and write access; official docs explicitly describe contextual availability and silent drop behavior. Read-after-write verification is mandatory. +- Parent/sub-issues and blocking dependencies: API `2026-03-10` documents them and `gh 2.96.0` exposes corresponding flags, but treat them as native extensions until GitHub Enterprise Server/version and repository capability are known. +- Projects v2: separate permissions and object model; `gh issue create` requires the `project` scope for project assignment. Keep outside core capture/handoff. +- Pin/lock/transfer/delete and PR operations: not needed for intake-to-workflow handoff. + +### Graceful degradation and safety rules + +1. If `gh` is absent but API credentials and network are available, use the API adapter. If API transport is not implemented/configured, return `transport_unavailable`; do not ask a workflow model to improvise shell commands. +2. If `gh` is selected, require a supported version, explicit `--repo`, non-interactive flags, and JSON output. `gh auth status`/equivalent preflight must not leak tokens. +3. If labels/assignees/type/fields are requested, preflight them. After create/update, re-read and compare requested values because GitHub documents silent dropping for some metadata without sufficient access. [Create/update issue parameters](https://docs.github.com/en/rest/issues/issues?apiVersion=2026-03-10). +4. Follow `Link` headers, cap total pages/results, surface truncation, and preserve rate-limit headers. Do not fetch all pages by default. +5. Map 401/403/404/410/422/429/503 with raw status and actionable remediation. Respect primary and secondary rate-limit guidance; repeated requests while limited can ban an integration. [Rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2026-03-10). +6. Never auto-retry an ambiguous create/comment. Reconcile by operation marker/recent issues, or return `ambiguous_commit` for user review. +7. Treat issue bodies, comments, labels, titles, and URLs as untrusted input. Pass structured arguments/JSON rather than interpolated shell, redact auth headers, and allow only configured GitHub hosts/repositories. + +**Inference — High confidence (90%).** This profile is large enough for fast capture and issue-to-workflow handoff, while every excluded feature has a documented configuration, permission, tier, kind, or object-model dependency. It therefore supports a real v1 without pretending GitHub's richer planning model is portable. + +## Answers to the Six Category 3 Questions + +1. **Smallest common set:** resolve, create, read, list/search, patch update, comment, labels, state transition, and capability discovery; normalize only minimal issue fields and retain raw metadata. +2. **Non-normalizable:** issue/PR kind, hierarchy, dependency links, projects, workflow states/transitions, issue types/custom fields, assignee identity/cardinality, rich text, and move semantics stay capability-gated/native. +3. **Execution:** filesystem for local; API semantics as the hosted baseline; CLI as a versioned convenience adapter; MCP as an optional host adapter. Preselect transport, and never post-dispatch fail over a write without proof. +4. **References:** persist `maister-issue://////` plus current `webUrl`; accept aliases and vendor URLs only as resolver inputs. +5. **Boundary semantics:** expose auth requirements, continuation cursor, rate/reset metadata, typed errors with raw provider evidence, dispatch/ambiguous-commit state, preconditions, and independent offline read/write capabilities. +6. **GitHub v1:** pin REST `2026-03-10`; guarantee issue-only CRUD/comments/labels/open-close/search with capability/auth preflight; gate hierarchy/dependencies/types/fields/projects/assignees and degrade explicitly. + diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/04-product-quality-tradeoffs.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/04-product-quality-tradeoffs.md new file mode 100644 index 00000000..059007a3 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/findings/04-product-quality-tradeoffs.md @@ -0,0 +1,419 @@ +# Category 4 Findings: Product Quality Trade-offs + +## TL;DR + +Use a small executable provider boundary with declarative capabilities; ship local Markdown and GitHub first. Handoff should persist a canonical `IssueRef`, an immutable normalized snapshot, and its revision—not a live mutable copy. Local Markdown needs random stable IDs, same-directory atomic publication, per-issue locks, and optimistic revision checks. Treat issue content as untrusted data, keep credentials outside repository configuration, and require explicit confirmation for external writes. + +## Key Decisions + +- **Recommendation (confidence: 86%, medium):** v1 should combine a canonical `IssueRef`, immutable captured snapshot, normalized fields, and source revision; `orchestrator-state.yml` remains workflow execution/resume state. +- **Recommendation (confidence: 84%, medium):** use a small executable provider helper with a strict normalized contract and capability discovery, while preserving provider-specific escape hatches outside the common workflow path. +- **Recommendation (confidence: 90%, high):** local issue identity must not depend on a slug or next sequential number; use an opaque random ID and treat the title slug as presentation only. +- **Recommendation (confidence: 91%, high):** project configuration may name credentials but must never contain them; external writes require an explicit operation and validated target. +- **v1 scope:** capture, list, show, select, and handoff; local Markdown plus GitHub; read-only drift checks; mocked external tests; direct-prompt workflows remain supported. +- **Later scope:** bidirectional synchronization, comments/status/labels from workflows, webhooks, user-global defaults, provider plugins, native dependency graphs, and automated stale-lock recovery. + +## Open Questions / Risks + +- The exact user-facing command names and canonical `IssueRef` grammar must be reconciled with Category 1 and Category 3 findings; this document specifies required behavior, not a final parser syntax. +- Product choice: whether an interactive first use may offer one-step local setup or must always stop and direct the user to `$maister:init`. +- Product choice: whether a workflow may refresh its snapshot after initialization. The safer v1 posture is an explicit refresh that archives the previous snapshot and never silently changes active workflow context. +- Filesystem guarantees vary on network filesystems. v1 should define support for ordinary local filesystems and fail with a diagnostic when lock or atomic-replace assumptions cannot be established. +- Git merge conflicts cannot be made atomic by the local provider. They must be detected and surfaced for human resolution. + +## Evidence Labels and Confidence + +- **Direct evidence** describes current repository behavior, tests, standards, or installed prior art. +- **Inference** connects direct evidence to the proposed tracker boundary. +- **Recommendation** is a product or architecture choice. +- Confidence follows `planning/research-plan.md` § **Confidence Rules**: high is 90–100%, medium is 60–89%, and low is below 60%. + +External security sources were accessed on **2026-07-13**. They are official OWASP or GitHub documentation. + +## 1. Minimum UX and Complete User Journeys + +### 1.1 Minimum command vocabulary + +**Recommendation (confidence: 82%, medium):** expose one issue-intake surface with these behavioral operations. Names may be rendered as host-native skills or commands, but their semantics should remain stable. + +| Operation | Explicit use | Interactive use | v1 behavior | +|---|---|---|---| +| Capture | `issue capture "title" [--body ...] [--provider P]` | Prompt for provider only when selection is genuinely ambiguous; collect title and optional body | Create exactly one issue and return its canonical `IssueRef`; no workflow starts implicitly | +| List | `issue list [--provider P] [--status open] [--limit N]` | Show a bounded numbered list and provider/status for each item | Read-only; stable ordering; state when results are incomplete/offline | +| Show | `issue show ` | Show the chosen list item | Read-only normalized fields plus provider-specific URL/path and freshness metadata | +| Select | `issue select [filters]` | Numbered choice from bounded results | Return one `IssueRef`; cancellation performs no write | +| Handoff | `research --issue `, `quick-plan --issue `, `development --issue `, or unified `work ` | After show/select, ask which workflow to start | Resolve, snapshot, initialize one workflow task, and record provenance | + +This separates persistent intake from workflow execution, matching the research brief § **Key Decisions** and project architecture § **Persistence Model**. Existing workflows already accept direct task descriptions and create their task directories/state (`plugins/maister/skills/research/SKILL.md` § **Initialization**, `plugins/maister/skills/quick-plan/SKILL.md` § **Workflow**, `plugins/maister/skills/development/SKILL.md` § **Initialization**); the issue path should be additive, not a replacement. **Direct evidence (confidence: 96%, high).** + +The installed prior art uses repository-local tracker instructions and explicit publish/fetch vocabulary rather than conflating tracker state with execution: `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/SKILL.md` § **Section A — Issue tracker**, and the three templates’ headings **When a skill says “publish to the issue tracker”** / **When a skill says “fetch the relevant ticket”**. **Direct evidence (confidence: 95%, high).** + +### 1.2 Journey A — interactive local capture to research + +**v1 must-have; recommendation (confidence: 88%, medium).** + +1. User invokes issue capture with no provider and no title in an interactive host. +2. Resolution finds one valid project default, `local`; if multiple providers are configured without a default, the UI asks the user to choose. No guessing from Git remotes occurs after providers are explicitly configured. +3. UI asks for a required title and optional body. It previews `provider=local` and repository-local destination; cancellation leaves files and directories unchanged. +4. Provider allocates an opaque ID, derives a bounded display slug, publishes one complete Markdown record atomically, and returns a canonical `IssueRef` plus local path. +5. UI offers read-only show, start workflow, or stop. User selects research. +6. Handoff re-reads the issue under revision protection, writes `source/issue-ref.yml` and an immutable `source/issue-snapshot.md` (or equivalently structured files) inside the new research task, then initializes `orchestrator-state.yml` with a pointer/digest to that snapshot. +7. Research starts from the snapshot as untrusted source material. Later edits to the local issue do not rewrite active research context; show/resume can report “source changed since capture.” + +The installed local template’s `.scratch//issues/-.md` and “first by number wins” conventions demonstrate a usable simple journey, but sequential IDs and in-place `Status:` edits are not concurrency-safe (`/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md` § **Conventions** and § **Wayfinding operations**). **Direct evidence plus inference (confidence: 93%, high for the limitation).** + +### 1.3 Journey B — explicit GitHub capture/select to quick planning + +**v1 must-have; recommendation (confidence: 85%, medium).** + +1. User runs explicit capture with `--provider github`, title, and body. The command resolves the configured owner/repository; it does not infer a different target from an unrelated current directory. +2. Before the network write, Maister validates the repository allowlist, authentication availability, requested capability, and body size, then shows the target in interactive mode. The operation performs one create request and returns a fully qualified `IssueRef` and URL. +3. Alternatively, user runs bounded `issue list --provider github --status open`, then `issue show ` or interactively selects one result. List/show are read-only and can degrade to an actionable offline/auth error. +4. User invokes quick plan with `--issue `. A full provider-qualified ref is authoritative; a conflicting `--provider local` is rejected before reads or writes. +5. Handoff fetches the issue once, normalizes fields, records native revision/freshness data, writes an immutable snapshot, and starts quick planning from the normalized objective/body. +6. Quick plan remains behaviorally compatible with direct task text; after approval it follows its existing implementation/verification flow rather than using tracker status as execution state (`plugins/maister/skills/quick-plan/SKILL.md` § **Workflow**). + +The GitHub prior-art template demonstrates explicit create/read/list and the ambiguity of bare GitHub numbers because issues and PRs share a number space (`/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md` § **Conventions** and § **Pull requests as a triage surface**). **Direct evidence (confidence: 94%, high).** + +### 1.4 Journey C — existing reference to development with provenance + +**v1 must-have; recommendation (confidence: 87%, medium).** + +1. User invokes development or unified work with a full `IssueRef`; no capture occurs. +2. Parser validates provider, repository/project namespace, issue kind, and native ID before provider invocation. An unknown provider, ambiguous bare number, or namespace mismatch fails closed with examples of valid references. +3. Provider resolves and reads the issue. If offline and no explicit cached snapshot was selected, initialization stops without creating a task. A later capability may permit `--snapshot ` offline handoff. +4. Maister displays source, title, current tracker status, and snapshot timestamp. In an interactive host, starting the workflow is the only approval; no tracker mutation is implied. +5. Development task initialization stores ref + snapshot + revision and then creates normal workflow state. `orchestrator-state.yml` owns phase/gate/resume semantics; tracker status remains live tracker data. +6. During resume, Maister may perform a read-only revision check. If changed, it warns and links/show diffs; it does not rewrite the task objective, reset phases, close the issue, or post comments. +7. Completion reports the source reference and workflow result locally. Updating/closing the external issue is a separate explicit command with a target preview and confirmation. + +Current unified work already distinguishes new descriptions from task folders containing `orchestrator-state.yml` and routes resume from that state (`plugins/maister/commands/work.md` § **Usage**, § **Step 1: Parse Input and Detect Task Folder**, and § **Step 2: Resume Existing Task**). Development can also derive task context from an existing research folder (`plugins/maister/skills/development/SKILL.md` § **Initialization**). **Direct evidence (confidence: 96%, high).** + +### 1.5 Journey D — explicit non-interactive list/show/select + +**v1 must-have; recommendation (confidence: 83%, medium).** + +1. Automation runs `issue list --provider local --status open --limit 20 --format json`. +2. Output contains schema version, provider, canonical refs, normalized summaries, and `complete: true|false`; diagnostics go to stderr. +3. Automation passes one returned ref to `issue show --format json`, checks the revision, then starts a workflow with that exact ref. +4. If configuration is ambiguous, results exceed a required deterministic bound, or the selected ref disappeared, the command exits nonzero and makes no mutation. Non-interactive execution never opens a prompt or silently chooses the first item. + +This mirrors the executable continuation boundary’s JSON-only stdout, stderr diagnostics, exact schema checks, and non-mutation on invalid input in `tests/phase-continue-contract.test.sh` functions `test_valid_stdin`, `test_exact_schema_validation`, and `test_validation_channels_and_immutability`. **Direct precedent and recommendation (confidence: 93%, high).** + +## 2. Domain Glossary + +**Recommendation (confidence: 90%, high):** use distinct tracker-intake and workflow-execution terms. The architecture’s no-database persistence model and authoritative workflow state make this separation essential (`.maister/docs/project/architecture.md` § **Persistence Model**). + +| Term | Owned by | Definition and invariant | +|---|---|---| +| `Issue` | Tracker context | The provider’s current, mutable work item as read now. It is normalized for consumption but remains tracker-owned. It is not a workflow and is not authoritative for resume. | +| `IssueRef` | Intake boundary | Immutable, canonical locator containing provider, namespace/repository, kind, and native ID. It identifies an issue but does not promise that it currently exists or is accessible. | +| `TrackerProvider` | Provider layer | Adapter implementing validated operations and declaring capabilities. Provider-specific terms are translated at this anti-corruption boundary. | +| `ProviderCapability` | Provider layer | A discoverable operation/feature with semantics, e.g. `read`, `create`, `list`, `update`, `comment`, `labels`, `state`, `native_dependencies`. Absence is data, not an exception or emulation promise. | +| `CapturedSnapshot` | Workflow task source | Immutable, time-stamped representation used to initialize a workflow: ref, selected normalized fields, native URL/path, capture time, source revision, and digest. Its content is untrusted data. | +| `SourceRevision` | Provider/intake boundary | Provider-native version token when available (ETag/update timestamp/object ID) or a deterministic content digest. Used for drift detection and compare-before-update, not as issue identity. | +| `WorkflowTask` | Workflow context | One research/planning/development execution directory under `.maister/tasks/`, including artifacts and source provenance. Multiple workflow tasks may originate from one issue. | +| `WorkflowState` | Orchestrator | `orchestrator-state.yml`: authoritative phase, gate, attempt, audit, and resume state after task initialization. It never serves as the backlog. | +| `TrackerStatus` | Tracker context | Provider-normalized lifecycle such as open/closed, plus native state. It must not be called workflow status. | +| `PhaseStatus` | Orchestrator | Workflow execution status such as pending/in-progress/completed/blocked. It never automatically changes `TrackerStatus`. | +| `Handoff` | Integration boundary | Read-only resolve + capture + workflow initialization operation that turns one `IssueRef` into one workflow task with provenance. Handoff is not synchronization. | +| `Drift` | Integration boundary | The live issue’s current revision differs from the captured source revision. Drift is surfaced, never silently merged into an active workflow. | + +The vocabulary is an anti-corruption layer in the sense of `.maister/docs/standards/global/language-md-convention.md` § **Relationship Types**: vendor words such as GitLab “note,” GitHub “comment,” PR/MR, and native dependency links should not leak into core workflow semantics. The installed GitHub and GitLab templates visibly use different words and number spaces, confirming the need (`issue-tracker-github.md` / `issue-tracker-gitlab.md` § **Conventions**). **Direct evidence and inference (confidence: 92%, high).** + +## 3. Tracker-vs-Workflow Ownership and Snapshot Policy + +### 3.1 Ownership model + +| Data/behavior | Tracker owns | Captured snapshot owns | Workflow task owns | `orchestrator-state.yml` owns | +|---|---:|---:|---:|---:| +| Canonical locator and native URL/path | Live resolution | Exact ref/URL used at capture | Pointer to source files | Snapshot path/digest only | +| Title/body/acceptance context | Current mutable value | Immutable captured value | Derived objective and authored artifacts | No backlog copy | +| Labels, assignees, comments, dependencies | Yes | Optional normalized values as-of capture | No live authority | No | +| Tracker open/closed/native state | Yes | Value as-of capture | No | No | +| Source revision/capture time/digest | Current revision | Yes | Source audit files | Pointer/digest may be recorded | +| Workflow phases, attempts, gates, decisions | No | No | Artifacts/reports | Sole resume/audit authority | +| External mutations | Explicit provider command | Never | May propose a mutation | Never implicitly performs it | + +**Direct evidence (confidence: 98%, high):** `.maister/docs/project/architecture.md` § **Persistence Model** says there is no database and `orchestrator-state.yml` is the only resume source of truth; the research brief § **Key Decisions** explicitly excludes backlog ownership from it. + +### 3.2 What initialization stores + +**Recommendation (confidence: 86%, medium): store the combination, not one alternative.** + +- `IssueRef`: durable provenance and future re-resolution. +- Immutable snapshot: reproducibility when the issue changes, disappears, becomes private, or the provider is offline. +- Selected normalized fields: workflow-friendly input without importing provider-specific schemas. At minimum: title, body, tracker status, labels, URL/path, created/updated timestamps when available. +- Source revision and digest: drift detection and integrity checks. +- Capture metadata: provider version/capabilities used, capture timestamp, and whether fields were unavailable/truncated. + +Ref-only is not reproducible; snapshot-only loses provenance and freshness; normalized-fields-only may omit evidence needed later. The project vision requires safe, auditable, resumable workflows and exact state provenance (`.maister/docs/project/vision.md` § **Purpose**). **Inference (confidence: 93%, high).** + +### 3.3 Later tracker changes + +**v1 behavior:** compare revisions on explicit show/refresh and optionally at resume if the provider is reachable. Report `unchanged`, `changed`, `deleted/inaccessible`, or `unknown/offline`. Do not block normal resume merely because the freshness check is unavailable; clearly label that the workflow is using its captured snapshot. Do block explicit external update when expected revision differs. **Recommendation (confidence: 87%, medium).** + +An explicit refresh should archive the prior snapshot, create a new immutable snapshot, record who/when/why, and ask the workflow to reconcile; it must not rewrite completed decisions. Automatic bidirectional synchronization is **later**, because it introduces two-writer conflict semantics and violates minimal-implementation guidance (`.maister/docs/standards/global/minimal-implementation.md` § **No Speculative Abstractions**). **Recommendation (confidence: 91%, high).** + +## 4. Configuration Precedence and Failure Behavior + +### 4.1 Recommended v1 configuration ownership + +- Store non-secret project configuration under the existing `.maister/config.yml`: enabled providers, one optional default, local root, and fixed external namespace/repository allowlists. +- Store credentials only in provider-native authenticated CLIs, host credential stores, environment variables, or secret managers. Configuration may contain an allowlisted environment-variable *name*, never its value. +- Do not add a user-global default in v1. Repository-local configuration is deterministic across hosts and follows installed precedent (`/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/SKILL.md` § **Write**), while `.maister/config.yml` is already the project-local policy surface (`.maister/docs/project/architecture.md` § **Configuration**). + +**Recommendation (confidence: 89%, medium).** + +### 4.2 Selection precedence + +Apply this order and stop at the first decisive, valid source: + +1. A fully qualified `IssueRef` determines provider and namespace for operations on that ref. +2. Explicit command override `--provider P` determines provider for capture/list or unqualified input. If it conflicts with a full ref, reject; do not reinterpret the ref. +3. Project `tracker.default_provider` when it names exactly one enabled provider. +4. If exactly one provider is enabled, use it as the unambiguous effective provider. +5. If multiple are enabled without a default, interactive hosts ask; non-interactive hosts fail with provider names and the exact override syntax. +6. If none is configured, fail with setup guidance. An interactive one-step “configure local” offer is an unresolved product choice and must be confirmed before writing config. + +Never choose a provider from a Git remote once explicit tracker configuration exists. Remote inference is acceptable only during setup as a recommendation, matching installed setup prior art (`setup-matt-pocock-skills/SKILL.md` § **Explore** / **Section A — Issue tracker**). **Recommendation (confidence: 92%, high).** + +### 4.3 Validation and failure semantics + +| Condition | Required behavior | +|---|---| +| Duplicate keys, aliases/anchors, noncanonical managed shape, unknown provider, contradictory overrides | Reject before any read/write; identify exact field and accepted values | +| Missing default with multiple providers | Ask only if interactive; otherwise fail without choosing | +| Missing credentials | Read-only local operations remain available; external operation fails with provider-specific login guidance, without printing tokens | +| Unsupported capability | Return a typed `unsupported_capability` result; do not emulate a write through prose or silently drop fields | +| Provider offline/rate-limited | Preserve local state; return retryability and safe retry guidance; never switch providers | +| Invalid repository/URL/ref | Reject via allowlist and canonical parser before subprocess/network/filesystem access | +| Setup/reconciliation failure | Preserve complete original bytes, modes, and directory topology; name recovery artifacts only if rollback itself fails | + +This follows `.maister/docs/standards/global/validation.md` § **Validate Early**, **Allowlists Over Blocklists**, and **Consistent Enforcement**, plus `.maister/docs/standards/global/error-handling.md` § **Clear User Messages**, **Fail Fast**, and **Graceful Degradation**. Existing configuration tests reject ambiguous/unsafe YAML unchanged and preserve bytes/modes (`tests/advisor-config-reconciliation.test.sh` cases 5–9); lifecycle tests prove contradictory flags fail before mutation and second-artifact failures restore exact YAML/TOML state (`tests/advisor-init-lifecycle.test.sh` cases 1, 6, 8–13). **Direct precedent (confidence: 98%, high).** + +## 5. Local Markdown Persistence and Concurrency Design + +### 5.1 Record and identity design + +**Recommendation (confidence: 92%, high):** use an opaque random ID generated by a built-in cryptographic primitive (for example UUIDv4), independent of title and creation order. A possible layout is `.maister/issues/.md`; a sanitized slug may appear in frontmatter or a derived index, but never participates in lookup authority. + +Each canonical record should have strict, bounded frontmatter: schema version, ID, title, tracker status, created/updated timestamps, integer revision, and optional normalized labels; body follows as Markdown. Reject duplicate keys, aliases, unsupported types, NULs, invalid UTF-8, conflict markers in managed metadata, and files whose frontmatter ID differs from the filename. Preserve unknown body content verbatim. + +Why not sequential `NN-slug`? The installed local template allocates numbers from `01` and scans “first by number,” which races when multiple sessions create tickets (`/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md` § **Conventions** / **Frontier**). The wayfinder skill explicitly warns that unblocked tickets may be worked in parallel (`/Users/mrapacz/.agents/skills/wayfinder/SKILL.md` § **Work through the map**). **Direct evidence and inference (confidence: 95%, high).** + +### 5.2 Create transaction + +1. Validate all fields, root containment, size limits, and ID/slug allowlists in memory. +2. Ensure issue root and lock root are real directories under the configured project root; reject symlinks for managed roots. +3. Generate a random ID and final path; if it exists, generate another ID rather than overwrite. +4. Write the complete record to an unpredictable same-directory temporary file opened exclusively; set intended mode; flush file contents. +5. Acquire a short-lived creation/index lock only if a shared derived index must be changed. Prefer no mutable shared index in v1: list can scan canonical records. +6. Recheck final nonexistence and atomically publish the temporary file to the final path. Flush the parent directory where supported. +7. Remove temporary/lock artifacts in cleanup. On failure before publication, no canonical issue exists; on failure after publication, report the returned ref and do not retry creation blindly. + +The repository’s executable precedent writes to a same-directory temporary directory, fsyncs, then renames in `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` function `atomicWrite`. Advisor reconciliation stages beside the destination and uses candidate/backup/commit/restore functions in `plugins/maister/skills/init/bin/reconcile-advisor-config.sh`. **Direct precedent (confidence: 97%, high).** + +### 5.3 Update transaction and multiple agents + +1. Require canonical ID and optional `expected_revision`/digest. +2. Acquire an exclusive per-issue lock by atomically creating `.locks/.lock/`; lock metadata contains random owner token, PID, host, and timestamp for diagnostics. +3. Read and strictly parse the current record after lock acquisition. +4. If expected revision/digest differs, return `conflict` with current revision and perform no mutation. +5. Build a complete candidate with incremented revision; write/fsync same-directory temporary; recheck lock ownership; atomically replace final; flush directory where supported. +6. Release only a lock whose owner token matches. On timeout, fail with owner/age diagnostics. v1 must not automatically steal stale locks because PID and liveness are not portable across hosts/network filesystems. + +Locks prevent two cooperating provider processes from overwriting one another; revision checks protect callers with stale reads. No design can stop an unrelated editor from bypassing the provider, so compare the on-disk digest again immediately before replacement and fail on drift. **Recommendation (confidence: 88%, medium).** + +### 5.4 Required edge behavior + +| Case | v1 design | +|---|---| +| Duplicate slugs/titles | Allowed; opaque ID is identity. UI may disambiguate with short ID/provider/status. | +| Random ID collision | Retry allocation; never overwrite. | +| Two simultaneous creates | Different IDs publish independently; no global sequential counter. | +| Two simultaneous updates | Per-issue lock serializes; stale expected revision loses without mutation. | +| Partial process crash | Canonical file is old or complete new version; incomplete temp is ignored by scans and may be cleaned later. | +| Git conflict markers | Managed parser rejects conflicted frontmatter; show may expose raw path; update refuses until manual resolution. | +| Git branch divergence | Stable IDs reduce rename conflicts but same-record edits can conflict; never auto-merge tracker records in v1. | +| Path traversal | IDs and provider names use strict allowlists; canonicalized target must remain below root; reject absolute paths, `..`, separators, NUL, symlinks, and root escapes. | +| Permissions | Preserve mode on update; create least-permissive project-appropriate mode; tests assert modes and topology. | +| Lock timeout | Fail actionable and unchanged; provide manual inspection/recovery instructions, not automatic lock deletion. | + +Transactional rejection is a documented testing requirement: `.maister/docs/standards/testing/test-writing.md` § **Prove Rejected Transactional Mutations Leave State Unchanged** requires byte-exact snapshots plus modes and directory topology. `tests/phase-continue-contract.test.sh` helpers `snapshot_files`, `snapshot_directories`, and `state_reports_and_directories_unchanged` are concrete precedent. **Direct evidence (confidence: 99%, high).** + +## 6. Security Boundaries and Threat/Failure Table + +### 6.1 Trust boundaries + +1. **User/config → core parser:** untrusted until exact schema, allowlist, and precedence validation succeeds. +2. **Issue content/provider output → model/workflow:** untrusted data, never instructions. Preserve provenance and visibly delimit it. +3. **Core → subprocess/API/filesystem:** use structured argument arrays/APIs, fixed executables/operations, canonical paths, and least privilege. +4. **Read → write:** reads do not authorize writes. Every external mutation names provider, target, operation, expected revision, and confirmation policy. +5. **Credential boundary:** tokens are retrieved at execution time and never enter snapshots, prompts, logs, command strings, config, or generated artifacts. + +OWASP describes indirect prompt injection through external files/content and recommends strict output formats, least privilege, human approval for high-risk actions, and clearly segregating external content ([OWASP LLM01:2025 Prompt Injection](https://genai.owasp.org/llmrisk/llm01-prompt-injection/), §§ **Types**, **Prevention and Mitigation Strategies**). OWASP’s command-injection guidance prefers direct APIs; where processes are unavoidable, it recommends structured separation of commands/data plus allowlist validation ([OWASP OS Command Injection Defense](https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html), §§ **Primary Defenses**). **Direct external evidence (confidence: 94%, high).** + +OWASP recommends least-privilege and fine-grained secret access ([OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html), § **Access Control**). GitHub recommends fine-grained tokens restricted to specific repositories and permissions; issue access has separate read/write levels ([GitHub: Managing personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), §§ **Permissions**, **Repository permissions**). **Direct external evidence (confidence: 95%, high).** + +### 6.2 Threat and failure table + +| Threat/failure | Impact | v1 control | Residual/later work | Confidence | +|---|---|---|---|---:| +| Credential committed in `.maister/config.yml` | Repository-wide secret leak | Schema accepts credential references only; reject token-like managed fields; redact diagnostics; provider-native auth/env/secret store | Automated secret scanning/rotation integration later | 96% high | +| Over-broad token | Unauthorized reads/writes across repos | Document least privilege; fixed repository allowlist; separate read/write capability checks | Provider-specific scope auditor later | 92% high | +| Shell/argument injection through title, ref, repo, labels | Arbitrary command or altered CLI operation | No shell interpolation; spawn fixed executable with argument array; `--` where supported; allowlist provider/ref/repo/enum fields; prefer API/library | CLI-specific adversarial fixtures remain necessary | 95% high | +| Indirect prompt injection in issue body/comments | Model ignores workflow policy, leaks data, or writes externally | Label/delimit snapshot as untrusted; issue content cannot select tools/provider/paths; deterministic schema checks; explicit confirmation for external writes | Content filtering and adversarial evaluation later | 93% high | +| Secret pasted into issue then copied into snapshot/report | Durable leakage in Git/task artifacts | Warn on capture; bounded secret-pattern detection/redaction gate before snapshot/log; never echo credentials; preserve safe audit marker | Full DLP is out of scope and imperfect | 81% medium | +| Malicious URL/repository/ref | Wrong target, SSRF-like fetch, credential forwarding | Provider-specific canonical grammar; configured host/repository allowlist; reject arbitrary URL schemes/credentials/redirected hosts | Enterprise/self-hosted host policy later | 90% high | +| Wrong-repository external write | Corrupts unrelated backlog | Full ref or fixed project config; preview target; expected revision; confirmation; never infer during write | Batch writes later require per-target audit | 94% high | +| Path traversal or symlink escape | Overwrite/read arbitrary project or user files | Strict ID regex, canonical containment checks, `lstat`, reject managed symlinks/absolute/`..`/separators, same-directory temp | Platform-specific no-follow primitives if needed | 93% high | +| Concurrent local updates | Lost update | Per-issue lock + expected revision/digest + atomic replacement | Network filesystem qualification | 88% medium | +| Crash/partial write | Corrupt issue or misleading success | Complete same-directory candidate, fsync, atomic publish, cleanup, post-publication ref reporting | Power-loss matrix varies by filesystem | 87% medium | +| Git conflict | Invalid metadata or silent lost change | Reject conflict markers in managed frontmatter; no auto-merge; manual recovery message | Semantic merge tool later | 92% high | +| Provider returns malformed/oversized data | Memory/resource abuse or schema confusion | Exact bounded response schema, pagination/item/body limits, UTF-8 checks, unknown-field policy | Streaming for very large bodies later | 90% high | +| Provider unavailable, rate-limited, or auth expired | Handoff/capture failure, unsafe retry | Typed retryable/nonretryable result; no provider fallback; read-only snapshot remains usable; create retries require idempotency/ref check | Provider-specific retry budgets later | 90% high | +| Source changes after handoff | Non-reproducible or contradictory workflow | Immutable snapshot + source revision; visible drift; no silent refresh | Explicit archived refresh later | 91% high | +| Ambiguous bare `#42` | Wrong issue/PR/provider | Require context or full `IssueRef`; fail when ambiguity remains | Friendly shorthand after deterministic resolution | 95% high | +| External write triggered by “close this” text inside issue | Unauthorized action via content | Issue content is data; only user command/workflow policy can request write; human confirmation for high-risk mutation | Policy-configurable low-risk writes later | 96% high | + +## 7. Risk-Based Behavior Test Matrix + +Tests should assert observable contracts and mock external systems, following `.maister/docs/standards/testing/test-writing.md` §§ **Test Behavior**, **Mock External Dependencies**, **Risk-Based Testing**, and **Critical Path Focus**. No test should write to a real tracker. + +| Risk / priority | Area | Behavior cases | Required assertions | Scope | +|---|---|---|---|---| +| Critical | Provider contract | Same fixture suite for local/GitHub: create/read/list/ref resolution/capabilities; unsupported operation; malformed response; pagination bound | Exact normalized schema; provider-specific data stays in extension field; typed errors; no silent fallback | v1 | +| Critical | Config precedence | Full ref, override, project default, sole provider, multiple/no default, none configured, contradictory flags, duplicate/unsafe YAML | Deterministic provider; interactive-only prompt; noninteractive failure; byte/mode/topology unchanged | v1 | +| Critical | Local create | Parallel creates with same title/slug, forced ID collision, invalid body/metadata, injected write/fsync/publish failure | Unique stable refs; no overwrite; canonical files old-or-complete; no leaked temp/lock artifacts | v1 | +| Critical | Local update | Two writers, stale expected revision, lock timeout, process crash, permission failure, conflicted file | Exactly one successful revision; loser gets conflict; bytes/mode/topology unchanged on rejection; actionable recovery | v1 | +| Critical | Filesystem security | `../`, absolute path, separators, NUL, symlinked root/record/lock, oversized file, filename/frontmatter mismatch | Access rejected before read/write; no out-of-root artifacts | v1 | +| Critical | Handoff to research | Valid local/GitHub issue, changed/deleted issue during fetch, snapshot write failure | One task only on success; ref/snapshot/revision/digest present; no task/state on precommit failure; research receives snapshot | v1 | +| Critical | Handoff to quick plan | Explicit ref and interactive selection; direct prompt regression | Issue path creates provenance; direct text still works unchanged; tracker status is not phase status | v1 | +| Critical | Handoff to development/work | Full ref, ambiguous bare number, existing task-folder resume, source drift | Correct routing; ambiguous input fails; existing `orchestrator-state.yml` resumes; drift never rewrites state | v1 | +| Critical | External write security | Injected shell metacharacters/leading flags, wrong repo, prompt-injection body, expired auth, duplicate create retry | Fixed argv/API calls; allowlist rejection; no content-driven write; no token in stdout/stderr/snapshot; idempotent outcome | v1 | +| High | Transactional setup/migration | Add tracker config to absent/valid config; malformed existing config; injected second-artifact failure; rollback failure | Exact rollback of bytes, modes, existence, directories; critical recovery paths retained only when rollback fails | v1 | +| High | Snapshot/freshness | Unchanged, changed, deleted/private, offline; explicit refresh | Stable original snapshot; correct drift state; offline resume uses labeled snapshot; refresh archives prior version | v1 read-only; refresh later | +| High | Generated platforms | Canonical skill/helper transformed for Claude, Codex, Cursor, Kiro; host command/tool vocabulary fixtures | `make build` deterministic; generated diff expected; host-capability behavior explicit; `make validate` passes | v1 | +| High | Migration/backward compatibility | Existing `.maister/config.yml` without tracker section; direct workflow invocation; no issue directory | Existing workflows behave identically; no eager directory/config mutation; feature opt-in | v1 | +| Medium | UX output | Bounded list, empty list, cancellation, JSON output, truncation/incomplete marker | Stable order; clear provider/status/ref; cancellation is read-only; JSON-only stdout and stderr diagnostics | v1 | +| Medium | Capability extensions | Labels/comments/state/native dependencies absent or present | Capability discovery governs UI; unsupported never pretends success | basic v1, mutations later | +| Medium | Git collaboration | Independent creates, same-record edits, conflict markers, branch rename | Stable IDs merge where independent; same-record conflict rejects; no automatic conflict resolution | v1 | +| Medium | Resilience | Rate limit with retry hint, timeout, malformed CLI JSON, provider command missing | Typed error/retryability; bounded retries; local provider remains usable; no cross-provider fallback | v1 | + +### 7.1 Test implementation precedents + +- `tests/phase-continue-contract.test.sh` validates duplicate JSON rejection, exact schema, path collisions, canonical state, unchanged files/directories, and durable recovery after injected report/transition failures. **Direct evidence (confidence: 98%, high).** +- `tests/advisor-config-reconciliation.test.sh` cases 5–9 validate ambiguity rejection, exact no-op, mode preservation, domain bounds, and unsupported YAML features. **Direct evidence (confidence: 98%, high).** +- `tests/advisor-init-lifecycle.test.sh` cases 1 and 6–13 validate precedence, pre-mutation rejection, two-artifact rollback, retained recovery artifacts on critical rollback failure, cleanup, and directory topology. **Direct evidence (confidence: 99%, high).** +- `.maister/docs/standards/global/build-pipeline.md` § **Canonical Source and Reproducible Generated Variants** requires canonical edits under `plugins/maister/`/`platforms/` and deterministic generated outputs, while § **Build and Validate Every Platform Before Release** requires `make build && make validate`. **Direct evidence (confidence: 99%, high).** + +## 8. Architecture Options + +### 8.1 Common evaluation rubric + +Scores: 1 poor, 3 mixed, 5 strong. These are comparative recommendations, not measured facts. + +| Criterion | A. Prose/config instructions | B. Declarative contract, host-executed | C. Small executable helper + declarative capabilities | +|---|---:|---:|---:| +| Initial simplicity | 5 | 3 | 3 | +| Deterministic generation/parity | 2 | 4 | 5 | +| Validation/fail-closed behavior | 1 | 3 | 5 | +| Testability and atomic local writes | 1 | 3 | 5 | +| Minimal dependencies | 5 | 5 | 4 | +| Offline local use | 4 | 4 | 5 | +| Extensibility | 3 | 4 | 4 | +| Tracker-specific escape hatches | 5 | 3 | 4 | +| Security/credential boundary | 2 | 3 | 5 | +| Host parity | 2 | 3 | 5 | +| Migration cost | 5 | 4 | 3 | + +### 8.2 Option A — repository prose/config instructions + +Each provider is described in Markdown like the installed `docs/agents/issue-tracker.md` templates; skills interpret “publish,” “fetch,” “list,” “claim,” and “resolve” using host tools/CLIs. + +- **Strengths:** fastest to author; highly adaptable; almost no runtime dependency; proven understandable in `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-{local,github,gitlab}.md`. +- **Weaknesses:** implicit interface, variable model execution, weak machine validation, difficult atomicity/idempotency guarantees, and high risk that credentials/content enter prompts or shell strings. +- **Fit:** useful documentation and provider guidance, not sufficient as the v1 safety boundary. +- **Recommendation:** reject as sole architecture. **Confidence: 94%, high** because current templates directly expose tracker-specific command prose and concurrency gaps. + +### 8.3 Option B — canonical declarative provider contract executed by each host + +A strict provider/config schema declares operations, command templates, capabilities, and normalized fields; each host adapter invokes its available subprocess/filesystem/tool mechanisms. + +- **Strengths:** documentation-as-code fit, low runtime footprint, deterministic schema, and visible capabilities. +- **Weaknesses:** safe command templates become a programming language; host execution differences can change quoting, errors, auth, and atomicity; complex validation logic risks duplication across generated variants. +- **Fit:** credible if all providers are read-only, but weaker for writes and local concurrency. +- **Recommendation:** retain declarative configuration/capabilities but not host-specific execution as the only implementation. **Confidence: 82%, medium.** + +### 8.4 Option C — small executable provider helper with declarative capabilities + +A canonical, versioned helper exposes structured stdin/stdout operations and owns parsing, target validation, local transactions, subprocess/API invocation, redaction, typed errors, and capability discovery. Skills remain thin UX/orchestration wrappers; adapters package/invoke the helper and map host prompts. + +- **Strengths:** one testable safety boundary; exact schema; consistent local atomicity; structured argv; deterministic JSON; easy mocked providers; strongest parity and audit behavior. Node built-ins are already part of the tech stack (`.maister/docs/project/tech-stack.md` §§ **JavaScript ESM on Node.js**, **Key Dependencies**), and `phase-continue.mjs` proves this pattern for a narrow cross-host state boundary. +- **Weaknesses:** adds code and schema migration responsibility; host packaging and Node availability must be validated; provider-specific features need an extension channel rather than core-field growth. +- **Fit:** best balance for v1 local + GitHub, provided the interface stays narrow and called code only. +- **Recommendation:** choose Option C, with declarative config/capabilities and prose documentation. **Confidence: 87%, medium**; the architecture is strongly supported by repository precedent, but final provider contract and host execution findings remain dependencies on Categories 1 and 3. + +### 8.5 Minimum executable boundary + +**v1 must-have:** `capabilities`, `create`, `resolve/read`, and bounded `list`; structured request/response envelopes; canonical ref parser; typed `invalid_input`, `ambiguous`, `not_found`, `unauthorized`, `forbidden`, `conflict`, `unsupported_capability`, `offline`, `rate_limited`, and `internal` outcomes. Handoff orchestration belongs in workflow skills, not the provider helper. **Recommendation (confidence: 85%, medium).** + +**Later:** `update`, `comment`, labels/state, native dependency links, search DSL, webhooks, and provider plugin loading. Add only with a workflow caller and contract tests, following `.maister/docs/standards/global/minimal-implementation.md` §§ **Build What You Need** and **No Future Stubs**. **Recommendation (confidence: 95%, high).** + +## 9. v1 Must-Haves vs Later Capabilities + +| v1 must-have | Later capability | +|---|---| +| Local Markdown and GitHub providers | GitLab/Jira/Linear implementations after contract validation | +| Full canonical ref; deterministic shorthand rejection | Configurable friendly aliases and cross-repository search | +| Capture, bounded list, show/select, handoff | Comments, labels, assignment, close/state transitions | +| Source ref + immutable snapshot + normalized fields + revision/digest | Webhook-driven freshness and explicit multi-snapshot reconciliation UI | +| Read-only drift detection; explicit external writes only | Policy-controlled low-risk synchronization | +| Random stable local IDs; atomic create/update; per-issue lock; revision conflict | Semantic Git merge driver, stale-lock recovery tooling, shared indexes | +| Strict project-local config; credentials external | User-global preference layer and enterprise credential brokers | +| Three workflow handoffs plus direct-prompt compatibility | Automatic tracker updates on workflow milestones | +| Mocked external provider tests and full transactional rejection tests | Live sandbox conformance suites run only with explicit credentials | +| Canonical source + generated platform parity | Third-party provider/plugin SDK | + +## 10. Answers to the Eight Category Questions + +1. **Minimum journeys:** capture, bounded list, show/select, and explicit handoff, each usable interactively and non-interactively; four complete journeys are specified in §1. +2. **Domain model:** distinct tracker and workflow contexts with `Issue`, `IssueRef`, `TrackerProvider`, `ProviderCapability`, `CapturedSnapshot`, `SourceRevision`, `WorkflowTask`, `WorkflowState`, `TrackerStatus`, `PhaseStatus`, `Handoff`, and `Drift`; see §2. +3. **Initialization storage:** combination of source ref, immutable snapshot, selected normalized fields, revision/digest, and capture metadata; later changes are surfaced as drift and never silently rewrite active context; see §3. +4. **Configuration:** full ref/explicit override → project default → sole provider → interactive choice, otherwise fail; credentials stay external and ambiguity rejects unchanged; see §4. +5. **Local concurrency:** opaque random IDs, strict records, same-directory staged publication, per-issue locks, expected revisions, no auto lock stealing, conflict-marker rejection, and canonical path containment; see §5. +6. **Security:** credentials, command/argument injection, prompt injection, secret leakage, target/URL validation, path traversal, and external writes each have explicit trust boundaries and mitigations; see §6. +7. **Tests:** provider contracts, local persistence, mocked externals, all three workflow handoffs, platform generation, migration, rollback, and transactional rejection are covered by the risk matrix in §7. +8. **Architecture:** three options are compared in §8; recommend a small executable provider helper plus declarative capabilities and prose docs, limited to called v1 operations. + +## 11. Primary Source Index + +### Local project evidence + +- `.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-brief.md` — § **Key Decisions**, § **Success Criteria**. +- `.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-plan.md` — § **Category 4**, § **Confidence Rules**. +- `.maister/docs/project/vision.md` — § **Purpose**, § **Evolution**. +- `.maister/docs/project/architecture.md` — § **Persistence Model**, § **Configuration**, § **Data and Control Flow**. +- `.maister/docs/project/tech-stack.md` — § **JavaScript ESM on Node.js**, § **Database**, § **Testing**, § **Key Dependencies**. +- `.maister/docs/standards/global/validation.md`, `error-handling.md`, `minimal-implementation.md`, `build-pipeline.md`, `conventions.md`, and `language-md-convention.md` — cited headings above. +- `.maister/docs/standards/testing/test-writing.md` — § **Test Behavior**, § **Mock External Dependencies**, § **Risk-Based Testing**, § **Prove Rejected Transactional Mutations Leave State Unchanged**. +- `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` — function `atomicWrite`. +- `plugins/maister/skills/init/bin/reconcile-advisor-config.sh` — functions `build_candidate`, `commit_file`, `restore_file`, `resolve_flags`, `run_init_transaction`. +- `tests/advisor-config-reconciliation.test.sh`, `tests/advisor-init-lifecycle.test.sh`, `tests/phase-continue-contract.test.sh` — cases/functions cited above. +- `plugins/maister/skills/research/SKILL.md`, `plugins/maister/skills/quick-plan/SKILL.md`, `plugins/maister/skills/development/SKILL.md`, `plugins/maister/commands/work.md` — initialization and routing headings cited above. + +### Installed tracker precedent + +- `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/SKILL.md` — § **Process**, especially tracker selection and repository-local write behavior. +- `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md` — § **Conventions**, § **Wayfinding operations**. +- `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md` — § **Conventions**, § **Pull requests as a triage surface**, § **Wayfinding operations**. +- `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md` — § **Conventions**, § **Merge requests as a triage surface**, § **Wayfinding operations**. +- `/Users/mrapacz/.agents/skills/to-spec/SKILL.md`, `to-tickets/SKILL.md`, `triage/SKILL.md`, `implement/SKILL.md`, and `wayfinder/SKILL.md` — explicit publication, readiness, handoff, claim, frontier, and parallel-work semantics. + +### Official external security evidence (accessed 2026-07-13) + +- [OWASP LLM01:2025 Prompt Injection](https://genai.owasp.org/llmrisk/llm01-prompt-injection/) — external-content risk, least privilege, segregation, validation, and human approval. +- [OWASP OS Command Injection Defense Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html) — direct API preference, parameterization, argument separation, allowlists, and least privilege. +- [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) — access control and secret lifecycle guidance. +- [GitHub: Managing personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — fine-grained repository restriction and issue read/write permissions. diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/synthesis.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/synthesis.md new file mode 100644 index 00000000..a3e59188 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/analysis/synthesis.md @@ -0,0 +1,146 @@ +# Synteza: konfigurowalne trackery issue i przekazanie do workflowu + +## TL;DR +Maister powinien dodać małą wykonywalną warstwę providerów z deklaratywnymi capabilities, zaczynając od Local Markdown i GitHub. +Tracker pozostaje właścicielem żywego issue; workflow zapisuje kanoniczny `IssueRef`, niezmienny snapshot i rewizję, a `orchestrator-state.yml` wyłącznie stan wykonania. +Publiczny UX obejmuje konfigurację, capture, list/show/select oraz jawne uruchomienie research, quick-plan lub development z issue. +Rekomendacja ma pewność średnio-wysoką (87%); główne blokery to sprzeczny schemat stanu workflowu i brak wspólnej trwałości `quick-plan`. + +## Key Decisions +- Wybrać mały helper wykonywalny + deklaratywne capabilities — daje jeden walidowalny kontrakt bezpieczeństwa na wszystkich hostach. +- Utrzymać ścisłą granicę własności — tracker posiada bieżący backlog, workflow posiada snapshot wejścia i stan wykonania. +- Utrwalać pełny `maister-issue://...`; skróty i URL-e są wyłącznie aliasami wejściowymi. +- Ograniczyć v1 do Local Markdown i GitHub oraz operacji potrzebnych przez capture/list/show/handoff; pozostałe operacje istnieją w kontrakcie jako capability-gated. +- Zachować bez zmian bezpośrednie wywołania workflowów tekstem i istniejącą ścieżkę resume. + +## Open Questions / Risks +- Trzeba rozstrzygnąć sprzeczność schematu: `orchestrator.started_phase` i zagnieżdżone `orchestrator.phases` kontra `orchestrator.current_phase` i główne `phases` wymagane przez runner. +- `quick-plan` nie ma wspólnego trwałego stanu: Claude/Codex używają planowania hosta, Cursor/Kiro pliku `.maister/plans/*.md`. +- Do decyzji pozostaje, czy v1 ma wystawić mutation UX poza `capture`; rekomendacja bezpieczeństwa to odłożyć comment/close/claim do osobnego etapu. +- Atomowość i blokady Local Markdown należy ograniczyć w v1 do zwykłych lokalnych systemów plików; Git nadal może generować konflikty semantyczne. + +## 1. Odpowiedź syntetyczna + +**Rekomendacja (87%, średnio-wysoka).** Dodać kanoniczny skill `plugins/maister/skills/issue-tracker/` z cienkim UX i zależnościowo lekkim helperem Node ESM. Helper ma posiadać parser `IssueRef`, wybór providera/transportu, walidację targetu, Local Markdown transactions, znormalizowane wyniki, typed errors, redakcję sekretów i capability discovery. Workflowy rozwiązują issue i tworzą snapshot **przed** utworzeniem własnego stanu. To najlepiej łączy istniejący model documentation-as-code z precedensem wykonywalnej, fail-closed granicy `phase-continue.mjs` ([01-maister-internals.md, „Seam Map”](findings/01-maister-internals.md); [04-product-quality-tradeoffs.md, „Architecture Options”](findings/04-product-quality-tradeoffs.md)). + +Nie należy kopiować modelu `mattpocock/skills` jeden do jednego. Jego repozytoryjna konfiguracja, neutralne czasowniki, frontiers, trwałe briefy i jawny handoff są dobrymi wzorcami; prose-as-API, niejednoznaczne referencje, dwa sprzeczne layouty lokalne, wspólne pole `Status:` i nieatomowe zapisy są zbyt słabe dla bezpiecznego, wielohostowego Maistera ([02-mattpocock-skills.md, „Reusable Patterns” i „Weaknesses”](findings/02-mattpocock-skills.md)). + +## 2. Ujednolicona terminologia + +| Termin kanoniczny | Znaczenie | Terminologie źródłowe i rozstrzygnięcie | +|---|---|---| +| `Issue` | Bieżący, mutowalny work item odczytany z providera | GitHub issue, GitLab issue/note, Jira issue, Linear issue, lokalny ticket. Nie jest workflowem. | +| `IssueRef` | Niezmienny, provider-qualified locator | Zastępuje niejednoznaczne `#42`, ścieżki i vendor URL jako zapis trwały. | +| `TrackerProvider` | Adapter antykorupcyjny providera | Zastępuje niejawne instrukcje „publish/fetch/claim” jako kontrakt wykonywalny. | +| `ProviderCapability` | Stan operacji: `native`, `emulated`, `unsupported`, `unknown` wraz z ograniczeniami | Nie redukować do boolean, bo tier, wersja, uprawnienia i obiekt wpływają na dostępność. | +| `CapturedSnapshot` | Niezmienna kopia treści użytej do startu workflowu | Nie jest repliką żywego issue; odpowiada na „na jakim wejściu pracowano?”. | +| `SourceRevision` | ETag/update token/timestamp lub digest | Służy do drift/CAS, nie do identyfikacji. | +| `WorkflowTask` | Katalog wykonania research/development lub trwały plan | Może być wiele workflowów z jednego issue. | +| `WorkflowState` | `orchestrator-state.yml`, stan faz/gates/resume | Nie jest backlogiem i nie dziedziczy tracker statusu. | +| `TrackerStatus` | Stan życia issue | Nie nazywać `PhaseStatus`; brak automatycznej synchronizacji. | +| `Handoff` | Resolve + read + snapshot + initialization | Operacja graniczna, nie synchronizacja ani claim. | +| `Drift` | Różnica między live revision a snapshot revision | Pokazać, nigdy nie scalać po cichu. | + +Bezpośrednie źródła wspierają rozdział: architektura mówi, że `orchestrator-state.yml` jest źródłem resume, a brief badawczy wyłącza backlog z jego odpowiedzialności ([research-brief.md, „Key Decisions”](../planning/research-brief.md); [04-product-quality-tradeoffs.md, „Domain Glossary”](findings/04-product-quality-tradeoffs.md)). **Pewność: 98%, wysoka.** + +## 3. Triangulacja dowodów i sprzeczności + +### 3.1 Punkty zgodne + +1. **Oddzielenie tracker/workflow.** Wszystkie cztery analizy wspierają model ref + snapshot + workflow state. Bezpośrednim precedensem jest istniejący `research_reference` i kopiowanie kontekstu przez development ([01-maister-internals.md, „State and Content Ownership”](findings/01-maister-internals.md)). **Pewność: 94%, wysoka.** +2. **Jeden wykonywalny boundary.** Repo ma precedens Node ESM, exact schema, idempotency i transactional rejection w `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` oraz testach kontraktowych ([01-maister-internals.md, „Existing Fail-Closed and Test Patterns”](findings/01-maister-internals.md)). **Pewność rekomendacji: 87%, średnia.** +3. **Capabilities zamiast udawanej portowalności.** Oficjalne API różnią się workflowami, relacjami, rich text, assignees i identyfikacją; common core musi być wąski ([03-tracker-providers.md, „Capabilities That Must Not Be Flattened”](findings/03-tracker-providers.md)). **Pewność: 90%, wysoka.** +4. **Local Markdown wymaga prawdziwego protokołu zapisu.** Zainstalowane skills używają sekwencyjnych numerów i edit-in-place; jednocześnie wayfinder dopuszcza równoległą pracę. Opaque ID + lock + expected revision + atomic replace usuwa największe ryzyka ([02-mattpocock-skills.md, „Weaknesses”](findings/02-mattpocock-skills.md); [04-product-quality-tradeoffs.md, „Local Markdown Persistence”](findings/04-product-quality-tradeoffs.md)). **Pewność: 90%, wysoka.** + +### 3.2 Sprzeczności i sposób ich zachowania + +| Sprzeczność | Dowód | Synteza | +|---|---|---| +| Pełny kontrakt mutation vs minimalny v1 | Category 3 rekomenduje CRUD/comments/labels/state; Category 4 ogranicza v1 UX do capture/list/show/handoff. | Ustalić pełne typy operacji kontraktu, lecz implementować i wystawiać tylko wywoływane operacje v1: capabilities, resolve, create, read, bounded list. Rozszerzać dopiero z callerem i testami. | +| Lokalny układ plików | Template: `.scratch//issues/NN-*.md`; `to-tickets`: jeden `tickets.md`. | Nie migrować automatycznie żadnego. Nowy kanoniczny root `.maister/issues/` i opaque IDs; stare layouty pozostają niezarządzane do jawnego importu. | +| Znaczenie `ready-for-agent` | `to-spec` i `to-tickets` nadają je automatycznie; `triage` wymaga autorytatywnego briefu. | W v1 traktować jako opcjonalną tracker-owned politykę wejścia, nie stan workflowu ani wymóg core handoff. | +| Stan workflowu | Dokumentacja/aktywny task używa `started_phase` + `orchestrator.phases`; runner testuje `current_phase` + root `phases`. | To blocker schematu `source_issue`; najpierw wybrać i fixture-testować jeden anchor, nie obsługiwać obu w providerze. | +| Trwałość quick-plan | Native plan na Claude/Codex; plik na Cursor/Kiro. | Rekomendować wspólny minimalny plan/provenance artifact, ale oznaczyć jako decyzję wymagającą zatwierdzenia przed implementacją. | + +## 4. Wymagania pochodne + +| ID | Wymaganie | Podstawa | Priorytet / pewność | +|---|---|---|---| +| R1 | Project-local, nie-sekretny config providerów z jednoznaczną precedence | Existing `.maister/config.yml`; installed repo-local config | Must / 92% | +| R2 | Capture ma tworzyć dokładnie jedno issue i zwracać pełny `IssueRef` | UX journeys + ambiguous commit analysis | Must / 90% | +| R3 | List/show/select są bounded, read-only, deterministic i wspierają JSON | Continuation stdout/stderr precedent | Must / 91% | +| R4 | Handoff rozwiązuje/refetchuje issue przed init, utrwala snapshot/revision/digest | State ownership triangulation | Must / 94% | +| R5 | Direct prose i task-path resume pozostają kompatybilne | Current workflow contracts | Must / 98% | +| R6 | Capability payload zawiera status, transport, permissions i constraints | Official provider divergence | Must / 90% | +| R7 | Typed errors rozróżniają invalid/ambiguous/auth/conflict/offline/rate/ambiguous commit | Official APIs + fail-closed standards | Must / 91% | +| R8 | Hosted writes nie przełączają transportu po dispatch bez reconciliation | Brak ogólnego idempotency key | Must / 85% | +| R9 | Local records mają opaque ID, strict metadata, atomic writes, locks i CAS | Concurrency analysis | Must / 90% | +| R10 | Issue content jest untrusted data; secrets są poza config/snapshot/log | OWASP + vendor auth docs | Must / 94% | +| R11 | Canonical edits trafiają do `plugins/maister/` i `platforms/`; generated variants tylko przez build | Project architecture/build standard | Must / 99% | +| R12 | GitLab/Jira/Linear wykorzystują ten sam seam bez implementowania ich w v1 | Capability matrix | Should / 86% | + +## 5. Porównanie opcji architektonicznych + +Skala 1–5; wyższa wartość jest lepsza. Oceny są rekomendacją porównawczą, nie pomiarem. + +| Kryterium | A. Prose/config instructions | B. Deklaratywny kontrakt wykonywany przez host | C. Helper wykonywalny + capabilities | +|---|---:|---:|---:| +| Prostota początkowa | 5 | 3 | 3 | +| Deterministyczna generacja | 2 | 4 | 5 | +| Rozszerzalność | 3 | 4 | 4 | +| Escape hatches providera | 5 | 3 | 4 | +| Walidacja/fail-closed | 1 | 3 | 5 | +| Testowalność | 1 | 3 | 5 | +| Bezpieczeństwo | 2 | 3 | 5 | +| Offline Local Markdown | 4 | 4 | 5 | +| Parzystość hostów | 2 | 3 | 5 | +| Koszt migracji | 5 | 4 | 3 | +| Minimalne zależności | 5 | 5 | 4 | + +**A — odrzucona jako sole architecture.** Dobra jako dokumentacja/escape hatch, lecz nie daje typów, atomowości ani walidacji. Bezpośredni dowód stanowią templates `mattpocock/skills` ([02-mattpocock-skills.md, „Implicit Provider Interface”](findings/02-mattpocock-skills.md)). **Pewność: 94%.** + +**B — niewystarczająca dla write path.** Deklarowanie command templates tworzy mały język programowania i powiela quoting/error semantics między hostami. Może uzupełniać C jako config, nie zastępować boundary. **Pewność: 82%.** + +**C — rekomendowana.** Jeden helper zapewnia exact JSON, fixed argv/API, local transactions, typed errors i mocks; skill pozostaje UX/orchestration. Node ESM jest już elementem tech stacku. **Pewność: 87%, ograniczona przez decyzje quick-plan i stan schema.** + +## 6. Rekomendowany model v1 + +### 6.1 Ścisła własność + +| Obszar | Tracker | Snapshot | Workflow/task | `orchestrator-state.yml` | +|---|---:|---:|---:|---:| +| Live title/body/comments/labels/assignees/dependencies | Tak | Wartości as-of capture | Nie | Nie | +| Canonical ref i URL/path | Tak | Dokładna użyta wartość | Link/pointer | Pointer + digest | +| Tracker status | Tak | As-of capture | Nie | Nie | +| Revision/capture time/digest | Bieżąca rewizja | Tak | Pliki source | Pointer/digest | +| Fazy/gates/attempts/decisions/verification | Nie | Nie | Artefakty | Wyłączna prawda resume | +| External mutation receipts | Provider/audit | Nie | Audyt operacji | Opcjonalny receipt, nigdy replika statusu | + +### 6.2 Canonical seam locations + +- `plugins/maister/skills/issue-tracker/SKILL.md` — publiczny UX configure/capture/list/show/select/start. +- `plugins/maister/skills/issue-tracker/bin/issue-tracker.mjs` — strict request/result boundary. +- `plugins/maister/skills/issue-tracker/references/issue-ref.md` — grammar i aliasy. +- `plugins/maister/skills/issue-tracker/providers/local.mjs` i `github.mjs` — v1 adapters; nazwy są rekomendacją. +- `.maister/config.yml` oraz `plugins/maister/skills/init/SKILL.md` — repozytoryjna konfiguracja i setup/upgrade. +- `plugins/maister/commands/work.md` + `plugins/maister/agents/task-classifier.md` — resolve raz, classify snapshot, przekazać ten sam snapshot dalej. +- `plugins/maister/skills/research/SKILL.md` przed initialization; `development/SKILL.md` przed utworzeniem state; `quick-plan/SKILL.md` i Cursor/Kiro overrides przed planning. +- `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` — wspólny typ `source_issue`, dopiero po ujednoliceniu state schema. +- `platforms/codex-cli/build.sh`, `platforms/cursor/build.sh`, `platforms/kiro-cli/build.sh` — tylko niezbędne transformacje, argument allowlists i packaging. + +Pełne uzasadnienie tych lokalizacji pochodzi z [01-maister-internals.md, „Seam Map”](findings/01-maister-internals.md). **Pewność: 86%.** + +## 7. Confidence i luki dowodowe + +| Konkluzja | Pewność | Uzasadnienie | +|---|---:|---| +| Rozdział tracker/workflow | 94% wysoka | Brief + architecture + cztery niezależne analizy. | +| Canonical/generated ownership | 99% wysoka | Dokumentacja, build scripts i testy platformowe. | +| Helper executable jako v1 | 87% średnia | Silny precedent lokalny; wybór architektoniczny, nie istniejąca implementacja. | +| `IssueRef` URI | 92% wysoka | Provider identity requirements + official scoping; dokładna składnia jest decyzją produktu. | +| GitHub v1 core | 93% wysoka | Aktualne oficjalne REST/CLI docs; brak real write testów. | +| Local atomic/concurrency protocol | 88% średnia | Silne precedensy i analiza, ale network filesystem/power-loss niezweryfikowane. | +| Quick-plan provenance | 76% średnia | Faktyczna rozbieżność hostów; brak zatwierdzonego wspólnego modelu. | +| Cała rekomendacja | 87% średnio-wysoka | Ograniczona przez state schema, quick-plan i mutation scope. | + +Nie przeprowadzono realnych zapisów do trackerów. GitLab/Jira/Linear zostały ocenione z aktualnej oficjalnej dokumentacji, ale nie mają lokalnych conformance tests. Brak ogólnego idempotency key w przejrzanych create endpoints jest evidence-of-absence, nie dowodem absolutnym ([03-tracker-providers.md, „Idempotency and concurrency”](findings/03-tracker-providers.md)). diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/dashboard-data.js b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/dashboard-data.js new file mode 100644 index 00000000..cd2397f0 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/dashboard-data.js @@ -0,0 +1,37 @@ +window.MAISTER_DATA = { + generated: "2026-07-13T16:16:12Z", + task: { + title: "Issue tracker workflow for Maister", + type: "research", + status: "completed", + description: "Research selectable issue trackers, fast task capture, and issue-to-workflow handoff.", + path: ".maister/tasks/research/2026-07-13-issue-tracker-workflow", + current_activity: null + }, + characteristics: { research_type: "mixed" }, + phases: [ + { id: "phase-1", name: "Research foundation", icon_hint: "analysis", status: "completed", started: "2026-07-13T13:53:40Z", completed: "2026-07-13T14:38:08Z", skip_reason: null, summary: "Research recommends an executable provider helper plus declarative capabilities, with Local Markdown and GitHub in v1 and immutable snapshots handed into workflows.", decisions: [{ decision: "Wybrać helper wykonywalny + deklaratywne capabilities, nie prose-as-provider-API.", rationale: "Zapewnia jeden walidowany kontrakt i ogranicza różnice między hostami." }, { decision: "Utrwalać maister-issue://...; przyjmować krótsze aliasy wyłącznie, gdy rozstrzygają się jednoznacznie.", rationale: "Referencje pozostają stabilne między providerami." }, { decision: "Rozwiązać i zsnapshotować issue przed utworzeniem workflow state; późniejszy drift tylko sygnalizować.", rationale: "Workflow pozostaje odtwarzalny, a tracker zachowuje żywy backlog." }, { decision: "W v1 wdrożyć Local Markdown i GitHub; zostawić GitLab/Jira/Linear bez pustych stubów.", rationale: "Ogranicza zakres i respektuje minimalną implementację." }], risks: ["Sprzeczny schemat orchestrator-state.yml blokuje wybór jednego kanonicznego miejsca dla source_issue.", "quick-plan ma różną trwałość na hostach; wspólny artifact proweniencji wymaga decyzji produktowej.", "Zakres mutacji trackera w v1 nie jest zatwierdzony.", "Local locks/atomic replace wymagają jasno zadeklarowanego wsparcia zwykłych lokalnych filesystemów."], artifacts: [{ path: "planning/research-brief.md", label: "Research Brief", html: null }, { path: "planning/research-plan.md", label: "Research Plan", html: null }, { path: "planning/sources.md", label: "Source Register", html: null }, { path: "analysis/findings/01-maister-internals.md", label: "Maister Internals", html: null }, { path: "analysis/findings/02-mattpocock-skills.md", label: "mattpocock/skills Prior Art", html: null }, { path: "analysis/findings/03-tracker-providers.md", label: "Tracker Provider Contracts", html: null }, { path: "analysis/findings/04-product-quality-tradeoffs.md", label: "Product Quality Trade-offs", html: null }, { path: "analysis/synthesis.md", label: "Research Synthesis", html: null }, { path: "outputs/research-report.md", label: "Research Report", html: "outputs/research-report.html" }, { path: "outputs/decision-summary.md", label: "Decision Summary", html: "outputs/decision-summary.html" }], gate: { question: "Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation?", answer: "Pause workflow", status: "decided" } }, + { id: "phase-2", name: "Evaluate brainstorming value", icon_hint: "plan", status: "completed", started: "2026-07-13T14:59:02Z", completed: "2026-07-13T15:05:17Z", skip_reason: null, summary: "Brainstorming and high-level design were both enabled after advisor-backed recommendations.", decisions: [{ decision: "Enable brainstorming", rationale: "The user accepted the advisor-backed recommendation to explore material architectural trade-offs." }, { decision: "Enable high-level design", rationale: "The user authorized following the advisor when it confirms the original recommendation." }], risks: [], artifacts: [], gate: { question: "The research identifies architectural decisions that would directly feed development. Would you like to generate a high-level design?", answer: "Yes, generate design", status: "decided" } }, + { id: "phase-3", name: "Generate solution alternatives", icon_hint: "spec", status: "completed", started: "2026-07-13T15:05:17Z", completed: "2026-07-13T15:17:32Z", skip_reason: null, summary: "Six sequential decision areas compare 18 alternatives and recommend an executable helper, root provenance, durable plans, capture-only mutations, transactional Local Markdown, and Local-first delivery.", decisions: [{ decision: "Executable Node ESM helper + CapabilitySet", rationale: "Host parity, fail-closed validation, and testability." }, { decision: "Root source_issue + immutable snapshot", rationale: "Separates live tracker ownership from reproducible workflow input." }, { decision: "Durable cross-host quick-plan artifact", rationale: "Creates one canonical handoff." }, { decision: "Capture-only v1 mutations", rationale: "Keeps handoff read-only and bounds risk." }, { decision: "Local Markdown first, GitHub second", rationale: "Stabilizes the conformance contract before hosted integration." }], risks: ["State schema variants must be unified before source_issue.", "Local transaction assumptions exclude network filesystems.", "GitHub timeout after dispatch can be an ambiguous commit.", "Durable quick-plan needs cross-host parity tests."], artifacts: [{ path: "outputs/solution-exploration.md", label: "Solution Exploration", html: "outputs/solution-exploration.html" }], gate: { question: "Continue to solution convergence?", answer: "Continue to solution convergence", status: "decided" } }, + { id: "phase-4", name: "Evaluate brainstorming alternatives", icon_hint: "plan", status: "completed", started: "2026-07-13T15:17:32Z", completed: "2026-07-13T15:51:06Z", skip_reason: null, summary: "All six convergence areas are resolved into an incremental provider architecture; the workflow is paused before high-level design.", decisions: [{ decision: "Choose a small Node ESM helper with exact JSON and a declarative CapabilitySet.", rationale: "It provides the strongest host parity, fail-closed validation, and testability." }, { decision: "Anchor source_issue at the root of orchestrator-state.yml after schema unification.", rationale: "It preserves one resume and audit source of truth." }, { decision: "Persist quick-plan in .maister/plans/*.md on every host.", rationale: "It provides a portable, Git-reviewable handoff." }, { decision: "Limit v1 mutations to explicit capture/create.", rationale: "It bounds side effects and keeps handoff and resume read-only." }, { decision: "Use UUID records, per-record locks, CAS, and atomic replace for Local Markdown.", rationale: "It prevents lost updates while preserving readable files." }, { decision: "Deliver Local Markdown first and GitHub second.", rationale: "It creates small verifiable increments over one conformance contract." }], risks: ["Codex fully_automatic remains unsupported because the host-native adapter/E2E is absent and the workflow state schema diverges from the runner contract."], artifacts: [{ path: "analysis/codex-fully-automatic-diagnosis.md", label: "Codex Fully Automatic Diagnosis", html: null }], gate: { question: "Brainstorming complete. Continue to high-level design?", answer: "Pause workflow", status: "decided" } }, + { id: "phase-5", name: "Design high-level architecture", icon_hint: "spec", status: "completed", started: "2026-07-13T15:55:19Z", completed: "2026-07-13T16:11:56Z", skip_reason: null, summary: "A layered provider boundary with immutable handoff snapshots separates live tracker ownership from reproducible workflow input; six ADRs make the design development-ready.", decisions: [{ decision: "Use one executable provider boundary instead of prose-only adapters or a command-template DSL.", rationale: "This centralizes validation, redaction, and cross-host semantics (ADR-001)." }, { decision: "Keep tracker data and workflow execution state under separate ownership, with root source_issue provenance after state-schema unification.", rationale: "This preserves tracker and workflow authority boundaries (ADR-002)." }, { decision: "Persist quick plans as portable Markdown artifacts on every host and treat native plan UI as a projection.", rationale: "This produces one durable cross-host handoff (ADR-003)." }, { decision: "Limit v1 mutations to explicit capture/create; handoff, resume, and drift checks remain read-only.", rationale: "This bounds side effects and operational risk (ADR-004)." }, { decision: "Give Local Markdown per-UUID records, per-record locks, compare-and-swap, and atomic replace only on ordinary local filesystems.", rationale: "This prevents lost updates within the supported filesystem boundary (ADR-005)." }, { decision: "Deliver Local Markdown first and GitHub second under the same conformance contract.", rationale: "This stabilizes the provider seam incrementally (ADR-006)." }], risks: ["The competing workflow-state schemas must be unified and fixture-tested before adding the root source_issue field; dual-read behavior is not part of this design.", "Local filesystem guarantees do not extend to network or distributed filesystems; unsupported environments must fail preflight with an actionable diagnostic.", "A GitHub create timeout after dispatch may remain ambiguous_commit; v1 must not blindly retry or switch transport.", "Cross-host fixtures must prove that canonical quick-plan content and native UI projections cannot silently diverge.", "Fully automatic Codex continuation remains unsupported until a host-native adapter, unified state schema, and end-to-end verification exist."], artifacts: [{ path: "outputs/high-level-design.md", label: "High-Level Design", html: "outputs/high-level-design.html" }, { path: "outputs/decision-log.md", label: "Decision Log", html: "outputs/decision-log.html" }], gate: { question: "Design complete. Continue to output generation?", answer: "Continue to output generation", status: "decided" } }, + { id: "phase-6", name: "Summarize research and suggest next steps", icon_hint: "done", status: "completed", started: "2026-07-13T16:11:56Z", completed: "2026-07-13T16:16:12Z", skip_reason: null, summary: "The complete research package is approved for final handoff, with five linked deliverables and the remaining prerequisites preserved.", decisions: [], risks: ["Workflow-state schema unification remains a prerequisite for root source_issue provenance.", "Codex automatic continuation remains unsupported until host-native end-to-end validation passes."], artifacts: [{ path: "outputs/research-report.md", label: "Research Report", html: "outputs/research-report.html" }, { path: "outputs/solution-exploration.md", label: "Solution Exploration", html: "outputs/solution-exploration.html" }, { path: "outputs/high-level-design.md", label: "High-Level Design", html: "outputs/high-level-design.html" }, { path: "outputs/decision-log.md", label: "Decision Log", html: "outputs/decision-log.html" }, { path: "outputs/decision-summary.md", label: "Decision Summary", html: "outputs/decision-summary.html" }], gate: { question: "Research outputs are complete. Approve the final handoff?", answer: "Complete workflow", status: "decided" } } + ], + verification: { status: null, issues: [], fixes: [], reverify_count: 0 }, + gate_history: [ + { idempotency_key: "sha256:8dc80ac772693c815f0dfac96f7baa45a3cded3e406f16c6f5a42756f1e157d4", phase_id: "phase-1", gate_type: "phase-1-exit", status: "decided", question: "Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation?", selected_option: "Pause workflow", final_actor: "user", rationale: "User explicitly chose to pause after reviewing the completed research foundation.", confidence: "high", user_override: true }, + { idempotency_key: "sha256:ef97f9b46a7c28e4c418e8abf667877f80fd953dacc6d142349fdfd47b1e72e6", phase_id: "phase-2", gate_type: "optional-phase-selection", status: "decided", question: "Multiple viable architectures and competing trade-offs make brainstorming valuable. Would you like to explore solution alternatives?", selected_option: "Yes, explore alternatives", final_actor: "user", rationale: "User accepted the recommendation to explore alternatives because the research contains material competing architectural trade-offs.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:571789075d8fe42ced95941597dca774808f00995f22ba6b6bf6ea6a477cf575", phase_id: "phase-2", gate_type: "optional-phase-selection", status: "decided", question: "The research identifies architectural decisions that would directly feed development. Would you like to generate a high-level design?", selected_option: "Yes, generate design", final_actor: "user", rationale: "User authorized following advisor recommendations that agree with the original recommendation, confirming generation of the high-level design.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:b44cce49b270e039db9825c224697b82b1f7ac236d4a1a361cd36e21a6e3cd13", phase_id: "phase-3", gate_type: "phase-3-exit", status: "decided", question: "Continue to solution convergence?", selected_option: "Continue to solution convergence", final_actor: "user", rationale: "User chose to continue from solution generation to sequential convergence.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:8b8e6268eadeea8e9075d04f18884ea11c39055775dd1d52df2849b6bd0c2af6", phase_id: "phase-4", gate_type: "research-convergence", status: "decided", question: "Which provider execution boundary should Maister use?", selected_option: "1C — mały helper Node ESM i deklaratywny CapabilitySet (Recommended)", final_actor: "user", rationale: "User selected the executable Node ESM helper and declarative CapabilitySet as the shared provider execution boundary.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:1405b0df3ba973ffe77cf109cf542cc3b69b3d0c709d74780c3d6c6c2206be62", phase_id: "phase-4", gate_type: "research-convergence", status: "decided", question: "Where should canonical source_issue provenance be anchored?", selected_option: "2A — korzeniowy source_issue w orchestrator-state.yml (Recommended)", final_actor: "user", rationale: "User selected a root source_issue provenance pointer in orchestrator-state.yml after schema unification.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:6420d393ee515436120df4c9fc4ee3237a536c22f59202bc3af214652b88006b", phase_id: "phase-4", gate_type: "research-convergence", status: "decided", question: "How should quick-plan provenance persist across hosts?", selected_option: "3B — wspólny .maister/plans/*.md plus native UI (Recommended)", final_actor: "user", rationale: "User selected a durable cross-host quick-plan artifact with native UI as a projection.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:2d424dd21881954ddefce454a09a7a06999e6b8804b6a11a5464d25f1abcaad2", phase_id: "phase-4", gate_type: "research-convergence", status: "decided", question: "Which tracker mutation surface should v1 expose?", selected_option: "4A — tylko jawne capture/create (Recommended)", final_actor: "user", rationale: "User limited v1 tracker mutations to explicit capture/create.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:eaaf8832a0e880c6b34925b886e016307a54722d2672df5fd5e37f6ee2f43863", phase_id: "phase-4", gate_type: "research-convergence", status: "decided", question: "Which persistence protocol should Local Markdown use?", selected_option: "5A — rekord per UUID, per-record lock, CAS i atomic replace (Recommended)", final_actor: "user", rationale: "User selected UUID records with per-record locks, CAS, and atomic replace.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:2e2af5cd201403e231f02eb0b77f59014f873fb8d3539b80647f50fb1615a7f6", phase_id: "phase-4", gate_type: "research-convergence", status: "decided", question: "In what order should v1 deliver tracker providers?", selected_option: "6B — Local Markdown tracer, następnie GitHub (Recommended)", final_actor: "user", rationale: "User selected Local Markdown first and GitHub second over the same conformance contract.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:deff7dc9407e4bf7bd8e9827eea83f0943d11d5daa1793b43db636eb584db001", phase_id: "phase-4", gate_type: "phase-4-exit", status: "decided", question: "Brainstorming complete. Continue to high-level design?", selected_option: "Pause workflow", final_actor: "user", rationale: "User chose to pause after completing all six convergence decisions and before high-level design.", confidence: "high", user_override: true }, + { idempotency_key: "sha256:d2d155b8dc6dc759724bbddbe3f5de77683741a654c0091310ef6e2f95fa31d6", phase_id: "phase-5", gate_type: "research-clarification", status: "decided", question: "The six convergence decisions establish the design direction. Should the high-level design proceed with those assumptions unchanged?", selected_option: "Confirm assumptions", final_actor: "user", rationale: "User confirmed that the high-level design should proceed with the six converged assumptions unchanged.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:6bdf08499f5ea52adcb109887df08612b87fed5c1a2a6ba779d4fc70c9cb160e", phase_id: "phase-5", gate_type: "phase-5-exit", status: "decided", question: "Design complete. Continue to output generation?", selected_option: "Continue to output generation", final_actor: "user", rationale: "User chose to continue from the verified high-level design to final output generation.", confidence: "high", user_override: false }, + { idempotency_key: "sha256:283ebe0a6247edeaaddef3b7647f654d966aa190da4ee71b2f961b3dd18d2825", phase_id: "phase-6", gate_type: "final-handoff-approval", status: "decided", question: "Research outputs are complete. Approve the final handoff?", selected_option: "Complete workflow", final_actor: "user", rationale: "User approved the final research handoff and completion of the workflow.", confidence: "high", user_override: false } + ] +}; diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/dashboard.html b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/dashboard.html new file mode 100644 index 00000000..9f5ea812 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/dashboard.html @@ -0,0 +1,629 @@ + + + + + +Maister Workflow Dashboard + + + + +
+
+ Waiting for dashboard-data.js… If this persists, the workflow has not written data yet. +
+
+ + + + diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/orchestrator-state.yml b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/orchestrator-state.yml new file mode 100644 index 00000000..52a1f863 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/orchestrator-state.yml @@ -0,0 +1,911 @@ +orchestrator: + started_phase: phase-1 + completed_phases: [phase-1, phase-2, phase-3, phase-4, phase-5, phase-6] + failed_phases: [] + auto_fix_attempts: + phase-1: 0 + phase-2: 0 + phase-3: 0 + phase-4: 0 + phase-5: 0 + phase-6: 0 + options: + html_output: true + brainstorming_enabled: true + design_enabled: true + advisor: + enabled: true + gate_policies: + phase-exit: fully_automatic + optional-phase: fully_automatic + clarify: fully_automatic + convergence: fully_automatic + verify-matrix: fully_automatic + advisor_agent: advisor + advisor_model: gpt-5.6-sol + arbiter_agent: arbiter + arbiter_model: gpt-5.6-sol + arbiter_enabled_on_disagreement: true + retry: + advisor_attempts: 3 + arbiter_attempts: 3 + backoff: exponential + created: "2026-07-13T13:53:40Z" + updated: "2026-07-13T16:16:12Z" + task_path: .maister/tasks/research/2026-07-13-issue-tracker-workflow + task_ids: + phase-1: research-phase-1 + phase-2: research-phase-2 + phase-3: research-phase-3 + phase-4: research-phase-4 + phase-5: research-phase-5 + phase-6: research-phase-6 + gate_history: + - schema_version: 1 + idempotency_key: sha256:8dc80ac772693c815f0dfac96f7baa45a3cded3e406f16c6f5a42756f1e157d4 + phase_id: phase-1 + gate_type: phase-1-exit + question: Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? + options: + - Continue to brainstorming evaluation + - Pause workflow + policy: advisor + safety_classification: configurable + status: decided + selected_option: Pause workflow + final_actor: user + original_recommendation: Continue to brainstorming evaluation + advisor: + agent: advisor + model: null + response: null + attempts: + - actor: advisor + attempt: 1 + started_at: "2026-07-13T14:31:56Z" + finished_at: "2026-07-13T14:33:12Z" + status: unavailable + raw_response: "The 'inherit' model is not supported when using Codex with a ChatGPT account." + validation_errors: + - Advisor role could not start with the configured inherited model. + backoff: + strategy: exponential + delay_ms: 1000 + scheduled_at: "2026-07-13T14:33:12Z" + completed_at: "2026-07-13T14:33:13Z" + - actor: advisor + attempt: 2 + started_at: "2026-07-13T14:33:13Z" + finished_at: "2026-07-13T14:33:52Z" + status: unavailable + raw_response: "The 'inherit' model is not supported when using Codex with a ChatGPT account." + validation_errors: + - Advisor role could not start with the configured inherited model. + backoff: + strategy: exponential + delay_ms: 2000 + scheduled_at: "2026-07-13T14:33:52Z" + completed_at: "2026-07-13T14:33:54Z" + - actor: advisor + attempt: 3 + started_at: "2026-07-13T14:33:54Z" + finished_at: "2026-07-13T14:34:29Z" + status: unavailable + raw_response: "The 'inherit' model is not supported when using Codex with a ChatGPT account." + validation_errors: + - Advisor role could not start with the configured inherited model. + backoff: + strategy: exponential + delay_ms: 0 + scheduled_at: null + completed_at: null + exhausted: true + arbiter: + agent: advisor + model: null + response: null + attempts: [] + exhausted: false + rationale: User explicitly chose to pause after reviewing the completed research foundation. + confidence: high + escalate_to_user: false + user_override: true + error: null + - schema_version: 1 + idempotency_key: sha256:ef97f9b46a7c28e4c418e8abf667877f80fd953dacc6d142349fdfd47b1e72e6 + phase_id: phase-2 + gate_type: optional-phase-selection + question: Multiple viable architectures and competing trade-offs make brainstorming valuable. Would you like to explore solution alternatives? + options: + - Yes, explore alternatives + - No, skip brainstorming + policy: advisor + safety_classification: configurable + status: decided + selected_option: Yes, explore alternatives + final_actor: user + original_recommendation: Yes, explore alternatives + advisor: + agent: advisor + model: gpt-5.6-sol + response: + selected_option: Yes, explore alternatives + rationale: The research identifies multiple architectural seams and unresolved trade-offs—including state-schema compatibility, host-specific persistence, mutation scope, and filesystem concurrency—so comparing alternatives is likely to materially improve the recommendation before implementation. + confidence: high + escalate_to_user: false + attempts: + - actor: advisor + attempt: 1 + started_at: "2026-07-13T14:59:02Z" + finished_at: "2026-07-13T15:00:02Z" + status: valid + raw_response: |- + selected_option: "Yes, explore alternatives" + rationale: "The research identifies multiple architectural seams and unresolved trade-offs—including state-schema compatibility, host-specific persistence, mutation scope, and filesystem concurrency—so comparing alternatives is likely to materially improve the recommendation before implementation." + confidence: high + escalate_to_user: false + validation_errors: [] + backoff: + strategy: exponential + delay_ms: 0 + scheduled_at: null + completed_at: null + exhausted: false + arbiter: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User accepted the recommendation to explore alternatives because the research contains material competing architectural trade-offs. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b44cce49b270e039db9825c224697b82b1f7ac236d4a1a361cd36e21a6e3cd13 + phase_id: phase-3 + gate_type: phase-3-exit + question: Continue to solution convergence? + options: + - Continue to solution convergence + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to solution convergence + final_actor: user + original_recommendation: Continue to solution convergence + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User chose to continue from solution generation to sequential convergence. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:8b8e6268eadeea8e9075d04f18884ea11c39055775dd1d52df2849b6bd0c2af6 + phase_id: phase-4 + gate_type: research-convergence + question: Which provider execution boundary should Maister use? + options: + - 1A — instrukcje prose i bezpośrednie narzędzia hosta + - 1B — deklaratywne command templates wykonywane przez host + - 1C — mały helper Node ESM i deklaratywny CapabilitySet (Recommended) + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 1C — mały helper Node ESM i deklaratywny CapabilitySet (Recommended) + final_actor: user + original_recommendation: 1C — mały helper Node ESM i deklaratywny CapabilitySet (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected the executable Node ESM helper and declarative CapabilitySet as the shared provider execution boundary. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:1405b0df3ba973ffe77cf109cf542cc3b69b3d0c709d74780c3d6c6c2206be62 + phase_id: phase-4 + gate_type: research-convergence + question: Where should canonical source_issue provenance be anchored? + options: + - 2A — korzeniowy source_issue w orchestrator-state.yml (Recommended) + - 2B — authoritative intake manifest poza state + - 2C — workflow-specific source fields + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 2A — korzeniowy source_issue w orchestrator-state.yml (Recommended) + final_actor: user + original_recommendation: 2A — korzeniowy source_issue w orchestrator-state.yml (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected a root source_issue provenance pointer in orchestrator-state.yml, contingent on unifying and fixture-testing the canonical state schema. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:6420d393ee515436120df4c9fc4ee3237a536c22f59202bc3af214652b88006b + phase_id: phase-4 + gate_type: research-convergence + question: How should quick-plan provenance persist across hosts? + options: + - 3A — tylko native plan hosta + - 3B — wspólny .maister/plans/*.md plus native UI (Recommended) + - 3C — centralny registry proweniencji bez trwałego planu + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 3B — wspólny .maister/plans/*.md plus native UI (Recommended) + final_actor: user + original_recommendation: 3B — wspólny .maister/plans/*.md plus native UI (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected a durable cross-host .maister/plans/*.md artifact as the canonical quick-plan handoff, with native UI as a projection. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:2d424dd21881954ddefce454a09a7a06999e6b8804b6a11a5464d25f1abcaad2 + phase_id: phase-4 + gate_type: research-convergence + question: Which tracker mutation surface should v1 expose? + options: + - 4A — tylko jawne capture/create (Recommended) + - 4B — capture plus comment/claim/transition za approval + - 4C — pełna synchronizacja statusu workflow ↔ tracker + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 4A — tylko jawne capture/create (Recommended) + final_actor: user + original_recommendation: 4A — tylko jawne capture/create (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User limited v1 tracker mutations to explicit capture/create; handoff, resume, and read flows remain non-mutating. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:eaaf8832a0e880c6b34925b886e016307a54722d2672df5fd5e37f6ee2f43863 + phase_id: phase-4 + gate_type: research-convergence + question: Which persistence protocol should Local Markdown use? + options: + - 5A — rekord per UUID, per-record lock, CAS i atomic replace (Recommended) + - 5B — append-only journal z materializowaną projekcją + - 5C — Git-only optimistic concurrency + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 5A — rekord per UUID, per-record lock, CAS i atomic replace (Recommended) + final_actor: user + original_recommendation: 5A — rekord per UUID, per-record lock, CAS i atomic replace (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected per-UUID records with per-record locking, CAS, and atomic replace, bounded to ordinary local filesystems. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:2e2af5cd201403e231f02eb0b77f59014f873fb8d3539b80647f50fb1615a7f6 + phase_id: phase-4 + gate_type: research-convergence + question: In what order should v1 deliver tracker providers? + options: + - 6A — Local Markdown i GitHub w jednym release + - 6B — Local Markdown tracer, następnie GitHub (Recommended) + - 6C — uniwersalny provider SDK przed konkretnymi providerami + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 6B — Local Markdown tracer, następnie GitHub (Recommended) + final_actor: user + original_recommendation: 6B — Local Markdown tracer, następnie GitHub (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected an incremental delivery sequence with Local Markdown as the first tracer and GitHub as the second tracer over the same conformance contract. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:deff7dc9407e4bf7bd8e9827eea83f0943d11d5daa1793b43db636eb584db001 + phase_id: phase-4 + gate_type: phase-4-exit + question: Brainstorming complete. Continue to high-level design? + options: + - Continue to high-level design + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Pause workflow + final_actor: user + original_recommendation: Continue to high-level design + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User chose to pause after completing all six convergence decisions and before high-level design. + confidence: high + escalate_to_user: false + user_override: true + error: null + - schema_version: 1 + idempotency_key: sha256:571789075d8fe42ced95941597dca774808f00995f22ba6b6bf6ea6a477cf575 + phase_id: phase-2 + gate_type: optional-phase-selection + question: The research identifies architectural decisions that would directly feed development. Would you like to generate a high-level design? + options: + - Yes, generate design + - No, skip design + policy: advisor + safety_classification: configurable + status: decided + selected_option: Yes, generate design + final_actor: user + original_recommendation: Yes, generate design + advisor: + agent: advisor + model: gpt-5.6-sol + response: + selected_option: Yes, generate design + rationale: The research has established a concrete direction but leaves important interface, state-management, provider-boundary, and concurrency decisions unresolved; a high-level design will convert those findings and the enabled alternatives analysis into development-ready architectural guidance. + confidence: high + escalate_to_user: false + attempts: + - actor: advisor + attempt: 1 + started_at: "2026-07-13T15:02:56Z" + finished_at: "2026-07-13T15:03:48Z" + status: valid + raw_response: |- + selected_option: "Yes, generate design" + rationale: "The research has established a concrete direction but leaves important interface, state-management, provider-boundary, and concurrency decisions unresolved; a high-level design will convert those findings and the enabled alternatives analysis into development-ready architectural guidance." + confidence: high + escalate_to_user: false + validation_errors: [] + backoff: + strategy: exponential + delay_ms: 0 + scheduled_at: null + completed_at: null + exhausted: false + arbiter: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User authorized following advisor recommendations that agree with the original recommendation, confirming generation of the high-level design. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:d2d155b8dc6dc759724bbddbe3f5de77683741a654c0091310ef6e2f95fa31d6 + phase_id: phase-5 + gate_type: research-clarification + question: The six convergence decisions establish the design direction. Should the high-level design proceed with those assumptions unchanged? + options: + - Confirm assumptions + - Correct assumptions + - Provide more context + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Confirm assumptions + final_actor: user + original_recommendation: Confirm assumptions + advisor: + agent: advisor + model: gpt-5.6-sol + response: + selected_option: Confirm assumptions + rationale: The six decisions are mutually consistent, respect the stated architectural constraints, keep orchestrator-state.yml authoritative, avoid provider coupling, and define a bounded v1 with explicit filesystem and platform limitations. The high-level design can proceed unchanged. + confidence: high + escalate_to_user: false + attempts: + - actor: advisor + attempt: 1 + started_at: "2026-07-13T15:55:19Z" + finished_at: "2026-07-13T15:56:25Z" + status: valid + raw_response: |- + selected_option: "Confirm assumptions" + rationale: "The six decisions are mutually consistent, respect the stated architectural constraints, keep orchestrator-state.yml authoritative, avoid provider coupling, and define a bounded v1 with explicit filesystem and platform limitations. The high-level design can proceed unchanged." + confidence: high + escalate_to_user: false + validation_errors: [] + backoff: + strategy: exponential + delay_ms: 0 + scheduled_at: null + completed_at: null + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed that the high-level design should proceed with the six converged assumptions unchanged. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:6bdf08499f5ea52adcb109887df08612b87fed5c1a2a6ba779d4fc70c9cb160e + phase_id: phase-5 + gate_type: phase-5-exit + question: Design complete. Continue to output generation? + options: + - Continue to output generation + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to output generation + final_actor: user + original_recommendation: Continue to output generation + advisor: + agent: advisor + model: gpt-5.6-sol + response: + selected_option: Continue to output generation + rationale: Phase 5 completed successfully, required design artifacts and checks are present, known risks and prerequisites are explicitly preserved, and Phase 6 only packages the validated findings into final outputs. + confidence: high + escalate_to_user: false + attempts: + - actor: advisor + attempt: 1 + started_at: "2026-07-13T16:08:21Z" + finished_at: "2026-07-13T16:09:46Z" + status: valid + raw_response: |- + selected_option: "Continue to output generation" + rationale: "Phase 5 completed successfully, required design artifacts and checks are present, known risks and prerequisites are explicitly preserved, and Phase 6 only packages the validated findings into final outputs." + confidence: high + escalate_to_user: false + validation_errors: [] + backoff: + strategy: exponential + delay_ms: 0 + scheduled_at: null + completed_at: null + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User chose to continue from the verified high-level design to final output generation. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:283ebe0a6247edeaaddef3b7647f654d966aa190da4ee71b2f961b3dd18d2825 + phase_id: phase-6 + gate_type: final-handoff-approval + question: Research outputs are complete. Approve the final handoff? + options: + - Complete workflow + - Keep workflow open + policy: manual + safety_classification: denylisted + status: decided + selected_option: Complete workflow + final_actor: user + original_recommendation: Complete workflow + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User approved the final research handoff and completion of the workflow. + confidence: high + escalate_to_user: false + user_override: false + error: null + implementation_approval: + status: not_required + approved_by: null + approved_at: null + approved_scope: [] + phases: + - id: phase-1 + name: Research foundation + status: completed + active_form: Executing research foundation + icon_hint: analysis + blocked_by: [] + started: "2026-07-13T13:53:40Z" + completed: "2026-07-13T14:38:08Z" + gate: + question: Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? + answer: Pause workflow + status: decided + - id: phase-2 + name: Evaluate brainstorming value + status: completed + active_form: Evaluating brainstorming value + icon_hint: plan + blocked_by: [phase-1] + started: "2026-07-13T14:59:02Z" + completed: "2026-07-13T15:05:17Z" + gate: + question: The research identifies architectural decisions that would directly feed development. Would you like to generate a high-level design? + answer: Yes, generate design + status: decided + - id: phase-3 + name: Generate solution alternatives + status: completed + active_form: Generating solution alternatives + icon_hint: spec + blocked_by: [phase-2] + started: "2026-07-13T15:05:17Z" + completed: "2026-07-13T15:17:32Z" + gate: + question: Continue to solution convergence? + answer: Continue to solution convergence + status: decided + - id: phase-4 + name: Evaluate brainstorming alternatives + status: completed + active_form: Evaluating brainstorming alternatives + icon_hint: plan + blocked_by: [phase-3] + started: "2026-07-13T15:17:32Z" + completed: "2026-07-13T15:51:06Z" + gate: + question: Brainstorming complete. Continue to high-level design? + answer: Pause workflow + status: decided + - id: phase-5 + name: Design high-level architecture + status: completed + active_form: Designing high-level architecture + icon_hint: spec + blocked_by: [phase-2, phase-4] + started: "2026-07-13T15:55:19Z" + completed: "2026-07-13T16:11:56Z" + gate: + question: Design complete. Continue to output generation? + answer: Continue to output generation + status: decided + - id: phase-6 + name: Summarize research and suggest next steps + status: completed + active_form: Completing research + icon_hint: done + blocked_by: [phase-2, phase-3, phase-4, phase-5] + started: "2026-07-13T16:11:56Z" + completed: "2026-07-13T16:16:12Z" + gate: + question: Research outputs are complete. Approve the final handoff? + answer: Complete workflow + status: decided + +task: + title: Issue tracker workflow for Maister + description: >- + Research the best way to add selectable issue-tracker support (local Markdown, + GitHub, and extensible providers), quick task capture, and handoff from a saved + issue into normal Maister research, planning, and development workflows. Treat + the installed mattpocock/skills implementation as a reference. + status: completed + tags: [research, issue-tracker, workflow, integration] + priority: null + +research_context: + research_type: mixed + research_question: >- + How should Maister add configurable issue-tracker providers, fast task capture, + and issue-to-workflow handoff while reusing good ideas from mattpocock/skills? + scope: + included: + - Existing Maister architecture, commands, task state, and platform adapters + - Installed mattpocock/skills tracker conventions and ticket workflows + - Local Markdown, GitHub Issues, and an extensible provider seam + - User experience for capture, listing, selection, and workflow handoff + - Compatibility with research, quick-plan, and development workflows + - Testing, migration, security, and multi-platform concerns + excluded: + - Implementing the feature during this research workflow + - Selecting a tracker for the current repository + - Building a hosted issue-tracking service + constraints: + - Preserve orchestrator-state.yml as the source of truth for workflow phase state + - Keep canonical edits under plugins/maister and generate platform variants + - Avoid coupling core workflows to a single external tracker + methodology: + - Technical iterative deepening + - Requirements extraction + - Comparative literature review + - Multi-source triangulation + sources: + - Maister canonical plugin, adapters, tests, and project documentation + - Installed mattpocock/skills files and tracker templates + - Current official GitHub, GitLab, Jira Cloud, Linear, and OWASP documentation + confidence_level: medium + gathering_strategy: + categories: + - maister-internals + - mattpocock-skills + - tracker-providers + - product-quality-tradeoffs + count: 4 + source: planner + project_doc_paths: + - .maister/docs/project/vision.md + - .maister/docs/project/roadmap.md + - .maister/docs/project/tech-stack.md + - .maister/docs/project/architecture.md + phase_summaries: + phase-1: + summary: Research recommends a canonical issue-tracker skill backed by a small executable provider helper, with Local Markdown and GitHub in v1 and immutable issue snapshots handed into existing workflows. + steps_completed: [initialize, plan, gather, synthesize] + decisions: + - decision: Wybrać helper wykonywalny + deklaratywne capabilities, nie prose-as-provider-API. + rationale: Zapewnia jeden walidowany kontrakt i ogranicza różnice między hostami. + - decision: Utrwalać maister-issue://...; przyjmować krótsze aliasy wyłącznie, gdy rozstrzygają się jednoznacznie. + rationale: Referencje pozostają stabilne i jednoznaczne między providerami oraz repozytoriami. + - decision: Rozwiązać i zsnapshotować issue przed utworzeniem workflow state; późniejszy drift tylko sygnalizować. + rationale: Workflow pozostaje odtwarzalny, a tracker zachowuje własność nad żywym backlogiem. + - decision: W v1 wdrożyć Local Markdown i GitHub; zostawić GitLab/Jira/Linear za tym samym kontraktem, bez pustych stubów. + rationale: Ogranicza zakres i respektuje standard minimalnej implementacji. + risks: + - Sprzeczny schemat orchestrator-state.yml blokuje wybór jednego kanonicznego miejsca dla source_issue. + - quick-plan ma różną trwałość na hostach; rekomendowany wspólny artifact proweniencji wymaga decyzji produktowej. + - Nie jest zatwierdzone, czy v1 ma udostępniać tracker mutations poza create; raport rekomenduje osobny późniejszy etap. + - Local locks/atomic replace wymagają jasno zadeklarowanego wsparcia zwykłych lokalnych filesystemów; konflikty Git pozostają manualne. + artifacts: + - path: planning/research-brief.md + label: Research Brief + html: null + - path: planning/research-plan.md + label: Research Plan + html: null + - path: planning/sources.md + label: Source Register + html: null + - path: analysis/findings/01-maister-internals.md + label: Maister Internals + html: null + - path: analysis/findings/02-mattpocock-skills.md + label: mattpocock/skills Prior Art + html: null + - path: analysis/findings/03-tracker-providers.md + label: Tracker Provider Contracts + html: null + - path: analysis/findings/04-product-quality-tradeoffs.md + label: Product Quality Trade-offs + html: null + - path: analysis/synthesis.md + label: Research Synthesis + html: null + - path: outputs/research-report.md + label: Research Report + html: outputs/research-report.html + - path: outputs/decision-summary.md + label: Decision Summary + html: outputs/decision-summary.html + phase-3: + summary: Six sequential decision areas compare 18 alternatives; the recommended direction uses an executable Node ESM helper, root source_issue provenance, durable cross-host quick-plan artifacts, capture-only v1 mutations, transactional Local Markdown, and Local-first delivery. + decisions: + - decision: "Granica providerów: wykonywalny helper Node ESM z exact JSON i deklaratywnym CapabilitySet." + rationale: Zapewnia parytet hostów, fail-closed validation i testowalność. + - decision: "Proweniencja: korzeniowy source_issue wskazuje niezmienny snapshot, ale nie przejmuje własności backlogu." + rationale: Oddziela żywy tracker od odtwarzalnego wejścia workflowu. + - decision: "Quick-plan: wspólny .maister/plans/*.md na wszystkich hostach, także z native plan UI." + rationale: Daje jeden trwały handoff artifact. + - decision: "v1 mutations: wyłącznie capture/create." + rationale: Ogranicza ryzyko i utrzymuje handoff read-only. + - decision: "Dostarczanie: Local Markdown jako tracer, potem GitHub za tym samym conformance contract." + rationale: Najpierw stabilizuje kontrakt i transakcyjność lokalną. + risks: + - Sprzeczne warianty schema state muszą zostać ujednolicone przed dodaniem source_issue. + - Założenia o rename, fsync i lockach nie obejmują network filesystems. + - GitHub write path może zakończyć się ambiguous_commit po timeout po dispatch. + - Trwały artifact quick-plan wymaga testów parytetu hostów. + artifacts: + - path: outputs/solution-exploration.md + label: Solution Exploration + html: outputs/solution-exploration.html + phase-4: + summary: "All six convergence areas are resolved into an incremental architecture: executable helper, root provenance pointer, durable plans, capture-only mutations, transactional Local Markdown, then GitHub as the second tracer." + decisions: + - decision: Choose a small Node ESM helper with exact JSON and a declarative CapabilitySet. + rationale: It provides the strongest host parity, fail-closed validation, and testability without a general provider framework. + - decision: Anchor canonical source_issue provenance at the root of orchestrator-state.yml after state schema unification. + rationale: It preserves one resume/audit source of truth without duplicating snapshot content or tracker ownership. + - decision: Persist quick-plan as a canonical .maister/plans/*.md artifact on every host, with native UI as a projection. + rationale: It provides a portable, Git-reviewable handoff to development. + - decision: Limit v1 tracker mutations to explicit capture/create; keep handoff and resume read-only. + rationale: It bounds side effects and defers lifecycle operations until concrete callers and conformance tests exist. + - decision: Use per-UUID Local Markdown records with per-record locks, CAS, and atomic replace on ordinary local filesystems. + rationale: It prevents lost updates while preserving readable files and byte-exact transactional rejection. + - decision: Deliver Local Markdown as the first tracer and GitHub second over the same conformance contract. + rationale: It creates small verifiable increments and isolates local contract issues before hosted failure modes. + risks: + - Codex fully_automatic pozostaje unsupported z powodu braku host-native adaptera/E2E oraz rozjazdu state schema; pełna diagnoza jest zapisana jako osobny artefakt. + artifacts: + - path: analysis/codex-fully-automatic-diagnosis.md + label: Codex Fully Automatic Diagnosis + html: null + decision_areas: + - area: Granica wykonawcza providerów + alternatives_count: 3 + chosen_approach: 1C — mały helper Node ESM i deklaratywny CapabilitySet + - area: Kanoniczna kotwica source_issue + alternatives_count: 3 + chosen_approach: 2A — korzeniowy source_issue w orchestrator-state.yml + - area: Proweniencja quick-plan między hostami + alternatives_count: 3 + chosen_approach: 3B — wspólny .maister/plans/*.md plus native UI + - area: Mutation surface w v1 + alternatives_count: 3 + chosen_approach: 4A — tylko jawne capture/create + - area: Trwałość i współbieżność Local Markdown + alternatives_count: 3 + chosen_approach: 5A — rekord per UUID, per-record lock, CAS i atomic replace + - area: Kolejność providerów i rozszerzalność + alternatives_count: 3 + chosen_approach: 6B — Local Markdown tracer, następnie GitHub + deferred_ideas: + - Comment/claim/close with receipts after concrete callers and reconciliation tests exist. + - GitLab, Jira, and Linear providers after the Local+GitHub conformance suite stabilizes. + - A public provider SDK only after at least three stable providers and real external authors exist. + - Semantic local merge and hosted offline mutation queues remain out of scope. + phase-5: + summary: A layered provider boundary with immutable handoff snapshots separates live tracker ownership from reproducible workflow input. Six ADRs define the executable boundary, provenance, portable plans, bounded mutations, local transactions, and sequential provider delivery. + decisions: + - decision: Use one executable provider boundary instead of prose-only adapters or a command-template DSL. + rationale: This centralizes validation, redaction, and cross-host semantics (ADR-001). + - decision: Keep tracker data and workflow execution state under separate ownership, with root source_issue provenance after state-schema unification. + rationale: This preserves tracker and workflow authority boundaries (ADR-002). + - decision: Persist quick plans as portable Markdown artifacts on every host and treat native plan UI as a projection. + rationale: This produces one durable cross-host handoff (ADR-003). + - decision: Limit v1 mutations to explicit capture/create; handoff, resume, and drift checks remain read-only. + rationale: This bounds side effects and operational risk (ADR-004). + - decision: Give Local Markdown per-UUID records, per-record locks, compare-and-swap, and atomic replace only on ordinary local filesystems. + rationale: This prevents lost updates within the supported filesystem boundary (ADR-005). + - decision: Deliver Local Markdown first and GitHub second under the same conformance contract. + rationale: This stabilizes the provider seam incrementally (ADR-006). + risks: + - The competing workflow-state schemas must be unified and fixture-tested before adding the root source_issue field; dual-read behavior is not part of this design. + - Local filesystem guarantees do not extend to network or distributed filesystems; unsupported environments must fail preflight with an actionable diagnostic. + - A GitHub create timeout after dispatch may remain ambiguous_commit; v1 must not blindly retry or switch transport. + - Cross-host fixtures must prove that canonical quick-plan content and native UI projections cannot silently diverge. + - Fully automatic Codex continuation remains unsupported until a host-native adapter, unified state schema, and end-to-end verification exist. + artifacts: + - path: outputs/high-level-design.md + label: High-Level Design + html: outputs/high-level-design.html + - path: outputs/decision-log.md + label: Decision Log + html: outputs/decision-log.html + architecture_style: layered provider boundary with immutable handoff snapshots + decisions_count: 6 + phase-6: + summary: Research, alternatives, convergence, and high-level design are complete. The final package recommends a provider-neutral executable boundary, immutable issue handoff, portable plans, capture-only v1 mutations, and Local Markdown then GitHub delivery. + decisions: [] + risks: + - Workflow-state schema unification remains a prerequisite for root source_issue provenance. + - Codex automatic continuation remains unsupported until host-native end-to-end validation passes. + artifacts: + - path: outputs/research-report.md + label: Research Report + html: outputs/research-report.html + - path: outputs/solution-exploration.md + label: Solution Exploration + html: outputs/solution-exploration.html + - path: outputs/high-level-design.md + label: High-Level Design + html: outputs/high-level-design.html + - path: outputs/decision-log.md + label: Decision Log + html: outputs/decision-log.html + - path: outputs/decision-summary.md + label: Decision Summary + html: outputs/decision-summary.html diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-log.html b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-log.html new file mode 100644 index 00000000..ec453545 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-log.html @@ -0,0 +1,76 @@ + + + + +Decision Log — issue-tracker-workflow + + + + +
Decision Log

Configurable Issue Tracker Workflow

MADR architecture decisions · 2026-07-13

+
6ADRs
6accepted
0superseded
0proposed
+

TL;DR

Six accepted ADRs define a provider-neutral, executable issue boundary and immutable issue-to-workflow handoff.
Workflow state retains provenance and resume truth without owning the live tracker; quick plans remain portable across hosts.
v1 is deliberately narrow: explicit capture/create, transactional Local Markdown first, then GitHub under one conformance contract.

Key Decisions

  • One small Node ESM boundary owns exact schemas, capabilities, dispatch, typed errors, and redaction.
  • Root source_issue is added only after the workflow-state schema is unified; snapshot content remains outside state.
  • Local Markdown and portable plans establish deterministic behavior before hosted-provider expansion.
+

Open Questions / Risks

  • State-schema unification and migration fixtures are prerequisites for ADR-002.
  • Local transactional guarantees are restricted to ordinary local filesystems.
  • GitHub create can remain ambiguous after a post-dispatch timeout, so blind retry is prohibited.
  • Codex fully automatic continuation stays unsupported until separately verified.
+ +
+

ADR-001: Use an Executable Provider Boundary

Accepted

Context

Maister needs consistent provider behavior across hosts whose tools, command syntax, and continuation capabilities differ. Prose-only guidance spreads parsing, quoting, validation, error handling, and redaction across prompts, while a declarative command-template approach creates a security-sensitive command language.

Decision Drivers

  • Deterministic, fail-closed validation across all supported hosts.
  • Exact machine-readable requests and results suitable for contract tests.
  • Explicit representation of provider and permission differences.
  • Minimal dependency footprint aligned with the existing Node.js runtime.

Considered Options

  1. Prose instructions with direct host tools.
  2. Declarative command templates executed by each host.
  3. A small Node ESM helper with exact JSON and a declarative CapabilitySet.

Decision Outcome

Chosen option: a small Node ESM helper with exact JSON and a declarative CapabilitySet, because it creates one testable safety boundary without introducing a general provider SDK or flattening vendor constraints.

Consequences · Good

  • Parsing, schema validation, provider dispatch, typed errors, redaction, and transport rules have one owner.
  • Host adapters remain thin and provider semantics remain testable through shared fixtures.
  • Capabilities can express native, emulated, unsupported, and unknown with permissions and constraints.

Consequences · Bad

  • The helper becomes a critical security and compatibility boundary requiring strong contract coverage.
  • Packaging and invocation must be validated for every generated host variant.
  • More implementation is required than for prose-only guidance.
+

ADR-002: Anchor Source Provenance in Workflow State

Accepted

Context

Issue handoff must record which live input started a workflow without turning workflow state into a backlog replica. Existing evidence reveals competing workflow-state schemas, so adding provenance before schema unification would create multiple authoritative shapes or dual-read complexity.

Decision Drivers

  • Preserve workflow state as the only source of truth for phase execution and resume.
  • Keep tracker ownership of live title, body, lifecycle, and relationships.
  • Make the exact workflow input auditable and drift-detectable.
  • Avoid duplicating snapshot content in state.

Considered Options

  1. A root source_issue pointer in the unified workflow state.
  2. An authoritative intake manifest outside workflow state.
  3. Separate source fields owned by each workflow.

Decision Outcome

Chosen option: a root source_issue pointer in the unified workflow state after schema unification, because it gives research and development one resume/audit anchor while immutable artifacts retain the actual snapshot content.

Consequences · Good

  • Resume and audit can discover source provenance from one authoritative state document.
  • Tracker status remains distinct from phase status, and live issue data is not mirrored.
  • Drift checks can compare the captured revision or digest without changing prior decisions.

Consequences · Bad

  • State schema unification, versioning, migration behavior, and fixtures are blocking prerequisites.
  • Quick-plan requires an analogous source block because it does not always create orchestrated workflow state.
  • The pointer and referenced artifacts must be committed transactionally to avoid broken provenance.
+

ADR-003: Use Portable Quick-Plan Artifacts

Accepted

Context

Quick-plan persistence currently depends on the host: some hosts expose native planning state while others produce project-local files. A handoff that exists only in host UI is not reliably auditable, versionable, or transferable to another host or a later development workflow.

Decision Drivers

  • Cross-host semantic parity and durable provenance.
  • Git-reviewable handoff from planning to development.
  • One canonical representation rather than divergent host-owned copies.
  • Compatibility with useful native planning interfaces.

Considered Options

  1. Persist only in each host's native plan mechanism.
  2. Persist a canonical .maister/plans/*.md artifact on every host and project it into native UI.
  3. Store only a central provenance registry referencing host-native plans.

Decision Outcome

Chosen option: a canonical Markdown plan artifact on every host, with native UI as a projection, because the artifact preserves plan content and source provenance independently of session or host lifetime.

Consequences · Good

  • Plans are portable, reviewable, and suitable for later development handoff.
  • All hosts share one durable source block containing issue ref, revision, digest, and snapshot linkage.
  • Native planning UI remains available without becoming authoritative persistence.

Consequences · Bad

  • Claude and Codex flows require new persistence behavior and parity fixtures.
  • Projection logic must prevent native and canonical plan content from silently diverging.
  • The workflow must define exactly when an approved plan artifact becomes durable.
+

ADR-004: Bound the v1 Mutation Surface

Accepted

Context

Tracker mutations are externally visible and harder to reverse than local workflow state. Comment, claim, close, labels, and transitions vary substantially by provider and create uncertain outcomes when a request times out after dispatch.

Decision Drivers

  • Explicit user intent for every external side effect.
  • Minimal v1 surface backed by real callers and tests.
  • Read-only, reproducible handoff and resume behavior.
  • Clear separation between tracker lifecycle and workflow phases.

Considered Options

  1. Expose only explicit capture/create in v1.
  2. Add comment, claim, and transition operations behind approvals.
  3. Synchronize workflow phases with tracker lifecycle automatically.

Decision Outcome

Chosen option: only explicit capture/create in v1, because it provides fast task capture while keeping select, handoff, resume, drift checks, and workflow completion free of implicit tracker mutation.

Consequences · Good

  • The external side-effect surface and ambiguous-commit risk are bounded.
  • Workflow replay and resume cannot unexpectedly claim, comment on, or close an issue.
  • Later mutations can be introduced with dedicated callers, approvals, receipts, and reconciliation tests.

Consequences · Bad

  • Users must update tracker lifecycle manually after workflow work.
  • Frontier, claim-before-work, and automated completion patterns remain deferred.
  • The provider contract may describe future capabilities that public v1 intentionally does not invoke.
+

ADR-005: Use Transactional Local Markdown Records

Accepted

Context

Local Markdown must remain human-readable and Git-friendly while tolerating concurrent agents in one worktree. Sequential identifiers, edit-in-place updates, or Git-only conflict detection can lose data before version control observes the conflict.

Decision Drivers

  • No lost update under concurrent access.
  • Byte-exact transactional rejection and predictable recovery.
  • Independent creates that merge cleanly in Git.
  • No database or event-store dependency.

Considered Options

  1. One UUID record per issue with per-record lock, CAS, and atomic replace.
  2. An append-only event journal with a materialized projection.
  3. Plain Markdown files with Git as the only concurrency mechanism.

Decision Outcome

Chosen option: per-UUID records with per-record locks, compare-and-swap, and atomic replace on ordinary local filesystems, because it provides understandable files and deterministic conflict handling without building an event store.

Consequences · Good

  • Concurrent updates either commit against the expected revision or fail with a typed conflict.
  • Random stable identities reduce collisions and independent-create merge conflicts.
  • Partial candidates are never published, and rejected operations can preserve bytes, permissions, and topology.

Consequences · Bad

  • Lock ownership, cleanup, flush, replacement, and failure injection require careful tests.
  • Stale locks need operator intervention in v1; automatic lock theft is excluded.
  • Network filesystems and semantic Git merge are not guaranteed, and same-record Git conflicts remain manual.
+

ADR-006: Deliver Providers as Sequential Tracers

Accepted

Context

Local Markdown and GitHub exercise different failure modes. Implementing both simultaneously combines filesystem transactions, authentication, pagination, rate limiting, transport choice, and uncertain hosted writes before the shared provider seam has conformance evidence.

Decision Drivers

  • Small, verifiable increments with fast feedback.
  • Early validation of provider-neutral contracts.
  • Isolation of local transaction failures from hosted network failures.
  • Avoidance of a speculative multi-provider SDK.

Considered Options

  1. Deliver Local Markdown and GitHub together in one release.
  2. Deliver the Local Markdown vertical tracer first, then GitHub under the same conformance contract.
  3. Design a public SDK and implement multiple hosted providers before workflow integration.

Decision Outcome

Chosen option: Local Markdown first and GitHub second under one conformance contract, because a deterministic offline tracer can stabilize references, errors, snapshots, and handoff before GitHub proves that the seam survives hosted-provider behavior.

Consequences · Good

  • Each increment has a focused acceptance surface and diagnosable failures.
  • GitHub must conform to the established provider-neutral contract rather than define it implicitly.
  • GitLab, Jira, and Linear remain future conformance tests instead of speculative v1 implementations.

Consequences · Bad

  • The first usable increment supports only one provider.
  • The Local-first contract must be reviewed actively to avoid filesystem-specific abstractions.
  • Hosted integration value arrives after the Local and handoff tracer is complete.
+
+ diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-log.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-log.md new file mode 100644 index 00000000..2c69f2c6 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-log.md @@ -0,0 +1,231 @@ +# Decision Log: Configurable Issue Tracker Workflow + +## TL;DR +Six accepted ADRs define a provider-neutral, executable issue boundary and immutable issue-to-workflow handoff. +Workflow state retains provenance and resume truth without owning the live tracker; quick plans remain portable across hosts. +v1 is deliberately narrow: explicit capture/create, transactional Local Markdown first, then GitHub under one conformance contract. + +## Key Decisions +- One small Node ESM boundary owns exact schemas, capabilities, dispatch, typed errors, and redaction. +- Root `source_issue` is added only after the workflow-state schema is unified; snapshot content remains outside state. +- Local Markdown and portable plans establish deterministic behavior before hosted-provider expansion. + +## Open Questions / Risks +- State-schema unification and migration fixtures are prerequisites for ADR-002. +- Local transactional guarantees are restricted to ordinary local filesystems. +- GitHub create can remain ambiguous after a post-dispatch timeout, so blind retry is prohibited. +- Codex fully automatic continuation stays unsupported until separately verified. + +## ADR-001: Use an Executable Provider Boundary + +### Status +Accepted + +### Context +Maister needs consistent provider behavior across hosts whose tools, command syntax, and continuation capabilities differ. Prose-only guidance spreads parsing, quoting, validation, error handling, and redaction across prompts, while a declarative command-template approach creates a security-sensitive command language. + +### Decision Drivers +- Deterministic, fail-closed validation across all supported hosts. +- Exact machine-readable requests and results suitable for contract tests. +- Explicit representation of provider and permission differences. +- Minimal dependency footprint aligned with the existing Node.js runtime. + +### Considered Options +1. Prose instructions with direct host tools. +2. Declarative command templates executed by each host. +3. A small Node ESM helper with exact JSON and a declarative `CapabilitySet`. + +### Decision Outcome +Chosen option: **a small Node ESM helper with exact JSON and a declarative `CapabilitySet`**, because it creates one testable safety boundary without introducing a general provider SDK or flattening vendor constraints. + +### Consequences + +#### Good +- Parsing, schema validation, provider dispatch, typed errors, redaction, and transport rules have one owner. +- Host adapters remain thin and provider semantics remain testable through shared fixtures. +- Capabilities can express `native`, `emulated`, `unsupported`, and `unknown` with permissions and constraints. + +#### Bad +- The helper becomes a critical security and compatibility boundary requiring strong contract coverage. +- Packaging and invocation must be validated for every generated host variant. +- More implementation is required than for prose-only guidance. + +--- + +## ADR-002: Anchor Source Provenance in Workflow State + +### Status +Accepted + +### Context +Issue handoff must record which live input started a workflow without turning workflow state into a backlog replica. Existing evidence reveals competing workflow-state schemas, so adding provenance before schema unification would create multiple authoritative shapes or dual-read complexity. + +### Decision Drivers +- Preserve workflow state as the only source of truth for phase execution and resume. +- Keep tracker ownership of live title, body, lifecycle, and relationships. +- Make the exact workflow input auditable and drift-detectable. +- Avoid duplicating snapshot content in state. + +### Considered Options +1. A root `source_issue` pointer in the unified workflow state. +2. An authoritative intake manifest outside workflow state. +3. Separate source fields owned by each workflow. + +### Decision Outcome +Chosen option: **a root `source_issue` pointer in the unified workflow state after schema unification**, because it gives research and development one resume/audit anchor while immutable artifacts retain the actual snapshot content. + +### Consequences + +#### Good +- Resume and audit can discover source provenance from one authoritative state document. +- Tracker status remains distinct from phase status, and live issue data is not mirrored. +- Drift checks can compare the captured revision or digest without changing prior decisions. + +#### Bad +- State schema unification, versioning, migration behavior, and fixtures are blocking prerequisites. +- Quick-plan requires an analogous source block because it does not always create orchestrated workflow state. +- The pointer and referenced artifacts must be committed transactionally to avoid broken provenance. + +--- + +## ADR-003: Use Portable Quick-Plan Artifacts + +### Status +Accepted + +### Context +Quick-plan persistence currently depends on the host: some hosts expose native planning state while others produce project-local files. A handoff that exists only in host UI is not reliably auditable, versionable, or transferable to another host or a later development workflow. + +### Decision Drivers +- Cross-host semantic parity and durable provenance. +- Git-reviewable handoff from planning to development. +- One canonical representation rather than divergent host-owned copies. +- Compatibility with useful native planning interfaces. + +### Considered Options +1. Persist only in each host's native plan mechanism. +2. Persist a canonical `.maister/plans/*.md` artifact on every host and project it into native UI. +3. Store only a central provenance registry referencing host-native plans. + +### Decision Outcome +Chosen option: **a canonical Markdown plan artifact on every host, with native UI as a projection**, because the artifact preserves plan content and source provenance independently of session or host lifetime. + +### Consequences + +#### Good +- Plans are portable, reviewable, and suitable for later development handoff. +- All hosts share one durable source block containing issue ref, revision, digest, and snapshot linkage. +- Native planning UI remains available without becoming authoritative persistence. + +#### Bad +- Claude and Codex flows require new persistence behavior and parity fixtures. +- Projection logic must prevent native and canonical plan content from silently diverging. +- The workflow must define exactly when an approved plan artifact becomes durable. + +--- + +## ADR-004: Bound the v1 Mutation Surface + +### Status +Accepted + +### Context +Tracker mutations are externally visible and harder to reverse than local workflow state. Comment, claim, close, labels, and transitions vary substantially by provider and create uncertain outcomes when a request times out after dispatch. + +### Decision Drivers +- Explicit user intent for every external side effect. +- Minimal v1 surface backed by real callers and tests. +- Read-only, reproducible handoff and resume behavior. +- Clear separation between tracker lifecycle and workflow phases. + +### Considered Options +1. Expose only explicit capture/create in v1. +2. Add comment, claim, and transition operations behind approvals. +3. Synchronize workflow phases with tracker lifecycle automatically. + +### Decision Outcome +Chosen option: **only explicit capture/create in v1**, because it provides fast task capture while keeping select, handoff, resume, drift checks, and workflow completion free of implicit tracker mutation. + +### Consequences + +#### Good +- The external side-effect surface and ambiguous-commit risk are bounded. +- Workflow replay and resume cannot unexpectedly claim, comment on, or close an issue. +- Later mutations can be introduced with dedicated callers, approvals, receipts, and reconciliation tests. + +#### Bad +- Users must update tracker lifecycle manually after workflow work. +- Frontier, claim-before-work, and automated completion patterns remain deferred. +- The provider contract may describe future capabilities that public v1 intentionally does not invoke. + +--- + +## ADR-005: Use Transactional Local Markdown Records + +### Status +Accepted + +### Context +Local Markdown must remain human-readable and Git-friendly while tolerating concurrent agents in one worktree. Sequential identifiers, edit-in-place updates, or Git-only conflict detection can lose data before version control observes the conflict. + +### Decision Drivers +- No lost update under concurrent access. +- Byte-exact transactional rejection and predictable recovery. +- Independent creates that merge cleanly in Git. +- No database or event-store dependency. + +### Considered Options +1. One UUID record per issue with per-record lock, CAS, and atomic replace. +2. An append-only event journal with a materialized projection. +3. Plain Markdown files with Git as the only concurrency mechanism. + +### Decision Outcome +Chosen option: **per-UUID records with per-record locks, compare-and-swap, and atomic replace on ordinary local filesystems**, because it provides understandable files and deterministic conflict handling without building an event store. + +### Consequences + +#### Good +- Concurrent updates either commit against the expected revision or fail with a typed conflict. +- Random stable identities reduce collisions and independent-create merge conflicts. +- Partial candidates are never published, and rejected operations can preserve bytes, permissions, and topology. + +#### Bad +- Lock ownership, cleanup, flush, replacement, and failure injection require careful tests. +- Stale locks need operator intervention in v1; automatic lock theft is excluded. +- Network filesystems and semantic Git merge are not guaranteed, and same-record Git conflicts remain manual. + +--- + +## ADR-006: Deliver Providers as Sequential Tracers + +### Status +Accepted + +### Context +Local Markdown and GitHub exercise different failure modes. Implementing both simultaneously combines filesystem transactions, authentication, pagination, rate limiting, transport choice, and uncertain hosted writes before the shared provider seam has conformance evidence. + +### Decision Drivers +- Small, verifiable increments with fast feedback. +- Early validation of provider-neutral contracts. +- Isolation of local transaction failures from hosted network failures. +- Avoidance of a speculative multi-provider SDK. + +### Considered Options +1. Deliver Local Markdown and GitHub together in one release. +2. Deliver the Local Markdown vertical tracer first, then GitHub under the same conformance contract. +3. Design a public SDK and implement multiple hosted providers before workflow integration. + +### Decision Outcome +Chosen option: **Local Markdown first and GitHub second under one conformance contract**, because a deterministic offline tracer can stabilize references, errors, snapshots, and handoff before GitHub proves that the seam survives hosted-provider behavior. + +### Consequences + +#### Good +- Each increment has a focused acceptance surface and diagnosable failures. +- GitHub must conform to the established provider-neutral contract rather than define it implicitly. +- GitLab, Jira, and Linear remain future conformance tests instead of speculative v1 implementations. + +#### Bad +- The first usable increment supports only one provider. +- The Local-first contract must be reviewed actively to avoid filesystem-specific abstractions. +- Hosted integration value arrives after the Local and handoff tracer is complete. diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-summary.html b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-summary.html new file mode 100644 index 00000000..a9725794 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-summary.html @@ -0,0 +1,157 @@ + + + + + + Decision Summary — Issue Tracker Research + + +
+ Workflow completed +

Decision Summary

+
+

TL;DR

+

Wszystkie wyniki badania i high-level design z sześcioma ADR-ami są kompletne. Użytkownik zatwierdził finalny handoff i zakończenie workflowu.

+
+

Gate record

+
+
Question
Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation?
+
Options
Continue to brainstorming evaluation; Pause workflow
+
Original recommendation
Continue to brainstorming evaluation
+
Selected option
Pause workflow
+
Final actor
user
+
Confidence
high
+
Status
decided
+
+

Advisor attempts

+
+ + + +
AttemptOutcomeBackoff
1inherit unsupported with ChatGPT account1000 ms
2same host error2000 ms
3same host error; exhausted—

No advisor recommendation was produced. The arbiter was not invoked.

+

Brainstorming selection

+
+
Question
Multiple viable architectures and competing trade-offs make brainstorming valuable. Would you like to explore solution alternatives?
+
Options
Yes, explore alternatives; No, skip brainstorming
+
Original recommendation
Yes, explore alternatives
+
Advisor recommendation
Yes, explore alternatives (high confidence)
+
Selected option
Yes, explore alternatives
+
Final actor
user
+
Status
decided
+
+

Phase 3 exit

+
+
Question
Continue to solution convergence?
+
Selected option
Continue to solution convergence
+
Final actor
user
+
Status
decided
+
+

Convergence area 1

+
+
Question
Which provider execution boundary should Maister use?
+
Selected option
1C — Node ESM helper + CapabilitySet
+
Final actor
user
+
Status
decided
+
+

Convergence area 2

+
+
Question
Where should canonical source_issue provenance be anchored?
+
Selected option
2A — root source_issue in orchestrator-state.yml
+
Final actor
user
+
Status
decided
+
+

Convergence area 3

+
+
Question
How should quick-plan provenance persist across hosts?
+
Selected option
3B — shared .maister/plans/*.md plus native UI
+
Final actor
user
+
Status
decided
+
+

Convergence area 4

+
+
Question
Which tracker mutation surface should v1 expose?
+
Selected option
4A — explicit capture/create only
+
Final actor
user
+
Status
decided
+
+

Convergence area 5

+
+
Question
Which persistence protocol should Local Markdown use?
+
Selected option
5A — UUID + lock + CAS + atomic replace
+
Final actor
user
+
Status
decided
+
+

Convergence area 6

+
+
Question
In what order should v1 deliver tracker providers?
+
Selected option
6B — Local Markdown first, then GitHub
+
Final actor
user
+
Status
decided
+
+

Phase 4 exit

+
+
Question
Brainstorming complete. Continue to high-level design?
+
Selected option
Pause workflow
+
Final actor
user
+
Status
decided
+
+

Phase 5 design clarification

+
+
Question
The six convergence decisions establish the design direction. Should the high-level design proceed with those assumptions unchanged?
+
Options
Confirm assumptions; Correct assumptions; Provide more context
+
Original recommendation
Confirm assumptions
+
Advisor recommendation
Confirm assumptions (high confidence)
+
Automatic continuation
Unsupported for Codex; interactive fallback used
+
Selected option
Confirm assumptions
+
Final actor
user
+
Status
decided
+
+

Phase 5 exit

+
+
Question
Design complete. Continue to output generation?
+
Options
Continue to output generation; Pause workflow
+
Original recommendation
Continue to output generation
+
Advisor recommendation
Continue to output generation (high confidence)
+
Automatic continuation
Unsupported for Codex; interactive fallback used
+
Selected option
Continue to output generation
+
Final actor
user
+
Status
decided
+
+

Final handoff approval

+
+
Question
Research outputs are complete. Approve the final handoff?
+
Options
Complete workflow; Keep workflow open
+
Safety
Denylisted; always user-controlled
+
Selected option
Complete workflow
+
Final actor
user
+
Status
decided
+
Workflow status
completed
+
+

Artifacts

+

High-level design selection

+
+
Question
The research identifies architectural decisions that would directly feed development. Would you like to generate a high-level design?
+
Original recommendation
Yes, generate design
+
Advisor recommendation
Yes, generate design (high confidence)
+
Selected option
Yes, generate design
+
Final actor
user
+
Status
decided
+
+

Artifacts

+

Research report · Synthesis · Workflow state · Dashboard

+
diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-summary.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-summary.md new file mode 100644 index 00000000..46f505f2 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/decision-summary.md @@ -0,0 +1,253 @@ +# Decision Summary + +## TL;DR +Wszystkie wyniki badania i high-level design z sześcioma ADR-ami są kompletne. Użytkownik zatwierdził finalny handoff i zakończenie workflowu. Codex nadal nie ma zweryfikowanej host-native continuation, więc bezpieczne bramki wymagały interaktywnych potwierdzeń. + +## Key Decisions +- Pause workflow — użytkownik zdecydował zatrzymać workflow po ukończeniu fundamentu badawczego. +- Yes, explore alternatives — użytkownik włączył brainstorming po wznowieniu workflowu. +- Yes, generate design — użytkownik włączył projekt wysokopoziomowy i zatwierdził automatyczne stosowanie zgodnych rekomendacji advisora dla bezpiecznych bramek. +- Confirm assumptions — użytkownik zatwierdził sześć decyzji konwergencji jako wejście do high-level design bez dodatkowych ograniczeń. +- Continue to output generation — użytkownik zaakceptował zweryfikowany high-level design i skierował workflow do Phase 6. +- Complete workflow — użytkownik zatwierdził finalny pakiet badawczy i zamknięcie workflowu. + +## Open Questions / Risks +- Konfiguracja `model = "inherit"` w `.codex/agents/advisor.toml` nie działa w bieżącym runtime Codex z kontem ChatGPT. +- Host Codex ma obecnie `fully_automatic: unsupported`; zgodnie z kontraktem workflow może nadal wymagać ręcznej bramki, dopóki host-native continuation nie przejdzie walidacji. + +## Gate Record + +- **Phase:** `phase-1` +- **Gate type:** `phase-1-exit` +- **Idempotency key:** `sha256:8dc80ac772693c815f0dfac96f7baa45a3cded3e406f16c6f5a42756f1e157d4` +- **Question:** Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? +- **Options, in order:** + 1. `Continue to brainstorming evaluation` + 2. `Pause workflow` +- **Original recommendation:** `Continue to brainstorming evaluation` +- **Configured policy:** `advisor` +- **Safety classification:** `configurable` +- **Selected option:** `Pause workflow` +- **Final actor:** `user` +- **Rationale:** User explicitly chose to pause after reviewing the completed research foundation. +- **Confidence:** `high` +- **User override:** `true` — the selected option differs from the original recommendation. +- **Terminal status:** `decided` + +## Gate Record: Phase 5 Design Clarification + +- **Phase:** `phase-5` +- **Gate type:** `research-clarification` +- **Idempotency key:** `sha256:d2d155b8dc6dc759724bbddbe3f5de77683741a654c0091310ef6e2f95fa31d6` +- **Question:** The six convergence decisions establish the design direction. Should the high-level design proceed with those assumptions unchanged? +- **Options, in order:** `Confirm assumptions`; `Correct assumptions`; `Provide more context` +- **Original recommendation:** `Confirm assumptions` +- **Configured policy:** `fully_automatic` +- **Safety classification:** `configurable` +- **Advisor recommendation:** `Confirm assumptions` +- **Advisor rationale:** The six decisions are mutually consistent, respect the stated architectural constraints, keep orchestrator-state.yml authoritative, avoid provider coupling, and define a bounded v1 with explicit filesystem and platform limitations. +- **Advisor confidence:** `high` +- **Automatic continuation:** unsupported for Codex; interactive fallback used. +- **Selected option:** `Confirm assumptions` +- **Final actor:** `user` +- **User override:** `false` +- **Terminal status:** `decided` + +## Gate Record: Phase 5 Exit + +- **Phase:** `phase-5` +- **Gate type:** `phase-5-exit` +- **Idempotency key:** `sha256:6bdf08499f5ea52adcb109887df08612b87fed5c1a2a6ba779d4fc70c9cb160e` +- **Question:** Design complete. Continue to output generation? +- **Options, in order:** `Continue to output generation`; `Pause workflow` +- **Original recommendation:** `Continue to output generation` +- **Configured policy:** `fully_automatic` +- **Safety classification:** `configurable` +- **Advisor recommendation:** `Continue to output generation` +- **Advisor rationale:** Phase 5 completed successfully, required design artifacts and checks are present, known risks and prerequisites are explicitly preserved, and Phase 6 only packages the validated findings into final outputs. +- **Advisor confidence:** `high` +- **Automatic continuation:** unsupported for Codex; interactive fallback used. +- **Selected option:** `Continue to output generation` +- **Final actor:** `user` +- **User override:** `false` +- **Terminal status:** `decided` + +## Gate Record: Final Handoff Approval + +- **Phase:** `phase-6` +- **Gate type:** `final-handoff-approval` +- **Idempotency key:** `sha256:283ebe0a6247edeaaddef3b7647f654d966aa190da4ee71b2f961b3dd18d2825` +- **Question:** Research outputs are complete. Approve the final handoff? +- **Options, in order:** `Complete workflow`; `Keep workflow open` +- **Original recommendation:** `Complete workflow` +- **Configured policy:** `manual` +- **Safety classification:** `denylisted` +- **Advisor/arbiter:** not invoked; this gate is always user-controlled. +- **Selected option:** `Complete workflow` +- **Final actor:** `user` +- **Rationale:** User approved the final research handoff and completion of the workflow. +- **Confidence:** `high` +- **User override:** `false` +- **Terminal status:** `decided` +- **Workflow terminal status:** `completed` + +## Gate Record: Phase 4 Exit + +- **Phase:** `phase-4` +- **Gate type:** `phase-4-exit` +- **Idempotency key:** `sha256:deff7dc9407e4bf7bd8e9827eea83f0943d11d5daa1793b43db636eb584db001` +- **Question:** Brainstorming complete. Continue to high-level design? +- **Options, in order:** `Continue to high-level design`; `Pause workflow` +- **Original recommendation:** `Continue to high-level design` +- **Selected option:** `Pause workflow` +- **Final actor:** `user` +- **User override:** `true` +- **Confidence:** `high` +- **Terminal status:** `decided` + +## Gate Record: Convergence Area 6 + +- **Phase:** `phase-4` +- **Gate type:** `research-convergence` +- **Idempotency key:** `sha256:2e2af5cd201403e231f02eb0b77f59014f873fb8d3539b80647f50fb1615a7f6` +- **Question:** In what order should v1 deliver tracker providers? +- **Original recommendation:** `6B — Local Markdown first, then GitHub` +- **Selected option:** `6B — Local Markdown first, then GitHub` +- **Final actor:** `user` +- **Confidence:** `high` +- **Terminal status:** `decided` + +## Gate Record: Convergence Area 5 + +- **Phase:** `phase-4` +- **Gate type:** `research-convergence` +- **Idempotency key:** `sha256:eaaf8832a0e880c6b34925b886e016307a54722d2672df5fd5e37f6ee2f43863` +- **Question:** Which persistence protocol should Local Markdown use? +- **Original recommendation:** `5A — UUID record, per-record lock, CAS, atomic replace` +- **Selected option:** `5A — UUID record, per-record lock, CAS, atomic replace` +- **Final actor:** `user` +- **Confidence:** `high` +- **Terminal status:** `decided` + +## Gate Record: Convergence Area 4 + +- **Phase:** `phase-4` +- **Gate type:** `research-convergence` +- **Idempotency key:** `sha256:2d424dd21881954ddefce454a09a7a06999e6b8804b6a11a5464d25f1abcaad2` +- **Question:** Which tracker mutation surface should v1 expose? +- **Original recommendation:** `4A — explicit capture/create only` +- **Selected option:** `4A — explicit capture/create only` +- **Final actor:** `user` +- **Confidence:** `high` +- **Terminal status:** `decided` + +## Gate Record: Convergence Area 3 + +- **Phase:** `phase-4` +- **Gate type:** `research-convergence` +- **Idempotency key:** `sha256:6420d393ee515436120df4c9fc4ee3237a536c22f59202bc3af214652b88006b` +- **Question:** How should quick-plan provenance persist across hosts? +- **Original recommendation:** `3B — shared .maister/plans/*.md plus native UI` +- **Selected option:** `3B — shared .maister/plans/*.md plus native UI` +- **Final actor:** `user` +- **Confidence:** `high` +- **Terminal status:** `decided` + +## Gate Record: Convergence Area 2 + +- **Phase:** `phase-4` +- **Gate type:** `research-convergence` +- **Idempotency key:** `sha256:1405b0df3ba973ffe77cf109cf542cc3b69b3d0c709d74780c3d6c6c2206be62` +- **Question:** Where should canonical source_issue provenance be anchored? +- **Original recommendation:** `2A — root source_issue in orchestrator-state.yml` +- **Selected option:** `2A — root source_issue in orchestrator-state.yml` +- **Final actor:** `user` +- **Confidence:** `high` +- **Terminal status:** `decided` + +## Gate Record: Convergence Area 1 + +- **Phase:** `phase-4` +- **Gate type:** `research-convergence` +- **Idempotency key:** `sha256:8b8e6268eadeea8e9075d04f18884ea11c39055775dd1d52df2849b6bd0c2af6` +- **Question:** Which provider execution boundary should Maister use? +- **Options, in order:** `1A`; `1B`; `1C`; `Need more info` +- **Original recommendation:** `1C — mały helper Node ESM i deklaratywny CapabilitySet` +- **Selected option:** `1C — mały helper Node ESM i deklaratywny CapabilitySet` +- **Final actor:** `user` +- **Confidence:** `high` +- **Terminal status:** `decided` + +## Gate Record: Phase 3 Exit + +- **Phase:** `phase-3` +- **Gate type:** `phase-3-exit` +- **Idempotency key:** `sha256:b44cce49b270e039db9825c224697b82b1f7ac236d4a1a361cd36e21a6e3cd13` +- **Question:** Continue to solution convergence? +- **Options, in order:** `Continue to solution convergence`; `Pause workflow` +- **Original recommendation:** `Continue to solution convergence` +- **Selected option:** `Continue to solution convergence` +- **Final actor:** `user` +- **Confidence:** `high` +- **Terminal status:** `decided` + +## Gate Record: High-Level Design Selection + +- **Phase:** `phase-2` +- **Gate type:** `optional-phase-selection` +- **Idempotency key:** `sha256:571789075d8fe42ced95941597dca774808f00995f22ba6b6bf6ea6a477cf575` +- **Question:** The research identifies architectural decisions that would directly feed development. Would you like to generate a high-level design? +- **Options, in order:** + 1. `Yes, generate design` + 2. `No, skip design` +- **Original recommendation:** `Yes, generate design` +- **Configured policy at evaluation:** `advisor` +- **Advisor recommendation:** `Yes, generate design` +- **Advisor confidence:** `high` +- **Selected option:** `Yes, generate design` +- **Final actor:** `user` +- **User override:** `false` +- **Terminal status:** `decided` + +## Advisor Attempts + +Configured agent: `advisor`. Configured workflow model override: `null`; the Codex agent definition resolves this to `model = "inherit"`. + +| Attempt | Outcome | Model | Retry/backoff | +|---|---|---|---| +| 1 | unavailable: `inherit` is unsupported with a ChatGPT account | inherited session model requested | 1000 ms | +| 2 | unavailable: same host error | inherited session model requested | 2000 ms | +| 3 | unavailable: same host error | inherited session model requested | exhausted | + +No valid advisor recommendation was produced. Interactive fallback was therefore used as required by the gate engine. + +## Arbiter + +The arbiter was not invoked because no valid advisor recommendation existed to disagree with the original recommendation. It is configured to use the same `advisor` agent and inherited model unless explicitly overridden. + +## Context and Artifacts + +- [Research report](research-report.md) +- [Research synthesis](../analysis/synthesis.md) +- [Canonical workflow state](../orchestrator-state.yml) +- [Dashboard](../dashboard.html) + +## Gate Record: Brainstorming Selection + +- **Phase:** `phase-2` +- **Gate type:** `optional-phase-selection` +- **Idempotency key:** `sha256:ef97f9b46a7c28e4c418e8abf667877f80fd953dacc6d142349fdfd47b1e72e6` +- **Question:** Multiple viable architectures and competing trade-offs make brainstorming valuable. Would you like to explore solution alternatives? +- **Options, in order:** + 1. `Yes, explore alternatives` + 2. `No, skip brainstorming` +- **Original recommendation:** `Yes, explore alternatives` +- **Configured policy:** `advisor` +- **Safety classification:** `configurable` +- **Advisor recommendation:** `Yes, explore alternatives` +- **Advisor rationale:** The research identifies multiple architectural seams and unresolved trade-offs, so comparing alternatives can materially improve the implementation direction. +- **Advisor confidence:** `high` +- **Selected option:** `Yes, explore alternatives` +- **Final actor:** `user` +- **User override:** `false` +- **Terminal status:** `decided` diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/high-level-design.html b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/high-level-design.html new file mode 100644 index 00000000..489ecb33 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/high-level-design.html @@ -0,0 +1,150 @@ + + + + +High-Level Design — issue-tracker-workflow + + + + +
High-Level Design

Configurable Issue Tracker Workflow

Issue-to-workflow architecture for Maister · 2026-07-13

+
7components
6decisions
Layeredarchitecture style
2provider tracers
+

TL;DR

Maister adds a provider-neutral issue boundary as a small Node ESM helper with exact JSON, typed errors, and a declarative CapabilitySet.
Issues remain live in their tracker; workflows consume immutable snapshots and retain only a root source_issue provenance pointer in the unified workflow state.
Local Markdown is the first tracer, GitHub the second; v1 mutates trackers only through explicit capture/create.
Portable .maister/plans/*.md files are canonical quick-plan handoff artifacts, while host-native plan UI is a projection.

+

Key Decisions

    +
  • Use one executable provider boundary instead of prose-only adapters or a command-template DSL — this centralizes validation, redaction, and cross-host semantics (ADR-001).
    • +
  • Keep tracker data and workflow execution state under separate ownership, with root source_issue provenance after state-schema unification (ADR-002).
    • +
  • Persist quick plans as portable Markdown artifacts on every host and treat native plan UI as a projection (ADR-003).
    • +
  • Limit v1 mutations to explicit capture/create; handoff, resume, and drift checks remain read-only (ADR-004).
    • +
  • Give Local Markdown per-UUID records, per-record locks, compare-and-swap, and atomic replace only on ordinary local filesystems (ADR-005).
    • +
  • Deliver Local Markdown first and GitHub second under the same conformance contract (ADR-006).
+

Open Questions / Risks

    +
  • The competing workflow-state schemas must be unified and fixture-tested before adding the root source_issue field; dual-read behavior is not part of this design.
    • +
  • Local filesystem guarantees do not extend to network or distributed filesystems; unsupported environments must fail preflight with an actionable diagnostic.
    • +
  • A GitHub create timeout after dispatch may remain ambiguous_commit; v1 must not blindly retry or switch transport.
    • +
  • Cross-host fixtures must prove that canonical quick-plan content and native UI projections cannot silently diverge.
    • +
  • Fully automatic Codex continuation remains unsupported until a host-native adapter, unified state schema, and end-to-end verification exist.
+ +
+

Design Overview

Maister users need to capture work quickly and start research, planning, or development from an issue without turning workflow state into a second backlog. The design gives all supported hosts one auditable handoff model while preserving existing direct-text invocation and task-path resume.

The chosen architecture is a layered provider boundary with immutable handoff snapshots. A thin host-facing workflow delegates reference parsing, capability discovery, provider dispatch, exact JSON validation, error normalization, and redaction to a small Node ESM boundary. The live tracker remains authoritative for issue content and lifecycle, while Maister owns the captured input, phase decisions, and resume state. Provider support grows through sequential vertical tracers and a shared conformance contract rather than a speculative public SDK.

Key decisions:

  • Provider differences are represented explicitly as native, emulated, unsupported, or unknown, with transport, permission, and constraint metadata.
  • Handoff resolves and reads an issue once, persists an immutable snapshot before task initialization, and reports later drift without rewriting history.
  • External writes require an explicit capture/create action; workflow start, resume, and completion have no implicit tracker side effects.
  • Canonical plugin behavior is transformed into generated host variants; generated outputs remain projections rather than edit targets.
+

Architecture

System Context (C4 Level 1)

[Software practitioner]
+    | capture/select/start workflow through host-native skill UX
+    v
+[Maister Issue-to-Workflow System]
+    | read/create through provider contract       | persist workflow provenance, snapshots, plans
+    +--------------------------------------------> [Configured Issue Tracker]
+    |                                              (Local Markdown or GitHub)
+    |
+    | execute research / quick-plan / development with immutable input
+    v
+[Maister Workflow Engine]
+    | host-native invocation and presentation
+    v
+[Claude Code | Codex | Cursor | Kiro]

The practitioner invokes a host-native Maister skill, but the issue contract and handoff semantics are host-independent. Trackers own live issues; the workflow engine owns execution state and derived artifacts. Host surfaces render the same canonical behavior within their native constraints.

+

Container Overview (C4 Level 2)

[Host UX / Workflow Skills]
+    | exact request envelope
+    v
+[Provider Boundary: Node ESM]
+    | parse/refine ref  | capabilities  | typed result/error
+    +-------------------+---------------+
+    |                                   |
+    v                                   v
+[Local Markdown Provider]          [GitHub Provider]
+    | locked CAS + atomic replace       | preselected REST/CLI transport
+    v                                   v
+[Local Issue Record Store]         [GitHub Issues API]
+
+[Provider Boundary]
+    | immutable normalized snapshot before initialization
+    v
+[Handoff Coordinator]
+    | root source_issue pointer         | durable source block
+    v                                   v
+[Workflow State + Intake Artifacts] [Quick-Plan Artifact]
+    |                                     |
+    +--------------- resume/handoff ------+
+                    v
+             [Workflow Engine]
+
+[Canonical Plugin + Platform Adapters] -- deterministic build --> [Host-Native Variants]
+
Host UX / Workflow Skills

Expose configure, capture, list, show, select, and start-from-issue behavior with explicit user intent.

Provider Boundary

Enforce exact contracts, normalize capabilities and errors, choose transport before dispatch, and redact secrets.

Provider Adapters

Translate the common contract to Local Markdown or GitHub without leaking vendor semantics into workflows.

Handoff Coordinator

Freeze the exact issue input, then initialize a workflow or durable plan transactionally.

Workflow Persistence

Retain provenance, snapshots, phase state, gates, and portable plan artifacts without mirroring tracker lifecycle.

Build Pipeline

Generate host-native projections from canonical behavior and validate semantic parity.

+

Key Components

+ + + + + + + +
ComponentPurposeResponsibilitiesKey InterfacesDependencies
Issue Tracker Skill UXProvides a consistent, explicit user journey across hosts.Configure and preflight providers.
Capture exactly one issue.
List, show, and select bounded results.
Start a workflow from a selected issue.		Host-native invocation; exact request envelopes.Canonical plugin model; host adapters; Provider Boundary.
Provider BoundaryCreates one fail-closed execution seam.Parse refs and aliases.
Validate exact JSON.
Discover capabilities and preselect transport.
Normalize errors and redact secrets.		resolve, create, read, bounded list, capabilities.Node.js; validated configuration; provider adapters.
Local Markdown ProviderSupplies an offline, reviewable first tracer.Manage UUID records.
Validate containment, metadata, and symlinks.
Use locks and CAS.
Publish atomically.		Common provider operations and normalized envelopes.Ordinary local filesystem; Local Issue Record Store.
GitHub ProviderProves the seam against hosted/network failures.Resolve refs and URLs.
Create/read/list with PR guards.
Honor auth, pagination, rate, and version constraints.
Return ambiguous_commit.		Common operations over one preselected REST or CLI transport.GitHub Issues; external credentials.
Handoff CoordinatorConverts a live issue into deterministic workflow input.Re-read and normalize issue.
Persist ref, revision, digest, snapshot.
Initialize exactly one workflow or plan.
Report drift read-only.		Provider Boundary; workflow initialization; snapshot contracts.Unified state schema; Workflow Persistence.
Workflow PersistenceSeparates execution truth from tracker truth.Store root source_issue pointer.
Keep snapshots immutable.
Retain phase/gate/resume state.
Persist quick-plan artifacts.		State, snapshot, and plan handoff contracts.Project filesystem; Handoff Coordinator; Workflow Engine.
Platform Build and ConformancePreserves one product across four hosts.Generate variants.
Package resources and adapters.
Run contract and parity checks.
Reject drift.		Deterministic build and validation pipeline.Canonical plugin; adapters; fixtures.
+

Data Flow

Capture flow

  1. The user explicitly invokes capture and selects or confirms a configured provider and target.
  2. The skill sends one exact request to the Provider Boundary; preflight validates configuration, target, capability, permissions, and transport before dispatch.
  3. Local Markdown publishes a new UUID record transactionally, or GitHub performs one create through the preselected transport.
  4. The provider returns a normalized result with a canonical IssueRef; uncertain hosted outcomes return ambiguous_commit and are not retried automatically.
  5. Capture ends after reporting the result. It does not start a workflow or mutate tracker lifecycle metadata.
+

Issue-to-workflow handoff flow

Issue alias / canonical ref
+    -> resolve and validate
+    -> read live issue once at SourceRevision
+    -> normalize untrusted content as data
+    -> write immutable snapshot + ref/revision/digest
+    -> commit root source_issue pointer or plan source block
+    -> initialize research, quick-plan, development, or work classification
+    -> later resume from workflow state; optional drift read only

If resolution, read, validation, or snapshot persistence fails before commit, no workflow task or state is created. For research and development, the unified workflow state is the sole resume authority and points to the captured artifacts. For quick-plan, the durable Markdown plan carries the source block and remains portable across hosts; native plan UI renders that artifact rather than becoming a second authority.

+

Local update flow

Although public v1 exposes only create, the Local persistence protocol establishes safe record evolution: acquire the record lock, verify owner token and expected revision/digest, construct a full candidate, write and flush a same-directory temporary file, re-check ownership and CAS, atomically replace, then release only the owned lock. Rejection leaves bytes, permissions, and directory topology unchanged.

+

Integration Points

+ +
IntegrationDirectionContract and boundary behavior
Host-native skill surfacesInboundHost syntax maps to the same semantics; interactive decisions stay explicit.
Project configurationInboundNon-secret configuration is validated with clear precedence; credentials remain outside files and logs.
Local filesystemOutboundUUID identity, strict metadata, containment, locks, CAS, and atomic replace on supported filesystems.
GitHub IssuesOutboundVersioned REST or selected CLI; pagination, rate limits, auth, PR exclusion, and uncertain dispatch are normalized.
Workflow engine and stateInternalSnapshot-before-init feeds workflows; source_issue records provenance while state remains resume truth.
Quick-plan workflowInternalEvery host produces one canonical Markdown plan; host UI is a projection.
Build and validation pipelineInternalCanonical behavior generates host variants; conformance and drift tests protect parity.
+

Design Decisions

+ +
ADRDecisionArchitectural effect
ADR-001Use an executable provider boundary.Centralizes schema enforcement, capabilities, errors, redaction, and dispatch.
ADR-002Anchor source provenance in unified workflow state.Keeps one resume/audit anchor while snapshots and trackers retain their ownership.
ADR-003Use portable quick-plan artifacts.Makes plans auditable and transferable across hosts.
ADR-004Bound v1 mutations to capture/create.Prevents hidden handoff and resume side effects.
ADR-005Use transactional Local Markdown records.Prevents lost updates and partial publication.
ADR-006Deliver providers as sequential tracers.Stabilizes the common seam before hosted failures.
+

Concrete Examples

1 · Local capture starts research

Given Local Markdown is configured on a supported local filesystem, when a user captures “Research cache strategy” and starts research from the returned canonical ref, then exactly one UUID issue record is published, an immutable snapshot is committed before research initialization, root source_issue points to it, and the live issue is not claimed, commented on, or closed.

2 · GitHub issue becomes a portable quick plan

Given GitHub preflight confirms repository access and read capability, when a user selects an issue and invokes quick-plan, then it is read once at a recorded revision, one canonical Markdown plan with provenance is produced, each host may project it in native UI, and no tracker mutation occurs.

3 · Concurrent Local update is rejected safely

Given two agents read the same Local issue revision, when the first publishes and the second uses the stale revision, then the second receives a typed conflict, the first record remains byte-exact and valid, and no temporary file or foreign lock is removed.

+

Out of Scope

  • Comment, claim, close, label, transition, and completion receipts until a concrete caller, approval policy, and reconciliation tests exist.
  • Bidirectional synchronization between tracker lifecycle and workflow phases.
  • GitLab, Jira, and Linear providers until the Local and GitHub conformance contract stabilizes.
  • A public or dynamic provider SDK before at least three providers and real external authors establish stable extension needs.
  • Semantic merging of Local Markdown records, automated stale-lock theft, and distributed/network filesystem locking guarantees.
  • Hosted offline mutation queues or silent transport fallback after write dispatch.
  • Automatic snapshot refresh or silent merging of upstream issue changes.
  • Fully automatic Codex continuation until host-native continuation and end-to-end state behavior are verified.
+

Success Criteria

  • The same conformance suite validates exact envelopes, capabilities, typed errors, and bounded lists for Local Markdown and GitHub.
  • A failed handoff before commit creates zero workflow tasks and leaves state and artifacts byte-exactly unchanged.
  • Successful research and development handoffs persist one immutable snapshot and one root source_issue pointer; resume uses only unified state.
  • Every host produces a semantically identical canonical quick-plan artifact, and projections pass parity fixtures.
  • Concurrent Local updates commit one revision-consistent result or return a typed conflict without partial writes, leaked temporary files, or unauthorized lock removal.
  • Existing direct-text invocation, task-path resume, and repositories without tracker configuration behave unchanged.
  • Canonical changes generate all host variants deterministically, and build plus validation reports no drift.
+
+ diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/high-level-design.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/high-level-design.md new file mode 100644 index 00000000..59c98587 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/high-level-design.md @@ -0,0 +1,197 @@ +# High-Level Design: Configurable Issue Tracker Workflow + +## TL;DR +Maister adds a provider-neutral issue boundary as a small Node ESM helper with exact JSON, typed errors, and a declarative `CapabilitySet`. +Issues remain live in their tracker; workflows consume immutable snapshots and retain only a root `source_issue` provenance pointer in the unified workflow state. +Local Markdown is the first tracer, GitHub the second; v1 mutates trackers only through explicit capture/create. +Portable `.maister/plans/*.md` files are canonical quick-plan handoff artifacts, while host-native plan UI is a projection. + +## Key Decisions +- Use one executable provider boundary instead of prose-only adapters or a command-template DSL — this centralizes validation, redaction, and cross-host semantics ([ADR-001](decision-log.md#adr-001-use-an-executable-provider-boundary)). +- Keep tracker data and workflow execution state under separate ownership, with root `source_issue` provenance after state-schema unification ([ADR-002](decision-log.md#adr-002-anchor-source-provenance-in-workflow-state)). +- Persist quick plans as portable Markdown artifacts on every host and treat native plan UI as a projection ([ADR-003](decision-log.md#adr-003-use-portable-quick-plan-artifacts)). +- Limit v1 mutations to explicit capture/create; handoff, resume, and drift checks remain read-only ([ADR-004](decision-log.md#adr-004-bound-the-v1-mutation-surface)). +- Give Local Markdown per-UUID records, per-record locks, compare-and-swap, and atomic replace only on ordinary local filesystems ([ADR-005](decision-log.md#adr-005-use-transactional-local-markdown-records)). +- Deliver Local Markdown first and GitHub second under the same conformance contract ([ADR-006](decision-log.md#adr-006-deliver-providers-as-sequential-tracers)). + +## Open Questions / Risks +- The competing workflow-state schemas must be unified and fixture-tested before adding the root `source_issue` field; dual-read behavior is not part of this design. +- Local filesystem guarantees do not extend to network or distributed filesystems; unsupported environments must fail preflight with an actionable diagnostic. +- A GitHub create timeout after dispatch may remain `ambiguous_commit`; v1 must not blindly retry or switch transport. +- Cross-host fixtures must prove that canonical quick-plan content and native UI projections cannot silently diverge. +- Fully automatic Codex continuation remains unsupported until a host-native adapter, unified state schema, and end-to-end verification exist. + +## Design Overview + +Maister users need to capture work quickly and start research, planning, or development from an issue without turning workflow state into a second backlog. The design gives all supported hosts one auditable handoff model while preserving existing direct-text invocation and task-path resume. + +The chosen architecture is a **layered provider boundary with immutable handoff snapshots**. A thin host-facing workflow delegates reference parsing, capability discovery, provider dispatch, exact JSON validation, error normalization, and redaction to a small **Node ESM boundary**. The live tracker remains authoritative for issue content and lifecycle, while Maister owns the captured input, phase decisions, and resume state. Provider support grows through sequential vertical tracers and a shared conformance contract rather than a speculative public SDK. + +**Key decisions:** + +- Provider differences are represented explicitly as `native`, `emulated`, `unsupported`, or `unknown`, with transport, permission, and constraint metadata. +- Handoff resolves and reads an issue once, persists an immutable snapshot before task initialization, and reports later drift without rewriting history. +- External writes require an explicit capture/create action; workflow start, resume, and completion have no implicit tracker side effects. +- Canonical plugin behavior is transformed into generated host variants; generated outputs remain projections rather than edit targets. + +## Architecture + +### System Context (C4 Level 1) + +```text +[Software practitioner] + | capture/select/start workflow through host-native skill UX + v +[Maister Issue-to-Workflow System] + | read/create through provider contract | persist workflow provenance, snapshots, plans + +--------------------------------------------> [Configured Issue Tracker] + | (Local Markdown or GitHub) + | + | execute research / quick-plan / development with immutable input + v +[Maister Workflow Engine] + | host-native invocation and presentation + v +[Claude Code | Codex | Cursor | Kiro] +``` + +The practitioner invokes a host-native Maister skill, but the issue contract and handoff semantics are host-independent. Trackers own live issues; the workflow engine owns execution state and derived artifacts. Host surfaces render the same canonical behavior within their native constraints. + +### Container Overview (C4 Level 2) + +```text +[Host UX / Workflow Skills] + | exact request envelope + v +[Provider Boundary: Node ESM] + | parse/refine ref | capabilities | typed result/error + +-------------------+---------------+ + | | + v v +[Local Markdown Provider] [GitHub Provider] + | locked CAS + atomic replace | preselected REST/CLI transport + v v +[Local Issue Record Store] [GitHub Issues API] + +[Provider Boundary] + | immutable normalized snapshot before initialization + v +[Handoff Coordinator] + | root source_issue pointer | durable source block + v v +[Workflow State + Intake Artifacts] [Quick-Plan Artifact] + | | + +--------------- resume/handoff ------+ + v + [Workflow Engine] + +[Canonical Plugin + Platform Adapters] -- deterministic build --> [Host-Native Variants] +``` + +Container responsibilities: + +- **Host UX / Workflow Skills:** expose configure, capture, list, show, select, and start-from-issue behavior with explicit user intent. +- **Provider Boundary:** enforce exact input/output contracts, normalize capabilities and errors, choose transport before dispatch, and redact secrets. +- **Provider Adapters:** translate the common contract to Local Markdown or GitHub without leaking vendor semantics into workflows. +- **Handoff Coordinator:** freeze the exact issue input, then initialize a workflow or durable plan transactionally. +- **Workflow Persistence:** retain provenance, snapshots, phase state, gates, and portable plan artifacts without mirroring tracker lifecycle. +- **Build Pipeline:** generate host-native projections from canonical behavior and validate semantic parity. + +## Key Components + +| Component | Purpose | Responsibilities | Key Interfaces | Dependencies | +|---|---|---|---|---| +| Issue Tracker Skill UX | Provides a consistent, explicit user journey across hosts. | Configure and preflight providers.
Capture exactly one issue.
List, show, and select bounded results.
Start a workflow from a selected issue. | Host-native skill/command invocation; exact request envelopes to Provider Boundary. | Canonical plugin model; host adapters; Provider Boundary. | +| Provider Boundary | Creates one fail-closed execution seam for all providers. | Parse canonical refs and unambiguous aliases.
Validate exact JSON schemas.
Discover capabilities and preselect transport.
Normalize typed errors and redact secrets. | `resolve`, `create`, `read`, bounded `list`, and `capabilities` operations. | Node.js runtime; validated project configuration; provider adapters. | +| Local Markdown Provider | Supplies an offline, reviewable first tracer with transactional behavior. | Manage UUID-backed records.
Validate containment, metadata, and symlink safety.
Use per-record locks and CAS.
Publish through same-directory atomic replacement. | Common provider operations and normalized result envelopes. | Ordinary local filesystem; Local Issue Record Store. | +| GitHub Provider | Proves the provider seam against a hosted tracker and network failures. | Resolve GitHub refs and URLs.
Create/read/list issues with PR guards.
Honor auth, pagination, rate, and version constraints.
Return `ambiguous_commit` when dispatch outcome is uncertain. | Common provider operations over one preselected REST or CLI transport. | GitHub Issues; external credentials kept outside repository config. | +| Handoff Coordinator | Converts a live issue into deterministic workflow input without tracker mutation. | Re-read and normalize the selected issue.
Persist ref, revision, digest, and immutable snapshot.
Initialize exactly one workflow or plan after snapshot success.
Report later drift read-only. | Provider Boundary; workflow initialization; snapshot and provenance contracts. | Unified workflow-state schema; Workflow Persistence. | +| Workflow Persistence | Separates execution truth from tracker truth. | Store root `source_issue` provenance pointer.
Keep snapshots and intake metadata immutable.
Retain phase/gate/resume state.
Persist canonical quick-plan handoff artifacts. | Workflow state contract; intake snapshot contract; plan handoff contract. | Local project filesystem; Handoff Coordinator; Workflow Engine. | +| Platform Build and Conformance | Preserves one product across Claude, Codex, Cursor, and Kiro. | Generate host-native variants from canonical sources.
Package helper resources and invocation adapters.
Run provider contract fixtures and host parity checks.
Reject generated drift. | Deterministic build and validation pipeline. | Canonical plugin; platform adapters; conformance fixtures. | + +## Data Flow + +### Capture flow + +1. The user explicitly invokes capture and selects or confirms a configured provider and target. +2. The skill sends one exact request to the Provider Boundary; preflight validates configuration, target, capability, permissions, and transport before dispatch. +3. Local Markdown publishes a new UUID record transactionally, or GitHub performs one create through the preselected transport. +4. The provider returns a normalized result with a canonical `IssueRef`; uncertain hosted outcomes return `ambiguous_commit` and are not retried automatically. +5. Capture ends after reporting the result. It does not start a workflow or mutate tracker lifecycle metadata. + +### Issue-to-workflow handoff flow + +```text +Issue alias / canonical ref + -> resolve and validate + -> read live issue once at SourceRevision + -> normalize untrusted content as data + -> write immutable snapshot + ref/revision/digest + -> commit root source_issue pointer or plan source block + -> initialize research, quick-plan, development, or work classification + -> later resume from workflow state; optional drift read only +``` + +If resolution, read, validation, or snapshot persistence fails before commit, no workflow task or state is created. For research and development, the unified workflow state is the sole resume authority and points to the captured artifacts. For quick-plan, the durable Markdown plan carries the source block and remains portable across hosts; native plan UI renders that artifact rather than becoming a second authority. + +### Local update flow + +Although public v1 exposes only create, the Local persistence protocol establishes safe record evolution: acquire the record lock, verify owner token and expected revision/digest, construct a full candidate, write and flush a same-directory temporary file, re-check ownership and CAS, atomically replace, then release only the owned lock. Rejection leaves bytes, permissions, and directory topology unchanged. + +## Integration Points + +| Integration | Direction | Contract and boundary behavior | +|---|---|---| +| Host-native skill surfaces | Inbound | Host syntax maps to the same configure/capture/list/show/select/start semantics; interactive decisions stay explicit. | +| Project configuration | Inbound | Non-secret provider configuration is validated with clear precedence and fail-closed preflight; credentials remain outside project files and logs. | +| Local filesystem | Outbound | Issue records use UUID identity, strict bounded metadata, containment checks, locks, CAS, and atomic replace only on supported ordinary local filesystems. | +| GitHub Issues | Outbound | A versioned REST contract or explicitly selected CLI transport supplies create/read/list; pagination, rate limits, auth, PR exclusion, and uncertain dispatch are normalized. | +| Workflow engine and state | Internal | Snapshot-before-init feeds research/development; root `source_issue` records provenance while workflow state remains the sole phase/resume truth. | +| Quick-plan workflow | Internal | Every host produces one canonical Markdown plan with source provenance; host UI is a projection. | +| Build and validation pipeline | Internal | Canonical behavior and adapters generate host variants; conformance and drift tests protect parity. | + +## Design Decisions + +| ADR | Decision | Architectural effect | +|---|---|---| +| [ADR-001](decision-log.md#adr-001-use-an-executable-provider-boundary) | Use an executable provider boundary. | Centralizes schema enforcement, capabilities, errors, redaction, and dispatch behavior. | +| [ADR-002](decision-log.md#adr-002-anchor-source-provenance-in-workflow-state) | Anchor source provenance in unified workflow state. | Keeps one resume/audit anchor while snapshots hold content and trackers hold live state. | +| [ADR-003](decision-log.md#adr-003-use-portable-quick-plan-artifacts) | Use portable quick-plan artifacts. | Makes plans auditable and transferable across all supported hosts. | +| [ADR-004](decision-log.md#adr-004-bound-the-v1-mutation-surface) | Bound v1 mutations to explicit capture/create. | Prevents handoff and resume from acquiring hidden external side effects. | +| [ADR-005](decision-log.md#adr-005-use-transactional-local-markdown-records) | Use transactional Local Markdown records. | Prevents lost updates and partial publication on supported local filesystems. | +| [ADR-006](decision-log.md#adr-006-deliver-providers-as-sequential-tracers) | Deliver providers as sequential tracers. | Stabilizes the common seam locally before adding hosted failure modes. | + +## Concrete Examples + +### Scenario 1: Local capture starts research + +**Given** Local Markdown is configured on a supported local filesystem, **when** a user captures “Research cache strategy” and then starts research from the returned canonical ref, **then** exactly one UUID issue record is published, an immutable issue snapshot is committed before research initialization, root `source_issue` points to that snapshot, and the live issue is not claimed, commented on, or closed. + +### Scenario 2: GitHub issue becomes a portable quick plan + +**Given** GitHub preflight confirms repository access and read capability, **when** a user selects an existing issue and invokes quick-plan, **then** the issue is read once at a recorded revision, one canonical Markdown plan containing source provenance is produced, each host may project it in native UI, and no tracker mutation occurs. + +### Scenario 3: Concurrent Local update is rejected safely + +**Given** two agents read the same Local Markdown issue revision, **when** the first publishes an update and the second attempts an update with the stale revision, **then** the second receives a typed conflict, the first record remains byte-exact and valid, and no temporary file or foreign lock is removed. + +## Out of Scope + +- Comment, claim, close, label, transition, and completion receipts until a concrete caller, approval policy, and reconciliation tests exist. +- Bidirectional synchronization between tracker lifecycle and workflow phases. +- GitLab, Jira, and Linear providers until the Local and GitHub conformance contract stabilizes. +- A public or dynamic provider SDK before at least three providers and real external authors establish stable extension needs. +- Semantic merging of Local Markdown records, automated stale-lock theft, and distributed/network filesystem locking guarantees. +- Hosted offline mutation queues or silent transport fallback after write dispatch. +- Automatic snapshot refresh or silent merging of upstream issue changes. +- Fully automatic Codex continuation until host-native continuation and end-to-end state behavior are verified. + +## Success Criteria + +- The same conformance suite validates exact request/result envelopes, capabilities, typed errors, and bounded list behavior for both Local Markdown and GitHub. +- A failed handoff before commit creates zero workflow tasks and leaves existing state and artifacts byte-exactly unchanged. +- Successful research and development handoffs persist one immutable snapshot and one root `source_issue` pointer; resume uses only the unified workflow state. +- Every host produces a semantically identical canonical quick-plan artifact, and generated native projections pass parity fixtures. +- Concurrent Local updates either commit one revision-consistent result or return a typed conflict without partial writes, leaked temporary files, or unauthorized lock removal. +- Existing direct-text workflow invocation, existing task-path resume, and repositories without tracker configuration continue to behave unchanged. +- Canonical changes generate all host variants deterministically, and the full build plus validation gate reports no generated drift. diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/research-report.html b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/research-report.html new file mode 100644 index 00000000..7d0178e6 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/research-report.html @@ -0,0 +1,336 @@ + + + + +Issue tracker workflow dla Maistera — raport badawczy + + + + + +
+ Research report +

Issue tracker workflow dla Maistera

+

Wygenerowano 2026-07-13T14:22:18Z · mixed research · Phase 1 / Step 4

+
+ +
+
4strumienie badań
+
3opcje architektury
+
2providery v1
+
87%pewność
+
6otwarte decyzje
+
+ +
+

TL;DR

+

Zaimplementować kanoniczny skill issue-tracker i mały helper Node ESM z providerami Local Markdown i GitHub. Tracker zachowuje żywe issue; workflow zapisuje pełny IssueRef, niezmienny snapshot i rewizję, a swój stan prowadzi wyłącznie w orchestrator-state.yml. v1 obejmuje configure, capture, bounded list, show/select i jawny start research/quick-plan/development — bez automatycznego close/comment/claim.

+

Key Decisions

+
    +
  • Helper wykonywalny + deklaratywne capabilities, nie prose-as-provider-API.
    • +
  • Persisted identity to maister-issue://...; skróty są tylko aliasami wejściowymi.
    • +
  • Resolve i snapshot następują przed utworzeniem workflow state; drift jest tylko sygnalizowany.
    • +
  • v1: Local Markdown + GitHub; GitLab/Jira/Linear korzystają później z tego samego kontraktu.
    • +
  • Direct prompts i istniejące resume pozostają kompatybilne.
    • +
+
+ +
+

Open Questions / Risks

+
    +
  • criticalSprzeczny workflow-state schema blokuje kanoniczne miejsce dla source_issue.
    • +
  • warningquick-plan ma różną trwałość na hostach.
    • +
  • warningMutation scope poza create nie został zatwierdzony dla v1.
    • +
  • infoLocal atomicity zakłada zwykły lokalny filesystem; konflikty Git są manualne.
    • +
+
+ + + +
+
+

1. Executive recommendation

+
+

Recommended · 87%

+

Jeden kanoniczny skill zarządza UX, zgodą i handoffem; jeden helper zarządza ref parserem, target validation, Local transactions, API/CLI transportem, exact JSON, typed errors i capability discovery. W v1 implementowane są tylko operacje mające callerów: capabilities, resolve, create, read i bounded list.

+
+ + + + + + + +
OpcjaWalidacjaTestowalnośćHost parityWerdykt
A. Prose/config1/51/52/5Dokumentacja, nie boundary
B. Deklaratywny kontrakt wykonywany przez host3/53/53/5Config, nie write engine
C. Helper + capabilities5/55/55/5Wybrać
+
+ +
+

2. Model domeny i strict ownership

+ + + + + + + + + +
ConcernTrackerSnapshot/workflow
Live title/body/comments/labels/assignees/dependenciesWłaścicielWartość as-of capture
Tracker statusWłaścicielInformacyjny snapshot
Identity i URLProvider authorityCanonical ref + użyty URL
Fazy/gates/attempts/verification/resume—orchestrator-state.yml
Comment/close/claimJawna provider operationReceipt, nigdy mirror statusu
+

Handoff = resolve + read + immutable snapshot + initialization. Drift = live revision różni się od snapshot revision; nie ma silent merge.

+
+ +
+

3. Architektura i seam locations

+ 
plugins/maister/skills/issue-tracker/
+├── SKILL.md
+├── bin/issue-tracker.mjs
+├── providers/{local,github}.mjs
+└── references/{provider-contract,issue-ref}.md
+ + + + + + + + + + +
ConcernCanonical seam
Config/setup.maister/config.yml + plugins/maister/skills/init/SKILL.md
Public UX/executionplugins/maister/skills/issue-tracker/
Unified routingplugins/maister/commands/work.md + agents/task-classifier.md
Workflow handoffresearch/SKILL.md, quick-plan/SKILL.md, development/SKILL.md
Shared provenanceorchestrator-patterns.md po naprawie schema
Host parityplatforms/{codex-cli,cursor,kiro-cli}/build.sh
+
+ +
+

4. Proponowana konfiguracja

+ 
tracker:
+  schema_version: 1
+  default_provider: local
+  providers:
+    local:
+      kind: local-markdown
+      root: .maister/issues
+    github:
+      kind: github
+      host: github.com
+      repository: openai/codex
+      transport: auto
+      api_version: "2026-03-10"
+      token_env: GITHUB_TOKEN
+  policy:
+    max_list_items: 100
+    require_write_confirmation: true
+    allow_stale_snapshot_handoff: false
+

Credentials pozostają poza repo. Precedence: pełny ref → explicit override → project default → jedyny provider → interactive choice → fail. Git remote jest tylko setup suggestion.

+
+ +
+

5. Provider contract i errors

+
+

v1 call surface

capabilities
resolve
create
read
list

+

Later, capability-gated

update
comment
setLabels
transition

+

Capability status

native
emulated
unsupported
unknown

+
+

Errors: invalid_ref, ambiguous_ref, unauthenticated, forbidden, not_found, validation, conflict, unsupported, rate_limited, unavailable, offline, precondition_failed, ambiguous_commit, provider_error.

+
    +
  • Jedna operacja wybiera jeden transport przed dispatch.
    • +
  • Read fallback tylko po pewnym non-dispatch failure.
    • +
  • Write po nieznanym dispatch nie retryuje się automatycznie.
    • +
  • Hosted offline snapshot może być użyty tylko jawnie i z stale=true; brak queued writes w v1.
    • +
+
+ +
+

6. Canonical IssueRef i aliasy

+ 
maister-issue://<provider>/<authority>/<container...>/<kind>/<native-id>
+
+maister-issue://github/github.com/openai/codex/issue/123
+maister-issue://local/workspace/issues/issue/<uuid>
+

Aliasy: gh:OWNER/REPO#123, gl:GROUP/PROJECT#123, jira:SITE/PROJ-123, lin:WORKSPACE/ENG-123, local:<uuid>. Bare #123 tylko przy jednym jednoznacznym provider/container/kind.

+
+ +
+

7. Command/skill UX

+ 
$maister:issue-tracker configure --provider local --root .maister/issues
+$maister:issue-tracker capture "Krótki tytuł" --body "..."
+$maister:issue-tracker list --status open --limit 20
+$maister:issue-tracker show gh:OWNER/REPO#123
+$maister:issue-tracker select --provider local --status open
+
+$maister:research --issue gh:OWNER/REPO#123
+$maister:quick-plan --issue maister-issue://local/workspace/issues/issue/<uuid>
+$maister:development --issue https://github.com/OWNER/REPO/issues/123
+$maister:work gh:OWNER/REPO#123
+

Capture nie uruchamia workflowu. Select/cancel jest read-only. Noninteractive JSON nie promptuje. Start workflowu nie implikuje claim/comment/close.

+
+ +
+

8. Local Markdown

+
+
Validate
schema, bounds, containment, symlinks
→ +
Stage
UUID, exclusive same-directory temp
→ +
Publish
fsync + atomic rename
→ +
Audit
canonical ref/revision/digest
+
+

Layout: .maister/issues/<uuid>.md i .maister/issues/.locks/<uuid>.lock/. Update używa owner-token lock, expected revision/digest, full candidate i atomic replace. v1 nie kradnie stale locks i nie auto-merguje konfliktów Git.

+
+ +
+

9. GitHub v1 i rozszerzenia

+
+

GitHub REST 2026-03-10

+

Guaranteed: resolve URL/alias/ref, create title/body, read issue z PR rejection, bounded repository list, auth/repository/capability preflight, canonical metadata. gh jest convenience/auth transportem; MCP opcjonalnym host adapterem.

+
+ + + + + + + +
ProviderPrzyszła adaptacja
GitLabhost + pełny project path + IID; tiered links jako extension
Jira Cloudsite/project/key, create metadata, ADF, native transition IDs
Linearworkspace/team/identifier, GraphQL cursors, team-specific states
+
+ +
+

10. `mattpocock/skills`: reuse / adapt / avoid

+
+

Reuse

  • Repo-local reviewable config
  • Neutral verbs i human titles
  • Durable briefs
  • Explicit publication approval
  • Create-first/wire-second
  • Frontier i one-ticket handoff
+

Adapt

  • Prose → typed contract + docs
  • Native fallback → recorded capability choice
  • Readiness → tracker-owned policy
  • Claim/resolve → explicit receipted operations
  • Local layout → UUID + lock/CAS
+

Avoid

  • Prose jako sole API
  • Free-form provider bez preflight
  • Bare numbers jako identity
  • Sprzeczne local layouts/status
  • Sequential IDs/edit-in-place
  • Implicit close/comment/commit
  • Credentials w config/log
+
+
+ +
+

11. End-to-end journeys

+
Local capture → research

Configure local → capture atomically → canonical ref → user wybiera research → protected re-read → snapshot/ref metadata → normalny research state → optional drift warning.

+
GitHub capture/select → quick-plan

Repo/auth preflight → one create lub bounded list/select → fetch once → trwały source block/snapshot → plan approval pozostaje mechanizmem quick-plan.

+
Existing issue → development

Validate full ref/URL → read/snapshot bez mutation → normalne analysis/spec/approval/implementation/verification → resume z task state → drift bez silent rewrite → completion mutation osobno.

+
+ +
+

12. Incremental implementation

+
    +
  1. Prerequisites: naprawić state schema; zatwierdzić quick-plan artifact i v1 mutation scope.
    2. +
  2. Contract + Local: ref/errors/capabilities/config + atomic Local create/read/list.
    3. +
  3. Handoff: source snapshot + research/quick-plan/development/work + drift.
    4. +
  4. GitHub: REST/gh transport, mocks, pagination, PR rejection, ambiguous commit.
    5. +
  5. Adapters/build/docs: canonical/platform edits, generated rebuild, full validation.
    6. +
  6. Later: mutations i GitLab/Jira/Linear po conformance suite.
    7. +
+
+ +
+

13. Risk-based tests i cross-platform impact

+ + + + + + + + + + +
PriorytetObszarKluczowy assertion
criticalContract/config/local securityExact schema, fail closed, byte/mode/topology unchanged
criticalConcurrent local writesJedna rewizja wygrywa; brak overwrite/temp leaks
criticalThree workflow handoffsJeden task na success, zero task/state na precommit failure
criticalExternal write securityFixed argv/API, target allowlist, no secret leakage, ambiguous commit
highGenerated hostsDeterministic build, arguments/resources/prompts preserved
mediumUX/Git/resilienceBounded output, no prompt in JSON mode, manual conflict behavior
+

Claude używa canonical skill; Codex kopiuje resources i transformuje commands; Cursor wymaga command-collapse/quick-plan override coverage; Kiro wymaga argument allowlist i bezpiecznych chat gates. Release gate: make build && make validate.

+
+ +
+

14. Unresolved decisions i handoff

+
    +
  1. Blocker: wybrać jeden state schema; nie implementować dual-read w providerze.
    2. +
  2. Zatwierdzić wspólny .maister/plans/*.md provenance artifact dla quick-plan.
    3. +
  3. Potwierdzić brak comment/close/claim UX w v1.
    4. +
  4. Wybrać one-step interactive Local setup lub obowiązkowy configure flow.
    5. +
  5. Ograniczyć support do ordinary local filesystems.
    6. +
  6. Odłożyć archived snapshot refresh; v1 tylko read-only drift.
    7. +
+
+

Proponowany implementation handoff

+ 
$maister:development --research=.maister/tasks/research/2026-07-13-issue-tracker-workflow
+

Pierwszy scope: prerequisites + contract/Local + handoff. GitHub jako osobny tracer-bullet po conformance suite.

+
+
+ +
+

15. Evidence i confidence

+

Całościowa pewność: 87% (średnio-wysoka). Granice własności, canonical locations, GitHub semantics i build ownership mają wysokie potwierdzenie. Wynik obniżają state schema, quick-plan provenance, mutation scope i brak realnych write tests.

+

Pełne cytowania i rozumowanie: analysis/synthesis.md oraz research-report.md.

+

Wybrane źródła oficjalne: GitHub REST Issues, GitLab Issues API, Jira Cloud Issues, Linear GraphQL.

+
+
+ + diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/research-report.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/research-report.md new file mode 100644 index 00000000..c32c97be --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/research-report.md @@ -0,0 +1,479 @@ +# Raport badawczy: issue tracker workflow dla Maistera + +## TL;DR +Zaimplementować kanoniczny skill `issue-tracker` i mały helper Node ESM z providerami Local Markdown oraz GitHub. +Tracker zachowuje żywe issue; workflow zapisuje pełny `IssueRef`, niezmienny snapshot i rewizję, a własny stan prowadzi wyłącznie w `orchestrator-state.yml`. +v1 udostępnia configure, capture, bounded list, show/select i jawny start research/quick-plan/development; bez automatycznego close/comment/claim. +Pewność rekomendacji: 87% (średnio-wysoka); przed implementacją trzeba ujednolicić workflow-state schema i zatwierdzić trwałość quick-plan. + +## Key Decisions +- Wybrać helper wykonywalny + deklaratywne capabilities, nie prose-as-provider-API. +- Utrwalać `maister-issue://...`; przyjmować krótsze aliasy wyłącznie, gdy rozstrzygają się jednoznacznie. +- Rozwiązać i zsnapshotować issue przed utworzeniem workflow state; późniejszy drift tylko sygnalizować. +- W v1 wdrożyć Local Markdown i GitHub; zostawić GitLab/Jira/Linear za tym samym kontraktem, bez pustych stubów. +- Zachować direct-prompt invocation i istniejące resume jako ścieżki równoległe. + +## Open Questions / Risks +- Sprzeczny schemat `orchestrator-state.yml` blokuje wybór jednego kanonicznego miejsca dla `source_issue`. +- `quick-plan` ma różną trwałość na hostach; rekomendowany wspólny artifact proweniencji wymaga decyzji produktowej. +- Nie jest zatwierdzone, czy v1 ma udostępniać tracker mutations poza create; raport rekomenduje osobny późniejszy etap. +- Local locks/atomic replace wymagają jasno zadeklarowanego wsparcia zwykłych lokalnych filesystemów; konflikty Git pozostają manualne. + +## 1. Executive recommendation + +**Rekomendacja (87%, średnio-wysoka):** zbudować jeden kanoniczny skill `plugins/maister/skills/issue-tracker/` i zależnościowo lekki helper `bin/issue-tracker.mjs`. Skill odpowiada za UX, autoryzację działań i handoff; helper za parser referencji, provider selection, exact schemas, filesystem/API/CLI execution, capability discovery, typed errors, redakcję, local transactions i write reconciliation. Wzorzec pasuje do istniejącego Node ESM i fail-closed runnera, a zarazem ogranicza różnice hostów ([01-maister-internals.md, „Existing Fail-Closed and Test Patterns”](../analysis/findings/01-maister-internals.md); [04-product-quality-tradeoffs.md, „Option C”](../analysis/findings/04-product-quality-tradeoffs.md)). + +W v1 publiczny produkt powinien wykonywać tylko operacje potrzebne przez realne journeys: configure/preflight, capture/create, resolve/read, bounded list, show/select oraz handoff. Docelowy kontrakt opisuje również update/comment/labels/transition, lecz ich implementacja i UX powinny wejść dopiero z konkretnym callerem i testami, zgodnie z minimal-implementation standard ([04-product-quality-tradeoffs.md, „v1 Must-Haves vs Later Capabilities”](../analysis/findings/04-product-quality-tradeoffs.md)). + +## 2. Model domeny i granica własności + +### 2.1 Ubiquitous language + +| Pojęcie | Definicja/inwariant | +|---|---| +| `Issue` | Aktualny, mutowalny work item providera. Nie jest workflowem ani źródłem resume. | +| `IssueRef` | Niezmienny kanoniczny locator: provider + authority + container + kind + native ID. | +| `TrackerProvider` | Adapter implementujący znormalizowane operacje i deklarujący capabilities. | +| `CapturedSnapshot` | Niezmienna, timestampowana treść faktycznie użyta do startu workflowu. | +| `SourceRevision` | Native version/ETag/update timestamp lub digest do drift/CAS. | +| `WorkflowTask` | Jedno wykonanie research/plan/development; wiele tasków może pochodzić z jednego issue. | +| `WorkflowState` | `orchestrator-state.yml`: jedyna prawda o fazach, gates, próbach i resume. | +| `Handoff` | Read-only resolve + read + snapshot + workflow initialization. Nie jest synchronizacją. | +| `Drift` | Live revision różni się od rewizji snapshotu; jest raportowany, nie scalany automatycznie. | + +Rozdział ten wynika bezpośrednio z projektowego persistence modelu i briefu ([`.maister/docs/project/architecture.md`, „Persistence Model`](../../../../docs/project/architecture.md); [research-brief.md, „Key Decisions”](../planning/research-brief.md)). **Pewność: 98%, wysoka.** + +### 2.2 Strict tracker-vs-workflow ownership + +| Dane/operacja | Właściciel | Co workflow zachowuje | +|---|---|---| +| Bieżący title/body/comments/labels/assignees/dependencies | Tracker | Snapshot wartości as-of capture, nie live replica | +| Tracker status i native workflow | Tracker | Status as-of capture wyłącznie informacyjnie | +| Stable identity i URL/path | Provider/tracker | Canonical `IssueRef` i użyty URL/path | +| Revision/capture time/digest | Boundary/snapshot | Dokładne metadata wejścia | +| Fazy, gates, decisions, attempts, verification, resume | Maister | Wyłącznie workflow/task state i artefakty | +| Comment/close/claim po workflow | Jawna operacja providera | Receipt/audit, nigdy automatyczne mirrorowanie statusu | + +Po inicjalizacji tracker może się zmienić. Resume używa snapshotu; opcjonalny read-only drift check zwraca `unchanged`, `changed`, `deleted_or_inaccessible` albo `unknown_offline`. Nie wolno po cichu przepisać objective ani ukończonych decyzji ([04-product-quality-tradeoffs.md, „Later tracker changes”](../analysis/findings/04-product-quality-tradeoffs.md)). **Rekomendacja: 87%.** + +## 3. Architektura v1 i dokładne seam locations + +### 3.1 Struktura kanoniczna + +```text +plugins/maister/skills/issue-tracker/ +├── SKILL.md +├── bin/ +│ └── issue-tracker.mjs +├── providers/ +│ ├── local.mjs +│ └── github.mjs +└── references/ + ├── provider-contract.md + └── issue-ref.md +``` + +Nazwy nowych plików są rekomendacją; miejsca integracji wynikają z kanonicznego/generated ownership ([01-maister-internals.md, „Canonical versus generated ownership” i „Seam Map”](../analysis/findings/01-maister-internals.md)). + +| Concern | Kanoniczna lokalizacja | Dokładna zmiana | +|---|---|---| +| Provider config/setup | `.maister/config.yml`; `plugins/maister/skills/init/SKILL.md` | Dodać walidowany `tracker` block; config bez sekretów; read-only preflight. Nie rozszerzać narrow Advisor reconciler — użyć jego transaction pattern w dedykowanym helperze. | +| Publiczny UX | `plugins/maister/skills/issue-tracker/SKILL.md` | Configure, capture, list, show, select, start. Thin commands tylko jeśli alias hosta jest naprawdę potrzebny. | +| Parser/contract/execution | `plugins/maister/skills/issue-tracker/bin/issue-tracker.mjs` | Exact JSON stdin/stdout, stderr diagnostics, fixed argv/API, typed errors, provider dispatch. | +| Unified `/work` | `plugins/maister/commands/work.md`, Steps 1/3; `plugins/maister/agents/task-classifier.md`, Phase 1/output | Resolve raz; classifier dostaje normalized snapshot; ten sam snapshot trafia do wybranego workflowu. | +| Research | `plugins/maister/skills/research/SKILL.md`, Initialization przed utworzeniem workflow | Obsłużyć `--issue`; zapisać `analysis/intake/issue-snapshot.md` i provenance przed briefem. | +| Development | `plugins/maister/skills/development/SKILL.md`, po Detect Research Context, przed Initialize Workflow | Dodać issue intake obok research/design refs; zachować precedence istniejących task paths i direct prose. | +| Quick plan | `plugins/maister/skills/quick-plan/SKILL.md` step 1 + Cursor/Kiro overrides | Resolve/snapshot przed planowaniem; zapisać source block w trwałym plan artifact. | +| Shared state contract | `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md`, obok `research_reference` | Dodać `source_issue` dopiero po ujednoliceniu state schema. Provider execution nie trafia do frameworku. | +| Platform build | `platforms/codex-cli/build.sh`, `platforms/cursor/build.sh`, `platforms/kiro-cli/build.sh` | Packaging resources, command-collapse/argument allowlists, host prompts i plan overrides; potem `make build && make validate`. | + +### 3.2 Rekomendowany snapshot layout + +Dla research/development: + +```text +analysis/intake/ +├── issue-ref.yml +└── issue-snapshot.md +``` + +`issue-ref.yml` zawiera ref, provider key/kind, retrieved_at, source revision, digest, transport, used capabilities, truncation/warnings i path snapshotu — bez credentials. `issue-snapshot.md` zachowuje normalized title/body/status/labels/URL/timestamps oraz wyraźnie oznacza treść jako niezaufaną. `orchestrator-state.yml` przechowuje tylko wspólny `source_issue` pointer/metadata, nie duplikuje body. + +**Quick-plan decision:** ujednolicić wszystkie hosty przez trwały `.maister/plans/YYYY-MM-DD-.md` z source block, nawet jeśli Claude/Codex nadal renderują plan w native planning UI. To rekomendacja o **76% pewności**; alternatywa utrzymuje różne audyty na hostach i komplikuje handoff. + +## 4. Proposed configuration shape + +```yaml +tracker: + schema_version: 1 + default_provider: local + providers: + local: + kind: local-markdown + root: .maister/issues + github: + kind: github + host: github.com + repository: openai/codex + transport: auto # api | gh | auto; MCP później jako host adapter + api_version: "2026-03-10" + token_env: GITHUB_TOKEN + policy: + max_list_items: 100 + require_write_confirmation: true + allow_stale_snapshot_handoff: false +``` + +Semantyka: + +- `.maister/config.yml` jest jedynym project-local policy source w v1; brak user-global defaults. +- Credentials nie mogą wystąpić w configu. `token_env` jest allowlisted nazwą zmiennej, nigdy wartością. +- Pełny `IssueRef` ustala provider/container. Sprzeczny `--provider` jest błędem. +- Dla capture/list bez ref precedence to: explicit override → configured default → jedyny enabled provider → interaktywne pytanie → fail w noninteractive. +- Po skonfigurowaniu nie wybierać providera z Git remote; remote służy tylko jako setup suggestion. +- Duplicate YAML keys, aliases/anchors w managed blocku, unknown kinds i unsafe paths odrzucać przed I/O i bez zmiany bajtów/mode/topology ([04-product-quality-tradeoffs.md, „Configuration Precedence and Failure Behavior”](../analysis/findings/04-product-quality-tradeoffs.md)). **Pewność: 89–92%.** + +## 5. Provider contract + +### 5.1 Envelope i operacje + +Helper przyjmuje jeden exact-schema JSON request na stdin i wypisuje jeden JSON result na stdout; diagnostics trafiają na stderr. Każdy request zawiera `schemaVersion`, `operation`, `provider`, `context`, `payload`, opcjonalny `operationId` i `precondition`. + +Docelowy kontrakt semantic: + +```text +capabilities(scope?) -> CapabilitySet +resolve(input, context) -> IssueRef +create(containerRef, draft, operationId?) -> Issue +read(issueRef, fields?) -> Issue +list(containerRef, query, page?) -> IssuePage +update(issueRef, patch, precondition?) -> Issue +comment(issueRef, body, operationId?) -> Comment +setLabels(issueRef, add[], remove[], precondition?) -> Issue +transition(issueRef, targetCategoryOrNativeTransition, precondition?) -> Issue +``` + +**Implemented/called in v1:** `capabilities`, `resolve`, `create`, `read`, bounded `list`. **Reserved, capability-gated for a later caller:** `update`, `comment`, `setLabels`, `transition`. Nie tworzyć pustych stubów; provider może raportować `unsupported` dopiero, gdy operacja jest częścią zbudowanego kontraktu testowego ([03-tracker-providers.md, „Smallest Common Operation Set”](../analysis/findings/03-tracker-providers.md); [04-product-quality-tradeoffs.md, „Minimum executable boundary”](../analysis/findings/04-product-quality-tradeoffs.md)). + +### 5.2 Normalized entities + +`Issue` zawiera tylko: `ref`, `webUrl/path`, `title`, raw-source `body`, coarse state (`open|active|done|cancelled|unknown`), labels/tags, opaque assignee refs, created/updated timestamps, `sourceRevision` i `extensions`. Nie round-tripować wszystkich providerów przez Markdown: Jira v3 używa ADF dla rich text ([Jira REST v3 introduction](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)). + +`CapabilitySet` dla każdej operacji podaje: + +```yaml +status: native | emulated | unsupported | unknown +transport: filesystem | api | cli | mcp +access: read | write +permission: +constraints: + tier: null + version: null + preview: false + fields: [] +reason: +``` + +Takie constraints są konieczne, bo np. GitLab links zależą od tieru, Jira transitions od workflow/permissions, a Linear states od teamu ([03-tracker-providers.md, „Capabilities That Must Not Be Flattened”](../analysis/findings/03-tracker-providers.md)). **Pewność: 90%.** + +### 5.3 Typed errors + +```text +invalid_ref | ambiguous_ref | unauthenticated | forbidden | not_found | +validation | conflict | unsupported | rate_limited | unavailable | +offline | precondition_failed | ambiguous_commit | provider_error +``` + +Każdy error zawiera `retryable`, opcjonalny `retryAt`, `operationDispatched: true|false|unknown`, sanitized provider status/code/request ID, constraint i actionable remediation. Nie zgadywać różnicy 403/404 dla private resources. Linear może zwrócić GraphQL errors z HTTP 200; parser musi sprawdzać envelope, nie tylko status ([Linear GraphQL, „Handling errors”](https://linear.app/developers/graphql#handling-errors)). + +### 5.4 Auth, offline, pagination, transport i idempotency + +- **Auth:** Local używa OS permissions. GitHub v1 używa fine-grained token/GitHub App/OAuth/`gh` auth z repo-specific Issues read/write; nie logować headerów/tokenów ([GitHub REST authentication](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api)). +- **Offline:** Local ma `offlineRead=true`, `offlineWrite=true`. Hosted providers nie mają authoritative offline read/write; jawnie wybrany cached snapshot może uruchomić workflow tylko z `stale=true`. Nie kolejkować writes w v1. +- **Pagination:** wszystkie listy mają `limit`, cursor/page metadata i `complete`; GitHub ma domyślnie 30 i `Link` pagination ([GitHub REST pagination](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)). +- **Rate limits:** honorować `Retry-After` i provider headers; GitHub ma primary i secondary/content-generation limits ([GitHub rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2026-03-10)). +- **Transport:** preflight wybiera jeden transport przed operacją. Read może fallbackować wyłącznie po pewnym non-dispatch failure. Write nie może przełączyć transportu po dispatch bez dowodu braku mutacji. +- **Idempotency:** każda mutation ma lokalny `operationId` zapisany przed dispatch. Create/comment po timeout dostaje `ambiguous_commit`; nie retry automatycznie. Reconciliation po markerze/recent items może nadal zakończyć się `ambiguous_commit`, bo przejrzane create APIs nie gwarantują ogólnego client idempotency key ([03-tracker-providers.md, „Idempotency and concurrency”](../analysis/findings/03-tracker-providers.md)). **Pewność: 85%, średnia.** + +## 6. Canonical IssueRef i aliasy + +### 6.1 Grammar + +```text +maister-issue:////...// +``` + +Przykłady: + +```text +maister-issue://github/github.com/openai/codex/issue/123 +maister-issue://gitlab/gitlab.com/group/subgroup/project/issue/123 +maister-issue://jira/acme.atlassian.net/PROJ/issue/PROJ-123 +maister-issue://linear/acme-workspace/ENG/issue/ENG-123 +maister-issue://local/workspace/issues/issue/550e8400-e29b-41d4-a716-446655440000 +``` + +Reguły: allowlist provider/kind; każdy segment percent-encoded osobno; odrzucić `.`, `..`, encoded separators, control chars i nieskonfigurowane authorities. GitHub/GitLab muszą zawierać pełny repo/project path, bo numery są container-scoped; GitLab rozróżnia globalne `id` i project-scoped `iid` ([GitLab REST, „id vs iid”](https://docs.gitlab.com/api/rest/#id-vs-iid)). Local ID jest UUIDv4/innym opaque random ID i nie zależy od slugu. + +### 6.2 Human-friendly aliases + +```text +gh:OWNER/REPO#123 +gl:GROUP/PROJECT#123 +jira:SITE/PROJ-123 +lin:WORKSPACE/ENG-123 +local: +``` + +Akceptować również allowlisted vendor URLs i `OWNER/REPO#123`. Bare `#123` jest legalne tylko, gdy dokładnie jeden configured provider/container rozstrzyga kontekst i kind. W przeciwnym razie `ambiguous_ref` zwraca kandydatów i przykłady. Alias nigdy nie zastępuje persisted canonical ref ([03-tracker-providers.md, „Canonical Reference Options”](../analysis/findings/03-tracker-providers.md)). **Pewność: 92%.** + +## 7. Command/skill UX + +Semantyka jest stała, nawet jeśli host renderuje ją jako slash command lub skill. + +### 7.1 Configure + +```text +$maister:issue-tracker configure +$maister:issue-tracker configure --provider local --root .maister/issues +$maister:issue-tracker configure --provider github --repo OWNER/REPO +``` + +Workflow: inspect → propose → show diff → validate read-only preflight → ask before config write → atomic reconciliation. GitHub setup nie tworzy labels ani issue. Brak auth kończy się guidance, nie zapisem tokenu. + +### 7.2 Capture/add + +```text +$maister:issue-tracker capture "Krótki tytuł" --body "..." +$maister:issue-tracker add "Krótki tytuł" --provider github +``` + +`add` jest aliasem UX dla `capture`, nie osobną operacją provider contract. Capture previewuje provider/target w interactive mode, tworzy dokładnie jedno issue, wypisuje canonical ref i niczego nie uruchamia automatycznie. + +### 7.3 List, show i select + +```text +$maister:issue-tracker list --status open --limit 20 +$maister:issue-tracker show gh:OWNER/REPO#123 +$maister:issue-tracker select --provider local --status open +``` + +List jest bounded i pokazuje provider/status/ref/freshness oraz incomplete marker. Select jest read-only numbered choice i zwraca jedno `IssueRef`; cancel nie mutuje. Noninteractive `--format json` nigdy nie promptuje i używa JSON-only stdout/stderr diagnostics. + +### 7.4 Start workflow from issue + +```text +$maister:research --issue gh:OWNER/REPO#123 +$maister:quick-plan --issue maister-issue://local/workspace/issues/issue/ +$maister:development --issue https://github.com/OWNER/REPO/issues/123 +$maister:work gh:OWNER/REPO#123 +``` + +`work` rozwiązuje issue raz, klasyfikuje snapshot i przekazuje go do wybranego workflowu. Direct text nadal działa. Start workflow nie oznacza claim/comment/close. Jeśli upstream jest offline, task nie powstaje, chyba że użytkownik jawnie wybrał dozwolony stale snapshot. + +## 8. Local Markdown design + +### 8.1 Layout i schema + +```text +.maister/issues/ +├── .md +└── .locks/ + └── .lock/ +``` + +Record ma strict bounded frontmatter: `schema_version`, `id`, `title`, `tracker_status`, `created_at`, `updated_at`, integer `revision`, optional labels; body pozostaje Markdown. Filename authority to UUID, slug jest wyłącznie prezentacyjny. Odrzucić duplicate keys, aliases, unsupported types, NUL, invalid UTF-8, conflict markers w managed metadata i ID niezgodne z filename ([04-product-quality-tradeoffs.md, „Record and identity design”](../analysis/findings/04-product-quality-tradeoffs.md)). **Pewność: 92%.** + +### 8.2 Atomic create + +1. Zweryfikować schema, bounds, containment i symlinks przed zapisem. +2. Wygenerować random ID; collision oznacza ponowienie ID, nigdy overwrite. +3. Zapisać kompletny record do exclusive, unpredictable temp w tym samym katalogu. +4. Ustawić mode, flush/fsync file, ponownie sprawdzić nonexistence, atomowo opublikować i gdzie wspierane fsync directory. +5. Cleanup temp/lock; po publikacji zwrócić ref i nie retry create w ciemno. + +Precedensem są `phase-continue.mjs` `atomicWrite` i Advisor config staging/rollback ([01-maister-internals.md, „Existing Fail-Closed and Test Patterns”](../analysis/findings/01-maister-internals.md)). + +### 8.3 Atomic update/concurrency + +Per-issue lock jest tworzony atomowo jako `.locks/.lock/` i zawiera owner token, PID, host, timestamp. Po locku provider czyta current record, porównuje `expected_revision`/digest, buduje pełny candidate z `revision+1`, zapisuje same-directory temp, ponownie sprawdza digest i lock ownership, atomowo replace i zwalnia wyłącznie własny token. Timeout kończy się konfliktem bez mutacji. v1 nie kradnie stale locków automatycznie. + +Niezależne creates łączą się w Git łatwiej dzięki stable random IDs. Edycje tego samego recordu mogą dać konflikt; provider odrzuca conflict markers i wymaga ręcznego rozwiązania. Nie budować semantic merge drivera w v1. **Pewność: 88%, średnia.** + +## 9. GitHub v1 i przyszłe providery + +### 9.1 GitHub execution recommendation + +Normatywna semantyka v1: GitHub REST API `2026-03-10`, headers `X-GitHub-Api-Version: 2026-03-10` i `Accept: application/vnd.github+json`; `gh 2.96+` może być convenience/auth transport z explicit `--repo`, noninteractive flags i structured JSON. MCP jest opcjonalnym host adapterem, nie core contract ([GitHub API versions](https://docs.github.com/en/rest/about-the-rest-api/api-versions?apiVersion=2026-03-10); [official `gh issue`](https://cli.github.com/manual/gh_issue)). + +Guaranteed v1 profile: + +- resolve canonical URI, GitHub issue URL, `OWNER/REPO#N`, unambiguous `#N`; +- create issue title + optional Markdown body; +- read issue i odrzucić response z `pull_request`, gdy kind=`issue`; +- bounded list repository issues z `type:issue` guard; +- preflight auth/repository/capabilities; +- canonical ref, URL, raw IDs, timestamps, coarse state, source revision i request/rate metadata. + +Provider contract może opisywać update/comment/labels/open-close, ale v1 publiczny UX nie musi ich wywoływać. Assignees, milestones, projects, issue types/fields, sub-issues i dependencies są extension capabilities; GitHub API je ma, ale permissions/context mogą je ograniczać lub silently drop metadata, więc constrained writes wymagają read-after-write verification ([GitHub REST Issues](https://docs.github.com/en/rest/issues/issues?apiVersion=2026-03-10); [GitHub issue dependencies](https://docs.github.com/en/rest/issues/issue-dependencies?apiVersion=2026-03-10)). **Pewność: 93%.** + +### 9.2 Extension path + +- **GitLab:** ten sam core, authority=host, pełny project path, project-scoped IID; state przez `state_event`; links/tier jako native extension ([GitLab Issues API](https://docs.gitlab.com/api/issues/), [Issue links](https://docs.gitlab.com/api/issue_links/)). +- **Jira Cloud:** site + project + issue key; create/edit metadata discovery, ADF, jawne transition IDs; nie mapować open/closed na write operation ([Jira issues/transitions](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/)). +- **Linear:** workspace + team + identifier/UUID; GraphQL Relay pagination, team-specific workflow states i OAuth scopes ([Linear GraphQL](https://linear.app/developers/graphql), [pagination](https://linear.app/developers/pagination)). + +Każdy nowy provider najpierw przechodzi wspólny conformance suite, potem dostaje real caller. Nie dodawać dynamicznego third-party plugin SDK w v1. + +## 10. Co dokładnie reuse/adapt/avoid z `mattpocock/skills` + +### Reuse + +- repo-local, reviewable configuration i root discovery pointer; +- provider-neutral verbs i human-readable titles z machine refs; +- canonical role vocabulary mapowane na provider labels; +- durable behavioral brief: current/desired behavior, interfaces, acceptance criteria, scope; +- explicit approval przed external publication; +- create blockers first, wire relationships second; +- parent jako index, child jako detail; +- frontier = open + unblocked + unclaimed oraz claim-before-work jako opcjonalna polityka; +- one-ticket/fresh-context handoff; +- audytowalny authorship/AI disclosure jako konfigurowalna polityka. + +### Adapt + +- prose provider guidance → validated config + typed provider contract + opcjonalna dokumentacja; +- native-first/fallback → capability negotiation z zapisanym wyborem i powodem; +- `ready-for-agent` → opcjonalna tracker-owned intake policy z jasno zdefiniowanym invariantem; +- agent brief/spec/ticket → snapshot z `derived_from`/revision i jednym authoritative input marker; +- frontier/claim/resolve → jawne operacje providerowe poza workflow state, z precondition/receipt; +- labels-as-roles → schema obejmująca oddzielnie category, readiness i native state; +- local Markdown → `.maister/issues/.md`, strict metadata, lock/CAS/atomic replace. + +### Avoid + +- prose jako jedyny executable provider API; +- free-form „Other” bez minimalnego kontraktu i preflight; +- bare numbers/paths jako trwałe identity; +- sprzeczne `.scratch/.../issues/NN-*.md` i `tickets.md` jako dwa canonical layouty; +- wspólne pole `Status:` dla triage role, claim i resolution; +- sequential IDs, „first by number”, edit-in-place i append bez lock/idempotency; +- silent fallback między native relation i body metadata bez source-of-truth; +- automatyczne close/comment/commit wynikające z samego handoff; +- przekazywanie issue content jako instrukcji modelu; +- credentials w repo config, promptach lub logs. + +Dowody: [02-mattpocock-skills.md, „Reusable Patterns” i „Weaknesses”](../analysis/findings/02-mattpocock-skills.md). **Pewność: 89–99% zależnie od wzorca.** + +## 11. End-to-end journeys + +### Journey A — Local capture → research + +1. `configure --provider local --root .maister/issues`; walidacja i atomic config write. +2. `capture "Zbadać strategię cache"`; preview, UUID, atomic record, canonical ref. +3. `show` lub oferta startu; user wybiera research. +4. Handoff re-readuje issue pod revision protection, zapisuje `analysis/intake/*`, tworzy research state i brief ze snapshotu. +5. Resume używa `orchestrator-state.yml`; read-only drift może ostrzec o zmianie local recordu. + +### Journey B — GitHub capture/select → quick plan + +1. Config ustala host/repository/transport; preflight sprawdza auth i issues capability. +2. `capture --provider github` wykonuje jeden create albo `list` + `select` wybiera istniejące issue. +3. `quick-plan --issue ` fetchuje raz, zapisuje trwały source block/snapshot i planuje z normalized objective. +4. Plan approval pozostaje mechanizmem quick-plan; tracker status nie staje się phase status. + +### Journey C — existing issue → development + +1. `$maister:development --issue `; parser waliduje provider/authority/container/kind/id. +2. Provider readuje issue, zapisuje revision/digest i snapshot; start nie mutuje trackera. +3. Development prowadzi analizę/spec/approval/implementation/verification i resume we własnym tasku. +4. Zmiana upstream generuje drift warning; snapshot i ukończone decyzje pozostają bez zmian. +5. Ewentualne completion comment/close jest późniejszą, osobną, idempotency-aware komendą. + +## 12. Incremental implementation and migration + +### Faza 0 — prerequisites + +- Ujednolicić workflow-state schema (`started_phase`/nested phases vs `current_phase`/root phases) i fixture-testować jeden kształt. +- Zatwierdzić quick-plan provenance artifact oraz mutation scope v1. + +### Faza 1 — contract + Local Markdown + +- Dodać parser `IssueRef`, exact envelopes, errors, capabilities i config validation. +- Wdrożyć Local create/read/list, atomic records, locks/CAS i JSON CLI contract. +- Dodać configure/capture/list/show/select skill UX bez workflow integrations. + +### Faza 2 — handoff + +- Dodać `source_issue` i snapshot artifacts. +- Zintegrować research, quick-plan, development i `/work`, zachowując direct prose/task paths. +- Dodać drift read-only i transactional task initialization: przy błędzie przed commit nie powstaje task/state. + +### Faza 3 — GitHub + +- REST-versioned GitHub provider + opcjonalny `gh` transport; mock fixtures, no real writes. +- Auth/repository preflight, bounded pagination, PR rejection, ambiguous-commit behavior. + +### Faza 4 — adapters/build/docs + +- Zmienić tylko canonical plugin i `platforms/`; zbudować generated variants. +- `make build`, inspect generated diff, `make validate`; zaktualizować config/ref/auth/offline/UX docs. + +### Faza 5 — later mutations/providers + +- Dopiero z zatwierdzonym callerem: update/comment/labels/transition/claim/resolve. +- GitLab, Jira, Linear kolejno po conformance suite; bez migracji istniejących `.scratch` bez jawnej komendy importu. + +Backward compatibility: brak `tracker` blocku nie zmienia istniejących workflowów ani nie tworzy `.maister/issues`; issue features są opt-in. Existing direct descriptions i task-folder resume zachowują znaczenie ([01-maister-internals.md, „Minimum Deterministic Change Set”](../analysis/findings/01-maister-internals.md)). + +## 13. Risk-based tests i cross-platform validation + +### Critical tests + +- contract fixtures Local/GitHub: resolve/create/read/list/capabilities, exact schema, bounded pagination, malformed provider output; +- config precedence i transactional rejection: duplicate/unsafe YAML, contradictory flags, exact unchanged bytes/modes/topology; +- concurrent local create/update, ID collision, stale revision, lock timeout, injected fsync/rename failure, no leaked temp/lock; +- filesystem security: traversal, absolute paths, separators/NUL, symlink root/record/lock, oversized/conflicted records; +- research/quick-plan/development handoff: snapshot/ref/revision/digest, one task on success, zero task/state on precommit failure; +- `/work`: issue resolved once, same snapshot to classifier/workflow, existing task folder still resumes; +- injection/secrets/wrong repo/expired auth/duplicate create timeout; no token in stdout/stderr/snapshot; +- external tests use mocks/fixtures only. + +### High/medium tests + +- unchanged/changed/deleted/private/offline source; resume from labeled snapshot; no silent rewrite; +- list empty/cancel/JSON/truncated/incomplete; noninteractive never promptuje; +- Git independent creates, same-record conflict, conflict markers; +- API/CLI transport preselection, missing command, rate limit/retry hint, ambiguous dispatch; +- existing config bez tracker blocku i direct workflow regression. + +### Cross-platform impact + +- **Claude:** canonical skill/helper działa bez generated adapter; thin command opcjonalny. +- **Codex:** command-to-skill transforms kopiują resources; testować collisions, invocation syntax i brak stale Claude vocabulary. +- **Cursor:** public skills są rename'owane; command aliases wymagają `merge_commands_to_skills`; quick-plan override musi dostać source artifact. +- **Kiro:** nowe public entry może wymagać command merge i `$ARGUMENTS` allowlist; external writes nie mogą odziedziczyć headless defaultu; testować chat gates/TUI/delegation/JSON agents. +- Wszystkie host-native automatic-continuation capabilities są obecnie `unsupported`; provider nie może syntetyzować odpowiedzi ani zakładać auto-gate ([01-maister-internals.md, „Cross-host automatic continuation posture”](../analysis/findings/01-maister-internals.md)). + +Release gate: `make build && make validate`, z committed generated variants i CI drift check zgodnie z [build-pipeline.md, „Build and Validate Every Platform Before Release”](../../../../docs/standards/global/build-pipeline.md). **Pewność: 99%.** + +## 14. Unresolved decisions + +1. **Workflow-state schema contradiction — blocker.** Dokumentacja i aktywny research task używają `orchestrator.started_phase` i zagnieżdżonego `orchestrator.phases`; `phase-continue.mjs` wymaga `orchestrator.current_phase` i jednego root `phases`, co potwierdzają fixtures/tests. Przed dodaniem `source_issue` wybrać jeden schema i nie implementować dual-read w providerze ([01-maister-internals.md, „Verified state-schema contradiction”](../analysis/findings/01-maister-internals.md)). **Pewność faktu: 97%.** +2. **Quick-plan persistence.** Zatwierdzić wspólny `.maister/plans/*.md` source/provenance artifact na wszystkich hostach lub jawnie zaakceptować słabszy audyt Claude/Codex. Rekomendacja: wspólny artifact. **Pewność: 76%.** +3. **Mutation scope v1.** Czy poza create wystawić comment/close/claim? Rekomendacja: nie; zachować contract semantics, ale wdrażać dopiero z osobnym UX i approval/receipt. **Pewność: 85%.** +4. **Interactive first-use.** Czy zaoferować atomic one-step Local setup, czy odesłać do configure/init? Rekomendacja: offer z pełnym preview i confirm, bez silent config write. **Pewność: 78%.** +5. **Network filesystems.** Zdefiniować v1 jako supported na ordinary local filesystem; w innych przypadkach preflight/fail diagnostic. **Pewność: 80%.** +6. **Snapshot refresh.** Rekomendacja v1: read-only drift; archived explicit refresh później. **Pewność: 91%.** + +## 15. Confidence i implementation handoff + +Całościowa pewność: **87% (średnio-wysoka)**. Granice własności, canonical locations, GitHub semantics i build ownership mają wysokie potwierdzenie. Wynik obniżają nierozstrzygnięte schema state, quick-plan provenance, mutation scope i brak realnych write tests/network-filesystem qualification. Szczegółowy reconciliation log znajduje się w [analysis/synthesis.md](../analysis/synthesis.md). + +Po zatwierdzeniu decyzji z §14 proponowany handoff do nowej sesji: + +```text +$maister:development --research=.maister/tasks/research/2026-07-13-issue-tracker-workflow +``` + +Pierwszy development scope powinien obejmować wyłącznie Fazy 0–2 (schema prerequisite, contract + Local Markdown + handoff); GitHub można utrzymać jako osobny tracer-bullet po przejściu local/provider conformance suite. diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/solution-exploration.html b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/solution-exploration.html new file mode 100644 index 00000000..ffb41d1c --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/solution-exploration.html @@ -0,0 +1,238 @@ + + + + +Eksploracja rozwiązań — issue-tracker-workflow + + + + +
+ solution exploration +

Issue tracker workflow dla Maistera

+

Konfigurowalne providery, szybkie capture i jawny handoff issue → workflow.

+
+
+
18alternatyw
+
6obszarów decyzji
+
6wybranych wariantów
+
86%pewność kierunku
+
+
+

TL;DR

+

Najsilniejszy wariant łączy mały helper Node ESM z deklaratywnymi capabilities, korzeniowym source_issue i trwałym artifactem quick-plan na każdym hoście. v1 dostarcza Local Markdown, następnie GitHub, i ogranicza mutacje do jawnego capture; handoff pozostaje read-only. Local Markdown używa atomic replace, per-record lock i CAS tylko na zwykłych lokalnych filesystemach. Najpierw trzeba ujednolicić schema orchestrator-state.yml.

+

Key Decisions

+
    +
  • Executable helper Node ESM z exact JSON i deklaratywnym CapabilitySet.
    • +
  • Korzeniowy source_issue wskazuje immutable snapshot, nie live backlog.
    • +
  • Wspólny .maister/plans/*.md także przy native plan UI.
    • +
  • Tylko capture/create jako mutation UX w v1.
    • +
  • Local Markdown jako tracer; GitHub jako drugi provider za tym samym contractem.
    • +
+

Open Questions / Risks

+
    +
  • criticalSprzeczne warianty state schema blokują bezpieczne dodanie source_issue.
    • +
  • warningGwarancje lock/rename/fsync nie obejmują network filesystems.
    • +
  • warningGitHub timeout po dispatch może pozostać ambiguous_commit.
    • +
  • infoQuick-plan artifact wymaga testów parytetu Claude/Codex/Cursor/Kiro.
    • +
+
+ +
+
+

1. Metoda i dywergencja

+
+

Obszary są sekwencyjne: boundary → proweniencja → quick-plan → mutacje → Local persistence → rollout. Macierze stosują T (wykonalność, 25%), U (user impact, 20%), S (prostota, 20%), R (ryzyko/odwracalność, 25%) i Sc (skalowalność, 10%); wynik jest ważony pewnością dowodów.

+
HMW
    +
  1. Ten sam bezpieczny UX na hostach bez wymazywania natywnych ograniczeń.
    2. +
  2. Start z żywego issue bez replikowania backlogu w workflow state.
    3. +
  3. Szybkie capture gwarantujące dokładnie jeden zapis i jednoznaczny wynik.
    4. +
  4. Audytowalny quick-plan mimo różnej trwałości hostów.
    5. +
  5. Bezpieczny Local Markdown przy równoległych agentach bez bazy danych.
    6. +
  6. Seam na przyszłych providerów bez spekulacyjnego SDK.
    7. +
+
SCAMPER

Substitute: prose → helper. Combine: snapshot + state pointer. Adapt: trwały brief → plan artifact. Modify: mutation surface → create. Put to other use: reuse atomic-write patterns. Eliminate: równoległy rollout obu providerów. Reverse: snapshot + drift zamiast live sync.

+
+
+ +
+

2. Decyzja 1 — granica wykonawcza providerów

+
+

1A · Prose + narzędzia hosta

Skill opisuje wywołania gh, filesystem lub MCP bez wspólnego runtime. Zachowuje lekkość wzorców mattpocock/skills, lecz rozprasza walidację i błędy.

Pros
Mało kodu; escape hatches; szybki prototyp.

Cons
Słaby parytet i testowalność; powielona redakcja/quoting; brak fail-closed contractu.

Evidence
Dobry UX, lecz niejednoznaczne refs i nieatomowe writes. 94%.

+

1B · Command templates

Config definiuje komendy i mapowania, które wykonuje host. Powstaje jednak mały DSL dla quoting, exit status, retry i parsing.

Pros
Bez SDK; konfigurowalność; umiarkowana przenośność.

Cons
Host-dependent semantics; trudne rejection; injection surface.

Evidence
Zgodne z docs-as-code, ale bez bezpiecznego precedensu ogólnego DSL. 82%.

+

1C · Helper Node ESM + capabilities

Skill jest UX, a helper obsługuje exact JSON, refs, dispatch, typed errors, redaction i local transactions. CapabilitySet zachowuje różnice vendorów.

Pros
Jeden boundary; parytet; testy; precedent phase-continue.mjs.

Cons
Więcej kodu; cross-host packaging; krytyczna granica bezpieczeństwa.

Evidence
Silny lokalny precedent, bez realnych provider writes. 87%.

+
+
OpcjaTUSRScWażonyConfidence-adjusted
1A334122.652.49
1B333343.102.54
1C544544.503.92
+
Rekomendacja: 1C. Jedyny wariant spełniający parytet, fail-closed validation i testowalność bez pełnego frameworka. Pewność 87%.
+
+ +
+

3. Decyzja 2 — kanoniczna kotwica source_issue

+
+

2A · Root source_issue

Top-level block state zawiera ref, revision, digest, czas i ścieżki intake. Położenie poza spornym układem phases oddziela proweniencję od mechaniki faz.

Pros
Jeden audit/resume anchor; drift check; brak body w state.

Cons
Schema migration; quick-plan potrzebuje analogii; trzeba jasno zachować ownership.

Evidence
State jako resume truth + ref/snapshot/pointer model. 86%.

+

2B · Authoritative intake manifest

issue-ref.yml jest źródłem proweniencji, a state ma tylko pointer lub digest. Omija konflikt schema, ale resume zależy od drugiego authoritative pliku.

Pros
Mała zmiana state; elastyczne metadata; immutable snapshot.

Cons
Dwa pliki resume; drift między nimi; słabszy single source.

Evidence
Dobry intake layout, ale napięcie z obecnym state contract. 80%.

+

2C · Workflow-specific fields

Research, development i quick-plan utrzymują osobne pola i snapshot paths. Zmniejsza zmianę frameworka, lecz powiela tę samą domenę.

Pros
Lokalne zmiany; niezależna ewolucja.

Cons
Duplikacja; trudny /work; słaby parytet.

Evidence
Obecny quick-plan pokazuje koszt rozbieżności. 91%.

+
+
OpcjaTUSRScWażonyConfidence-adjusted
2A445454.303.70
2B443343.552.84
2C432222.702.46
+
Rekomendacja: 2A po ujednoliceniu state schema. Root block jest tylko pointerem; snapshot posiada treść, tracker stan żywy. Pewność 86%.
+
+ +
+

4. Decyzja 3 — proweniencja quick-plan

+
+

3A · Tylko native plan

Claude/Codex używają hostowego planu, Cursor/Kiro pliku. Minimalna zmiana, ale handoff i audyt zależą od hosta.

Pros
Niski koszt; native flow.

Cons
Brak przenośności i wspólnego audytu; nietrwały content handoff.

Evidence
Rozbieżność potwierdzona w adapterach. 92%.

+

3B · Wspólny plan file + native UI

Każdy host zapisuje .maister/plans/*.md ze source blockiem; native UI może pozostać projekcją. Plik jest canonical handoff artifactem.

Pros
Audyt; parytet; Git review; prosty development handoff.

Cons
Zmiany Claude/Codex; ryzyko dwóch kopii; gate timing.

Evidence
Trwałe briefs + istniejące Cursor/Kiro plans, bez wspólnego contractu. 76%.

+

3C · Registry bez plan content

Globalny registry wiąże issue z natywnym planem lub session ID. Ułatwia lookup, ale nie gwarantuje dostępności samego planu.

Pros
Mały artifact; wiele handoffów.

Cons
Stale pointers; global conflicts; brak content handoffu.

Evidence
Brak precedensu; persistence sprzyja osobnym artifactom. 68%.

+
+
OpcjaTUSRScWażonyConfidence-adjusted
3A535223.553.27
3B454444.203.19
3C332232.551.73

Po korekcie pewności 3A korzysta z dobrze znanego niskiego kosztu, ale odpada przez krytyczny brak przenośnego handoffu; 3C nie zachowuje treści planu.

+
Rekomendacja: 3B. Trwały plik jest canonical handoff artifactem, native UI projekcją; wymagane golden fixtures czterech hostów. Pewność 76%.
+
+ +
+

5. Decyzja 4 — mutation surface v1

+
+

4A · Tylko capture/create

Jedno jawne create; list/show/select/handoff/drift są read-only. Start i finish workflowu nie oznaczają claim/comment/close.

Pros
Mały blast radius; prosta zgoda; ambiguous-commit focus.

Cons
Ręczne aktualizacje trackera; mniej automatyzacji.

Evidence
Brak idempotency key i callerów dla kolejnych mutacji. 85%.

+

4B · Lifecycle za approval

Capture plus comment/claim/transition z approval, precondition i receipt. Wymaga modelowania różnic permissions i native workflow states już w v1.

Pros
Mniej context switching; audyt; frontier/claim.

Cons
Duża capability matrix; provider semantics; dispatch uncertainty.

Evidence
API mają częściowe wsparcie, ale brak callerów/testów. 72%.

+

4C · Dwukierunkowa synchronizacja

Start claimuje issue, fazy aktualizują status, finish komentuje i zamyka. Miesza TrackerStatus z PhaseStatus i dwa źródła prawdy.

Pros
Najwięcej automatyzacji; widoczność w trackerze.

Cons
Narusza ownership; partial failures; resume side effects; słaba przenośność.

Evidence
Analizy konsekwentnie odrzucają silent sync. 96%.

+
+
OpcjaTUSRScWażonyConfidence-adjusted
4A535534.403.74
4B352343.302.38
4C251132.252.16
+
Rekomendacja: 4A. Capture jest osobną komendą; handoff/resume nie mutują trackera. Dalsze writes wracają z callerem, approval i tests. Pewność 85%.
+
+ +
+

6. Decyzja 5 — trwałość Local Markdown

+
+

5A · UUID + lock + CAS + replace

Record per UUID ze strict frontmatter i revision. Exclusive temp/publish dla create, a dla update per-record lock, expected digest i atomic replace.

Pros
Czytelność; Git-friendly independent creates; conflict zamiast lost update.

Cons
Cleanup/fsync; stale locks; filesystem assumptions; manual Git conflicts.

Evidence
Atomic-write precedent i analiza współbieżności. 88%.

+

5B · Append-only journal

Zmiany są eventami z operation ID, a stan jest odtwarzany lub materializowany. Redukuje overwrite, ale tworzy mały event store.

Pros
Audit log; idempotency; mniej replaces.

Cons
Ordering, compaction, recovery i projekcje; słaby human review.

Evidence
Wykonalne, ale bez precedensu i potrzeby skali. 74%.

+

5C · Git jako concurrency control

Runtime zapisuje bez locków, konflikty wykrywa commit/merge. Nie chroni jednak równoległych procesów w jednym worktree.

Pros
Mało runtime; znany conflict flow; historia.

Cons
Lost updates przed Git; duplicate capture; brak non-Git profile.

Evidence
Równoległe agents i słabość edit-in-place są potwierdzone. 93%.

+
+
OpcjaTUSRScWażonyConfidence-adjusted
5A443544.053.56
5B231452.802.07
5C425122.852.65
+
Rekomendacja: 5A. v1 wspiera ordinary local filesystems i failuje preflightem poza profilem; bez auto-steal stale locks i bez semantic merge drivera. Pewność 88%.
+
+ +
+

7. Decyzja 6 — rollout providerów

+
+

6A · Local + GitHub razem

Contract, oba providery i integracje trafiają do pierwszego release. Waliduje przenośność, ale łączy filesystem i network failure modes.

Pros
Pełna wartość; szybki common-core proof.

Cons
Szeroki blast radius; trudna diagnoza; długi feedback.

Evidence
Obie ścieżki opisane, brak conformance tests. 80%.

+

6B · Local tracer → GitHub tracer

Schema, contract i Local vertical slice z handoffem powstają pierwsze; GitHub przechodzi następnie ten sam suite. Seam dojrzewa na deterministycznym providerze przed siecią.

Pros
Małe inkrementy; offline value; szybki feedback; GitHub dowodzi seam.

Cons
Przejściowo jeden provider; ryzyko filesystem bias.

Evidence
Zgodne z incremental handoff raportu. 90%.

+

6C · SDK + czterech providerów

Najpierw publiczne SDK i GitHub/GitLab/Jira/Linear, potem workflow integration. Projektuje rozszerzenia bez realnych callerów.

Pros
Szeroka macierz; formalne extension points.

Cons
Spekulacja; auth/rich-text complexity; narusza minimal implementation.

Evidence
Różnice API potwierdzone, potrzeba SDK nie. 92%.

+
+
OpcjaTUSRScWażonyConfidence-adjusted
6A353243.252.60
6B544544.504.05
6C241152.252.07
+
Rekomendacja: 6B. Schema + contract + Local + handoff, następnie GitHub; przyszli providerzy pozostają testem seam, nie v1 implementation. Pewność 90%.
+
+ +
+

8. Zintegrowany wariant docelowy

+ 
user/host UX
+    │
+    ▼
+issue-tracker skill
+    │ exact JSON + explicit approvals
+    ▼
+Node ESM provider boundary ── capabilities / typed errors / redaction
+    ├── Local Markdown: UUID + lock + CAS + atomic replace
+    └── GitHub: versioned REST or preselected gh transport
+              │
+              ▼
+resolve + read + immutable snapshot (before workflow initialization)
+              │
+              ├── research/development → root source_issue pointer in state
+              └── quick-plan → durable .maister/plans/*.md source block
+
+Later source change → drift signal only; no silent merge, claim, comment or close
+
  1. Ujednolicić state schema i fixtures.
  2. Zdefiniować provider contract, refs, errors, config i capabilities.
  3. Dostarczyć Local capture/read/list/resolve.
  4. Dodać snapshot-before-init, source pointer, quick-plan artifact i drift.
  5. Zweryfikować cross-host build/golden fixtures.
  6. Dodać GitHub przez niezmieniony core contract.
+
+ +
+

9. Trzy strefy zakresu

+
+

In-scope

  • Project-local config bez sekretów.
  • IssueRef, capabilities, errors, Node helper.
  • Local + GitHub core operations.
  • Capture/list/show/select/start.
  • Snapshot, source pointer, plan artifact, drift.
  • Cross-host conformance i build validation.
+

Stretch

  • Archived explicit snapshot refresh.
  • GitHub metadata read-after-write.
  • Jawny import starych local layouts.
  • Read-only readiness/frontier policy.
+

Out-of-scope

  • Tracker ↔ phases sync.
  • Dynamic provider SDK/marketplace.
  • Semantic merge i network locks.
  • Hosted offline mutation queue.
  • Automatyczne commit/push/close/comment.
+
+
+ +
+

10. Odroczone pomysły

+
+ + + + + + + +
PomysłStrefaWartośćWarunek powrotu
Comment/claim/close + receiptStretchDomyka tracker UXCaller, approval, reconciliation tests
GitLabStretchNested paths, tiered capabilitiesStabilny Local+GitHub suite
JiraStretchADF i transitionsExtension model zachowuje native semantics
LinearStretchGraphQL i team statesPagination/error conformance
Provider SDKOutEkosystem adapterów3 stabilne providery i external authors
Semantic local mergeOutMniej konfliktówCzęste same-record conflicts
Hosted offline queueOutPraca bez sieciOperation log + reconciliation semantics
+
Założenia, które mogą zmienić wybór
  • Brak Node runtime ponownie otwiera decyzję 1.
  • Zakaz proweniencji w state przesuwa decyzję 2 na manifest 2B.
  • Przenośny export native plan zmniejsza koszt 3A.
  • Częste concurrent same-record updates mogą przywrócić journal 5B.
  • GitHub jako krytyczny pierwszy użytkownik może odwrócić kolejność tracerów w 6B.
+
+ +
+

11. Źródła decyzji

+
+
+
+ + diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/solution-exploration.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/solution-exploration.md new file mode 100644 index 00000000..6f1e5bce --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/outputs/solution-exploration.md @@ -0,0 +1,388 @@ +# Eksploracja rozwiązań: issue tracker workflow dla Maistera + +## TL;DR +Najsilniejszy wariant łączy mały helper Node ESM z deklaratywnymi capabilities, korzeniowym `source_issue` i trwałym artifactem quick-plan na każdym hoście. +v1 powinno dostarczyć Local Markdown, następnie GitHub, oraz ograniczyć mutacje do jawnego capture; handoff pozostaje read-only. +Local Markdown wymaga atomic replace, per-record lock i CAS, ale wyłącznie na zwykłych lokalnych filesystemach. +Łączna pewność kierunku: 86% (średnio-wysoka); najpierw trzeba ujednolicić schemat `orchestrator-state.yml`. + +## Key Decisions +- Granica providerów: wykonywalny helper Node ESM z exact JSON i deklaratywnym `CapabilitySet`. +- Proweniencja: korzeniowy `source_issue` wskazuje niezmienny snapshot, ale nie przejmuje własności backlogu. +- Quick-plan: wspólny `.maister/plans/*.md` na wszystkich hostach, także gdy host równolegle pokazuje native plan UI. +- v1 mutations: wyłącznie `capture/create`; comment, claim, close i transition są odroczone. +- Dostarczanie: Local Markdown jako tracer, potem GitHub za tym samym conformance contract. + +## Open Questions / Risks +- Sprzeczne warianty schema state (`started_phase`/nested phases i `current_phase`/root phases) muszą zostać ujednolicone przed dodaniem `source_issue`. +- Założenia o `rename`, `fsync` i lockach nie obejmują network filesystems; preflight musi ograniczyć wspierany profil v1. +- GitHub write path nie ma potwierdzonego ogólnego idempotency key; timeout po dispatch może pozostać `ambiguous_commit`. +- Trwały artifact quick-plan zmienia dotychczasową praktykę Claude/Codex i wymaga testów parytetu hostów. + +## 1. Metoda i reguły wyboru + +Eksploracja zaczęła się od dywergencji HMW/SCAMPER, a dopiero potem oceniła warianty. Porządek obszarów jest sekwencyjny: decyzja 1 ustala granicę wykonawczą, 2 miejsce proweniencji, 3 jej zachowanie dla quick-plan, 4 dozwolone mutacje, 5 protokół Local Markdown, a 6 kolejność dostarczenia. + +Każda macierz używa pięciu perspektyw w skali 1–5: **T** — wykonalność techniczna, **U** — wpływ na użytkownika, **S** — prostota, **R** — bezpieczeństwo i odwracalność, **Sc** — skalowalność/rozszerzalność. Wagi wynoszą odpowiednio 25%, 20%, 20%, 25% i 10%; wynik ważony jest następnie mnożony przez pewność dowodów, dlatego dobrze brzmiąca opcja z niską jakością dowodów nie wygrywa automatycznie. + +### 1.1 Pytania HMW + +1. Jak możemy dać każdemu hostowi ten sam bezpieczny UX trackera, zachowując jego natywne ograniczenia? +2. Jak możemy rozpocząć workflow z żywego issue, nie zamieniając workflow state w replikę backlogu? +3. Jak możemy zachować szybkie capture, a jednocześnie zagwarantować dokładnie jeden zapis i jednoznaczny rezultat? +4. Jak możemy zapewnić audytowalny quick-plan mimo różnych mechanizmów trwałości hostów? +5. Jak możemy uczynić Local Markdown bezpiecznym przy równoległych agentach bez dodawania bazy danych? +6. Jak możemy otworzyć seam na GitLab/Jira/Linear bez budowania spekulacyjnego SDK w v1? + +### 1.2 Dywergencja SCAMPER + +| Ruch | Wygenerowana możliwość | Gdzie oceniana | +|---|---|---| +| Substitute | Zastąpić prose-as-API exact-schema helperem | Obszar 1 | +| Combine | Połączyć immutable snapshot z małym pointerem w state | Obszar 2 | +| Adapt | Zaadaptować trwały brief z `mattpocock/skills` do wspólnego plan artifactu | Obszar 3 | +| Modify | Zmniejszyć mutation surface do jednego create | Obszar 4 | +| Put to other use | Użyć wzorca atomic write z continuation/Advisor config dla Local Markdown | Obszar 5 | +| Eliminate | Usunąć obowiązek równoczesnego dostarczenia GitHub z pierwszego vertical slice | Obszar 6 | +| Reverse | Zamiast synchronizować live issue do workflowu, zamrozić wejście i tylko sygnalizować drift | Obszary 2–3 | + +## 2. Obszar decyzyjny 1 — granica wykonawcza providerów + +To decyzja bazowa: kolejne obszary zakładają jeden sposób resolve/read/create, jeden model błędów i jedno capability discovery na wszystkich hostach. + +### Alternatywa 1A — instrukcje prose i bezpośrednie narzędzia hosta + +Skill opisuje, jak wywołać `gh`, filesystem lub MCP, a host wykonuje instrukcje bez wspólnej warstwy runtime. To maksymalnie przypomina lekkie wzorce `mattpocock/skills`, lecz semantyka walidacji i błędów pozostaje rozproszona w promptach i adapterach. + +**Pros:** najmniej nowego kodu; łatwe provider-specific escape hatches; szybki prototyp. + +**Cons:** słaba testowalność i parytet hostów; quoting i redakcja sekretów są powielane; brak jednego fail-closed contractu. + +**Dowody / pewność:** bezpośredni dowód z istniejących skills pokazuje dobry UX, ale także niejednoznaczne referencje i nieatomowe zapisy. Pewność oceny: 94% (wysoka). + +### Alternatywa 1B — deklaratywne command templates wykonywane przez host + +Config definiuje komendy i mapowanie pól, a każdy host uruchamia je przez własne narzędzia. Daje to wspólny opis capabilities, ale w praktyce tworzy mały język programowania obejmujący quoting, statusy wyjścia, retry i parsing. + +**Pros:** brak stałego procesu lub SDK; provider może być konfigurowany bez zmiany core; umiarkowana przenośność. + +**Cons:** semantyka procesu nadal zależy od hosta; trudne transactional rejection; command templates zwiększają powierzchnię injection. + +**Dowody / pewność:** zgodne z documentation-as-code, lecz repo nie ma precedensu bezpiecznego ogólnego command DSL. Pewność oceny: 82% (średnia). + +### Alternatywa 1C — mały helper Node ESM i deklaratywny CapabilitySet + +Skill pozostaje cienką warstwą UX, a helper obsługuje exact JSON, parser `IssueRef`, provider dispatch, typed errors, redakcję i transakcje lokalne. Provider deklaruje `native|emulated|unsupported|unknown` wraz z transportem, permissions i constraints, więc różnice vendorów nie są spłaszczane. + +**Pros:** jeden testowalny boundary; najwyższy parytet hostów; zgodność z precedensem `phase-continue.mjs`; mały dependency footprint. + +**Cons:** więcej kodu początkowego; packaging zasobów na każdym hoście; helper staje się krytyczną granicą bezpieczeństwa. + +**Dowody / pewność:** Node ESM, exact schemas i atomic write mają lokalny precedent; brak jeszcze realnych provider write tests. Pewność oceny: 87% (średnio-wysoka). + +| Opcja | T | U | S | R | Sc | Wynik ważony | Po korekcie pewności | +|---|---:|---:|---:|---:|---:|---:|---:| +| 1A | 3 | 3 | 4 | 1 | 2 | 2.65 | 2.49 | +| 1B | 3 | 3 | 3 | 3 | 4 | 3.10 | 2.54 | +| 1C | 5 | 4 | 4 | 5 | 4 | 4.50 | 3.92 | + +**Rekomendacja obszaru:** wybrać 1C. Jest jedynym wariantem, który spełnia równocześnie parytet, fail-closed validation i testowalność bez wprowadzania pełnego frameworka; łączna pewność decyzji 87%. + +## 3. Obszar decyzyjny 2 — kanoniczna kotwica `source_issue` + +Po wyborze executable boundary trzeba zdecydować, gdzie trwa identyfikacja wejścia. Niezależnie od wariantu tracker pozostaje właścicielem live issue, a body snapshotu nie może być duplikowane w state. + +### Alternatywa 2A — korzeniowy `source_issue` w `orchestrator-state.yml` + +Top-level block przechowuje canonical ref, revision, digest, retrieved_at oraz ścieżki do `analysis/intake/issue-ref.yml` i `issue-snapshot.md`. Umieszczenie obok, a nie wewnątrz spornego `orchestrator.phases`, oddziela proweniencję od mechaniki faz i zapewnia jeden anchor dla research/development. + +**Pros:** jedno miejsce audytu i resume; łatwy drift check; nie replikuje treści issue; naturalne rozszerzenie istniejącego state contractu. + +**Cons:** wymaga wersjonowania i ujednolicenia schema; quick-plan bez orchestratora potrzebuje analogicznego source blocku; błędna implementacja mogłaby sugerować własność backlogu. + +**Dowody / pewność:** architektura ustanawia state jako prawdę resume, a research potwierdza ref + snapshot + pointer. Pewność oceny: 86% (średnio-wysoka), ograniczona sprzecznością schema. + +### Alternatywa 2B — authoritative intake manifest poza state + +`analysis/intake/issue-ref.yml` jest jedynym źródłem proweniencji, a state zawiera co najwyżej ścieżkę lub digest. Rozwiązuje to konflikt schema i pozwala współdzielić manifest między różnymi workflowami, lecz resume wymaga odczytu drugiego authoritative pliku. + +**Pros:** mała zmiana state; bogatsza ewolucja metadata intake; łatwe zachowanie immutable snapshotu. + +**Cons:** dwa pliki uczestniczą w resume; większe ryzyko rozjazdu lub brakującego manifestu; słabszy single-source-of-truth audit. + +**Dowody / pewność:** layout intake jest dobrze uzasadniony, ale obecny kontrakt mówi, że state jest jedynym źródłem resume. Pewność oceny: 80% (średnia). + +### Alternatywa 2C — workflow-specific source fields + +Research, development i quick-plan definiują własne pola oraz własne miejsca snapshotu. Minimalizuje to zmianę wspólnego frameworka, ale koduje tę samą domenę w kilku kontraktach i przenosi rozbieżności hostów do warstwy trwałości. + +**Pros:** lokalne zmiany; niezależna ewolucja workflowów; brak migracji wspólnego state na starcie. + +**Cons:** duplikacja parserów i drift semantics; trudny `/work` handoff; słaba AI-nawigowalność i parytet. + +**Dowody / pewność:** aktualna rozbieżność quick-plan pokazuje koszt takiego podejścia. Pewność oceny: 91% (wysoka). + +| Opcja | T | U | S | R | Sc | Wynik ważony | Po korekcie pewności | +|---|---:|---:|---:|---:|---:|---:|---:| +| 2A | 4 | 4 | 5 | 4 | 5 | 4.30 | 3.70 | +| 2B | 4 | 4 | 3 | 3 | 4 | 3.55 | 2.84 | +| 2C | 4 | 3 | 2 | 2 | 2 | 2.70 | 2.46 | + +**Rekomendacja obszaru:** wybrać 2A po uprzednim ujednoliceniu i fixture-testowaniu jednego state schema. Root `source_issue` ma być wyłącznie pointerem proweniencji, podczas gdy snapshot przechowuje treść, a tracker — stan żywy; pewność 86%. + +## 4. Obszar decyzyjny 3 — proweniencja quick-plan między hostami + +Quick-plan nie zawsze tworzy `orchestrator-state.yml`, dlatego decyzja 2 nie wystarcza. Ten obszar wybiera wspólny trwały rezultat, z którego później może skorzystać development. + +### Alternatywa 3A — tylko native plan hosta + +Claude/Codex zachowują plan w swoim mechanizmie planowania, a Cursor/Kiro nadal zapisują plik. Jest to najmniejsza zmiana UX, ale proweniencja i możliwość handoffu zależą od hosta, na którym plan powstał. + +**Pros:** minimalny koszt; zachowuje natywny flow; brak dodatkowego artifactu dla części hostów. + +**Cons:** brak wspólnego audytu; plan może nie być dostępny po zmianie hosta; issue snapshot nie ma trwałego, przenośnego konsumenta. + +**Dowody / pewność:** rozbieżność jest potwierdzona w bieżących adapterach, lecz trwałość native UI nie jest wspólnym kontraktem Maistera. Pewność oceny: 92% (wysoka). + +### Alternatywa 3B — wspólny `.maister/plans/*.md` plus native UI + +Każdy host zapisuje minimalny trwały plan z source blockiem zawierającym ref, revision, digest i snapshot path; host może równolegle prezentować ten plan natywnie. Artifact jest formatem handoffu, nie próbą zastąpienia hostowego UI. + +**Pros:** pełny audyt i parytet; prosty development handoff; plan można reviewować w Git; wykorzystuje istniejący format Cursor/Kiro. + +**Cons:** wymaga zmian adapterów Claude/Codex; trzeba uniknąć dwóch rozbieżnych kopii planu; zapis musi nastąpić przy właściwej bramce approval. + +**Dowody / pewność:** wzorzec trwałych briefów i istniejące plany plikowe wspierają wariant, ale brak zatwierdzonego cross-host contractu. Pewność oceny: 76% (średnia). + +### Alternatywa 3C — centralny registry proweniencji bez trwałego planu + +Wspólny `.maister/issue-handoffs.yml` rejestruje powiązanie issue z natywnym planem lub identyfikatorem sesji. Ujednolica lookup, lecz nie gwarantuje, że sam plan nadal istnieje albo jest dostępny innemu hostowi. + +**Pros:** mały wspólny artifact; wiele planów może wskazywać jedno issue; łatwa enumeracja handoffów. + +**Cons:** registry może wskazywać nietrwałe obiekty; nowy globalny punkt konfliktów; nie rozwiązuje cross-host content handoffu. + +**Dowody / pewność:** brak precedensu takiego registry w projekcie, a Git-friendly persistence przemawia za osobnymi artifactami. Pewność oceny: 68% (średnia-niska). + +| Opcja | T | U | S | R | Sc | Wynik ważony | Po korekcie pewności | +|---|---:|---:|---:|---:|---:|---:|---:| +| 3A | 5 | 3 | 5 | 2 | 2 | 3.55 | 3.27 | +| 3B | 4 | 5 | 4 | 4 | 4 | 4.20 | 3.19 | +| 3C | 3 | 3 | 2 | 2 | 3 | 2.55 | 1.73 | + +Wynik po korekcie pewności nieznacznie premiuje status quo 3A, ale to efekt lepiej potwierdzonego niskiego kosztu, a nie spełnienia krytycznego wymagania parytetu. Stosujemy eliminację: 3A odpada, bo nie zapewnia przenośnego handoffu, a 3C odpada, bo registry nie zachowuje treści planu. + +**Rekomendacja obszaru:** wybrać 3B i potraktować trwały plik jako canonical handoff artifact, a native UI jako projekcję. To świadome pierwszeństwo kryterium krytycznego nad czystym rankingiem; pewność 76% i obowiązkowe golden fixtures dla czterech hostów. + +## 5. Obszar decyzyjny 4 — mutation surface w v1 + +Po ustaleniu read-only handoffu trzeba zdecydować, czy uruchomienie i zakończenie workflowu ma automatycznie zmieniać tracker. Zewnętrzne mutacje są trudniej odwracalne niż lokalny state, dlatego perspektywa ryzyka ma tu charakter eliminacyjny. + +### Alternatywa 4A — tylko jawne capture/create + +v1 pozwala utworzyć dokładnie jedno issue, ale list/show/select/handoff/drift pozostają read-only. Comment, claim, close, labels i transitions nie są publicznym UX i nie wynikają automatycznie ze startu lub zakończenia workflowu. + +**Pros:** najmniejsza powierzchnia skutków ubocznych; prosty model zgody; można dopracować ambiguous-commit reconciliation; zgodność z minimal implementation. + +**Cons:** użytkownik ręcznie aktualizuje tracker po pracy; mniej automatyzacji; część wzorców frontier/claim pozostaje poza Maisterem. + +**Dowody / pewność:** research wskazuje brak ogólnego idempotency key oraz potrzebę konkretnych callerów przed dodaniem operacji. Pewność oceny: 85% (średnio-wysoka). + +### Alternatywa 4B — capture plus comment/claim/transition za approval + +Provider oferuje podstawowy lifecycle, każda mutacja wymaga jawnego approval, precondition i receipt. Daje pełniejszy flow, lecz wymusza już w v1 model różnic między labels, assignees i native workflow states. + +**Pros:** mniej przełączania kontekstu; można adaptować frontier/claim; jawny receipt poprawia audyt. + +**Cons:** większa macierz capabilities i permissions; provider-specific semantyka; timeout po dispatch jest trudny do rozstrzygnięcia. + +**Dowody / pewność:** API dostawców wspierają część operacji, ale różnią się modelem stanu i uprawnień; nie ma jeszcze callerów/testów. Pewność oceny: 72% (średnia). + +### Alternatywa 4C — pełna synchronizacja statusu workflow ↔ tracker + +Start workflowu claimuje issue, fazy aktualizują jego status, a zakończenie komentuje i zamyka. Zapewnia atrakcyjny „one-click lifecycle”, lecz miesza TrackerStatus z PhaseStatus i tworzy dwukierunkową synchronizację dwóch źródeł prawdy. + +**Pros:** najwyższa automatyzacja; tracker pokazuje aktywność bez ręcznych kroków; łatwy monitoring zespołowy. + +**Cons:** narusza granicę własności; częściowe błędy są trudne do naprawy; drift i resume mogą wykonywać nieoczekiwane mutacje; słaba portowalność. + +**Dowody / pewność:** wszystkie analizy domenowe wspierają rozdział tracker/workflow i odrzucają silent sync. Pewność oceny: 96% (wysoka). + +| Opcja | T | U | S | R | Sc | Wynik ważony | Po korekcie pewności | +|---|---:|---:|---:|---:|---:|---:|---:| +| 4A | 5 | 3 | 5 | 5 | 3 | 4.40 | 3.74 | +| 4B | 3 | 5 | 2 | 3 | 4 | 3.30 | 2.38 | +| 4C | 2 | 5 | 1 | 1 | 3 | 2.25 | 2.16 | + +**Rekomendacja obszaru:** wybrać 4A. Capture jest osobną, jawną komendą; handoff i resume nigdy nie mutują trackera, a dalsze operacje wracają dopiero z własnym callerem, approval policy i conformance tests; pewność 85%. + +## 6. Obszar decyzyjny 5 — trwałość i współbieżność Local Markdown + +Local provider jest write path, więc zwykłe `writeFile` lub edit-in-place nie wystarcza przy równoległych agentach. Wariant musi zachować byte-exact brak zmian przy odrzuceniu i nie może polegać na kolejności nazw plików. + +### Alternatywa 5A — rekord per UUID, per-record lock, CAS i atomic replace + +Każde issue jest `.maister/issues/.md` ze strict frontmatter i integer revision. Create używa exclusive same-directory temp i atomic publish; update po atomowym locku sprawdza expected revision/digest, zapisuje pełnego kandydata i wykonuje atomic replace. + +**Pros:** czytelne pliki; niezależne creates dobrze łączą się w Git; jawny conflict zamiast lost update; reuse istniejących atomic-write patterns. + +**Cons:** złożony cleanup i fsync; stale lock wymaga operatora; gwarancje zależą od filesystemu; same-record Git conflicts pozostają manualne. + +**Dowody / pewność:** istniejące runtime i Advisor reconciliation dają bezpośredni precedent, a analiza współbieżności wspiera UUID+CAS. Pewność oceny: 88% (średnio-wysoka). + +### Alternatywa 5B — append-only journal z materializowaną projekcją + +Każda zmiana dopisuje zdarzenie z unikalnym operation ID, a list/show odtwarza aktualny stan lub czyta cache projection. Append redukuje overwrite, ale wprowadza event ordering, compaction i naprawę częściowych logów — de facto mały event store. + +**Pros:** naturalny audit log; idempotency po operation ID; brak replace tego samego rekordu dla większości operacji. + +**Cons:** znacząca złożoność; trudniejsze ręczne review; globalny lub shardowany ordering; wymaga projekcji i recovery protocol. + +**Dowody / pewność:** technicznie wykonalne, lecz brak precedensu i brak potrzeby skali uzasadniającej event store. Pewność oceny: 74% (średnia). + +### Alternatywa 5C — Git jako jedyny mechanizm współbieżności + +Provider zapisuje pliki bez runtime locków, a konflikty są wykrywane dopiero przy commit/merge. To upraszcza lokalny kod, ale równoległe procesy w jednym worktree nadal mogą nadpisać dane przed wejściem Git do gry. + +**Pros:** najmniej mechaniki runtime; znany workflow naprawy konfliktów; pełna historia po commitach. + +**Cons:** brak ochrony samego worktree; capture może się zduplikować; użytkownik poznaje konflikt zbyt późno; repo bez Git nie jest wspierane. + +**Dowody / pewność:** research wykazał równoległe użycie agentów oraz słabość sekwencyjnych IDs/edit-in-place. Pewność oceny: 93% (wysoka). + +| Opcja | T | U | S | R | Sc | Wynik ważony | Po korekcie pewności | +|---|---:|---:|---:|---:|---:|---:|---:| +| 5A | 4 | 4 | 3 | 5 | 4 | 4.05 | 3.56 | +| 5B | 2 | 3 | 1 | 4 | 5 | 2.80 | 2.07 | +| 5C | 4 | 2 | 5 | 1 | 2 | 2.85 | 2.65 | + +**Rekomendacja obszaru:** wybrać 5A, ale zadeklarować wsparcie v1 tylko dla ordinary local filesystems i failować preflightem poza tym profilem. Nie kraść stale locks automatycznie i nie budować semantic merge drivera; pewność 88%. + +## 7. Obszar decyzyjny 6 — kolejność providerów i rozszerzalność + +Ostatnia decyzja przekłada architekturę na inkrementy. Każdy wariant zachowuje Local Markdown i GitHub jako docelowe providery v1, ale różni się sposobem uzyskania dowodu, że seam naprawdę działa. + +### Alternatywa 6A — Local Markdown i GitHub równolegle w jednym wydaniu + +Kontrakt, oba providery i wszystkie integracje workflowowe powstają przed pierwszym release. Szybko pokazuje realną przenośność, lecz łączy ryzyka filesystemu, auth, pagination, rate limits i ambiguous commit w jednym kroku. + +**Pros:** pełna wartość v1 od razu; szybka walidacja common core; mniej przejściowych stanów produktu. + +**Cons:** szeroki blast radius; trudniejsze diagnozowanie kontraktu; wydłuża feedback loop; łatwo przeciążyć pierwszy scope. + +**Dowody / pewność:** obie ścieżki są dobrze opisane, ale żadna nie ma jeszcze conformance tests. Pewność oceny: 80% (średnia). + +### Alternatywa 6B — Local tracer, handoff, następnie GitHub tracer + +Najpierw powstaje schema prerequisite, contract i pełny Local vertical slice wraz z handoffem; GitHub wchodzi jako drugi tracer za tym samym suite. To pozwala skorygować seam na deterministycznym providerze przed dodaniem sieciowych failure modes. + +**Pros:** małe, weryfikowalne inkrementy; szybszy feedback; Local działa offline; GitHub dowodzi rozszerzalności zamiast ją definiować. + +**Cons:** przejściowo tylko jeden provider; możliwe dopasowanie contractu zbyt mocno do filesystemu; wymaga pilnowania provider-neutral types. + +**Dowody / pewność:** raport wskazuje dokładnie taki incremental handoff i oddzielny GitHub tracer. Pewność oceny: 90% (wysoka). + +### Alternatywa 6C — najpierw ogólne SDK i czterech hosted providerów + +Core definiuje publiczny plugin SDK, po czym GitHub, GitLab, Jira i Linear powstają przed integracją workflowową. Maksymalizuje wczesną abstrakcyjność, ale projektuje rozszerzenia bez realnych callerów i conformance feedbacku. + +**Pros:** szeroka macierz providerów; formalne extension points; mniejsze późniejsze zmiany publicznego API. + +**Cons:** spekulacyjna abstrakcja; duża powierzchnia auth i rich-text semantics; narusza minimal implementation; wysoki koszt utrzymania. + +**Dowody / pewność:** różnice oficjalnych API są dobrze potwierdzone, ale nie ma dowodu potrzeby dynamicznego third-party SDK w v1. Pewność oceny: 92% (wysoka). + +| Opcja | T | U | S | R | Sc | Wynik ważony | Po korekcie pewności | +|---|---:|---:|---:|---:|---:|---:|---:| +| 6A | 3 | 5 | 3 | 2 | 4 | 3.25 | 2.60 | +| 6B | 5 | 4 | 4 | 5 | 4 | 4.50 | 4.05 | +| 6C | 2 | 4 | 1 | 1 | 5 | 2.25 | 2.07 | + +**Rekomendacja obszaru:** wybrać 6B. Pierwszy development scope obejmuje schema prerequisite, contract, Local i handoff; GitHub jest następnym tracerem, a GitLab/Jira/Linear pozostają testem projektowym seam, nie implementacją v1; pewność 90%. + +## 8. Zintegrowany wariant docelowy + +```text +user/host UX + │ + ▼ +issue-tracker skill + │ exact JSON + explicit approvals + ▼ +Node ESM provider boundary ── capabilities / typed errors / redaction + ├── Local Markdown: UUID + lock + CAS + atomic replace + └── GitHub: versioned REST or preselected gh transport + │ + ▼ +resolve + read + immutable snapshot (before workflow initialization) + │ + ├── research/development → root source_issue pointer in state + └── quick-plan → durable .maister/plans/*.md source block + +Later source change → drift signal only; no silent merge, claim, comment or close +``` + +Sekwencja wdrożenia wynikająca z decyzji: + +1. Ujednolicić jeden state schema i jego migration/fixtures. +2. Zdefiniować exact provider contract, `IssueRef`, errors, config i capabilities. +3. Dostarczyć Local create/read/list/resolve oraz bezpieczny capture UX. +4. Dodać snapshot-before-init, root `source_issue`, quick-plan artifact i read-only drift. +5. Przepuścić ten vertical slice przez cross-host build/golden fixtures. +6. Dodać GitHub jako drugi provider korzystający z niezmienionego core contractu. + +## 9. Trzy strefy zakresu + +### In-scope + +- Project-local konfiguracja bez sekretów i jednoznaczna precedence. +- `IssueRef`, capabilities, typed errors i helper Node ESM. +- Local Markdown i GitHub: capabilities, resolve, create, read, bounded list. +- Capture/list/show/select oraz jawny start research/quick-plan/development/`work`. +- Immutable snapshot, `source_issue`, trwały quick-plan artifact i read-only drift. +- Cross-host packaging, conformance fixtures, transactional rejection i build validation. + +### Stretch + +- Jawny refresh tworzący nową zarchiwizowaną wersję snapshotu. +- Read-after-write verification dla opcjonalnych GitHub metadata. +- Import istniejących `.scratch/.../issues` lub `tickets.md` przez osobną komendę. +- Policy-based readiness/frontier jako read-only filtr po ustabilizowaniu core. + +### Out-of-scope + +- Dwukierunkowa synchronizacja tracker status ↔ workflow phases. +- Dynamiczny third-party provider SDK i marketplace providerów. +- Semantyczny Git merge driver lub wsparcie rozproszonych/network filesystem locks. +- Offline queue dla hosted mutations. +- Automatyczne commit/push/close/comment wynikające z samego handoffu lub resume. + +## 10. Odroczone pomysły + +| Pomysł | Strefa | Dlaczego warto później | Warunek powrotu | +|---|---|---|---| +| Comment/claim/close z receipt | Stretch | Domyka tracker UX i może adaptować frontier/claim | Konkretny caller, approval policy, idempotency/reconciliation tests | +| GitLab provider | Stretch | Sprawdza nested project paths i tiered capabilities | Local+GitHub conformance suite stabilny | +| Jira provider | Stretch | Sprawdza rich text i native transitions | Extension model bez spłaszczania ADF/workflows | +| Linear provider | Stretch | Sprawdza GraphQL envelope i team states | Pagination/error conformance gotowe | +| Provider SDK | Out-of-scope | Może umożliwić ekosystem adapterów | Co najmniej trzy stabilne providery i realni autorzy zewnętrzni | +| Semantic local merge | Out-of-scope | Może zmniejszyć ręczne konflikty Git | Udokumentowane częste same-record conflicts | +| Hosted offline mutation queue | Out-of-scope | Ułatwia pracę bez sieci | Trwały operation log i bezpieczna reconciliation semantics | + +## 11. Założenia zmieniające wybór + +- Jeśli Node.js przestanie być gwarantowanym runtime na którymkolwiek wspieranym hoście, obszar 1 trzeba ponownie otworzyć i porównać standalone binary z host-native execution. +- Jeśli `orchestrator-state.yml` ma pozostać absolutnie wolny od proweniencji wejścia, obszar 2 przechodzi na 2B i wymaga jawnego rozszerzenia definicji resume source. +- Jeśli native plan hosta uzyska przenośny, wersjonowany export contract, koszt 3A spada i trwały plik może stać się generowaną projekcją. +- Jeśli realne telemetry pokażą częste concurrent updates tego samego local issue, append-only model 5B może wymagać ponownej oceny. +- Jeśli GitHub jest krytycznym pierwszym użytkownikiem i Local nie ma adopcji, kolejność 6B można odwrócić, zachowując dwa osobne tracery. + +## 12. Źródła decyzji + +- [Research report](research-report.md) +- [Synthesis](../analysis/synthesis.md) +- [Project vision](../../../../docs/project/vision.md) +- [Project roadmap](../../../../docs/project/roadmap.md) +- [Technology stack](../../../../docs/project/tech-stack.md) +- [System architecture](../../../../docs/project/architecture.md) + diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-brief.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-brief.md new file mode 100644 index 00000000..027e5c2e --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-brief.md @@ -0,0 +1,42 @@ +# Research Brief: Issue Tracker Workflow for Maister + +## TL;DR +Research a provider-based issue intake layer for Maister that supports local Markdown and external trackers, makes capturing work fast, and lets any saved issue become input to a normal Maister workflow. Preserve `orchestrator-state.yml` as workflow execution state rather than turning it into a backlog. Use the installed `mattpocock/skills` conventions as a concrete comparison point. + +## Key Decisions +- Treat issue tracking as persistent work intake, separate from workflow execution state — the existing orchestrator state becomes authoritative only after a workflow starts. +- Evaluate a small common provider contract plus capability discovery — tracker-specific features should remain available without contaminating core workflows. + +## Open Questions / Risks +- The provider abstraction must not erase tracker-specific capabilities or leak credentials. +- Local Markdown needs stable identifiers and concurrency-safe writes if it is to behave like a real tracker. + +## Research Question + +How should Maister add configurable issue-tracker providers, fast task capture, and issue-to-workflow handoff while reusing good ideas from `mattpocock/skills`? + +## Scope + +Included: + +- Existing Maister commands, workflow state, task directories, and platform adapters. +- Installed `mattpocock/skills` tracker configuration, ticket creation, triage, and implementation handoff. +- Local Markdown, GitHub Issues, and an extensible provider seam for future trackers. +- Capture, list/show/select, and handoff UX for research, planning, and development. +- Testing, migration, security, offline behavior, and cross-platform generation. + +Excluded: + +- Implementing the feature during this research workflow. +- Selecting or configuring a tracker for this repository. +- Building a hosted issue-tracking product. + +## Success Criteria + +1. Document the current Maister intake and resume model with exact integration seams. +2. Compare at least three architecture options and identify their trade-offs. +3. Define a recommended provider contract and canonical issue reference format. +4. Specify the minimum commands and end-to-end user journeys. +5. Explain how saved issues feed `$maister:research`, `$maister:quick-plan`, and `$maister:development` without duplicating sources of truth. +6. Identify a migration path, test strategy, and platform-specific risks. +7. Produce an implementation-ready recommendation suitable for a later development workflow. diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-plan.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-plan.md new file mode 100644 index 00000000..61ab61cf --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-plan.md @@ -0,0 +1,192 @@ +# Research Plan: Configurable Issue Tracker Workflow + +## TL;DR +Use a mixed-method, four-stream investigation: Maister internals, installed `mattpocock/skills`, external tracker contracts, and cross-cutting product-quality trade-offs. Run the streams independently in parallel, then triangulate their evidence into provider options, a minimum user journey, and an implementation-ready recommendation. Keep issue intake separate from `orchestrator-state.yml`, which remains authoritative only after a workflow starts. + +## Key Decisions +- Use four independent gathering categories, each with one owned findings file and explicit source priorities. +- Treat local code, tests, and installed skill files as primary evidence; use official vendor documentation as primary evidence for external APIs. +- Require the synthesis to compare at least three architecture options and trace capture-to-workflow handoff across research, planning, and development. +- Score confidence per claim from evidence quality and triangulation, not from researcher certainty. + +## Open Questions / Risks +- A common provider contract may become either too weak for useful tracker features or too broad for a reliable local Markdown implementation. +- Tracker references may be ambiguous across providers, repositories, and issue/PR number spaces. +- CLI and API capabilities, authentication, rate limits, and offline behavior can change; external claims require current primary-source verification. +- Platform generation may constrain where canonical commands, configuration, and provider helpers can live. + +## Research Objective + +Answer: **How should Maister add configurable issue-tracker providers, fast task capture, and issue-to-workflow handoff while reusing good ideas from `mattpocock/skills`?** + +The final research must be detailed enough to start a later Maister development workflow without repeating discovery. It must preserve these boundaries: + +- issue tracking is persistent work intake; +- `.maister/tasks/**/orchestrator-state.yml` is execution and resume state after a workflow begins; +- generated platform variants are not edited directly; +- the feature must work without introducing a hosted service or database; +- local Markdown and GitHub are required comparison points, while future providers remain possible. + +## Methodology + +This is mixed research combining: + +1. **Technical iterative deepening** — discover components, trace invocation and state flows, identify canonical and generated ownership, then verify seams against tests. +2. **Requirements extraction** — derive functional and non-functional requirements from the brief, current workflows, and user journeys. +3. **Comparative literature review** — inspect current official tracker API/CLI documentation and compare capabilities and constraints. +4. **Multi-source triangulation** — validate important conclusions across source code, instructions, tests, configuration, and official documentation. + +Each gatherer should distinguish direct evidence, inference, and recommendation. Scope expansion is allowed only when a newly discovered dependency is necessary to answer one of the exact questions below; record other ideas as deferred. + +## Gathering Strategy + +Launch all four categories in parallel. Each gatherer owns only its expected findings file under `analysis/findings/` and must open the artifact with the required TL;DR, Key Decisions, and Open Questions / Risks sections. + +### Category 1 — Maister Internals and Platform Adapters + +**Expected output:** `analysis/findings/01-maister-internals.md` + +**Exact questions:** + +1. How do `$maister:research`, `$maister:quick-plan`, `$maister:development`, and `$maister:work` currently accept task context, initialize task directories, and persist resume state? +2. Which canonical files are the safest seams for: tracker configuration, issue reference parsing, issue retrieval, fast capture, and workflow handoff? +3. What data must be copied or linked into a workflow at initialization, and what must remain owned by the tracker to avoid two sources of truth? +4. How are canonical skills and commands transformed for Claude, Codex, Cursor, and Kiro, and which host capability differences affect subprocesses, user prompts, file access, or CLI invocation? +5. Which existing continuation, gate, config reconciliation, validation, and build tests provide patterns for fail-closed provider behavior? +6. What minimum changes would preserve the project's documentation-as-code architecture and deterministic generated variants? + +**Authoritative source priority:** + +1. Canonical files under `plugins/maister/`, especially workflow skills and `skills/orchestrator-framework/`. +2. Platform adapter scripts and overrides under `platforms/`. +3. Contract, fixture, install, and end-to-end tests under `tests/` and `platforms/*/tests/`. +4. `.maister/docs/project/` and applicable standards as supporting intent; generated `plugins/maister-*` trees only as parity checks. + +**Required evidence:** cite exact local paths and relevant headings/functions; trace at least one end-to-end current workflow initialization path; distinguish canonical source from generated output. + +### Category 2 — Installed `mattpocock/skills` Prior Art + +**Expected output:** `analysis/findings/02-mattpocock-skills.md` + +**Exact questions:** + +1. How does `setup-matt-pocock-skills` select and persist GitHub, GitLab, local Markdown, or free-form tracker configuration? +2. What implicit provider interface is encoded by `docs/agents/issue-tracker.md` phrases such as publish, fetch, list, label, comment, close, claim, resolve, blocking, and frontier? +3. How do `to-spec`, `to-tickets`, `triage`, and `implement` pass work from idea/specification through ticket publication, readiness state, and implementation? +4. Which conventions are reusable in Maister: repository-local configuration, prose adapter instructions, stable references, labels-as-roles, local file layout, dependency edges, and explicit handoff? +5. Which conventions should Maister avoid or strengthen because they are underspecified, tracker-specific, difficult to validate, or unsafe under concurrent/local writes? +6. Can the installed skills' setup-to-tickets-to-triage-to-implement journey be mapped onto Maister research, planning, development, resume, and audit semantics without duplicating state? + +**Authoritative source priority:** + +1. Installed files under `/Users/mrapacz/.agents/skills/`, read in full for setup, tracker templates, `to-spec`, `to-tickets`, `triage`, and `implement`. +2. Supporting installed skills directly referenced by that flow, including `wayfinder`, `domain-modeling`, `grilling`, `tdd`, and `code-review`, only where needed to understand handoff contracts. +3. The upstream `mattpocock/skills` repository for provenance and changes relative to the installed copy; treat local installed behavior as authoritative for what is available in this environment. + +**Required evidence:** produce an operation matrix by provider and a sequence narrative from setup through implementation; cite exact installed paths; label upstream-only observations separately. + +### Category 3 — External Tracker Provider Contracts + +**Expected output:** `analysis/findings/03-tracker-providers.md` + +**Exact questions:** + +1. What is the smallest common operation set needed for capture and handoff across local Markdown, GitHub Issues, GitLab Issues, Jira Cloud, and Linear: create, resolve reference, read, list/search, update, comment, label/state, and capability discovery? +2. Which capabilities cannot be normalized cleanly, such as sub-issues, native blocking links, issue/PR ambiguity, projects, custom workflows, assignees, or rich metadata? +3. Should providers use vendor CLIs, HTTP APIs, MCP/connectors, filesystem operations, or a layered preference/fallback model in Maister's supported hosts? +4. What canonical reference syntax can unambiguously identify provider, repository/project, issue kind, and native ID while remaining quick to type? +5. What authentication, pagination, rate-limit, error, idempotency, and offline semantics must the provider boundary expose? +6. Which current API or CLI guarantees are stable enough for an initial GitHub provider, and which assumptions require capability checks or graceful degradation? + +**Authoritative source priority:** + +1. Current official vendor API and CLI documentation, including authentication, issue operations, pagination/rate limits, and error contracts. +2. Official schemas or machine-readable API references where available. +3. Installed CLI help/version output as environment evidence, without treating local installation as a product requirement. +4. Third-party examples only to identify gaps; never use them as sole support for contract claims. + +**Required evidence:** include a provider capability matrix; record access date and source version where available; mark unsupported or unverified capabilities explicitly; do not test writes against real trackers. + +### Category 4 — UX, Domain Model, Testing, and Security Trade-offs + +**Expected output:** `analysis/findings/04-product-quality-tradeoffs.md` + +**Exact questions:** + +1. What are the minimum fast-capture, list/show/select, and handoff journeys for both interactive and explicit command use? +2. What domain vocabulary and entities prevent confusion among `Issue`, `IssueRef`, `TrackerProvider`, captured snapshot, workflow task, workflow state, status, and provider capability? +3. Should workflow initialization store a source reference, an immutable snapshot, selected normalized fields, or a combination, and how should later tracker changes be surfaced? +4. How should default provider selection, per-project configuration, command overrides, and missing/ambiguous configuration behave? +5. What failure and concurrency cases matter for local Markdown: stable IDs, atomic creation/update, duplicate slugs, multiple agents, partial writes, Git conflicts, and path traversal? +6. What security boundaries apply to credentials, untrusted issue content, command injection, prompt injection, secret leakage, URL/repository validation, and external writes? +7. What behavior-focused test matrix covers provider contracts, local persistence, mocked external providers, handoff into three workflows, platform generation, migration, rollback, and transactional rejection? +8. Which architecture options best balance a shared provider contract, tracker-specific capabilities, minimal dependencies, offline use, and cross-platform parity? + +**Authoritative source priority:** + +1. Research brief, project vision/architecture/tech-stack, and global validation/error-handling/minimal-implementation plus testing standards. +2. Existing Maister fail-closed configuration, gate persistence, atomic reconciliation, fixtures, and rollback-oriented tests as implementation precedent. +3. Installed tracker templates and workflow UX as concrete prior art. +4. Official security guidance and vendor authentication documentation for boundary-specific recommendations. + +**Required evidence:** provide a domain glossary, at least three complete user journeys, a threat/failure table, and a risk-based test matrix; separate must-have v1 behavior from later capabilities. + +## Synthesis Procedure + +The synthesizer must read all four findings files and produce `analysis/synthesis.md` plus `outputs/research-report.md`. It should: + +1. Reconcile terminology before comparing designs; use one name for each domain concept and call out conflicting source vocabulary. +2. Build a requirements matrix covering fast capture, provider selection, reference resolution, retrieval, handoff, offline behavior, security, auditability, and platform parity. +3. Compare at least three architecture options, including: + - prose/config-driven provider instructions similar to `mattpocock/skills`; + - a canonical declarative provider contract with host-adapted execution; + - a small executable provider layer/helper with declarative capabilities. +4. Evaluate each option against the same criteria: simplicity, deterministic generation, extensibility, tracker-specific escape hatches, validation, testability, security, offline behavior, migration cost, and host parity. +5. Define a recommended v1 provider contract, canonical `IssueRef` format, configuration shape, command vocabulary, and capability/error model at enough detail for implementation planning. +6. Trace at least these end-to-end journeys: + - configure local Markdown, quickly capture a task, then start research from it; + - configure GitHub, capture or select an issue, then start quick planning; + - hand an existing issue reference into development while retaining source provenance and workflow-local state. +7. Explicitly state what remains tracker-owned versus what becomes a workflow snapshot/reference, including behavior when the upstream issue changes. +8. Propose an incremental migration and test strategy that introduces no database and preserves existing direct-prompt workflow invocation. +9. Record rejected alternatives and unresolved decisions rather than silently choosing defaults. + +## Synthesis Acceptance Criteria + +The research is ready for a development handoff only if: + +- every success criterion from `planning/research-brief.md` is answered with cited evidence; +- all four findings artifacts exist and satisfy their required evidence; +- at least three architecture options are compared on a common rubric; +- the recommendation includes a provider contract, issue-reference grammar, configuration ownership, minimal commands, and fallback behavior; +- local Markdown and GitHub flows are specified end to end, with future-provider extension points identified but not overbuilt; +- workflow handoff semantics for research, quick plan, and development preserve `orchestrator-state.yml` as the resume source of truth; +- platform adapter impact and generated-artifact ownership are explicit; +- security, concurrency, migration, and behavior-focused testing risks have concrete mitigations; +- contradictions and evidence gaps remain visible in the final report. + +## Confidence Rules + +Assign confidence to each material finding and final recommendation component: + +- **High (90–100%)** — direct current evidence plus at least one independent confirmation, such as canonical code + tests, installed skill + observed config template, or official API docs + official schema/CLI help; no material contradiction. +- **Medium (60–89%)** — one authoritative source or multiple indirect sources, with minor gaps, version uncertainty, or behavior inferred but not covered by tests. +- **Low (<60%)** — proposal, extrapolation, conflicting evidence, stale/unverified external documentation, or behavior unsupported by direct evidence. + +Rules for applying scores: + +- A recommendation cannot have higher confidence than its most important unresolved dependency. +- Generated Maister variants do not independently confirm canonical behavior; tests or adapter logic are needed for triangulation. +- Upstream `mattpocock/skills` behavior does not confirm the installed version unless the files match. +- External API facts without a current official source are low confidence. +- User preference questions and product choices are decisions, not factual findings; label them as open decisions rather than assigning false certainty. + +## Planned Deliverables + +- `analysis/findings/01-maister-internals.md` +- `analysis/findings/02-mattpocock-skills.md` +- `analysis/findings/03-tracker-providers.md` +- `analysis/findings/04-product-quality-tradeoffs.md` +- `analysis/synthesis.md` +- `outputs/research-report.md` + diff --git a/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/sources.md b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/sources.md new file mode 100644 index 00000000..b203adc2 --- /dev/null +++ b/.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/sources.md @@ -0,0 +1,182 @@ +# Source Register: Configurable Issue Tracker Workflow + +## TL;DR +Primary evidence comes from Maister's canonical plugin, adapters, and tests; the installed `mattpocock/skills` files; and current official tracker documentation. Local sources listed as verified were confirmed present during planning. External URLs are planned and unverified until a gatherer records access date, applicability, and relevant evidence. + +## Key Decisions +- Prefer canonical source and tests over generated variants or descriptive documentation when determining current Maister behavior. +- Treat the installed `/Users/mrapacz/.agents/skills` copy as authoritative for locally available prior art and the upstream repository as provenance/comparison. +- Use only official vendor documentation for material API, authentication, rate-limit, and capability claims. +- Keep an explicit source status so planned sources cannot be mistaken for reviewed evidence. + +## Open Questions / Risks +- External documentation paths and API behavior may change; every planned URL needs current verification before citation. +- Some tracker capabilities depend on plan, repository settings, CLI version, or preview APIs. +- Installed skills may differ from the current upstream repository. +- Generated Maister variants can look authoritative while being derived artifacts; conclusions must trace back to canonical source or adapters. + +## Status Legend + +- **Verified local** — path was confirmed present and, where noted, read during planning. +- **Planned local** — expected local evidence to be read by a gatherer; presence or relevance still needs confirmation. +- **Planned external / unverified** — candidate primary source; URL, currency, and exact claim support must be checked during gathering. +- **Supporting** — useful context but not sufficient as sole evidence for behavior. + +## Research Foundation + +| Status | Source | Purpose | +|---|---|---| +| Verified local, read | `.maister/tasks/research/2026-07-13-issue-tracker-workflow/planning/research-brief.md` | Scope, constraints, success criteria, and initial state-ownership decisions. | +| Verified local, read | `.maister/docs/INDEX.md` | Index of project documentation and standards. | +| Verified local, read | `.maister/docs/project/vision.md` | Product goals: cross-platform parity, auditability, resumability, safety, and minimal dependencies. | +| Verified local, read | `.maister/docs/project/roadmap.md` | Current priorities and known platform/runtime assurance gaps. | +| Verified local, read | `.maister/docs/project/tech-stack.md` | Implementation constraints: Markdown/YAML, shell, Node ESM, no database, deterministic build. | +| Verified local, read | `.maister/docs/project/architecture.md` | Canonical/generated ownership, adapters, persistence, configuration, and workflow control flow. | +| Verified local, read | `/Users/mrapacz/.codex/plugins/cache/maister-local/maister/2.2.1-fork.1/skills/research/references/research-methodologies.md` | Mixed-method decomposition, triangulation, comparative analysis, and confidence scoring. | + +## Category 1 Sources — Maister Internals and Platform Adapters + +### Primary local evidence + +| Status | Source | Questions supported | +|---|---|---| +| Verified local | `plugins/maister/skills/research/SKILL.md` | Research input, initialization, task state, outputs, and handoff semantics. | +| Verified local | `plugins/maister/skills/quick-plan/SKILL.md` | Current quick-plan input contract and output behavior. | +| Verified local | `plugins/maister/skills/development/SKILL.md` | Development entry points, phase initialization, and source-context handling. | +| Verified local | `plugins/maister/commands/work.md` | Thin command delegation and unified workflow entry. | +| Verified local | `plugins/maister/skills/orchestrator-framework/SKILL.md` | Shared orchestration responsibilities and framework boundaries. | +| Verified local | `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` | Canonical state schema, phase lifecycle, gates, persistence, and context-passing rules. | +| Verified local | `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` | Host capability differences relevant to provider execution and continuation. | +| Verified local | `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs` | Executable state-validation and continuation patterns. | +| Verified local | `platforms/codex-cli/build.sh` | Codex transformation and generated-artifact impact. | +| Verified local | `platforms/cursor/build.sh` | Cursor transformation and generated-artifact impact. | +| Verified local | `platforms/kiro-cli/build.sh` | Kiro transformation and generated-artifact impact. | +| Planned local | `plugins/maister/commands/` and `plugins/maister/skills/` invocation wrappers related to research, planning, development, and quick flows | Exact command-to-skill input vocabulary and aliases. | +| Planned local | `.maister/config.yml` and configuration initialization/reconciliation paths | Current configuration ownership, defaults, validation, and atomic update patterns. | + +### Verification and precedent + +| Status | Source | Purpose | +|---|---|---| +| Verified local | `tests/phase-continue-contract.test.sh` | Contract-test pattern for state and continuation boundaries. | +| Verified local | `tests/fully-automatic-phase-continue.test.sh` | Transactional continuation and fail-closed behavior. | +| Verified local | `tests/host-capability-matrix.test.sh` | Cross-host capability validation precedent. | +| Verified local | `tests/advisor-config-reconciliation.test.sh` | Atomic, allowlisted, fail-closed configuration reconciliation. | +| Verified local | `tests/fixtures/phase-continue/` | Valid/invalid state fixture patterns. | +| Verified local | `platforms/codex-cli/tests/install.test.sh` | Codex installation contract and generated layout. | +| Verified local | `platforms/cursor/tests/install.test.sh` | Cursor installation contract and generated layout. | +| Verified local | `platforms/kiro-cli/tests/validation.test.sh` | Kiro validation and platform-specific constraints. | +| Supporting local | `plugins/maister-codex/`, `plugins/maister-cursor/`, `plugins/maister-kiro/` | Generated parity checks only; not canonical evidence. | + +## Category 2 Sources — Installed `mattpocock/skills` + +### Primary installed evidence + +| Status | Source | Purpose | +|---|---|---| +| Verified local, read | `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/SKILL.md` | Interactive tracker selection, repository-local config, labels, and domain-doc setup. | +| Verified local, read | `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md` | Local Markdown layout, publication/fetch semantics, status, blocking, claim, and resolve behavior. | +| Verified local, read | `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md` | GitHub CLI operations, issue/PR ambiguity, dependencies, frontier, and handoff conventions. | +| Verified local, read | `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md` | GitLab CLI operations, MR semantics, blocking links, tier fallback, and handoff conventions. | +| Verified local, read | `/Users/mrapacz/.agents/skills/to-spec/SKILL.md` | Conversation/codebase-to-spec publication and readiness labeling. | +| Verified local, read | `/Users/mrapacz/.agents/skills/to-tickets/SKILL.md` | Tracer-bullet decomposition, blocking edges, provider-dependent publication, and implementation handoff. | +| Verified local, read | `/Users/mrapacz/.agents/skills/triage/SKILL.md` | Tracker-independent role/state machine and agent-ready brief workflow. | +| Verified local, read | `/Users/mrapacz/.agents/skills/implement/SKILL.md` | Ticket/spec-to-implementation handoff and completion expectations. | +| Planned local | `/Users/mrapacz/.agents/skills/triage/AGENT-BRIEF.md` | Durable context contract handed to implementation agents. | +| Planned local | `/Users/mrapacz/.agents/skills/wayfinder/SKILL.md` | Map, frontier, claim, blocking, and resolution semantics across providers. | +| Planned local | `/Users/mrapacz/.agents/skills/domain-modeling/SKILL.md` | Domain terminology and decision persistence used during triage. | +| Planned local | `/Users/mrapacz/.agents/skills/tdd/SKILL.md` and `/Users/mrapacz/.agents/skills/code-review/SKILL.md` | Downstream implementation quality gates where relevant. | + +### Upstream provenance + +| Status | Source | Purpose | +|---|---|---| +| Planned external / unverified | https://github.com/mattpocock/skills | Upstream repository history, current templates, and differences from the installed copy. | + +## Category 3 Sources — External Tracker Providers + +All URLs below are **planned external / unverified** until the gatherer opens them, records the access date, confirms they are current official documentation, and cites the exact sections used. + +### GitHub + +| Source | Purpose | +|---|---| +| https://docs.github.com/en/rest/issues/issues | Create, read, update, list, lock, and state behavior for issues. | +| https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api | Pagination contract. | +| https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api | Rate limits and response handling. | +| https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api | Authentication boundaries and token use. | +| https://cli.github.com/manual/gh_issue | Official `gh issue` command family. | +| https://cli.github.com/manual/gh_issue_create | Fast creation flags and interactive/non-interactive behavior. | +| https://cli.github.com/manual/gh_issue_view | Issue retrieval and JSON output behavior. | + +### GitLab + +| Source | Purpose | +|---|---| +| https://docs.gitlab.com/api/issues/ | Issue API operations, identifiers, pagination, and fields. | +| https://docs.gitlab.com/api/issue_links/ | Related and blocking issue capabilities and tier constraints. | +| https://docs.gitlab.com/api/rest/authentication/ | Authentication methods and credential handling. | +| https://docs.gitlab.com/api/rest/ | REST conventions, pagination, status codes, and errors. | +| https://docs.gitlab.com/cli/issue/ | Official `glab issue` command surface; verify URL and installed-version parity. | + +### Jira Cloud + +| Source | Purpose | +|---|---| +| https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/ | Issue create/read/edit and project-scoped identifiers. | +| https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/ | Authentication guidance and constraints. | +| https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/ | REST conventions, errors, pagination, and versioning. | + +### Linear + +| Source | Purpose | +|---|---| +| https://linear.app/developers/graphql | GraphQL endpoint, authentication, queries, mutations, and pagination. | +| https://linear.app/developers/rate-limiting | Rate-limit semantics and client behavior. | +| https://linear.app/developers/webhooks | Change-notification options; likely post-v1, useful for ownership analysis. | + +### Local Markdown and portable persistence + +| Status | Source | Purpose | +|---|---|---| +| Verified local | `/Users/mrapacz/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md` | Concrete local layout and operations to evaluate. | +| Planned local | Existing Maister atomic-write and rollback tests/scripts discovered through `rg` in `plugins/maister/` and `tests/` | Repository-native precedent for safe writes and transactional rejection. | +| Planned external / unverified | https://pubs.opengroup.org/onlinepubs/9799919799/functions/rename.html | Portable atomic-replacement semantics and limitations relevant to local writes. | + +## Category 4 Sources — UX, Domain Model, Testing, and Security + +### Project standards and precedents + +| Status | Source | Purpose | +|---|---|---| +| Planned local | `.maister/docs/standards/global/validation.md` | Allowlisting, format checks, sanitization, and boundary validation. | +| Planned local | `.maister/docs/standards/global/error-handling.md` | Fail-fast errors, retries, degradation, and cleanup. | +| Planned local | `.maister/docs/standards/global/minimal-implementation.md` | Minimum viable interface and avoidance of speculative provider abstractions. | +| Planned local | `.maister/docs/standards/global/build-pipeline.md` | Canonical edits, generated ownership, and cross-platform validation. | +| Planned local | `.maister/docs/standards/global/conventions.md` | Project structure, dependencies, feature flags, and test expectations. | +| Planned local | `.maister/docs/standards/testing/test-writing.md` | Behavior-focused, risk-based, external-mock, and transactional rejection tests. | +| Verified local | `.maister/docs/project/vision.md` | User and safety goals for UX trade-offs. | +| Verified local | `.maister/docs/project/architecture.md` | State ownership, configuration, and integration constraints. | +| Verified local | `.maister/docs/project/tech-stack.md` | No-database and minimal-dependency constraints. | + +### Security primary sources + +| Status | Source | Purpose | +|---|---|---| +| Planned external / unverified | https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html | Credential storage, exposure prevention, rotation, and least privilege. | +| Planned external / unverified | https://cheatsheetseries.owasp.org/cheatsheets/Injection_Prevention_Cheat_Sheet.html | Command/input injection threat framing. | +| Planned external / unverified | https://owasp.org/www-project-top-10-for-large-language-model-applications/ | Prompt-injection and untrusted issue-content risks; verify current project/version and use only applicable guidance. | +| Planned external / unverified | Vendor authentication pages listed in Category 3 | Provider-specific token scopes and credential handling. | + +## Source Evaluation Rules + +For every cited finding, record: + +1. source path or direct URL; +2. access date for external sources; +3. version, plan/tier, preview status, or CLI version when behavior depends on it; +4. whether evidence is direct, inferred, or recommended; +5. contradictions or limitations; +6. confidence according to `planning/research-plan.md`. + +Do not promote a source from planned to verified merely because its URL resolves. The gatherer must confirm that the source directly supports the claim and is current for the relevant product/API version. diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/findings/canonical-core-boundary.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/findings/canonical-core-boundary.md new file mode 100644 index 00000000..a21a3b57 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/findings/canonical-core-boundary.md @@ -0,0 +1,238 @@ +# Granica kanonicznego rdzenia i adapterów platformowych + +## TL;DR +Maister ma już realny, przenośny rdzeń wykonawczy: pięć modułów Node.js odpowiedzialnych za stan, bramki i kontynuację jest kopiowanych bajt w bajt do wszystkich trzech generowanych targetów. +Nie ma jednak neutralnego kanonicznego modelu instrukcji: `plugins/maister/` jest pakietem Claude Code, a Cursor, Kiro i Codex odzyskują własne kontrakty przez około 320 tekstowych substytucji, override'y i syntezę nowych plików. +Najstabilniejsza granica przebiega między neutralnym kontraktem zachowania (fazy, stan, gate semantics, role i artefakty) a jawnym adapterem capabilities/invocation/packaging; materializacja może odbywać się przy instalacji, ale sama zmiana momentu generowania nie usuwa potrzeby testowania adapterów. +Rekomendowany kierunek to wspólny behavior/runtime core plus cienkie, wersjonowane adaptery hostów i deterministyczny instalator `--target`, bez commitowania pełnych wygenerowanych drzew jako źródeł utrzymania. + +## Key Decisions +- Traktować pięć wspólnych modułów ESM oraz kontrakty `orchestrator-state.yml` i gate engine jako zalążek właściwego portable core, a nie jako element adaptera Claude. +- Nie traktować obecnego `plugins/maister/` jako neutralnego IR: jest to Claude-native frontend zawierający nazwy narzędzi, plików, trybów i namespace'u Claude. +- Wydzielić mały, deklaratywny Host Contract oraz materializer instalacyjny; różnice semantyczne muszą być capability-controlled i jawnie testowane, nie realizowane globalnym `sed`. +- Przenieść wybór targetu do instalacji dopiero po uzyskaniu deterministycznych golden/contract tests dla każdego adaptera; install-time generation zmienia dystrybucję, nie obowiązek weryfikacji. + +## Open Questions / Risks +- Czy hosty potrafią wykonać wspólną neutralną reprezentację workflow bez utraty jakości promptów, czy też potrzebny będzie kompilowany dokument per host? +- Kiro zmienia nie tylko składnię, lecz także model pytań, progress tracking, planowanie i sposób reprezentacji agentów; zbyt cienki adapter ukryje różnice semantyczne zamiast je kontrolować. +- Brak runtime Claude Code pozostawia jego host-native discovery i wykonanie niezweryfikowane; wspólny core i materializer mogą być dobrze przetestowane, ale nie zastępują E6. +- Rezygnacja z commitowanych targetów upraszcza repozytorium, ale wymaga hermetycznego, wersjonowanego materializera oraz release artifacts możliwych do odtworzenia offline. + +## 1. Mapa aktualnego przepływu + +Aktualny pipeline ma postać: + +```text +plugins/maister/ (Claude-native source) + | + +--> platforms/cursor/build.sh ----> plugins/maister-cursor/ + +--> platforms/kiro-cli/build.sh --> plugins/maister-kiro/ + +--> platforms/codex-cli/build.sh -> plugins/maister-codex/ +``` + +### Finding 1: „canonical” oznacza obecnie Claude-native source, nie neutralny model + +- **Claim:** Źródło kanoniczne jest fizycznie i językowo związane z Claude Code: manifest znajduje się w `.claude-plugin`, opis nazywa Claude Code, instrukcje projektu są w `CLAUDE.md`, a współdzielony dokument orchestratora definiuje delegację przez `Skill`/`Task` oraz pytania przez `AskUserQuestion`. +- **Evidence:** + - `plugins/maister/.claude-plugin/plugin.json:1-8` — host-native manifest i opis „for Claude Code”. + - `plugins/maister/CLAUDE.md:1-16` oraz `plugins/maister/CLAUDE.md:26-41` — kanoniczna instrukcja i bezpośrednia zależność od `AskUserQuestion`. + - `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:7-20` — delegacja jest opisana nazwami narzędzi Claude. + - `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:58-80` — obowiązkowe bramki odwołują się do `AskUserQuestion` i permission modes Claude. +- **Evidence level:** E1 (static source inspection). +- **Confidence:** high — coupling jest jawny w manifestach i normatywnych instrukcjach. +- **Inference/limitation:** Dokumenty workflow są wykonywane przez model, więc tekst host-specific jest częścią programu, a nie wyłącznie komentarzem; nie zmierzono jeszcze wpływu neutralizacji słownika na jakość wykonania. + +### Finding 2: Behavior model jest w większości wspólny mimo Claude-oriented powierzchni + +- **Claim:** Fazy, kolejność persystencji, idempotency, denylist, gate history, phase-entry evidence i artefakty są definiowane niezależnie od hosta; nowsze workflow już nazywają pytanie prymitywem `host_adapter.present_user_gate`, co jest gotowym miejscem na seam. +- **Evidence:** + - `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:94-128` — wspólna polityka gate/Advisor/Arbiter i porządek persystencji. + - `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:139-159` — wspólny durable continuation protocol. + - `plugins/maister/skills/development/SKILL.md:100-140` — workflow jawnie rozróżnia gate engine od adapterowego `present_user_gate`. + - `plugins/maister/skills/research/SKILL.md:63-104` — research używa tego samego gate/state/continuation contract. +- **Evidence level:** E1 dla deklarowanego kontraktu; E3 dla jego wykonywalnych helperów opisanych w Finding 3. +- **Confidence:** high — te same invariants występują w frameworku i wielu workflow. +- **Inference/limitation:** Wspólny model jest dziś powielony w prozie workflow; samo podobieństwo instrukcji nie gwarantuje identycznej interpretacji przez różne hosty. + +## 2. Rzeczywisty portable runtime + +### Finding 3: Pięć modułów Node.js jest już bajtowo identycznym rdzeniem wszystkich targetów + +- **Claim:** `gate-evaluator.mjs`, `orchestrator-state-repository.mjs`, `orchestrator-state-schema.mjs`, `phase-continue.mjs` i `workflow-continuation.mjs` są wspólną implementacją o łącznej wielkości 1 995 linii; bieżące kopie w Codex, Cursor i Kiro są byte-identical względem canonical. +- **Evidence:** + - `Makefile:3-9` — macierz runnerów i lista wspólnych automatic runtime files. + - `Makefile:57-66` — ten sam contract suite jest wykonywany przeciw czterem ścieżkom runnera. + - `Makefile:68-87` — `cmp` wymusza identyczność wspólnego runtime w trzech projekcjach; wyjątkiem jest osobny Codex binding. + - `plugins/maister/skills/orchestrator-framework/bin/phase-continue.mjs:1-24` — czysty Node.js ESM, jawny denylist i ścisły kontrakt wejścia. + - Reprodukowalny inventory w tym checkout: `wc -l plugins/maister/skills/orchestrator-framework/bin/*.mjs` = 1 995; `cmp` dla każdego z 5 plików i 3 targetów zakończył się sukcesem. +- **Evidence level:** E3 (isolated executable contract + byte-identity validation). +- **Confidence:** high — repo ma wykonujące się testy kontraktowe i jawne `cmp`. +- **Inference/limitation:** Byte-identical kopie dowodzą wspólnego core, ale ich fizyczne powielanie w targetach nadal jest problemem packagingu, nie semantyki. + +### Finding 4: Capability-dependent binding jest mały i powinien pozostać poza core + +- **Claim:** Fully automatic continuation ma wspólny evaluator/repository/runner, lecz host-native evidence i binding są rozdzielone; aktualnie tylko Codex ma `declared_status: supported`, a pozostałe hosty są fail-closed. +- **Evidence:** + - `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml:1-18` — jedna macierz invariants i osobne host-native evidence targets. + - `platforms/codex-cli/build.sh:172-176` — tylko host-specific binding jest podmieniany, a sąsiedni runtime pozostaje canonical. + - `Makefile:47-55` — shared runner jest jawnie odrzucony jako native evidence; status wynika z wykonania targetu hosta. +- **Evidence level:** E3 dla wspólnego kontraktu, E1 dla deklarowanej macierzy bieżącego checkoutu. +- **Confidence:** high — granica jest jawnie opisana i egzekwowana w Makefile. +- **Inference/limitation:** Status capability jest migawką repozytorium, nie trwałą własnością hosta; adapter musi być wersjonowany wraz z evidence. + +## 3. Inwentarz transformacji + +Poniższa klasyfikacja rozróżnia transformacje **syntaktyczne** (zmiana reprezentacji przy zachowaniu intencji) od **semantycznych** (zmiana dostępnego zachowania, fallbacku lub modelu interakcji). + +| Klasa | Przykład | Typ | Dowód | Poziom / confidence | +|---|---|---|---|---| +| Manifest i layout | `.claude-plugin` jest zastępowany `.cursor-plugin`; Codex tworzy `.codex-plugin`; Kiro usuwa manifest Claude i buduje `agents/`, `steering/`, `settings/` | syntactic/packaging | `platforms/cursor/build.sh:18-48`; `platforms/codex-cli/build.sh:15-42`; `platforms/kiro-cli/build.sh:382-387` | E2 / high | +| Namespace i discovery nazw | `maister:foo` → `maister-foo`, zmiana nazw katalogów i frontmatter | syntactic | `platforms/cursor/build.sh:50-63`; `platforms/kiro-cli/build.sh:389-421`; `platforms/codex-cli/build.sh:51-57` | E2 / high | +| Commands → skills | Host bez command component materializuje command wrappers jako skills | syntactic z ryzykiem inventory collision | `platforms/cursor/build.sh:254-288`; `platforms/kiro-cli/build.sh:43-74`; `platforms/codex-cli/build.sh:178-187` | E2 / high | +| Invocation vocabulary | `Skill tool`, `Task tool`, `subagent_type` są przepisywane na slash skills/subagent/native delegation | semantic boundary, bo zmienia dostępne primitive i nesting | `platforms/kiro-cli/build.sh:263-344`; `platforms/codex-cli/build.sh:60-90`; canonical kontrakt: `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:7-20` | E1-E2 / high | +| User gates | Claude `AskUserQuestion`, Cursor `AskQuestion`, Kiro chat-native gate, Codex plain-text question | semantic, zwłaszcza multi-select/headless fallback | `platforms/cursor/build.sh:74-92`; `platforms/kiro-cli/build.sh:94-163`; `platforms/codex-cli/build.sh:60-68` | E1-E2 / high | +| Progress | Claude tasks są mapowane na Cursor `TodoWrite`, Kiro `todo`, a Codex na wpisy w authoritative state | semantic projection | `platforms/cursor/build.sh:413-456`; `platforms/kiro-cli/build.sh:346-367`; `platforms/codex-cli/build.sh:64-68` | E1-E2 / high | +| Planning | Claude plan-mode vocabulary jest usuwane lub zastępowane file/native planning | semantic UX/capability | `platforms/kiro-cli/build.sh:165-181`; `platforms/codex-cli/build.sh:67-68`; `platforms/cursor/build.sh:86-92` | E1-E2 / high | +| Agent representation | Kiro konwertuje Markdown+frontmatter do JSON i osobnych instruction files, mapując tools/resources/trusted agents | syntactic + capability mapping | `platforms/kiro-cli/generate-agent-json.sh:75-139`; `platforms/kiro-cli/build.sh:589-689` | E2 / high | +| Hooks | Każdy target zastępuje lub syntetyzuje host-native event schema i ścieżki | semantic integration | `platforms/cursor/build.sh:137-142`; `platforms/kiro-cli/build.sh:595-689`; `platforms/codex-cli/build.sh:299-303` | E2 / high | +| Content override | quick-plan/quick-bugfix i utility skills otrzymują osobne ciała; Kiro generuje dodatkowe shortcuts | semantic divergence | `platforms/cursor/build.sh:256-260`; `platforms/cursor/build.sh:463-576`; `platforms/kiro-cli/build.sh:184-243`; `platforms/kiro-cli/build.sh:698-814`; `platforms/codex-cli/build.sh:189-297` | E1-E2 / high | +| Context optimization | Kiro wycina katalog z always-loaded steering do lazy reference | semantic/performance | `platforms/kiro-cli/build.sh:525-580` | E2 / high | + +### Finding 5: Większość ryzyka leży w transformacji prozy, nie w packagingu + +- **Claim:** Trzy build adapters mają razem 1 780 linii (`582 + 860 + 338`), a pomocniczy generator agentów Kiro kolejne 160. W bieżącej migawce prosty inventory wykrywa około 320 wyrażeń substytucji (`91 Cursor + 169 Kiro + 60 Codex`), przy czym wiele dopasowuje warianty naturalnego języka zamiast stabilnych pól schema. +- **Evidence:** + - `platforms/cursor/build.sh:310-374` — długa lista ręcznych wariantów nazw i fraz. + - `platforms/kiro-cli/build.sh:94-153` — kilkadziesiąt zamian tylko dla sposobów zapisania gate. + - `platforms/kiro-cli/build.sh:263-344` — kolejna lista wariantów delegacji i nazw skills. + - `platforms/codex-cli/build.sh:44-132` — ten sam słownik zamian jest duplikowany w dwóch funkcjach transformujących Markdown. + - Reprodukowalny inventory w tym checkout: `wc -l` dla skryptów oraz `rg` wyrażeń `sedi`/`sed -e`. +- **Evidence level:** E1 (static inventory); deterministyczność samej materializacji jest E2 tam, gdzie build jest porównywany z committed output. +- **Confidence:** high dla liczb w checkout; medium dla wniosku o awaryjności bez historii defectów. +- **Inference/limitation:** Liczba substytucji nie jest miarą złożoności semantycznej jeden-do-jednego, ale wielokrotne warianty tej samej frazy zwiększają surface na silent miss i order-dependent rewrite. + +### Finding 6: Canonical vocabulary rozlewa coupling na większość aktywnych workflow + +- **Claim:** W bieżącym checkout 52 pliki Markdown canonical zawierają co najmniej jeden z host-specific tokenów (`AskUserQuestion`, task/plan/delegation tools, `subagent_type`, `CLAUDE.md`); samo `AskUserQuestion` występuje w 33 plikach, `Task tool` w 23, `Skill tool` w 18, a `subagent_type` w 17. +- **Evidence:** + - Reprodukowalny inventory: `rg -l --glob '*.md' plugins/maister`. + - Reprezentatywne miejsca: `plugins/maister/agents/implementation-planner.md:239-244`; `plugins/maister/commands/reviews-code.md:20-37`; `plugins/maister/skills/codebase-analyzer/SKILL.md:97-110`. + - Centralny kontrakt: `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:7-20` i `:58-80`. +- **Evidence level:** E1. +- **Confidence:** high dla inventory; medium dla oceny kosztu, bo część trafień jest dokumentacyjna. +- **Inference/limitation:** Globalne token counts mogą zawierać przykłady lub opisy anti-patterns, ale adapter i tak musi odróżnić je od instrukcji wykonywalnych, co samo jest źródłem fragility. + +### Finding 7: Commitowane projekcje zwielokrotniają powierzchnię repo, ale nie dają niezależnego dowodu semantyki + +- **Claim:** Cztery drzewa pluginów zawierają obecnie 610 plików i około 5,08 MB wersjonowanej treści łącznie; trzy targety są deterministycznymi projekcjami canonical + adapter, więc ich obecność ułatwia dystrybucję i drift diff, lecz nie stanowi trzech niezależnych implementacji behavior. +- **Evidence:** + - `Makefile:11-22` — każdy build generuje osobny target, a validate uruchamia wszystkie target gates. + - `.maister/docs/standards/global/build-pipeline.md:1-17` — generated targets są nieedytowalne i muszą odtwarzać się ze źródła. + - Reprodukowalny inventory w tym checkout: `find plugins/maister* -type f` oraz `git ls-files ... | xargs wc -c` = 610 plików / 5 084 215 bajtów dla czterech drzew. +- **Evidence level:** E1 dla rozmiaru i ownership; E2 dla deterministycznej projekcji objętej build/drift check. +- **Confidence:** high. +- **Inference/limitation:** Usunięcie targetów z Git nie zmniejszy wielkości instalowanego pluginu i może pogorszyć review diffs, jeśli release pipeline nie zachowa czytelnych artifacts/snapshots. + +## 4. Proponowana granica core/adapter + +### Finding 8: Stabilny seam powinien opisywać intencję, nie nazwy narzędzi + +- **Claim:** Najmniejszy sensowny portable core obejmuje: phase graph, domain workflow rules, artifact contracts, state schema/repository, gate policy/evaluator, continuation protocol, role intents i safety invariants. Poza core powinny znaleźć się: discovery layout, manifest, invocation syntax, user-gate presentation, delegation primitive, progress projection, planning UX, hook events, agent serialization i capability evidence. +- **Evidence:** + - Core candidates: `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md:94-159`; `plugins/maister/skills/research/SKILL.md:56-130`; `Makefile:3-9`. + - Adapter candidates są dokładnie miejscami obecnych transformacji: `platforms/cursor/build.sh:21-151`; `platforms/kiro-cli/build.sh:382-508`; `platforms/codex-cli/build.sh:15-132`. + - Istniejący seam nazwany wprost: `plugins/maister/skills/development/SKILL.md:109-140`. +- **Evidence level:** E1 + architectural inference. +- **Confidence:** high dla przypisania obecnych odpowiedzialności; medium dla dokładnego przyszłego API bez prototypu. +- **Inference/limitation:** Neutralny core nie musi być jednym plikiem ani pełnym AST. Minimalna migracja może zacząć się od jawnych placeholderów/primitives w Markdown, zanim uzasadniony będzie pełny IR. + +Proponowany kontrakt hosta powinien być mały i deklaratywny, np. koncepcyjnie: + +```yaml +host: + id: codex + capabilities: + user_gate: plain_text + nested_subagents: true + progress_projection: state_only + fully_automatic_continuation: native_evidence_required + vocabulary: + project_instructions: AGENTS.md + skill_invocation: "$maister:{name}" + packaging: + manifest: .codex-plugin/plugin.json + skills_root: skills/ + commands: materialize_as_skills + bindings: + present_user_gate: codex_plain_text + delegate_role: codex_native_subagent + project_progress: orchestrator_state +``` + +Ten przykład jest **hipotezą projektową, E0, confidence medium**: nazwy pól wymagają prototypu i golden fixtures, ale odpowiedzialności wynikają bezpośrednio z istniejących adapterów. + +## 5. Ocena install-time materialization + +### Finding 9: Wybór platformy przy instalacji jest wykonalny, ale powinien materializować host-native artefakt + +- **Claim:** Wszystkie trzy adaptery już działają jako deterministyczne materializery `CORE + PLATFORM -> OUT`; przeniesienie wywołania z `make build-*` do `maister install --target ` jest zmianą momentu i miejsca wykonania, a nie nowym modelem transformacji. +- **Evidence:** + - `platforms/cursor/build.sh:4-19`, `platforms/kiro-cli/build.sh:4-8` i `:380-384`, `platforms/codex-cli/build.sh:4-16` — każdy adapter ma jawne wejście canonical, katalog platformy i output. + - `Makefile:11-20` — obecny selector targetu istnieje jako trzy build targets. + - `platforms/kiro-cli/build.sh:18-34` — materializacja już wymaga ochrony przed współbieżną mutacją outputu, co wskazuje na potrzebę atomowego instalatora. +- **Evidence level:** E2 dla obecnej materializacji; E0 dla przyszłego install-time CLI. +- **Confidence:** high dla wykonalności, medium dla ergonomii i kompatybilności bez prototypu instalatora. +- **Inference/limitation:** Jeden dystrybuowany bundle nadal musi zawierać adaptery i host-specific assets. Nie będzie jednym identycznym katalogiem odkrywanym przez wszystkie hosty; będzie jednym inputem generującym jeden wybrany native layout. + +### Rekomendowany model docelowy + +1. **Portable behavior/runtime core** — neutralne workflow contracts i obecne moduły ESM, testowane raz na fixtures. **E3 / confidence high** na podstawie istniejącego runtime matrix (`Makefile:57-87`). +2. **Versioned Host Contract** — capabilities oraz wiązania dla gate/delegation/progress/planning/hooks, z fail-closed defaults. **E1 + inference / confidence high** na podstawie istniejącej capability matrix (`host-capabilities.yml:1-18`). +3. **Per-host renderer/materializer** — generuje manifest, layout, agent format i host-native instrukcje do katalogu tymczasowego, waliduje, a następnie atomowo instaluje. **E0 / confidence medium**; obecne build scripts dowodzą wejść/wyjść, nie atomowego unified installera. +4. **Release bundle zamiast trzech utrzymywanych drzew** — canonical core + adapters + assets + golden fixtures; CI materializuje wszystkie targety i publikuje gotowe artifacts dla marketplace, ale pełne drzewa nie muszą być commitowane. **E0 / confidence medium**; wymaga decyzji o review ergonomics i offline reproducibility. + +## 6. Co uprościć najpierw + +### Etap A — bez zmiany dystrybucji + +- Zastąpić w canonical workflow bezpośrednie nazwy narzędzi małym słownikiem intencji (`present_user_gate`, `delegate_role`, `invoke_capability`, `project_progress`) tam, gdzie pliki już mówią o `host_adapter`. **E0 / confidence high** co do kierunku; dowód istniejącego seam: `plugins/maister/skills/development/SKILL.md:109-140`. +- Utrzymywać semantyczne capability branches jawnie; nie zamieniać ich regexami. **E0 / confidence high**, bo Kiro gate/progress/delegation transforms zmieniają zachowanie (`platforms/kiro-cli/build.sh:94-163`, `:263-367`). +- Wyciągnąć wspólne utility skills (`resume/status/next/bye/dev`) do jednego neutralnego źródła z rendererem invocation syntax. Dziś są generowane osobno w Cursor, Codex i Kiro. **E1 / confidence high**: `platforms/cursor/build.sh:463-576`, `platforms/codex-cli/build.sh:189-297`, `platforms/kiro-cli/build.sh:746-814`. + +### Etap B — semantic materializer + +- Zastąpić globalne `sed` strukturą transformacji opartą o jawne pola/frontmatter/placeholdery; tekst naturalny pozostawić nietknięty, chyba że dany blok jest oznaczonym host bindingiem. **E0 / confidence medium** — potrzebny prototyp na reprezentatywnych workflow. +- Rozdzielić transformacje na `package`, `render-vocabulary`, `bind-capability`, `host-assets`; każdy etap ma schema validation i golden output. **E0 / confidence medium**. +- Utrzymać native evidence target jako osobny element capability record, nie jako właściwość wspólnego runtime. **E3 / confidence high**: `Makefile:47-55`. + +### Etap C — install-time selection + +- Dodać jeden entrypoint w stylu `maister install --target claude|codex|cursor|kiro [--dest ...]`. +- Materializować do katalogu tymczasowego, walidować manifest/inventory/references, wykonywać atomic rename lub pełny rollback; zapisać target, adapter version i content hash w install receipt. +- W CI nadal materializować i testować **wszystkie** targety; lokalny użytkownik wybiera jeden. Nie używać install-time wyboru do ograniczenia macierzy projektu. +- Dla marketplace publikować prebuilt artifacts z tego samego materializera, aby konsument nie potrzebował toolchainu build. + +Wszystkie cztery punkty Etapu C są **E0 / confidence medium**: są rekomendacją wyprowadzoną z obecnych deterministic builds, lecz nie istnieją jeszcze w repo. + +## 7. Konsekwencja dla Claude Code bez runtime + +### Finding 10: Neutralny core zwiększy zakres dowodu bez Claude runtime, lecz nie zamknie luki hostowej + +- **Claim:** Po wydzieleniu core można raz udowodnić gate/state/continuation semantics na E3 i materializację Claude adaptera na E1-E2; bez uruchomienia Claude Code nie można dowieść discovery, tool binding ani pełnego workflow na E5-E6. +- **Evidence:** + - `Makefile:24-30` i `:57-87` — shared contracts i byte-identity runtime są testowane niezależnie od hosta. + - `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml:7-9` — Claude native target jest obecnie zadeklarowany jako unsupported. + - `Makefile:47-55` — shared runner nie może zastąpić native evidence. +- **Evidence level:** E3 dla core, E1-E2 dla możliwej materializacji, `unverified` dla Claude E5-E6. +- **Confidence:** high. +- **Inference/limitation:** Nawet idealny kontrakt statyczny nie wykryje zmian nieudokumentowanego zachowania hosta; potrzebny jest okresowy zewnętrzny/native canary, gdy runtime stanie się dostępny. + +## 8. Ostateczna rekomendacja dla syntezy + +**Rekomendacja:** wybrać wariant **„wspólny behavior/runtime core + cienkie adaptery + install-time materializer”**, a neutralny pełny IR wprowadzać tylko tam, gdzie oznaczone primitives i templates nie wystarczą. + +- **Dlaczego:** repo już dowodzi, że executable state/continuation core może być identyczny na wszystkich hostach (`Makefile:57-87`), natomiast setki prozatorskich rewrite'ów pokazują, że Claude-native Markdown nie jest stabilnym neutralnym wejściem (`platforms/kiro-cli/build.sh:94-367`, `platforms/cursor/build.sh:310-456`, `platforms/codex-cli/build.sh:44-132`). +- **Evidence level:** E3 + architectural inference. +- **Confidence:** high dla wyboru granicy; medium dla szczegółowego formatu materializera. +- **Najważniejsze zastrzeżenie:** „jedno rozwiązanie” powinno oznaczać jedno źródło zachowania, jeden testowalny runtime i jeden bundle instalacyjny — nie jeden identyczny output filesystem dla czterech hostów. + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/findings/host-contracts-installation.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/findings/host-contracts-installation.md new file mode 100644 index 00000000..e9a4cc55 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/findings/host-contracts-installation.md @@ -0,0 +1,244 @@ +# Host contracts and install-time materialization + +## TL;DR + +Maister może być dystrybuowany jako **jeden pakiet z `install --target claude|codex|cursor|kiro-cli`**, ale hosty nie przyjmą jednego identycznego, już zmaterializowanego drzewa. Wspólny może być model workflow, katalog źródłowych skills, portable runtime/helpers, assets i neutralne metadane. Instalator musi natomiast wygenerować host-native manifest, layout, nazwy invocation, kontrakt agentów, hooki, MCP i ścieżki zasobów. + +Najmniejsza stabilna granica to: **canonical behavior package + cienkie, wersjonowane host descriptors/materializers + atomowy installer**. Obecne buildy dowodzą wykonalności transformacji, lecz zawierają zbyt wiele globalnych `sed` i semantycznych wyjątków, aby po prostu przenieść je 1:1 do instalatora. Najpierw należy przenieść różnice do jawnego modelu capabilities i strukturalnych generatorów. + +Runtime availability jest nierówna. Claude Code ma oficjalny non-interactive runtime (`claude -p`), ale w badanym środowisku nie jest on dostępny, więc dla tego hosta można uczciwie osiągnąć najwyżej E1–E4 zależnie od uruchomionych testów instalacji; E5/E6 pozostają `unverified`. Codex, Cursor i Kiro publikują ścieżki headless/non-interactive, lecz ich obecność w dokumentacji również nie jest dowodem wykonanego testu Maister. + +## Key Decisions + +- Traktować „jedno rozwiązanie” jako jedno canonical source i jeden dystrybuowany bundle, nie jeden identyczny installed tree. +- Materializować na etapie instalacji wyłącznie host binding: manifest/catalog, layout, invocation vocabulary, agent schema, hook schema/env, MCP placement i absolutyzację ścieżek. +- Zachować `orchestrator-state.yml` i executable helpers jako wspólny kontrakt continuation; natywne session-resume hosta traktować jako opcjonalny UX, nie source of truth Maister. +- Nie deklarować Claude runtime parity bez realnego `claude` E5/E6; oficjalna możliwość `claude -p` nie zastępuje dostępu do runtime, uwierzytelnienia i wykonanego scenariusza. + +## Open Questions & Risks + +- Cursor plugin contract jest bardzo świeży (plugin marketplace od Cursor 2.5, luty 2026; szeroki Customize/marketplace update w 3.9, czerwiec 2026) i może nadal szybko ewoluować. +- Kiro CLI i Kiro IDE mają obecnie różne agent formats (CLI JSON, IDE Markdown); `--target kiro-cli` musi być nazwany precyzyjnie, zamiast obiecywać abstrakcyjny target `kiro`. +- Install-time transforms zmniejszają liczbę commitowanych generated trees, ale przenoszą failure moment na maszynę użytkownika; wymagają schema validation, staging directory, atomic rename i rollback. +- Obecne textual substitutions ingerują w semantykę gate/delegation. Bez strukturalnego IR lub host-aware templates materializer będzie trudny do wersjonowania i audytu. + +## Scope and evidence discipline + +Źródła lokalne opisują Maister `2.2.1-fork.1`. Źródła internetowe są wyłącznie host-owned i zostały sprawdzone 2026-07-14. Poziomy dowodu: E0 dokument/intencja; E1 static/schema; E2 deterministic transform; E3 isolated executable contract; E4 install; E5 host CLI smoke; E6 host runtime E2E. Oficjalna dokumentacja hosta jest dowodem kontraktu, nie udanego uruchomienia Maister. + +## Feature matrix + +Legenda: **common** = może pochodzić bezpośrednio ze wspólnego pakietu; **adapter** = wymagany binding/materialization; **unsupported/unknown** = nie wolno emulować bez dowodu hosta. + +| Powierzchnia | Claude Code | Codex | Cursor | Kiro CLI | Klasyfikacja | +|---|---|---|---|---|---| +| Discovery/layout | Plugin root z opcjonalnym `.claude-plugin/plugin.json`; domyślne `skills/`, `commands/`, `agents/`, `hooks/hooks.json`, `.mcp.json`; marketplace kopiuje do cache | Wymagany `.codex-plugin/plugin.json`; `skills/`, `hooks/`, `.mcp.json`; repo marketplace w `.agents/plugins/marketplace.json` | `.cursor-plugin/plugin.json`; plugin może bundle skills, subagents, MCP, hooks i rules; Maister instaluje do `~/.cursor/plugins/local/maister-cursor` | Brak jednego manifestu pluginu w obecnym wariancie; profil `$KIRO_HOME` z `agents/*.json`, `skills/*/SKILL.md`, `settings/mcp.json`, steering/hooks | **adapter** dla root/layout i catalog; payload skills/assets częściowo **common** | +| Manifest/catalog | `.claude-plugin/plugin.json`; `.claude-plugin/marketplace.json`; manifest może być pominięty przy default discovery, ale dystrybucja wymaga stabilnej identity/version | `.codex-plugin/plugin.json` jest wymagany; katalog `.agents/plugins/marketplace.json` ma inne `source` i policy | `.cursor-plugin/plugin.json` zawiera host-specific `skills`, `agents`, `hooks`; osobny `.cursor-plugin/marketplace.json` | Agent JSON pełni funkcję entry configuration; discovery przez `$KIRO_HOME`; brak zgodnego marketplace manifestu w repo | **adapter**, ale neutralne metadata name/version/author/repository są **common** | +| Skills/commands | `skills//SKILL.md`; legacy `commands/*.md`; plugin skill namespace `/plugin:skill` | `skills//SKILL.md`; Maister konwertuje source commands do skills; invocation `$maister:...` | Skills i commands jako plugin capabilities, lecz Maister scala commands do skills i zmienia `maister:` na `maister-` | Skills jako `skill://` resources i slash skills; Maister generuje krótkie shortcut skills oraz `maister-*` | Body workflow może być **common**; namespace, entrypoints, frontmatter i command collapse są **adapter** | +| Project instructions | Claude-native context, ale oficjalnie plugin-root `CLAUDE.md` nie jest ładowany jako plugin context | `AGENTS.md` hierarchicznie; build zamienia `CLAUDE.md`→`AGENTS.md` | CLI czyta `AGENTS.md` i `CLAUDE.md`; Maister emituje `.mdc` rules | CLI ładuje `AGENTS.md`, steering i skill resources; isolated profile może zmienić inheritance | Semantyka standardów **common**; delivery channel **adapter** | +| Agents/subagents | Plugin `agents/*.md`, Claude frontmatter i Task/subagent vocabulary | Native/custom subagents; standalone TOML w `~/.codex/agents/` lub `.codex/agents/`; plugin Maister obecnie nie kopiuje source agents i używa native delegation | Plugin subagents jako Markdown; Maister prefiksuje names, wprowadza `maister-explore`, `readonly` i `model: inherit` | CLI custom agents to JSON; `tools`, `allowedTools`, `resources`, hooks i `toolsSettings.subagent`; Maister konwertuje MD→JSON+instruction files | Prompty/role intent częściowo **common**; agent schema, tool names, trust, concurrency i invocation **adapter** | +| User gates/progress | `AskUserQuestion`/host interaction and Task APIs in canonical vocabulary | Plain-text user question + optional Goals/native planning; Maister persystuje fazy w state | `AskQuestion`; Cursor-specific plan/progress behavior | Chat gate; headless nie ma mid-session input; `todo` activity-tray mapping | State transition invariant **common**; presentation/tool binding **adapter**; interactive gate w headless może być **unsupported** bez policy | +| Hooks | PascalCase event schema, nested `hooks[]`, `${CLAUDE_PLUGIN_ROOT}` | Zbliżony event schema, `PLUGIN_ROOT`/`PLUGIN_DATA`; plugin hooks wymagają review/trust | `version:1`, camelCase events, `${CURSOR_PLUGIN_ROOT}`, inny response contract | Hooks inline w agent JSON; inne triggers/tool matchers i absolute install paths; brak `preCompact` w obecnym wsparciu Maister | Hook intent/script logic częściowo **common**; schema, env, matchers, output i dostępne events **adapter** | +| MCP | Plugin `.mcp.json` / manifest `mcpServers` | `.mcp.json` + manifest `mcpServers`; user controls trust/approval | Plugin MCP; lokalny install Maister dodaje `mcp.json` tylko opt-in | `settings/mcp.json` lub agent `mcpServers`; `includeMcpJson`; CLI może fail-fast `--require-mcp-startup` | Server definitions mogą mieć neutralny model; file placement/policy **adapter** | +| Continuation/resume | Oficjalnie `--continue`/`--resume `; Maister state nadal niezależny | `codex exec`; natywne sesje są oddzielne od `orchestrator-state.yml`; utility `$maister:resume` odczytuje state | Headless `-p`; Maister `/maister-resume` odczytuje state | `--resume`, `--resume-id`; Maister `/resume` odczytuje state | `orchestrator-state.yml` + helpers **common**; native session continuation **adapter/optional** | +| Headless/runtime testability | Oficjalnie `claude -p`, plugin przez `--plugin-dir`; **runtime niedostępny w tym badaniu** | Oficjalnie `codex exec`; lokalny repo ma plugin install flow | Oficjalnie `cursor-agent -p`, `--force` dla writes | Oficjalnie `kiro-cli chat --no-interactive`, wymaga `KIRO_API_KEY`; brak mid-session input | CLI harness **adapter**; scenario/evidence model **common**; osiągnięty level zależy od dostępnego binary/auth | +| Install/update | Marketplace add/install/update, scoped user/project/local, version/cache; `/reload-plugins` | CLI marketplace add/list/upgrade/remove; install plugin i nowa sesja; repo/personal catalog | Marketplace `/add-plugin` lub local copy; team marketplace policies; lokalny Maister rebuild+copy | Obecny Maister kopiuje do isolated `$KIRO_HOME`, rewrites absolute paths, ustawia default agent/aliases; update = rebuild+reinstall | Jeden installer UX **common**; backend per host **adapter** | + +## Findings + +### Finding 1: identyczny installed tree jest sprzeczny z publicznymi kontraktami hostów + +- Claim: Cztery hosty mają różne root markers i discovery contracts; wspólny katalog nie może równocześnie być natywnym pluginem bez host-specific files lub instalacyjnej transformacji. +- Evidence: + - Local: `plugins/maister/.claude-plugin/plugin.json:1-9` — canonical manifest jest jawnie Claude-oriented. + - Local: `plugins/maister-codex/.codex-plugin/plugin.json:1-22` — Codex wymaga innego marker directory i interface metadata. + - Local: `plugins/maister-cursor/.cursor-plugin/plugin.json:1-16` — Cursor manifest wskazuje skills, agents i hooks. + - Local: `plugins/maister-kiro/agents/maister.json:1-21` — Kiro entrypoint jest agent JSON z tool/resource policy, nie plugin manifest tego samego typu. + - Official Claude: [Plugins reference](https://code.claude.com/docs/en/plugins-reference) (accessed 2026-07-14, version rolling/unknown) — default component roots i `.claude-plugin/plugin.json`; plugin-root `CLAUDE.md` nie jest ładowany jako plugin context. + - Official Codex: [Build plugins](https://learn.chatgpt.com/docs/build-plugins) (accessed 2026-07-14, version rolling/unknown) — `.codex-plugin/plugin.json` jest required entry point, a `skills/`, `hooks/`, `.mcp.json` pozostają w plugin root. + - Official Cursor: [Cursor 2.5 changelog](https://cursor.com/changelog/2-5) (accessed 2026-07-14, Cursor 2.5, 2026-02-17) — plugins bundle skills, subagents, MCP servers, hooks i rules. + - Official Kiro CLI: [Agent configuration reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/) (accessed 2026-07-14, current CLI docs; agent-create filename behavior v1.26.0+ noted elsewhere) — CLI agents are JSON in `.kiro/agents/` or `~/.kiro/agents/` with tools/resources/hooks/MCP fields. +- Evidence level: E1 for local shape; E0 for public contract. +- Confidence: high — niezależne manifesty i oficjalne layouts są jawne. +- Inference/limitation: Host może tolerować dodatkowe obce katalogi, ale to nie daje wspólnej identity, discovery ani update semantics. + +### Finding 2: Agent Skills są najlepszą wspólną jednostką payload, lecz invocation nie jest wspólne + +- Claim: Wszystkie hosty potrafią konsumować `SKILL.md`-like instruction packages, więc body, references, scripts i assets mogą być canonical; nazwy, namespaces, command wrappers, visibility i invocation syntax muszą pozostać bindingiem hosta. +- Evidence: + - Local: `platforms/codex-cli/build.sh:135-170` — source skill jest kopiowany, frontmatter transformowany, a optional Codex `agents/openai.yaml` generowany. + - Local: `platforms/codex-cli/build.sh:178-187` — Codex nie ma source command component w tym modelu; commands stają się skill entrypoints. + - Local: `platforms/cursor/build.sh:50-63` — Cursor zmienia `maister:foo`→`maister-foo` w commands, skills i references. + - Local: `platforms/kiro-cli/build.sh:43-91` — Kiro scala commands do skills i prefiksuje katalogi/names. + - Official Codex: [Build skills](https://learn.chatgpt.com/docs/build-skills) (accessed 2026-07-14, version rolling/unknown) — skill to directory z required `SKILL.md` i optional scripts/references/assets; required `name` i `description`. + - Official Claude: [Create plugins](https://code.claude.com/docs/en/plugins) (accessed 2026-07-14, Claude Code rolling; zip `--plugin-dir` requires v2.1.128+) — plugin skills use `skills//SKILL.md` and plugin-namespaced invocation. + - Official Cursor: [Cursor 2.4 changelog](https://cursor.com/changelog/2-4) and [Cursor 2.5 changelog](https://cursor.com/changelog/2-5) (accessed 2026-07-14, Cursor 2.4/2.5) — Agent Skills and plugin packaging are native capabilities in editor and CLI. + - Official Kiro: [Kiro IDE 0.9 changelog](https://kiro.dev/changelog/ide/0-9/) (accessed 2026-07-14, IDE 0.9) — Kiro imports portable Agent Skills packages; CLI agent config supports progressive `skill://.../SKILL.md` resources. +- Evidence level: E2 for current local materialization logic; E0/E1 for host contracts. +- Confidence: high for shared skill package shape, medium for byte-identical frontmatter portability. +- Inference/limitation: Common body does not imply common runtime semantics; tool names embedded in prose and gates still require structural binding. + +### Finding 3: Agents, gates and hooks są semantyczną — nie tylko syntaktyczną — granicą adaptera + +- Claim: Host bindings muszą modelować capabilities, ponieważ obecne adaptery zmieniają role agentów, user-gate mechanism, progress system, hook events i trust policy. +- Evidence: + - Local: `platforms/codex-cli/build.sh:60-90` — transformuje AskUserQuestion, task/progress tools, plan mode, Skill/Task i agent-role vocabulary. + - Local: `platforms/cursor/build.sh:65-101` — Cursor dodaje własny `maister-explore`, mapuje AskUserQuestion→AskQuestion, usuwa plan-mode references i usuwa default MCP. + - Local: `platforms/kiro-cli/build.sh:94-120` — Kiro przepisuje mandatory user questions na chat gates i headless defaults. + - Local: `platforms/kiro-cli/build.sh:245-300` — Kiro mapuje Explore i Task/Skill na `subagent` i slash skills. + - Local: `plugins/maister/hooks/hooks.json:1-38`, `platforms/cursor/hooks/hooks.json:1-58`, `platforms/codex-cli/hooks/hooks.json:1-41`, `plugins/maister-kiro/agents/maister.json:22-60` — cztery różne hook envelopes, event names, root env/path conventions i matchers. + - Official Codex: [Subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) (accessed 2026-07-14, version rolling/unknown) — custom agents są standalone TOML w `~/.codex/agents/` lub `.codex/agents/`; concurrency/depth są host config. + - Official Codex: [Hooks](https://learn.chatgpt.com/docs/hooks) (accessed 2026-07-14, version rolling/unknown) — plugin hooks use `PLUGIN_ROOT`/`PLUGIN_DATA`, current definition requires review/trust, and events/matchers are host-defined. + - Official Kiro CLI: [Agent configuration reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/) (accessed 2026-07-14, current docs) — hooks are inline agent fields with Kiro internal tool matcher names and agent-level tool/MCP policy. +- Evidence level: E2 for transforms, E1 for generated hook/config shape. +- Confidence: high — różnice są bezpośrednio zakodowane i potwierdzone przez host docs. +- Inference/limitation: Część scripts (np. destructive command policy) może być wspólna, ale tylko po zdefiniowaniu neutralnego input/output contract i host wrappers. + +### Finding 4: MCP jest wspólną capability, lecz placement i security policy są platformowe + +- Claim: Definicję serwera MCP można utrzymywać jako neutralne dane, ale installer musi wygenerować host-specific path/manifest wiring i respektować trust/governance. +- Evidence: + - Local: `platforms/cursor/build.sh:99-101` oraz `platforms/cursor/smoke-install.sh:58-66` — MCP jest usuwany z default build i dodawany opt-in jako `mcp.json`. + - Local: `platforms/codex-cli/smoke-install.sh:30-43` — installer materializuje `.mcp.json` i dodaje/usuwa `mcpServers` w Codex manifest. + - Local: `platforms/kiro-cli/build.sh:582-587` i `platforms/kiro-cli/smoke-install.sh:265-272` — Kiro przenosi config do `settings/mcp.json`, a install bez opt-in usuwa config i `includeMcpJson`. + - Official Claude: [MCP](https://code.claude.com/docs/en/mcp) and [Plugins reference](https://code.claude.com/docs/en/plugins-reference) (accessed 2026-07-14, version rolling/unknown) — plugins can bundle MCP config via `.mcp.json`/manifest. + - Official Codex: [Build plugins](https://learn.chatgpt.com/docs/build-plugins) (accessed 2026-07-14, version rolling/unknown) — plugin `.mcp.json`, `mcpServers`, plus plugin-scoped approval/enable policy. + - Official Cursor: [Cursor 3.9 changelog](https://cursor.com/changelog) (accessed 2026-07-14, Cursor 3.9, 2026-06-29) — team marketplaces distribute MCP across cloud agents, Agents window, IDE and CLI. + - Official Kiro: [Configuration](https://kiro.dev/docs/cli/chat/configuration/) (accessed 2026-07-14, page updated 2026-05-27) — MCP priority is Agent > Project > Global and files live at global/workspace paths. +- Evidence level: E2 local materialization; E0/E1 official contract. +- Confidence: high. +- Inference/limitation: Secrets/auth must never be baked into common artifact; installer should only wire declarative server identity and leave credentials to host-native flow. + +### Finding 5: wspólny continuation contract jest możliwy niezależnie od natywnej sesji hosta + +- Claim: `orchestrator-state.yml` i deterministic helpers mogą pozostać host-independent; natywne session resume differs and should not be required for correctness. +- Evidence: + - Local: `platforms/codex-cli/build.sh:189-218` — Codex utility resume odczytuje state i ponownie wywołuje właściwy workflow. + - Local: `docs/kiro-cli-support.md:137-145` — Kiro `/resume` traktuje `orchestrator-state.yml` jako source of truth. + - Local: `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml:6-18` — host continuation status jest jawnie różny: Codex supported; Claude/Cursor/Kiro unsupported w tej macierzy. + - Official Claude: [Run programmatically](https://code.claude.com/docs/en/headless) (accessed 2026-07-14, Claude Code rolling) — `--continue` i `--resume ` są host session features. + - Official Kiro: [CLI commands](https://kiro.dev/docs/cli/reference/cli-commands/) (accessed 2026-07-14, page updated 2026-06) — `--resume`, `--resume-id` i session listing są native CLI features. + - Official Codex: [Non-interactive mode](https://learn.chatgpt.com/docs/non-interactive-mode) (accessed 2026-07-14, version rolling/unknown) — automation entrypoint is `codex exec`; it has its own session persistence semantics. +- Evidence level: E3 for portable helpers only when their contract tests run (covered by another gatherer); E0/E1 here for host/session contracts. +- Confidence: high for architectural separation, medium for full cross-host continuation parity. +- Inference/limitation: State portability does not guarantee a host will rehydrate identical conversational context; workflow must reconstruct needed context from durable artifacts. + +### Finding 6: jeden bundle + `--target` jest wykonalny, ale installer staje się kompilatorem i transaction boundary + +- Claim: Aktualne build/install flows pokazują wszystkie potrzebne kroki do target selection, lecz bezpieczna wersja musi materializować do staging, validate against selected host contract, then atomically install/rollback. +- Evidence: + - Local: `platforms/cursor/build.sh:18-48` — build kopiuje canonical tree i generuje Cursor manifest. + - Local: `platforms/codex-cli/build.sh:15-42` — build tworzy nowy Codex root/manifest zamiast kopiować identyczny plugin. + - Local: `platforms/kiro-cli/generate-agent-json.sh:75-139` — Kiro generator strukturalnie tworzy JSON agent + instruction file. + - Local: `platforms/cursor/smoke-install.sh:49-63` — Cursor build+replace-copy to local discovery path. + - Local: `platforms/codex-cli/smoke-install.sh:99-124` — Codex build, marketplace registration, install path resolution i post-install MCP patch. + - Local: `platforms/kiro-cli/smoke-install.sh:49-120` — Kiro rewrites hook/resource/prompt paths at install time; `platforms/kiro-cli/smoke-install.sh:105-120` replaces isolated profile. + - Official Claude: [Plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces) (accessed 2026-07-14, version rolling/unknown) — installed plugins are copied to versioned cache and cannot rely on files outside plugin directory; update is marketplace/version driven. + - Official Codex: [Build plugins](https://learn.chatgpt.com/docs/build-plugins) (accessed 2026-07-14, version rolling/unknown) — CLI supports marketplace add/list/upgrade/remove and repo/personal catalogs. + - Official Cursor: [Cursor 2.5 changelog](https://cursor.com/changelog/2-5) and [Cursor 3.9 changelog](https://cursor.com/changelog) (accessed 2026-07-14) — marketplace install and team distribution are native paths. + - Official Kiro: [Settings](https://kiro.dev/docs/cli/reference/settings/) (accessed 2026-07-14, page updated 2026-06-05) — `KIRO_HOME` overrides discovery root for agents, skills, steering, settings and sessions. +- Evidence level: E2 for generation mechanics; E4 only for install scripts when their tests are actually run (not claimed here). +- Confidence: high for feasibility, medium for migration cost and long-term stability. +- Inference/limitation: Shipping source+materializer is not automatically simpler if transforms remain global regexes. Simplicity comes from deleting committed generated variants and replacing regexes with typed target descriptors/templates. + +### Finding 7: runtime availability must be recorded per host and per run + +- Claim: Public headless support exists for all four hosts, but evidence level depends on local binary, credentials, version and actual execution; Claude E5/E6 cannot be claimed in this research environment. +- Evidence: + - Local: `.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/research-brief.md:5-7` — problem statement says Claude runtime is unavailable for E2E. + - Local: `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml:7-18` — only Codex fully-automatic continuation is declared supported; other host scenarios are unsupported. + - Official Claude: [Run Claude Code programmatically](https://code.claude.com/docs/en/headless) (accessed 2026-07-14, Claude Code rolling; v2.1.128 mentioned for stdin/archive-related behavior) — `claude -p`, plugin loading and structured stream init exist. + - Official Codex: [Non-interactive mode](https://learn.chatgpt.com/docs/non-interactive-mode) (accessed 2026-07-14, version rolling/unknown) — `codex exec` is supported for scripts/CI with explicit sandbox. + - Official Cursor: [Headless CLI](https://docs.cursor.com/en/cli/headless) (accessed 2026-07-14, version unknown) — `cursor-agent -p`; writes require `--force`. + - Official Kiro: [Headless mode](https://kiro.dev/docs/cli/headless/) (accessed 2026-07-14, page updated 2026-06-04) — `--no-interactive`, `KIRO_API_KEY`, no mid-session input, optional `--require-mcp-startup`. +- Evidence level: E0 for supported contract; achieved E5/E6 is `unverified` in this finding. +- Confidence: high. +- Inference/limitation: „Brak runtime Claude” jest ograniczeniem środowiska projektu, nie brakiem produktu Anthropic. Można budować static/contract/install assurance, ale nie nazywać go runtime parity. + +## Unavoidable differences vs install-time materialization + +### Różnice nieusuwalne + +1. Marker/manifest/catalog i host namespace. +2. Tool and agent invocation vocabulary, available built-ins, concurrency/depth and trust model. +3. User-interaction API oraz zachowanie w non-interactive mode. +4. Hook event names, nesting, matcher names, environment variables, output/permission semantics i brakujące events. +5. MCP discovery/security/governance and credential flow. +6. Native session continuation, install scopes/cache/update and marketplace governance. + +### Różnice właściwe do materializacji przy instalacji + +1. Wybranie target descriptor i capability version range. +2. Wygenerowanie manifestu/catalog entry i final layout. +3. Utworzenie host-native skill entrypoints z canonical skill bodies. +4. Wygenerowanie agent MD/TOML/JSON z neutralnych role definitions; dla Codex można świadomie użyć native roles zamiast materializować wszystkich agentów. +5. Wygenerowanie hook config i cienkich wrappers do wspólnych scripts. +6. Przeniesienie MCP definitions do właściwego pliku i włączenie tylko jawnie wybranych optional capabilities. +7. Rozwiązanie `${PLUGIN_ROOT}`/`$KIRO_HOME`, absolutyzacja wymaganych resource paths i validation, że wszystkie paths pozostają w install root. +8. Wygenerowanie host-specific help, invocation examples i utility entrypoints. + +### Czego nie przenosić do install-time regexów + +- Globalnych substitutions typu `AskUserQuestion`→tekst, `Task tool`→inny tekst, plan-mode removal i headless defaults. To są decyzje semantyczne, które powinny pochodzić z jawnego bindingu/capability IR. +- Host detection na podstawie przypadkowych env vars bez explicit `--target`; installer powinien przyjmować target jawnie, a autodetection tylko potwierdzać lub zgłaszać konflikt. +- Secretów MCP i policy bypass; te pozostają host/user managed. + +## Proposed single-package contract + +```text +maister-dist/ + package.json|manifest-neutral.json + core/ + skills/ + runtime/ + references/ + assets/ + bindings/ + claude/ + codex/ + cursor/ + kiro-cli/ + installer/ + maister install --target [--scope ...] [--with-mcp ...] + maister verify --target --install-root +``` + +Minimalny installer contract: + +1. `--target` jest wymagany lub jednoznacznie autodetected i potwierdzony. +2. Target descriptor deklaruje supported host versions/capabilities; unknown version = warning lub fail zgodnie z policy. +3. Materialization odbywa się do pustego staging dir. +4. Validator sprawdza manifest/schema, referential integrity, brak obcych absolute paths, hook executable bits i target-specific forbidden vocabulary. +5. Installer tworzy backup/receipt z source version, target, host version, enabled options i hashes. +6. Commit to install root następuje przez atomic rename, a failure przywraca poprzedni receipt/tree. +7. Update powtarza ten sam deterministic compile; uninstall usuwa wyłącznie files z receipt. + +## Recommendation to synthesizer + +Preferowany wariant to **wspólny behavior/runtime core + cienkie host bindings materializowane przez jeden installer**. Jeden przenośny bundle jest realistyczny, natomiast „zero adapterów” nie jest. Największą redukcję złożoności da usunięcie commitowanych `plugins/maister-{cursor,codex,kiro}` po osiągnięciu deterministic install-time generation i golden/contract coverage, nie samo przeniesienie istniejących build scripts do komendy install. + +Kolejność migracji sugerowana przez te dowody: + +1. Ustabilizować neutralny inventory/IR dla skills, roles, gates, hooks i MCP. +2. Przepisać obecne regex transforms jako typed emitters per target; zachować golden outputs przejściowo. +3. Zbudować `install --target` ze staging/receipt/rollback i parity against existing generated trees. +4. Dopiero po parity usunąć committed variants; zostawić bindings i fixtures. +5. Uruchamiać wspólny core contract suite raz, target validators dla każdego hosta, E5/E6 tylko tam, gdzie binary/auth są dostępne. Claude pozostaje jawnie `runtime-unverified` do czasu wykonania rzeczywistego `claude -p` scenario. + +## Decision and risk handoff + +### Decisions + +- One distributed package with explicit `--target` is plausible and recommended. +- Installed host trees must remain different; the target adapter surface is unavoidable. +- Install-time materialization should be structural/typed and transactional, not a relocation of broad textual substitutions. +- `orchestrator-state.yml` is the portable continuation source of truth; native session resume is supplementary. +- Claude runtime parity remains unverified until a real Claude Code CLI run is available. + +### Risks + +- Fast-moving host plugin contracts, especially Cursor and Kiro, can invalidate descriptors. +- Semantic drift can hide inside prose/tool-name transforms even when generated layouts validate. +- Install-time compilation can leave broken user state without staging, receipts and rollback. +- Kiro CLI absolute resource-path workaround and CLI/IDE agent-format split require target/version-specific handling. +- Marketplace update semantics differ; a common installer may coexist with native marketplaces rather than replace them. diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/findings/test-assurance-runtime-gap.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/findings/test-assurance-runtime-gap.md new file mode 100644 index 00000000..e0040f72 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/findings/test-assurance-runtime-gap.md @@ -0,0 +1,277 @@ +# Test assurance i luka runtime hostów + +## TL;DR + +Repozytorium ma już dobry zalążek platformowo niezależnego rdzenia: wykonywalne moduły bramek, stanu i kontynuacji są testowane bez hosta, a identyczne pliki runtime są kopiowane do targetów. Obecna macierz miesza jednak testy tekstu, materializacji, instalacji i runtime pod wspólnymi nazwami `smoke`/`e2e`. Najbardziej jaskrawy przypadek: cele `fully-automatic-continuation.e2e.sh` dla Claude, Cursor i Kiro zawsze zwracają `77 UNAVAILABLE`; tylko Codex uruchamia uwierzytelniony host. + +Rekomendowany kierunek assurance to jedna pełna suita executable-contract dla wspólnego core, parametryczny contract harness dla cienkich adapterów/materializera oraz osobne, jawnie warunkowe host-runtime probes. Bez runtime Claude Code można uczciwie osiągnąć E4 (atomowa instalacja i poprawny installed shape), ale nie E5/E6. Obecny stan Claude to E1 jako dowód specyficzny dla hosta oraz E3 tylko dla wspólnego zachowania, które ma działać w każdym hoście. + +## Key Decisions + +- Testy należy klasyfikować po tym, co faktycznie wykonują, nie po nazwie pliku: `structural`, `transform`, `core-contract`, `install`, `host-smoke`, `host-runtime-e2e`. +- Wspólny runtime powinien przechodzić pełną suitę dokładnie raz; adaptery powinny przechodzić tylko kontrakt mapowania, materializacji, instalacji i minimalny runtime probe. +- Capability `supported` nie może wynikać z shared runnera ani static checks; musi być wyprowadzane z aktualnego host-native evidence target i fail-closed dla `77`, missing, skipped lub failed. +- Dla Claude Code bez runtime raport może deklarować najwyżej E4 po dodaniu izolowanego testu instalacji; E5/E6 pozostają `unverified`. + +## Open Questions / Risks + +- Nie ma repozytoryjnego testu instalacji canonical Claude pluginu ani adapter harnessu, więc poprawność host discovery pozostaje nieudowodniona. +- PR CI sprawdza reproducibility generated variants, ale nie uruchamia `make validate`; duża część testów działa dopiero przy tagu release albo lokalnie. +- Codex native E2E dowodzi aktywnego tool loop i kontynuacji, lecz nie instaluje pluginu ani nie wywołuje workflow przez host discovery; nie należy rozszerzać jego wniosku na pełny plugin E2E. +- Obecne instalatory Cursor i Kiro usuwają zawartość celu przed kopiowaniem, więc nie zapewniają transakcyjnego rollbacku przy przerwaniu instalacji. + +## Zakres i metoda + +Przeanalizowano `Makefile`, workflow GitHub Actions, macierz capabilities, wspólne testy executable, target-specific install/smoke/E2E oraz skrypty instalacji. Dodatkowo 2026-07-14 uruchomiono lokalnie, bez hostów i bez modyfikowania globalnej instalacji: + +- `tests/gate-evaluator.test.sh` — 6/6; +- `tests/orchestrator-state-repository.test.sh` — 3/3; +- `tests/workflow-continuation.test.sh` — 5/5; +- `tests/phase-continue-contract.test.sh` dla source runnera — 6/6. + +W środowisku nie było polecenia `claude`; dostępność pozostałych CLI została tylko wykryta przez `command -v`, bez ich uruchamiania. + +## Findings + +### Finding 1: wspólny executable core istnieje, ale quality gate nie uruchamia całej jego suity + +- **Claim:** Moduły evaluator/state/continuation są bezpośrednio importowane z canonical `plugins/maister/.../bin` i mają rzeczywiste testy zachowania, w tym retry, transakcyjność, lease/reclaim i idempotencję. Jednak `make validate-contract` uruchamia tylko test dokumentacyjno-strukturalny engine, runner contract, jeden happy-path fully-automatic oraz capability projection; nie uruchamia osobno `gate-evaluator`, `orchestrator-state-repository` ani `workflow-continuation`. +- **Evidence:** + - `tests/gate-evaluator.test.sh:14-17` — test importuje canonical evaluator i schema; `tests/gate-evaluator.test.sh:48-69` buduje pełny gate context i role config. + - `tests/orchestrator-state-repository.test.sh:26-43` — wykonuje commit i sprawdza revision/mode; `tests/orchestrator-state-repository.test.sh:46-105` sprawdza byte-exact non-mutation, lock, symlink i injected failure. + - `tests/workflow-continuation.test.sh:16-24` — importuje executable continuation/repository; `tests/workflow-continuation.test.sh:34-88` wykonuje same-phase, phase-entry, reclaim i acknowledgement safety. + - `Makefile:24-30` — pełna lista poleceń `validate-contract` nie zawiera tych trzech suit. +- **Evidence level:** E3. +- **Confidence:** high — kod testów i wiring Makefile są bezpośrednim dowodem; lokalny run potwierdził przejście suit. +- **Inference/limitation:** Przejście core E3 nie dowodzi, że host dostarczy poprawne prymitywy UI/delegation/continuation. + +### Finding 2: pełny runner contract jest powtarzany cztery razy na byte-identical projections + +- **Claim:** `validate-phase-continue` uruchamia tę samą suitę kontraktową dla source, Codex, Cursor i Kiro, podczas gdy osobny target wymaga byte-identical kopii wspólnych runtime files. To daje pewność projection/import-path, ale powiela koszt pełnej suity dla kodu, który według kontraktu ma być identyczny. +- **Evidence:** + - `Makefile:3-7` — macierz czterech ścieżek runnera. + - `Makefile:57-66` — ta sama `tests/phase-continue-contract.test.sh` jest wykonywana dla każdego wpisu. + - `Makefile:68-81` — binding i wspólne runtime files są porównywane przez `cmp` z canonical source. + - `tests/phase-continue-contract.test.sh:4-6` — test różnicuje runner wyłącznie zmienną `PHASE_CONTINUE_RUNNER`. +- **Evidence level:** E3 dla zachowania source + E2/E3 dla projekcji targetów. +- **Confidence:** high. +- **Inference/limitation:** Nie rekomenduję usunięcia wszystkich target checks: każdy target nadal potrzebuje krótkiego `node --check`, checksum/import-resolution i jednego canary contract. Pełna macierz edge cases może działać raz na core. + +### Finding 3: trzy z czterech nazwanych host E2E są wyłącznie sentinelami unavailable + +- **Claim:** Claude, Cursor i Kiro `fully-automatic-continuation.e2e.sh` nie uruchamiają hosta, adaptera ani shared runnera. Każdy wypisuje komunikat i kończy kodem 77. Nie są nawet structural/golden tests — są jawnym rekordem braku dowodu. +- **Evidence:** + - `tests/host-continuation/claude.e2e.sh:1-5` — bezwarunkowe `UNAVAILABLE` i `exit 77`. + - `platforms/cursor/tests/fully-automatic-continuation.e2e.sh:1-5` — bezwarunkowe `UNAVAILABLE` i `exit 77`. + - `platforms/kiro-cli/tests/fully-automatic-continuation.e2e.sh:1-5` — bezwarunkowe `UNAVAILABLE` i `exit 77`. +- **Evidence level:** E0 jako deklaracja luki; E5/E6 `unverified`. +- **Confidence:** high. +- **Inference/limitation:** Sama obecność pliku `.e2e.sh` nie podnosi assurance. Powinien być raportowany jako `evidence=unavailable`, nie jako test passed/skipped bez kontekstu. + +### Finding 4: Codex target naprawdę uruchamia host, lecz zakres dowodu jest węższy niż pełny plugin E2E + +- **Claim:** Codex E2E wymaga binarki i zalogowanego runtime, uruchamia `codex ... exec`, obserwuje kolejność tool command → marker → final message i weryfikuje persisted trace. Bootstrap importuje wygenerowany Codex binding/runtime. Test nie wykonuje jednak marketplace install ani hostowego wywołania skilla; prompt nakazuje bezpośrednio uruchomić repozytoryjny bootstrap. +- **Evidence:** + - `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh:8-18` — fail-closed `77` bez uwierzytelnionego Codex. + - `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh:34-56` — host dostaje prompt i uruchamia bootstrap w aktywnym `codex exec`. + - `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh:64-88` — sprawdzenie markera, final message, trace i kolejności zdarzeń. + - `platforms/codex-cli/tests/native-evidence-bootstrap.mjs:8-13` — bootstrap importuje generated Codex binding/repository i canonical capability matrix. + - `platforms/codex-cli/tests/native-evidence-bootstrap.mjs:87-163` — wykonuje binding z mockowanymi portami Advisor/Arbiter/User/Target i sprawdza resume. + - `platforms/codex-cli/tests/fully-automatic-continuation.e2e.sh:118-135` — izolacja bootstrapu i fail-closed unavailable. +- **Evidence level:** E6 dla konkretnej aktywnej pętli host tool-use + continuation binding; nie E6 dla install/discovery/workflow invocation. +- **Confidence:** high. +- **Inference/limitation:** Nazwa „native continuation E2E” jest uzasadniona, ale claim powinien być scenariuszowy: „Codex executes and observes the continuation bridge”, nie „pełny Maister działa E2E w Codex”. + +### Finding 5: capability matrix poprawnie odrzuca shared-runner evidence i fail-closed mapuje wynik + +- **Claim:** Capability `supported` jest przyznawane tylko po `passed` target-specific executable. Missing, non-executable, `77` i failure mapują się na `unsupported`; shared contract targets są jawnie zakazane jako native evidence. +- **Evidence:** + - `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml:6-18` — Claude/Cursor/Kiro są `unsupported`, Codex `supported`, każdy z własnym targetem. + - `Makefile:32-45` — executable target jest uruchamiany, `0 → passed`, `77 → unavailable`, reszta → failed; tylko `passed → supported`. + - `Makefile:47-55` — validator odrzuca shared targets i porównuje deklarację z projekcją evidence. + - `tests/host-capability-matrix.test.sh:48-63` — missing/skipped/unavailable/inconclusive/failed fail closed, shared runner nie kwalifikuje hosta. +- **Evidence level:** E3 dla mechanizmu projekcji; poziom hosta zależy od targetu. +- **Confidence:** high. +- **Inference/limitation:** Stan capability jest globalnym booleanem dla continuation, nie opisuje wersji hosta, scenariusza ani świeżości evidence; przy większej liczbie capabilities potrzebny będzie record `{capability, host, version, evidence_level, timestamp, target}`. + +### Finding 6: `make validate` jest głównie structural/contract/install; host smokes nie są jego częścią + +- **Claim:** Cursor validation jawnie deklaruje structural-only, Kiro i Cursor uruchamiają `smoke-cli --contract`, a Codex `smoke-cli.sh` wyłącznie parsuje wygenerowane pliki i grepuje kontrakty. Żaden z tych trzech kroków w `make validate` nie jest host-runtime smoke. +- **Evidence:** + - `Makefile:92-94` — komentarz definiuje Cursor checks jako structural only i wyklucza live hook behavior. + - `Makefile:186-190` — Cursor inventory/install oraz `smoke-cli.sh --contract`. + - `platforms/cursor/smoke-cli.sh:10-37` — `--contract` wykonuje tylko file/grep checks i wychodzi przed sprawdzeniem CLI. + - `Makefile:286-287` i `platforms/kiro-cli/smoke-cli.sh:32-54` — Kiro validation również wybiera contract-only path. + - `Makefile:289-295` i `platforms/codex-cli/smoke-cli.sh:9-21` — Codex smoke buduje i waliduje JSON/layout; nie wywołuje `codex`. +- **Evidence level:** E1–E4 zależnie od podtestu; nie E5. +- **Confidence:** high. +- **Inference/limitation:** Nazwa `smoke-cli.sh` przy Codex jest myląca w quality gate; lepsza nazwa to `plugin-contract.test.sh`. + +### Finding 7: istnieją realne host smokes dla Cursor/Kiro, ale są opcjonalne i nierówne w CI + +- **Claim:** Cursor full smoke naprawdę uruchamia `agent`, wykrywa plugin, deleguje custom agent i tworzy artifact. Kiro full smoke naprawdę uruchamia `kiro-cli` przez wrapper oraz testuje discovery/delegation/artifacts, ale bez binarki kończy sukcesem po komunikacie SKIP. Tylko Cursor ma dedykowany tygodniowy workflow, który również może zakończyć sukcesem bez smoke z powodu braku CLI/API key. +- **Evidence:** + - `platforms/cursor/smoke-cli.sh:39-60` — wymagane `agent`, auth i host invocation z `--plugin-dir`. + - `platforms/cursor/smoke-cli.sh:63-100` — runtime plugin detection, subagent, quick-plan artifact i sentinel skill resolution. + - `platforms/kiro-cli/smoke-cli.sh:98-109` — rzeczywisty `kiro-cli chat --no-interactive` przez wrapper. + - `platforms/kiro-cli/smoke-cli.sh:111-148` — detection, delegation oraz plan artifacts. + - `platforms/kiro-cli/smoke-cli.sh:185-188` — brak CLI daje SKIP i exit 0. + - `.github/workflows/cursor-cli-smoke.yml:1-10` — weekly/manual, non-blocking wobec PR/push. + - `.github/workflows/cursor-cli-smoke.yml:27-59` oraz `:61-76` — instalacja lub brak secretu może pominąć smoke bez failure. +- **Evidence level:** E5, kiedy host smoke faktycznie się wykona i przejdzie; E0, gdy tylko istnieje skrypt; `unavailable` przy skip. +- **Confidence:** high. +- **Inference/limitation:** Kiro `tests/e2e-matrix.test.sh` nie jest runtime E2E: sam opisuje się jako structural/doc (`platforms/kiro-cli/tests/e2e-matrix.test.sh:1-3`) i sprawdza dokumentację/output (`:32-99`). + +### Finding 8: PR CI nie uruchamia validate; release jest pierwszym automatycznym pełnym gate + +- **Claim:** Workflow PR/push tylko buduje trzy warianty i sprawdza `git diff`. `make validate` jest uruchamiane dopiero w workflow tagów `v*`. To oznacza, że nawet obecne E1–E4 quality gates nie są obowiązkowe na pull requestach. +- **Evidence:** + - `.github/workflows/validate-generated-variants.yml:15-24` — jedyny job buduje warianty. + - `.github/workflows/validate-generated-variants.yml:24-48` — jedyna walidacja to diff generated trees. + - `.github/workflows/release.yml:1-13` — dopiero tag `v*` uruchamia `make build && make validate`. +- **Evidence level:** E0/E2 (pipeline intent i reproducibility). +- **Confidence:** high. +- **Inference/limitation:** Dokumentacja architektury mówi łącznie „make validate and CI ... run structural/contract checks” (`.maister/docs/project/architecture.md:52-58`), co może sugerować silniejsze PR coverage niż implementuje obecny workflow. + +### Finding 9: install tests są użyteczne, lecz nie tworzą jednolitego, transakcyjnego kontraktu + +- **Claim:** Cursor i Codex testują MCP default/opt-in na temp trees. Kiro ma szerszy izolowany install test. Nie ma odpowiednika dla Claude. Cursor/Kiro production-like install najpierw czyszczą dest i kopiują nowy tree, więc przerwanie może zostawić częściową instalację; Codex helper używa tmp+mv tylko dla pojedynczego manifestu po host-managed install. +- **Evidence:** + - `platforms/cursor/tests/install.test.sh:9-18` — temp install i MCP assertions. + - `platforms/codex-cli/tests/install.test.sh:13-28` — temp trees i apply/remove MCP helper; nie uruchamia `codex plugin add`. + - `platforms/kiro-cli/tests/smoke.test.sh:39-60` — izolacja od personal `~/.kiro`; `:62-93` — default/alias/MCP checks. + - `platforms/cursor/smoke-install.sh:49-60` — build, `rm -rf DEST`, copy. + - `platforms/kiro-cli/smoke-install.sh:105-121` — build, clear target, copy, post-copy transforms. + - `platforms/codex-cli/smoke-install.sh:30-43` — manifest mutation przez tmp+mv; `:99-120` — rzeczywisty host marketplace install jest poza testem temp-tree. +- **Evidence level:** E4 dla testowanych temp install behaviors; E1 dla Claude packaging; brak E4 Claude. +- **Confidence:** high. +- **Inference/limitation:** Install-time materializer powinien najpierw tworzyć pełny staged tree, walidować go, a następnie atomowo zamieniać docelowy katalog albo przywracać snapshot. + +## Macierz aktualnego dowodu + +| Warstwa / host | Claude | Cursor | Kiro | Codex | +|---|---:|---:|---:|---:| +| Canonical/shared core behavior | E3, applicable by inference | E3 | E3 | E3 | +| Generated/static host shape | E1 (canonical manifest) | E1 | E1 | E1 | +| Deterministic materialization | n/a dla canonical source | E2 | E2 | E2 | +| Install contract | brak | E4 temp tree | E4 isolated profile | E4 helpers, nie marketplace install | +| Host discovery/smoke | brak | E5 warunkowo | E5 warunkowo | brak ogólnego plugin smoke w gate | +| Host runtime continuation E2E | unavailable | unavailable | unavailable | E6 dla wąskiego continuation scenario | + +**Ważne rozróżnienie:** najwyższy dowód zachowania wspólnego, który można przypisać Claude, to E3; najwyższy aktualny dowód specyficzny dla Claude host contract to E1. Bez runtime można podnieść host-specific assurance do E4, ale nie do E5/E6. + +## Proponowany evidence ladder E0–E6 + +| Poziom | Wymagany dowód | Dozwolony claim | Niedozwolony claim | +|---|---|---|---| +| E0 | dokument, capability declaration, manual checklist | zamierzony kontrakt / znana luka | implementacja działa | +| E1 | parser/schema/static adapter contract | host-native tree ma wymagany shape i vocabulary | host odkrywa lub wykonuje plugin | +| E2 | deterministic materializer + golden/inventory/checksum | ten input i adapter dają reprodukowalny output | semantyka hosta jest równoważna | +| E3 | executable core contract na fixtures/ports | portable behavior spełnia invarianty niezależnie od hosta | adapter dostarcza prawidłowe prymitywy | +| E4 | isolated install/update/uninstall/rollback test | staged tree, config mutations i rollback są poprawne | host odkrywa plugin | +| E5 | prawdziwy host CLI smoke z wersją i auth | host odkrywa package i wykonuje wąską ścieżkę | pełna parity workflows | +| E6 | host runtime E2E konkretnego scenariusza | scenariusz działa na zapisanej wersji hosta | pełna/przyszła kompatybilność | + +Każdy wynik powinien emitować rekord maszynowy, np. `host`, `capability`, `host_version`, `evidence_level`, `status`, `scenario`, `timestamp`, `target`, zamiast pojedynczego globalnego `supported`. + +## Proponowany contract harness + +### 1. Jedna suita portable core + +Uruchamiać raz przeciw canonical modułom: + +- schema + state repository; +- gate evaluator i policy/denylist; +- continuation/outbox/idempotency; +- report projection; +- failure injection i transactional non-mutation. + +Włączyć istniejące `gate-evaluator`, `orchestrator-state-repository`, `workflow-continuation` i runner contract do jednego `make test-core`; podpiąć go do PR CI. + +### 2. Wersjonowany kontrakt adaptera + +Każdy adapter implementuje mały descriptor/port contract, np.: + +- `host_id`, `contract_version`, minimal/max host version; +- layout/manifest schema i discovery root; +- mapowanie invocation names, skills/commands/agents/hooks; +- prymitywy `present_user_gate`, `invoke_subagent`, `phase_continue` i capability status; +- install transforms i dozwolone post-processing; +- unsupported capabilities z jawnym fallbackiem. + +Parametryczny harness uruchamia tę samą tabelę testów dla `claude|cursor|kiro|codex`, ale nie kopiuje pełnych testów core. Sprawdza tylko mapping, brak host-obcego vocabulary, required files, schema, permissions i referential integrity. + +### 3. Materializer contract E2 + +Dla wspólnego package + `install --target HOST`: + +1. materializuj do temp staging directory; +2. waliduj descriptor/schema/inventory; +3. porównaj semantyczny manifest z golden fixture (nie cały duży snapshot tekstowy); +4. sprawdź deterministic rebuild; +5. wykonaj jeden canary core runner z installed path, aby wykryć broken imports; +6. dopiero potem atomic swap do destination. + +To zachowuje wartość obecnej czterokrotnej runner matrix bez czterokrotnego wykonywania wszystkich edge cases. + +### 4. Install contract E4 dla każdego hosta, także Claude + +Wspólna tabela przypadków: + +- fresh install, reinstall same version, upgrade, downgrade policy; +- invalid target/version/config; +- injected failure przed i po validation; +- byte-exact rollback, modes, symlinks i directory topology; +- uninstall usuwa wyłącznie managed files; +- offline mode bez globalnych side effects. + +Dla Claude można to wykonać bez `claude`: materializer instaluje do tymczasowego `CLAUDE_CONFIG_DIR`/fixture discovery root, waliduje `.claude-plugin/plugin.json`, commands/skills/agents/hooks oraz rollback. To jest E4, nie host discovery. + +### 5. Minimalne host-native probes E5/E6 + +Oddzielne targety, które zawsze zwracają jeden z: `passed`, `failed`, `unavailable(77)`, nigdy cichy sukces po skipie: + +- E5: install/discover + invoke sentinel skill/agent; +- E6: jeden krytyczny workflow scenario, gate interaction i continuation; +- zapis host version, model/config constraints i raw trace artifact; +- scheduled dla niestabilnych/sekretnych hostów, required tylko tam, gdzie runtime jest dostępny i stabilny. + +Claude pozostaje E4 do czasu pozyskania runtime/CI credential lub wykonania ręcznego E5/E6 na zarejestrowanej wersji. Sentinel `claude.e2e.sh` jest dobrym fail-closed placeholderem, ale dashboard powinien pokazywać go jako lukę, nie zielony test. + +## Rekomendowana zmiana macierzy testów + +| Target | Częstotliwość | Zawartość | +|---|---|---| +| `test-core` | każdy PR | pełny E3 raz na canonical core | +| `test-materializer` | każdy PR | E2 dla wszystkich adapter descriptors | +| `test-adapter-contract HOST` | każdy PR | E1 + canary E3 installed-path per host | +| `test-install HOST` | każdy PR | E4 na izolowanym root, atomicity/rollback | +| `test-host-smoke HOST` | nightly/manual/available PR | E5, fail/77 rozróżnione | +| `test-host-e2e HOST SCENARIO` | scheduled/release evidence | E6 scenariuszowe | +| `validate-capabilities` | każdy PR/release | projekcja tylko z odpowiedniego targetu i świeżego evidence record | + +## Wnioski architektoniczne + +1. **Jedno rozwiązanie jest realne na poziomie behavior/runtime core.** Obecne testy już pokazują, że state/gate/continuation wykonują się poza hostem. +2. **Nie należy dążyć do jednego fizycznego installed tree.** E1/E4 pozostają host-specific, bo layout, manifest, discovery, agents i hooks są częścią kontraktu hosta. +3. **Najlepsza granica to wspólny core + install-time materializer + cienkie adapter descriptors.** Testy core działają raz, a host matrix mierzy tylko różnice, które rzeczywiście należą do hosta. +4. **Brak Claude runtime nie blokuje migracji.** Blokuje wyłącznie E5/E6 claim; E1–E4 można i należy budować lokalnie, jawnie oznaczając granicę dowodu. + +## Decisions (verbatim handoff) + +- Adopt one full E3 executable-contract suite for the canonical portable core and run it once per change. +- Retain per-host checks only for adapter mapping, installed-path canary execution, materialization, installation, and native runtime behavior. +- Treat `exit 77` as explicit unavailable evidence and never as a passing or silently skipped host test. +- Define Claude Code assurance as current host-specific E1 / shared-core E3; target E4 without runtime, while keeping E5/E6 unverified. +- Make install-time materialization staged, validated, atomic, and rollback-tested before it replaces any host destination. +- Add core, materializer, adapter-contract, and isolated install suites to pull-request CI; keep credentialed host probes separately visible. + +## Risks (verbatim handoff) + +- PR CI currently proves generated reproducibility but not the repository's complete structural, contract, or install validation. +- Claude Code has no repository-owned install contract or native runtime evidence; host discovery and execution remain unknown. +- Codex native continuation E2E can be overinterpreted because it drives a repository bootstrap directly rather than invoking an installed Maister workflow through discovery. +- Cursor and Kiro installation scripts can leave partial destinations because they delete before copying instead of staging and atomically swapping. +- A single boolean host capability can hide scenario, host-version, freshness, and evidence-level differences. +- Renaming tests without changing their execution semantics will not fix assurance ambiguity; result metadata and CI routing must enforce the ladder. + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/synthesis.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/synthesis.md new file mode 100644 index 00000000..eff63b85 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/analysis/synthesis.md @@ -0,0 +1,234 @@ +# Synteza: platformowo niezależny Maister + +## TL;DR +Maister może mieć jedno źródło zachowania, jeden testowalny rdzeń i jeden bundle dystrybucyjny, ale nie jeden identyczny katalog instalacyjny ani jeden wspólny runtime hosta. +Najlepszy kierunek to portable core + wersjonowane kontrakty hostów + strukturalny materializer uruchamiany przez `install --target`. +Pełny neutralny IR warto wprowadzać ewolucyjnie tylko dla miejsc, których nie da się bezpiecznie opisać typowanymi primitives i templates. +Brak runtime Claude Code nie blokuje E1–E4 ani migracji, ale pozostawia discovery i wykonanie E5/E6 niezweryfikowane. + +## Key Decisions +- Przyjąć trzy różne znaczenia „jednego rozwiązania”: jedno źródło, jeden bundle oraz jeden runtime; celem są dwa pierwsze i wspólny portable runtime, nie jeden runtime hosta. +- Wybrać architekturę portable behavior/runtime core + cienkie, wersjonowane host adapters + install-time materializer. +- Zastąpić globalne transformacje prozy jawnie oznaczonymi primitives, typed descriptors i host-aware templates; neutralny IR rozszerzać tylko tam, gdzie przynosi mierzalną wartość. +- Utrzymać testy per host wyłącznie dla kontraktu adaptera, materializacji, instalacji i prawdziwych probes hosta; pełną suitę core wykonywać raz. +- Nie usuwać commitowanych wariantów przed osiągnięciem deterministycznej parity, transakcyjnego installera i odtwarzalnych release artifacts. + +## Open Questions / Risks +- Największym ryzykiem nie jest layout, lecz semantyczna transformacja gate/delegation/progress/hooks ukryta dziś w zamianach tekstowych. +- Host contracts, szczególnie Cursor i rozdział Kiro CLI/IDE, mogą zmieniać się szybciej niż wersjonowane descriptors. +- Install-time compilation przenosi awarię na maszynę użytkownika; bez staging, validation, receipt, atomic swap i rollback pogorszy niezawodność. +- Claude Code pozostanie `runtime-unverified` do czasu realnego E5/E6 na zapisanej wersji binarki i scenariusza. +- Trzeba rozstrzygnąć, czy marketplaces otrzymują prebuilt artifacts z tego samego materializera, czy uruchamiają compiler po stronie klienta. + +## 1. Triangulacja ustaleń + +Trzy niezależne strumienie dowodów zbiegają się w tym samym miejscu: + +1. **Rdzeń jest realnie przenośny.** Pięć modułów ESM odpowiedzialnych za state, gate i continuation jest identycznych w targetach, a testy wykonują ich zachowanie poza hostem (`analysis/findings/canonical-core-boundary.md:57-81`; `analysis/findings/test-assurance-runtime-gap.md:34-58`). +2. **Źródło instrukcji nie jest neutralne.** `plugins/maister/` jest Claude-native, zaś inne targety odzyskują własny kontrakt poprzez rozległe, częściowo semantyczne rewrites (`analysis/findings/canonical-core-boundary.md:33-55`, `analysis/findings/canonical-core-boundary.md:83-123`). +3. **Installed shape musi pozostać host-native.** Manifesty, discovery, agents, hooks, MCP i invocation różnią się kontraktowo, więc wspólny bundle musi materializować różne outputy (`analysis/findings/host-contracts-installation.md:29-63`). +4. **Testy nie powinny być mnożone razem z outputami.** Core można testować raz; adapter i install potrzebują parametrycznego harnessu, a host runtime osobnych, jawnie warunkowych probes (`analysis/findings/test-assurance-runtime-gap.md:163-250`). + +Nie ma sprzeczności między „jednym rozwiązaniem” a różnymi outputami. Sprzeczność powstaje dopiero wtedy, gdy „jedno rozwiązanie” zostanie błędnie utożsamione z jednym fizycznym drzewem lub pełną runtime parity. + +## 2. Trzy poziomy niezależności + +| Poziom | Realistyczny cel | Ocena | +|---|---|---| +| Jedno źródło | Jeden neutralny model zachowania, assets, role intents i portable runtime | Tak; obecny core już to częściowo realizuje | +| Jeden bundle dystrybucyjny | Core + descriptors/templates + installer, wybór `--target` podczas instalacji | Tak; obecne buildy dowodzą wykonalności materializacji | +| Jeden runtime | Ten sam mechanizm discovery, tools, subagents, hooks i session semantics | Nie; runtime należy do hosta i pozostaje poza kontrolą Maister | + +Wniosek: rozwiązanie może być niezależne od narzędzia na poziomie **intencji i zachowania domenowego**, ale integracja pozostaje zależna od hosta na granicy wejścia/wyjścia. To jest właściwa granica modułu, nie porażka portability. + +## 3. Granica portable / platform-specific + +### Portable core + +- graf faz, bramki, safety invariants i reguły wznowienia; +- schema/repository `orchestrator-state.yml`, outbox, idempotency, gate history; +- portable ESM helpers i report projections; +- kontrakty artefaktów, role intents oraz wspólne bodies skills; +- neutralne metadata pluginu, MCP server definitions bez secretów i hook intent. + +### Host adapter/materializer + +- root marker, manifest/catalog, discovery root i namespace; +- mapping skills/commands oraz invocation syntax; +- MD/TOML/JSON agent serialization, tool names, trust i concurrency; +- `present_user_gate`, delegation, progress/planning projection i headless fallback; +- hook event schema, matchers, environment, root variables i output contract; +- MCP placement/policy, native marketplace/install scope i host session UX. + +Dowody pokazują, że agents, gates i hooks są granicą semantyczną, a nie kosmetyczną (`analysis/findings/host-contracts-installation.md:81-111`). Dlatego adapter nie może być tylko mapą nazw plików. + +## 4. Porównanie wariantów + +Skala 1–5: 5 oznacza wynik najlepszy. Oceny są syntezą kosztu źródeł, udziału wspólnego testowalnego zachowania, fragility transformacji, host-native compatibility, reprodukowalności i migracji. Źródła bazowe: inventory transformacji i projekcji (`analysis/findings/canonical-core-boundary.md:83-133`), host contracts (`analysis/findings/host-contracts-installation.md:29-158`) oraz test ladder (`analysis/findings/test-assurance-runtime-gap.md:150-250`). + +| Wariant | Utrzymanie | Testowalny core | Odporność transformacji | Host compatibility | Migracja/rollback | Razem /25 | Confidence | +|---|---:|---:|---:|---:|---:|---:|---| +| A. Obecne build-time variants | 2 | 3 | 2 | 4 | 4 | 15 | high | +| B. Obecne skrypty przeniesione 1:1 do installera | 3 | 3 | 1 | 4 | 2 | 13 | high | +| C. Portable core + typed thin adapters + install-time materializer | 5 | 5 | 4 | 5 | 4 | **23** | high dla kierunku, medium dla API | +| D. Pełny neutralny IR + generatory hostów | 4 | 5 | 5 | 4 | 2 | 20 | medium | + +### A. Build-time generated variants + +Zachowuje review diff i gotowe marketplace artifacts, ale wersjonuje 610 plików/~5,08 MB projekcji i powiela testowanie identycznego runtime. Jest bezpieczną bazą migracji, nie najlepszym stanem docelowym (`analysis/findings/canonical-core-boundary.md:125-133`). + +### B. Install-time compiler bez zmiany modelu + +Spełnia ergonomiczne `--target`, lecz relokuje około 320 substytucji i ich silent-failure surface na maszynę użytkownika. Upraszcza repo pozornie, a pogarsza transaction boundary. Tego wariantu nie rekomendujemy (`analysis/findings/canonical-core-boundary.md:101-123`; `analysis/findings/host-contracts-installation.md:126-142`). + +### C. Shared portable core + thin adapters + +Najlepiej wykorzystuje istniejący seam. Wspólne invariants i helpers są testowane raz; descriptor deklaruje capabilities, renderer tworzy native shape, a installer kontroluje transakcję. To rekomendowany target architecture. + +### D. Neutralny IR + +Docelowo może usunąć zależność prozy od host-specific vocabulary, lecz pełny AST/DSL podnosi koszt migracji i może pogorszyć ergonomię edycji promptów. IR jest uzasadniony dla strukturalnych elementów — gates, role, hooks, metadata i capability branches — ale nie jako warunek wstępny dla całej migracji. Należy go pogłębiać na podstawie prototypów, nie projektować kompletnie z góry (`analysis/findings/canonical-core-boundary.md:136-172`). + +## 5. Rekomendowana architektura + +```text +maister-dist/ + core/ + workflows/ # host-neutral behavior + oznaczone primitives + runtime/ # state/gate/continuation ESM + roles/ # intent, nie format MD/TOML/JSON + assets/ + contracts/ + host.schema.json + capability.schema.json + adapters/ + claude/ + codex/ + cursor/ + kiro-cli/ + installer/ + materialize + validate + commit + rollback +``` + +Interfejs adaptera powinien być wersjonowany i zawierać co najmniej: `host_id`, zakres wersji, capability states, layout/manifest schema, invocation mapping, agent/hook emitters, unsupported fallbacks i native evidence target. Default dla nieznanej capability powinien być fail-closed. + +### Explicit non-goals + +- Jeden identyczny installed tree dla wszystkich hostów. +- Emulowanie brakującej capability za pomocą niejawnego prompt rewrite. +- Zastąpienie natywnych marketplaces jednym prywatnym mechanizmem instalacji. +- Deklarowanie pełnej parity tylko na podstawie schema, golden lub wspólnego core. +- Budowa kompletnego DSL/IR przed walidacją minimalnych typed primitives. +- Usunięcie wszystkich testów per host. + +## 6. Kontrakt `install --target` + +Proponowana ergonomia: + +```text +maister install --target claude|codex|cursor|kiro-cli \ + [--scope user|project|local] [--dest PATH] [--with-mcp NAME] \ + [--host-version VERSION] [--offline] +``` + +Pipeline: + +1. **Resolve** — `--target` jest jawny; autodetection może tylko zasugerować lub potwierdzić, a konflikt kończy się błędem. +2. **Type-check** — załaduj descriptor zgodny ze schema i sprawdź zakres wersji/capabilities. +3. **Materialize** — wygeneruj kompletne native tree w pustym staging dir; nie modyfikuj destination. +4. **Validate** — schema, inventory, referential integrity, forbidden vocabulary, path containment, executable bits, semantic golden i installed-path canary. +5. **Receipt** — zapisz source version, adapter/contract version, target, detected host version, options, hashes, destination i previous receipt. +6. **Atomic commit** — backup istniejącego managed tree, rename staged tree w tej samej filesystem boundary, potem osobno kontrolowane config/marketplace mutations. +7. **Rollback** — przy dowolnym failure przywróć poprzedni tree, receipt, modes, symlinks i config byte-exact; nowy receipt staje się aktywny dopiero po pełnym commit. +8. **Verify** — zwróć maszynowy evidence record; runtime probe jest osobnym krokiem i nie może zmieniać wyniku E4 na E5 bez rzeczywistego hosta. + +Update wykonuje ten sam deterministic compile. Uninstall usuwa tylko ścieżki zarządzane przez receipt. Prebuilt marketplace artifacts powinny powstawać w CI z tego samego materializera, dzięki czemu klient nie musi mieć build toolchainu (`analysis/findings/host-contracts-installation.md:186-214`). + +## 7. Strategia testów + +### Testowane raz + +- schema/state repository, atomic state transitions i failure injection; +- gate evaluator, policy, denylist, Advisor/Arbiter records; +- continuation/outbox/idempotency/reclaim; +- report projection i wspólne workflow invariants; +- deterministyczne utilities niekorzystające z host APIs. + +Repo ma już E3 dla istotnej części tego rdzenia, choć PR quality gate nie uruchamia wszystkich suit (`analysis/findings/test-assurance-runtime-gap.md:36-58`, `analysis/findings/test-assurance-runtime-gap.md:125-134`). + +### Pozostające per host + +- E1 adapter contract: descriptor, schema, vocabulary, required/forbidden files; +- E2 materializer: deterministyczność, semantic golden, checksums, installed-path canary; +- E4 install: fresh/reinstall/upgrade/uninstall, atomicity, rollback, permissions, topology; +- E5 host smoke: discovery + sentinel skill/agent; +- E6 scenario E2E: krytyczny workflow, user gate, delegation i continuation. + +Wynik powinien mieć pola `{host, capability, host_version, adapter_version, evidence_level, status, scenario, timestamp, target}`. `exit 77` oznacza `unavailable`, nigdy pass (`analysis/findings/test-assurance-runtime-gap.md:60-95`). + +## 8. Claude Code: evidence ceiling + +W badanym środowisku nie ma runtime `claude`. Oficjalna dokumentacja opisuje `claude -p`, plugin loading i session continuation, ale jest to dowód kontraktu produktu, nie wykonania Maister: [Claude Code headless](https://code.claude.com/docs/en/headless), [Claude Code plugins reference](https://code.claude.com/docs/en/plugins-reference). + +Aktualnie: + +- host-specific shape: E1; +- wspólny core: E3, stosowalny do Claude przez wspólny kontrakt; +- install: brak repo-owned E4 dla Claude; +- discovery/runtime: E5/E6 `unverified`. + +Po wdrożeniu izolowanego testu staged install do fixture `CLAUDE_CONFIG_DIR` można uczciwie osiągnąć E4 bez binarki. Nadal nie wolno twierdzić, że Claude odkrywa plugin, wiąże tools lub wykonuje workflow. Granicę tę potwierdzają zarówno sentinel `exit 77`, jak i fail-closed capability matrix (`analysis/findings/test-assurance-runtime-gap.md:60-95`, `analysis/findings/test-assurance-runtime-gap.md:150-175`). + +## 9. Migracja z kryteriami wyjścia i rollbacku + +### M0 — Baseline i nazwanie testów + +- Exit: inventory current outputs, evidence records, `test-core` w PR CI, obecne buildy pozostają źródłem release. +- Rollback: tylko zmiany CI/nazw; powrót do dotychczasowych targets bez wpływu na użytkownika. + +### M1 — Portable primitives i Host Contract v1 + +- Zastąpić reprezentatywne gate/delegation/progress rewrites oznaczonymi primitives; descriptor dla czterech hostów. +- Exit: canonical behavior nie zawiera wybranych host tokens; parametryczny E1 przechodzi dla wszystkich targetów. +- Rollback: renderer może emitować dotychczasowy tekst; build-time variants nadal obowiązują. + +### M2 — Typed materializer w trybie shadow + +- Generować targety obok obecnych buildów, bez instalacji użytkownika. +- Exit: semantic parity na inventory/manifest/references i deterministyczny rebuild; wszystkie rozbieżności sklasyfikowane. +- Rollback: wyłączyć shadow job; stare skrypty nadal publikują artifacts. + +### M3 — Transactional installer opt-in + +- Dodać `install --target`, staging, receipt, atomic swap, rollback oraz E4 dla czterech hostów. +- Exit: injected failures dowodzą byte-exact rollback; fresh/update/uninstall przechodzą offline na temp roots. +- Rollback: feature flag/legacy install path; receipt umożliwia odtworzenie poprzedniej wersji. + +### M4 — Jedno źródło dystrybucji + +- CI generuje prebuilt marketplace artifacts wyłącznie nowym materializerem; stare buildy pozostają comparison oracle przez jeden cykl release. +- Exit: dwa kolejne release bez nieobjaśnionego driftu i z odtworzeniem artifacts z tagu. +- Rollback: republish ostatni legacy artifact; nie usuwaj legacy builderów przed zakończeniem obserwacji. + +### M5 — Usunięcie commitowanych variants + +- Exit: release, offline rebuild, audit diff, receipts i per-host E1–E4 są stabilne; dostępne E5/E6 pozostają zielone lub jawnie unavailable. +- Rollback: odtworzyć warianty z release bundle/materializer; tag zachowuje dokładne adapter versions i hashes. + +## 10. Decyzje do późniejszej konwergencji + +1. **Zakres neutralnego modelu:** minimalne typed primitives + templates (rekomendowane) czy pełny IR/DSL od początku. +2. **Dystrybucja:** jeden source bundle + CI-prebuilt marketplace artifacts (rekomendowane) czy compiler zawsze uruchamiany na kliencie. +3. **Usunięcie generated trees:** po jednym czy dwóch stabilnych release; rekomendowane dwa cykle z parity oracle. +4. **Nieznana wersja hosta:** fail dla krytycznych capability mappings, warning dla packaging-only różnic (rekomendowane) czy global fail/warn. +5. **Claude assurance:** zaakceptować E4 jako release gate przy jawnym E5/E6 unavailable (rekomendowane) czy blokować release do uzyskania runtime. + +## Confidence + +- **High:** istnienie portable core, konieczność host-native outputów, wykonalność jednego bundle + target materialization, obecny evidence ceiling Claude. +- **Medium:** dokładny format descriptor/IR, ergonomia atomic swap across native marketplace flows, moment usunięcia generated trees. +- **Low/unknown:** realna pełna parity Claude Code, dopóki nie zostanie wykonany wersjonowany E5/E6. + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/dashboard-data.js b/.maister/tasks/research/2026-07-14-platform-independent-plugin/dashboard-data.js new file mode 100644 index 00000000..fa833338 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/dashboard-data.js @@ -0,0 +1,273 @@ +window.MAISTER_DATA = { + generated: "2026-07-14T16:25:57Z", + task: { + title: "Uproszczenie i uniezależnienie Maister od platformy", + type: "research", + status: "completed", + description: "Zbadać model jednego testowalnego rozwiązania z różnicami hostów materializowanymi podczas instalacji.", + path: ".maister/tasks/research/2026-07-14-platform-independent-plugin", + current_activity: null + }, + characteristics: { research_type: "mixed" }, + phases: [ + { id: "phase-1", name: "Research foundation", icon_hint: "analysis", status: "completed", started: "2026-07-14T13:25:50Z", completed: "2026-07-14T14:15:37Z", skip_reason: null, summary: "One neutral behavior/runtime core and one distribution bundle are feasible; typed, versioned host adapters should materialize distinct native trees at install time.", decisions: [ + { decision: "Typ badania: mixed — technical, requirements i literature research.", rationale: "Wymagane jest połączenie analizy kodu, kontraktów hostów i źródeł oficjalnych." }, + { decision: "Jednostką porównania będzie kontrakt zachowania, packagingu, instalacji i weryfikacji, a nie tylko układ plików wygenerowanych pluginów.", rationale: "Sam filesystem shape nie dowodzi parity semantycznej." }, + { decision: "Gathering Strategy ma trzy stabilne, niezależne kategorie, aby zmieścić analizę w dostępnym limicie agentów i umożliwić późniejsze łączenie ustaleń po identyfikatorach.", rationale: "Kategorie pokrywają core/transforms, host contracts/installation oraz assurance/runtime gap." }, + { decision: "Hipoteza „różnice dopiero przy instalacji” będzie oceniana obok co najmniej dwóch alternatyw, a nie traktowana jako z góry wybrana architektura.", rationale: "Rekomendacja musi wynikać z porównywalnych dowodów." } + ,{ decision: "Docelowo: portable behavior/runtime core + typed host contracts + install-time materializer.", rationale: "Maksymalizuje jednokrotne testowanie wspólnej semantyki i ogranicza adaptery do wymaganych kontraktów hostów." } + ,{ decision: "„Jedno rozwiązanie” oznacza jedno źródło, jeden testowalny core i jeden dystrybuowany bundle; nie oznacza jednego host runtime.", rationale: "Hosty wymagają różnych manifestów, discovery, agents, hooks i MCP placement." } + ,{ decision: "Neutralny IR rozwijać ewolucyjnie dla gates/roles/hooks/capabilities, zamiast budować pełny DSL przed migracją.", rationale: "Ogranicza koszt i ryzyko over-design." } + ,{ decision: "Instalacja musi używać staging, validation, receipt, atomic swap i byte-exact rollback.", rationale: "Materializacja na maszynie użytkownika musi być transakcyjna." } + ,{ decision: "Commitowane target trees usunąć dopiero po potwierdzonej parity i stabilnych release artifacts.", rationale: "Pozwala migrować shadow-first i zachować rollback." } + ,{ decision: "Continue to brainstorming evaluation", rationale: "User explicitly chose to continue after reviewing the completed research foundation and report." } + ], risks: [ + "Dokumentacja hostów może opisywać możliwości nowsze niż dostępne lokalnie CLI lub marketplace; wersje i daty muszą być zapisane przy dowodzie.", + "Brak runtime Claude Code uniemożliwia uczciwe potwierdzenie pełnego E2E; trzeba oddzielić dowód semantyczny, instalacyjny, statyczny i runtime.", + "Tekstowe transformacje mogą zawierać ukryte różnice semantyczne, których nie ujawni samo porównanie struktury katalogów.", + "Termin „jedno rozwiązanie” może oznaczać jedno źródło, jeden artefakt dystrybucyjny albo jeden runtime; synteza musi rozdzielić te poziomy." + ,"Semantyka gate/delegation/progress może dryfować mimo poprawnego layoutu; globalne substytucje tekstu są głównym źródłem ryzyka." + ,"Cursor i Kiro contracts są ruchome, a Kiro CLI/IDE wymagają osobnych, precyzyjnie nazwanych targetów." + ,"Compiler na maszynie użytkownika zwiększa koszt awarii, jeśli nie jest transakcyjny i odtwarzalny offline." + ,"Claude Code E5/E6 nie może być deklarowane bez realnej binarki, auth, wersji i wykonanego scenariusza." + ,"Native marketplaces mogą wymagać prebuilt artifacts; wspólny installer powinien z nimi współistnieć, nie koniecznie je zastępować." + ], artifacts: [ + { path: "planning/research-brief.md", label: "Research brief", html: null }, + { path: "planning/research-plan.md", label: "Research plan", html: null }, + { path: "planning/sources.md", label: "Source plan", html: null }, + { path: "analysis/findings/canonical-core-boundary.md", label: "Canonical core boundary findings", html: null }, + { path: "analysis/findings/host-contracts-installation.md", label: "Host contracts and installation findings", html: null }, + { path: "analysis/findings/test-assurance-runtime-gap.md", label: "Test assurance and runtime gap findings", html: null } + ,{ path: "analysis/synthesis.md", label: "Research synthesis", html: null } + ,{ path: "outputs/research-report.md", label: "Research report", html: "outputs/research-report.html" } + ,{ path: "outputs/decision-summary.md", label: "Decision summary", html: "outputs/decision-summary.html" } + ], gate: { question: "Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation?", answer: "Continue to brainstorming evaluation" } }, + { id: "phase-2", name: "Evaluate brainstorming value", icon_hint: "plan", status: "completed", started: "2026-07-14T14:15:37Z", completed: "2026-07-14T14:24:33Z", skip_reason: null, summary: "Brainstorming and high-level design are enabled because the solution has multiple viable variants and changes several architectural seams.", decisions: [{ decision: "Yes, explore alternatives", rationale: "User accepted the recommendation to explore alternatives." }, { decision: "Yes, generate design", rationale: "User accepted the recommendation to generate a high-level design after solution convergence." }], risks: [], artifacts: [], gate: { question: "Rekomendacja obejmuje nową granicę portable core/Host Contract/materializer, transakcyjną instalację, przebudowę CI oraz etapową migrację dystrybucji, więc high-level design jest wartościowy. Would you like to generate a high-level design?", answer: "Yes, generate design" } }, + { id: "phase-3", name: "Generate solution alternatives", icon_hint: "spec", status: "completed", started: "2026-07-14T14:24:33Z", completed: "2026-07-14T14:33:56Z", skip_reason: null, summary: "Five decision areas and fifteen alternatives are ready; the coherent recommendation is 1A + 2C + 3B + 4C + 5B.", decisions: [ + { decision: "Recommend minimal, evolutionary typed primitives plus host-aware templates instead of a full neutral IR at migration start.", rationale: "Ogranicza ryzyko over-design i pozwala migrować stopniowo." }, + { decision: "Recommend a hybrid distribution model in which local installation and CI-prebuilt marketplace artifacts invoke the same deterministic materializer and bundle.", rationale: "Łączy jeden compiler path z wymaganiami marketplace." }, + { decision: "Recommend removing committed generated trees only after two consecutive stable releases satisfy E1, E2, E4, installed-path E3 canary, reproducible artifact, rollback, and zero unresolved semantic-parity exceptions for every target.", rationale: "Zapewnia mierzalne, odwracalne exit criteria." }, + { decision: "Recommend capability-sensitive unknown-version handling: fail closed for semantic or safety-sensitive mappings, and allow packaging-only provisional compatibility after validation with explicit warning and expiring evidence.", rationale: "Unika zarówno nadmiernego blokowania, jak i ryzykownego best-effort." }, + { decision: "Recommend Claude Code releases use E1–E4 plus shared-core E3 as the enforceable gate, while E5/E6 remain explicitly unavailable until a versioned native probe runs.", rationale: "Utrzymuje uczciwy evidence ceiling bez blokowania całego projektu." }, + { decision: "Recommend the coherent architecture combination 1A + 2C + 3B + 4C + 5B.", rationale: "Wybrane rekomendacje wzajemnie się wspierają." } + ], risks: [ + "The boundary between a typed primitive and a host-aware template can drift and become another implicit transformation layer without an exception-review policy.", + "Marketplace packaging or signing constraints may require prebuilt artifacts, so local materialization cannot be the only supported distribution channel.", + "Textual parity does not prove semantic parity; the migration oracle must validate inventory, references, descriptors, semantic goldens, and installed-path canaries.", + "Two-release shadow operation temporarily increases CI and maintenance cost and needs a precise definition of a stable release.", + "Capability classification can be wrong; misclassifying a semantic mapping as packaging-only could permit unsafe provisional compatibility.", + "Claude Code E5/E6 remain unverified without a real binary, authentication, version, and executed scenario; unavailable evidence must never be shown as passing.", + "External host documentation and marketplaces can change faster than adapter evidence, so compatibility records need version, scenario, timestamp, and freshness policy." + ], artifacts: [{ path: "outputs/solution-exploration.md", label: "Solution exploration", html: "outputs/solution-exploration.html" }], gate: { question: "Continue to solution convergence?", answer: "Continue to solution convergence" } }, + { id: "phase-4", name: "Evaluate brainstorming alternatives", icon_hint: "plan", status: "completed", started: "2026-07-14T14:33:56Z", completed: "2026-07-14T15:38:33Z", skip_reason: null, summary: "Convergence completed with 1A + 2D + 3D + 4C + 5D: minimal primitives, custom installer, explicit host overlays, task-scoped shadow removal, capability-sensitive compatibility, and no Claude target.", decisions: [{ decision: "1A — minimalne typed primitives + host-aware templates", rationale: "Low-level tool selection normally remains with the host harness; explicit bindings cover control-flow, safety, persistence, and capability-sensitive operations." }, { decision: "Marketplace jest poza zakresem docelowego modelu instalacji.", rationale: "Instalacja ma działać z lokalnego lub GitHub repo przez własny installer pod pełną kontrolą projektu." }, { decision: "2D — custom installer + wspólne skille + jawne host overlays w repo", rationale: "Generic skills są kopiowane bez transformacji, a hooks, agents, commands, manifests i settings pozostają jawnie zdefiniowane per harness." }, { decision: "3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania", rationale: "User confirmed task-scoped shadow comparison with mandatory removal before implementation completion." }, { decision: "4C — capability-sensitive: semantic fail-closed, packaging provisional", rationale: "Semantic and safety-sensitive incompatibilities block installation; packaging-only differences may proceed provisionally after validation." }, { decision: "5D — usunąć Claude Code ze wspieranych targetów", rationale: "Future Claude support is a separate new-harness task driven by real need and available runtime." }], risks: ["Zbyt szerokie mapowanie nazw narzędzi stworzy kosztowną warstwę translacji; zbyt wąskie mapowanie może oddać harnessowi operacje wpływające na kontrolę przepływu i bezpieczeństwo.", "Jawne host overlays mogą dryfować, jeśli wspólne skille zaczną zawierać ukryte zależności od nazw narzędzi konkretnego harnessu.", "Usunięcie legacy oracle w tym samym zadaniu wymaga mocniejszej bramki parity, ponieważ nie będzie dwóch release obserwacji."], artifacts: [], gate: { question: "Brainstorming complete. Continue to high-level design?", answer: "Continue to high-level design" } }, + { id: "phase-5", name: "Design high-level architecture", icon_hint: "spec", status: "completed", started: "2026-07-14T15:38:33Z", completed: "2026-07-14T16:19:37Z", skip_reason: null, summary: "A repository-bundle modular monolith is designed with a portable documentation core, explicit Host Overlay Contracts, a transactional custom installer, and seven accepted ADRs.", decisions: [ + { decision: "Architektura: portable documentation core with explicit host overlays, nie pełny workflow DSL ani install-time compiler promptów.", rationale: "Minimalizuje semantyczną translację i utrzymuje generic skills jako jedno źródło." }, + { decision: "Harness sam wybiera zwykłe narzędzia wykonawcze; jawne bindings obejmują wyłącznie control flow, safety, persistence i capability-sensitive behavior.", rationale: "Unika mapowania implementacyjnych nazw narzędzi." }, + { decision: "Jedna kopia generic skills/runtime jest instalowana bez transformacji, a host-native assets są utrzymywane wprost w hosts/codex, hosts/cursor i hosts/kiro-cli.", rationale: "Różnice harnessów pozostają jawne i reviewowalne." }, + { decision: "Własny installer obsługuje lokalne repo i GitHub source, staging, validation, lock, receipt, atomic commit, update, uninstall i rollback.", rationale: "Instalacja pozostaje kontrolowana i transakcyjna." }, + { decision: "Nieznana wersja hosta blokuje niepotwierdzone capabilities semantyczne; packaging-only może otrzymać jawny status provisional.", rationale: "Fail-closed chroni semantykę bez sztucznego blokowania packagingu." }, + { decision: "Legacy build adapters, committed generated trees i Claude Code zostają usunięte w tym samym zadaniu po shadow comparison i spełnieniu Definition of Done.", rationale: "Tymczasowy oracle nie staje się drugą architekturą produkcyjną." } + ], risks: [ + "Docelowe ścieżki discovery i format settings każdego hosta trzeba potwierdzić aktualnymi testami contract/runtime przed implementacją overlayu.", + "Atomowa podmiana całego managed tree jest prosta; wieloplikowy merge do współdzielonych ustawień użytkownika wymaga journalu i byte-exact rollbacku.", + "Neutralna proza może z czasem zacząć przemycać słownik jednego hosta; potrzebny jest forbidden-vocabulary contract oraz review wyjątków.", + "Błędna klasyfikacja capability jako packaging zamiast semantic może przepuścić niezgodność; klasyfikacja musi być jawna i przeglądana.", + "Usunięcie legacy w jednym zadaniu zwiększa wagę końcowej bramki parity, szczególnie dla hooks, agents i invocation semantics." + ], artifacts: [{ path: "outputs/high-level-design.md", label: "High-level design", html: "outputs/high-level-design.html" }, { path: "outputs/decision-log.md", label: "Decision log", html: "outputs/decision-log.html" }], gate: { question: "Design complete. Continue to output generation?", answer: "Continue to output generation" } }, + { id: "phase-6", name: "Summarize research and suggest next steps", icon_hint: "done", status: "completed", started: "2026-07-14T16:19:37Z", completed: "2026-07-14T16:25:57Z", skip_reason: null, summary: "Research, convergence, and high-level design are complete; the user approved the final handoff.", decisions: [{ decision: "Complete workflow", rationale: "User explicitly approved the final research handoff and completion of the workflow." }], risks: ["Implementation should start in a fresh session using the high-level design and decision log as scope sources."], artifacts: [{ path: "outputs/research-report.md", label: "Research report", html: "outputs/research-report.html" }, { path: "outputs/solution-exploration.md", label: "Solution exploration", html: "outputs/solution-exploration.html" }, { path: "outputs/high-level-design.md", label: "High-level design", html: "outputs/high-level-design.html" }, { path: "outputs/decision-log.md", label: "Decision log", html: "outputs/decision-log.html" }, { path: "outputs/decision-summary.md", label: "Decision summary", html: "outputs/decision-summary.html" }], gate: { question: "Research workflow complete. Complete workflow?", answer: "Complete workflow" } } + ], + verification: { status: null, issues: [], fixes: [], reverify_count: 0 }, + gate_history: [{ + idempotency_key: "sha256:8dc80ac772693c815f0dfac96f7baa45a3cded3e406f16c6f5a42756f1e157d4", + phase_id: "phase-1", + gate_type: "phase-1-exit", + question: "Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation?", + options: ["Continue to brainstorming evaluation", "Pause workflow"], + original_recommendation: "Continue to brainstorming evaluation", + status: "decided", + selected_option: "Continue to brainstorming evaluation", + final_actor: "user", + rationale: "User explicitly chose to continue after reviewing the completed research foundation and report.", + confidence: "high" + }, { + idempotency_key: "sha256:aa3bd0f18b9311593067d380929d9f07dfe632faf4dd36a02904bf603026be24", + phase_id: "phase-2", + gate_type: "optional-phase-selection", + question: "Badanie wykazało cztery realne warianty oraz nierozstrzygnięte decyzje dotyczące IR, marketplace artifacts, momentu usunięcia generated trees i polityki nieznanych wersji hostów. Would you like to explore solution alternatives?", + options: ["Yes, explore alternatives", "No, skip brainstorming"], + original_recommendation: "Yes, explore alternatives", + status: "decided", + selected_option: "Yes, explore alternatives", + final_actor: "user", + rationale: "User accepted the recommendation to explore alternatives.", + confidence: "high" + }, { + idempotency_key: "sha256:65ca0aed2a12829399eaccb4883a2f0dd909b2b475c9172a924d5be41018fae3", + phase_id: "phase-2", + gate_type: "optional-phase-selection", + question: "Rekomendacja obejmuje nową granicę portable core/Host Contract/materializer, transakcyjną instalację, przebudowę CI oraz etapową migrację dystrybucji, więc high-level design jest wartościowy. Would you like to generate a high-level design?", + options: ["Yes, generate design", "No, skip design"], + original_recommendation: "Yes, generate design", + status: "decided", + selected_option: "Yes, generate design", + final_actor: "user", + rationale: "User accepted the recommendation to generate a high-level design after solution convergence.", + confidence: "high" + }, { + idempotency_key: "sha256:b44cce49b270e039db9825c224697b82b1f7ac236d4a1a361cd36e21a6e3cd13", + phase_id: "phase-3", + gate_type: "phase-3-exit", + question: "Continue to solution convergence?", + options: ["Continue to solution convergence", "Pause workflow"], + original_recommendation: "Continue to solution convergence", + status: "decided", + selected_option: "Continue to solution convergence", + final_actor: "user", + rationale: "User explicitly chose to continue from generated alternatives to sequential solution convergence.", + confidence: "high" + }, { + idempotency_key: "sha256:1c0159ead600b2c3ba1d2b1a28bee5b4dec632b0378564f1bb75386b3f380e6b", + phase_id: "phase-4", + gate_type: "research-convergence", + question: "Jak głęboka powinna być kanoniczna reprezentacja workflow Maister?", + options: ["1A — minimalne typed primitives + host-aware templates (Recommended)", "1B — pełny neutralny workflow IR od początku", "1C — canonical Markdown + ulepszone regex/golden snapshots", "Need more info"], + original_recommendation: "1A — minimalne typed primitives + host-aware templates (Recommended)", + status: "decided", + selected_option: "1A — minimalne typed primitives + host-aware templates (Recommended)", + final_actor: "user", + rationale: "User selected minimal typed primitives and clarified that low-level tool choice should normally remain with the host harness, while explicit bindings are reserved for control-flow, safety, persistence, or capability-sensitive operations.", + confidence: "high" + }, { + idempotency_key: "sha256:b9678e25714b36a77ab80c6b8e99dce1ae251775ffd0668e7f0d24736a65279c", + phase_id: "phase-4", + gate_type: "research-convergence", + question: "Gdzie powinien działać materializer i jak dystrybuować host-native artefakty?", + options: ["2A — lokalny materializer jako jedyna ścieżka", "2B — wyłącznie CI-prebuilt artifacts", "2C — hybryda: referencyjny lokalny materializer + prebuild z tego samego path (Recommended)", "Need more info"], + original_recommendation: "2C — hybryda: referencyjny lokalny materializer + prebuild z tego samego path (Recommended)", + status: "decided", + selected_option: "Need more info", + final_actor: "user", + rationale: "User rejected the marketplace-oriented framing and clarified that installation is from a local or GitHub repository through a fully controlled custom installer, with generic skills copied unchanged and host-specific assets explicit in the repository.", + confidence: "high" + }, { + idempotency_key: "sha256:153a61d692e97ae1ac47bef311677bf1c1f7e2eab3e0c23c703ce5087414a4bf", + phase_id: "phase-4", + gate_type: "research-convergence", + question: "Jaki model instalacji i przechowywania host-specific assets powinniśmy przyjąć po wykluczeniu marketplace?", + options: ["2D — custom installer + wspólne skille + jawne host overlays w repo (Recommended)", "2A — custom installer generuje host-specific assets podczas instalacji", "2B — kompletne prebuilt host trees przechowywane w repo", "Need more info"], + original_recommendation: "2D — custom installer + wspólne skille + jawne host overlays w repo (Recommended)", + status: "decided", + selected_option: "2D — custom installer + wspólne skille + jawne host overlays w repo (Recommended)", + final_actor: "user", + rationale: "User confirmed the repository-owned overlay model with a fully controlled custom installer, shared generic skills, and explicit harness-specific assets.", + confidence: "high" + }, { + idempotency_key: "sha256:d883bbce776c4f95ce19c8db040193ced1eafa5255bdbae75888d5515e32e785", + phase_id: "phase-4", + gate_type: "research-convergence", + question: "Kiedy i na jakich warunkach usunąć obecne commitowane generated trees?", + options: ["3A — natychmiastowe usunięcie po uruchomieniu nowego installera", "3B — shadow-first, dwa stabilne release i jawne exit criteria (Recommended)", "3C — pozostawić generated trees jako stale publikowane snapshots", "Need more info"], + original_recommendation: "3B — shadow-first, dwa stabilne release i jawne exit criteria (Recommended)", + status: "decided", + selected_option: "Need more info", + final_actor: "user", + rationale: "User refined the migration model: keep legacy generated trees only as a comparison oracle during implementation, then remove them before the implementation task is completed rather than waiting for two releases.", + confidence: "high" + }, { + idempotency_key: "sha256:9eef80c3b88f94ca365644236f7e7f5b860fb3086e4fa6018f4b1d6b3bfa81c2", + phase_id: "phase-4", + gate_type: "research-convergence", + question: "Jaką bramkę usunięcia legacy generated trees przyjąć dla zadania implementacyjnego?", + options: ["3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania (Recommended)", "3A — usunięcie legacy trees od razu po uruchomieniu installera", "3B — utrzymanie legacy trees przez dwa stabilne release", "Need more info"], + original_recommendation: "3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania (Recommended)", + status: "decided", + selected_option: "3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania (Recommended)", + final_actor: "user", + rationale: "User confirmed task-scoped shadow comparison with mandatory removal of legacy generated trees before implementation completion.", + confidence: "high" + }, { + idempotency_key: "sha256:87b6b2a02b6c2c1783c7192766cce253a77b31ca8518131c34293c4c9aaccd5b", + phase_id: "phase-4", + gate_type: "research-convergence", + question: "Jak custom installer powinien obsługiwać nieznaną lub niepotwierdzoną wersję harnessu?", + options: ["4A — zawsze fail-closed poza zadeklarowanym zakresem", "4B — zawsze warning i best-effort install", "4C — capability-sensitive: semantic fail-closed, packaging provisional (Recommended)", "Need more info"], + original_recommendation: "4C — capability-sensitive: semantic fail-closed, packaging provisional (Recommended)", + status: "decided", + selected_option: "4C — capability-sensitive: semantic fail-closed, packaging provisional (Recommended)", + final_actor: "user", + rationale: "User selected capability-sensitive compatibility with fail-closed semantic boundaries and provisional packaging-only compatibility.", + confidence: "high" + }, { + idempotency_key: "sha256:9d56a4cec456a5958dbefc581a6fe1ac046278c265f19685240d902cbf817948", + phase_id: "phase-4", + gate_type: "research-convergence", + question: "Jaką bramkę jakości przyjąć dla overlay i instalacji Claude Code bez dostępnego runtime?", + options: ["5A — blokować ukończenie zadania bez Claude E5/E6", "5B — wymagać E1–E4 + shared-core E3, a E5/E6 oznaczyć jako unavailable (Recommended)", "5C — community/canary certification przed stable promotion", "Need more info"], + original_recommendation: "5B — wymagać E1–E4 + shared-core E3, a E5/E6 oznaczyć jako unavailable (Recommended)", + status: "decided", + selected_option: "Need more info", + final_actor: "user", + rationale: "User rejected retaining an untestable Claude Code target and requested removing it until a real need and runtime exist.", + confidence: "high" + }, { + idempotency_key: "sha256:af63e4bae8d90431fe69ac253a4d766f0f4d06f92f0b0310a72f2fa59edfae1a", + phase_id: "phase-4", + gate_type: "research-convergence", + question: "Co zrobić z targetem Claude Code w docelowej architekturze?", + options: ["5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie (Recommended)", "5B — zachować Claude z E1–E4 i jawnym E5/E6 unavailable", "5A — zachować Claude i blokować ukończenie bez E5/E6", "Need more info"], + original_recommendation: "5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie (Recommended)", + status: "decided", + selected_option: "5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie (Recommended)", + final_actor: "user", + rationale: "User confirmed removal of Claude Code from supported targets; future support will be a separate new-harness task driven by real need and available runtime.", + confidence: "high" + }, { + idempotency_key: "sha256:deff7dc9407e4bf7bd8e9827eea83f0943d11d5daa1793b43db636eb584db001", + phase_id: "phase-4", + gate_type: "phase-4-exit", + question: "Brainstorming complete. Continue to high-level design?", + options: ["Continue to high-level design", "Pause workflow"], + original_recommendation: "Continue to high-level design", + status: "decided", + selected_option: "Continue to high-level design", + final_actor: "user", + rationale: "User explicitly chose to continue from completed solution convergence to high-level design.", + confidence: "high" + }, { + idempotency_key: "sha256:27838d495a10abcfeb14322b18149cd45829a1c61bda25c3992a388e58244645", + phase_id: "phase-5", + gate_type: "research-clarification", + question: "Założenia projektu: wspieramy Codex, Cursor i Kiro CLI; Claude Code i marketplace są poza zakresem; generic skills są kopiowane bez transformacji; jawne host overlays zawierają hooks, agents, commands, manifests i settings; custom installer składa i instaluje wynik transakcyjnie; legacy generated trees znikają przed zamknięciem zadania. Czy potwierdzasz te założenia?", + options: ["Confirm assumptions", "Correct assumptions", "Provide more context"], + original_recommendation: "Confirm assumptions", + status: "decided", + selected_option: "Confirm assumptions", + final_actor: "user", + rationale: "User confirmed the consolidated architecture assumptions without corrections.", + confidence: "high" + }, { + idempotency_key: "sha256:6bdf08499f5ea52adcb109887df08612b87fed5c1a2a6ba779d4fc70c9cb160e", + phase_id: "phase-5", + gate_type: "phase-5-exit", + question: "Design complete. Continue to output generation?", + options: ["Continue to output generation", "Pause workflow"], + original_recommendation: "Continue to output generation", + status: "decided", + selected_option: "Continue to output generation", + final_actor: "user", + rationale: "User explicitly chose to continue from the completed high-level design to final output generation.", + confidence: "high" + }, { + idempotency_key: "sha256:b35883e703798a8680ccae7ccae72418a71acd780faaa9c19d3a12a5723f17ce", + phase_id: "phase-6", + gate_type: "final-handoff-approval", + question: "Research workflow complete. Complete workflow?", + options: ["Complete workflow", "Keep workflow open"], + original_recommendation: "Complete workflow", + status: "decided", + selected_option: "Complete workflow", + final_actor: "user", + rationale: "User explicitly approved the final research handoff and completion of the workflow.", + confidence: "high" + }] +}; diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/dashboard.html b/.maister/tasks/research/2026-07-14-platform-independent-plugin/dashboard.html new file mode 100644 index 00000000..9f5ea812 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/dashboard.html @@ -0,0 +1,629 @@ + + + + + +Maister Workflow Dashboard + + + + +
+
+ Waiting for dashboard-data.js… If this persists, the workflow has not written data yet. +
+
+ + + + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/orchestrator-state.yml b/.maister/tasks/research/2026-07-14-platform-independent-plugin/orchestrator-state.yml new file mode 100644 index 00000000..21a22112 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/orchestrator-state.yml @@ -0,0 +1,856 @@ +orchestrator: + started_phase: phase-6 + completed_phases: [phase-1, phase-2, phase-3, phase-4, phase-5, phase-6] + failed_phases: [] + auto_fix_attempts: + phase-1: 0 + phase-2: 0 + phase-3: 0 + phase-4: 0 + phase-5: 0 + phase-6: 0 + options: + html_output: true + brainstorming_enabled: true + design_enabled: true + advisor: + enabled: true + gate_policies: + phase-exit: fully_automatic + optional-phase: fully_automatic + clarify: fully_automatic + convergence: fully_automatic + verify-matrix: fully_automatic + advisor_agent: advisor + advisor_model: gpt-5.6-sol + arbiter_agent: arbiter + arbiter_model: gpt-5.6-sol + arbiter_enabled_on_disagreement: true + retry: + advisor_attempts: 3 + arbiter_attempts: 3 + backoff: exponential + created: "2026-07-14T13:25:50Z" + updated: "2026-07-14T16:25:57Z" + task_path: .maister/tasks/research/2026-07-14-platform-independent-plugin + task_ids: + phase-1: research-phase-1 + phase-2: research-phase-2 + phase-3: research-phase-3 + phase-4: research-phase-4 + phase-5: research-phase-5 + phase-6: research-phase-6 + gate_history: + - schema_version: 1 + idempotency_key: sha256:8dc80ac772693c815f0dfac96f7baa45a3cded3e406f16c6f5a42756f1e157d4 + phase_id: phase-1 + gate_type: phase-1-exit + question: Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? + options: + - Continue to brainstorming evaluation + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to brainstorming evaluation + final_actor: user + original_recommendation: Continue to brainstorming evaluation + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly chose to continue after reviewing the completed research foundation and report. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b44cce49b270e039db9825c224697b82b1f7ac236d4a1a361cd36e21a6e3cd13 + phase_id: phase-3 + gate_type: phase-3-exit + question: Continue to solution convergence? + options: + - Continue to solution convergence + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to solution convergence + final_actor: user + original_recommendation: Continue to solution convergence + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly chose to continue from generated alternatives to sequential solution convergence. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:1c0159ead600b2c3ba1d2b1a28bee5b4dec632b0378564f1bb75386b3f380e6b + phase_id: phase-4 + gate_type: research-convergence + question: Jak głęboka powinna być kanoniczna reprezentacja workflow Maister? + options: + - 1A — minimalne typed primitives + host-aware templates (Recommended) + - 1B — pełny neutralny workflow IR od początku + - 1C — canonical Markdown + ulepszone regex/golden snapshots + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 1A — minimalne typed primitives + host-aware templates (Recommended) + final_actor: user + original_recommendation: 1A — minimalne typed primitives + host-aware templates (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected minimal typed primitives and clarified that low-level tool choice should normally remain with the host harness, while explicit bindings are reserved for control-flow, safety, persistence, or capability-sensitive operations. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b9678e25714b36a77ab80c6b8e99dce1ae251775ffd0668e7f0d24736a65279c + phase_id: phase-4 + gate_type: research-convergence + question: Gdzie powinien działać materializer i jak dystrybuować host-native artefakty? + options: + - 2A — lokalny materializer jako jedyna ścieżka + - 2B — wyłącznie CI-prebuilt artifacts + - "2C — hybryda: referencyjny lokalny materializer + prebuild z tego samego path (Recommended)" + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Need more info + final_actor: user + original_recommendation: "2C — hybryda: referencyjny lokalny materializer + prebuild z tego samego path (Recommended)" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User rejected the marketplace-oriented framing and clarified that installation is from a local or GitHub repository through a fully controlled custom installer, with generic skills copied unchanged and host-specific assets explicit in the repository. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:153a61d692e97ae1ac47bef311677bf1c1f7e2eab3e0c23c703ce5087414a4bf + phase_id: phase-4 + gate_type: research-convergence + question: Jaki model instalacji i przechowywania host-specific assets powinniśmy przyjąć po wykluczeniu marketplace? + options: + - 2D — custom installer + wspólne skille + jawne host overlays w repo (Recommended) + - 2A — custom installer generuje host-specific assets podczas instalacji + - 2B — kompletne prebuilt host trees przechowywane w repo + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 2D — custom installer + wspólne skille + jawne host overlays w repo (Recommended) + final_actor: user + original_recommendation: 2D — custom installer + wspólne skille + jawne host overlays w repo (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed the repository-owned overlay model with a fully controlled custom installer, shared generic skills, and explicit harness-specific assets. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:d883bbce776c4f95ce19c8db040193ced1eafa5255bdbae75888d5515e32e785 + phase_id: phase-4 + gate_type: research-convergence + question: Kiedy i na jakich warunkach usunąć obecne commitowane generated trees? + options: + - 3A — natychmiastowe usunięcie po uruchomieniu nowego installera + - 3B — shadow-first, dwa stabilne release i jawne exit criteria (Recommended) + - 3C — pozostawić generated trees jako stale publikowane snapshots + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Need more info + final_actor: user + original_recommendation: 3B — shadow-first, dwa stabilne release i jawne exit criteria (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: "User refined the migration model: keep legacy generated trees only as a comparison oracle during implementation, then remove them before the implementation task is completed rather than waiting for two releases." + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:9eef80c3b88f94ca365644236f7e7f5b860fb3086e4fa6018f4b1d6b3bfa81c2 + phase_id: phase-4 + gate_type: research-convergence + question: Jaką bramkę usunięcia legacy generated trees przyjąć dla zadania implementacyjnego? + options: + - 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania (Recommended) + - 3A — usunięcie legacy trees od razu po uruchomieniu installera + - 3B — utrzymanie legacy trees przez dwa stabilne release + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania (Recommended) + final_actor: user + original_recommendation: 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed task-scoped shadow comparison with mandatory removal of legacy generated trees before implementation completion. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:87b6b2a02b6c2c1783c7192766cce253a77b31ca8518131c34293c4c9aaccd5b + phase_id: phase-4 + gate_type: research-convergence + question: Jak custom installer powinien obsługiwać nieznaną lub niepotwierdzoną wersję harnessu? + options: + - 4A — zawsze fail-closed poza zadeklarowanym zakresem + - 4B — zawsze warning i best-effort install + - "4C — capability-sensitive: semantic fail-closed, packaging provisional (Recommended)" + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: "4C — capability-sensitive: semantic fail-closed, packaging provisional (Recommended)" + final_actor: user + original_recommendation: "4C — capability-sensitive: semantic fail-closed, packaging provisional (Recommended)" + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User selected capability-sensitive compatibility with fail-closed semantic boundaries and provisional packaging-only compatibility. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:9d56a4cec456a5958dbefc581a6fe1ac046278c265f19685240d902cbf817948 + phase_id: phase-4 + gate_type: research-convergence + question: Jaką bramkę jakości przyjąć dla overlay i instalacji Claude Code bez dostępnego runtime? + options: + - 5A — blokować ukończenie zadania bez Claude E5/E6 + - 5B — wymagać E1–E4 + shared-core E3, a E5/E6 oznaczyć jako unavailable (Recommended) + - 5C — community/canary certification przed stable promotion + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Need more info + final_actor: user + original_recommendation: 5B — wymagać E1–E4 + shared-core E3, a E5/E6 oznaczyć jako unavailable (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User rejected retaining an untestable Claude Code target and requested removing it until a real need and runtime exist. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:af63e4bae8d90431fe69ac253a4d766f0f4d06f92f0b0310a72f2fa59edfae1a + phase_id: phase-4 + gate_type: research-convergence + question: Co zrobić z targetem Claude Code w docelowej architekturze? + options: + - 5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie (Recommended) + - 5B — zachować Claude z E1–E4 i jawnym E5/E6 unavailable + - 5A — zachować Claude i blokować ukończenie bez E5/E6 + - Need more info + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: 5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie (Recommended) + final_actor: user + original_recommendation: 5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie (Recommended) + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed removal of Claude Code from supported targets; future support will be a separate new-harness task driven by real need and available runtime. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:deff7dc9407e4bf7bd8e9827eea83f0943d11d5daa1793b43db636eb584db001 + phase_id: phase-4 + gate_type: phase-4-exit + question: Brainstorming complete. Continue to high-level design? + options: + - Continue to high-level design + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to high-level design + final_actor: user + original_recommendation: Continue to high-level design + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly chose to continue from completed solution convergence to high-level design. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:27838d495a10abcfeb14322b18149cd45829a1c61bda25c3992a388e58244645 + phase_id: phase-5 + gate_type: research-clarification + question: "Założenia projektu: wspieramy Codex, Cursor i Kiro CLI; Claude Code i marketplace są poza zakresem; generic skills są kopiowane bez transformacji; jawne host overlays zawierają hooks, agents, commands, manifests i settings; custom installer składa i instaluje wynik transakcyjnie; legacy generated trees znikają przed zamknięciem zadania. Czy potwierdzasz te założenia?" + options: + - Confirm assumptions + - Correct assumptions + - Provide more context + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Confirm assumptions + final_actor: user + original_recommendation: Confirm assumptions + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User confirmed the consolidated architecture assumptions without corrections. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:6bdf08499f5ea52adcb109887df08612b87fed5c1a2a6ba779d4fc70c9cb160e + phase_id: phase-5 + gate_type: phase-5-exit + question: Design complete. Continue to output generation? + options: + - Continue to output generation + - Pause workflow + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Continue to output generation + final_actor: user + original_recommendation: Continue to output generation + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly chose to continue from the completed high-level design to final output generation. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:b35883e703798a8680ccae7ccae72418a71acd780faaa9c19d3a12a5723f17ce + phase_id: phase-6 + gate_type: final-handoff-approval + question: Research workflow complete. Complete workflow? + options: + - Complete workflow + - Keep workflow open + policy: manual + safety_classification: denylisted + status: decided + selected_option: Complete workflow + final_actor: user + original_recommendation: Complete workflow + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User explicitly approved the final research handoff and completion of the workflow. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:aa3bd0f18b9311593067d380929d9f07dfe632faf4dd36a02904bf603026be24 + phase_id: phase-2 + gate_type: optional-phase-selection + question: Badanie wykazało cztery realne warianty oraz nierozstrzygnięte decyzje dotyczące IR, marketplace artifacts, momentu usunięcia generated trees i polityki nieznanych wersji hostów. Would you like to explore solution alternatives? + options: + - Yes, explore alternatives + - No, skip brainstorming + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, explore alternatives + final_actor: user + original_recommendation: Yes, explore alternatives + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User accepted the recommendation to explore alternatives. + confidence: high + escalate_to_user: false + user_override: false + error: null + - schema_version: 1 + idempotency_key: sha256:65ca0aed2a12829399eaccb4883a2f0dd909b2b475c9172a924d5be41018fae3 + phase_id: phase-2 + gate_type: optional-phase-selection + question: Rekomendacja obejmuje nową granicę portable core/Host Contract/materializer, transakcyjną instalację, przebudowę CI oraz etapową migrację dystrybucji, więc high-level design jest wartościowy. Would you like to generate a high-level design? + options: + - Yes, generate design + - No, skip design + policy: fully_automatic + safety_classification: configurable + status: decided + selected_option: Yes, generate design + final_actor: user + original_recommendation: Yes, generate design + advisor: + agent: advisor + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + arbiter: + agent: arbiter + model: gpt-5.6-sol + response: null + attempts: [] + exhausted: false + rationale: User accepted the recommendation to generate a high-level design after solution convergence. + confidence: high + escalate_to_user: false + user_override: false + error: null + implementation_approval: + status: not_required + approved_by: null + approved_at: null + approved_scope: [] + +task: + title: Uproszczenie i uniezależnienie Maister od platformy + description: Przeanalizować, jak zastąpić generowanie i osobne testowanie wariantów dla wielu hostów jednym rozwiązaniem niezależnym od narzędzia, z rozróżnieniem platformy możliwym na etapie instalacji. + status: completed + tags: [research, architecture, portability, installation, testing] + priority: high + +phases: + - id: phase-1 + name: Research foundation + status: completed + blocked_by: [] + started: "2026-07-14T13:25:50Z" + completed: "2026-07-14T14:15:37Z" + gate: + question: Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? + answer: Continue to brainstorming evaluation + - id: phase-2 + name: Evaluate brainstorming value + status: completed + blocked_by: [phase-1] + started: "2026-07-14T14:15:37Z" + completed: "2026-07-14T14:24:33Z" + gate: + question: Rekomendacja obejmuje nową granicę portable core/Host Contract/materializer, transakcyjną instalację, przebudowę CI oraz etapową migrację dystrybucji, więc high-level design jest wartościowy. Would you like to generate a high-level design? + answer: Yes, generate design + - id: phase-3 + name: Generate solution alternatives + status: completed + blocked_by: [phase-2] + started: "2026-07-14T14:24:33Z" + completed: "2026-07-14T14:33:56Z" + gate: + question: Continue to solution convergence? + answer: Continue to solution convergence + - id: phase-4 + name: Evaluate brainstorming alternatives + status: completed + blocked_by: [phase-3] + started: "2026-07-14T14:33:56Z" + completed: "2026-07-14T15:38:33Z" + gate: + question: Brainstorming complete. Continue to high-level design? + answer: Continue to high-level design + - id: phase-5 + name: Design high-level architecture + status: completed + blocked_by: [phase-4] + started: "2026-07-14T15:38:33Z" + completed: "2026-07-14T16:19:37Z" + gate: + question: Design complete. Continue to output generation? + answer: Continue to output generation + - id: phase-6 + name: Summarize research and suggest next steps + status: completed + blocked_by: [phase-5] + started: "2026-07-14T16:19:37Z" + completed: "2026-07-14T16:25:57Z" + gate: + question: Research workflow complete. Complete workflow? + answer: Complete workflow + +research_context: + research_type: mixed + research_question: W jaki sposób uprościć Maister i uniezależnić go od platform AI coding hostów, tak aby utrzymywać jedno testowalne rozwiązanie, a ewentualne różnice wybierać dopiero podczas instalacji — również dla Claude Code, gdzie nie mamy dostępnego runtime do testów? + scope: + included: + - Kanoniczne źródła pluginu, adaptery platformowe i generowane warianty + - Różnice kontraktów Claude Code, Codex, Cursor i Kiro + - Instalacja, manifesty, discovery skills/agents/commands i host-native runtime + - Obecny build, test matrix, walidacja oraz luki testowe Claude Code + - Możliwe architektury jednego artefaktu lub instalacyjnej materializacji targetu + - Ścieżka migracji ograniczająca duplikację i ryzyko regresji + excluded: + - Implementacja wybranego rozwiązania w tym workflow + - Zmiana funkcjonalnego zakresu workflow Maister niezwiązana z przenośnością + - Deklarowanie pełnej zgodności bez dowodów kontraktowych lub runtime + - Utrzymywanie Claude Code jako wspieranego targetu w docelowej architekturze; może zostać dodany później jako nowy harness + constraints: + - Zachować natywne wymagania każdego hosta i jego mechanizm instalacji + - Zachować audytowalność, resumability i bezpieczeństwo bramek + - Nie opierać gwarancji Claude Code na runtime, którego projekt nie może uruchomić + - Preferować jeden kanoniczny model zachowania i deterministyczne granice platformowe + methodology: + - Mixed technical, requirements, and literature research + - Layer decomposition across behavior, portable runtime, host contract, packaging, installation, and assurance + - Multi-source triangulation with evidence levels E0-E6 + - Comparative scorecard across current build-time generation, install-time materialization, shared core with thin adapters, and optional neutral IR + sources: + - planning/sources.md + - Canonical plugin sources and shared runtime helpers + - Platform adapters, installers, generated target shapes, and host-owned official documentation + - Make, CI, contract/install/smoke/E2E tests, and host capability matrix + confidence_level: high + gathering_strategy: + categories: + - canonical-core-transform-boundary + - host-contracts-installation + - test-assurance-runtime-gap + count: 3 + source: planner + project_doc_paths: + - .maister/docs/project/vision.md + - .maister/docs/project/roadmap.md + - .maister/docs/project/tech-stack.md + - .maister/docs/project/architecture.md + phase_summaries: + phase-1: + summary: Jeden neutralny behavior/runtime core i jeden bundle są wykonalne; host-native drzewa pozostają różne i powinny być materializowane przez typowane, wersjonowane adaptery podczas instalacji. Kierunek ma wysoką pewność, natomiast dokładny descriptor/IR i integracja marketplace wymagają dalszej konwergencji. + steps_completed: [initialize, plan, gather, synthesize] + decisions: + - decision: "Typ badania: mixed — technical, requirements i literature research." + rationale: Wymagane jest połączenie analizy kodu, kontraktów hostów i źródeł oficjalnych. + - decision: Jednostką porównania będzie kontrakt zachowania, packagingu, instalacji i weryfikacji, a nie tylko układ plików wygenerowanych pluginów. + rationale: Sam filesystem shape nie dowodzi parity semantycznej. + - decision: Gathering Strategy ma trzy stabilne, niezależne kategorie, aby zmieścić analizę w dostępnym limicie agentów i umożliwić późniejsze łączenie ustaleń po identyfikatorach. + rationale: Kategorie pokrywają core/transforms, host contracts/installation oraz assurance/runtime gap. + - decision: Hipoteza „różnice dopiero przy instalacji” będzie oceniana obok co najmniej dwóch alternatyw, a nie traktowana jako z góry wybrana architektura. + rationale: Rekomendacja musi wynikać z porównywalnych dowodów. + - decision: "Docelowo: portable behavior/runtime core + typed host contracts + install-time materializer." + rationale: Maksymalizuje jednokrotne testowanie wspólnej semantyki i ogranicza adaptery do wymaganych kontraktów hostów. + - decision: „Jedno rozwiązanie” oznacza jedno źródło, jeden testowalny core i jeden dystrybuowany bundle; nie oznacza jednego host runtime. + rationale: Hosty wymagają różnych manifestów, discovery, agents, hooks i MCP placement. + - decision: Neutralny IR rozwijać ewolucyjnie dla gates/roles/hooks/capabilities, zamiast budować pełny DSL przed migracją. + rationale: Ogranicza koszt i ryzyko over-design. + - decision: Instalacja musi używać staging, validation, receipt, atomic swap i byte-exact rollback. + rationale: Materializacja na maszynie użytkownika musi być transakcyjna. + - decision: Commitowane target trees usunąć dopiero po potwierdzonej parity i stabilnych release artifacts. + rationale: Pozwala migrować shadow-first i zachować rollback. + - decision: Continue to brainstorming evaluation + rationale: User explicitly chose to continue after reviewing the completed research foundation and report. + risks: + - Dokumentacja hostów może opisywać możliwości nowsze niż dostępne lokalnie CLI lub marketplace; wersje i daty muszą być zapisane przy dowodzie. + - Brak runtime Claude Code uniemożliwia uczciwe potwierdzenie pełnego E2E; trzeba oddzielić dowód semantyczny, instalacyjny, statyczny i runtime. + - Tekstowe transformacje mogą zawierać ukryte różnice semantyczne, których nie ujawni samo porównanie struktury katalogów. + - Termin „jedno rozwiązanie” może oznaczać jedno źródło, jeden artefakt dystrybucyjny albo jeden runtime; synteza musi rozdzielić te poziomy. + - Semantyka gate/delegation/progress może dryfować mimo poprawnego layoutu; globalne substytucje tekstu są głównym źródłem ryzyka. + - Cursor i Kiro contracts są ruchome, a Kiro CLI/IDE wymagają osobnych, precyzyjnie nazwanych targetów. + - Compiler na maszynie użytkownika zwiększa koszt awarii, jeśli nie jest transakcyjny i odtwarzalny offline. + - Claude Code E5/E6 nie może być deklarowane bez realnej binarki, auth, wersji i wykonanego scenariusza. + - Native marketplaces mogą wymagać prebuilt artifacts; wspólny installer powinien z nimi współistnieć, nie koniecznie je zastępować. + artifacts: + - path: planning/research-brief.md + label: Research brief + html: null + - path: planning/research-plan.md + label: Research plan + html: null + - path: planning/sources.md + label: Source plan + html: null + - path: analysis/findings/canonical-core-boundary.md + label: Canonical core boundary findings + html: null + - path: analysis/findings/host-contracts-installation.md + label: Host contracts and installation findings + html: null + - path: analysis/findings/test-assurance-runtime-gap.md + label: Test assurance and runtime gap findings + html: null + - path: analysis/synthesis.md + label: Research synthesis + html: null + - path: outputs/research-report.md + label: Research report + html: outputs/research-report.html + - path: outputs/decision-summary.md + label: Decision summary + html: outputs/decision-summary.html + phase-3: + summary: Wygenerowano pięć obszarów decyzyjnych i piętnaście znacząco różnych alternatyw. Spójna rekomendacja to minimalne typed primitives, hybrydowa materializacja, shadow-first migration, capability-sensitive compatibility oraz jawny Claude evidence ceiling. + decisions: + - decision: Recommend minimal, evolutionary typed primitives plus host-aware templates instead of a full neutral IR at migration start. + rationale: Ogranicza ryzyko over-design i pozwala migrować stopniowo. + - decision: Recommend a hybrid distribution model in which local installation and CI-prebuilt marketplace artifacts invoke the same deterministic materializer and bundle. + rationale: Łączy jeden compiler path z wymaganiami marketplace. + - decision: Recommend removing committed generated trees only after two consecutive stable releases satisfy E1, E2, E4, installed-path E3 canary, reproducible artifact, rollback, and zero unresolved semantic-parity exceptions for every target. + rationale: Zapewnia mierzalne, odwracalne exit criteria. + - decision: "Recommend capability-sensitive unknown-version handling: fail closed for semantic or safety-sensitive mappings, and allow packaging-only provisional compatibility after validation with explicit warning and expiring evidence." + rationale: Unika zarówno nadmiernego blokowania, jak i ryzykownego best-effort. + - decision: Recommend Claude Code releases use E1–E4 plus shared-core E3 as the enforceable gate, while E5/E6 remain explicitly unavailable until a versioned native probe runs. + rationale: Utrzymuje uczciwy evidence ceiling bez blokowania całego projektu. + - decision: Recommend the coherent architecture combination 1A + 2C + 3B + 4C + 5B. + rationale: Wybrane rekomendacje wzajemnie się wspierają. + risks: + - The boundary between a typed primitive and a host-aware template can drift and become another implicit transformation layer without an exception-review policy. + - Marketplace packaging or signing constraints may require prebuilt artifacts, so local materialization cannot be the only supported distribution channel. + - Textual parity does not prove semantic parity; the migration oracle must validate inventory, references, descriptors, semantic goldens, and installed-path canaries. + - Two-release shadow operation temporarily increases CI and maintenance cost and needs a precise definition of a stable release. + - Capability classification can be wrong; misclassifying a semantic mapping as packaging-only could permit unsafe provisional compatibility. + - Claude Code E5/E6 remain unverified without a real binary, authentication, version, and executed scenario; unavailable evidence must never be shown as passing. + - External host documentation and marketplaces can change faster than adapter evidence, so compatibility records need version, scenario, timestamp, and freshness policy. + artifacts: + - path: outputs/solution-exploration.md + label: Solution exploration + html: outputs/solution-exploration.html + phase-4: + summary: "Konwergencja zakończona zestawem 1A + 2D + 3D + 4C + 5D: neutralne minimalne primitives, custom installer, jawne host overlays, task-scoped shadow removal, capability-sensitive compatibility i usunięcie Claude Code." + decisions: + - decision: 1A — minimalne typed primitives + host-aware templates + rationale: Low-level tool selection normally remains with the host harness; explicit bindings cover control-flow, safety, persistence, and capability-sensitive operations. + - decision: Marketplace jest poza zakresem docelowego modelu instalacji. + rationale: Instalacja ma działać z lokalnego lub GitHub repo przez własny installer pod pełną kontrolą projektu. + - decision: 2D — custom installer + wspólne skille + jawne host overlays w repo + rationale: Generic skills są kopiowane bez transformacji, a hooks, agents, commands, manifests i settings pozostają jawnie zdefiniowane per harness. + - decision: Okres shadow nie powinien wykraczać poza zadanie implementacyjne. + rationale: Legacy trees służą do porównania podczas implementacji, ale muszą zniknąć przed Definition of Done. + - decision: 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania + rationale: User confirmed task-scoped shadow comparison with mandatory removal before implementation completion. + - decision: "4C — capability-sensitive: semantic fail-closed, packaging provisional" + rationale: Semantic and safety-sensitive incompatibilities block installation; packaging-only differences may proceed provisionally after validation. + - decision: Claude Code nie powinien pozostać wspieranym targetem bez możliwości testowania i realnej potrzeby. + rationale: Target można później dodać przez ten sam kontrakt host overlay, gdy pojawi się runtime i uzasadniony use case. + - decision: 5D — usunąć Claude Code ze wspieranych targetów + rationale: Future Claude support is a separate new-harness task driven by real need and available runtime. + risks: + - Zbyt szerokie mapowanie nazw narzędzi stworzy kosztowną warstwę translacji; zbyt wąskie mapowanie może oddać harnessowi operacje wpływające na kontrolę przepływu i bezpieczeństwo. + - Jawne host overlays mogą dryfować, jeśli wspólne skille zaczną zawierać ukryte zależności od nazw narzędzi konkretnego harnessu. + - Usunięcie legacy oracle w tym samym zadaniu wymaga mocniejszej bramki parity, ponieważ nie będzie dwóch release obserwacji. + artifacts: [] + decision_areas: + - area: Głębokość reprezentacji kanonicznej / IR + alternatives_count: 3 + chosen_approach: 1A — minimalne typed primitives + host-aware templates + - area: Dystrybucja i miejsce materializacji + alternatives_count: 3 + chosen_approach: 2D — custom installer + wspólne skille + jawne host overlays w repo + - area: Przejście i kryteria usunięcia generated trees + alternatives_count: 3 + chosen_approach: 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania + - area: Polityka nieznanych wersji harnessu + alternatives_count: 3 + chosen_approach: "4C — capability-sensitive: semantic fail-closed, packaging provisional" + - area: Claude Code assurance bez runtime + alternatives_count: 3 + chosen_approach: 5D — usunąć Claude Code ze wspieranych targetów i dodać ponownie dopiero przy realnej potrzebie + deferred_ideas: + - Pełny neutralny workflow IR, jeśli minimalne primitives przestaną wystarczać. + - Ponowne dodanie Claude Code jako nowego harnessu po pojawieniu się realnej potrzeby, runtime i testów E5/E6. + - Integracje marketplace pozostają poza zakresem; instalacja odbywa się z lokalnego lub GitHub repo. + phase-5: + summary: "Zaprojektowano modularny monolit dystrybuowany jako repozytoryjny bundle: portable documentation core, jawne Host Overlay Contracts dla Codex/Cursor/Kiro CLI oraz transakcyjny custom installer. Decision log zawiera siedem zaakceptowanych ADR-ów." + decisions: + - decision: "Architektura: portable documentation core with explicit host overlays, nie pełny workflow DSL ani install-time compiler promptów." + rationale: Minimalizuje semantyczną translację i utrzymuje generic skills jako jedno źródło. + - decision: Harness sam wybiera zwykłe narzędzia wykonawcze; jawne bindings obejmują wyłącznie control flow, safety, persistence i capability-sensitive behavior. + rationale: Unika mapowania implementacyjnych nazw narzędzi. + - decision: Jedna kopia generic skills/runtime jest instalowana bez transformacji, a host-native assets są utrzymywane wprost w hosts/codex, hosts/cursor i hosts/kiro-cli. + rationale: Różnice harnessów pozostają jawne i reviewowalne. + - decision: Własny installer obsługuje lokalne repo i GitHub source, staging, validation, lock, receipt, atomic commit, update, uninstall i rollback. + rationale: Instalacja pozostaje kontrolowana i transakcyjna. + - decision: Nieznana wersja hosta blokuje niepotwierdzone capabilities semantyczne; packaging-only może otrzymać jawny status provisional. + rationale: Fail-closed chroni semantykę bez sztucznego blokowania packagingu. + - decision: Legacy build adapters, committed generated trees i Claude Code zostają usunięte w tym samym zadaniu po shadow comparison i spełnieniu Definition of Done. + rationale: Tymczasowy oracle nie staje się drugą architekturą produkcyjną. + risks: + - Docelowe ścieżki discovery i format settings każdego hosta trzeba potwierdzić aktualnymi testami contract/runtime przed implementacją overlayu. + - Atomowa podmiana całego managed tree jest prosta; wieloplikowy merge do współdzielonych ustawień użytkownika wymaga journalu i byte-exact rollbacku. + - Neutralna proza może z czasem zacząć przemycać słownik jednego hosta; potrzebny jest forbidden-vocabulary contract oraz review wyjątków. + - Błędna klasyfikacja capability jako packaging zamiast semantic może przepuścić niezgodność; klasyfikacja musi być jawna i przeglądana. + - Usunięcie legacy w jednym zadaniu zwiększa wagę końcowej bramki parity, szczególnie dla hooks, agents i invocation semantics. + artifacts: + - path: outputs/high-level-design.md + label: High-level design + html: outputs/high-level-design.html + - path: outputs/decision-log.md + label: Decision log + html: outputs/decision-log.html + architecture_style: modular monolith distributed as a repository bundle with portable documentation core, declarative Host Overlay Contracts, and a transactional installer adapter + decisions_count: 7 + phase-6: + summary: Zakończono research, konwergencję i high-level design. Finalny kierunek to neutralny portable core, jawne overlays Codex/Cursor/Kiro CLI, transakcyjny custom installer, task-scoped removal legacy, capability-sensitive compatibility oraz usunięcie Claude Code. + decisions: + - decision: Complete workflow + rationale: User explicitly approved the final research handoff and completion of the workflow. + risks: + - Implementacja powinna rozpocząć się w świeżej sesji i traktować high-level design oraz decision log jako źródło zakresu. + artifacts: + - path: outputs/research-report.md + label: Research report + html: outputs/research-report.html + - path: outputs/solution-exploration.md + label: Solution exploration + html: outputs/solution-exploration.html + - path: outputs/high-level-design.md + label: High-level design + html: outputs/high-level-design.html + - path: outputs/decision-log.md + label: Decision log + html: outputs/decision-log.html + - path: outputs/decision-summary.md + label: Decision summary + html: outputs/decision-summary.html diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-log.html b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-log.html new file mode 100644 index 00000000..7c3a910f --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-log.html @@ -0,0 +1,181 @@ + + + + +Decision log — platformowo niezależny Maister + + + + +
MADR Decision Log

Platformowo niezależny Maister

Accepted architectural decisions from convergence 1A / 2D / 3D / 4C / 5D

+
+
7ADR
+
7accepted
+
0proposed
+
0superseded
+
5user choices
+
+ +
+

TL;DR

+

Przyjęto portable core, trzy jawne host overlays i własny transakcyjny installer. Harness wybiera ordinary tools; formalne bindings obejmują tylko semantic invariants. Legacy generated trees i Claude Code znikają przed zakończeniem zadania. Core E3 działa raz, a host evidence pozostaje per capability i scenario.

+

Key Decisions

+
    +
  • ADR-001 — minimalne semantic primitives, bez workflow DSL.
    • +
  • ADR-002 — common + repo-owned overlays + copy/merge installer.
    • +
  • ADR-003 — shadow tylko podczas implementacji, potem deletion.
    • +
  • ADR-004 — semantic fail-closed, packaging provisional.
    • +
  • ADR-005 — remove Claude Code, future return as new host task.
    • +
  • ADR-006 — managed ownership, journal, receipt, byte-exact rollback.
    • +
  • ADR-007 — core once; E1/E2/E4 and available E5/E6 per host.
    • +
+

Open Questions / Risks

+
    +
  • Aktualne Codex/Cursor/Kiro contracts trzeba potwierdzić podczas implementacji.
    • +
  • Primitive registry może puchnąć bez rygoru promotion rule.
    • +
  • Shared settings transaction zależy od journalu i recovery tests.
    • +
  • Task-scoped removal wymaga mocnej parity bramki.
    • +
  • Native E5/E6 może być unavailable; brak dowodu nie jest sukcesem.
    • +
+
+ + + +
+
+ Accepted

ADR-001 — Minimalne semantic primitives zamiast pełnego IR

+
2026-07-14Convergence: 1AUser-confirmed
+

Context

Setki tekstowych transformacji wiążą canonical source z host vocabulary. Pełny AST/DSL byłby spekulatywny, a documentation-as-code pozostaje wartościowe.

Drivers

  • jedna kopia skills
  • brak regex rewrite
  • harness autonomy
  • formal safety/control-flow boundaries

Options

  1. 1A minimal primitives
  2. pełny IR/DSL
  3. Markdown + regex/golden

Outcome

Intencje ordinary operations są neutralne; rg, grep, Explore/read pozostają wyborem harnessu. Explicit bindings obejmują gates, required delegation, safety hooks, persistence i continuation.

+
Consequences
  • Nie powstaje prompt compiler.
  • Potrzebny mały primitive registry i completeness contract.
  • Forbidden vocabulary test chroni generic layer.
  • Nowy primitive wymaga repeated semantic divergence albo safety invariant.
+
+ +
+ Accepted

ADR-002 — Repo-owned host overlays i custom installer

+
2026-07-14Convergence: 2DMarketplace excluded
+

Context

Instalacja odbywa się z local/GitHub repo. Generic skills są wspólne, lecz agents, commands, hooks, manifests i settings są natywne. Runtime generation przeniosłoby złożoność adapterów do użytkownika.

Drivers

  • jawny review różnic
  • deterministyczna instalacja
  • jeden common source
  • brak marketplace

Options

  1. 2D common + overlays + installer
  2. runtime generation
  3. pełne duplicated prebuilt trees
  4. marketplace hybrid

Outcome

common/ plus hosts/codex|cursor|kiro-cli. Installer kopiuje common byte-for-byte, dokłada native overlay, waliduje i transakcyjnie instaluje. GitHub ref zostaje zapisany jako commit SHA.

+
Consequences
  • Host diffs są jawne.
  • Overlay schema/tests są obowiązkowe.
  • Mała świadoma duplikacja formatów jest akceptowalna.
  • Installer jest assemblerem, nie workflow compilerem.
+
+ +
+ Accepted

ADR-003 — Legacy tylko jako migration oracle

+
2026-07-14Convergence: 3DDeletion before DoD
+

Context

Generated trees pomagają porównać inventory, permissions, hooks i references, ale są źródłem duplikacji. Dual path nie może przetrwać zadania.

Drivers

  • parity evidence
  • finalny brak generated trees
  • jednoznaczne DoD

Options

  1. natychmiastowe deletion
  2. dwa stabilne releases
  3. stałe snapshots
  4. 3D shadow then delete in task

Outcome

Legacy służy wyłącznie w branchu implementacyjnym. Po zero unexplained diffs i E1–E4 zostaje usunięte wraz z build adapters i drift jobs.

+
Consequences
  • Czasowy dual path.
  • Semantic parity zamiast samego full-text diff.
  • Rollback po merge opiera się na Git/receipts.
  • Inventory test blokuje powrót generated trees.
+
+ +
+ Accepted

ADR-004 — Capability-sensitive compatibility

+
2026-07-14Convergence: 4CSafety fail-closed
+

Context

Host version nie odróżnia zmiany layoutu od zmiany gate/delegation semantics. Boolean capability ukrywa scenario, freshness i evidence level.

Drivers

  • fail-closed safety
  • nie blokować packaging changes
  • audytowalne claims
  • brak global force

Options

  1. global fail
  2. global warning
  3. 4C capability-sensitive

Outcome

Każda capability ma klasę semantic lub packaging. Unknown semantic blokuje; packaging może przejść po E1/E2/E4 jako provisional.

+
Consequences
  • Klasyfikacja jest częścią schema/review.
  • CLI rozróżnia supported/provisional/unavailable/failed.
  • Evidence jest per host/capability/version/scenario/time/target.
+
+ +
+ Accepted

ADR-005 — Usunięcie Claude Code

+
2026-07-14Convergence: 5DScope reduction
+

Context

Brak runtime i bieżącej potrzeby. Utrzymanie targetu zwiększa zakres i zachowuje Claude-native coupling przy niższym assurance.

Drivers

  • brak nietestowalnych claims
  • neutralny common core
  • minimal implementation

Options

  1. block without E5/E6
  2. retain E1–E4
  3. community certification
  4. 5D remove

Outcome

Claude znika z targets, installera, overlays, assets, tests, capability matrix, docs i vocabulary. Future support jest osobnym new-host task.

+
Consequences
  • Support matrix: Codex/Cursor/Kiro.
  • Możliwa komunikacja do istniejących użytkowników.
  • Brak placeholdera/future stub.
  • Project docs wymagają aktualizacji.
+
+ +
+ Accepted

ADR-006 — Transakcyjna własność konfiguracji

+
2026-07-14Installer invariantByte-exact rollback
+

Context

Host settings bywają współdzielone, a delete-before-copy może zostawić partial state. Standard projektu wymaga byte-exact non-mutation lub rollbacku.

Drivers

  • ochrona user data
  • jawna ownership
  • crash recovery
  • deterministyczny audit

Options

  1. overwrite whole settings
  2. best-effort merge
  3. dedicated files + managed keys
  4. manual config

Outcome

Mutacja ma whole_file lub managed_keys. Installer używa backup bytes/modes/topology, temp rename, journalu i immutable receipt. Active pointer zmienia się na końcu.

+
Consequences
  • Receipt/transaction schema są krytycznym API.
  • Recovery poprzedza nowe operacje.
  • Failure injection obejmuje każdy commit point.
  • Dedicated files są preferowane nad shared serialization.
+
+ +
+ Accepted

ADR-007 — Granica testów i dowodu

+
2026-07-14Research-derivedE1–E6
+

Context

Portable E3 jest powtarzane dla byte-identical copies, a host test names mają nierówne znaczenie. exit 77 jest brakiem dowodu, nie sukcesem.

Drivers

  • szybki PR feedback
  • host assurance tylko dla różnic
  • brak false-green skipów
  • scenario/version provenance

Options

  1. full suite per assembled tree
  2. core only
  3. E3 once + E1/E2/E4 per host + native E5/E6

Outcome

test-core działa raz. Parametryczny harness sprawdza trzy overlays, assembly i transactional lifecycle. Native probes zapisują structured evidence; 77 = unavailable.

+
Consequences
  • Krótszy PR gate.
  • Host tests nie kopiują core edge cases.
  • Evidence freshness jest release governance.
  • Support jest per capability/scenario.
+
+ +
+

Decision dependency map

+
ADR-001 minimal primitives
+        |
+        +------> ADR-002 common + overlays + installer
+                         |            |
+                         |            +--> ADR-006 transactional ownership
+                         |
+                         +--> ADR-003 legacy removal
+                         +--> ADR-004 compatibility
+                         +--> ADR-007 evidence
+
+ADR-005 Claude removal ------> narrows scope to 3 hosts
+
+ +
+

Traceability

+ + + + + + + + +
ChoiceADRDesign
1AADR-001Primitives
2DADR-002Overlay + Installer
3DADR-003Migration
4CADR-004Compatibility
5DADR-005Definition of Done
Transaction invariantADR-006Settings
Evidence boundaryADR-007Tests
+
+
+ + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-log.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-log.md new file mode 100644 index 00000000..1d1bcbcd --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-log.md @@ -0,0 +1,311 @@ +# Decision log: platformowo niezależny Maister + +## TL;DR +Przyjęto siedem decyzji prowadzących do jednego portable core, trzech jawnych host overlays i własnego transakcyjnego installera. +Zwykły dobór narzędzi pozostaje po stronie harnessu; formalizujemy tylko operacje wpływające na control flow, safety, persistence i capability claims. +Legacy generated trees oraz Claude Code zostaną usunięte przed zamknięciem zadania, po użyciu ich jako tymczasowego oracle migracji. +Każda decyzja ma status Accepted i wynika z konwergencji 1A/2D/3D/4C/5D albo z koniecznej konsekwencji transakcyjnego lifecycle. + +## Key Decisions +- ADR-001: minimalne semantic primitives, bez pełnego workflow DSL. +- ADR-002: jedna warstwa common, jawne repo-owned overlays i własny copy/merge installer. +- ADR-003: shadow comparison tylko w czasie implementacji; legacy znika przed Definition of Done. +- ADR-004: compatibility per capability — semantic fail-closed, packaging może być provisional. +- ADR-005: Claude Code zostaje usunięty; jego ewentualny powrót jest nowym zadaniem host integration. +- ADR-006: installer posiada zarządzane drzewa i jawne keys settings, używa journalu, receipt i byte-exact rollbacku. +- ADR-007: core testujemy raz, a E1/E2/E4 i dostępne E5/E6 pozostają per host oraz per scenario. + +## Open Questions / Risks +- Aktualne host contracts Codex/Cursor/Kiro muszą zostać ponownie potwierdzone podczas implementacji; ADR-y definiują politykę, nie zamrażają ich API. +- Granica primitive może puchnąć; każdy nowy binding wymaga dowodu powtarzalnej różnicy semantycznej albo ochrony safety/persistence. +- Multi-file settings transaction nie ma natywnej atomowości filesystemu; poprawność zależy od journalu, backupu i recovery tests. +- Task-scoped removal legacy nie zapewnia okresu obserwacji po release; parity i failure-injection gates muszą być kompletne przed deletion. +- E5/E6 zależą od dostępnego host runtime i auth; `unavailable` pozostaje jawną luką, nie sukcesem. + +## Status legend + +- **Accepted** — zatwierdzone przez użytkownika lub niezbędne do realizacji zatwierdzonego invariant. +- **Superseded** — zastąpione późniejszą decyzją; brak takich decyzji w tym logu. +- **Proposed** — wymaga decyzji; brak otwartych ADR-ów blokujących design. + +## ADR-001 — Minimalne semantic primitives zamiast pełnego IR + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 1A, wybrane przez użytkownika; doprecyzowanie: harness wybiera zwykłe narzędzia. + +### Context + +Canonical source jest obecnie powiązany z nazwami narzędzi i konstrukcjami jednego hosta, a adaptery wykonują setki transformacji tekstowych. Jednocześnie workflow jest w dużej części czytelną dokumentacją, której zamiana na pełny AST/DSL byłaby kosztowna i spekulatywna. Badanie oceniło minimalne typed primitives jako najlepszy stosunek separacji do kosztu ([canonical boundary](../analysis/findings/canonical-core-boundary.md), [alternatives](solution-exploration.md#2-obszar-decyzyjny-1--głębokość-reprezentacji-kanonicznej--ir)). + +### Decision drivers + +- jedna kopia generic skills; +- brak globalnego regex rewrite; +- zachowanie documentation-as-code; +- swoboda harnessu w doborze zwykłych narzędzi; +- formalne gwarancje na safety/control-flow/persistence boundaries; +- minimal implementation. + +### Considered options + +1. **1A — minimalne typed primitives + host-aware contract**. +2. 1B — pełny neutralny workflow IR/DSL. +3. 1C — canonical Markdown + ulepszone regex/golden snapshots. + +### Outcome + +Przyjmujemy 1A. Generic skills opisują intencję i są kopiowane bez zmian. `grep`, `rg`, read/search/explore i inne zwykłe strategie pozostają decyzją harnessu. Jawne primitives istnieją dla `present_user_gate`, wymaganej delegacji roli, safety hooks, persistence-before-continue, phase continuation i innych operacji, których błędna realizacja zmienia semantykę lub bezpieczeństwo. + +### Consequences + +- nie powstaje pełny DSL ani prompt compiler; +- potrzebny jest mały `primitives.yml` oraz binding completeness contract; +- generic vocabulary test blokuje nazwy host-specific tools; +- każdy nowy primitive wymaga uzasadnienia powtarzalną różnicą lub safety invariant; +- część neutralnej prozy nadal jest walidowana scenariuszowo, nie statycznie. + +## ADR-002 — Repo-owned host overlays i custom installer + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 2D, wybrane po odrzuceniu marketplace-oriented wariantów. + +### Context + +Użytkownik instaluje Maister z lokalnego repo albo GitHuba i chce pełnej kontroli nad installerem. Generic skills są identyczne, natomiast agents, commands, hooks, manifests, settings i wymagane semantic bindings są natywnie różne. Generowanie tych assetów w czasie instalacji przeniosłoby obecną złożoność adapterów do środowiska użytkownika ([host contracts](../analysis/findings/host-contracts-installation.md)). + +### Decision drivers + +- jawny diff host-specific behavior w repo; +- prosta, deterministyczna instalacja; +- brak marketplace i prebuilt release matrix; +- brak runtime generation z prozy; +- jedno utrzymywane common source; +- łatwe dodanie następnego hosta przez nowy overlay. + +### Considered options + +1. **2D — common + explicit host overlays + custom copy/merge installer**. +2. Installer generuje host-specific assets z descriptors/templates. +3. Repo przechowuje kompletne prebuilt trees z duplikowanymi skills. +4. CI/marketplace hybrid z materializerem — odrzucone jako poza zakresem. + +### Outcome + +Repo zawiera `common/` oraz `hosts/codex`, `hosts/cursor`, `hosts/kiro-cli`. Installer wybiera target, kopiuje common byte-for-byte, dokłada repo-owned overlay, wykonuje tylko jawny path/config merge, waliduje i transakcyjnie instaluje wynik. GitHub source jest resolve'owany do immutable commit SHA. + +### Consequences + +- każda różnica hosta jest widoczna w code review; +- overlay contract i test harness są obowiązkowe; +- podobne pliki hostów mogą pozostać małą, świadomą duplikacją; +- installer jest assemblerem i transaction managerem, nie compilerem workflow; +- dokumentacja dystrybucji nie zawiera marketplace assumptions. + +## ADR-003 — Legacy tylko jako oracle w zadaniu implementacyjnym + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 3D, wybrane przez użytkownika. + +### Context + +Commitowane target trees i obecne adaptery są wartościowym punktem porównania podczas migracji, ale stanowią główne źródło duplikacji. Długie utrzymywanie dual path przeczyłoby celowi zadania. Użytkownik zaakceptował użycie legacy w trakcie implementacji, pod warunkiem jego usunięcia przed zakończeniem zadania. + +### Decision drivers + +- wykrycie brakujących assets i semantic drift; +- finalny brak generated trees; +- brak dwóch ścieżek przez kolejne release; +- jednoznaczna Definition of Done; +- możliwość porównania hooks, permissions, inventory i references. + +### Considered options + +1. Usunąć legacy natychmiast po pierwszym działającym installerze. +2. Utrzymywać je przez dwa stabilne release. +3. Pozostawić jako stałe snapshots. +4. **3D — shadow w czasie zadania, obowiązkowe deletion przed jego zamknięciem**. + +### Outcome + +Legacy generated trees i build adapters są migration-only oracle. Po uzyskaniu zero niewyjaśnionych różnic oraz zielonych E1–E4 zostają usunięte w tym samym zadaniu. Końcowe CI i docs nie mogą się do nich odwoływać. + +### Consequences + +- branch implementacyjny czasowo zawiera dual path; +- końcowa bramka parity musi być silniejsza niż zwykły textual diff; +- rollback po merge opiera się na Git history/receipts, nie aktywnym legacy builderze; +- repository inventory test powinien blokować ponowne pojawienie się generated trees. + +## ADR-004 — Capability-sensitive compatibility + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 4C, wybrane przez użytkownika. + +### Context + +Numer wersji hosta nie mówi, czy zmienił się wyłącznie layout, czy semantyka gate/delegation/hooks. Globalne „fail” blokowałoby kompatybilne releases, a globalny warning mógłby przepuścić safety regression. Obecny boolean capability ukrywa host version, scenario, freshness i evidence level ([assurance findings](../analysis/findings/test-assurance-runtime-gap.md)). + +### Decision drivers + +- fail-closed safety boundaries; +- brak niepotrzebnego blokowania packaging changes; +- audytowalne claims; +- brak globalnego unsafe override; +- możliwość aktualizacji evidence bez zmiany common core. + +### Considered options + +1. Zawsze fail-closed poza zakresem wersji. +2. Zawsze warning i best-effort. +3. **4C — semantic fail-closed, packaging provisional**. + +### Outcome + +Overlay klasyfikuje każdą capability jako `semantic` albo `packaging`. Niepotwierdzony semantic fingerprint/binding blokuje instalację. Packaging-only może przejść po walidacji E1/E2/E4 ze statusem `provisional`. Evidence jest per host/capability/version/scenario/timestamp/target. + +### Consequences + +- klasyfikacja capability jest częścią review i schema; +- błędna klasyfikacja jest nowym istotnym ryzykiem; +- UI/CLI musi jasno odróżniać `supported`, `provisional`, `unavailable`, `failed`; +- nie ma globalnego `--force` dla semantic/safety invariants. + +## ADR-005 — Usunięcie Claude Code + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło konwergencji:** 5D, wybrane przez użytkownika. + +### Context + +Claude Code nie ma dostępnego runtime ani obecnie potwierdzonej potrzeby. Zachowanie targetu wymagałoby utrzymywania overlayu, testów i wyjątków przy niższym assurance, a obecne canonical source jest historycznie Claude-native. Zamiast raportować trwałe E5/E6 `unavailable`, użytkownik zdecydował usunąć host i wrócić do niego dopiero przy realnej potrzebie. + +### Decision drivers + +- redukcja zakresu i nietestowalnych claims; +- rzeczywiście neutralny common core; +- tylko hosty z aktywną potrzebą; +- brak projektowania pod hipotetyczną przyszłość; +- jasna lista supportu. + +### Considered options + +1. Blokować completion bez Claude E5/E6. +2. Zachować Claude z E1–E4 i jawnym E5/E6 unavailable. +3. Zewnętrzna/community certification. +4. **5D — usunąć Claude, dodać później jako nowy host**. + +### Outcome + +Claude znika ze supported targets, installera, overlays, canonical manifests, agents, commands, hooks, settings, tests, capability matrix i dokumentacji. Claude-native vocabulary zostaje usunięte z generic layer. Ponowne dodanie wymaga osobnego zadania z aktualnym Host Overlay Contract i dostępnością wymaganych testów. + +### Consequences + +- support matrix obejmuje Codex, Cursor i Kiro CLI; +- obecni użytkownicy Claude, jeśli istnieją, tracą wsparcie i wymagają komunikacji migracyjnej; +- nie powstaje placeholder `hosts/claude` ani future stub; +- docs project vision/architecture/roadmap wymagają aktualizacji. + +## ADR-006 — Transakcyjna własność konfiguracji + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło:** konsekwencja zatwierdzonego custom installera i istniejącego standardu byte-exact rollback. + +### Context + +Host settings często współdzielą plik z konfiguracją użytkownika. Obecne instalatory Cursor/Kiro mogą najpierw usuwać destination, co pozostawia partial state po przerwaniu; standard projektu wymaga dowodu byte-exact non-mutation lub rollbacku dla transactional writers ([install evidence](../analysis/findings/test-assurance-runtime-gap.md), `.maister/docs/standards/testing/test-writing.md`). + +### Decision drivers + +- brak utraty danych użytkownika; +- update/uninstall tylko w granicach własności Maister; +- crash recovery; +- deterministyczny audit; +- wspólna implementacja lifecycle. + +### Considered options + +1. Nadpisywanie całych settings files. +2. Best-effort merge bez receipt. +3. Dedykowane pliki tam, gdzie host pozwala, oraz managed-key merge z journalem dla shared config. +4. Pozostawienie settings do ręcznej konfiguracji. + +### Outcome + +Installer deklaruje `whole_file` albo `managed_keys` per mutation. Przed commit zapisuje backup bytes/modes/topology, używa temp+atomic rename, transaction journalu i immutable receipt. Active receipt zmienia się dopiero po pełnym sukcesie. Uninstall usuwa tylko nadal zarządzane wartości; user drift pozostaje nietknięty. + +### Consequences + +- transaction/receipt schemas stają się krytycznym interfejsem; +- recovery musi uruchamiać się przed nową operacją; +- failure-injection tests obejmują każdy punkt commit; +- serializacja config może zmienić formatting, więc preferowane są dedicated files; shared merge wymaga świadomego formatter contract. + +## ADR-007 — Granica testów i dowodu + +**Status:** Accepted +**Data:** 2026-07-14 +**Źródło:** research evidence oraz zatwierdzone rozdzielenie common/overlay. + +### Context + +Portable runtime ma wykonywalne E3, ale pełne suite'y są powtarzane dla byte-identical target copies. Jednocześnie host tests mają nierówne znaczenie: część to strukturalne checks, część realnie uruchamia CLI, a `exit 77` sygnalizuje brak dowodu. Nazwa testu nie może zastępować jawnego evidence level ([test assurance findings](../analysis/findings/test-assurance-runtime-gap.md)). + +### Decision drivers + +- szybki PR feedback bez czterokrotnego core; +- host-specific assurance tam, gdzie host rzeczywiście się różni; +- brak fałszywie zielonych skipów; +- claims powiązane z wersją i scenariuszem; +- możliwość dodania kolejnego hosta bez kopiowania całej suite. + +### Considered options + +1. Pełna suite dla każdego złożonego tree. +2. Tylko common core tests. +3. **Pełny E3 raz + parametryczne E1/E2/E4 per host + native E5/E6 per scenario**. + +### Outcome + +CI uruchamia pełne `test-core` raz. Dla Codex/Cursor/Kiro uruchamia wspólny overlay harness, deterministic assembly canary i pełny transactional lifecycle. Native host smoke/E2E są oddzielne i zapisują structured evidence. `77` oznacza `unavailable` i nigdy pass. + +### Consequences + +- krótszy, czytelniejszy PR quality gate; +- per-host tests nie mogą ponownie duplikować core edge cases; +- evidence schema i freshness validation są częścią release governance; +- host support jest per capability/scenario, nie jednym booleanem. + +## Decision dependency map + +```text +ADR-001 minimal primitives + | + +------> ADR-002 common + overlays + installer + | | + | +--> ADR-006 transactional ownership + | + +--> ADR-003 legacy removal + +--> ADR-004 capability compatibility + +--> ADR-007 evidence boundary + +ADR-005 Claude removal --------> narrows ADR-002/003/007 to 3 hosts +``` + +## Traceability matrix + +| Convergence choice | ADR | Design section | +|---|---|---| +| 1A | ADR-001 | High-level design §5 | +| 2D | ADR-002 | High-level design §3, §6–9 | +| 3D | ADR-003 | High-level design §12–13 | +| 4C | ADR-004 | High-level design §10 | +| 5D | ADR-005 | High-level design §12–13 | +| transactional installer invariant | ADR-006 | High-level design §7–9 | +| core once / host evidence | ADR-007 | High-level design §11 | + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-summary.html b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-summary.html new file mode 100644 index 00000000..55a5be55 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-summary.html @@ -0,0 +1,4 @@ + + +Decision Summary +

Decision Summary

TL;DR

Research, konwergencja i high-level design zostały ukończone. Finalny kierunek to neutralny core, jawne overlays Codex/Cursor/Kiro CLI, transakcyjny custom installer oraz usunięcie Claude i legacy trees. Użytkownik zaakceptował końcowy handoff; workflow jest zakończony.

PhaseGateSelectionActorStatus
phase-1phase-1-exitContinue to brainstorming evaluationuserdecided
phase-2optional-phase-selection (brainstorming)Yes, explore alternativesuserdecided
phase-2optional-phase-selection (design)Yes, generate designuserdecided
phase-3phase-3-exitContinue to solution convergenceuserdecided
phase-4canonical representation1Auserdecided
phase-4marketplace framingNeed more infouserdecided
phase-4repository-owned overlay model2Duserdecided
phase-4two-release migrationNeed more infouserdecided
phase-4task-scoped removal gate3Duserdecided
phase-4unknown harness version policy4Cuserdecided
phase-4Claude assurance framingNeed more infouserdecided
phase-4Claude target removal5Duserdecided
phase-4phase-4-exitContinue to high-level designuserdecided
phase-5research-clarificationConfirm assumptionsuserdecided
phase-5phase-5-exitContinue to output generationuserdecided
phase-6final-handoff-approvalComplete workflowuserdecided

Audit metadata

Configurable gates inherited fully_automatic, but this validation run used the interactive fallback because qualifying host-native continuation evidence was not executed. Final handoff is denylisted and was explicitly resolved by the user. Advisor model: gpt-5.6-sol; Arbiter model: gpt-5.6-sol; no model attempts, retries, arbitration, or user overrides occurred.

Full workflow context

diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-summary.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-summary.md new file mode 100644 index 00000000..00ef9895 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/decision-summary.md @@ -0,0 +1,57 @@ +# Decision Summary + +## TL;DR +Research, konwergencja i high-level design zostały ukończone. +Finalny kierunek to neutralny core, jawne overlays Codex/Cursor/Kiro CLI, transakcyjny custom installer oraz usunięcie Claude i legacy trees. +Użytkownik zaakceptował końcowy handoff; workflow jest zakończony. + +## Key Decisions +- Continue to brainstorming evaluation — User explicitly chose to continue after reviewing the completed research foundation and report. +- Yes, explore alternatives — User accepted the recommendation to explore alternatives. +- Yes, generate design — User accepted the recommendation to generate a high-level design after solution convergence. +- Continue to solution convergence — User explicitly chose to continue from generated alternatives to sequential solution convergence. +- 1A — minimalne typed primitives + host-aware templates — Low-level tool selection normally remains with the host harness; explicit bindings cover control-flow, safety, persistence, and capability-sensitive operations. +- Marketplace poza zakresem — instalacja ma działać z lokalnego lub GitHub repo przez własny installer. +- 2D — custom installer + wspólne skille + jawne host overlays w repo. +- Shadow comparison ograniczone do zadania implementacyjnego — legacy trees muszą zniknąć przed Definition of Done. +- 3D — shadow podczas implementacji, usunięcie legacy trees przed zamknięciem zadania. +- 4C — capability-sensitive: semantic fail-closed, packaging provisional. +- Claude Code powinien zostać usunięty do czasu realnej potrzeby i dostępnego runtime. +- 5D — usunąć Claude Code ze wspieranych targetów. +- Continue to high-level design. +- Confirm assumptions — User confirmed the consolidated architecture assumptions without corrections. +- Continue to output generation — User explicitly chose to continue from the completed high-level design to final output generation. +- Complete workflow — User explicitly approved the final research handoff and completion of the workflow. + +## Gate history + +| Phase | Gate | Question | Options | Recommendation | Selection | Actor | Confidence | Status | +|---|---|---|---|---|---|---|---|---| +| phase-1 | phase-1-exit | Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation? | Continue to brainstorming evaluation; Pause workflow | Continue to brainstorming evaluation | Continue to brainstorming evaluation | user | high | decided | +| phase-2 | optional-phase-selection | Badanie wykazało cztery realne warianty oraz nierozstrzygnięte decyzje dotyczące IR, marketplace artifacts, momentu usunięcia generated trees i polityki nieznanych wersji hostów. Would you like to explore solution alternatives? | Yes, explore alternatives; No, skip brainstorming | Yes, explore alternatives | Yes, explore alternatives | user | high | decided | +| phase-2 | optional-phase-selection | Rekomendacja obejmuje nową granicę portable core/Host Contract/materializer, transakcyjną instalację, przebudowę CI oraz etapową migrację dystrybucji, więc high-level design jest wartościowy. Would you like to generate a high-level design? | Yes, generate design; No, skip design | Yes, generate design | Yes, generate design | user | high | decided | +| phase-3 | phase-3-exit | Continue to solution convergence? | Continue to solution convergence; Pause workflow | Continue to solution convergence | Continue to solution convergence | user | high | decided | +| phase-4 | research-convergence | Jak głęboka powinna być kanoniczna reprezentacja workflow Maister? | 1A; 1B; 1C; Need more info | 1A | 1A | user | high | decided | +| phase-4 | research-convergence | Gdzie powinien działać materializer i jak dystrybuować host-native artefakty? | 2A; 2B; 2C; Need more info | 2C | Need more info | user | high | decided | +| phase-4 | research-convergence | Jaki model instalacji i przechowywania host-specific assets powinniśmy przyjąć po wykluczeniu marketplace? | 2D; 2A; 2B; Need more info | 2D | 2D | user | high | decided | +| phase-4 | research-convergence | Kiedy i na jakich warunkach usunąć obecne commitowane generated trees? | 3A; 3B; 3C; Need more info | 3B | Need more info | user | high | decided | +| phase-4 | research-convergence | Jaką bramkę usunięcia legacy generated trees przyjąć dla zadania implementacyjnego? | 3D; 3A; 3B; Need more info | 3D | 3D | user | high | decided | +| phase-4 | research-convergence | Jak custom installer powinien obsługiwać nieznaną lub niepotwierdzoną wersję harnessu? | 4A; 4B; 4C; Need more info | 4C | 4C | user | high | decided | +| phase-4 | research-convergence | Jaką bramkę jakości przyjąć dla overlay i instalacji Claude Code bez dostępnego runtime? | 5A; 5B; 5C; Need more info | 5B | Need more info | user | high | decided | +| phase-4 | research-convergence | Co zrobić z targetem Claude Code w docelowej architekturze? | 5D; 5B; 5A; Need more info | 5D | 5D | user | high | decided | +| phase-4 | phase-4-exit | Brainstorming complete. Continue to high-level design? | Continue to high-level design; Pause workflow | Continue to high-level design | Continue to high-level design | user | high | decided | +| phase-5 | research-clarification | Czy potwierdzasz skonsolidowane założenia architektury? | Confirm assumptions; Correct assumptions; Provide more context | Confirm assumptions | Confirm assumptions | user | high | decided | +| phase-5 | phase-5-exit | Design complete. Continue to output generation? | Continue to output generation; Pause workflow | Continue to output generation | Continue to output generation | user | high | decided | +| phase-6 | final-handoff-approval | Research workflow complete. Complete workflow? | Complete workflow; Keep workflow open | Complete workflow | Complete workflow | user | high | decided | + +## Audit metadata + +- All configurable gates inherited `fully_automatic` from the workflow snapshot, but this validation run did not execute qualifying host-native continuation evidence; they therefore used the interactive user fallback. +- `final-handoff-approval` is denylisted and resolved to `manual` regardless of configuration. +- Advisor: logical agent `advisor`, model `gpt-5.6-sol`; no advisor attempts were executed because gates used the user path. +- Arbiter: logical agent `arbiter`, model `gpt-5.6-sol`; no disagreement arbitration or retries were executed. +- Every terminal selection, including final handoff, was made by the user with `confidence: high`. +- `user_override` is false for every persisted gate; no implementation approval, rollback, scope-expansion, or production action was inferred. +- Full options, rationales, statuses and idempotency records are in [orchestrator-state.yml](../orchestrator-state.yml). + +Full workflow context: [orchestrator-state.yml](../orchestrator-state.yml) diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/high-level-design.html b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/high-level-design.html new file mode 100644 index 00000000..bcf7a4ac --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/high-level-design.html @@ -0,0 +1,314 @@ + + + + +High-level design — platformowo niezależny Maister + + + + +
+ High-level design +

Platformowo niezależny Maister

+

Portable documentation core + jawne host overlays + transakcyjny custom installer

+
+
+
3wspierane hosty
+
10komponentów
+
7ADR
+
5faz migracji
+
E1–E6evidence ladder
+
+ +
+

TL;DR

+

Wspólne skille są kopiowane bez zmian. Codex, Cursor i Kiro CLI mają jawne repozytoryjne overlays dla agents, commands, hooks, manifests, settings i semantycznych bindings. Installer wykonuje deterministyczne copy/merge, staging, validation i transakcyjny commit. Legacy generated trees oraz Claude Code znikają przed zamknięciem zadania.

+

Key Decisions

+
    +
  • Portable documentation core, bez pełnego workflow DSL i bez prompt rewrite.
    • +
  • Harness wybiera ordinary tools; explicit bindings chronią control flow, safety, persistence i capability claims.
    • +
  • Jedna kopia common + jawne hosts/codex, hosts/cursor, hosts/kiro-cli.
    • +
  • Custom installer z local/GitHub source, receipt, journalem i byte-exact rollbackiem.
    • +
  • Semantic unknown fail-closed; packaging-only może być provisional.
    • +
  • Legacy i Claude zostają usunięte w tym samym zadaniu po parity gate.
    • +
+

Open Questions / Risks

+
    +
  • Aktualne discovery paths i settings formats hostów wymagają potwierdzenia w testach.
    • +
  • Shared settings potrzebują journalu, backupu i recovery zamiast pozornej wieloplikowej atomowości.
    • +
  • Neutralna proza może zacząć przemycać host vocabulary.
    • +
  • Błędna klasyfikacja packaging/semantic może przepuścić niezgodność.
    • +
  • Task-scoped deletion wymaga kompletnego parity i failure-injection gate.
    • +
+
+ + + +
+
+

1. Architektura i przepływ

+
+

Styl: modular monolith dystrybuowany jako repozytoryjny bundle, z portable documentation core, deklaratywnymi Host Overlay Contracts i transakcyjnym adapterem instalacyjnym.

+
Maintainer edits
+      |
+      v
++-------------------+       +-------------------------+
+| common/           |       | hosts/<target>/          |
+| skills + runtime  |       | explicit native overlay |
++-------------------+       +-------------------------+
+          \                         /
+           v                       v
+             +-------------------+
+             | custom installer  |
+             | copy + merge only |
+             +-------------------+
+                       |
+                stage -> validate
+                       |
+                  atomic commit
+                       v
+             host-native managed tree
+

Common definiuje co ma się wydarzyć, overlay jak harness reprezentuje integracje, a installer jak bezpiecznie dostarczyć oba moduły. Installer nie interpretuje promptów.

+
+
+
In scope
  • Codex, Cursor, Kiro CLI
  • local/GitHub source
  • common skills/runtime
  • explicit native overlays
+
Out of scope
  • marketplace
  • Claude Code
  • jeden identyczny installed tree
  • pełny IR/DSL
  • host assets generowane z promptów
+
+
+ +
+

2. Proponowane repo

+ 
maister/
+├── common/
+│   ├── skills/        # jedna kopia generic SKILL.md
+│   ├── runtime/       # state, gates, continuation
+│   ├── references/    # wspólne kontrakty
+│   ├── assets/        # dashboard/report assets
+│   └── primitives.yml
+├── hosts/
+│   ├── codex/{overlay.yml,agents,commands,hooks,manifests,settings,tests}
+│   ├── cursor/{overlay.yml,agents,commands,hooks,manifests,settings,tests}
+│   └── kiro-cli/{overlay.yml,agents,commands,hooks,manifests,settings,tests}
+├── installer/{bin,lib}
+├── schemas/{host-overlay,primitive,receipt,evidence}.schema.json
+├── tests/{core,overlay-contract,installer,host-runtime,fixtures}
+└── docs/{installation,host-support,adding-a-host}.md
+

Obecne plugins/maister/skills może być przejściowym ownerem, ale końcowa struktura nie może pozostać Claude pluginem bez deklarowanego supportu.

+
+ +
+

3. Głębokie komponenty

+
+ + + + + + + + + + + + + +
KomponentPubliczny kontraktNie odpowiada za
Portable coreskills, runtime, primitive ids, E3 contractslayout/tool names/settings hosta
Primitive registryid, class, required effect, failure policyworkflow DSL/AST
Host overlayoverlay.yml + native assetskopie generic skills i proza transforms
Source resolverlocal/GitHub → immutable source SHAinstalacja i mutacje
Assemblerassemble(source, overlay, staging)generowanie agents/hooks z promptów
Validatorschema, inventory, paths, compatibilityautomatyczna naprawa
Settings mergeplan/read/apply/restore managed keysniezarządzane klucze
Transaction managerprepare → commit → finalize / rollbackczęściowy sukces
Receipt storeimmutable receipts + active pointerworkflow state
Evidence harnessE1–E6 per capability/scenariomapowanie unavailable na pass
+
+ +
+

4. Granica semantic primitives

+
+
Harness-owned

Ordinary operations

  • wyszukaj pliki/symbole — rg, grep, index, Explore
  • przeczytaj kod — native read, shell, index
  • uruchom test — host process runner
  • sformatuj — repo formatter
  • zbierz read-only context — inline lub helper

Generic prompt opisuje intencję, nie nazwę toola.

+
Explicit binding

Semantic invariants

  • present_user_gate
  • delegate_role, gdy delegacja jest wymagana
  • persist_before_continue
  • continue_phase
  • enforce_safety_hook
  • resolve_project_instructions

Błędna realizacja zmienia control flow, safety, persistence lub capability claim.

+
+ 
- id: present_user_gate
+  class: control-flow
+  required_effect: block_until_one_exact_option_is_selected
+  failure_policy: fail_closed
+- id: search_repository
+  class: ordinary
+  binding: harness_owned

Primitive dodajemy tylko po powtarzalnej różnicy semantycznej albo dla safety/persistence invariant.

+
+ +
+

5. Host Overlay Contract

+ 
schema_version: 1
+host_id: codex
+overlay_version: 1
+layout:
+  managed_root: ".codex/plugins/maister"
+  copy_common: [{from: common/skills, to: skills}]
+  overlay_assets: [{from: hosts/codex/agents, to: agents}]
+capabilities:
+  present_user_gate:
+    class: semantic
+    binding: hooks/user-gate.md
+    evidence_required: E5
+  plugin_layout:
+    class: packaging
+    binding: manifests/plugin.json
+    evidence_required: E2
+settings:
+  - {id: advisor_agent, format: toml, ownership: whole_file}
+validation:
+  forbidden_vocabulary: ["AskUserQuestion", "Task tool"]
+
Obowiązkowe invariants
  • allowlisted paths i path containment;
  • brak niejawnych common/overlay collisions;
  • binding albo jawny unsupported dla każdego required primitive;
  • class semantic/packaging i evidence target;
  • pełne inventory native assets;
  • repo-owned host contract tests.
+
+ +
+

6. Custom installer i lifecycle

+ 
maister install   --target codex|cursor|kiro-cli [--source PATH|GH_URL] [--ref TAG_OR_SHA]
+                  [--scope user|project] [--dest PATH] [--host-version VERSION]
+                  [--dry-run] [--json]
+maister update    --target HOST [...]
+maister uninstall --target HOST [--dry-run]
+maister rollback  --target HOST [--to RECEIPT_ID]
+maister verify    --target HOST [--native]
+maister status    [--target HOST] [--json]
+
Transaction flow

resolve → probe → compatibility → lock → plan → stage → validate → backup → commit tree → commit settings → receipt → active pointer

Failure: restore bytes, modes, symlinks and topology; keep previous receipt active.

+
+
Install

Pełny staging przed pierwszą mutacją. Jeden active receipt albo pełny rollback.

+
Update

Nowy staging od zera, integrity/drift check, poprzedni receipt jako rollback target.

+
Uninstall

Usuwa tylko managed paths/keys; zachowuje user drift i niepuste parent dirs.

+
Rollback

Odtwarza snapshot starego receipt, nie rekonstruuje go z bieżącego source.

+
+
Receipt i crash recovery

Receipt zapisuje target, scope, immutable source commit, Maister/overlay/host versions, compatibility status, pełny managed inventory z hashami/modes, settings ownership, previous receipt i evidence. Journal przechowuje prepared, committing, rolling_back. Recovery zawsze poprzedza nową operację.

+
+ +
+

7. Własność settings

+
+ + +
PolicySemantykaUninstall
whole_filededykowany plik wyłącznie Maister, atomic replaceusuń, jeśli hash nadal odpowiada receipt
managed_keysjawne JSON/TOML/YAML paths we współdzielonym plikuusuń tylko nadal zarządzane wartości; zachowaj drift

Brak deep merge i sed. Parse → validate → allowlisted mutate → deterministic temp write → atomic rename. Backup zachowuje bytes, mode i topology.

+
+ +
+

8. Compatibility i evidence

+
+ + + + +
StanSemantic/safetyPackaging-only
known + required evidencesupportedsupported
unknown version, unchanged fingerprinttylko jeśli kontrakt jawnie dopuszcza fingerprintprovisional po E1/E2/E4
changed fingerprint / missing bindingfail-closedfail lub provisional po pełnej walidacji
runtime unavailableunavailable, nigdy passnie podnosi ponad E4

Nie ma globalnego --force dla safety invariants. Record zawiera host, capability, class, host/overlay version, fingerprint, evidence level, status, scenario, timestamp i target.

+
+ +
+

9. Macierz testów

+
+ + + + + + + +
TargetZakresFrequencyEvidence
test-corestate/gates/continuation/failure injectionkażdy PR, razE3
test-generic-skillsinventory, links, neutral vocabularykażdy PRE1/E3
test-overlay HOSTschema/native assets/bindingskażdy PR ×3E1
test-assembly HOSTdeterminism, hashes, installed canarykażdy PR ×3E2/E3
test-installer HOSTlifecycle + injected rollbackkażdy PR ×3E4
test-host-smoke HOSTdiscovery + sentinelgdy runtime dostępnyE5
test-host-e2egate/delegation/continuation scenariorelease/scheduledE6

exit 77 to unavailable, nie passing skip. Claim supportu jest per capability/scenario.

+
+ +
+

10. Migracja w jednym zadaniu

+
+
M0

Baseline

Inventory legacy, semantic manifests, obecne build/validate.

+
M1

Neutral common

Przenieś common, usuń Claude vocabulary, dodaj primitives/core tests.

+
M2

Overlays

Codex/Cursor/Kiro native assets, schema i contract harness.

+
M3

Installer

Local/GitHub, transaction lifecycle, E4 i canaries.

+
M4

Shadow comparison

Zero niewyjaśnionych różnic w semantics/inventory/hooks.

+
M5

Delete before completion

Usuń generated trees, build adapters, Claude, drift jobs; przepnij CI/docs.

+
+
+ +
+

11. Definition of Done

+
    +
  1. Jedna byte-identical kopia generic skills dla trzech hostów.
    2. +
  2. Generic layer nie zawiera Claude/foreign-host tool vocabulary.
    3. +
  3. Każdy required semantic primitive ma binding lub validated unsupported fallback.
    4. +
  4. Trzy overlays zawierają pełne native assets i contract tests.
    5. +
  5. Installer działa z local/GitHub SHA, bez marketplace i runtime generation.
    6. +
  6. Fresh/update/uninstall/rollback przechodzą dla każdego hosta.
    7. +
  7. Failures dowodzą byte-exact bytes/modes/symlinks/topology rollback.
    8. +
  8. Settings merge dotyka wyłącznie managed keys i zachowuje user drift.
    9. +
  9. Compatibility ma semantic fail-closed i audytowalne packaging provisional.
    10. +
  10. Core E3 raz; host E1/E2/E4 i dostępne E5/E6 emitują records.
    11. +
  11. Shadow comparison ma zero niewyjaśnionych różnic.
    12. +
  12. Legacy adapters, transforms, drift jobs i generated trees nie istnieją.
    13. +
  13. Claude nie istnieje w targets, installerze, overlays, assets, tests, matrix, docs ani vocabulary.
    14. +
  14. Project docs opisują nową architekturę i trzy hosty.
    15. +
  15. Clean checkout instaluje/verify/uninstall bez brudzenia repo.
    16. +
+
+ +
+

12. Ryzyka i obserwowalność

+
+ + + + + + +
RyzykoMitigacjaSygnał
semantic drift w prozievocabulary + primitive/scenario reviewfailed canary/inventory diff
partial installstaging, journal, backup, injected failurestransaction/recovery status
host contract driftfingerprints + fail-closedper-capability decision
utrata user configreceipt ownership + drift checkconflict report
legacy zostajeM5 + repository inventory gateforbidden path failure
false-green native testsE0–E6 records, 77=unavailablestatus/freshness dashboard
+

Pełny ślad siedmiu decyzji: Decision Log. Dowody źródłowe: canonical boundary, host contracts, test assurance.

+
+
+ + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/high-level-design.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/high-level-design.md new file mode 100644 index 00000000..46fafd74 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/high-level-design.md @@ -0,0 +1,492 @@ +# High-level design: platformowo niezależny Maister + +## TL;DR +Maister przechodzi na architekturę **portable documentation core + repository-owned host overlays + transactional installer**. +Wspólne skille są kopiowane bez zmian, a Codex, Cursor i Kiro CLI przechowują jawne agents, commands, hooks, manifests, settings oraz bindings tylko dla operacji semantycznie istotnych. +Installer składa `common + hosts/` przez deterministyczne copy/merge, waliduje staging i zatwierdza instalację transakcyjnie z receipt oraz byte-exact rollbackiem. +Legacy generated trees i cały target Claude Code służą wyłącznie jako tymczasowy oracle migracji i muszą zniknąć przed zamknięciem zadania implementacyjnego. + +## Key Decisions +- Architektura: **portable documentation core with explicit host overlays**, nie pełny workflow DSL ani install-time compiler promptów. +- Harness sam wybiera zwykłe narzędzia wykonawcze; jawne bindings obejmują wyłącznie control flow, safety, persistence i capability-sensitive behavior. +- Jedna kopia generic skills/runtime jest instalowana bez transformacji, a host-native assets są utrzymywane wprost w `hosts/codex`, `hosts/cursor` i `hosts/kiro-cli`. +- Własny installer obsługuje lokalne repo i GitHub source, staging, validation, lock, receipt, atomic commit, update, uninstall i rollback. +- Nieznana wersja hosta blokuje niepotwierdzone capabilities semantyczne; packaging-only może otrzymać jawny status `provisional`. +- Legacy build adapters, committed generated trees i Claude Code zostają usunięte w tym samym zadaniu po shadow comparison i spełnieniu Definition of Done. + +## Open Questions / Risks +- Docelowe ścieżki discovery i format settings każdego hosta trzeba potwierdzić aktualnymi testami contract/runtime przed implementacją overlayu. +- Atomowa podmiana całego managed tree jest prosta; wieloplikowy merge do współdzielonych ustawień użytkownika wymaga journalu i byte-exact rollbacku. +- Neutralna proza może z czasem zacząć przemycać słownik jednego hosta; potrzebny jest forbidden-vocabulary contract oraz review wyjątków. +- Błędna klasyfikacja capability jako `packaging` zamiast `semantic` może przepuścić niezgodność; klasyfikacja musi być jawna i przeglądana. +- Usunięcie legacy w jednym zadaniu zwiększa wagę końcowej bramki parity, szczególnie dla hooks, agents i invocation semantics. + +## 1. Kontekst i cele + +Obecny system ma jedno Claude-oriented źródło, trzy adaptery tekstowe i trzy commitowane projekcje. Badanie wykazało około 610 plików projekcji, około 5,08 MB duplikowanych drzew i około 320 substytucji tekstowych, mimo że pięć kluczowych modułów runtime jest byte-identical w targetach ([canonical core evidence](../analysis/findings/canonical-core-boundary.md)). Testy potwierdzają też, że wspólna semantyka state/gate/continuation ma wykonywalny poziom E3, podczas gdy pełny runner contract jest niepotrzebnie powtarzany dla kopii ([assurance evidence](../analysis/findings/test-assurance-runtime-gap.md)). + +Projekt ma osiągnąć: + +1. jedno utrzymywane źródło generic skills i portable runtime; +2. jawne, małe różnice hostów bez globalnych transformacji prozy; +3. instalację z lokalnego checkoutu albo GitHuba pod pełną kontrolą projektu; +4. testowanie wspólnej semantyki raz i host contracts tylko tam, gdzie rzeczywiście się różnią; +5. brak nietestowalnego Claude Code oraz brak commitowanych generated trees po zakończeniu migracji. + +Poza zakresem są marketplace, jeden identyczny installed tree, pełny workflow IR/DSL, generowanie host assets z promptów oraz emulowanie brakujących capabilities przez niejawne rewrite'y. + +## 2. Styl architektury i granice + +**Styl:** modular monolith dystrybuowany jako repozytoryjny bundle, z portable documentation core, deklaratywnymi Host Overlay Contracts i transakcyjnym adapterem instalacyjnym. + +```text +Maintainer edits + | + v ++-------------------+ +-------------------------+ +| common/ | | hosts// | +| skills + runtime | | explicit native overlay | ++-------------------+ +-------------------------+ + \ / + \ / + v v + +-------------------+ + | custom installer | + | copy + merge only | + +-------------------+ + | + stage -> validate + | + atomic commit + v + host-native managed tree +``` + +Granica modułu jest celowo głęboka: + +- `common` opisuje **co ma się wydarzyć** i utrzymuje invariants workflow; +- `hosts/` opisuje **jak dany harness reprezentuje wymagane integracje**; +- `installer` odpowiada za **bezpieczne dostarczenie obu warstw**, ale nie interpretuje semantyki promptów; +- `tests` dostarczają oddzielny dowód core, overlay, install i native runtime. + +## 3. Proponowana struktura repozytorium + +```text +maister/ +├── common/ +│ ├── skills/ # jedna kopia generic SKILL.md +│ ├── runtime/ # state, gates, continuation, helpers +│ ├── references/ # wspólne kontrakty i metodyki +│ ├── assets/ # dashboard/report assets +│ └── primitives.yml # mały rejestr semantic invariants +├── hosts/ +│ ├── codex/ +│ │ ├── overlay.yml # Host Overlay Contract +│ │ ├── agents/ +│ │ ├── commands/ +│ │ ├── hooks/ +│ │ ├── manifests/ +│ │ ├── settings/ +│ │ └── tests/ +│ ├── cursor/ # identyczny kontrakt katalogów +│ └── kiro-cli/ +├── installer/ +│ ├── bin/maister-install.mjs +│ └── lib/ +│ ├── source-resolver.mjs +│ ├── overlay-loader.mjs +│ ├── compatibility.mjs +│ ├── assembler.mjs +│ ├── validator.mjs +│ ├── transaction.mjs +│ ├── settings-merge.mjs +│ └── receipt-store.mjs +├── schemas/ +│ ├── host-overlay.schema.json +│ ├── primitive.schema.json +│ ├── receipt.schema.json +│ └── evidence.schema.json +├── tests/ +│ ├── core/ +│ ├── overlay-contract/ +│ ├── installer/ +│ ├── host-runtime/ +│ └── fixtures/ +└── docs/ + ├── installation.md + ├── host-support.md + └── adding-a-host.md +``` + +`common/skills` może pozostać fizycznie w obecnym `plugins/maister/skills` podczas pierwszych kroków migracji, ale końcowy owner nie może być nazwany ani ukształtowany jako Claude plugin. Nazwy docelowe są częścią migracji, nie wymaganiem wstecznej kompatybilności. + +## 4. Komponenty i głębokie interfejsy + +| Komponent | Odpowiedzialność | Publiczny interfejs | Czego nie robi | +|---|---|---|---| +| Portable core | Skills, workflow invariants, state/gate/continuation runtime | pliki `common/**`, primitive ids, executable core contracts | nie zna layoutu, tool names ani settings hosta | +| Primitive registry | Minimalny słownik operacji wymagających jawnej gwarancji | `id`, `class`, `required_effect`, `failure_policy` | nie jest DSL-em faz ani prompt AST | +| Host overlay | Natywne assets i bindings jednego harnessu | `overlay.yml` + repo-owned files | nie kopiuje generic skills i nie transformuje ich prozy | +| Source resolver | Lokalny checkout albo zweryfikowane źródło GitHub | `resolve(source, ref) -> immutableSource` | nie instaluje i nie ufa ruchomemu refowi bez receipt | +| Assembler | Deterministyczne `common + overlay` w staging | `assemble(source, overlay, staging)` | nie generuje agents/hooks/commands z promptów | +| Validator | Schema, inventory, paths, references, compatibility | `validate(staging, contract, hostFacts)` | nie naprawia niezgodnych danych | +| Settings merge | Plan kontrolowanych mutacji shared config | `plan/read/apply/restore` dla managed keys | nie nadpisuje niezarządzanych kluczy | +| Transaction manager | Lock, backup, commit, rollback i recovery | `prepare -> commit -> finalize` | nie uznaje częściowego sukcesu | +| Receipt store | Własność, hashes, evidence i historia instalacji | immutable receipt + active pointer | nie jest źródłem workflow state | +| Evidence harness | E1–E6 ze statusem i provenance | evidence record per host/capability/scenario | `unavailable` nigdy nie mapuje na pass | + +## 5. Taksonomia semantic primitives + +Zasada wyboru jest prosta: **jeżeli harness może swobodnie wybrać sposób wykonania bez zmiany obserwowalnej semantyki workflow, nie tworzymy bindingu**. Primitive powstaje dopiero wtedy, gdy błędny wybór może ominąć pauzę, zmienić trwały stan, naruszyć safety policy albo fałszywie zadeklarować capability. + +### 5.1 Harness-owned ordinary operations + +| Intencja w generic skill | Decyzja harnessu | Dlaczego bez bindingu | +|---|---|---| +| znajdź pliki lub użycia symbolu | `rg`, grep, index, search tool, Explore | wynik nie zależy od nazwy narzędzia | +| przeczytaj i przeanalizuj kod | native read, shell, semantic index | prompt określa cel i zakres | +| uruchom lokalny test | shell/process runner | exit code i artefakt są wystarczającym kontraktem | +| sformatuj plik | repo formatter lub edycja natywna | repo standards definiują wynik | +| zbierz read-only informacje | wykonanie inline albo pomocniczy agent | delegacja nie jest wymagana semantycznie | + +Generic skills używają języka intencji: „wyszukaj”, „przeczytaj”, „zweryfikuj”. Nie zawierają `Grep`, `Task tool`, `Explore tool`, `AskUserQuestion`, `Skill tool` ani odpowiedników konkretnych hostów. + +### 5.2 Explicit semantic bindings + +| Primitive | Klasa | Wymagany efekt | Przykład bindingu overlayu | +|---|---|---|---| +| `present_user_gate` | control-flow/safety | zatrzymuje fazę, prezentuje dokładne opcje, zwraca jedną decyzję | native user-input UI albo host-specific blocking protocol | +| `delegate_role` | capability | uruchamia rolę z przekazanym context i ograniczeniami read/write | native subagent schema lub udokumentowany inline fallback | +| `persist_before_continue` | persistence | terminalny record jest trwały przed kolejną fazą | portable runtime + host invocation wrapper | +| `continue_phase` | control-flow | idempotentna kontynuacja tylko po ważnej decyzji | host hook/command/binding do shared runnera | +| `enforce_safety_hook` | safety | blokuje denylisted mutation przed wykonaniem | native hook event i matcher | +| `report_progress` | capability | pokazuje status bez zmiany source of truth | native plan/progress surface albo jawny no-op | +| `resolve_project_instructions` | safety/context | ładuje właściwe instrukcje przed pracą | host discovery rule/manifest | + +Minimalny wpis `common/primitives.yml` opisuje invariant, nie składnię hosta: + +```yaml +- id: present_user_gate + class: control-flow + required_effect: block_until_one_exact_option_is_selected + failure_policy: fail_closed +- id: search_repository + class: ordinary + binding: harness_owned +``` + +Nowy primitive jest dopuszczalny, gdy ta sama różnica semantyczna wystąpiła w co najmniej dwóch workflow lub gdy pojedyncza operacja chroni safety/persistence invariant. To ogranicza ryzyko zbudowania pełnego DSL, zgodnie z decyzją 1A ([solution convergence](solution-exploration.md#2-obszar-decyzyjny-1--głębokość-reprezentacji-kanonicznej--ir)). + +## 6. Host Overlay Contract + +Każdy `hosts//overlay.yml` przechodzi wspólny schema i ma następujący kontrakt: + +```yaml +schema_version: 1 +host_id: codex +overlay_version: 1 +supported_source_version: ">=3.0.0 <4" + +layout: + managed_root: ".codex/plugins/maister" + copy_common: + - from: common/skills + to: skills + - from: common/runtime + to: runtime + overlay_assets: + - from: hosts/codex/agents + to: agents + +capabilities: + present_user_gate: + class: semantic + binding: hooks/user-gate.md + evidence_required: E5 + compatible_fingerprints: ["sha256:..."] + plugin_layout: + class: packaging + binding: manifests/plugin.json + evidence_required: E2 + +settings: + - id: advisor_agent + format: toml + destination: ".codex/agents/advisor.toml" + ownership: whole_file + source: settings/advisor.toml + +validation: + required_paths: [skills, agents] + forbidden_vocabulary: ["AskUserQuestion", "Task tool"] +``` + +Kontrakt wymaga: + +- jawnej allowlisty target paths; żaden wpis nie może wyjść poza root; +- braku kolizji między `copy_common` i `overlay_assets`, chyba że schema wskazuje dozwolony `replace` dla host-owned path; +- bindingu albo jawnego `unsupported` dla każdego wymaganego semantic primitive; +- klasy `semantic` albo `packaging` dla każdej capability; +- wskazania evidence target i ostatnio potwierdzonego fingerprint/version; +- kompletnego inventory agents, commands, hooks, manifests i settings wymaganych przez host; +- host contract tests w `hosts//tests`. + +Overlay jest małym, repo-owned modułem. Nie ma renderera prozy ani templates generujących jego zawartość w czasie instalacji. Jeśli dwa hosty mają identyczny plik, mogą korzystać ze wspólnego assetu tylko wtedy, gdy semantyka i format są rzeczywiście wspólne; nie tworzymy abstrakcji wyłącznie dla kilku podobnych linii. + +## 7. Custom installer + +### 7.1 CLI + +```text +maister install --target codex|cursor|kiro-cli [--source PATH|GH_URL] [--ref TAG_OR_SHA] + [--scope user|project] [--dest PATH] [--host-version VERSION] + [--dry-run] [--json] +maister update --target HOST [--source PATH|GH_URL] [--ref TAG_OR_SHA] [--dry-run] +maister uninstall --target HOST [--scope user|project] [--dry-run] +maister rollback --target HOST [--to RECEIPT_ID] +maister verify --target HOST [--native] +maister status [--target HOST] [--json] +``` + +Domyślne źródło to bieżący local checkout. GitHub source jest pobierany do tymczasowego immutable checkoutu; `--ref` zostaje rozwiązany do commit SHA i zapisany w receipt. Installer nie korzysta z marketplace i nie utrzymuje osobnych kanałów prebuilt. + +### 7.2 Pipeline instalacji + +```text +resolve source -> load overlay -> probe host facts -> compatibility decision + -> acquire lock -> build plan -> stage copies/settings -> validate + -> backup managed state -> commit managed tree -> commit settings + -> write receipt -> switch active pointer -> cleanup + failure at any point + | + v + restore bytes + modes + topology, keep old receipt active +``` + +1. **Resolve:** waliduje target/source/ref; autodetection może zasugerować host, ale nie nadpisuje jawnego `--target`. +2. **Probe:** odczytuje host version i capability fingerprints bez mutacji. +3. **Compatibility:** semantic unknown/incompatible kończy się przed staging; packaging-only unknown może przejść jako `provisional`. +4. **Lock:** per `{target, scope, destination}` zapobiega równoległym mutacjom. +5. **Plan:** wylicza pełne copy operations, settings mutations, ownership i expected hashes. +6. **Stage:** kopiuje wspólną warstwę i overlay do pustego katalogu na tym samym filesystemie co destination. +7. **Validate:** schema, inventory, referencje, vocabulary, permissions, path containment, deterministic hash i installed-path canary. +8. **Backup:** zachowuje wszystkie zarządzane pliki, współdzielone config bytes, modes, symlinks i directory topology. +9. **Commit:** rename managed tree, potem kontrolowane atomic writes settings; receipt pozostaje pending. +10. **Finalize:** zapisuje immutable receipt i atomowo przełącza active pointer dopiero po sukcesie wszystkich mutacji. +11. **Rollback:** przy błędzie odtwarza pełny snapshot i poprzedni active receipt; recovery może dokończyć rollback po przerwaniu procesu. + +### 7.3 Receipt i stan transakcji + +Receipt nie zastępuje `orchestrator-state.yml`; opisuje wyłącznie instalację: + +```json +{ + "receipt_version": 1, + "id": "2026-07-14T...-codex-", + "status": "active", + "target": "codex", + "scope": "project", + "source": {"kind":"github","url":"...","commit":""}, + "versions": {"maister":"3.0.0","overlay":1,"host":"..."}, + "compatibility": {"status":"supported","capabilities":[]}, + "managed_tree": {"root":"...","files":[{"path":"...","sha256":"...","mode":"..."}]}, + "settings_mutations": [{"path":"...","owned_keys":["..."],"before_sha256":"...","after_sha256":"..."}], + "previous_receipt_id": "...", + "evidence": [] +} +``` + +Stan przejściowy (`prepared`, `committing`, `rolling_back`) żyje w journalu obok receipt store. Po restarcie installer najpierw odzyskuje niedokończoną transakcję, a dopiero potem przyjmuje nowe polecenie. + +## 8. Własność i merge ustawień + +Każda mutacja ustawień deklaruje jedną z dwóch polityk: + +1. `whole_file` — Maister jest wyłącznym właścicielem pliku w dedykowanej ścieżce; update może go zastąpić atomowo. +2. `managed_keys` — plik jest współdzielony; overlay deklaruje dokładne JSON/TOML/YAML paths, a installer zmienia tylko te klucze. + +Reguły: + +- brak niejawnego deep merge i brak tekstowych `sed` na configu; +- parse -> validate -> mutate allowlisted keys -> serialize deterministycznie do temp -> atomic rename; +- konflikt z wartością użytkownika kończy się czytelnym błędem albo wymaga jawnej opcji wyboru, nigdy silent overwrite; +- receipt zapisuje owned keys oraz before/after hash; backup zachowuje oryginalne bytes, mode i symlink topology; +- uninstall usuwa tylko wartości nadal równe wartościom zarządzanym z aktywnego receipt; wykryty user drift jest raportowany i pozostawiony bez zmian; +- update liczy plan względem aktywnego receipt i aktualnego filesystemu; nie zakłada czystego stanu. + +## 9. Przepływy lifecycle + +### Install + +- wymaga braku aktywnego receipt albo jawnego `update`; +- tworzy pełny staging i nie dotyka destination przed przejściem walidacji; +- commit kończy się jednym aktywnym receipt lub pełnym rollbackiem. + +### Update + +- sprawdza integralność aktualnie zarządzanych plików i user drift; +- składa nowy staging od zera z nowego immutable source; +- zachowuje poprzedni receipt i backup jako bezpośredni rollback target; +- nie wykonuje in-place patchowania generic skills. + +### Uninstall + +- usuwa wyłącznie pliki/rooty i managed settings wskazane przez aktywny receipt; +- zachowuje zmodyfikowane przez użytkownika elementy, zgłasza conflict i nie usuwa parent directory, jeśli nie jest puste; +- tworzy uninstall receipt, aby operacja była audytowalna i odwracalna do czasu cleanup policy. + +### Rollback + +- domyślnie wraca do `previous_receipt_id`; opcjonalnie do jawnego receipt zgodnego z tym samym target/scope; +- przywraca bytes, modes, symlinks, directory topology i settings snapshot; +- po weryfikacji atomowo przełącza active pointer; nie rekonstruuje starej instalacji z aktualnego source. + +## 10. Compatibility i evidence + +Capability record rozdziela semantykę od packagingu: + +```yaml +host: cursor +capability: present_user_gate +class: semantic +host_version: "x.y.z" +overlay_version: 1 +fingerprint: "sha256:..." +evidence_level: E5 +status: passed +scenario: blocking-exact-options +timestamp: "..." +target: test-host-smoke-cursor +``` + +Polityka: + +| Stan | Semantic/safety | Packaging-only | +|---|---|---| +| known fingerprint + wymagany evidence passed | `supported` | `supported` | +| unknown host version, fingerprint unchanged | dozwolone tylko jeśli kontrakt jawnie uznaje fingerprint za wystarczający | `provisional` po E1/E2/E4 | +| fingerprint changed lub brak wymaganego bindingu | fail-closed | fail, jeśli validation nie przechodzi; inaczej `provisional` | +| runtime probe niedostępny | `unavailable`, nigdy pass; zgodnie z wymaganym progiem może blokować | nie podnosi ponad E4 | + +Nie ma globalnego `--force` omijającego safety invariants. Ewentualny override jest per packaging capability, zapisany w receipt i niedostępny dla denylisted semantic primitives. Badanie wykazało, że globalny boolean capability ukrywa wersję, scenariusz i świeżość, dlatego record musi pozostać wielowymiarowy ([test assurance findings](../analysis/findings/test-assurance-runtime-gap.md)). + +## 11. Walidacja i macierz testów + +### 11.1 Testowane raz dla common core + +- schema/state repository oraz byte-exact transactional rejection; +- gate engine, denylist, Advisor/Arbiter provenance i idempotency; +- continuation/outbox/reclaim/acknowledgement; +- generic skill inventory, references i forbidden host vocabulary; +- report/dashboard projections i installed-path portable runtime canary; +- failure injection wspólnych utilities. + +### 11.2 Testowane per host overlay + +- `overlay.yml` schema, required inventory i referential integrity; +- agents/commands/hooks/manifests/settings native syntax; +- kompletność semantic primitive bindings i unsupported fallbacks; +- brak foreign-host vocabulary; +- deterministic `common + overlay` assembly; +- install/update/uninstall/rollback w izolowanym root; +- host discovery E5 oraz krytyczne scenariusze E6, gdy runtime jest dostępny. + +| Target | Zakres | Częstotliwość | Dowód | +|---|---|---|---| +| `test-core` | pełny portable core | każdy PR | E3 | +| `test-generic-skills` | inventory, links, neutral vocabulary | każdy PR | E1/E3 | +| `test-overlay HOST` | schema/native assets/bindings | każdy PR, 3 hosty | E1 | +| `test-assembly HOST` | determinism, hashes, installed canary | każdy PR, 3 hosty | E2/E3 | +| `test-installer HOST` | lifecycle + injected rollback | każdy PR, 3 hosty | E4 | +| `test-host-smoke HOST` | discovery + sentinel | required, jeśli środowisko hosta jest dostępne; inaczej jawne 77 | E5 | +| `test-host-e2e HOST SCENARIO` | gate/delegation/continuation | release/scheduled | E6 | +| `validate-evidence` | status, freshness, version, target | każdy PR/release | governance | + +`exit 77` jest `unavailable`, nie zielonym skipem. Claim supportu jest per capability/scenario, nie per samą nazwę hosta. Obecne testy pokazują realne, lecz nierówne poziomy host evidence, więc migracja nie może sprowadzić ich do jednego booleanu ([current evidence matrix](../analysis/findings/test-assurance-runtime-gap.md)). + +## 12. Migracja w jednym zadaniu implementacyjnym + +Migracja zachowuje legacy tylko jako tymczasowy oracle na branchu. Końcowy stan zadania nie zawiera dual path. + +### M0 — baseline + +- zinwentaryzować exact legacy outputs, testy, docs, CI i install paths; +- zapisać semantic manifest każdego wspieranego docelowo hosta; +- uruchomić obecne build/validate i zachować wyniki jako porównanie. + +### M1 — neutral common core + +- przenieść generic skills/runtime/references/assets do neutralnej własności; +- usunąć Claude-native vocabulary z generic layer; +- dodać minimalny primitive registry i common core suite. + +### M2 — repo-owned overlays + +- utworzyć `hosts/codex`, `hosts/cursor`, `hosts/kiro-cli` z pełnym native inventory; +- przenieść host-specific agents, commands, hooks, manifests i settings bez generowania; +- dodać overlay schema oraz parametryczny contract harness. + +### M3 — custom installer + +- wdrożyć local/GitHub source resolution, copy/merge assembly, validation, receipt, lifecycle i recovery; +- uruchomić E4 dla każdego z trzech hostów z failure injection; +- sprawdzić installed-path canaries. + +### M4 — shadow comparison + +- dla Codex, Cursor i Kiro złożyć nowy tree i porównać z legacy generated tree; +- klasyfikować różnice jako expected architectural change albo defect; +- wymagać zero nierozstrzygniętych różnic w manifestach, referencjach, executable bits, hooks i semantic primitives. + +### M5 — deletion before completion + +- usunąć `plugins/maister-codex`, `plugins/maister-cursor`, `plugins/maister-kiro` oraz stare build adapters, generatory i drift jobs; +- usunąć canonical Claude plugin, Claude manifest/hooks/commands/agents, `claude.e2e.sh`, capability entries, dokumentację i vocabulary; +- przepiąć CI, Makefile, release/docs na nowy installer i trzy hosty; +- wykonać finalne testy na czystym checkout i potwierdzić czysty `git status`. + +## 13. Definition of Done + +Zadanie implementacyjne jest ukończone tylko wtedy, gdy wszystkie warunki są spełnione: + +1. `common/skills` jest jedyną utrzymywaną kopią generic skills i installer kopiuje ją byte-for-byte dla Codex, Cursor i Kiro CLI. +2. Generic layer nie zawiera Claude-native ani foreign-host tool vocabulary; ordinary operations pozostają harness-owned. +3. Każdy wymagany semantic primitive ma binding lub jawny, walidowany unsupported fallback w każdym overlayu. +4. `hosts/codex`, `hosts/cursor` i `hosts/kiro-cli` zawierają jawne agents, commands, hooks, manifests, settings oraz host contract tests. +5. Installer działa z lokalnego checkoutu i GitHub source resolved do SHA; nie korzysta z marketplace ani runtime prompt generation. +6. Fresh install, reinstall policy, update, uninstall i rollback przechodzą dla wszystkich trzech hostów w izolowanych rootach. +7. Invalid input i injected failure pozostawiają bytes, modes, symlinks i directory topology bez zmian albo przywrócone byte-exact. +8. Settings merge modyfikuje wyłącznie zadeklarowane managed keys; user drift jest zachowany i raportowany. +9. Compatibility records rozróżniają semantic/safety od packaging; semantic unknown fail-closed, packaging provisional jest audytowalne. +10. Pełny common-core E3 działa raz; per-host E1/E2/E4 oraz dostępne E5/E6 emitują wersjonowane evidence records, a `unavailable` nie jest pass. +11. Shadow comparison ma zero niewyjaśnionych różnic dla Codex, Cursor i Kiro CLI. +12. Stare build adapters, transform scripts, generated drift jobs i kompletne generated trees nie istnieją w końcowym repo. +13. Claude Code nie istnieje w supported targets, installerze, overlays, manifests, commands, agents, hooks, tests, capability matrix, docs ani generic vocabulary. +14. Repo docs i `.maister/docs/project/{vision,architecture,tech-stack,roadmap}.md` opisują nową architekturę i tylko trzy wspierane hosty. +15. Czysty checkout potrafi zainstalować, zweryfikować i odinstalować każdy target bez modyfikowania repo; końcowy `git status` jest czysty. + +## 14. Ryzyka i obserwowalność + +| Ryzyko | Mitigacja | Sygnał | +|---|---|---| +| semantic drift w generic prose | forbidden vocabulary + primitive review + scenario contracts | diff inventory i failed semantic canary | +| partial install/config corruption | staging, journal, backups, atomic writes, injected failures | transaction id, recovery status, before/after hashes | +| overlay niekompletny po zmianie hosta | schema + capability fingerprint + fail-closed | compatibility decision per capability | +| installer usuwa dane użytkownika | receipt ownership + managed-key comparison | drift/conflict report przed commit/uninstall | +| dual path pozostaje na stałe | M5 i DoD wymagają fizycznego usunięcia legacy | repository inventory check | +| fałszywie zielone host tests | structured E0–E6 evidence, `77=unavailable` | dashboard/report by status and freshness | + +Każde polecenie installera z `--json` emituje `operation_id`, `target`, `source_commit`, `phase`, `compatibility_status`, `changed_paths`, `receipt_id`, `rollback_performed` i listę evidence. Logi nie zawierają credentials ani pełnej treści ustawień. Domyślny human output podaje następny krok naprawczy oraz ścieżkę receipt/journalu. + +## 15. Integracja z istniejącym systemem + +- `orchestrator-state.yml` pozostaje jedynym źródłem prawdy workflow; receipt jest osobnym stanem instalacyjnym. +- Istniejące ESM state/gate/continuation stają się `common/runtime` i zachowują swoje executable contracts. +- Obecne Cursor/Kiro/Codex host assets są wejściem do jawnych overlayów, nie szablonami generatora. +- Obecne generated trees są wyłącznie baseline M0/M4 i są usuwane w M5. +- Make/CI zostają uproszczone do core + parametrycznych overlay/installer tests oraz oddzielnych native probes. + +## 16. Ślad decyzji i dowodów + +Siedem decyzji architektonicznych zapisano w [decision-log.md](decision-log.md): boundary reprezentacji, overlay/installer, task-scoped legacy removal, capability-sensitive compatibility, usunięcie Claude, transactional settings ownership oraz evidence boundary. Decyzje 1A, 2D, 3D, 4C i 5D pochodzą z potwierdzonej konwergencji zapisanej w `orchestrator-state.yml`; szczegółowe pierwotne alternatywy są w [solution-exploration.md](solution-exploration.md). + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/research-report.html b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/research-report.html new file mode 100644 index 00000000..d023918c --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/research-report.html @@ -0,0 +1,110 @@ + + + + +Raport badawczy — platformowo niezależny Maister + + + + +
Research report

Jedno, platformowo niezależne rozwiązanie Maister

Wygenerowano 2026-07-14 · badanie mieszane · evidence E0–E6

+
4warianty
3strumienie źródeł
4hosty
Highkierunek
+

TL;DR

Rekomenduję jedno źródło zachowania i jeden bundle, z którego maister install --target <host> tworzy natywny pakiet wybranego narzędzia. Rdzeń state/gates/continuation testujemy raz; per host zostają adapter, materializer, install i runtime probes. Nie rekomenduję jednego identycznego installed tree ani przeniesienia obecnych regex buildów 1:1 do instalatora. Claude bez runtime może dojść do E4, ale E5/E6 pozostają niezweryfikowane.

+

Key Decisions

  • Portable behavior/runtime core + typed host contracts + install-time materializer.
  • Jedno źródło, jeden testowalny core i jeden bundle — nie jeden host runtime.
  • Neutralny IR rozwijany ewolucyjnie dla gates/roles/hooks/capabilities.
  • Staging, validation, receipt, atomic swap i byte-exact rollback.
  • Generated target trees usuwane dopiero po parity i stabilnych release artifacts.
+

Open Questions / Risks

  • Semantyczny dryf gate/delegation/progress ukryty w transformacjach prozy.
  • Ruchome contracts Cursor i Kiro CLI/IDE.
  • Ryzyko awarii install-time compilation na maszynie użytkownika.
  • Claude E5/E6 wymaga rzeczywistej binarki, auth, wersji i scenariusza.
  • Współistnienie common installera z native marketplaces.
+ + +
+ + +

Dlaczego obecny model jest kosztowny

Claude-native canonical

Źródło nie jest neutralne; adaptery muszą przepisywać vocabulary i host primitives.

canonical-core-boundary.md:33-55
~320 substytucji

1 780 linii adapterów + 160 linii generatora Kiro; największe ryzyko leży w prozie.

canonical-core-boundary.md:101-112
610 plików projekcji

Około 5,08 MB wersjonowanego outputu bez niezależnego dowodu behavior.

canonical-core-boundary.md:125-133
Test matrix ≠ assurance

Byte-identical runner jest testowany cztery razy, PR CI nie wykonuje pełnego validate.

test-assurance-runtime-gap.md:48-58,125-134
+ +

Porównanie wariantów

WariantWynikZaletaProblemWerdykt
Build-time variants15/25niski koszt przejścia, diffduplikacja i regex couplingbaza migracji
Installer 1:113/25prosty --targetregexy trafiają do użytkownikaodrzucić
Portable core + typed adapters23/25test core raz, mała macierz hostównowy kontraktwybrać
Pełny neutralny IR20/25silna separacjawysoki koszt, over-designselektywnie
Podstawa scorecard

Inventory transformacji: analysis/findings/canonical-core-boundary.md:83-133; host contracts: analysis/findings/host-contracts-installation.md:29-158; assurance: analysis/findings/test-assurance-runtime-gap.md:150-250.

+ +

Architektura docelowa

maister-dist/
+  core/
+    workflows/    # neutral behavior + primitives
+    runtime/      # state/gate/continuation ESM
+    roles/        # role intent
+    assets/
+  contracts/      # host + capability schemas
+  adapters/
+    claude/ codex/ cursor/ kiro-cli/
+  installer/
+    materialize validate commit rollback
Portable core

Fazy, durable state, gates, continuation, safety, artifacts i bodies skills. Pięć ESM modules jest już byte-identical i executable-tested.

canonical-core-boundary.md:57-81
Host Contract

Host/version/capabilities, layout, mappings, emitters, fallbacks i native evidence target. Nieznane capability: fail-closed.

Structural materializer

Generuje manifesty, layouts, agents, hooks, MCP i help z pól/templates — nie z dowolnej prozy.

Bundle + prebuilt

Jeden compiler path tworzy local install i CI marketplace artifacts.

+

Common vs adapter-required

CommonAdapter-required
workflow invariants, state, gate semanticsmanifest, catalog, discovery
portable ESM helpersinvocation i command/skill mapping
skill bodies, assets, role intentagents, trust, tools, user gates
neutral MCP/hook intenthooks schema/env, MCP placement/security

Źródła oficjalne: Claude, Codex, Cursor, Kiro CLI. Dokumentują kontrakty, nie runtime Maister.

+ +

Kontrakt install --target

maister install --target claude|codex|cursor|kiro-cli
+  [--scope user|project|local] [--dest PATH]
+  [--with-mcp NAME] [--host-version VERSION] [--offline]
  1. Resolve: target jawny; autodetection tylko potwierdza.
  2. Type-check: descriptor/schema i compatibility policy.
  3. Materialize: pełne native tree w pustym staging.
  4. Validate: manifest, inventory, referencje, paths, permissions, forbidden vocabulary, semantic golden, canary.
  5. Receipt: source/adapter/contract/host version, options, destination, hashes.
  6. Atomic commit: swap managed tree i transakcyjne config mutations.
  7. Rollback: byte-exact tree, receipt, modes, symlinks i config.
  8. Verify: maszynowy evidence record bez sztucznego podnoszenia E4 do E5.
+ +

Testowanie

Raz na core
  • state schema/repository
  • gate policy/denylist
  • continuation/idempotency
  • reports/invariants
  • failure injection
Per host
  • E1 adapter contract
  • E2 materializer + golden
  • E4 install/rollback
  • E5 discovery sentinel
  • E6 scenario E2E
TargetCzęstotliwość
test-corekażdy PR
test-materializer, test-adapter-contract HOST, test-install HOSTkażdy PR
test-host-smoke HOSTnightly/manual
test-host-e2e HOST SCENARIOscheduled/release

Każdy wynik: {host, capability, host_version, adapter_version, evidence_level, status, scenario, timestamp, target}. exit 77 oznacza unavailable, nie pass. Dowód: test-assurance-runtime-gap.md:60-95,241-250.

+ +

Claude Code: evidence ceiling

W badaniu nie było runtime claude. Oficjalny tryb claude -p jest kontraktem produktu, nie dowodem uruchomienia Maister.

DowódAktualnieBez runtime
E1 static/schemataktak
E2 materializationprzyszły adaptertak
E3 shared coretaktak
E4 install/rollbackbraktak, cel
E5 discoverybraknie
E6 runtime scenariounavailable 77nie

Uczciwy claim docelowy bez runtime: Claude host-specific E4; shared-core E3; E5/E6 unavailable. Nie „pełna parity”. test-assurance-runtime-gap.md:150-175.

+ +

Migracja i rollback

EtapExit criterionRollback
M0 Baselinetest-core w PR, evidence inventorystare CI
M1 Host Contract v1E1 dla 4 targetów, typed primitiveslegacy text/builds
M2 Shadow materializerdeterministyczna semantic paritywyłącz shadow
M3 Opt-in installerE4 × 4, byte-exact injected rollbacklegacy path + receipt
M4 Jedna release path2 stabilne, odtwarzalne releaserepublish legacy artifact
M5 Usuń variantsoffline rebuild, audit diff, E1–E4odtwórz z tagu/bundle
+ +

Explicit non-goals

  • Jeden identyczny installed tree lub wspólny host runtime.
  • Pełna parity bez host-native evidence.
  • Regexowe emulowanie brakujących capabilities.
  • Pełny DSL/IR jako warunek startu.
  • Usunięcie wszystkich testów per platform.
+ +

Decyzje do konwergencji

  1. Minimalne typed primitives + templates (rekomendowane) czy pełny IR od początku?
  2. CI-prebuilt marketplace artifacts (rekomendowane) czy compiler zawsze u użytkownika?
  3. Usunięcie generated trees po dwóch stabilnych release (rekomendowane) czy wcześniej?
  4. Nieznana host version: fail dla semantic mapping i warning dla packaging-only (rekomendowane)?
  5. Claude E4 jako release gate z jawnym E5/E6 unavailable (rekomendowane) czy blokada release?
+ +

Confidence

High

Portable core, różne installed outputs, jeden bundle + target materialization, Claude evidence ceiling.

Medium

Descriptor/IR API, marketplace atomicity, moment usunięcia generated trees.

Unknown

Pełna runtime parity Claude bez realnego E5/E6.

+
+ + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/research-report.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/research-report.md new file mode 100644 index 00000000..167dc5d6 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/research-report.md @@ -0,0 +1,181 @@ +# Raport badawczy: jedno, platformowo niezależne rozwiązanie Maister + +## TL;DR +Rekomenduję jedno źródło zachowania i jeden bundle, z którego `maister install --target ` tworzy natywny pakiet wybranego narzędzia. +Rdzeń state/gates/continuation testujemy raz; per host zostają tylko adapter, materializer, install i runtime probes. +Nie rekomenduję jednego identycznego installed tree ani prostego przeniesienia obecnych regex buildów do instalatora. +Claude Code bez runtime może osiągnąć E4 instalacji, ale discovery i wykonanie E5/E6 pozostają jawnie niezweryfikowane. + +## Key Decisions +- Docelowo: portable behavior/runtime core + typed host contracts + install-time materializer. +- „Jedno rozwiązanie” oznacza jedno źródło, jeden testowalny core i jeden dystrybuowany bundle; nie oznacza jednego host runtime. +- Neutralny IR rozwijać ewolucyjnie dla gates/roles/hooks/capabilities, zamiast budować pełny DSL przed migracją. +- Instalacja musi używać staging, validation, receipt, atomic swap i byte-exact rollback. +- Commitowane target trees usunąć dopiero po potwierdzonej parity i stabilnych release artifacts. + +## Open Questions / Risks +- Semantyka gate/delegation/progress może dryfować mimo poprawnego layoutu; globalne substytucje tekstu są głównym źródłem ryzyka. +- Cursor i Kiro contracts są ruchome, a Kiro CLI/IDE wymagają osobnych, precyzyjnie nazwanych targetów. +- Compiler na maszynie użytkownika zwiększa koszt awarii, jeśli nie jest transakcyjny i odtwarzalny offline. +- Claude Code E5/E6 nie może być deklarowane bez realnej binarki, auth, wersji i wykonanego scenariusza. +- Native marketplaces mogą wymagać prebuilt artifacts; wspólny installer powinien z nimi współistnieć, nie koniecznie je zastępować. + +## Odpowiedź wprost + +Tak — projekt można znacząco uprościć i uniezależnić od narzędzia. Najlepszy model to: + +```text +jedno canonical behavior/runtime core + + +małe, wersjonowane adaptery hostów + + +jeden installer/materializer --target + = +różne, natywne pakiety instalacyjne +``` + +Nie da się bezpiecznie osiągnąć pełnej niezależności jako jednego identycznego katalogu. Hosty wymagają różnych manifestów, discovery, agents, hooks, MCP placement i sposobów interakcji (`analysis/findings/host-contracts-installation.md:29-63`). Niezależność powinna oznaczać wspólne **zachowanie i źródło**, nie identyczną fizyczną integrację. + +## Dlaczego obecny model jest kosztowny + +- Canonical source jest Claude-native, nie neutralny (`analysis/findings/canonical-core-boundary.md:33-55`). +- Trzy adaptery mają łącznie 1 780 linii, generator Kiro kolejne 160, a inventory wykazał około 320 tekstowych substytucji (`analysis/findings/canonical-core-boundary.md:101-112`). +- Cztery drzewa pluginów to 610 plików i ok. 5,08 MB wersjonowanych projekcji; nie są niezależnymi implementacjami behavior (`analysis/findings/canonical-core-boundary.md:125-133`). +- Pełny runner contract jest wykonywany cztery razy dla byte-identical copies, mimo że edge cases mogą działać raz na core (`analysis/findings/test-assurance-runtime-gap.md:48-58`). +- PR CI sprawdza głównie rebuild/diff, a pełne `make validate` dopiero release (`analysis/findings/test-assurance-runtime-gap.md:125-134`). + +## Warianty + +| Wariant | Wynik /25 | Największa zaleta | Główny problem | Rekomendacja | +|---|---:|---|---|---| +| Build-time generated variants | 15 | niski koszt przejścia, czytelny diff | duplikacja i regex coupling | baza migracji | +| Install-time compiler 1:1 | 13 | prosty `--target` | przenosi kruche regexy do użytkownika | odrzucić | +| Portable core + typed adapters | **23** | test core raz, minimalna macierz hostów | wymaga nowego kontraktu | **wybrać** | +| Pełny neutralny IR | 20 | najsilniejsza separacja | wysoki koszt i ryzyko over-design | stosować selektywnie | + +Scorecard opiera się na wspólnych kryteriach planu oraz triangulacji transformacji, host contracts i assurance (`analysis/findings/canonical-core-boundary.md:83-133`; `analysis/findings/host-contracts-installation.md:29-158`; `analysis/findings/test-assurance-runtime-gap.md:150-250`). + +## Architektura docelowa + +### 1. Portable behavior/runtime core + +Zawiera fazy, state schema/repository, gates, safety invariants, continuation, role intents, artifact contracts i wspólne bodies skills. Pięć modułów ESM już jest byte-identical w targetach i ma executable contracts, więc to nie jest czysto teoretyczny kierunek (`analysis/findings/canonical-core-boundary.md:57-81`). + +### 2. Versioned Host Contract + +Descriptor definiuje `host_id`, zakres wersji, capabilities, layout, invocation mapping, agent/hook emitters, fallbacki i native evidence target. Nieznane capabilities są fail-closed. + +### 3. Typed/structural materializer + +Materializer generuje manifest, layout, namespaces, agent MD/TOML/JSON, hooks, MCP placement i help. Działa na jawnych fields/primitives/templates, a nie na dowolnej prozie. + +### 4. Jeden bundle i prebuilt artifacts + +Bundle zawiera core, adapters, schemas, assets, installer i golden fixtures. CI materializuje wszystkie targety i może publikować prebuilt marketplace artifacts z dokładnie tego samego compiler path. + +## Co pozostaje platformowe + +| Common | Adapter-required | +|---|---| +| workflow invariants, durable state, gate semantics | manifest, catalog, discovery root | +| portable ESM runtime/helpers | invocation names i commands/skills collapse | +| skill bodies, assets, references | agent schema, tools, trust, concurrency | +| role intent i hook intent | user gate, progress, planning, headless policy | +| neutral MCP server data bez credentials | hook schema/env, MCP placement/security | +| evidence record schema | native marketplace, install scope, session UX | + +Oficjalne kontrakty potwierdzają różne entry points: [Claude plugins reference](https://code.claude.com/docs/en/plugins-reference), [Codex build plugins](https://learn.chatgpt.com/docs/build-plugins), [Cursor plugins](https://cursor.com/changelog/2-5), [Kiro custom agents](https://kiro.dev/docs/cli/custom-agents/configuration-reference/). Są to dowody kontraktu, nie dowody udanego Maister runtime. + +## Kontrakt instalacji + +```text +maister install --target claude|codex|cursor|kiro-cli + [--scope user|project|local] + [--dest PATH] + [--with-mcp NAME] + [--host-version VERSION] + [--offline] +``` + +1. Jawnie wybierz target; autodetection jedynie potwierdza. +2. Zweryfikuj descriptor/schema i compatibility policy. +3. Materializuj do pustego staging directory. +4. Sprawdź manifest, inventory, referencje, paths, permissions, forbidden vocabulary, semantic golden i installed-path canary. +5. Utwórz receipt: source/adapter/contract/host version, options, destination i hashes. +6. Zrób atomic swap managed tree; config mutations wykonaj transakcyjnie. +7. Przy failure przywróć tree, receipt, modes, symlinks i config byte-exact. +8. Update używa tego samego compile; uninstall usuwa wyłącznie managed files z receipt. + +Obecne instalatory Cursor i Kiro czyszczą destination przed copy, więc nie spełniają takiego rollback contract (`analysis/findings/test-assurance-runtime-gap.md:136-148`). + +## Testowanie: co raz, co per host + +### Raz na każdą zmianę core + +- state schema/repository, transactional rejection; +- gate evaluator/policy/denylist; +- continuation/outbox/idempotency/reclaim; +- report projection i portable workflow invariants; +- failure injection. + +### Dla każdego hosta + +- E1 descriptor/adapter contract; +- E2 deterministic materialization + semantic golden + canary; +- E4 isolated install/update/uninstall/rollback; +- E5 prawdziwe discovery + sentinel invocation, gdy binary/auth dostępne; +- E6 wersjonowany krytyczny scenario E2E. + +Rekomendowane targety CI: `test-core` na każdy PR; `test-materializer`, `test-adapter-contract HOST` i `test-install HOST` na każdy PR; `test-host-smoke` nightly/manual; `test-host-e2e` scheduled/release (`analysis/findings/test-assurance-runtime-gap.md:241-250`). + +## Claude Code bez runtime + +W tym badaniu `claude` nie był dostępny. Claude Code oficjalnie oferuje tryb programistyczny `claude -p` i plugin loading ([headless docs](https://code.claude.com/docs/en/headless)), ale sama dokumentacja nie jest runtime proof. + +| Dowód | Aktualnie | Możliwe bez runtime | +|---|---|---| +| E1 static/schema | tak | tak | +| E2 deterministic materialization | canonical n/a / przyszły adapter | tak | +| E3 shared core executable | tak | tak | +| E4 isolated install/rollback | brak dla Claude | **tak, cel** | +| E5 host discovery/smoke | brak | nie | +| E6 scenario runtime | `exit 77 unavailable` | nie | + +Zatem release może jawnie raportować: `Claude host-specific E4; shared-core E3; E5/E6 unavailable`. Nie może raportować „pełna parity Claude”. To ograniczenie jest dobrze zdefiniowanym evidence ceiling, nie blokadą dla całej migracji (`analysis/findings/test-assurance-runtime-gap.md:150-175`). + +## Migracja + +| Etap | Exit criterion | Rollback | +|---|---|---| +| M0 Baseline | `test-core` w PR CI, evidence inventory | powrót do dotychczasowego CI | +| M1 Host Contract v1 | E1 dla 4 targetów, pierwsze typed primitives | emituj legacy text, stare buildy aktywne | +| M2 Shadow materializer | deterministyczna semantic parity z obecnymi outputami | wyłącz shadow job | +| M3 Opt-in installer | E4 dla 4 hostów, byte-exact injected rollback | legacy install path + previous receipt | +| M4 Jedna release path | dwa stabilne release z odtwarzalnymi artifacts | republish legacy artifact | +| M5 Usuń committed variants | offline rebuild, audit diff, E1–E4 stabilne | odtwórz z bundle/tagu | + +## Explicit non-goals + +- Jeden identyczny installed tree. +- Jeden wspólny host runtime. +- Pełna parity bez host-native evidence. +- Regexowe emulowanie brakujących capabilities. +- Pełny DSL/IR jako warunek startu. +- Usunięcie wszystkich testów per platform. + +## Decyzje do konwergencji + +1. Minimalne typed primitives + templates czy pełny IR od początku? **Rekomendacja: minimalne primitives.** +2. CI-prebuilt marketplace artifacts czy compiler zawsze u użytkownika? **Rekomendacja: prebuilt z tego samego materializera.** +3. Kiedy usunąć generated trees? **Rekomendacja: po dwóch stabilnych release z parity oracle.** +4. Co robić z nieznaną wersją hosta? **Rekomendacja: fail dla semantycznych mappings, warning dla packaging-only.** +5. Czy Claude E4 wystarcza jako release gate? **Rekomendacja: tak, przy jawnym E5/E6 unavailable.** + +## Ryzyka i confidence + +- **High confidence:** portable core istnieje; installed outputs muszą być różne; jeden bundle + target materialization jest wykonalny; Claude E5/E6 jest obecnie niezweryfikowane. +- **Medium confidence:** format descriptor/IR, atomic integration z marketplaces, moment usunięcia generated trees. +- **Low/unknown:** pełna runtime parity Claude bez realnego testu. + +Najważniejsze ryzyka to semantic drift w prozie, zmienność host contracts, nietransakcyjny install i mylące zielone statusy dla testów unavailable. Każdy evidence record powinien zawierać host, capability, version, level, status, scenario, timestamp i target. + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/solution-exploration.html b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/solution-exploration.html new file mode 100644 index 00000000..82545d8a --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/solution-exploration.html @@ -0,0 +1,54 @@ + + + + +Eksploracja rozwiązania — platformowo niezależny Maister + + + + +
solution exploration

Platformowo niezależny Maister

HMW + SCAMPER · ocena z perspektyw maintainera, użytkownika, host contract, assurance i ewolucji

+
5decision areas
15alternatives
5recommended
E1–E4Claude gate
Highcore confidence
+

TL;DR

Najlepszy spójny wariant to jeden portable core i bundle, mały Host Contract oraz strukturalny materializer. Instalator materializuje lokalnie, a CI publikuje marketplace artifacts z tej samej ścieżki. Generated trees znikają po dwóch stabilnych release. Claude może być wydawany przy E4 bez runtime, jeśli E5/E6 pozostają jawnie unavailable.

Key Decisions

  • Minimalne typed primitives + templates, rozwijane ewolucyjnie.
  • Hybrydowa dystrybucja local + CI-prebuilt z jednego compilera.
  • Shadow-first removal po dwóch stabilnych release i pełnych exit criteria.
  • Unknown version: semantic fail-closed, packaging-only provisional warning.
  • Claude: E1–E4 + shared E3; E5/E6 jawnie unavailable.
+

Open Questions / Risks

  • Granica primitive/template może dryfować bez przeglądu wyjątków.
  • Marketplace może wymuszać signed/prebuilt artifacts.
  • Tekstowy diff nie dowodzi semantic parity.
  • Claude ma twardy evidence ceiling E4 bez runtime.
  • Compatibility evidence musi mieć version, scenario, timestamp i freshness.
+ + +

Ramy eksploracji

HMW: jak testować semantykę raz; przesunąć różnice do instalacji bez przenoszenia regexów; uczciwie wydać Claude bez runtime; usunąć 610 projekcji z rollbackiem.
SCAMPER: substitute regex → typed primitives; combine local/prebuilt; adapt existing trees as oracle; modify test matrix; reuse trees as rollback artifacts; eliminate repeated core tests; reverse build-time generation into install-time materialization.
+ +

1. Głębokość reprezentacji kanonicznej / IR

Decyzja ustala koszt migracji oraz to, czy projekt stworzy osobny język workflow.

+

1A · Typed primitives + templates recommended

Behavior pozostaje w Markdown/YAML/ESM. Host-sensitive gates, roles, delegation, hooks, capabilities, invocation i layout dostają walidowane pola; IR rośnie dopiero przy powtarzalnej różnicy semantycznej.

Pros
  • Najmniejsza migracja.
  • Usuwa ryzykowne globalne substytucje.
  • Wcześnie uruchamia core i adapter harness.
  • Pasuje do minimal implementation.
Cons
  • Wymaga dyscypliny granicy primitive/template.
  • Część prozy pozostaje trudno walidowalna.
  • Nowe capabilities mogą wymagać wyjątków.

E3 już istnieje dla wspólnego runtime; ryzykiem jest 20+ transformacji. Założenie: większość różnic zamyka się w primitives/templates.

+

1B · Pełny neutralny IR

Nowy schemat opisuje fazy, gates, role, artifacts i hooks; Markdown jest projekcją lub content field, a hosty mają kompletne backendy emitterów.

Pros
  • Najsilniejsza separacja.
  • Bogata walidacja i migracje schematu.
  • Potencjalnie dobre skalowanie na wiele hostów.
Cons
  • Wysoki koszt i własny DSL.
  • Podwójna migracja.
  • Proza nie mapuje się dobrze na AST.
  • Opóźnia redukcję duplikacji.

Scorecard: 20/25, medium confidence, wysokie ryzyko over-design.

+

1C · Markdown + regex/golden

Obecne skrypty pozostają, lecz dostają markery sekcji oraz większe fixtures i snapshoty. Nie powstaje Host Contract ani strukturalny model.

Pros
  • Najniższy koszt początkowy.
  • Wykorzystuje obecne narzędzia.
  • Łatwy ręczny diff.
Cons
  • Nie usuwa text coupling.
  • Snapshot nie dowodzi semantyki.
  • Słabo skaluje się z hostami.
  • Nie daje jednego bundle.

Obecny rebuild wykrywa drift, ale utrzymuje 610 projekcji.

Rekomendacja 1A: promote to primitive after repeated semantic divergence; kwartalny przegląd wyjątków.
+ +

2. Dystrybucja i miejsce materializacji

Installed trees pozostają różne; wybieramy, gdzie powstają.

+

2A · Tylko lokalny materializer

install --target tworzy, waliduje i atomowo instaluje staging tree lokalnie; marketplace ma co najwyżej bootstrap.

Pros
  • Jedno źródło i jawny target.
  • Offline po pobraniu bundle.
  • Dokładny receipt.
Cons
  • Compiler trafia do user env.
  • Błąd kompilacji jest błędem instalacji.
  • Marketplace może wymagać prebuilt.

Bez strukturalnego compiler path ten kierunek przenosi kruche regexy do użytkownika.

+

2B · Tylko CI-prebuilt

CI publikuje osobny host artifact; użytkownik pobiera gotowe drzewo, choć repo go nie commituje.

Pros
  • Małe wymagania użytkownika.
  • Signing, hashes i audit przed publikacją.
  • Błędy wykrywane w CI.
Cons
  • Osobne paczki i wybór downloadu.
  • Możliwy drift local/release.
  • Więcej release jobs.

Dobrze pasuje do marketplace, ale nie realizuje w pełni jednego bundle.

+

2C · Hybrid, same compiler path recommended

Local installer i CI-prebuild wywołują ten sam materializer z tym samym bundle. Artefakty zawierają receipt, hashes i semantyczny parity record.

Pros
  • Jedno rozwiązanie + marketplace.
  • Brak rozjazdu logiki local/prebuilt.
  • Offline i szybki install.
  • Wspólny E4 staging/rollback.
Cons
  • Dwa kanały do testowania.
  • Wymaga deterministycznego metadata.
  • Trzeba spinać wersje bundle/descriptor/compiler.

Wysoka pewność dla materializera, średnia dla integracji marketplace.

Rekomendacja 2C: local materializer jest referencją; marketplace artifact to podpisana, cache'owana projekcja z identycznym receipt.
+ +

3. Przejście i usunięcie generated trees

+

3A · Usuń natychmiast

Drzewa znikają, gdy compiler wygeneruje cztery targety; rollback używa starego tagu.

Pros
  • Natychmiast usuwa 610 plików.
  • Wymusza nowy path.
  • Prosta ownership rule.
Cons
  • Brak czasu na semantic parity.
  • Trudniejszy pierwszy rollback.
  • Ryzyko strukturalnego-only oracle.

Sprzeczne z research criterion: parity i stabilne release artifacts przed removal.

+

3B · Shadow + 2 releases recommended

Legacy i materializer działają równolegle. Removal po dwóch stabilnych release z E1, E2, E4, installed-path E3, reproducible artifact, rollback i zerem nierozwiązanych semantic exceptions.

Pros
  • Kontrolowane ryzyko.
  • Mierzalne criteria bez host runtime.
  • Byte-exact rollback.
  • Waliduje local i marketplace.
Cons
  • Tymczasowy dual path.
  • Wymaga semantic oracle.
  • Trzeba zdefiniować stable release.

Zgodne z M2 shadow → M3 opt-in → M4 two releases → M5 removal.

+

3C · Zostaw snapshots

Materializer jest główny, ale target trees nadal są commitowane i drift-checked.

Pros
  • Łatwy review outputu.
  • Obecny marketplace i rollback.
  • Mała zmiana procesu.
Cons
  • Duplikacja pozostaje.
  • Projekcja wygląda jak source.
  • Słabe skalowanie.

To obecny model i źródło zgłaszanego kosztu.

Rekomendacja 3B: po removal zachować release artifacts, receipts, semantic manifests i offline rebuild z tagu.
+ +

4. Nieznane wersje hosta

+

4A · Zawsze fail-closed

Każda wersja poza zakresem jest blokowana niezależnie od capability.

Pros
  • Prosta audytowalna reguła.
  • Brak pomylenia dowodu.
  • Chroni safety mappings.
Cons
  • Blokuje zgodne patche.
  • Wymaga szybkich adapter updates.
  • Zachęca do override.

Dobre na safety boundary, zbyt szerokie dla packaging-only.

+

4B · Zawsze warning

Instalacja postępuje po static validation, a wersja jest zapisana jako unverified.

Pros
  • Nie blokuje użytkowników.
  • Toleruje packaging additions.
  • Prosty UX.
Cons
  • Ryzyko semantic drift.
  • E1 nie wykrywa runtime zmian.
  • Słaby compatibility claim.

Globalny warning jest zbyt słaby dla gates/delegation/hooks.

+

4C · Capability-sensitive recommended

Semantic/safety capabilities są fail-closed; packaging-only może być provisional po E1/E2/E4, z ostrzeżeniem i expiring evidence.

Pros
  • Fail dokładnie na ryzykownych granicach.
  • Nie blokuje czystego packagingu.
  • Evidence per capability/version.
  • Jasna ścieżka do native probe.
Cons
  • Wymaga klasyfikacji i fingerprints.
  • Misclassification jest ryzykiem.
  • Bardziej złożony UX statusów.

Naprawia obecny globalny boolean, który ukrywa wersję, scenario i freshness.

Rekomendacja 4C: brak globalnego --force; override per capability, audytowany i niedostępny dla denylisted invariants.
+ +

5. Claude Code release assurance bez runtime

+

5A · Blokuj bez E5/E6

Każdy release wymaga Claude discovery i krytycznego E2E.

Pros
  • Najsilniejszy parity claim.
  • Wykrywa runtime regressions.
Cons
  • Obecnie blokuje wszystko.
  • Zależność od binary/auth/model.
  • Nie rozróżnia zakresu zmiany.

Repo nie ma Claude runtime; sentinel poprawnie zwraca 77.

+

5B · E1–E4 + explicit unavailable recommended

Release wymaga adapter E1, materialization E2, core E3, transactional E4 i installed canary. E5/E6 są jawnie unavailable; scheduled/manual probe dodaje wersjonowany native evidence.

Pros
  • Release bez fałszywego runtime claim.
  • Maksymalizuje testy bez hosta.
  • Precyzyjny evidence record.
  • Credentials poza zwykłym PR CI.
Cons
  • Możliwa luka między probe'ami.
  • Wymaga wielopoziomowego badge.
  • Potrzebna freshness policy.

E1–E4 są wykonalne bez runtime; E5/E6 nie są. Exit 77 nigdy nie jest pass.

+

5C · Community/canary certification

E1–E4 publikuje candidate, a zaufany zewnętrzny runner promuje go po signed E5/E6.

Pros
  • Realne E5/E6 bez centralnego runtime.
  • Candidate oddzielony od stable.
  • Skaluje się na credentialed hosty.
Cons
  • Złożony manual release.
  • Wymaga provenance/trust.
  • Asynchroniczne host versions.

Możliwe później; dziś brak trust/provenance modelu.

Rekomendacja 5B: core-only release przy E1–E4; po zmianie Claude semantic adapter compatibility jest provisional aż do świeżego E5/E6.
+ +

Spójna kombinacja: 1A + 2C + 3B + 4C + 5B

Portable Markdown/YAML/ESM core→Typed Host Contract→One structural materializer→Local install / CI prebuild→E1–E4 per host→Native E5/E6 when available
AreaChoiceMaintainerUserHostAssuranceConfidence
IR1AHighNeutralHighHighMedium-high
Distribution2CHighHighHighHighMedium-high
Removal3BMedium → highHighHighVery highMedium-high
Versions4CMediumMediumVery highVery highMedium
Claude5BHighHonest statusHighHigh within boundaryHigh
+ +

Pomysły odroczone

  • Pełny DSL/IR — dopiero gdy rejestr wyjątków pokaże potrzebę.
  • Hosted compiler — niepotrzebny dla local/offline i zwiększa trust surface.
  • Jeden identyczny installed tree — sprzeczny z kontraktami hostów.
  • Autodetection bez jawnego --target — może potwierdzać, nie wybierać.
  • Globalny --force — zbyt szeroki.
  • Community certification jako jedyny gate — ewentualne uzupełnienie.
+ +

Decisions & risks handoff

Decisions (verbatim)
  • Recommend minimal, evolutionary typed primitives plus host-aware templates instead of a full neutral IR at migration start.
  • Recommend a hybrid distribution model in which local installation and CI-prebuilt marketplace artifacts invoke the same deterministic materializer and bundle.
  • Recommend removing committed generated trees only after two consecutive stable releases satisfy E1, E2, E4, installed-path E3 canary, reproducible artifact, rollback, and zero unresolved semantic-parity exceptions for every target.
  • Recommend capability-sensitive unknown-version handling: fail closed for semantic or safety-sensitive mappings, and allow packaging-only provisional compatibility after validation with explicit warning and expiring evidence.
  • Recommend Claude Code releases use E1–E4 plus shared-core E3 as the enforceable gate, while E5/E6 remain explicitly unavailable until a versioned native probe runs.
  • Recommend the coherent architecture combination 1A + 2C + 3B + 4C + 5B.
Risks (verbatim)
  • The boundary between a typed primitive and a host-aware template can drift and become another implicit transformation layer without an exception-review policy.
  • Marketplace packaging or signing constraints may require prebuilt artifacts, so local materialization cannot be the only supported distribution channel.
  • Textual parity does not prove semantic parity; the migration oracle must validate inventory, references, descriptors, semantic goldens, and installed-path canaries.
  • Two-release shadow operation temporarily increases CI and maintenance cost and needs a precise definition of a stable release.
  • Capability classification can be wrong; misclassifying a semantic mapping as packaging-only could permit unsafe provisional compatibility.
  • Claude Code E5/E6 remain unverified without a real binary, authentication, version, and executed scenario; unavailable evidence must never be shown as passing.
  • External host documentation and marketplaces can change faster than adapter evidence, so compatibility records need version, scenario, timestamp, and freshness policy.
+ diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/solution-exploration.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/solution-exploration.md new file mode 100644 index 00000000..b2906a68 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/outputs/solution-exploration.md @@ -0,0 +1,371 @@ +# Eksploracja rozwiązania: platformowo niezależny Maister + +## TL;DR +Najbardziej spójny wariant to jeden portable core i jeden bundle, z małym wersjonowanym Host Contract oraz strukturalnym materializerem. +Instalator powinien domyślnie materializować target lokalnie, a CI ma publikować opcjonalne artefakty marketplace z dokładnie tej samej ścieżki kompilacji. +Commitowane drzewa należy usunąć dopiero po dwóch stabilnych wydaniach z deterministyczną parity, E1–E4 i odtwarzalnym rollbackiem. +Claude Code może być uczciwie wydawany przy E4 bez runtime, o ile E5/E6 pozostają jawnie `unavailable`, a okresowe zewnętrzne probe'y nie blokują zwykłego release. + +## Key Decisions +- **Rekomendacja:** minimalny, ewolucyjny IR: typed primitives + host-aware templates, rozszerzane wyłącznie dla udowodnionych różnic semantycznych. +- **Rekomendacja:** hybrydowa dystrybucja: lokalny materializer jako referencyjna ścieżka oraz CI-prebuilt marketplace artifacts z tego samego wejścia i kompilatora. +- **Rekomendacja:** shadow-first migration i usunięcie generated trees po dwóch stabilnych release oraz spełnieniu jawnej macierzy exit criteria. +- **Rekomendacja:** dwupoziomowa kompatybilność nieznanych wersji: fail-closed dla mapowań semantycznych, ostrzeżenie dla zmian packaging-only potwierdzonych walidacją. +- **Rekomendacja:** Claude release gate E1–E4 + shared E3, z E5/E6 raportowanymi jako `unavailable` i oddzielnym programem okresowych native probes. + +## Open Questions / Risks +- Granica między typed primitive a template może z czasem dryfować; potrzebny jest przegląd każdego nowego wyjątku adaptera. +- Marketplace może wymuszać podpisany lub prebuilt artefakt, więc lokalny materializer nie może być jedynym kanałem dystrybucji. +- Parity tekstowa nie dowodzi parity semantycznej; oracle musi porównywać inventory, descriptor, referencje i canary, nie tylko pełny diff. +- Brak Claude runtime pozostawia twardy evidence ceiling na E4; statusu `unavailable` nie wolno prezentować jako sukcesu. +- Nieznane wersje hostów mogą zmienić semantykę bez zmiany schematu; polityka kompatybilności wymaga wersjonowanego evidence record i daty ważności. + +## 1. Ramy eksploracji + +### Pytania HMW +- Jak moglibyśmy testować całą semantykę workflow raz, zachowując natywne kontrakty czterech hostów? +- Jak moglibyśmy przesunąć rozróżnienie hosta do instalacji bez przenoszenia kruchych transformacji tekstowych na maszynę użytkownika? +- Jak moglibyśmy wydać Claude Code uczciwie, mimo braku runtime, bez blokowania zmian wspólnego core? +- Jak moglibyśmy usunąć 610 commitowanych projekcji, zachowując audytowalność release i prosty rollback? + +### SCAMPER — użyte kierunki +- **Substitute:** zastąpić globalne `sed`/regex typed primitives i host-aware templates. +- **Combine:** połączyć lokalną instalację i prebuilt marketplace artifacts jednym deterministycznym materializerem. +- **Adapt:** wykorzystać obecne fixtures, manifesty i testy jako oracle migracji, zamiast przepisywać je od razu. +- **Modify:** zmniejszyć macierz testów do pełnego E3 raz oraz krótkich E1/E2/E4 per host. +- **Put to another use:** użyć generated trees jako tymczasowych golden fixtures i rollback artifacts. +- **Eliminate:** po okresie shadow usunąć commitowane target trees i czterokrotne uruchamianie identycznych core contracts. +- **Reverse:** zamiast generować wszystko przed release, materializować host-native tree z wersjonowanego bundle przy instalacji; CI wykonuje tę samą operację dla marketplace. + +### Pięć perspektyw oceny + +Każdy wariant oceniono jakościowo z pięciu perspektyw: **maintainer** (prostota i koszt zmian), **installer/user** (niezawodność i offline), **host contract** (natywność i kompatybilność), **assurance/release** (dowód E0–E6 i rollback) oraz **evolution** (dodawanie hostów i zmiany kontraktów). Pewność rekomendacji jest ważona jako wysoka dla granicy core/adapters/materializer i średnia dla dokładnego IR, marketplace oraz polityki wersji. + +## 2. Obszar decyzyjny 1 — głębokość reprezentacji kanonicznej / IR + +Ta decyzja określa, czy wspólne źródło będzie nadal głównie dokumentacją z lepszymi punktami rozszerzeń, czy stanie się pełnym modelem pośrednim. Ma największy wpływ na koszt migracji i ryzyko stworzenia drugiego języka workflow. + +### Alternatywa 1A — minimalne typed primitives + host-aware templates **(REKOMENDOWANA)** + +Behavior pozostaje w obecnych Markdown/YAML i przenośnych modułach ESM, lecz host-sensitive miejsca dostają jawne, walidowane pola: gate, role intent, delegation, progress, hooks, capabilities, invocation i layout. Adapter emituje natywne pliki przez małe strukturalne renderery oraz templates; IR rośnie dopiero, gdy konkretna różnica semantyczna powtórzy się w co najmniej dwóch miejscach. + +**Pros** +- Najmniejsza migracja z obecnego canonical source; zachowuje czytelność dokumentacji-as-code. +- Eliminuje najbardziej ryzykowne globalne substytucje bez projektowania pełnego DSL. +- Pozwala wcześnie uruchomić wspólny core contract i parametryczny adapter harness. +- Dobrze pasuje do zasady minimal implementation oraz istniejącego stosu Markdown/YAML/ESM. + +**Cons** +- Granica primitive/template wymaga dyscypliny i może z czasem stać się niespójna. +- Część prozy nadal pozostaje trudna do walidacji semantycznej. +- Nowa capability może początkowo wymagać kontrolowanego wyjątku adaptera. + +**Dowody / założenia:** pięć modułów runtime jest byte-identical, a wspólna semantyka gate/state/continuation ma E3; największe ryzyko stanowią ponad 20 transformacji tekstowych. Zakładamy, że większość różnic daje się zamknąć w jawnych primitives i templates bez pełnego AST. + +### Alternatywa 1B — pełny neutralny workflow IR od początku + +Wszystkie workflow, role, fazy, gates, artifacts, hooks i invocation są opisane w nowym, wersjonowanym schemacie, z którego renderowane są również ludzkie instrukcje. Markdown staje się projekcją lub polem content w IR, a każdy host implementuje kompletny backend emitera. + +**Pros** +- Najsilniejsza separacja semantyki od reprezentacji hosta. +- Umożliwia bogatą walidację, migracje schematu i narzędzia analityczne. +- Długoterminowo może uprościć dodawanie wielu kolejnych hostów. + +**Cons** +- Wysoki koszt początkowy i ryzyko zbudowania własnego języka workflow. +- Podwójna migracja: najpierw obecnych instrukcji do IR, potem adapterów do nowych emitterów. +- Proza i zachowanie modeli nie zawsze dają się sensownie sprowadzić do AST. +- Opóźnia szybkie usunięcie obecnej duplikacji. + +**Dowody / założenia:** research scorecard ocenił pełny IR na 20/25, lecz z medium confidence i wysokim ryzykiem over-design. Wariant opłaca się dopiero, jeśli typed primitives nie potrafią opisać rosnącej liczby hostów lub potrzebne są formalne transformacje całych workflow. + +### Alternatywa 1C — canonical Markdown + ulepszone regex/golden snapshots + +Zachowujemy obecny model generacji, porządkujemy skrypty transformacji, dodajemy markery sekcji i większe snapshoty/golden fixtures. Nie powstaje osobny Host Contract ani strukturalny model; bezpieczeństwo pochodzi głównie z diffów. + +**Pros** +- Najniższy koszt krótkoterminowy i minimalna zmiana narzędzi. +- Wykorzystuje istniejące skrypty i doświadczenie zespołu. +- Pełne generated diffs są łatwe do ręcznego przeglądu. + +**Cons** +- Nie usuwa podstawowego coupling do tekstu i host vocabulary. +- Snapshoty wykrywają zmianę, lecz nie dowodzą semantycznej poprawności. +- Koszt rośnie z każdym hostem i każdym nowym wyjątkiem. +- Nie realizuje celu jednego instalowanego bundle. + +**Dowody / założenia:** obecny rebuild/diff wykrywa drift, ale PR CI nie uruchamia pełnego `make validate`, a cztery drzewa mają 610 plików. To rozsądny rollback baseline, lecz słaby model docelowy. + +**Rekomendacja:** wybrać **1A**, z jawną zasadą „promote to primitive after repeated semantic divergence” i kwartalnym przeglądem wyjątków adapterów. + +## 3. Obszar decyzyjny 2 — dystrybucja i miejsce materializacji + +Host-native drzewa muszą się różnić, ale nie muszą być niezależnie utrzymywane. Decyzja dotyczy tego, czy tree powstaje na maszynie użytkownika, w CI, czy w obu miejscach z jednego deterministycznego compiler path. + +### Alternatywa 2A — lokalny materializer jako jedyna ścieżka + +Jeden bundle zawiera core, descriptors, schemas, templates i installer; `maister install --target HOST` tworzy staging tree lokalnie, waliduje i atomowo instaluje. Marketplace otrzymuje wyłącznie bootstrap lub nie jest wspierany. + +**Pros** +- Najprostszy model źródłowy i jednoznaczny wybór hosta przy instalacji. +- Działa offline po pobraniu bundle i łatwo zapisuje receipt z dokładnymi opcjami. +- Nie wymaga przechowywania prebuilt target trees w repozytorium. + +**Cons** +- Przenosi compiler i jego zależności do środowiska użytkownika. +- Awaria materializacji staje się awarią instalacji; rollback musi być perfekcyjny. +- Niektóre marketplace wymagają gotowego, podpisanego lub indeksowanego artefaktu. + +**Dowody / założenia:** install-time compiler 1:1 otrzymał 13/25, głównie przez ryzyko przeniesienia kruchych transformacji. Wariant staje się bezpieczniejszy dopiero po zastąpieniu regexów strukturalnym materializerem. + +### Alternatywa 2B — wyłącznie CI-prebuilt artifacts + +CI materializuje i publikuje osobny artefakt dla każdego hosta; użytkownik lub marketplace pobiera już gotowy tree. Repo nie przechowuje generated trees, ale release nadal ma cztery paczki. + +**Pros** +- Minimalne wymagania na maszynie użytkownika i przewidywalne marketplace integration. +- Każdy opublikowany artefakt można podpisać, zahaszować i zachować do audytu. +- Błąd compilera jest wykrywany przed publikacją, nie podczas instalacji. + +**Cons** +- Instalacja spoza marketplace nadal wymaga wyboru i pobrania odpowiedniej paczki. +- Ryzyko rozjazdu między release artifacts i lokalnym developerskim install path. +- Dodanie targetu zwiększa liczbę publikowanych artefaktów i jobs. + +**Dowody / założenia:** native marketplaces mogą wymagać prebuilt artifacts, a obecny release już publikuje platformowe warianty. Sam prebuild nie realizuje w pełni żądania jednego bundle. + +### Alternatywa 2C — hybryda: referencyjny lokalny materializer + prebuild z tego samego path **(REKOMENDOWANA)** + +Jeden wersjonowany bundle i jedna implementacja materializera są źródłem prawdy. Installer uruchamia materializer lokalnie, natomiast CI wywołuje dokładnie ten sam entry point z tym samym bundle, by stworzyć podpisane marketplace artifacts i zapisać receipt/SBOM/hash; parity test porównuje semantyczny output local vs CI. + +**Pros** +- Łączy jedno rozwiązanie i wybór targetu przy instalacji z wymaganiami marketplace. +- Jeden compiler path zapobiega rozjazdowi logiki local/prebuilt. +- Umożliwia offline install, szybki marketplace install i reprodukowalny audit. +- Staging/validation/atomic swap pozostają wspólnym kontraktem E4. + +**Cons** +- Dwa kanały dystrybucji zwiększają liczbę scenariuszy release/install. +- Wymaga deterministycznego build metadata i jednoznacznej polityki preferencji artefaktu. +- Należy pilnować identycznej wersji bundle, descriptor i materializera. + +**Dowody / założenia:** raport rekomenduje jeden bundle i prebuilt artifacts z tego samego compiler path; confidence jest wysokie dla materializera, średnie dla konkretnej integracji marketplace. Zakładamy możliwość publikowania host-specific projections bez ich commitowania. + +**Rekomendacja:** wybrać **2C**. Lokalny materializer jest referencją, a marketplace artifact jest cache'owaną, podpisaną projekcją z identycznym receipt. + +## 4. Obszar decyzyjny 3 — przejście i kryteria usunięcia generated trees + +Dzisiejsze drzewa są jednocześnie kosztem utrzymania, wizualnym diffem i awaryjnym artefaktem dystrybucyjnym. Ich usunięcie powinno być konsekwencją dowiedzionej zastępowalności, nie daty kalendarzowej. + +### Alternatywa 3A — natychmiastowe usunięcie po uruchomieniu materializera + +Gdy nowy compiler potrafi wygenerować cztery targety, commitowane drzewa znikają w tym samym wydaniu. Rollback opiera się na tagu sprzed migracji lub odtworzeniu z bundle. + +**Pros** +- Natychmiast usuwa 610 plików i drift-check overhead. +- Wymusza używanie nowej architektury bez długiego dual path. +- Upraszcza regułę własności repozytorium. + +**Cons** +- Brak czasu na wykrycie semantycznych różnic i problemów marketplace. +- Rollback podczas pierwszych wydań jest trudniejszy operacyjnie. +- Może ukryć regresje, jeśli parity oracle porównuje tylko strukturę. + +**Dowody / założenia:** obecne fixtures i target trees są wartościowym baseline; research jawnie odradza usunięcie przed potwierdzoną parity i stabilnymi release artifacts. + +### Alternatywa 3B — shadow-first, dwa stabilne release i jawne exit criteria **(REKOMENDOWANA)** + +Nowy materializer działa w shadow CI obok legacy build, a generated trees służą jako oracle oraz rollback artifact. Usunięcie następuje po dwóch kolejnych stabilnych release, gdy każdy target ma deterministic E2, adapter E1, isolated transactional E4, installed-path canary E3, reprodukowalny marketplace artifact i zero nierozwiązanych semantic parity exceptions. + +**Pros** +- Najlepszy balans między szybkim uproszczeniem i kontrolowanym ryzykiem. +- Exit criteria są mierzalne i niezależne od dostępności host runtime. +- Umożliwia byte-exact rollback i porównanie dwóch ścieżek. +- Daje czas na walidację lokalnego oraz marketplace install. + +**Cons** +- Przez co najmniej dwa release utrzymujemy dual path i podwójne CI. +- Wymaga semantic parity oracle oraz rejestru zaakceptowanych różnic. +- „Stabilny release” musi mieć precyzyjną definicję i ownera decyzji. + +**Dowody / założenia:** raport proponuje M2 shadow, M3 opt-in, M4 dwa stabilne release, M5 removal. Zakładamy, że dwa release obejmują rzeczywiste instalacje oraz brak rollback-triggering defects, nie tylko zielony pipeline. + +### Alternatywa 3C — pozostawić generated trees jako stale publikowane snapshots + +Materializer staje się główną implementacją, ale wszystkie target trees nadal są commitowane po każdym buildzie jako audytowalne snapshoty. CI wymusza brak diffu tak jak obecnie. + +**Pros** +- Najłatwiejszy ręczny review outputu i szybka inspekcja host-native plików. +- Zachowuje obecną ścieżkę marketplace i rollback. +- Niski koszt zmiany procesu release. + +**Cons** +- Nie usuwa dużej części repozytoryjnej duplikacji ani drift workflow. +- Zachęca do traktowania projekcji jako równorzędnego źródła. +- Skaluje się słabo z liczbą hostów i wersji kontraktów. + +**Dowody / założenia:** obecna architektura działa w ten sposób i daje deterministyczność, ale jest dokładnie źródłem zgłaszanego kosztu generowania/testowania wielu platform. + +**Rekomendacja:** wybrać **3B**. Po usunięciu drzew zachować release artifacts, receipts, semantyczne manifesty i możliwość offline rebuild z tagu. + +## 5. Obszar decyzyjny 4 — polityka nieznanych wersji hosta + +Hosty ewoluują niezależnie i sama zgodność schematu nie gwarantuje zgodności zachowania. Polityka musi unikać zarówno niepotrzebnego blokowania patch releases, jak i cichego uruchamiania niezweryfikowanych mapowań bramek czy delegacji. + +### Alternatywa 4A — zawsze fail-closed poza zadeklarowanym zakresem + +Installer odrzuca każdą wersję hosta spoza `min_version..max_tested_version`, niezależnie od rodzaju użytych capabilities. Użytkownik musi zaktualizować adapter lub jawnie użyć niebezpiecznego override. + +**Pros** +- Najprostsza, audytowalna reguła bezpieczeństwa. +- Nie pozwala pomylić braku dowodu z kompatybilnością. +- Chroni safety-sensitive gates, delegation i continuation. + +**Cons** +- Blokuje prawdopodobnie kompatybilne patch/minor releases. +- Wymaga bardzo szybkich aktualizacji adapterów. +- Zachęca użytkowników do globalnego override, jeśli false positives są częste. + +**Dowody / założenia:** fail-closed jest właściwy na safety boundaries, lecz wersja hosta nie zawsze koreluje ze zmianą używanego kontraktu. + +### Alternatywa 4B — zawsze warning i best-effort install + +Każda nieznana wersja otrzymuje ostrzeżenie, ale materializacja i instalacja postępują po przejściu walidacji strukturalnej. Evidence record zapisuje niezweryfikowaną wersję. + +**Pros** +- Najmniej blokuje użytkowników i nowe wydania hostów. +- Dobrze toleruje zmiany packaging-only oraz backward-compatible additions. +- Prosty UX instalacji. + +**Cons** +- Może dopuścić cichy semantic drift w gate, agent lub hook behavior. +- Static validation nie wykryje zmian runtime/discovery. +- Osłabia wiarygodność deklaracji compatibility. + +**Dowody / założenia:** dokumentacja hostów jest ruchoma, a E1/E2 nie dowodzą E5/E6. Globalny warning jest zbyt słaby dla safety-sensitive mappings. + +### Alternatywa 4C — capability-sensitive policy: semantic fail, packaging warning **(REKOMENDOWANA)** + +Host Contract klasyfikuje mapowania jako `semantic/safety-sensitive` albo `packaging-only` i zapisuje zweryfikowany zakres wersji/capability fingerprint. Nieznana wersja blokuje instalację, jeśli dotyka gates, delegation, continuation, tool trust lub hooks; dla niezmienionego packagingu może przejść z ostrzeżeniem po E1/E2/E4, tworząc `provisional` evidence record i ograniczony czas ważności. + +**Pros** +- Zachowuje fail-closed dokładnie tam, gdzie błąd zmienia bezpieczeństwo lub workflow. +- Nie blokuje bez potrzeby czysto strukturalnych patch releases. +- Łączy wersję z capability/evidence zamiast globalnego booleanu. +- Dostarcza jasny mechanizm aktualizacji confidence po native probe. + +**Cons** +- Wymaga klasyfikacji capabilities i utrzymania fingerprintów. +- Błędna klasyfikacja packaging vs semantic może być źródłem ryzyka. +- UX musi jasno wyjaśnić `supported`, `provisional` i `unavailable`. + +**Dowody / założenia:** obecny boolean capability ukrywa wersję, scenariusz i świeżość; badanie rekomenduje record `{host, capability, version, evidence_level, timestamp, target}`. Zakładamy, że adapter potrafi jawnie oznaczyć safety-sensitive mappings. + +**Rekomendacja:** wybrać **4C**, bez globalnego `--force`; ewentualny override ma być per capability, jawnie audytowany i niedostępny dla denylisted safety invariants. + +## 6. Obszar decyzyjny 5 — release assurance Claude Code bez runtime + +Brak binarki/auth nie uniemożliwia testowania wspólnego core, materializacji i instalacji, ale uniemożliwia dowód discovery oraz runtime. Decyzja dotyczy uczciwego progu wydania, nie sposobu udawania E5/E6. + +### Alternatywa 5A — blokować każdy release bez Claude E5/E6 + +Każde wydanie wieloplatformowe wymaga uruchomienia Claude host discovery i krytycznego scenariusza E2E. Brak runtime zatrzymuje release albo usuwa Claude ze wsparcia. + +**Pros** +- Najsilniejsza deklaracja parity dla każdego wydania. +- Natychmiast wykrywa host-native regressions. +- Nie dopuszcza niezweryfikowanego artefaktu Claude. + +**Cons** +- Obecnie praktycznie blokuje wszystkie release niezależnie od zakresu zmiany. +- Uzależnia wspólny produkt od zewnętrznej binarki, auth i model behavior. +- Nie rozróżnia zmian core, packaging i Claude-specific adapter. + +**Dowody / założenia:** repo nie ma Claude runtime; E5/E6 są nieosiągalne lokalnie, a obecny sentinel zwraca 77. To polityka możliwa dopiero po zapewnieniu stabilnego środowiska native evidence. + +### Alternatywa 5B — E1–E4 jako release gate, jawne unavailable E5/E6 + okresowe native probes **(REKOMENDOWANA)** + +Każdy release wymaga Claude adapter E1, deterministic materialization E2, wspólnego core E3, izolowanego transactional install/update/uninstall E4 i installed-path canary. E5/E6 są zapisywane jako `unavailable`, nigdy `passed`; niezależny scheduled/manual probe na realnym Claude zbiera wersjonowany evidence, a Claude-specific zmiany mogą wymagać takiego probe przed oznaczeniem pełnej kompatybilności. + +**Pros** +- Umożliwia rozwój i release bez fałszywego claimu runtime parity. +- Maksymalizuje testy możliwe bez hosta, w tym brakujący dziś Claude E4. +- Status evidence jest precyzyjny, scenariuszowy i audytowalny. +- Native probe można uruchomić w innym środowisku bez włączania credentials do zwykłego PR CI. + +**Cons** +- Regresja discovery/runtime może dotrzeć do użytkownika między probe'ami. +- Wymaga komunikowania różnych poziomów assurance zamiast jednego zielonego badge. +- Należy określić freshness window i zasady dla Claude-specific changes. + +**Dowody / założenia:** E1–E4 są wykonalne bez runtime; E5/E6 wymagają prawdziwego hosta. `exit 77` ma pozostać jawnym `unavailable`, a nie cichym sukcesem. + +### Alternatywa 5C — community/canary certification przed stable promotion + +CI publikuje Claude artifact jako candidate po E1–E4. Zaufany maintainer lub grupa canary uruchamia podpisany sentinel/discovery i jeden workflow scenario; dopiero ich evidence promuje artifact do stable, podczas gdy inne hosty mogą wydać się wcześniej. + +**Pros** +- Dostarcza realne E5/E6 bez centralnego runtime w projekcie. +- Oddziela publikację candidate od deklaracji stable compatibility. +- Może skalować na hosty wymagające płatnych lub interaktywnych credentials. + +**Cons** +- Złożony, częściowo manualny release i ryzyko opóźnienia Claude artifact. +- Wymaga zaufania, podpisów, provenance i ochrony przed zmanipulowanym reportem. +- Asynchroniczne wersje per host komplikują wsparcie i komunikację. + +**Dowody / założenia:** zewnętrzny probe jest technicznie możliwy, ale projekt nie ma dziś zdefiniowanego trust/provenance modelu. Ten wariant może uzupełnić 5B dla krytycznych wydań, lecz nie powinien być warunkiem startu migracji. + +**Rekomendacja:** wybrać **5B**. Dla zmian wyłącznie core release jest dozwolony przy E1–E4; dla zmian Claude semantic adapter status kompatybilności pozostaje `provisional` aż do świeżego E5/E6. + +## 7. Spójna kombinacja rekomendowana + +Rekomendacje **1A + 2C + 3B + 4C + 5B** tworzą jeden model: + +1. Canonical Markdown/YAML/ESM pozostaje jednym portable behavior core. +2. Minimalny, wersjonowany Host Contract opisuje wyłącznie realne różnice semantyczne i packagingowe. +3. Jeden strukturalny materializer tworzy target w staging; lokalny installer i CI-prebuild używają tego samego entry pointu. +4. PR CI uruchamia pełne E3 raz oraz E1/E2/E4 i installed-path canary dla każdego hosta. +5. Shadow parity wykorzystuje obecne generated trees przez dwa release, po czym projekcje znikają z repo, lecz zostają w release artifacts. +6. Unknown-version policy działa per capability; safety-sensitive semantics są fail-closed. +7. Claude wydaje się uczciwie z E1–E4, a E5/E6 pozostają widocznie `unavailable` do czasu prawdziwego probe. + +Z perspektywy pięciu interesariuszy ten zestaw ma najlepszy bilans: maintainer testuje core raz, użytkownik wybiera host przy instalacji, host zachowuje natywny layout, release ma reprodukowalny evidence chain, a nowe hosty wymagają descriptor/emittera zamiast kopii produktu. + +## 8. Porównanie rekomendacji + +| Obszar | Rekomendowany wariant | Maintainer | Installer/user | Host contract | Assurance | Evolution | Confidence | +|---|---|---|---|---|---|---|---| +| Canonical representation | 1A minimal typed primitives | wysoki | neutralny | wysoki | wysoki | wysoki | medium-high | +| Distribution | 2C hybrid same compiler path | wysoki | wysoki | wysoki | wysoki | wysoki | medium-high | +| Generated-tree removal | 3B two-release shadow | średni krótkoterminowo | wysoki | wysoki | bardzo wysoki | wysoki | medium-high | +| Unknown host versions | 4C capability-sensitive | średni | średni | bardzo wysoki | bardzo wysoki | wysoki | medium | +| Claude assurance | 5B E1–E4 + explicit unavailable | wysoki | uczciwy status | wysoki | wysoki w granicy dowodu | wysoki | high | + +## 9. Pomysły odroczone + +- Pełny neutralny DSL/IR dla wszystkich workflow — odroczyć do czasu, gdy rejestr wyjątków typed primitives pokaże mierzalną potrzebę. +- Zdalny hosted compiler/materialization service — niepotrzebny przy wymaganiu local/offline i zwiększa powierzchnię zaufania. +- Jeden identyczny installed tree dla wszystkich hostów — sprzeczny z natywnymi manifestami, discovery, agents, hooks i MCP placement. +- Automatyczny target detection bez jawnego `--target` — może potwierdzać wybór, ale nie powinien sam decydować przy wielu hostach. +- Globalny compatibility `--force` — zbyt szeroki; ewentualne override musi być per capability i audytowane. +- Community certification jako jedyny release gate — możliwy później jako uzupełnienie programu native probes. + +## Decisions (verbatim handoff) + +- Recommend minimal, evolutionary typed primitives plus host-aware templates instead of a full neutral IR at migration start. +- Recommend a hybrid distribution model in which local installation and CI-prebuilt marketplace artifacts invoke the same deterministic materializer and bundle. +- Recommend removing committed generated trees only after two consecutive stable releases satisfy E1, E2, E4, installed-path E3 canary, reproducible artifact, rollback, and zero unresolved semantic-parity exceptions for every target. +- Recommend capability-sensitive unknown-version handling: fail closed for semantic or safety-sensitive mappings, and allow packaging-only provisional compatibility after validation with explicit warning and expiring evidence. +- Recommend Claude Code releases use E1–E4 plus shared-core E3 as the enforceable gate, while E5/E6 remain explicitly unavailable until a versioned native probe runs. +- Recommend the coherent architecture combination 1A + 2C + 3B + 4C + 5B. + +## Risks (verbatim handoff) + +- The boundary between a typed primitive and a host-aware template can drift and become another implicit transformation layer without an exception-review policy. +- Marketplace packaging or signing constraints may require prebuilt artifacts, so local materialization cannot be the only supported distribution channel. +- Textual parity does not prove semantic parity; the migration oracle must validate inventory, references, descriptors, semantic goldens, and installed-path canaries. +- Two-release shadow operation temporarily increases CI and maintenance cost and needs a precise definition of a stable release. +- Capability classification can be wrong; misclassifying a semantic mapping as packaging-only could permit unsafe provisional compatibility. +- Claude Code E5/E6 remain unverified without a real binary, authentication, version, and executed scenario; unavailable evidence must never be shown as passing. +- External host documentation and marketplaces can change faster than adapter evidence, so compatibility records need version, scenario, timestamp, and freshness policy. diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/research-brief.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/research-brief.md new file mode 100644 index 00000000..febb759b --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/research-brief.md @@ -0,0 +1,43 @@ +# Research Brief: platform-independent Maister + +## TL;DR +Badanie ma ustalić, czy Maister może mieć jeden kanoniczny, testowalny model zachowania, a różnice hostów materializować dopiero podczas instalacji. +Głównym problemem jest koszt generowania i utrzymywania kilku wariantów oraz brak dostępnego runtime Claude Code do testów end-to-end. +Wynik ma porównać realne opcje architektoniczne, wskazać granicę niezależności od platformy i zaproponować bezpieczną ścieżkę migracji. + +## Key Decisions +- Badanie ma charakter mieszany — wymaga analizy kodu, kontraktów hostów, instalacji i strategii testowania. +- Rozróżnienie platformy na etapie instalacji jest hipotezą do zweryfikowania, nie z góry przyjętym rozwiązaniem. + +## Open Questions / Risks +- Hosty mogą wymagać różnych fizycznych layoutów, manifestów, nazw narzędzi i modeli agentów, których nie da się ujednolicić w artefakcie instalowanym bez transformacji. +- Brak runtime Claude Code ogranicza możliwy poziom dowodu do walidacji statycznej, kontraktowej i testów wspólnego rdzenia, chyba że znajdziemy wiarygodny emulator lub oficjalny validator. + +## Research question + +W jaki sposób uprościć Maister i uniezależnić go od platform AI coding hostów, tak aby utrzymywać jedno testowalne rozwiązanie, a ewentualne różnice wybierać dopiero podczas instalacji — również dla Claude Code, gdzie nie mamy dostępnego runtime do testów? + +## Scope + +### Included + +- Kanoniczne źródła pluginu, platform adapters i generowane warianty. +- Host-native wymagania Claude Code, Codex, Cursor i Kiro. +- Instalacja, discovery, manifesty, role/agents, skills/commands i runtime helpers. +- Build oraz test matrix, w tym luka runtime Claude Code. +- Warianty: wspólny artefakt, instalacyjny compiler/materializer, cienkie host adapters i wspólny runtime/core. +- Migracja, ryzyka kompatybilności i sposób dowodzenia parity. + +### Excluded + +- Implementacja rozwiązania. +- Zmiany funkcjonalne workflow niezwiązane z portability. +- Twierdzenie o pełnej zgodności Claude Code bez dostępnego runtime proof. + +## Success criteria + +1. Każda istotna różnica platformowa ma dowód w kodzie, dokumentacji, konfiguracji lub teście. +2. Raport oddziela model zachowania od host-native packaging i invocation. +3. Co najmniej trzy warianty uproszczenia są ocenione pod kątem utrzymania, testowalności, zgodności i migracji. +4. Rekomendacja określa, co może być wspólne, co musi pozostać platformowe i na jakim etapie wykonywać transformację. +5. Strategia testów wyjaśnia uczciwie, co można udowodnić dla Claude Code bez jego runtime. diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/research-plan.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/research-plan.md new file mode 100644 index 00000000..c64a1261 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/research-plan.md @@ -0,0 +1,146 @@ +# Research Plan: platform-independent Maister + +## TL;DR +Badanie zastosuje metodologię mieszaną: analizę repozytorium, rekonstrukcję kontraktów hostów oraz porównanie oficjalnych wymagań z obecną macierzą testów. +Trzy niezależne strumienie zbiorą dowody o kanonicznym rdzeniu, granicy instalacyjnych adapterów i możliwym poziomie assurance bez runtime Claude Code. +Synteza porówna co najmniej trzy warianty i wskaże jeden docelowy model, który maksymalizuje wspólne, uruchamialne testy bez ukrywania nieuniknionych różnic hostów. + +## Key Decisions +- Typ badania: mixed — technical, requirements i literature research. +- Jednostką porównania będzie kontrakt zachowania, packagingu, instalacji i weryfikacji, a nie tylko układ plików wygenerowanych pluginów. +- Gathering Strategy ma trzy stabilne, niezależne kategorie, aby zmieścić analizę w dostępnym limicie agentów i umożliwić późniejsze łączenie ustaleń po identyfikatorach. +- Hipoteza „różnice dopiero przy instalacji” będzie oceniana obok co najmniej dwóch alternatyw, a nie traktowana jako z góry wybrana architektura. + +## Open Questions / Risks +- Dokumentacja hostów może opisywać możliwości nowsze niż dostępne lokalnie CLI lub marketplace; wersje i daty muszą być zapisane przy dowodzie. +- Brak runtime Claude Code uniemożliwia uczciwe potwierdzenie pełnego E2E; trzeba oddzielić dowód semantyczny, instalacyjny, statyczny i runtime. +- Tekstowe transformacje mogą zawierać ukryte różnice semantyczne, których nie ujawni samo porównanie struktury katalogów. +- Termin „jedno rozwiązanie” może oznaczać jedno źródło, jeden artefakt dystrybucyjny albo jeden runtime; synteza musi rozdzielić te poziomy. + +## Research Question + +W jaki sposób uprościć Maister i uniezależnić go od platform AI coding hostów, tak aby utrzymywać jedno testowalne rozwiązanie, a ewentualne różnice wybierać dopiero podczas instalacji — również dla Claude Code, gdzie nie ma dostępnego runtime do testów? + +## Methodology + +### Classification + +Badanie jest mieszane: + +1. **Technical research** — rekonstrukcja aktualnego przepływu canonical source → platform adapters → generated variants → installation/runtime. +2. **Requirements research** — ekstrakcja nieusuwalnych kontraktów Claude Code, Codex, Cursor i Kiro oraz kryteriów kompatybilności, migracji i dystrybucji. +3. **Literature research** — weryfikacja kontraktów hostów w oficjalnych dokumentacjach oraz porównanie wzorców single-source, install-time materialization i contract testing. + +### Core method + +1. Rozłożyć pytanie na cztery płaszczyzny: model zachowania, host-native invocation, packaging/installation oraz assurance/testing. +2. Zmapować każdy istotny wariant platformowy do konkretnego źródła: kodu, manifestu, dokumentacji, fixture lub testu. +3. Zrekonstruować obecną macierz build/install/smoke/E2E oraz oznaczyć, które dowody uruchamiają wspólny rdzeń, a które tylko walidują wygenerowany tekst. +4. Porównać co najmniej trzy warianty architektoniczne wspólną kartą oceny. +5. Wyprowadzić rekomendację oraz etapową ścieżkę migracji z jawnym poziomem pewności dla Claude Code. + +## Analytical Model + +### Layer decomposition + +Każde ustalenie będzie przypisane do jednej lub kilku warstw: + +- **Behavior model** — fazy, bramki, stan, safety invariants, Advisor/Arbiter i reguły wznowienia. +- **Portable runtime/helpers** — JavaScript ESM, shell helpers, schema/state repository i deterministyczne operacje możliwe do testowania bez hosta. +- **Host contract** — narzędzia, role/agenci, invocation, continuation, hooks i ograniczenia wykonawcze. +- **Packaging and discovery** — layout, manifesty, marketplace, commands/skills/rules i wymagane nazwy. +- **Installation/materialization** — wybór hosta, transformacja, walidacja wejścia i atomowość instalacji. +- **Assurance** — unit/contract/golden/install/smoke/E2E oraz brakujące dowody runtime. + +### Alternatives to compare + +Synteza ma ocenić co najmniej: + +1. **Obecny canonical source + build-time generated targets** — wariant bazowy. +2. **Jeden przenośny pakiet + install-time compiler/materializer** — użytkownik wybiera host podczas instalacji, a instalator tworzy host-native layout. +3. **Wspólny behavior/runtime core + cienkie, wersjonowane host adapters** — wspólne testy rdzenia, minimalne adaptery packaging/invocation instalowane per host. +4. **Wspólny neutralny IR/schema + generatory hostów** — ocenić tylko jeśli dowody pokażą, że tekst kanoniczny jest zbyt powiązany z Claude Code, by służyć jako neutralne źródło. + +### Evaluation scorecard + +Każdy wariant będzie oceniony jakościowo i, gdzie dowody pozwalają, w skali 1–5 według: + +- liczby i złożoności utrzymywanych źródeł; +- procentu zachowania wykonywanego przez jeden testowalny rdzeń; +- ilości host-specific transformations i ich fragility; +- jakości dowodu możliwego bez runtime Claude Code; +- zgodności z natywnym discovery, manifestami, tools i hooks; +- deterministyczności, reprodukowalności i możliwości działania offline; +- kompatybilności wstecznej, rollbacku i kosztu migracji; +- ergonomii instalacji i diagnostyki błędów; +- ryzyka dryfu wersji hostów. + +## Gathering Strategy + +| Stable category ID | Zakres niezależnego badania | Kluczowe pytania | Output prefix | +|---|---|---|---| +| `canonical-core-transform-boundary` | Kanoniczny plugin, wspólne workflow/runtime helpers, adaptery build i generowane warianty | Co jest rzeczywiście wspólnym modelem zachowania? Które transformacje są mechaniczne, a które semantyczne? Czy canonical jest neutralny, czy Claude-oriented? Gdzie może przebiegać stabilny interfejs core/adapter? | `canonical-core-` | +| `host-contracts-installation` | Kontrakty Claude Code, Codex, Cursor i Kiro; layout, manifesty, commands/skills/agents/hooks/MCP; install/uninstall i marketplace | Jakie różnice są wymagane przez hosta? Które można materializować przy instalacji? Czy możliwy jest jeden dystrybuowany pakiet z wyborem `--target`, zachowując host-native discovery i aktualizacje? | `host-contracts-` | +| `test-assurance-runtime-gap` | Make/CI, validation, fixtures, golden/contract/install/smoke/E2E, capability matrix oraz luka Claude Code runtime | Co dzisiaj jest wykonywane, a co tylko sprawdzane strukturalnie? Jak testować wspólny core raz? Jaki evidence ladder i contract harness da uczciwe assurance dla Claude Code bez twierdzenia o pełnym E2E? | `test-assurance-` | + +Każdy gatherer zapisuje jeden lub więcej plików `analysis/findings/*.md`. Kategorie nie powinny zmieniać wspólnych źródeł ani stanu workflow. Mogą cytować te same pliki tylko wtedy, gdy odpowiadają na różne pytania; synteza rozstrzyga rozbieżności. + +## Evidence and Citation Discipline + +1. Każde twierdzenie o aktualnym zachowaniu musi mieć cytat do pliku z numerem linii: ``path/to/file:line`` albo zakres krótkich, bezpośrednio związanych linii. +2. Każde twierdzenie o wymaganiu hosta musi wskazać oficjalną dokumentację lub host-owned schema/CLI output, wraz z URL, datą dostępu i — jeśli dostępne — wersją. +3. Test jest dowodem wyłącznie zachowania, które rzeczywiście wykonuje. Structural grep, snapshot/golden, install test, smoke i E2E muszą być jawnie rozróżnione. +4. Dokumentacja projektowa jest źródłem intencji, nie automatycznie dowodem implementacji; rozbieżności kod–docs mają być zapisane jako finding. +5. Wnioski architektoniczne muszą odwoływać się do co najmniej dwóch niezależnych źródeł lub być oznaczone jako hipoteza/inference. +6. Dla każdego findingu podać confidence: `high`, `medium` lub `low`, oraz krótkie uzasadnienie braków. +7. Nie cytować wygenerowanego wariantu jako niezależnego dowodu canonical behavior, jeśli jest deterministyczną kopią tego samego źródła; używać go do dowodu materializacji lub host-native shape. + +## Investigation Procedure + +### 1. Broad discovery + +- Zbudować mapę katalogów canonical, `platforms/`, generated variants, testów, CI, instalatorów i dokumentacji hostów. +- Wyszukać host-specific vocabulary, warunki platformowe, overrides/patches/transforms oraz duplikowane helpery. +- Zinwentaryzować wejścia i wyjścia `make build`, `make validate`, install/smoke/E2E i release jobs. + +### 2. Targeted tracing + +- Prześledzić reprezentatywny workflow od `plugins/maister/skills/*/SKILL.md` do każdego targetu. +- Prześledzić wspólne runtime helpers i ich platformowe kopie/wrappers. +- Prześledzić instalację dla każdego hosta: source artifact, wybór miejsca, manifest, konfigurację i walidację. +- Prześledzić po jednym dowodzie z każdej klasy testu, zapisując dokładnie co wykonuje. + +### 3. Contract extraction + +- Utworzyć macierz cech hostów: discovery/layout, invocation, tools, subagents, user gates, hooks, continuation, MCP, config i marketplace. +- Dla każdej komórki oznaczyć `common`, `adapter-required`, `unsupported` lub `unknown`. +- Oddzielić różnice składniowe od semantycznych oraz instalacyjne od runtime. + +### 4. Verification and synthesis handoff + +- Cross-check kluczowych różnic w co najmniej dwóch źródłach. +- Zidentyfikować sprzeczności między dokumentacją, adapterami i testami. +- Przekazać synthesizerowi findings, macierz dowodów, warianty i nierozstrzygnięte luki bez przedwczesnego wyboru architektury. + +## Required Synthesis Outputs + +Raport końcowy powinien zawierać: + +1. mapę aktualnej architektury i kosztów złożoności; +2. macierz host contracts oraz granicę portable/platform-specific; +3. macierz testów i evidence ladder, w tym dokładny status Claude Code; +4. porównanie co najmniej trzech wariantów; +5. rekomendowany model docelowy i uzasadnienie; +6. propozycję install-time selection oraz wymagania fail-fast/atomic rollback; +7. migrację etapami z kryteriami wejścia/wyjścia i możliwością rollbacku; +8. ryzyka, założenia, otwarte pytania i confidence per major finding. + +## Completion Criteria + +- Wszystkie cztery hosty mają udokumentowany kontrakt i źródło dowodu albo jawny status `unknown`. +- Wszystkie istotne platform transforms są przypisane do warstwy i sklasyfikowane jako syntactic lub semantic. +- Dla każdego rodzaju testu wiadomo, czy testuje core, materializer, instalację czy host runtime. +- Co najmniej trzy warianty są ocenione tą samą scorecard. +- Rekomendacja definiuje jeden canonical/testable solution oraz minimalny install-time adapter surface. +- Raport nie utożsamia static/contract validation z Claude Code runtime E2E. + diff --git a/.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/sources.md b/.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/sources.md new file mode 100644 index 00000000..314a73c2 --- /dev/null +++ b/.maister/tasks/research/2026-07-14-platform-independent-plugin/planning/sources.md @@ -0,0 +1,151 @@ +# Source Plan: platform-independent Maister + +## TL;DR +Pierwszeństwo mają źródła pierwotne: canonical code, adaptery, instalatory, testy, CI oraz oficjalne kontrakty czterech hostów. +Dokumentacja projektu opisuje intencję, natomiast kod i uruchamialne testy potwierdzają faktyczny stan. +Każde źródło zostanie przypisane do warstwy architektury i siły dowodu, aby szczególnie dla Claude Code nie pomylić walidacji statycznej z runtime proof. + +## Key Decisions +- Lokalne źródła będą cytowane jako `path:line`; źródła internetowe jako oficjalny URL, data dostępu i wersja, jeśli jest dostępna. +- Generated variants będą traktowane jako dowód shape/materialization, a nie jako niezależne potwierdzenie wspólnej semantyki. +- Dowody testowe będą klasyfikowane na unit/contract, golden/structural, install, smoke i runtime E2E. +- Nieoficjalne artykuły mogą służyć wyłącznie do odkrywania tropów; kluczowe wymagania muszą wrócić do źródła host-owned. + +## Open Questions / Risks +- Oficjalne dokumentacje mogą nie gwarantować stabilności wszystkich niejawnych zachowań CLI i marketplace. +- Lokalnie obecne skrypty `claude.e2e.sh` mogą wymagać runtime, którego badanie nie może uruchomić; sam plik nie jest dowodem udanego E2E. +- Brak lockfile dla opcjonalnych narzędzi może osłabić reprodukowalność dowodów środowiskowych. + +## Source Priority + +1. **P0 — executable primary evidence:** kod runtime, adaptery/materializery, instalatory, walidatory, testy i CI, które można odczytać lub uruchomić. +2. **P1 — contractual primary evidence:** oficjalne dokumentacje i schematy Claude Code, OpenAI Codex, Cursor i Kiro. +3. **P2 — project intent:** dokumentacja architektury, vision, roadmap, standards i README. +4. **P3 — secondary context:** materiały zewnętrzne tylko do porównania wzorców; nie mogą samodzielnie uzasadniać host compatibility. + +## Local Primary Sources + +### Canonical behavior and runtime + +- `plugins/maister/CLAUDE.md` — kanoniczne instrukcje hosta źródłowego i sygnał Claude-oriented coupling. +- `plugins/maister/.claude-plugin/plugin.json` — canonical manifest i pola zależne od Claude Code. +- `plugins/maister/skills/*/SKILL.md` — model zachowania workflow, invocation i host vocabulary. +- `plugins/maister/agents/*.md` — role, narzędzia i kontrakty delegacji. +- `plugins/maister/commands/*.md` — canonical command wrappers i granica commands/skills. +- `plugins/maister/hooks/*` — canonical hook surface i safety behavior. +- `plugins/maister/skills/orchestrator-framework/references/orchestrator-patterns.md` — kontrakt faz, stanu, bramek i wznowienia. +- `plugins/maister/skills/orchestrator-framework/references/gate-decision-engine.md` — portable/manual/advisor gate semantics. +- `plugins/maister/skills/orchestrator-framework/references/host-capabilities.yml` — deklarowana macierz capabilities do zweryfikowania z implementacją i testami. +- `plugins/maister/skills/orchestrator-framework/bin/*.mjs` — wspólny executable runtime/core kandydat do jednokrotnego testowania. + +### Build and transformation boundary + +- `Makefile` — entry points build/validate oraz aktualna kolejność generacji. +- `platforms/cursor/build.sh` i `platforms/cursor/{transforms,patches,overrides,templates,rules}/` — typy transformacji Cursor. +- `platforms/kiro-cli/build.sh`, `generate-agent-json.sh` i `platforms/kiro-cli/{transforms,overrides,templates}/` — Kiro materialization i generation contracts. +- `platforms/codex-cli/build.sh` i `platforms/codex-cli/{templates,hooks,bin}/` — Codex materialization, TOML agents i runtime wrappers. +- `plugins/maister-cursor/`, `plugins/maister-kiro/`, `plugins/maister-codex/` — generated host-native shape, inventory i drift; analizować przez porównanie z wejściem/adaptorem. +- `.github/workflows/validate-generated-variants.yml` — CI drift contract. +- `.github/workflows/release.yml` — jakie artefakty są faktycznie dystrybuowane i wersjonowane. + +### Installation and host discovery + +- `platforms/cursor/smoke-install.sh`, `platforms/cursor/tests/install.test.sh`, `platforms/cursor/smoke-cli.sh` — instalacja, filesystem layout i dostępne CLI proof. +- `platforms/kiro-cli/maister-kiro`, `platforms/kiro-cli/smoke-install.sh`, `smoke-uninstall.sh`, `smoke-cli.sh` — Kiro install/uninstall i entry point. +- `platforms/codex-cli/smoke-install.sh`, `platforms/codex-cli/tests/install.test.sh`, `smoke-cli.sh` — Codex install/config/CLI proof. +- `README.md`, `docs/codex-support.md`, `docs/cursor-agent-support.md`, `docs/kiro-cli-support.md`, `docs/on-demand-skills.md` — udokumentowany user journey do sprawdzenia z implementacją. + +### Testing and assurance + +- `tests/host-continuation/claude.e2e.sh` — intencja Claude runtime E2E; sprawdzić prerequisites i nie uznawać za wykonany dowód bez udanego runu. +- `tests/workflow-continuation.test.sh`, `tests/fully-automatic-phase-continue.test.sh`, `tests/phase-continue-contract.test.sh` — testy wspólnego continuation/state core. +- `tests/gate-decision-engine.test.sh`, `tests/gate-evaluator.test.sh`, `tests/orchestrator-state-repository.test.sh` — wspólny gate/state runtime contract. +- `tests/host-capability-matrix.test.sh` — spójność capability declarations. +- `tests/advisor-*.test.sh` oraz `tests/fixtures/advisor-*` — cross-platform configuration and safety evidence. +- `platforms/cursor/tests/*.test.sh` i `fully-automatic-continuation.e2e.sh` — structural/install/runtime boundary dla Cursor. +- `platforms/kiro-cli/tests/*.test.sh` i `fully-automatic-continuation.e2e.sh` — generation/install/runtime boundary dla Kiro. +- `platforms/codex-cli/tests/*.test.sh` i `fully-automatic-continuation.e2e.sh` — native evidence i runtime boundary dla Codex. +- `.github/workflows/cursor-cli-smoke.yml` — realne pokrycie środowiskowe i jego blocking/non-blocking status. + +## Project Documentation Sources + +- `.maister/docs/project/vision.md` — docelowe single-source, parity i safety principles. +- `.maister/docs/project/architecture.md` — opis aktualnego canonical + deterministic multi-target model. +- `.maister/docs/project/roadmap.md` — rozpoznane długi: runtime coverage, semantic transforms, golden fixtures i capability matrix. +- `.maister/docs/project/tech-stack.md` — dostępne runtime/tooling constraints i brak root dependency lock. +- `.maister/docs/standards/global/build-pipeline.md` — obowiązująca własność generated targets i release validation. +- `.maister/docs/standards/global/minimal-implementation.md` — ograniczenie spekulacyjnych abstrakcji. +- `.maister/docs/standards/global/validation.md` i `error-handling.md` — wymagania dla przyszłego install-time selector/materializer. +- `.maister/docs/standards/testing/test-writing.md` — behavior focus, risk-based depth i transactional rejection tests. + +## External Primary Sources to Verify + +Gatherer `host-contracts-installation` powinien wyszukać wyłącznie aktualne, oficjalne źródła i zapisać datę dostępu 2026-07-14: + +### Claude Code / Anthropic + +- Oficjalna dokumentacja plugin marketplace, plugin manifests i installation/discovery. +- Oficjalna dokumentacja skills, slash commands, subagents, hooks i MCP. +- Oficjalna dokumentacja headless/non-interactive CLI lub dostępnych mechanizmów walidacji; ustalić, czy istnieje wspierany sposób testów bez interaktywnego runtime. +- Release notes lub compatibility/version statements, jeśli kontrakt różni się między wersjami. + +### OpenAI Codex + +- Oficjalna dokumentacja Codex plugins/skills/agents oraz local marketplace/install layout. +- Oficjalna dokumentacja `AGENTS.md`, agent TOML, tools, subagent delegation i automation/CLI execution. +- Oficjalne źródła dla hooks/continuation tylko jeśli są częścią publicznego kontraktu używanego przez projekt. + +### Cursor + +- Oficjalna dokumentacja Agent CLI, plugins, rules/MDC, skills/commands, hooks i subagents. +- Oficjalna dokumentacja instalacji lokalnej, discovery paths i możliwości non-interactive/smoke testing. + +### Kiro CLI + +- Oficjalna dokumentacja custom agents, skills, hooks, steering i MCP. +- Oficjalna dokumentacja layoutu instalacji, agent JSON schema oraz headless/CLI execution. + +### Portable installer/runtime constraints + +- Oficjalna dokumentacja Node.js dla filesystem/process/path/crypto używanych w potencjalnym materializerze. +- POSIX/GNU/BSD źródła tylko dla konkretnego portability claim dotyczącego shell tools; preferować eliminację zależności od implementacyjnych różnic nad szeroką literaturą. + +## Evidence Ladder + +| Poziom | Rodzaj dowodu | Co można twierdzić | Czego nie można twierdzić | +|---|---|---|---| +| E0 | Dokument/intencja | Zamierzony kontrakt lub roadmapa | Że implementacja działa | +| E1 | Static/schema validation | Pliki mają oczekiwany shape i dozwolone wartości | Że host je odkryje lub wykona | +| E2 | Golden/reproducible transform | Materializacja jest deterministyczna i zgodna z fixture | Że semantyka jest równoważna w runtime | +| E3 | Isolated executable contract | Wspólny helper/core spełnia kontrakt na fixtures | Że integracja hosta działa | +| E4 | Install/uninstall test | Layout, rollback i lokalne config mutations są poprawne | Że workflow wykona się w hoście | +| E5 | Host CLI smoke | Host odkrywa plugin i wykonuje wąską ścieżkę | Że wszystkie workflow zachowują parity | +| E6 | Host runtime E2E | Konkretny scenariusz działa w określonej wersji hosta | Że przyszłe wersje zachowają kompatybilność | + +Dla Claude Code raport musi wskazać najwyższy faktycznie osiągnięty poziom. Brak dostępnego runtime oznacza, że E6 pozostaje `unverified`, nawet jeśli E1–E4 są kompletne. + +## Citation Record Template + +Każdy finding powinien używać minimalnie tego formatu: + +```markdown +### Finding: + +- Claim: +- Evidence: + - Local: `path/to/file:line` — + - Official: (accessed 2026-07-14, version ) — +- Evidence level: E0–E6 +- Confidence: high | medium | low +- Inference/limitation: +``` + +## Cross-Checks Required Before Synthesis + +- Porównać `host-capabilities.yml` z adapterami, testami i oficjalnymi dokumentacjami. +- Porównać canonical manifest/instructions z każdym generated manifest/layout. +- Porównać wszystkie transform/patch/override classes i oznaczyć duplikacje lub semantyczne wyjątki. +- Porównać dokumentowane install flows z wykonywalnymi install tests. +- Dla każdego E2E ustalić, czy naprawdę uruchamia host CLI/runtime, czy tylko wspólny runner pod nazwą platformy. +- Ustalić, które testy mogą działać raz przeciw canonical core, a które muszą pozostać w target-specific contract matrix. + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..09a4943f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# Agent Instructions + +## Coding Standards & Conventions + +Read @.maister/docs/INDEX.md before starting any task. It indexes the project's coding standards and conventions: +- Coding standards organized by domain (frontend, backend, testing, etc.) +- Project vision, tech stack, and architecture decisions + +Follow standards in `.maister/docs/standards/` when writing code — they represent team decisions. If standards conflict with the task, ask the user. + +### Standards Evolution + +When you notice recurring patterns, fixes, or conventions during implementation that aren't yet captured in standards — suggest adding them. Examples: +- A bug fix reveals a pattern that should be standardized (e.g., "always validate X before Y") +- PR review feedback identifies a convention the team wants enforced +- The same type of fix is needed across multiple files +- A new library/pattern is adopted that should be documented + +When this happens, briefly suggest the standard to the user. If approved, invoke `/maister-standards-update` with the identified pattern. + +## Maister Workflows + +This project uses the maister plugin for structured development workflows. When any `/maister-*` command is invoked, execute it via the Skill tool immediately — do not skip workflows for "straightforward" tasks. The user chose the workflow intentionally; complexity assessment is the workflow's job. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 7fe2c173..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,99 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Repository Overview - -This is a Claude Code plugin marketplace repository containing bundled plugins for AI-driven SDLC workflows. The main plugin is `maister` which provides structured development workflows. - -## IMPORTANT: Never Edit Generated Files - -**NEVER directly modify files under `plugins/maister-copilot/`** — those are auto-generated by the `make` command. Always edit the source files in `plugins/maister/` instead. Changes to `maister-copilot/` will be overwritten. - -## Structure - -``` -.claude-plugin/marketplace.json # Marketplace manifest (lists all plugins) -plugins/ -└── maister/ # Main plugin - ├── .claude-plugin/plugin.json # Plugin manifest - ├── CLAUDE.md # Detailed plugin documentation (READ THIS) - ├── agents/ # Subagent definitions (*.md) - ├── commands/ # Slash commands (organized by workflow type) - ├── skills/ # Skills with SKILL.md entry points - └── .mcp.json # MCP server configuration -docs/ # User-facing documentation and guides -``` - -## Key Files - -- **`@plugins/maister/CLAUDE.md`**: Comprehensive plugin documentation with all skills, commands, agents, and workflow principles. Read this when working on plugin internals. -- **`README.md`**: User-facing documentation for plugin consumers. - -## Plugin Development - -### Adding a New Skill - -1. Create directory: `plugins/maister/skills/[skill-name]/` -2. Create `SKILL.md` with workflow phases and execution instructions -3. Optionally add `references/` directory for supporting documentation -4. Document in `@plugins/maister/CLAUDE.md` under "Available Skills" - -### Adding a New Command - -1. Create markdown file: `plugins/maister/commands/[category]/[command].md` -2. Commands are thin wrappers that invoke skills -3. Document in `plugins/maister/CLAUDE.md` under "Available Commands" - -### Adding a New Agent - -1. Create markdown file: `plugins/maister/agents/[agent-name].md` -2. Define agent purpose, tools, and workflow -3. Document in `plugins/maister/CLAUDE.md` under "Available Subagents" - -## Documentation Principles - -This plugin follows specific documentation guidelines (see @plugins/maister/CLAUDE.md section "Plugin Documentation Principles"): - -- Trust Claude to reason—provide principles, not prescriptive implementations -- Commands are thin wrappers; orchestration logic lives in skills -- Reference files guide implementation, not provide complete code -- Single source of truth: technical details in `SKILL.md`, not scattered across files - -## Beta Branch Management - -The `beta` branch is used for developing and testing new features before they reach `master`. - -### Branch Conventions - -- **master**: Stable releases. Marketplace name: `maister-plugins`, versions: `X.Y.Z` -- **beta**: Pre-release testing. Marketplace name: `maister-plugins-beta`, versions: `X.Y.Z-beta.N` - -### Merging beta to master (squash workflow) - -1. **Sync beta with master**: `git checkout beta && git merge master` -2. **Squash-merge to master**: `git checkout master && git merge --squash beta` -3. **Fix versions before committing**: Restore master's marketplace name (`maister-plugins`) and set the new release version (not beta version) in all three manifest files -4. **Commit the feature**: `git commit -m "Feature description"` -5. **Bump version**: Separate commit for the version bump -6. **Reset beta**: `git checkout beta && git reset --hard master` — required because squash-merge doesn't track merge parents -7. **Set beta version**: Update manifests to next beta version (e.g., `X.Y.Z-beta.1`) with marketplace name `maister-plugins-beta`, commit -8. **Push both**: `git push origin master beta` - -### Why reset beta after squash? - -After `git merge --squash`, git doesn't record that beta's commits were merged. A regular `git merge master` back to beta would try to replay all old commits, causing conflicts. `reset --hard master` is safe because all beta work is preserved on master. - -### Manifest files to update - -These three files need version/name changes during the merge workflow: -- `.claude-plugin/marketplace.json` — name + version + descriptions -- `plugins/maister/.claude-plugin/plugin.json` — version + description -- `plugins/maister-copilot/.claude-plugin/plugin.json` — version + description - -## Testing Changes - -1. Navigate to a test project -2. Run `/maister:init` to initialize the framework -3. Test commands like `/maister:development "test feature"` -4. Test workflows with different task types and complexity levels diff --git a/Makefile b/Makefile index 2f885c1a..59eb86b0 100644 --- a/Makefile +++ b/Makefile @@ -1,25 +1,71 @@ -.PHONY: build validate clean watch - -build: - bash platforms/copilot-cli/build.sh - -validate: - @echo "Checking no colons in command names..." - @! grep -r '^name:.*:' plugins/maister-copilot/commands/ 2>/dev/null || (echo "FAIL: colons in command names" && exit 1) - @echo "Checking no multi-select references..." - @! grep -ri 'multi.select\|multiSelect' plugins/maister-copilot/skills/ 2>/dev/null || (echo "FAIL: multi-select found in skills" && exit 1) - @echo "Checking commands are flat (no subdirectories)..." - @test $$(find plugins/maister-copilot/commands -mindepth 2 -name "*.md" 2>/dev/null | wc -l) -eq 0 || (echo "FAIL: nested command directories found" && exit 1) - @echo "Checking no CLAUDE.md references in skills..." - @! grep -ri 'CLAUDE\.md' plugins/maister-copilot/skills/ 2>/dev/null || (echo "FAIL: CLAUDE.md references found in skills" && exit 1) - @echo "Checking no maister- prefix in copilot command names..." - @! grep -r '^name: maister-' plugins/maister-copilot/commands/ 2>/dev/null || (echo "FAIL: maister- prefix in command names" && exit 1) - @echo "Checking no maister: prefixes in copilot variant..." - @! grep -r 'maister:' plugins/maister-copilot/ --include="*.md" 2>/dev/null || (echo "FAIL: maister: prefix found" && exit 1) - @echo "All checks passed" - -clean: - rm -rf plugins/maister-copilot/ - -watch: - fswatch -o plugins/maister/ | xargs -n1 -I{} make build +SHELL := /bin/bash + +TARGET ?= codex +ifneq ($(origin SUPPORTED_TARGETS),undefined) +$(error SUPPORTED_TARGETS is not configurable; targets are owned by plugins/maister/lib/distribution/targets.mjs) +endif +DIST_DIR ?= dist +SOURCE_DATE_EPOCH ?= $(shell git log -1 --format=%ct 2>/dev/null || date +%s) +SOURCE_COMMIT ?= $(shell git rev-parse HEAD 2>/dev/null || true) +SOURCE_VERSION ?= $(shell if test -f VERSION; then cat VERSION; else echo unknown; fi) +E3_ATTESTATION ?= +E3_OUTPUT ?= +E3_RESULT ?= +E3_TEST_COMMAND ?= make test-core +E3_SCENARIO_VERSION ?= 1.0.0 +E3_EXPIRES_AT ?= +PARITY_ORACLE ?= tests/fixtures/platform-independent/parity-oracle/manifest.json +PARITY_ALLOW_DIRTY_LOCAL ?= 0 +PARITY_REPORT ?= + +export TARGET DIST_DIR SOURCE_DATE_EPOCH SOURCE_COMMIT SOURCE_VERSION +export E3_ATTESTATION E3_OUTPUT E3_RESULT E3_TEST_COMMAND E3_SCENARIO E3_SCENARIO_VERSION E3_EXPIRES_AT +export MAISTER_E3_ATTESTATION +export PARITY_ORACLE PARITY_ALLOW_DIRTY_LOCAL PARITY_REPORT +export HOME MAISTER_ALLOW_DIRTY_LOCAL + +.PHONY: check-cursor-projection test-platform-independent test-core generate-e3-attestation test-overlay test-materializer test-install test-evidence test-parity test-parity-release test-topology test validate package install + +check-cursor-projection: + node plugins/maister/bin/generate-cursor-skills.mjs --check + +test-platform-independent: + node --test tests/platform-independent/*.test.mjs + +test-core: + node --test tests/platform-independent/overlay-contract.test.mjs tests/platform-independent/source-materializer.test.mjs tests/platform-independent/installer-transaction.test.mjs + +generate-e3-attestation: + node plugins/maister/bin/release-interface.mjs generate-e3 + +test-overlay: + node plugins/maister/bin/release-interface.mjs validate-overlay + +test-materializer: + node --test tests/platform-independent/source-materializer.test.mjs + +test-install: + node --test tests/platform-independent/installer-transaction.test.mjs + +test-evidence: + node --test tests/platform-independent/evidence-parity-topology.test.mjs + +test-parity: test-parity-release + +test-parity-release: + node plugins/maister/bin/release-interface.mjs parity-release + +test-topology: + node plugins/maister/bin/release-interface.mjs topology + +test: test-core test-evidence test-topology + +validate: check-cursor-projection + node plugins/maister/bin/release-interface.mjs validate-overlays + $(MAKE) --no-print-directory test + +package: check-cursor-projection + node plugins/maister/bin/release-interface.mjs package + +install: + node plugins/maister/bin/release-interface.mjs install diff --git a/README.md b/README.md index 6b43db48..f82bacb9 100644 --- a/README.md +++ b/README.md @@ -1,182 +1,184 @@ -
- # Maister -**Structured, standards-aware development workflows for Claude Code** - -Describe what you want to build, and the plugin handles the rest - from specification through implementation to verification - while enforcing your project's coding standards at every step. +Maister is a portable, auditable SDLC plugin. The repository contains one common source, three explicit host overlays, and one transactional installer. Host selection happens at installation time; maintainers do not independently maintain generated host trees. Cursor's checked-in compatibility projection is deterministically derived and drift-checked from the canonical source, with explicit hash-locked exceptions, and remains migration debt rather than a second source of truth. -
+## Supported hosts -## What You Get +- Codex +- Cursor +- Kiro CLI -- **Guided workflows** for features, bug fixes, enhancements, performance, migrations, research, and product design -- **Auto-discovered standards** from your codebase - config files, source patterns, and documentation are analyzed and enforced throughout every workflow -- **Test-driven implementation** with automated planning, incremental verification, and full test suite runs before completion -- **Pause and resume** any workflow - state is preserved across sessions -- **Production readiness checks** including code review, reality assessment, and pragmatic over-engineering detection +### Migration boundary (historical) -## Getting Started +The old generated host trees, marketplace projections, and legacy host support were removed during the platform-independent distribution migration. They are retained only as migration history/parity context and are not supported installation targets. -### Prerequisites +## Installation -- [Claude Code](https://claude.ai/code) CLI installed and configured +The public installer supports a clean local Git checkout, a self-contained Maister archive, or a GitHub source. Production source must resolve to one full commit and must be free of untracked or ignored inputs. For `github:owner/repo`, the bounded resolver uses Git to resolve the requested safe ref, creates a temporary detached checkout at the resolved commit, verifies `HEAD`, status, and content hash, and removes the checkout after the transaction. The overlay is selected from that same checkout, so source and host contract cannot silently come from different revisions. -### Installation - -```bash -/plugin marketplace add SkillPanel/maister -/plugin install maister@maister-plugins +```sh +SOURCE=/path/to/maister +test -z "$(git -C "$SOURCE" status --porcelain --untracked-files=all --ignored=matching)" +REF="$(git -C "$SOURCE" rev-parse HEAD)" +node plugins/maister/bin/maister-install.mjs install \ + --target codex \ + --source "local:$SOURCE" \ + --ref "$REF" \ + --home "$HOME" \ + --json ``` -After installing, restart Claude Code (`/exit` and relaunch) to ensure the plugin is fully loaded. - -### Initial project setup +For an immutable GitHub install, prefer the full commit SHA: -Initialize your project to auto-detect coding standards and generate project documentation: - -```bash -/maister:init +```sh +node plugins/maister/bin/maister-install.mjs install \ + --target codex \ + --source github:SkillPanel/maister \ + --ref 0123456789012345678901234567890123456789 \ + --home "$HOME" \ + --json ``` -This scans your codebase and creates `.maister/` with standards, docs, and task folders. May take a few minutes on larger projects. +The resolver also accepts a safe branch or tag ref, but resolves it with `git ls-remote` and records the resulting full commit. Short SHAs, unsafe ref syntax, ambiguous refs, dirty checkouts, and Git operations exceeding the bounded timeout are rejected. Git operations default to 30 seconds; `MAISTER_GIT_TIMEOUT_MS` may explicitly set a value from 1 ms through 10 minutes. -If you have another project already using Maister, you can reuse its standards as a starting point: +For development-only work on an intentionally dirty checkout: -```bash -/maister:init --standards-from=/path/to/other-project +```sh +MAISTER_ALLOW_DIRTY_LOCAL=1 node plugins/maister/bin/maister-install.mjs install \ + --target cursor \ + --source local:/path/to/maister \ + --home "$HOME" \ + --json ``` -### First Workflow - -```bash -/maister:development Add user profile page with avatar upload -``` - -Or just discuss your task with Claude and then run: - -```bash -/maister:development -``` - -The plugin picks up context from your conversation - no arguments needed. - -## How It Works - -1. You describe a task - either as an argument or just in conversation -2. The plugin classifies it (feature, bug, enhancement, etc.) and proposes a workflow -3. You confirm, and it guides you through phases: **requirements → spec → plan → implement → verify** -4. At each phase, it asks for your input and decisions -5. You get tested, verified code with a detailed work log +`MAISTER_ALLOW_DIRTY_LOCAL=1` is an explicit development escape hatch. It is not production provenance: do not use it for a release, support reproduction, or an operator runbook that claims immutable source. -All artifacts are saved in `.maister/tasks/` organized by type and date. +The lifecycle commands are `install`, `update`, `status`, `verify`, `uninstall`, `rollback`, and `recover`. Installation stages and validates the source and overlay before it changes a target home. Updates refuse unsafe drift, preserve unmanaged settings, and publish a receipt only after integrity verification. -### Context-Aware Commands - -Every workflow command works without arguments. The plugin reads your current conversation to extract the task description and auto-detect the task type: - -``` -You: "The login page throws a 500 error when the session expires" -You: /maister:development -→ Auto-detects: bug fix, extracts description from conversation -``` +State is kept outside the plugin source: +```text +$XDG_STATE_HOME/maister//active-receipt.json +$XDG_STATE_HOME/maister//receipts/ +$XDG_STATE_HOME/maister//journals/ +$XDG_STATE_HOME/maister//backups/ ``` -You: /maister:standards-update -→ Scans conversation for patterns like "we always use..." or "prefer X over Y" -``` - -You can always be explicit when you prefer - arguments and flags simply override the auto-detection. - -## Supported Workflows -| Command | Use When | -|---------|----------| -| `/maister:development` | Features, bug fixes, enhancements | -| `/maister:research` | Research with synthesis and solution design | -| `/maister:performance` | Optimizing speed or resource usage | -| `/maister:migration` | Changing technologies or patterns | -| `/maister:product-design` | Product and feature design | +If `XDG_STATE_HOME` is unset, the default is `~/.local/state`. State roots, journals, receipts, backups, staging directories, and lock files should be private to the operator (`0700` directories and `0600` files). A journal records transaction boundaries. Recovery and rollback are safety-sensitive operations; see the runbook below and preserve the state directory whenever a transaction does not complete. -Task type (feature/bug/enhancement) is auto-detected from context. Override with `--type=feature|bug|enhancement` if needed. Or use `/maister:work` as a single entry point that routes to the right workflow. +### Concurrency and ownership boundary -### Quick Commands +The installer lock coordinates cooperating Maister lifecycle processes for one target and state root. It does not lock the host application, the user's editor, shell scripts, synchronization software, backup tools, or another process that writes the target tree or shared settings directly. Maister owns only the inventory and settings keys recorded in its receipt; all other content remains operator-owned. Path-identity revalidation, drift checks, staging, journals, and rollback reduce time-of-check/time-of-use risk, but they cannot make arbitrary external writers participate in the transaction. -For smaller tasks that don't need a full workflow: +Before install, update, uninstall, rollback, or recovery, stop the host and any process that may write the selected target or settings. Do not manually edit managed files, receipts, journals, backups, or settings keys during a lifecycle operation. If an external writer races the installer, treat a drift, integrity, transaction, or recovery error as unresolved: stop all writers, preserve target and state data, then follow the recovery runbook. The threat model assumes the operator controls the local account and state directory; it does not defend against a malicious same-user process or privileged process that can replace files while the transaction runs. -| Command | Use When | -|---------|----------| -| `/maister:quick-plan` | You want a plan with standards awareness before coding | -| `/maister:quick-dev` | You know what to do - just implement with standards applied | -| `/maister:quick-bugfix` | Quick TDD-driven bug fix — write failing test, fix, verify | +## Exit codes -## Standards-Aware Development +The JSON envelope includes the same numeric `code` as the process exit status: -This is the key differentiator. Maister doesn't just run workflows - it learns your project's conventions and enforces them: +| Code | Meaning | Typical action | +| ---: | --- | --- | +| 0 | Completed successfully | Inspect the receipt for provenance and evidence. | +| 2 | Usage or settings-format error | Correct arguments or the settings format; do not retry unchanged. | +| 3 | Source or Git resolution error | Use a clean local checkout and a full commit; for GitHub, use a safe ref or preferably its full commit SHA and inspect the resolver details. | +| 4 | Overlay, materialization, or settings validation error | Fix the source/overlay contract; no target mutation should be accepted. | +| 5 | Managed-target or settings drift conflict | Review the reported unmanaged change before retrying. | +| 6 | Target lock is busy | Confirm another installer is not running, then retry. | +| 7 | Transaction, recovery, or rollback failure | Preserve state and journals; follow the recovery runbook. | +| 8 | Integrity verification failure | Do not continue; inspect provenance and receipt/journal evidence. | -- **`/maister:init`** scans config files, source code, and documentation to auto-detect your coding standards -- **Continuous checking** - standards are consulted before specification, during planning, and while coding (not just at the start) -- **`/maister:standards-discover`** refreshes standards from your evolving codebase -- **`/maister:standards-update`** lets you add or refine standards manually, or sync from another project with `--from=PATH` +## Locks, journals, recovery, and rollback failures -Standards live in `.maister/docs/standards/` and are indexed in `.maister/docs/INDEX.md`. +1. Stop concurrent Maister operations for the affected target and preserve the complete target state directory. +2. Check `$XDG_STATE_HOME/maister//install.lock` (or `~/.local/state/maister//install.lock`). Do not remove it while an installer process is alive. If the process is confirmed gone, preserve a copy of the lock and journals before any cleanup. +3. Inspect `journals/`, `active-receipt.json`, `receipts/`, and `backups/`. These are audit and recovery inputs; do not hand-edit them. +4. Run `recover --target --home --json` only after the process is stopped and the backup/journal paths are readable. Verify the returned journal path and receipt before retrying install/update. +5. For a rollback failure, do not repeatedly invoke `rollback`. Preserve the failing journal and backup, copy the target-scoped state directory for support, and repair the underlying permission, missing-backup, or drift condition first. +6. If recovery or rollback returns code 7, stop. A successful command exit is not evidence that the prior state was restored unless `verify` succeeds and the receipt/journal record the expected target. -**Important**: Run workflows with **auto-accept edits** enabled. Do not use Claude Code's plan mode with workflows (see [Best Practices](#best-practices) below). +Recovery follows the durable journal and target-scoped backups. A code-7 result means the transaction or recovery boundary is unresolved: preserve the state, correct the underlying condition, run `recover`, and then run `verify`. Do not treat a successful recovery command as proof of correctness without the resulting receipt and integrity verification. -## Beta Channel +## Packaged archive lifecycle and provenance -Want to try experimental features before they hit stable? Install from the beta channel: +`make package TARGET=` creates a self-contained deterministic target tarball under `dist/`. It includes the distribution runtime, installer, canonical source, selected overlay, and `.maister-source.json` containing source commit, version, and content hash. Before an artifact is published or installed, inspect it and its checksum: -```bash -# Add the beta marketplace -/plugin marketplace add SkillPanel/Maister#beta - -# Install the beta plugin -/plugin install maister@maister-plugins-beta +```sh +sha256sum dist/maister-.tar.gz +tar -tzf dist/maister-.tar.gz +cat dist/SHA256SUMS ``` -If you already have the stable version installed, uninstall it first to avoid conflicts: +Treat `dist/` as disposable local build output. Filenames and timestamps do not prove that an archive was produced by the current source: old flat-layout or partially generated archives may remain there after development. Before a manual release, remove or isolate prior output, regenerate all three archives in the same clean release run, and require each archive to contain `plugins/maister/bin/maister-install.mjs` plus only its selected overlay. Never publish a pre-existing `dist/` archive that did not pass the current run's extracted lifecycle, checksum, metadata, and strict parity gates. -```bash -/plugin uninstall maister@maister-plugins -``` +The package test's default mode builds each target twice with a fixed source timestamp and verifies byte-for-byte deterministic output. The installer requires a passed portable-core E3 record for install/update. Generate the deterministic record only after the core gate, then pass the same bytes to every target package: -To switch back to stable: +```sh +make test-core +make generate-e3-attestation E3_OUTPUT=dist/e3-portable-core.json E3_RESULT=passed SOURCE_VERSION=2.2.1 +E3_ATTESTATION=dist/e3-portable-core.json make package TARGET=codex SOURCE_VERSION=2.2.1 +``` -```bash -/plugin uninstall maister@maister-plugins-beta -/plugin install maister@maister-plugins +Release CI runs `make test-core`, generates one deterministic E3 record, embeds it in all three archives, and blocks publication unless the extracted archive smoke completes install, verify, and uninstall for every target. The E3 schema/digest binding remains owned by the portable-core evidence boundary; the release record is not a cryptographic signature. + +To exercise an approved archive manually: + +```sh +EXTRACT="$(mktemp -d)" +SANDBOX="$(mktemp -d)" +HOME_DIR="$SANDBOX/home" +STATE_DIR="$SANDBOX/state" +mkdir -p "$HOME_DIR" "$STATE_DIR" +tar -xzf dist/maister-codex.tar.gz -C "$EXTRACT" +REF="$(node --input-type=module -e 'import fs from "node:fs"; console.log(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).source_commit)' "$EXTRACT/plugins/maister/.maister-source.json")" +XDG_STATE_HOME="$STATE_DIR" node "$EXTRACT/plugins/maister/bin/maister-install.mjs" install --target codex --source "local:$EXTRACT" --ref "$REF" --home "$HOME_DIR" --json +XDG_STATE_HOME="$STATE_DIR" node "$EXTRACT/plugins/maister/bin/maister-install.mjs" verify --target codex --source "local:$EXTRACT" --home "$HOME_DIR" --json +XDG_STATE_HOME="$STATE_DIR" node "$EXTRACT/plugins/maister/bin/maister-install.mjs" uninstall --target codex --source "local:$EXTRACT" --home "$HOME_DIR" --json +rm -rf "$EXTRACT" "$SANDBOX" ``` -Beta versions may contain features that are not yet fully tested. Use at your own discretion. +Use an isolated home/state directory for destructive lifecycle checks. The release test performs this flow in temporary sandboxes for every target. -## Best Practices +The release workflow generates `dist/SHA256SUMS`, a CycloneDX artifact inventory at `dist/SBOM.cdx.json`, and an unsigned build provenance record at `dist/PROVENANCE.json`; it uploads these alongside the archives. Provenance and SBOM entries bind the embedded E3 canonical digest and attestation bytes as well as each archive hash. These files provide reproducibility and integrity only after they are obtained through a trusted release channel: they are not signatures, do not authenticate the publisher, and do not claim native E6. An attacker able to replace an archive can also replace unsigned checksums and metadata. Release actions are pinned to verified commit SHAs. Operators should retain the checksum, source commit, overlay/version identifier, parity report, E3 record, SBOM, and provenance record with the artifact. -**Don't use plan mode when starting a workflow.** Planning is a built-in part of every workflow — the orchestrator creates specs, plans, and other files as it goes. Claude Code's plan mode restricts file creation, which conflicts with this. Let the workflow handle planning on its own. +## Repository model -**Start workflows in a fresh session.** This is especially useful when chaining workflows (e.g., research → development). Research and product-design artifacts already contain all the context needed, so a clean session avoids noise from prior conversation. +```text +plugins/maister/common/ portable primitives and common source +plugins/maister/overlays/ codex, cursor, and kiro-cli contracts +plugins/maister/lib/ resolver, materializer, evidence, and installer +plugins/maister/bin/ validation, materialization, installation, parity +tests/platform-independent/ core and target-seam tests +``` -**Chain workflows by passing a task folder.** If you've completed a research or product-design workflow and want to build on those results, pass the task folder directly: +Portable behavior is intended to have one owner. Codex and Kiro CLI consume the canonical common source; Cursor currently carries a behavior-bearing skills projection under its overlay, which is migration debt and must not be treated as an independent source of truth. An overlay should otherwise own only native manifests, layout, settings ownership, bindings, inventories, and forbidden vocabulary. The materializer produces a staging tree; the installer owns the target transaction. -```bash -/maister:development .maister/tasks/research/2026-01-12-oauth-research -``` +## Compatibility evidence -You can also append additional instructions to narrow scope or guide the workflow: +Evidence is recorded per target, capability, host version, scenario, timestamp, provenance, and expiry: -```bash -/maister:development .maister/tasks/product-design/2026-03-10-dashboard-redesign Implement only phase 1 -``` +- E1 — source, schema, and overlay validation +- E2 — deterministic materialization and content validation +- E3 — shared portable-core behavior +- E4 — installer transaction, receipt, settings, drift, recovery, and rollback +- E5 — host-native discovery and integration +- E6 — host-native runtime scenarios -## Known Issues +`passed`, `failed`, and `unavailable` are distinct. E5 or E6 may be unavailable because the host executable, authentication, a safe probe adapter, or a versioned runtime scenario is absent. An unavailable record is never promoted to passed and does not prove host-native discovery or runtime semantics. Packaging may be reported as provisional under the selected policy when its structural and transactional evidence passes, but semantic support that requires unavailable E5/E6 remains unverified and must not be advertised as supported. Re-probe after the missing prerequisite is supplied or evidence expires. -**Orchestrator may stall after long phases.** After context compaction (which typically happens after lengthy phases like implementation), the main agent may stop progressing automatically. If you notice it's idle, just type something like "continue" or "proceed" — it will pick up where it left off. You can also re-invoke the workflow in resume mode to reload the orchestrator state: +## Development -```bash -/maister:development .maister/tasks/development/2026-03-24-my-feature +```sh +make test-core +make test-overlay TARGET=codex +make test-materializer TARGET=cursor +make test-install TARGET=kiro-cli +make test-evidence +make test-parity-release +make test-topology +make validate +make package TARGET=codex ``` -## Learn More +For migration parity, `make test-parity-release` reconstructs the three reviewed legacy trees directly from the immutable Git-tree oracle, materializes all three targets from the same checkout, and requires zero unresolved differences. It needs no external legacy root. A release candidate must run this command from a clean checkout; `E_SOURCE_DIRTY` is a release stop, not a warning. `PARITY_ALLOW_DIRTY_LOCAL=1` is available only for development diagnostics, and a passing dirty-local comparison is never release evidence. Release CI runs the strict command without that override. The CLI rejects a missing manifest and accepts only explicit, versioned path rules with immutable observations, category, and rationale; it does not auto-learn differences from the candidate output. Edit `plugins/maister/` and its overlays directly. Do not create generated target directories or marketplace entries. `make validate` validates every supported overlay, the common core, evidence policy, and repository topology before packaging. -- [Workflow Details](docs/workflows.md) - phases, examples, and task structure for each workflow type -- [Full Command Reference](docs/commands.md) - all workflow, review, utility, and quick commands +More operator detail is in [docs/README.md](docs/README.md). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..a67c3c19 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,53 @@ +# Maister documentation + +Maister is distributed from one common source through explicit Codex, Cursor, and Kiro CLI overlays. The target-aware installer accepts a clean local Git checkout, a self-contained Maister archive, or a GitHub source, then materializes a staging tree, validates it, and commits through a journaled transaction. GitHub installation resolves one immutable commit, creates a bounded temporary detached checkout, verifies it, selects the overlay from that same checkout, and cleans it up after the transaction. + +## Operator guide + +- Use `plugins/maister/bin/maister-install.mjs` for install, update, status, verify, uninstall, rollback, and recovery. +- For production, use a clean local checkout with `HEAD` set to the intended full commit SHA, or use `github:owner/repo` with a full commit SHA. Safe branch/tag refs are resolved to a full commit before checkout; short SHAs, unsafe refs, and dirty/ignored inputs are rejected. +- GitHub fetch/checkout operations are bounded to 30 seconds by default; set `MAISTER_GIT_TIMEOUT_MS` explicitly when a different value is required, within the supported 1 ms–10 minute range. +- Use `MAISTER_ALLOW_DIRTY_LOCAL=1` only for explicit development experiments; it bypasses the clean-checkout guard and must not be used in release or support instructions. +- State and receipts live below `$XDG_STATE_HOME/maister/` or `~/.local/state/maister/`. +- A drift conflict stops the operation until the managed target or settings ownership is reconciled. +- `recover` follows the journal and restores file content, modes, links, existence, and topology. Preserve the target-scoped state and journal if code 7 is returned, then verify the resulting receipt before retrying a lifecycle command. +- Stop the host application and every external writer to the selected target or shared settings before a lifecycle command. The target lock coordinates Maister processes only; it cannot lock editors, synchronization tools, shell scripts, or malicious same-user/privileged processes. + +## State and permissions + +For target ``, state is under `$XDG_STATE_HOME/maister/` or `~/.local/state/maister/` and contains `active-receipt.json`, `receipts/`, `journals/`, `backups/`, `staging/`, and `install.lock`. Keep directories private (`0700`) and files containing receipts, settings snapshots, or lock metadata private (`0600`). Never hand-edit a receipt or journal and never remove a lock while its owning process may still be running. + +Maister owns only receipt-listed inventory and allowlisted managed settings keys. Unlisted files and settings remain operator-owned. Identity checks, drift detection, and rollback detect or repair supported races, but arbitrary external mutation is outside the transaction protocol. If another writer races a lifecycle command, stop all writers, preserve the target and state directories, and treat any drift, integrity, or code-7 result as unresolved until recovery and verification succeed. + +## Exit codes and recovery + +The installer returns: `0` success, `2` usage/settings format, `3` source/Git, `4` overlay/materializer/settings validation, `5` drift, `6` lock busy, `7` transaction/recovery/rollback failure, and `8` integrity failure. On `5`, inspect the reported drift before retrying. On `6`, confirm the competing process. On `7` or `8`, preserve the state directory, inspect the journal and backup, run `recover` only after the process has stopped, and verify the resulting receipt before another lifecycle command. A failed rollback is not repaired by repeated rollback attempts. + +## Compatibility + +The evidence schema distinguishes E1–E6. E5/E6 records are `unavailable` when a host executable, authentication, safe adapter, or configured versioned scenario is missing. Unavailable never satisfies a passed capability and must remain visible in receipts and support statements. Structural and transactional evidence may permit provisional packaging, but unavailable E5/E6 does not certify host-native discovery or runtime semantics; re-probe when the prerequisite becomes available or the evidence expires. + +## Migration boundary (historical) + +The migration removed legacy host support, committed generated target trees, old host builders, and marketplace installation assumptions. Those artifacts are parity history only. Maintainers now edit the common source and versioned overlays, then validate a selected target. + +## Package verification + +`make package TARGET=` creates a self-contained deterministic archive containing the distribution runtime, installer, canonical source, selected overlay, `.maister-source.json`, and the recognized embedded E3 record. The manifest binds the archive to its source commit, source version, and content hash. Run `make test-core` first, then generate one deterministic record with `make generate-e3-attestation E3_RESULT=passed ...` and pass it as `E3_ATTESTATION` to every target package. The release-package test builds each target twice to verify determinism; release CI blocks publication unless the three-target lifecycle smoke consumes that embedded E3 record successfully. + +The release job writes `dist/SHA256SUMS`, `dist/SBOM.cdx.json`, and unsigned `dist/PROVENANCE.json`, then uploads them with the archives. Actions in the release workflow are pinned to verified commit SHAs. The metadata records artifact hashes, source commit, source-date epoch, successful parity report, and the embedded E3 digest/bytes; it is not a cryptographic attestation, does not authenticate the publisher, and does not claim native E6. Checksums and metadata establish integrity only when obtained through a trusted release channel because an attacker who replaces an archive can replace unsigned sidecars too. + +Treat local `dist/` as disposable output. Remove or isolate old artifacts before a manual release, build all targets in the same clean run, confirm each archive has the `plugins/maister/**` package shape and only its selected overlay, and publish only artifacts that passed that run's extracted lifecycle, strict parity, checksum, and metadata checks. A familiar filename or recent timestamp is not release evidence. Before installation, inspect `tar -tzf dist/maister-.tar.gz` and verify the archive against `dist/SHA256SUMS`; retain the source commit, overlay/version, E3 record, parity report, SBOM, and provenance with the artifact. + +## Checks + +```sh +make test-core +make test-evidence +make test-parity-release +node --test tests/platform-independent/release-package.test.mjs +make test-topology +make validate +``` + +The parity release gate is migration-only but release-blocking: it reconstructs the reviewed immutable Git-tree oracle, materializes Codex, Cursor, and Kiro CLI from one checkout, and requires zero unresolved differences. It must pass from a clean checkout. `E_SOURCE_DIRTY` blocks publication, and `PARITY_ALLOW_DIRTY_LOCAL=1` is a diagnostic override whose result must never be used as release evidence. Expected differences are explicit, versioned, path-scoped, and fingerprint-bound. The portable-distribution workflow validates overlays and contracts rather than rebuilding independently maintained projections. The Cursor evidence workflow does not install a remote runtime; it probes only a preinstalled CLI and records `unavailable` when the host or required scenario is absent. The final topology check rejects legacy/generated trees, marketplace paths, and stale installation references. diff --git a/docs/commands.md b/docs/commands.md index a95e98eb..6c2743b3 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -162,7 +162,7 @@ Initialize the Maister framework. Scans your codebase with a project-analyzer su - `.maister/docs/` with INDEX.md, project docs (vision, roadmap, tech-stack), and coding standards - `.maister/tasks/` directory structure -- CLAUDE.md integration +- Project-instructions integration | Flag | Description | |------|-------------| @@ -206,7 +206,7 @@ Implement a task directly — exactly as the main agent normally would, no plann ### `/maister:quick-plan [task description]` -Works exactly like Claude Code's built-in plan mode, with standards enforcement folded in. While planning, it reads INDEX.md and the specific matched standard files (INDEX.md alone is not enough), and the plan must reference the applicable standards and include a Standards Compliance Checklist (verified after implementation) before exiting plan mode. +Works like the host's built-in plan mode, with standards enforcement folded in. While planning, it reads INDEX.md and the specific matched standard files (INDEX.md alone is not enough), and the plan must reference the applicable standards and include a Standards Compliance Checklist (verified after implementation) before exiting plan mode. ### `/maister:quick-bugfix [bug description]` @@ -215,3 +215,103 @@ Lightweight TDD-driven bug fix without a full orchestrator workflow. Analyzes th **When to use**: Simple, isolated bugs where you can quickly identify the root cause. If the bug is too complex (multiple files, unclear root cause, architectural impact), the skill suggests escalating to `/maister:development`. No task directory created — works directly in your codebase. + +--- + +## On-Demand Skills + +Standalone skills for requirements critique, DDD modeling, architecture review, and stakeholder communication. These are **not** orchestrator phases — invoke them manually. See [On-Demand Skills Guide](on-demand-skills.md) for when to use each skill and Bundle A–D chaining. + +### `/maister:quick-transcript-critic` + +Audits a meeting transcript or notes for decision-process problems — false consensus, marginalized voices, scope drift. Produces a structured critique with severity ratings, evidence quotes, and diagnostic questions. + +**When to use**: After meetings where requirements were discussed verbally; before converting notes into tickets or specs. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:quick-requirements-critic` + +Interactive requirements quality critique via four checks: problem vs solution framing, observable behavior, extensible signal map, and rigid quantifier probing. + +**When to use**: Before writing a specification; when requirements feel vague or solution-heavy. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:quick-problem-classifier` + +Classifies business requirements into four DDD modeling problem classes (CRUD, Transformation & Presentation, Integration, Resource Contention) with clarifying questions and implementation guidance. + +**When to use**: When unsure which modeling approach fits; as entry point for DDD modeling chains. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:quick-metaprogram-classifier` + +Diagnoses NLP metaprogram patterns in utterances or described behavior and suggests context-specific communication strategies. + +**When to use**: Before difficult stakeholder conversations; when communication style seems mismatched. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:modeling-context-distiller` + +Distills bounded contexts via bidirectional linguistic analysis — finds generalization candidates and context-split signals. Produces a strategic design artifact. + +**When to use**: When domain concepts might be generalized or split across contexts; after problem-classifier in modeling chains. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:modeling-aggregate-designer` + +Interactive wizard for Resource Contention consistency units — aggregate boundaries, command locking, optimistic concurrency. + +**When to use**: When problem-classifier detects RC class; when modeling concurrent resource contention. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:reviews-linguistic-boundaries` + +Read-only audit of bounded-context language leakage via `language.md` files. Gracefully degrades when the convention is not adopted. + +**When to use**: When modules have `language.md` files; before merging cross-module changes. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:reviews-test-strategy` + +Read-only review that classifies production code by problem class and compares test strategy (output/state/interaction-based) against recommendations. + +**When to use**: After linguistic-boundary review; when tests feel misaligned with production code structure. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:grill-me` + +**Primary invocation:** Ask explicitly in natural language (e.g., "grill me on this plan"). Cursor users: `/maister-grill-me`. + +Relentless interactive interview to stress-test a plan or design until shared understanding. Walks a decision tree one question at a time with a convergence gate. Read-only — no documentation or code edits. Explicit request only. + +**When to use**: Before stakeholder conversations; when a design has unresolved branches; when you do not want docs maintained during grilling. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:grill-with-docs` + +**Primary invocation:** Ask explicitly in natural language (e.g., "grill this plan and update language.md"). Cursor users: `/maister-grill-with-docs`. + +Stress-test a plan or domain topic with the same grilling discipline as `grill-me`, plus user-confirmed updates to `language.md` and sparse ADRs. Explicit request only. + +**When to use**: When stress-testing and you want canonical vocabulary and significant decisions captured in project documentation as you go. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. + +### `/maister:thermos` + +**Primary invocation:** Ask explicitly in natural language (e.g., "run a thermos review on this branch"). Cursor users: `/maister-thermos`. + +Launches both thermo-nuclear-review and thermo-nuclear-code-quality-review in parallel, then synthesizes deduplicated findings — bugs, breaking changes, security, maintainability, and structural simplification. + +**When to use**: Before merging a significant PR or branch; as optional final step in architecture review chains. + +See [On-Demand Skills Guide](on-demand-skills.md) for when to use. diff --git a/docs/on-demand-skills.md b/docs/on-demand-skills.md new file mode 100644 index 00000000..c15a5c3a --- /dev/null +++ b/docs/on-demand-skills.md @@ -0,0 +1,459 @@ +# On-Demand Skills Guide + +User-oriented guide to Maister's Wave 1–3 on-demand skills — what they do, when to invoke them, and how they relate to orchestrator workflows. + +**Related docs:** [Documentation Hub](README.md) · [Workflows](workflows.md) · [Command Reference](commands.md) + +--- + +## 1. Introduction + +### On-demand vs orchestrator workflows + +Maister provides **five orchestrator workflows** (`development`, `research`, `performance`, `migration`, `product-design`) that run multi-phase pipelines automatically. Each orchestrator invokes internal skills (codebase-analyzer, specification-creator, implementation-planner, and others) as phases — you do not call those directly. + +**On-demand skills** are different. They are **standalone capabilities** you invoke when you need a specific analysis, critique, or modeling session outside — or before — a full orchestrator run. They are **not phases** of `/maister:development` or any other orchestrator. + +| Type | Examples | How they run | +|------|----------|--------------| +| **Orchestrator** | `/maister:development`, `/maister:research` | Multi-phase pipeline; phases activate based on task characteristics | +| **On-demand skill** | `context-distiller`, `requirements-critic`, `thermos` | Single focused session; you invoke manually | +| **Internal skill** | `codebase-analyzer`, `implementation-verifier` | Auto-invoked by orchestrators only — see [Workflows § Internal Skills](workflows.md#internal-skills) | + +### Manual invocation + +On-demand skills require an **explicit request**: + +- **Slash command** — for skills with a command wrapper (e.g. `/maister:quick-problem-classifier`) +- **Natural language** — ask the agent directly (e.g. "grill me on this plan" or "run a thermos review on this branch") +- **Cursor hyphen form** — `/maister-quick-problem-classifier` (see §2) + +Skills marked **"Explicit request only"** in the agent catalog under `plugins/maister/skills/` will not auto-run during unrelated work. The `disable-model-invocation` frontmatter flag means the model cannot silently attach the skill — you must ask. + +### ADR-008: soft suggestions (never auto-invoked) + +Two on-demand skills may be **soft-suggested** by orchestrators after specific phases. The orchestrator may mention them; it will **never** invoke them automatically. + +| Skill | Orchestrator | When suggested | +|-------|--------------|----------------| +| `requirements-critic` | `development` only | After requirements are drafted in Phase 5 — you may run `/maister:quick-requirements-critic` for interactive quality critique | +| `transcript-critic` | `product-design` only | When meeting transcripts are present — you may run `/maister:quick-transcript-critic` for decision-process audit | + +All other on-demand skills: **no orchestrator suggestion, no auto-invocation**. + +--- + +## 2. How to invoke + +### Colon-style invocation + +``` +/maister: +``` + +Examples: `/maister:quick-requirements-critic`, `/maister:modeling-context-distiller`, `/maister:reviews-test-strategy` + +### Cursor Agent + +Cursor uses a **hyphen** prefix instead of a colon: + +``` +/maister- +``` + +Examples: `/maister-quick-requirements-critic`, `/maister-modeling-context-distiller` + +### Kiro CLI + +Kiro uses a different invocation model; see the supported-target installation and evidence notes in [the documentation hub](README.md). + +### Explicit-request skills + +`grill-me`, `grill-with-docs`, and `thermos` do not have standard command wrappers. Invoke them by **asking explicitly**: + +- "Grill me on this design until we agree on the trade-offs" +- "Grill this plan and update language.md" +- "Run a thermos review on my branch before merge" + +**Cursor users** can also try: `/maister-grill-me`, `/maister-grill-with-docs`, and `/maister-thermos` + +### Trigger phrases (summary) + +| Skill | Example trigger phrases | +|-------|------------------------| +| `transcript-critic` | "audit this meeting transcript", "critique these notes for decision problems" | +| `requirements-critic` | "critique these requirements", "run requirements critic" | +| `problem-classifier` | "classify these requirements", "what modeling problem class is this?" | +| `context-distiller` | "distill bounded contexts", "can X be generalized with Y?" | +| `aggregate-designer` | "design aggregates", "modeling resource contention" | +| `linguistic-boundary-verifier` | "check linguistic boundaries", "language.md leakage audit" | +| `test-strategy-reviewer` | "review test strategy", "are these tests output-based or interaction-based?" | +| `metaprogram-classifier` | "what metaprogram is this person using?", "how should I communicate with them?" | +| `grill-me` | "grill me", "stress-test this plan" | +| `grill-with-docs` | "grill with docs", "grill this plan and update language.md", "stress-test and capture domain language" | +| `thermos` | "thermos review", "thermo-nuclear review of this PR" | + +For full invocation guards and workflow detail, see each skill's `SKILL.md` (linked in §5). + +--- + +## 3. Which skill should I use? + +```mermaid +flowchart TD + START([What do you need?]) --> Q1{Requirements
quality?} + Q1 -->|Meeting notes / transcript| TC[transcript-critic] + Q1 -->|Written requirements / spec| RC[requirements-critic] + Q1 -->|Modeling class unclear| PC[problem-classifier] + + START --> Q2{DDD / domain
modeling?} + Q2 -->|Boundaries / contexts| CD[context-distiller] + Q2 -->|Resource contention / aggregates| AD[aggregate-designer] + Q2 -->|Start here| PC + + START --> Q3{Architecture
review?} + Q3 -->|language.md boundaries| LB[linguistic-boundary-verifier] + Q3 -->|Test strategy fit| TS[test-strategy-reviewer] + Q3 -->|PR / branch risk| TH[thermos] + + START --> Q4{Stakeholder
communication?} + Q4 -->|Understand their style| MP[metaprogram-classifier] + Q4 -->|Stress-test your proposal| GM[grill-me] + + START --> Q5{Full workflow
needed?} + Q5 -->|Yes| ORCH[Use an orchestrator
see workflows.md] +``` + +**Rule of thumb:** If you need end-to-end implementation with spec, plan, and verification — use `/maister:development`. If you need a focused critique or modeling session — pick an on-demand skill (or chain via Bundles A–D below). + +--- + +## 4. Recommended bundles (A–D) + +Bundles are **manual chains** — run each skill in sequence yourself. Progress via each skill's "Recommended next steps" section, not orchestrator wiring. + +### Bundle A — Requirements quality + +Use after meetings or when refining raw notes into implementable requirements. + +```mermaid +flowchart LR + A1[transcript-critic] --> A2[requirements-critic] --> A3[problem-classifier] +``` + +1. **`transcript-critic`** — Audit meeting transcript for decision-process problems (false consensus, scope drift) +2. **`requirements-critic`** — Interactive 4-check requirements quality critique on refined stories +3. **`problem-classifier`** — When concurrency or resource-contention signals appear, classify into DDD problem classes + +### Bundle B — DDD modeling + +Use when shaping a new domain or resolving modeling ambiguity. + +```mermaid +flowchart LR + B1[problem-classifier] --> B2[context-distiller] --> B3[aggregate-designer] --> B4[linguistic-boundary-verifier] +``` + +1. **`problem-classifier`** — Classify requirements into modeling problem classes +2. **`context-distiller`** — When generalization or ambiguity signals appear, distill bounded contexts +3. **`aggregate-designer`** — When Resource Contention (RC) class is detected, design consistency units +4. **`linguistic-boundary-verifier`** — When `language.md` files exist, audit boundary leakage + +### Bundle C — Architecture review + +Use before merging significant changes or when adopting the `language.md` convention. + +```mermaid +flowchart LR + C1[linguistic-boundary-verifier] --> C2[test-strategy-reviewer] --> C3[thermos] + C3 -.->|optional| C3 +``` + +1. **`linguistic-boundary-verifier`** — Audit bounded-context language via [`language.md` files](../.maister/docs/standards/global/language-md-convention.md) +2. **`test-strategy-reviewer`** — Compare test strategy (output/state/interaction-based) against production code problem class +3. **`thermos`** *(optional)* — Comprehensive PR audit combining risk + maintainability reviews + +### Bundle D — Stakeholder communication + +Use before difficult conversations or when adapting your message to someone's style. + +```mermaid +flowchart LR + D1[metaprogram-classifier] --> D2{Need doc
maintenance?} + D2 -->|No| D3[grill-me] + D2 -->|Yes| D4[grill-with-docs] +``` + +1. **`metaprogram-classifier`** — Diagnose NLP metaprogram patterns in their communication +2. **`grill-me`** or **`grill-with-docs`** — Stress-test your proposal before the conversation; use `grill-with-docs` when you want confirmed `language.md` and sparse ADR updates during grilling + +--- + +## 5. Skill catalog + +Each entry: 2–4 sentences + when/when-not + invocation + output type + suggested next step. Full behavioral spec: link to `SKILL.md`. + +### Wave 1 — Requirements, decisions, branch review + +#### transcript-critic + +**What it does:** Audits meeting transcripts for decision-process problems — false consensus, marginalized voices, scope drift. Produces a structured non-interactive critique with severity ratings, evidence quotes, and diagnostic questions. + +**When to use:** After meetings where requirements were discussed verbally; before converting notes into tickets or specs. + +**When not to use:** For written requirements already in structured form (use `requirements-critic` instead); during orchestrator runs (invoke manually before or between phases). + +**Command:** `/maister:quick-transcript-critic` (Cursor: `/maister-quick-transcript-critic`) + +**Output type:** Report (non-interactive) + +**Suggested next:** `requirements-critic` (Bundle A) — see [Bundle A](#bundle-a--requirements-quality) + +**Full spec:** [plugins/maister/skills/transcript-critic/SKILL.md](../plugins/maister/skills/transcript-critic/SKILL.md) + +--- + +#### requirements-critic + +**What it does:** Interactive requirements critique via four checks: problem vs solution framing, observable behavior, extensible signal map, and rigid quantifier probing. + +**When to use:** Before writing a specification; when requirements feel vague or solution-heavy; after `transcript-critic` in Bundle A. + +**When not to use:** For meeting transcripts (use `transcript-critic`); as a substitute for `/maister:development` specification phase. + +**Command:** `/maister:quick-requirements-critic` (Cursor: `/maister-quick-requirements-critic`) + +**Output type:** Interactive session + +**Suggested next:** `problem-classifier` when RC signals appear — see [Bundle A](#bundle-a--requirements-quality) + +**Full spec:** [plugins/maister/skills/requirements-critic/SKILL.md](../plugins/maister/skills/requirements-critic/SKILL.md) + +--- + +#### problem-classifier + +**What it does:** Classifies business requirements into four DDD modeling problem classes: CRUD, Transformation & Presentation, Integration, and Resource Contention. Provides signal scan, clarifying questions, and implementation guidance. + +**When to use:** When unsure which modeling approach fits; as the entry point for Bundle B; after requirements quality work in Bundle A. + +**When not to use:** For routing tasks to orchestrators (that's the `task-classifier` **agent**, not this skill). + +**Command:** `/maister:quick-problem-classifier` (Cursor: `/maister-quick-problem-classifier`) + +**Output type:** Interactive session + +**Suggested next:** `context-distiller` (generalization signals) or `aggregate-designer` (RC class) — see [Bundle B](#bundle-b--ddd-modeling) + +**Full spec:** [plugins/maister/skills/problem-classifier/SKILL.md](../plugins/maister/skills/problem-classifier/SKILL.md) + +--- + +#### grill-me + +**What it does:** Relentless interactive interview to stress-test a plan or design until shared understanding. Walks a decision tree one question at a time with recommended answers. Ends with a **convergence gate** — summarizes decisions, assumptions, deferrals, and contradictions; requires explicit user confirmation before closing. **Read-only** — no documentation or code edits during the session. Explicit request only. + +**When to use:** Before stakeholder conversations; when a design has unresolved branches; as the second step in Bundle D; when you want stress-testing without maintaining `language.md` or ADRs. + +**When not to use:** When you want vocabulary or decisions captured in project docs during grilling (use `grill-with-docs` instead); for automated reports (use review skills); as a replacement for product-design orchestrator. + +**Invocation:** Ask explicitly in natural language (e.g. "grill me on this plan"). Cursor: `/maister-grill-me`. Do not rely on automatic slash invocation. + +**Output type:** Interactive session (read-only) + +**Suggested next:** Proceed to implementation, stakeholder meeting, or `grill-with-docs` to harden vocabulary — see [Bundle D](#bundle-d--stakeholder-communication) + +**Related:** [`grill-with-docs`](#grill-with-docs) — docs-maintaining grilling variant + +**Full spec:** [plugins/maister/skills/grill-me/SKILL.md](../plugins/maister/skills/grill-me/SKILL.md) + +--- + +#### grill-with-docs + +**What it does:** Same grilling discipline as `grill-me` — one question at a time, facts vs decisions, decision-tree walk, convergence gate — plus user-confirmed updates to `language.md` and sparse ADRs when decisions meet significance criteria. Explicit request only. + +**When to use:** When stress-testing a plan or domain topic and you want canonical vocabulary and reversible decisions captured in project documentation as you go; before implementation when `language.md` or ADRs should reflect agreed terms. + +**When not to use:** For read-only stress-testing without doc edits (use `grill-me`); for strategic bounded-context discovery (use `context-distiller`); for aggregate/locking design (use `aggregate-designer`); for read-only boundary audits of existing docs (use `linguistic-boundary-verifier`). + +**Invocation:** Ask explicitly in natural language (e.g. "grill this plan and update language.md"). Cursor: `/maister-grill-with-docs`. Do not rely on automatic slash invocation. + +**Output type:** Interactive session with confirmed `language.md` and ADR edits + +**Suggested next:** `linguistic-boundary-verifier` for read-only boundary audit; `/maister:quick-plan` or `/maister:development` once vocabulary is settled + +**Related:** [`grill-me`](#grill-me) — read-only alternative; [`linguistic-boundary-verifier`](#linguistic-boundary-verifier) — post-settlement audit + +**Full spec:** [plugins/maister/skills/grill-with-docs/SKILL.md](../plugins/maister/skills/grill-with-docs/SKILL.md) + +--- + +#### Grilling and modeling — when to use which skill + +| Skill | Use when… | +|-------|-----------| +| `grill-me` | Stress-testing a plan or design until shared understanding; **no** documentation or code edits | +| `grill-with-docs` | Same grilling discipline, but you want confirmed terms in `language.md` and sparse ADRs as decisions resolve | +| `context-distiller` | Strategic bounded-context discovery — generalization candidates and context-split signals across the domain | +| `aggregate-designer` | Resource Contention consistency units — aggregate boundaries, command locking, optimistic concurrency | +| `linguistic-boundary-verifier` | Read-only audit of existing `language.md` files for cross-module leakage (does not interactively resolve terms) | + +--- + +#### thermos + +**What it does:** Launches both `thermo-nuclear-review` and `thermo-nuclear-code-quality-review` in parallel, then synthesizes deduplicated findings. Covers bugs, breaking changes, security, maintainability, and structural simplification ("code judo"). + +**When to use:** Before merging a significant PR or branch; as optional final step in Bundle C alongside boundary and test-strategy reviews. + +**When not to use:** For routine small changes; when you only need linguistic boundaries (use `linguistic-boundary-verifier` alone). + +**Invocation:** Ask explicitly (e.g. "run a thermos review on this branch"). Cursor: `/maister-thermos`. Do not rely on automatic slash invocation. + +**Output type:** Report (synthesized from parallel sub-reviews) + +**Covers:** `thermo-nuclear-review` + `thermo-nuclear-code-quality-review` (documented here only, not as separate catalog entries) + +**Suggested next:** Address findings, then merge — see [Bundle C](#bundle-c--architecture-review) + +**Full spec:** [plugins/maister/skills/thermos/SKILL.md](../plugins/maister/skills/thermos/SKILL.md) + +--- + +### Wave 2 — Architecture language, tests, communication + +#### linguistic-boundary-verifier + +**What it does:** Read-only audit of bounded-context language leakage via `language.md` files. Gracefully degrades when the convention is not adopted. + +**When to use:** When modules have `language.md` files; before merging cross-module changes; as entry to Bundle C. + +**When not to use:** When `language.md` convention is not in use (skill will note graceful degradation). + +**Command:** `/maister:reviews-linguistic-boundaries` (Cursor: `/maister-reviews-linguistic-boundaries`) + +**Output type:** Report (read-only) + +**Suggested next:** `test-strategy-reviewer` — see [Bundle C](#bundle-c--architecture-review) + +**Full spec:** [plugins/maister/skills/linguistic-boundary-verifier/SKILL.md](../plugins/maister/skills/linguistic-boundary-verifier/SKILL.md) + +--- + +#### test-strategy-reviewer + +**What it does:** Read-only review that classifies production code by problem class and compares test strategy (output/state/interaction-based) against recommendations. + +**When to use:** After `linguistic-boundary-verifier` in Bundle C; when tests feel misaligned with production code structure. + +**When not to use:** To write tests (it reviews strategy only); as a substitute for running the test suite. + +**Command:** `/maister:reviews-test-strategy` (Cursor: `/maister-reviews-test-strategy`) + +**Output type:** Report (read-only) + +**Suggested next:** Optional `thermos` for PR-level audit — see [Bundle C](#bundle-c--architecture-review) + +**Full spec:** [plugins/maister/skills/test-strategy-reviewer/SKILL.md](../plugins/maister/skills/test-strategy-reviewer/SKILL.md) + +--- + +#### metaprogram-classifier + +**What it does:** Diagnoses NLP metaprogram patterns in utterances or described behavior and suggests context-specific communication strategies. + +**When to use:** Before difficult stakeholder conversations; when communication style seems mismatched; as entry to Bundle D. + +**When not to use:** For technical code review; for requirements quality (use Bundle A skills). + +**Command:** `/maister:quick-metaprogram-classifier` (Cursor: `/maister-quick-metaprogram-classifier`) + +**Output type:** Interactive session + +**Suggested next:** `grill-me` — see [Bundle D](#bundle-d--stakeholder-communication) + +**Full spec:** [plugins/maister/skills/metaprogram-classifier/SKILL.md](../plugins/maister/skills/metaprogram-classifier/SKILL.md) + +--- + +### Wave 3 — Strategic DDD + +#### context-distiller + +**What it does:** Distills bounded contexts via bidirectional linguistic analysis — finds generalization candidates and context-split signals. Produces a strategic design artifact, not implementation code. + +**When to use:** When domain concepts might be generalized or split across contexts; after `problem-classifier` in Bundle B when ambiguity signals appear. + +**When not to use:** For RC-class problems needing aggregate design (skip to `aggregate-designer`); for implementation planning (use `/maister:development`). + +**Command:** `/maister:modeling-context-distiller` (Cursor: `/maister-modeling-context-distiller`) + +**Output type:** Strategic design artifact (report) + +**Suggested next:** `aggregate-designer` (RC class) or `linguistic-boundary-verifier` — see [Bundle B](#bundle-b--ddd-modeling) + +**Full spec:** [plugins/maister/skills/context-distiller/SKILL.md](../plugins/maister/skills/context-distiller/SKILL.md) + +--- + +#### aggregate-designer + +**What it does:** Interactive wizard for Resource Contention consistency units — aggregate boundaries, command locking, optimistic concurrency. + +**When to use:** When `problem-classifier` detects RC class; when modeling concurrent resource contention. + +**When not to use:** For CRUD or integration-class problems; before context boundaries are understood (run `context-distiller` first if ambiguous). + +**Command:** `/maister:modeling-aggregate-designer` (Cursor: `/maister-modeling-aggregate-designer`) + +**Output type:** Interactive wizard + +**Suggested next:** `linguistic-boundary-verifier` when `language.md` exists — see [Bundle B](#bundle-b--ddd-modeling) + +**Full spec:** [plugins/maister/skills/aggregate-designer/SKILL.md](../plugins/maister/skills/aggregate-designer/SKILL.md) + +--- + +## 6. Common scenarios + +### Post-meeting notes → implementation + +1. Run **Bundle A**: `transcript-critic` on raw notes → `requirements-critic` on refined stories → `problem-classifier` if RC signals appear +2. If modeling is complex, continue **Bundle B** before starting `/maister:development` +3. Start `/maister:development` with clean requirements — orchestrator handles spec, plan, and implementation + +### Jira ticket before spec + +1. Paste ticket text into `/maister:quick-requirements-critic` for interactive critique +2. If solution-heavy or ambiguous, run `/maister:quick-problem-classifier` +3. Proceed to `/maister:development` or `/maister:quick-plan` depending on scope + +### New domain with resource contention + +1. `/maister:quick-problem-classifier` on requirements — expect RC class +2. `/maister:modeling-context-distiller` if multiple contexts or generalization candidates +3. `/maister:modeling-aggregate-designer` for consistency unit design +4. `/maister:reviews-linguistic-boundaries` once `language.md` files exist +5. `/maister:development` for implementation + +### PR review before merge + +1. `/maister:reviews-linguistic-boundaries` on changed modules (if `language.md` adopted) +2. `/maister:reviews-test-strategy` on new/changed tests +3. Ask for a **thermos** review on the branch for comprehensive risk + maintainability audit +4. Address findings, then merge + +--- + +## 7. Related docs + +| Doc | Purpose | +|-----|---------| +| [Documentation Hub](README.md) | Start here — index of all user docs | +| [Workflows](workflows.md) | Orchestrator phases and internal skills | +| [Command Reference](commands.md) | Slash command syntax for all commands | +| [language.md Convention](../.maister/docs/standards/global/language-md-convention.md) | Bounded-context language files (Bundle C) | +| [Documentation Hub](README.md) | Target-aware installation, evidence, parity, and recovery | + +For the agent-oriented skill catalog and bundle definitions, inspect `plugins/maister/skills/` and the explicit target overlays. diff --git a/platforms/copilot-cli/build.sh b/platforms/copilot-cli/build.sh deleted file mode 100755 index 1bb2a604..00000000 --- a/platforms/copilot-cli/build.sh +++ /dev/null @@ -1,74 +0,0 @@ -#!/bin/bash -set -e - -SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" -ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" -CORE="$ROOT/plugins/maister" -OUT="$ROOT/plugins/maister-copilot" - -# Cross-platform sed in-place (macOS needs '' arg, Linux doesn't) -sedi() { - if [[ "$OSTYPE" == "darwin"* ]]; then - sed -i '' "$@" - else - sed -i "$@" - fi -} - -rm -rf "$OUT" -cp -r "$CORE" "$OUT" -rm -rf "$OUT/hooks" - -# 1. Update plugin.json name -sedi 's/"name": "maister"/"name": "maister-copilot"/' "$OUT/.claude-plugin/plugin.json" - -# 2. Strip plugin prefix from command names: "maister:foo" → "foo" -# Plugin system adds the plugin-id prefix automatically -find "$OUT/commands" -name "*.md" | while read f; do - sedi 's/^name: maister:/name: /' "$f" -done - -# 3. Strip plugin prefix from skill names: "maister:foo" → "foo" -find "$OUT/skills" -name "*.md" | while read f; do - sedi 's/^name: maister:/name: /' "$f" -done - -# 4. Replace maister: prefix with maister- for subagent/skill refs -# Run AFTER command name transform so name: lines are already clean -find "$OUT" -name "*.md" | while read f; do - sedi 's/maister:/maister-/g' "$f" -done - -# 5. Transform multi-select patterns to sequential -find "$OUT/skills" -name "*.md" | while read f; do - sedi \ - -e 's/multi-select question/sequential single-select questions (one per option)/g' \ - -e 's/multi-select/sequential single-select/g' \ - -e 's/multiselect/sequential single-select/g' \ - -e 's/multiSelect/sequential single-select/g' \ - "$f" -done - -# 6. Replace CLAUDE.md references with copilot equivalents in skills -find "$OUT/skills" -name "*.md" | while read f; do - sedi 's/CLAUDE\.md/.github\/copilot-instructions.md/g' "$f" -done - -# 7. Add platform note to plugin's CLAUDE.md -cat >> "$OUT/CLAUDE.md" << 'EOF' - -## Platform: Copilot CLI - -This is the Copilot CLI variant. Key differences from Claude Code: -- **No multi-select**: When asking users to select multiple options, ask sequential single-select questions instead -- **Command names**: No plugin prefix in names (e.g., `development`); the plugin system adds the plugin-id prefix automatically -- **Project instructions file**: Use `.github/copilot-instructions.md` instead of `CLAUDE.md`. If the project uses `AGENTS.md`, support that as well. -- **User questions**: Use `ask_user` tool instead of `AskUserQuestion` -EOF - -# 8. Replace AskUserQuestion with copilot's ask_user tool -find "$OUT" -name "*.md" | while read f; do - sedi 's/AskUserQuestion/ask_user/g' "$f" -done - -echo "Built Copilot CLI variant at $OUT" diff --git a/plugins/maister-copilot/.claude-plugin/plugin.json b/plugins/maister-copilot/.claude-plugin/plugin.json deleted file mode 100644 index de57a9fd..00000000 --- a/plugins/maister-copilot/.claude-plugin/plugin.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "name": "maister-copilot", - "version": "2.2.1", - "description": "Structured, standards-aware development workflows for Claude Code", - "author": { - "name": "Skillpanel", - "email": "marek@skillpanel.com" - } -} diff --git a/plugins/maister-copilot/CLAUDE.md b/plugins/maister-copilot/CLAUDE.md deleted file mode 100644 index 0949fcd0..00000000 --- a/plugins/maister-copilot/CLAUDE.md +++ /dev/null @@ -1,761 +0,0 @@ -# Maister Plugin - -This plugin provides AI-powered Software Development Lifecycle (SDLC) capabilities for Claude Code projects. - -## Purpose - -The Maister plugin helps teams streamline software development workflows by providing: - -- **Workflow Commands**: Slash commands for common SDLC tasks like feature development, bug fixes, and code reviews -- **Specialized Agents**: AI agents optimized for specific development tasks (spec writing, implementation, verification) -- **Skills**: Reusable capabilities for managing standards, documentation, and development workflows -- **Coding Standards**: Project-level standards and best practices that can be customized and enforced - -## Installation - -Install this plugin in your project to gain access to structured development workflows and standards management. - -## Features - -- Step-by-step guided development workflows -- Automated task planning and tracking -- Reusable skills for common development tasks -- Customizable coding standards -- Verification and quality assurance capabilities - -## Critical Principle: User-Confirmed Rollback - -**NEVER automatically rollback or revert code changes without user confirmation.** - -All workflows in this plugin follow this pattern when failures occur: - -1. **STOP** - Don't attempt automatic fixes for critical failures -2. **ANALYZE** - Examine the root cause (config issue? test setup? actual logic error?) -3. **CHECK FOR EASY FIXES** - Often failures are simple config/setup issues -4. **ASK USER** - Use `ask_user` with options: - - "Try suggested fix" (if easy fix identified) - - "Rollback changes" (user confirms rollback) - - "Let me investigate" (pause for manual investigation) -5. **EXECUTE** - Only perform rollback if user explicitly confirms - -**Rationale**: Automatic rollback discards potentially valid work, hides root causes, and frustrates users. Many failures are simple configuration issues with easy 1-line fixes. - -## Workflow Types Supported - -This plugin supports 4 workflow types that route to specialized orchestrators: - -| Workflow Type | Purpose | Orchestrator | Classification Keywords | -|---------------|---------|-------------|------------------------| -| **Development** | Bug fixes, enhancements, new features | development | "fix", "bug", "add", "new", "improve", "enhance", "create" | -| **Performance** | Optimize speed/efficiency | performance | "slow", "optimize", "speed up", "faster" | -| **Migration** | Move tech/patterns | migration | "migrate", "move from X to Y", "upgrade" | -| **Research** | Investigate and document findings | research | "research", "investigate", "explore options" | -| **Product Design** | Design features/products before building | product-design | "design", "product design", "feature design", "wireframe", "prototype" | - -### Design Principles - -- **Adaptive Phases**: The development orchestrator's phases activate based on detected task characteristics, not predetermined types -- **Characteristic Detection**: The gap-analyzer detects whether a task involves reproducible defects, existing code modifications, new capabilities, data operations, or UI changes -- **Flexible Granularity**: Complex steps can have substeps when needed -- **Consistent Core**: All workflows share planning, specification, implementation, and verification phases -- **Conditional Stages**: Phases activate based on context (e.g., TDD gates when defects detected, UI mockups when UI-heavy) - -## Terminology - -To avoid confusion, this plugin uses specific terminology: - -**Development Task** (or simply "Task") -- The high-level work item: a bug fix, new feature, enhancement, refactoring, etc. -- Represents the overall piece of work from start to finish -- Located in: `.maister/tasks/[workflow-type]/YYYY-MM-DD-task-name/` -- Contains: specification, requirements, implementation plan, and verification results - -**Implementation Step** (or "Implementation Task") -- Specific actionable steps executed during the implementation phase -- The detailed breakdown of HOW to build the development task -- Listed in: `implementation-plan.md` within each development task folder -- Example: "1.1 Create User model", "2.3 Write API endpoint", "3.5 Add form validation" - -**Key Distinction**: A "development task" is WHAT to build (the feature/fix), while "implementation steps" are HOW to build it (the specific actions). - -## User-Centric Development Focus - -This plugin prioritizes usability and user experience throughout development: - -### User Journey Analysis - -**During Requirements Gathering** (when creating new capabilities): -- Asks how users will discover the feature -- Identifies target personas (admin, regular user, power user, etc.) -- Maps feature into existing workflows -- Documents access patterns and navigation paths - -**During Gap Analysis** (when modifying existing features): -Comprehensive analysis ensuring complete, usable features: - -**User Journey Impact Assessment**: -- **Feature Reachability**: Current vs new access paths, dead end analysis, discoverability scoring (1-10 scale) -- **Multi-Persona Analysis**: Per-persona workflow impact assessment with value/learning curve metrics -- **Flow Integration**: How enhancement fits existing workflows without disruption -- **Navigation Consistency**: Alignment with app-wide UI/navigation patterns -- **Discoverability Before/After**: Quantified improvement metrics showing usability impact - -**Data Entity Lifecycle Analysis**: -- **Three-Layer Verification Framework**: Backend capability + UI component + User accessibility (all required) -- **Backend ≠ User Operability**: API endpoints alone don't confirm users can actually perform operations -- **Orphaned Display Detection**: Flags features that display data with no way to input it (useless feature) -- **Orphaned Input Detection**: Flags data capture with nowhere to view/use it (user frustration) -- **Layer 3 Critical Checks**: Component rendering, page routing, navigation access, permissions -- **Multi-Touchpoint Discovery**: Finds ALL places where data should appear, not just user-mentioned locations -- **CRUD Completeness**: Ensures data has complete lifecycle with verified user accessibility -- **Scope Expansion Recommendations**: Suggests phased approach when critical gaps found -- **Safety-Critical Awareness**: Heightened analysis for healthcare, finance, legal domains - -**Why This Matters**: -- Prevents orphaned features that users can't find -- Ensures logical user flows and navigation -- Identifies discoverability issues early -- Analyzes impact from multiple persona perspectives -- Documents navigation integration concerns -- **Prevents incomplete features**: Catches "display allergy info" requests that lack input mechanisms -- **Ensures safety**: Identifies missing critical touchpoints (e.g., allergies in prescription workflow) - -**Real-World Example**: -User requests: "Display allergy info on patient summary" - -*Without data lifecycle analysis*: -- ✅ Implements display component -- ❌ No way to input allergies (feature useless) -- ❌ Missing from prescription workflow (safety issue) - -*With data lifecycle analysis*: -- ⚠️ Detects orphaned display (no input mechanism) -- ⚠️ Discovers 5 additional critical touchpoints (prescriptions, appointments, emergencies) -- ✅ Recommends phased approach: Phase 1 (input + 3 critical displays), Phase 2 (remaining displays), Phase 3 (edit/delete) -- ✅ Result: Complete, safe, usable feature - -**Output**: Ensures features are discoverable, accessible, complete, and logically integrated into the application - -### ASCII Mockup Generation - -For UI-heavy features/enhancements, the plugin can generate ASCII mockups: -- Shows how new UI integrates with existing layout structure -- Identifies reusable components from current codebase -- Visualizes navigation patterns and placement -- Annotates with actual component file references -- Ensures consistency with existing app patterns - -**When Used**: -- Optional phase in development workflow -- Auto-triggered when `task_characteristics.ui_heavy` is true -- Invoked automatically by development orchestrator - -**Output**: `analysis/design-context/ascii/ui-mockups.md` with ASCII diagrams, plus stable screen/component IDs appended to `analysis/design-context/INDEX.md` - -**Example**: -``` -┌──────────────────────────────────────┐ -│ Toolbar: [Existing] [Buttons] [NEW] │ -│ └─ Integration point here │ -└──────────────────────────────────────┘ -``` - -**Benefits**: -- Visualize layout before implementation -- Ensure consistency with existing UI -- Identify reusable components early -- Prevent navigation confusion -- No external design tools needed - -## Structure Organization - -### Separation of Concerns - -This plugin separates reference documentation from work items: - -**`.maister/docs/`** - Reference documentation (stable) -- Project vision, roadmap, tech stack -- Coding standards and conventions -- Architecture documentation -- Read these to understand the project - -**`.maister/tasks/`** - Work items (active, growing) -- Individual development tasks -- Feature implementations, bug fixes, etc. -- Active work in progress -- Create/reference these when building - -**Why separate?** -- Keeps INDEX.md focused on project understanding (not task lists) -- Better scalability (tasks grow independently from docs) -- Clearer navigation (docs = learn, tasks = work) -- Different lifecycle (docs = stable reference, tasks = active work) - -## Documentation & Task Organization - -### Project Documentation Structure - -The maister plugin uses this structure: - -``` -.maister/ -├── config.yml # Project configuration (optional; scaffolded by /maister-init) -├── docs/ # Reference documentation (stable) -│ ├── INDEX.md # Master index - READ THIS FIRST -│ ├── project/ # Project-level documentation -│ │ ├── vision.md # Project vision and goals -│ │ ├── roadmap.md # Development roadmap -│ │ ├── tech-stack.md # Technology choices and rationale -│ │ └── architecture.md # System architecture (optional) -│ └── standards/ # Technical standards and conventions -│ ├── global/ # Language-agnostic standards -│ ├── frontend/ # Frontend-specific standards -│ ├── backend/ # Backend-specific standards -│ └── testing/ # Testing standards -└── tasks/ # Development tasks (active, growing) - ├── development/ - ├── performance/ - ├── migrations/ - ├── research/ - └── product-design/ -``` - -**Core Principle**: -- Reference documentation in `.maister/docs/` is the source of truth for understanding the project -- Always read `docs/INDEX.md` first to understand available documentation and standards -- Development tasks live separately in `.maister/tasks/` for better organization and scalability - -### Project Configuration (`.maister/config.yml`) - -An optional project-level config file holds defaults that apply to every workflow. `/maister-init` scaffolds it with documented defaults; orchestrators read it at initialization and fall back to defaults when it is absent (so existing projects are unaffected). - -```yaml -html_output: true # Generate the operator dashboard + HTML companion reports. false = markdown-only. -``` - -- **`html_output`** (default `true`): when `false`, workflows skip the operator dashboard (`dashboard.html`/`dashboard-data.js`, no browser auto-open) AND the HTML companion reports (`.html` twins). Markdown artifacts, their `## TL;DR` summary blocks, `orchestrator-state.yml`, and product-design's visual mockups are produced regardless. The value is read once at init and seeded into `orchestrator.options.html_output` in state. - -**See**: `skills/orchestrator-framework/references/orchestrator-patterns.md` § 4 "Project Configuration" for the read/seed/gate mechanism. - -### Development Task Organization - -Development tasks are organized by workflow type in `.maister/tasks/`: - -``` -.maister/tasks/ -├── development/ -│ └── YYYY-MM-DD-task-name/ -├── performance/ -│ └── YYYY-MM-DD-task-name/ -├── migrations/ -│ └── YYYY-MM-DD-task-name/ -├── research/ -│ └── YYYY-MM-DD-task-name/ -└── product-design/ - └── YYYY-MM-DD-task-name/ -``` - -**Benefits of workflow-based organization:** -- Clear routing to orchestrator -- Date-prefixed naming provides chronological sorting -- Scales well to 100s of tasks - -### Base Task Structure - -Each development task follows a common structure with core directories: - -``` -YYYY-MM-DD-task-name/ -├── orchestrator-state.yml # Execution state and task metadata -├── dashboard.html # Operator dashboard (copied plugin asset — never model-generated) -├── dashboard-data.js # Dashboard data projection (rewritten after each phase/gate) -├── analysis/ # Analysis and planning artifacts -│ ├── research-context/ # From research (if --research provided) -│ │ └── research-report.md # Full research findings -│ ├── design-context/ # Mockups and design artifacts (when present — see below) -│ │ ├── mockups/ # HTML/PNG/screenshots (from product-design or inline prompt refs) -│ │ ├── ascii/ # ASCII mockups generated by ui-mockup-generator -│ │ ├── brief.md # Product brief (when handed off from product-design task) -│ │ ├── external-links.md # Figma/Sketch/Zeplin URLs -│ │ └── INDEX.md # Screen/component inventory with stable IDs -│ └── requirements.md # Gathered requirements -├── implementation/ # Implementation work -│ ├── spec.md # Main specification (WHAT to build) -│ ├── spec.html # Operator-facing HTML companion -│ ├── implementation-plan.md # Implementation steps breakdown (HOW to build) -│ ├── implementation-plan.html # Operator-facing HTML companion -│ ├── visual-coverage.md # Coverage matrix (when design-context exists) -│ └── work-log.md # Chronological activity log -├── verification/ # Verification results -│ ├── spec-audit.md # Independent spec audit (conditional, complex tasks only) -│ └── visual-fidelity.md # Mockup-vs-rendered comparison (when design-context exists, report-only) -└── documentation/ # User-facing docs (if applicable) -``` - -### Operator Visibility Layer - -Workflow artifacts accumulate deep detail for subagent context — the operator monitoring layer distills them: - -1. **Artifact Summary Contract**: every markdown artifact opens with `## TL;DR` (max 5 lines) + `## Key Decisions` + `## Open Questions / Risks` (sections omitted when empty). Operators read the first 20 lines of any artifact; full detail follows unchanged. -2. **Operator Dashboard**: each task root carries `dashboard.html` (static plugin asset from `skills/orchestrator-framework/assets/`, never model-generated) + `dashboard-data.js` (terse projection of state, rewritten after each phase/gate). Open the HTML in a browser — phase timeline, decisions/risks, verification status, artifact deep-links; auto-refreshes every 5s, works from `file://` with no server. -3. **HTML Companion Reports**: high-value artifacts (spec, implementation plan, verification reports) get a rich HTML twin written by the same subagent that writes the md, following the shared style guide (`skills/orchestrator-framework/references/html-report-style.md`). The md stays the source of truth for subagents; HTML is for humans. Companions never block the workflow. - -**See**: `skills/orchestrator-framework/references/orchestrator-patterns.md` § 7-9 for the full contracts and the `dashboard-data.js` schema. - -**Design context** (`analysis/design-context/`) is auto-populated by the development orchestrator's Step 4 when: -- The argument is a product-design task path (mockups + brief copied in) -- The task description references mockup file paths (auto-ingested) or design-tool URLs (recorded) -- `task_characteristics.ui_heavy` is true and no external mockups exist (Phase 4 generates ASCII into `design-context/ascii/`) - -When present, mockups are **binding inputs** to implementation — the planner attaches `Visual References` to UI task groups, the implementer reads each mockup before coding, and Phase 12 produces a structural visual-fidelity report. When no mockups exist, the entire `design-context/` directory is omitted and behavior is unchanged. - -**See**: `skills/development/SKILL.md` § "Design-Informed Development" for the full propagation model. - -Task types can add specialized subdirectories as needed (e.g., `analysis/bug-analysis/` for bug fixes, `implementation/metrics/` for performance tasks). - -**Note**: The `implementation/implementation-plan.md` file contains implementation steps (the detailed breakdown of actions), created by the implementation-planner subagent after the specification is approved. - -### Naming Conventions - -**Workflow Type Directories:** -- Use workflow names: `development/`, `performance/`, `migrations/`, `research/`, `product-design/` - -**Task Directories:** -- Format: `YYYY-MM-DD-task-name` -- Example: `2025-10-23-user-authentication` -- Example: `2025-10-23-fix-login-timeout` -- Date prefix enables chronological sorting -- Concise but descriptive name (3-5 words) - -### Integration - -- **Documentation Discovery**: Always read `.maister/docs/INDEX.md` before starting work to understand project context -- **Task Discovery**: Browse `.maister/tasks/` to find development tasks by workflow type -- **Standards Compliance**: Follow standards from `.maister/docs/standards/` during implementation -- **Task Tracking**: Task status, priority, tags, and time tracking are in the `task:` section of `orchestrator-state.yml` -- **Activity Logging**: Record work in `implementation/work-log.md` for transparency - -## Plugin Documentation Principles - -These principles guide how we document skills, commands, orchestrators, and agents in this plugin to avoid verbosity and duplication while trusting Claude to reason effectively. - -### Philosophy - -**Trust Claude to reason.** Provide principles and patterns, not prescriptive implementations. Claude can discover technical details from skill.md files when needed—CLAUDE.md and commands should guide thinking, not dictate exact steps. - -### Core Principles - -1. **No Verbose Pseudocode** - Show conceptual patterns and decision frameworks, not complete implementations -2. **No Prescriptive Templates** - Guide thinking with principles, don't dictate exact prompts or scripts -3. **Avoid Duplication** - If technical details exist in skill.md, reference them in CLAUDE.md/commands -4. **Commands as Thin Wrappers** - User-facing guidance in commands, technical orchestration logic in skills -5. **Single Source of Truth** - Orchestration logic lives in skill.md, not scattered across multiple files -6. **Principle Over Process** - Explain WHY and WHEN, trust Claude to figure out HOW - -### Content Guidelines - -Target lengths for different documentation types: - -| Documentation Type | Target Length | Focus | -|-------------------|---------------|-------| -| Skill descriptions (in CLAUDE.md) | 5-15 lines | Purpose, key capabilities, philosophy | -| Command descriptions (in CLAUDE.md) | 3-8 lines | What it does, when to use | -| Orchestrator sections (in CLAUDE.md) | 20-30 lines | Overview, key features, reference skill | -| Reference files (in skills/) | <1,000 lines | Conceptual patterns, not implementations | -| Agent files (in agents/) | 300-450 lines | Core mission, decision frameworks, workflow principles | -| Individual standards (### sections in standard files) | 1-10 lines (excluding code snippets) | ### heading + description + optional code example. Multiple standards per topic file. | - -### When Adding New Content - -Ask these questions before documenting: - -1. **"Does this duplicate skill.md content?"** → Reference instead of duplicating -2. **"Am I providing exact implementation?"** → Simplify to principles -3. **"Would Claude need this spelled out?"** → Probably not, trust reasoning ability -4. **"Is this a manual or guidance?"** → Should be guidance, not manual - -### Examples - -**❌ Too Verbose** (Manual approach): -```markdown -**Process**: -1. Initialize: Check prerequisites, load state, validate inputs -2. Analyze: Parse task description, extract key entities, determine scope -3. Plan: Create task groups, define dependencies, set milestones -4. Execute: For each group: (a) run tests, (b) implement, (c) verify -5. Finalize: Generate report, update metadata, commit changes -``` - -**✅ Principle-Based** (Guidance approach): -```markdown -Orchestrates implementation from plan to verified code. Delegates each task group to subagent, maintains continuous standards discovery, follows test-driven approach. - -**See**: `skills/implementation-plan-executor/SKILL.md` for execution model and technical details. -``` - -## Reference Documentation Guidelines - -Reference files (`references/*.md`) in skills provide conceptual patterns and decision frameworks. They guide implementation rather than provide complete code. - -### Purpose of References - -References should answer: -- **WHAT** patterns to use (strategies, approaches) -- **WHEN** to apply them (decision criteria) -- **WHY** certain approaches work (rationale) -- **HOW** (conceptually) to structure solutions (high-level) - -References should NOT contain: -- Complete function implementations -- Production-ready code (>10 lines) -- Extensive pseudocode implementations -- Framework-specific boilerplate - -### Size Guidelines - -| Reference Type | Target Size | Max Size | Token Budget | -|---------------|-------------|----------|--------------| -| Orchestrator phase reference | 600-800 lines | 1,000 lines | ~8K tokens | -| Algorithm pattern reference | 400-600 lines | 800 lines | ~6K tokens | -| Strategy/decision reference | 300-500 lines | 600 lines | ~4K tokens | - -**Total per skill**: Aim for <3,000 lines across all references (~24K tokens) - -### Content Structure - -**✅ Good Reference Style** (Conceptual): -```markdown -### Algorithm: Feature Detection - -**Purpose**: Locate existing files using multi-strategy search - -**Strategy**: -1. **Filename search**: Extract nouns → Generate patterns → Glob search -2. **Code pattern search**: Detect tech hints → Search for patterns → Grep -3. **Scoring**: Combine filename match + directory + size + tests + usage - -**Decision Criteria**: -- High confidence (>80%): Present top 3 matches -- Medium confidence (50-80%): Present top 5 with warnings -- Low confidence (<50%): Expand search or prompt user - -**Output**: Ranked list with confidence scores -``` - -**❌ Bad Reference Style** (Implementation): -```python -def detect_feature_files(description, codebase_root): - """Complete 100-line implementation""" - tokens = tokenize(description) - patterns = [] - for token in tokens: - # 50+ lines of detailed logic - patterns.append(generate_pattern(token)) - # More implementation details... - return scored_results -``` - -### When to Use Code Examples - -Acceptable scenarios for code examples (keep <10 lines): -- **Test patterns**: Show expected test structure -- **Configuration examples**: YAML/JSON structure samples -- **API usage**: Brief integration examples -- **Decision pseudocode**: If-then logic (5-10 lines max) - -### Review Checklist - -Before finalizing reference documentation: - -✓ Does this explain WHAT/WHEN/WHY rather than implement HOW? -✓ Are code examples <10 lines and conceptual? -✓ Is total file size under target guidelines? -✓ Could an experienced developer implement from this guide? -✓ Is it tool/framework agnostic where possible? -✓ Does it focus on patterns over implementation? - -### Philosophy - -**References are maps, not detailed instructions.** -- Maps show landmarks, routes, decision points -- Instructions show every step, every turn -- Skills/agents follow the map to create their own path - -## Orchestrator Creation Guidelines - -When creating or auditing orchestrators, follow the patterns established in existing orchestrators and consult the framework reference files. - -**See**: `skills/orchestrator-framework/references/orchestrator-creation-checklist.md` for the complete creation checklist and anti-patterns. -**See**: `skills/orchestrator-framework/references/orchestrator-patterns.md` for execution rules, schemas, and patterns. - -## Available Skills - -Skills are automatically invoked by Claude when appropriate. Details live in each skill's `skill.md` file. - -### Core Workflow Skills - -| Skill | Purpose | Details | -|-------|---------|---------| -| `codebase-analyzer` | Thin dispatcher: selects agent roles adaptively, launches parallel Explore subagents, delegates report synthesis to `codebase-analysis-reporter` subagent | `skills/codebase-analyzer/SKILL.md` | -| `implementation-verifier` | Read-only QA orchestrator: delegates completeness checks, test execution, code review, and production readiness to specialized subagents; compiles results into verification report | `skills/implementation-verifier/SKILL.md` | -| `standards-discover` | Parallel multi-source standards discovery (config, code, docs, PRs/CI) with confidence scoring | `skills/standards-discover/SKILL.md` | -| `docs-manager` | Internal engine for doc file operations, INDEX.md generation, CLAUDE.md integration. Not user-invocable — accessed via `docs-operator` agent (Task tool) by init, standards-update, standards-discover | `skills/docs-manager/skill.md` | -| `maister-init` | Initialize `.maister/docs/` with project analysis, documentation generation, and baseline standards | `skills/init/SKILL.md` | -| `standards-update` | Update or create standards from conversation context or explicit input | `skills/standards-update/SKILL.md` | -| `quick-plan` | Built-in plan mode + standards enforcement: discovers matched standards from INDEX.md during planning and folds a Standards Compliance Checklist into the plan | `skills/quick-plan/SKILL.md` | -| `quick-dev` | Direct main-agent development (no plan mode) + standards enforcement: applies matched standards while implementing and verifies compliance after | `skills/quick-dev/SKILL.md` | -| `quick-bugfix` | Quick TDD-driven bug fix with complexity escalation to full development workflow | `skills/quick-bugfix/SKILL.md` | - -### Orchestrator Framework - -All orchestrators share patterns documented in a single reference file: - -| File | Purpose | -|------|---------| -| `orchestrator-patterns.md` | Delegation rules, interactive mode, state schema, context passing, initialization, resume, issue resolution, artifact summary contract (§ 7), operator dashboard (§ 8), HTML companion reports (§ 9) | -| `orchestrator-creation-checklist.md` | Authoring checklist for new orchestrators (not loaded at runtime) | -| `html-report-style.md` | Shared style guide for HTML companion reports (standard CSS, severity badges, per-artifact layouts) | -| `assets/dashboard.html` | Static operator dashboard viewer, copied into each task directory at workflow init (never model-generated) | - -Each orchestrator reads `orchestrator-patterns.md` at initialization and implements domain-specific phases. Key principles: state-driven execution, resume capability, interactive phase gates, user-confirmed rollback, context passing between phases via `phase_summaries`, delegation enforcement (Skill tool for skills, Task tool for agents). - -### Orchestrator Skills - -Orchestrators manage complete workflows with state management, auto-recovery, and pause/resume. - -| Skill | Purpose | Details | -|-------|---------|---------| -| `development` | **Unified workflow** (14 phases: 1-14) for all development tasks. Phases activate based on detected task characteristics (not predetermined types). TDD gates activate when defects detected, UI mockups when UI-heavy. | `skills/development/SKILL.md` | -| `performance` | Static code analysis for bottleneck detection, reuses standard spec/plan/implement/verify pipeline | `skills/performance/SKILL.md` | -| `migration` | Code/data/architecture migrations with rollback plans | `skills/migration/SKILL.md` | -| `research` | Multi-source research with synthesis, solution brainstorming, high-level design, and citations | `skills/research/SKILL.md` | -| `product-design` | **Interactive product/feature design** (9 phases: 0-8) with adaptive scope (feature-level default, product-level when detected), mixed interaction pattern (questioning for exploration, propose-and-refine for convergence), iterative refinement loops, browser-based visual companion, and layered product brief output. | `skills/product-design/SKILL.md` | - -## Available Commands - -Commands invoke orchestrators and utilities. All orchestrators support `--from=phase` (resume point). - -### Setup & Standards - -| Command | Usage | Purpose | -|---------|-------|---------| -| `/maister-init` | `/maister-init [--standards-from=PATH]` | Initialize framework with project analysis and smart defaults for docs/standards. Optionally copy standards from another project's `.maister/docs/standards/` instead of built-in defaults. | -| `/maister-standards-update` | `/maister-standards-update [description] [--from=PATH]` | Update/create standards from conversation context, or sync from another project | -| `/maister-standards-discover` | `/maister-standards-discover [--scope=SCOPE]` | Discover standards from config files and code patterns | - -> **Note**: These are all skills (not commands). `/maister-init`, `/maister-standards-update`, and `/maister-standards-discover` invoke their respective skills which delegate file operations to the internal `docs-manager` skill. - -### Workflow Commands - -Each workflow skill handles both new tasks and resuming existing ones. Pass a task description to start new, or a task path to resume. - -| Command | Usage | Task Directory | -|---------|-------|----------------| -| `/maister-development` | `[desc] [--e2e] [--user-docs] [--research=PATH] [--sequential]` (new) / `[task-path] [--from=PHASE] [--reset-attempts] [--sequential]` (resume) | `.maister/tasks/development/` | -| `/maister-performance` | `[desc] [--sequential]` (new) / `[task-path] [--from=PHASE] [--sequential]` (resume) | `.maister/tasks/performance/` | -| `/maister-migration` | `[desc] [--type=TYPE] [--sequential]` (new) / `[task-path] [--from=PHASE] [--sequential]` (resume) | `.maister/tasks/migrations/` | -| `/maister-research` | `[question] [--type=TYPE] [--brainstorm] [--no-brainstorm] [--design] [--no-design]` (new) / `[task-path] [--from=PHASE]` (resume) | `.maister/tasks/research/` | -| `/maister-product-design` | `[desc] [--research=PATH] [--no-visual]` (new) / `[task-path] [--from=PHASE]` (resume) | `.maister/tasks/product-design/` | - -**Research-Based Development**: Start development informed by a completed research workflow: -```bash -# Auto-detect research folder (recommended) -/maister-development .maister/tasks/research/2026-01-12-oauth-research - -# Explicit --research flag -/maister-development "Implement OAuth" --research=.maister/tasks/research/2026-01-12-oauth-research -``` -Research context flows through ALL phases without skipping any. Research artifacts are copied to `analysis/research-context/` and summaries pass to every subagent via Pattern 7. - -### Review & Audit Commands - -| Command | Usage | Purpose | -|---------|-------|---------| -| `/maister-reviews-code` | `[path] [--scope=SCOPE]` | Automated code quality, security, performance analysis | -| `/maister-reviews-pragmatic` | `[path]` | Detect over-engineering, ensure code matches project scale | -| `/maister-reviews-spec-audit` | `[spec-path]` | Independent spec audit for completeness and clarity | -| `/maister-reviews-reality-check` | `[task-path]` | Validate work actually solves the problem | -| `/maister-reviews-production-readiness` | `[path] [--target=ENV]` | Pre-deployment verification with GO/NO-GO recommendation | - -### Quick Commands - -| Command | Usage | Purpose | -|---------|-------|---------| -| `/maister-quick-plan` | `[task description]` | Enter planning mode with standards awareness from INDEX.md | -| `/maister-quick-dev` | `[task description]` | Implement directly with standards awareness (no planning) | -| `/maister-quick-bugfix` | `[bug description]` | Quick bug fix with TDD red/green gates and complexity escalation | - -**See**: Individual `commands/` and `skills/*/skill.md` files for detailed documentation. - -## Available Subagents - -Subagents are specialized AI agents invoked by skills and orchestrators. All agents are read-only unless specified. - -### Initialization & Analysis Agents - -| Agent | Purpose | Invoked By | Details | -|-------|---------|------------|---------| -| `project-analyzer` | Deep codebase analysis for tech stack, architecture, conventions | `/maister-init` | `agents/project-analyzer.md` | -| `docs-operator` | Internal service agent: executes docs-manager operations mid-workflow via Task tool. Has docs-manager skill preloaded. **Special case**: companion agent pattern only works here because docs-manager does NOT spawn subagents (only file operations). Do not use this pattern for skills that spawn subagents. | init, standards-update, standards-discover | `agents/docs-operator.md` | -| `task-classifier` | Classifies task descriptions into workflow types with confidence scoring | `/work` command | `agents/task-classifier.md` | -| `gap-analyzer` | Compares current vs desired state with characteristic-detection-based analysis modules | development orchestrator | `agents/gap-analyzer.md` | -| `specification-creator` | Creates specs from gathered requirements with reusability search and self-verification | development, migration orchestrators | `agents/specification-creator.md` | -| `implementation-planner` | Breaks specs into task groups with test-driven steps and dependency chains | development, migration orchestrators | `agents/implementation-planner.md` | -| `codebase-analysis-reporter` | Merges raw Explore agent findings into structured analysis report with deduplication, cross-referencing, and risk assessment | codebase-analyzer skill | `agents/codebase-analysis-reporter.md` | - -**Deprecated Agent**: -- `existing-feature-analyzer` → Replaced by `codebase-analyzer` skill (uses adaptive parallel Explore subagents) - -### UI & Documentation Agents - -| Agent | Purpose | Invoked By | Details | -|-------|---------|------------|---------| -| `ui-mockup-generator` | ASCII mockups showing UI integration with existing layouts | development orchestrator (feature/enhancement), product-design orchestrator (Phase 7 ASCII fallback) | `agents/ui-mockup-generator.md` | -| `e2e-test-verifier` | Runtime browser verification via Playwright MCP tools (not test file generation) | development orchestrator (optional) | `agents/e2e-test-verifier.md` | -| `user-docs-generator` | User documentation with Playwright screenshots | development orchestrator (optional) | `agents/user-docs-generator.md` | -| `html-companion-writer` | Generates an HTML companion report from one finalized markdown artifact (style-guide compliant). For orchestrators that write artifacts inline and have no producing subagent to attach a companion to. | product-design orchestrator (Phases 5/6/8) | `agents/html-companion-writer.md` | - -### Performance Agents - -| Agent | Purpose | Invoked By | Details | -|-------|---------|------------|---------| -| `bottleneck-analyzer` | Static code analysis detecting N+1 queries, missing indexes, O(n^2) algorithms, blocking I/O, memory leak patterns. Optionally incorporates user-provided profiling data. | performance orchestrator | `agents/bottleneck-analyzer.md` | - -### Research Agents - -| Agent | Purpose | Invoked By | Details | -|-------|---------|------------|---------| -| `research-planner` | Creates methodology and identifies sources | research orchestrator | `agents/research-planner.md` | -| `information-gatherer` | Multi-source data collection with citations | research orchestrator, product-design orchestrator (Phase 1 mini-research) | `agents/information-gatherer.md` | -| `research-synthesizer` | Pattern identification, insights generation | research orchestrator | `agents/research-synthesizer.md` | -| `solution-brainstormer` | Solution alternatives with multi-perspective trade-off analysis | research orchestrator, product-design orchestrator | `agents/solution-brainstormer.md` | -| `solution-designer` | High-level C4 architecture design and ADR documentation | research orchestrator | `agents/solution-designer.md` | - -### Verification Agents - -| Agent | Purpose | Invoked By | Details | -|-------|---------|------------|---------| -| `implementation-completeness-checker` | Plan completion + standards compliance + documentation completeness | implementation-verifier | `agents/implementation-completeness-checker.md` | -| `test-suite-runner` | Runs full test suite, analyzes results, flags regressions | implementation-verifier | `agents/test-suite-runner.md` | -| `code-reviewer` | Automated code quality, security, performance analysis | implementation-verifier, standalone command | `agents/code-reviewer.md` | -| `production-readiness-checker` | Pre-deployment verification with GO/NO-GO recommendation | implementation-verifier, performance orchestrator, standalone command | `agents/production-readiness-checker.md` | - -### Review & Audit Agents - -| Agent | Purpose | Invoked By | Details | -|-------|---------|------------|---------| -| `code-quality-pragmatist` | Detects over-engineering, ensures scale-appropriate code | implementation-verifier | `agents/code-quality-pragmatist.md` | -| `spec-auditor` | Independent spec audit with senior auditor perspective | orchestrators | `agents/spec-auditor.md` | -| `reality-assessor` | Validates work actually solves the problem | implementation-verifier | `agents/reality-assessor.md` | - -**See**: Individual `agents/*.md` files for detailed workflows and philosophies. - -## Key Workflow Principles - -1. **Documentation First**: Always check docs/INDEX.md before and during work -2. **Specification Before Implementation**: Create clear specs before coding -3. **Planning Before Execution**: Break implementation into manageable steps -4. **Test-Driven Approach**: Write tests first, implement, then verify -5. **Continuous Standards Discovery**: Check standards throughout, not just at start -6. **Incremental Verification**: Run only new tests after each group, not entire suite -7. **Comprehensive Verification Before Commit**: Run full test suite and create verification report before code review -8. **Task Directory Artifact Anchoring**: ALL workflow artifacts (reports, documentation, screenshots) MUST be saved under the task directory (`.maister/tasks/[type]/[task-name]/`). NEVER save task artifacts to project directories like `docs/`, `src/`, or project root. - -**For detailed workflow documentation, see**: individual skill `SKILL.md` files - -## Progress Tracking with Task System - -All orchestrators use `TaskCreate`/`TaskUpdate` for real-time progress visibility at two levels: - -### Orchestrator Phase Tracking - -- At workflow start: `TaskCreate` for all phases (pending), then `TaskUpdate addBlockedBy` for phase dependencies -- At each phase: `TaskUpdate` to `in_progress` (shows spinner with `activeForm`) → execute → `TaskUpdate` to `completed` -- Optionally set `owner` when delegating to skills/agents, and `metadata` for timing/artifacts -- State file (`orchestrator-state.yml`) is source of truth for resume logic -- Task system mirrors state for UX and provides dependency visualization - -### Implementation Task Group Tracking - -- At planning: `TaskCreate` for each task group with `Dependencies` AND `Files to Modify` declared in `implementation-plan.md` -- During execution: executor computes parallel waves from dependencies + file overlap, then dispatches all groups in a wave concurrently via parallel `Task` tool calls. The `--sequential` flag (read from `orchestrator-state.yml` as `orchestrator.options.sequential`) forces the legacy one-at-a-time loop -- `TaskUpdate` to `in_progress` on wave dispatch → execute → `TaskUpdate` to `completed` on each group's return -- Markdown checkboxes in `implementation-plan.md` remain the step-level source of truth -- Task system provides group-level visibility with dependencies, timing, ownership, and wave membership - -See individual orchestrator `skill.md` files for phase-specific task tables. - -## Hooks - -The plugin includes hooks that fire at specific Claude Code lifecycle events. - -### Post-Compaction State Reminder - -**Hook**: `SessionStart` (matcher: `compact`) -**Location**: `hooks/post-compact-reminder.sh` - -This hook fires after context compaction and injects a reminder into Claude's context to check the `orchestrator-state.yml` file for the active workflow. - -**Purpose**: Reminds Claude to check `orchestrator-state.yml` for completed phases and use ask_user at phase gates after compaction, regardless of any "continue without asking" instructions in the compacted context. - -**See**: `hooks/hooks.json` for hook configuration (auto-discovered by Claude Code). - -### Destructive Command Protection - -**Hook**: `PreToolUse` (matcher: `Bash`) -**Location**: `hooks/block-destructive-commands.sh` - -Blocks destructive shell commands (`git stash`, `git reset --hard`, `git checkout .`, `git clean`, `git push --force`, `rm -rf`) from subagents that should not perform such operations. Uses a whitelist approach — only explicitly trusted execution agents bypass the check: - -**Unprotected agents** (full Bash access): `test-suite-runner`, `e2e-test-verifier`, `user-docs-generator`, `docs-operator` - -`task-group-implementer` is **not** whitelisted. It runs implementation code under the same destructive-command guard as ordinary agents to prevent rogue `git stash` / `reset --hard` from clobbering sibling implementers in a parallel wave (see "Implementation Task Group Tracking" above). - -All other agents and the main agent pass through normally. When adding a new agent that needs full Bash access, add it to the `case` statement in the hook script. - -## Claude Code Documentation - -**IMPORTANT**: Always consult the latest Claude Code documentation when working with plugins and skills. The documentation is regularly updated with new features, best practices, and implementation details. - -### Essential Reading - -Before working with this plugin, read the following up-to-date documentation: - -1. **Plugins Overview**: https://code.claude.com/docs/en/plugins - - Understanding plugin architecture and capabilities - - How plugins extend Claude Code functionality - - Plugin installation and configuration - -2. **Skills Documentation**: https://code.claude.com/docs/en/skills - - How to create and use skills effectively - - Skill best practices and patterns - - Skill discovery and invocation - -3. **Plugins Reference**: https://code.claude.com/docs/en/plugins-reference - - Complete plugin API reference - - Plugin structure and requirements - - Available plugin features and hooks - -4. **Sub-agents/Agents documentation**: https://code.claude.com/docs/en/sub-agents https://code.claude.com/docs/en/plugins-reference#agents - - Sub-agent architecture and capabilities - - Agent definition and tool access - -5. **Built-in tools** available for usage: https://gist.github.com/bgauryy/0cdb9aa337d01ae5bd0c803943aa36bd - -### Documentation Priority - -When implementing or modifying plugin features: -1. **Current official documentation** (links above) - Always check for latest updates -2. **Project-specific documentation** (this file and .maister/docs/) -3. **Code patterns** in this plugin's codebase -4. **General best practices** - -**Note**: Claude Code is actively developed. Always verify implementation details against the current documentation before making changes. - -## Platform: Copilot CLI - -This is the Copilot CLI variant. Key differences from Claude Code: -- **No multi-select**: When asking users to select multiple options, ask sequential single-select questions instead -- **Command names**: No plugin prefix in names (e.g., `development`); the plugin system adds the plugin-id prefix automatically -- **Project instructions file**: Use `.github/copilot-instructions.md` instead of `CLAUDE.md`. If the project uses `AGENTS.md`, support that as well. -- **User questions**: Use `ask_user` tool instead of `ask_user` diff --git a/plugins/maister-copilot/agents/e2e-test-verifier.md b/plugins/maister-copilot/agents/e2e-test-verifier.md deleted file mode 100644 index 9a21dfca..00000000 --- a/plugins/maister-copilot/agents/e2e-test-verifier.md +++ /dev/null @@ -1,612 +0,0 @@ ---- -name: e2e-test-verifier -description: Executes runtime browser verification using Playwright MCP tools to verify implementation behavior against specifications. Does NOT generate test files — performs live interactive verification with evidence collection. -model: inherit -color: green ---- - -# E2E Test Verifier - -This agent performs **runtime browser verification** using Playwright MCP tools — it navigates pages, interacts with UI elements, captures screenshots, and validates behavior against specifications. It does NOT write Playwright test files (`.spec.ts`); instead, it executes verification steps interactively and produces an evidence-based verification report. - -## Purpose - -The E2E test verifier ensures implementations work from the user's perspective by: -- Verifying user stories and acceptance criteria from specifications via live browser interaction -- Executing real browser-based workflows using Playwright MCP tools (navigate, click, fill, screenshot) -- Capturing visual evidence of behavior at each step -- Reporting discrepancies between specification and implementation -- Validating complete user journeys, not just isolated functions - -This agent focuses on **evidence-based runtime verification**, not test file generation. - -## Core Responsibilities - -1. **Requirement Extraction**: Convert specifications into concrete, testable scenarios -2. **Test Scenario Planning**: Organize tests by category (happy path, error handling, edge cases, integration) -3. **Browser Test Execution**: Execute Playwright tests using MCP tools to verify UI behavior -4. **Evidence Collection**: Capture screenshots and console messages at significant steps -5. **Spec Alignment Analysis**: Compare actual behavior against specification requirements -6. **Comprehensive Reporting**: Document findings with evidence and severity categorization - -## Input Parameters - -| Parameter | Source | Description | -|-----------|--------|-------------| -| `task_path` | Orchestrator | **Absolute path** to task directory. ALL outputs MUST be written under this path. | -| `spec_path` | Orchestrator | Path to spec.md | -| `base_url` | Orchestrator | Application base URL for Playwright | -| `design_context_path` | Orchestrator (optional) | Path to `analysis/design-context/` when mockups are present. Triggers visual-fidelity comparison (Step 7) and writes `verification/visual-fidelity.md`. | -| `html_style_guide_path` | Orchestrator | Absolute path to `html-report-style.md` (for the HTML companion reports, Step 8) | - -**CRITICAL**: Always use `task_path` as the root for ALL file writes. Save report to `{task_path}/verification/e2e-verification-report.md`, screenshots to `{task_path}/verification/screenshots/`, visual fidelity report to `{task_path}/verification/visual-fidelity.md` (when design_context_path provided). NEVER write to project-level directories. - ---- - -## Workflow - -### 1. Extract Requirements from Specification - -**Purpose**: Understand what needs verification - -**Key Actions**: -- Read specification file (spec.md in task directory) -- Extract user stories with their acceptance criteria -- Identify expected behaviors, workflows, UI interactions -- Note data inputs/outputs and error handling requirements - -**Conversion Approach**: Transform each user story into testable scenarios -- User action (what they do) → Test steps (how to execute) -- Expected outcome (what should happen) → Verification points (how to verify) -- Acceptance criteria → Assertions - -**Output**: List of testable scenarios derived from specification - ---- - -### 2. Plan Test Scenarios - -**Purpose**: Organize systematic test execution - -**Test Categories**: - -**Happy Path Tests**: -- Primary user workflows -- Expected inputs and outputs -- Most common use cases - -**Error Handling Tests**: -- Invalid inputs and missing fields -- Server errors and network failures -- Validation behavior - -**Edge Case Tests**: -- Boundary values and maximum lengths -- Special characters and empty states -- Unusual but valid inputs - -**Integration Tests**: -- Multi-step workflows -- Cross-feature interactions -- Data persistence across pages - -**Execution Order**: Start with happy paths (validates core functionality), then error handling (validates robustness), then edge cases (validates boundaries), finally integration (validates complete workflows) - -**Output**: Organized test plan with categorized scenarios - ---- - -### 3. Execute Browser Verification Steps - -**Purpose**: Run browser tests and gather evidence - -**For Each Test Scenario**: - -**Navigation**: Use `mcp__playwright__navigate` to load application pages - -**Interaction**: Use `mcp__playwright__click` and `mcp__playwright__fill` for user actions - -**Verification**: Use `mcp__playwright__evaluate` to check DOM state, element visibility, content - -**Evidence Collection**: Use `mcp__playwright__screenshot` after significant steps - -**Console Monitoring**: Use `mcp__playwright__console_messages` to detect errors - -**Execution Pattern**: -1. Navigate to starting page -2. Capture initial state screenshot -3. Execute each test step (click, fill, submit) -4. Screenshot after significant actions -5. Verify expected outcomes using DOM queries -6. Check console for errors -7. Track pass/fail for each step - -**Screenshot Naming**: Use `[step-number]-[description]` format (e.g., `01-initial-page.png`, `02-form-filled.png`) - -**Selector Strategies**: Prefer data-testid attributes, then role/accessible name, then text matching as fallback - -**Output**: Verification results with screenshots and console messages - ---- - -### 4. Verify Results Against Specification - -**Purpose**: Compare expected behavior (from spec) with actual behavior (from tests) - -**Analysis Approach**: -- Check each acceptance criterion against test results -- Identify discrepancies with evidence (screenshots, console logs) -- Categorize findings by severity: - - **Critical**: Feature completely broken, blocks usage - - **Major**: Significant functionality missing or incorrect - - **Minor**: Small issues with workarounds - - **Cosmetic**: Visual issues without functional impact - -**For Each Issue**: -- What specification says should happen -- What actually happened in test -- Evidence (screenshot references, console messages) -- Impact on user experience -- Hypothesis about root cause - -**Output**: Categorized list of discrepancies with evidence - ---- - -### 5. Generate Verification Report - -**Purpose**: Create a consistent, evidence-based report. The report MUST follow the canonical 12-section template below — same headings, same order, every run. This is what downstream phases, code reviews, and humans depend on. - -**Save Location**: `[task-path]/verification/e2e-verification-report.md` - -**Strict rules** (apply on every run, no exceptions): - -1. Include **all 12 sections** in the numbered order shown below. Do not omit, do not add, do not reorder. The only content allowed before `## 1. Identifier` is the unnumbered TL;DR preamble shown in the template (Artifact Summary Contract). -2. Use the **exact heading text** shown (including the `## N. Title` numbering). -3. If a section has no content, write `_None observed._` (or `_None._` where the template indicates) — do **NOT** delete the heading. -4. Severity is exactly one of: **Critical · Major · Minor · Cosmetic** (matches §4 severity ladder). No "warning", "blocker", or other synonyms. -5. Status icons are exactly: **✅** (passed/match) · **⚠️** (passed with issues / minor deviation) · **❌** (failed/drift). No other glyphs. -6. Verdict is exactly one of: **GO · GO WITH CAVEATS · NO-GO**. -7. Screenshot references use the relative path form `screenshots/{filename}.png` — never absolute paths, never `verification/screenshots/…`. -8. Executive Summary metrics must be arithmetically consistent: `planned ≥ executed`, `executed = passed + failed + blocked`. - -#### Canonical Report Template - -````markdown -# E2E Verification Report - -## TL;DR -[3-5 lines max — verdict, pass/fail counts, headline finding. Conclusions, not process.] - -## Open Questions / Risks -[Top critical/major findings the operator should know about — one bullet each. Omit section entirely when none.] - -## 1. Identifier -- **Task**: {task-name} -- **Task path**: {task_path} -- **Spec**: {spec_path} -- **Date**: {YYYY-MM-DD} -- **Git ref**: {short SHA + branch} -- **Tester**: e2e-test-verifier (maister) - -## 2. Test Environment -| Field | Value | -|---|---| -| Base URL | {base_url} | -| Browser | {playwright browser + version} | -| Viewport | {width}×{height} | -| Auth context | {anonymous / role-name / user identifier} | -| Test data | {seeded / fixture / live} | - -## 3. Executive Summary -**Verdict**: ✅ GO | ⚠️ GO WITH CAVEATS | ❌ NO-GO *(pick exactly one)* - -| Metric | Count | -|---|---| -| Scenarios planned | N | -| Scenarios executed | N | -| Passed | N | -| Failed | N | -| Blocked | N | -| Pass rate | NN% | -| Critical issues | N | -| Major issues | N | -| Minor issues | N | -| Cosmetic issues | N | - -One-paragraph narrative summary (3–5 sentences) — what works, what doesn't, the headline finding. - -## 4. Verification Scenarios -For each scenario, repeat this exact block (numbered 4.1, 4.2, …): - -### 4.X {Scenario name} — ✅ Passed | ⚠️ Passed with issues | ❌ Failed -- **User story / acceptance criterion**: {ref to spec section} -- **Preconditions**: {explicit state — user, data, env} - -| # | Action | Expected | Actual | Status | -|---|---|---|---|---| -| 1 | … | … | … | ✅ / ❌ | - -- **Issues observed**: {bullets referencing §5 entries, or `_None observed._`} -- **Evidence**: `screenshots/{filename}.png` (one per key state) -- **Acceptance criteria checklist**: - - [ ] criterion 1 - - [x] criterion 2 - -## 5. Discrepancies -Grouped by severity. Use exactly these four buckets in this order. Empty buckets keep their heading and write `_None observed._`. - -### 5.1 Critical -For each finding, exactly: -- **Spec requirement**: {quote/ref} -- **Expected**: … -- **Actual**: … -- **Evidence**: `screenshots/…` -- **Root cause hypothesis**: … -- **User impact**: … -- **Recommended fix**: … -- **Workaround**: … - -### 5.2 Major -(same 8-field block) - -### 5.3 Minor -(same 8-field block) - -### 5.4 Cosmetic -(same 8-field block) - -## 6. Console & Network Errors -| Source (file:line) | Message | Frequency | Severity | Impact | -|---|---|---|---|---| - -(If none: write `_None observed._` below the table heading and omit the table body.) - -## 7. Spec Alignment -- **Fully implemented**: bulleted list of spec items -- **Partially implemented**: bulleted list with what's missing -- **Not implemented**: bulleted list with reason -- **Extra (unspecified) behavior**: bulleted list - -## 8. Variances from Plan -What was tested differently than the spec/plan prescribed (skipped scenarios, substituted data, environment workarounds). Write `_None._` if everything ran as planned. - -## 9. Evaluation Against Exit Criteria -Quote each exit criterion from the spec and mark ✅/❌ with one-line evidence. - -| Criterion (from spec) | Status | Evidence | -|---|---|---| - -## 10. Recommendations -- **Must fix before merge**: {refs to §5 entries} -- **Should fix soon**: {refs} -- **Nice-to-have**: {refs} - -## 11. Artifacts -- **Screenshots**: `verification/screenshots/` (N files) -- **Visual-fidelity report**: `verification/visual-fidelity.md` *(only when mockups were present)* — otherwise `_Not generated (no design_context_path)._` -- **Console log dump**: inline in §6 - -## 12. Conclusion -Restate the verdict from §3 in one sentence, then 2–3 sentences of justification, then an explicit next-step recommendation (merge / fix-then-merge / block). -```` - -#### Pre-save Validation Checklist - -Before writing the report file, walk this checklist and only save once every item passes: - -1. ☐ All 12 sections present, in numeric order (1 → 12). -2. ☐ Every section heading matches the canonical text exactly (including the `N.` prefix). -3. ☐ Every discrepancy carries all 8 sub-fields (Spec requirement … Workaround). No partial blocks. -4. ☐ Severity uses only Critical / Major / Minor / Cosmetic. -5. ☐ Status icons use only ✅ / ⚠️ / ❌. -6. ☐ Verdict is one of GO / GO WITH CAVEATS / NO-GO (no other wording). -7. ☐ Empty sections contain the `_None observed._` / `_None._` placeholder — heading not deleted. -8. ☐ Screenshot paths are relative (`screenshots/foo.png`), never absolute, never prefixed `verification/`. -9. ☐ Executive Summary arithmetic checks out: `planned ≥ executed`, `executed = passed + failed + blocked`. -10. ☐ §10 recommendations reference real §5 entries (no dangling refs). - ---- - -### 6. Organize Screenshots - -**Purpose**: Copy only referenced screenshots and validate all references - -**Actions**: -- Create `[task-path]/verification/screenshots/` directory -- Read generated report from `[task-path]/verification/e2e-verification-report.md` -- Extract image references: `!\[.*?\]\(screenshots/(.*?\.png)\)` -- For each referenced screenshot: - - Look ONLY in `.playwright-mcp/` directory (relative to project root) - - Copy to `verification/screenshots/`: `cp .playwright-mcp/FILENAME verification/screenshots/` - - Verify copied: `test -f verification/screenshots/FILENAME` - - If not found in `.playwright-mcp/`, mark as missing in report — do NOT search elsewhere -- **NEVER** use broad glob patterns (e.g., `**/*.png`) from root, home, or parent directories — this can scan the entire filesystem -- Only search within `.playwright-mcp/` and the task's own `verification/screenshots/` directory - -**Output**: All referenced screenshots in `verification/screenshots/`, validated - ---- - -### 7. Visual Fidelity Comparison (Conditional) - -**Skip this step entirely** when `design_context_path` was not provided. - -**Purpose**: Report (not gate) structural drift between the implemented UI and the source mockups. - -**Inputs**: -- `analysis/design-context/INDEX.md` — list of screens/components with stable IDs -- `analysis/design-context/mockups/` — source mockup files (HTML, screenshots, ASCII) -- `verification/screenshots/` — screenshots captured during Steps 3-6 - -**Comparison approach** (LLM-judged structural match — NOT pixel diff): - -For each screen ID in INDEX.md: -1. Read the source mockup (Read tool renders binary screenshots; HTML and ASCII as text) -2. Find the corresponding captured screenshot (match by screen ID, page name, or step description) -3. Compare structurally: - - **Layout regions**: header/sidebar/main split, column counts, panel placement - - **Field order**: form fields, table columns, list items in the same order as the mockup - - **Primary actions**: buttons present, labels match, placement matches - - **State coverage**: empty/loading/error/success states from the mockup are reachable in the implementation - - **Copy text**: headings, labels, button text match (or follow project copy-tone standards if a deviation is justified) -4. Mark each comparison ✓ (structural match), ⚠ (minor deviation, noted), or ✗ (substantive drift) - -**Output**: `verification/visual-fidelity.md` with this structure: - -```markdown -# Visual Fidelity Report - -**Mode**: Report-only (does NOT gate completion) -**Comparison**: LLM-judged structural match (not pixel-perfect) -**Source**: analysis/design-context/INDEX.md -**Captured**: verification/screenshots/ - -## TL;DR -[3-5 lines max — overall fidelity verdict and the count of matches / deviations / drift. Conclusions, not process.] - -## Open Questions / Risks -[Substantive drift items the operator should decide on — one bullet each. Omit section entirely when none.] - -## Summary -- Total screens compared: [N] -- Match (✓): [count] -- Minor deviation (⚠): [count] -- Substantive drift (✗): [count] - -## Per-Screen Comparison - -### screen:login (✓ Match) -- Mockup: analysis/design-context/mockups/login.html -- Screenshot: verification/screenshots/03-login-page.png -- Layout: 2-column split matches -- Field order: email → password → submit ✓ -- Primary action: "Sign In" button matches mockup label and placement -- States covered: default, error (invalid credentials) - -### screen:dashboard (⚠ Minor Deviation) -- Mockup: analysis/design-context/mockups/dashboard.html -- Screenshot: verification/screenshots/05-dashboard.png -- Layout: 3-column matches -- Deviation: icon library differs (implementation uses Heroicons; mockup shows custom icons) -- Impact: visual texture differs but information hierarchy preserved -- Recommendation: confirm icon choice with design team - -### screen:settings (✗ Substantive Drift) -- Mockup: analysis/design-context/mockups/settings.html -- Screenshot: verification/screenshots/08-settings.png -- Drift: implementation uses tab navigation; mockup specifies accordion -- Impact: information density and discoverability differ -- Implementer's justification (from work-log): standards conflict — `frontend/navigation.md` requires tabs for ≤5 sections -- Recommendation: design + standards owners reconcile -``` - -**Critical**: this report does NOT block workflow completion. The development orchestrator surfaces deviations prominently in the verifier summary (per "report-only, surfaced prominently" decision). Users decide whether to act on findings. - ---- - -### 8. HTML Companion Reports - -After the markdown reports and screenshots are finalized, write operator-facing HTML companions: - -- `verification/e2e-verification-report.html` (always) -- `verification/visual-fidelity.html` (only when Step 7 produced `visual-fidelity.md`) - -**Rules**: -**Companions are optional — gated by the orchestrator.** If `html_style_guide_path` is NOT provided in your prompt, SKIP this step entirely: write only the markdown reports, note the skip in your summary, and continue. The steps below run only when `html_style_guide_path` is provided. - -1. **Read the style guide** at `html_style_guide_path` (provided in your prompt) and follow it: self-contained single file, standard CSS block, no external resources. -2. **E2E companion**: lead with the verdict banner and pass/fail counts; then scenario cards with embedded screenshots (`` — relative paths, same form as the md), step tables with ✅/❌ status, discrepancies sorted by severity with `.sev` badges. Link to the md twin in the header. -3. **Visual-fidelity companion**: lead with the fidelity verdict; then side-by-side mockup-vs-screenshot pairs per screen (relative `` paths into `../analysis/design-context/mockups/` and `screenshots/`), discrepancy notes per screen. -4. **Same content as the md** — restructure and visualize, never add findings. -5. **Never block on it** — if generation fails, keep the md reports, note the miss in your summary, continue. - ---- - -## Verification Execution Patterns - -### Form Submission Pattern - -1. Navigate to form page -2. Capture initial state -3. Fill each field with test data -4. Screenshot after filling complete form -5. Submit form -6. Verify success message/feedback -7. Verify expected result (data saved, page updated, etc.) -8. Check console for errors - -### Navigation Pattern - -1. Start at initial page -2. Click navigation element -3. Verify page loaded (check URL or page element) -4. Screenshot destination page -5. Continue to next navigation step -6. Verify navigation consistency - -### CRUD Lifecycle Pattern - -**Create**: Navigate → Fill form → Submit → Verify creation -**Read**: Navigate to list → Verify item present → View details → Verify data -**Update**: Edit item → Modify fields → Submit → Verify changes -**Delete**: Delete item → Confirm → Verify removal - -### Error Handling Pattern - -1. Navigate to form/feature -2. Provide invalid input (missing required field, invalid format, etc.) -3. Submit/trigger action -4. Verify error message shown -5. Verify appropriate feedback to user -6. Screenshot error state - ---- - -## Error Handling - -### Playwright MCP Not Available - -Detect unavailable tools and provide setup instructions: -- Install playwright-mcp -- Configure MCP server in Claude Code -- Restart and retry - -### Application Not Running - -Detect navigation failures and suggest: -- Verify application is running -- Check URL correctness -- Start dev server if needed - -### Element Not Found - -When selectors fail to match: -- Try alternative selectors (data-testid, role, text) -- Screenshot current state -- Report in findings with attempted selectors -- Note possible causes (implementation issue, different selector, hidden element, loading delay) - ---- - -## Important Guidelines - -### Evidence-Based Verification - -**Always**: -- Execute real browser tests, never assume behavior -- Capture screenshots for every significant step -- Reference actual test results in findings -- Include console messages -- Link findings to specification requirements - -**Never**: -- Assume behavior without testing -- Report issues without evidence -- Skip screenshots -- Ignore console errors - -### Thorough Coverage - -Test systematically: -- All user stories from specification -- All acceptance criteria -- Happy paths first, then error cases -- Edge cases mentioned in spec -- Console errors after each scenario - -### Clear Reporting - -Reports must be: -- Comprehensive but readable -- Evidence-based (screenshots, console logs) -- Actionable (clear next steps) -- Categorized by severity -- Referenced to specification requirements - -### Read-Only Operation - -Remember: -- Test and report findings -- Document issues with evidence -- Provide actionable recommendations -- **NEVER** fix implementation -- **NEVER** modify application code -- **NEVER** assume without testing - -### Pragmatic Testing - -Focus on what matters: -- User-facing functionality from specification -- Critical workflows -- Balance thoroughness with efficiency -- Prioritize testing requirements over nice-to-haves - ---- - -## Validation Checklist - -Before completing verification, ensure: - -✓ All user stories tested from spec.md -✓ All acceptance criteria verified -✓ Screenshots captured for all scenarios -✓ Screenshots organized to `verification/screenshots/` -✓ Screenshot references use relative paths -✓ Console checked for errors -✓ Pass/fail status determined for each test -✓ Issues documented with evidence -✓ Severity assigned to all issues -✓ Recommendations provided -✓ Report saved to verification/e2e-verification-report.md -✓ Deployment decision made (GO/NO-GO) -✓ When `design_context_path` was provided: `verification/visual-fidelity.md` written with per-screen comparison (✓/⚠/✗) -✓ HTML companions written (Step 8): `e2e-verification-report.html` (+ `visual-fidelity.html` when applicable) — or the miss noted in summary (companions never block) - ---- - -## Success Criteria - -E2E verification is complete when: - -✅ All user stories from specification tested -✅ Test scenarios executed with Playwright MCP tools -✅ Screenshots captured and organized -✅ Console errors checked for all scenarios -✅ Pass/fail determined with evidence -✅ Discrepancies categorized by severity -✅ Specification alignment analyzed -✅ Comprehensive report generated with actionable recommendations -✅ Deployment recommendation provided with justification - ---- - -## Example Invocation - -``` -You are the e2e-test-verifier agent. Your task is to verify implementation -using end-to-end browser tests. - -Task Path: .maister/tasks/development/2025-10-26-user-registration/ -Spec: .maister/tasks/development/2025-10-26-user-registration/implementation/spec.md -Base URL: http://localhost:3000 - -Please: -1. Read spec.md and extract user stories with acceptance criteria -2. Create test scenarios from requirements -3. Execute Playwright tests for each scenario using MCP tools -4. Verify UI behavior matches expectations -5. Capture screenshots of each significant step -6. Check console for errors after each scenario -7. Generate comprehensive verification report - -Save screenshots to: verification/screenshots/ -Save report to: verification/e2e-verification-report.md - -Use Playwright MCP tools (navigate, click, fill, evaluate, screenshot, console_messages). -All findings must have evidence (screenshots, console logs, test results). -``` - ---- - -This agent ensures implementations work correctly from the user's perspective through runtime, evidence-based browser verification — not by generating test files, but by executing verification steps live via Playwright MCP tools. diff --git a/plugins/maister-copilot/skills/codebase-analyzer/SKILL.md b/plugins/maister-copilot/skills/codebase-analyzer/SKILL.md deleted file mode 100644 index 58aa090e..00000000 --- a/plugins/maister-copilot/skills/codebase-analyzer/SKILL.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -name: codebase-analyzer -description: Analyzes codebase using adaptive parallel Explore subagents based on task complexity. Selects agent roles from a pool, launches Explore agents, then delegates report generation to codebase-analysis-reporter subagent. -user-invocable: false ---- - -# Codebase Analyzer Skill - -Orchestrates parallel codebase analysis using built-in Explore subagents. Adaptively selects which agent roles to activate based on task complexity, then delegates report synthesis to a specialized subagent. - -## Core Principles - -1. **Adaptive Agent Selection**: Select roles from a pool based on task complexity — no fixed count -2. **Task-Type Awareness**: Adapt prompts and focus based on task type -3. **Delegated Reporting**: Raw findings go to `codebase-analysis-reporter` subagent for synthesis - ---- - -## Input Parameters - -| Parameter | Required | Description | -|-----------|----------|-------------| -| `task_description` | Yes | Description of the development task | -| `description` | Yes | Task description from user | -| `task_path` | Yes | Path to task directory | -| `artifact_name` | No | Override output filename (default: `codebase-analysis.md`) | - ---- - -## Execution Workflow - -### Step 1: Parse Input and Determine Focus - -Extract keywords, component names, file hints, domain, and technology hints from the description. - -Determine primary focus from the task description: - -| Signal in Description | Primary Focus | Key Questions | -|----------------------|---------------|---------------| -| Error/crash/broken language | Find buggy code path | Where does the issue occur? What's the execution flow? | -| Improve/enhance/existing | Find existing feature | What files implement this feature? How does it work? | -| Add/new/create | Find patterns/integration points | What similar patterns exist? Where should this integrate? | - -### Step 2: Select Agent Roles - -Choose which roles to activate from the pool. Each role is a distinct analysis concern. - -| Role | Purpose | When Needed | -|------|---------|-------------| -| **File Discovery** | Find relevant files by patterns, keywords, naming | Almost always | -| **Code Analysis** | Analyze code structure, patterns, execution flow | When understanding existing behavior matters | -| **Context Discovery** | Find tests, consumers, dependencies | When understanding impact/coverage matters | -| **Pattern Mining** | Find similar implementations as templates | New features following existing patterns | -| **Migration Target** | Analyze target technology/compatibility | Migrations comparing current vs target | - -**Decision signals:** -- **Specificity** (exact files mentioned → fewer agents) -- **Scope breadth** (multiple domains → more agents) -- **Uncertainty** (unclear location → more agents) -- **Task type** (bugs tend focused, features broad, migrations broadest) - -**Examples:** - -| Task Description | Roles Selected | Count | -|------------------|---------------|-------| -| "Fix null check in `utils/parser.ts`" | File Discovery + Code Analysis (combined) | 1 | -| "Add sorting to user table" | File Discovery, Code Analysis | 2 | -| "Fix login timeout" | File Discovery + Code Analysis (combined), Context Discovery | 2 | -| "Add OAuth authentication system" | File Discovery, Code Analysis, Context Discovery | 3 | -| "Add export feature similar to import" | File Discovery, Code Analysis, Pattern Mining | 3 | -| "Migrate from REST to GraphQL" | File Discovery, Code Analysis, Context Discovery, Migration Target | 4 | - -When selecting fewer agents, merge related concerns into a single prompt — don't drop concerns. - -State which roles you selected and why (1 sentence). - -### Step 3: Read Prompt Templates and Launch Agents - -> **STOP — Do NOT skip this step. Do NOT write prompts from memory.** -> -> Before launching ANY Explore agent, you MUST use the Read tool to load the prompt template for each selected role. This is non-negotiable. - -**3a. Read templates** — Use the Read tool to load ONLY the files for your selected roles: - -| Role | Read This File | -|------|--------------| -| File Discovery | `references/file-discovery.md` | -| Code Analysis | `references/code-analysis.md` | -| Context Discovery | `references/context-discovery.md` | -| Pattern Mining | `references/pattern-mining.md` | -| Migration Target | `references/migration-target.md` | - -If combining roles into one agent, also read `references/combined.md` for merging guidance. - -**3b. Adapt templates** — Replace `[description]` with the actual task description. Select the correct task-type section (Bug / Enhancement / Feature). - -**3c. Launch agents** — Use the Task tool with `subagent_type="Explore"` — one call per selected role, all in ONE message. - -**IMPORTANT**: Every Explore agent prompt MUST include this instruction: -> IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -**SELF-CHECK**: Did you read the template files with the Read tool? If not, go back to 3a. Do not proceed. - -### Step 4: Delegate Report Generation - -After all Explore agents complete, delegate to `codebase-analysis-reporter` subagent via Task tool: - -``` -Task tool: - subagent_type: "maister-codebase-analysis-reporter" - description: "Merge findings into analysis report" - prompt: | - You are the codebase-analysis-reporter. Merge these raw findings into a structured analysis report. - - Task description: [description] - Agent roles used: [list of roles] - Agent count: [N] - Output path: [task_path]/analysis/[artifact_name] - - ## Raw Findings - - ### [Role 1 Name] - [paste raw output from agent 1] - - ### [Role 2 Name] - [paste raw output from agent 2] - - [... for each agent] -``` - -The subagent produces the final report at `{task_path}/analysis/{artifact_name}` and returns structured results. - -### Step 5: Return Results to Orchestrator - -Pass through the subagent's structured output: - -```yaml -status: success|partial|failed -report_path: analysis/[artifact_name] -summary: "[1-2 sentence summary]" -files_found: [count] -complexity: simple|moderate|complex -risk_level: low|low-medium|medium|medium-high|high -``` - ---- - -## Error Handling - -- **No files found**: Report partial results, suggest user provide more specific hints -- **Agent timeout**: Use results from completed agents, note incomplete analysis -- **Conflicting results**: Pass all perspectives to reporter subagent, which highlights conflicts - ---- - -## Integration - -| Orchestrator | Phase | artifact_name | -|-------------|-------|---------------| -| development orchestrator | Phase 1 | `codebase-analysis.md` (default) | -| migration orchestrator | Phase 1 | `current-state-analysis.md` | -| performance orchestrator | Phase 1 | `codebase-analysis.md` (default) | diff --git a/plugins/maister-copilot/skills/codebase-analyzer/references/code-analysis.md b/plugins/maister-copilot/skills/codebase-analyzer/references/code-analysis.md deleted file mode 100644 index 129c7b54..00000000 --- a/plugins/maister-copilot/skills/codebase-analyzer/references/code-analysis.md +++ /dev/null @@ -1,63 +0,0 @@ -# Code Analysis — Prompt Templates - -Replace `[description]` with the actual task description. - -## Bug -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Analyze the code related to: "[description]" - -Focus on: -1. Trace execution flow from input to output -2. Identify state changes and side effects -3. Look for edge cases, error conditions, race conditions -4. Find validation logic and where it might fail -5. Check for recent changes that might have introduced the bug - -Output: -- Execution flow diagram (text-based) -- Key functions/methods involved -- Potential problem areas -- State management approach -``` - -## Enhancement -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Analyze the existing implementation of: "[description]" - -Focus on: -1. Understand current functionality and capabilities -2. Identify the component/service architecture -3. Document the data flow (props, state, API calls) -4. Note coding patterns used (hooks, classes, functional) -5. Assess complexity (simple/moderate/complex) - -Output: -- Current functionality summary -- Architecture overview -- Key functions and their purposes -- Coding patterns observed -``` - -## Feature -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Analyze the codebase architecture for adding: "[description]" - -Focus on: -1. Understand the overall project structure -2. Identify architectural patterns in use (MVC, component-based, etc.) -3. Document naming conventions and code style -4. Find the data layer patterns (API, state management) -5. Note any relevant abstractions or base classes - -Output: -- Project structure overview -- Architectural patterns to follow -- Naming conventions to match -- Recommended approach for new feature -``` diff --git a/plugins/maister-copilot/skills/codebase-analyzer/references/combined.md b/plugins/maister-copilot/skills/codebase-analyzer/references/combined.md deleted file mode 100644 index 0b8d867b..00000000 --- a/plugins/maister-copilot/skills/codebase-analyzer/references/combined.md +++ /dev/null @@ -1,31 +0,0 @@ -# Combined Prompts — Guidance - -When merging multiple roles into a single agent, integrate concerns logically rather than concatenating prompts. Read the individual role templates first, then merge them into a coherent single prompt. - -## Example: File Discovery + Code Analysis (Bug) - -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Explore and analyze the codebase for: "[description]" - -1. Find files where the bug likely occurs (search for error keywords, related functionality) -2. Trace the code path through these files - entry points, handlers, processing logic -3. Identify state changes, side effects, and potential failure points -4. Look for edge cases, validation logic, and error handling -5. Check for related configuration that might affect behavior - -Output: -- Relevant files with paths and why they matter -- Execution flow through identified files -- Key functions/methods and their roles -- Potential problem areas and root cause hypotheses -``` - -## Merging Principles - -- Unify the focus areas into a single logical flow (don't just list both sets of bullet points) -- Combine the output sections — avoid duplicate asks -- Keep the total prompt concise (aim for 8-12 focus items max) -- The merged prompt should read as one coherent task, not two tasks stitched together -- Always include the no-write constraint: "IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only." diff --git a/plugins/maister-copilot/skills/codebase-analyzer/references/context-discovery.md b/plugins/maister-copilot/skills/codebase-analyzer/references/context-discovery.md deleted file mode 100644 index 35031bc0..00000000 --- a/plugins/maister-copilot/skills/codebase-analyzer/references/context-discovery.md +++ /dev/null @@ -1,63 +0,0 @@ -# Context Discovery — Prompt Templates - -Replace `[description]` with the actual task description. - -## Bug -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Find testing and context information for: "[description]" - -Focus on: -1. Find existing tests that cover this functionality -2. Look for test files that might help reproduce the bug -3. Identify test data or fixtures used -4. Find related integration or E2E tests -5. Check for any existing bug reports or TODOs in comments - -Output: -- Relevant test files and what they test -- Test coverage gaps -- Reproduction hints from tests -- Related issues or TODOs found in code -``` - -## Enhancement -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Find dependencies and consumers for: "[description]" - -Focus on: -1. Find all files that import/use this feature (consumers) -2. Identify what this feature depends on (dependencies) -3. Locate test files and assess coverage -4. Find API endpoints or routes related to this feature -5. Check for documentation or comments - -Output: -- Consumer list (who uses this) -- Dependency list (what this uses) -- Test files and coverage assessment -- Integration points -``` - -## Feature -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Find integration requirements for: "[description]" - -Focus on: -1. Identify where this feature needs to be registered/routed -2. Find existing integration patterns (how other features connect) -3. Look for shared dependencies this feature will need -4. Check for authentication/authorization patterns to follow -5. Find configuration or environment requirements - -Output: -- Required integration points -- Patterns to follow for registration -- Shared dependencies to use -- Configuration requirements -``` diff --git a/plugins/maister-copilot/skills/codebase-analyzer/references/file-discovery.md b/plugins/maister-copilot/skills/codebase-analyzer/references/file-discovery.md deleted file mode 100644 index e3b446e5..00000000 --- a/plugins/maister-copilot/skills/codebase-analyzer/references/file-discovery.md +++ /dev/null @@ -1,51 +0,0 @@ -# File Discovery — Prompt Templates - -Replace `[description]` with the actual task description. - -## Bug -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Explore the codebase to find files related to: "[description]" - -Focus on: -1. Find files where the bug likely occurs (search for error keywords, related functionality) -2. Trace the code path - entry points, handlers, processing logic -3. Look for related error handling, validation, edge cases -4. Find configuration files that might affect this behavior - -Output a list of relevant files with their paths and why they're relevant. -Be thorough - check multiple naming conventions (PascalCase, kebab-case, snake_case). -``` - -## Enhancement -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Explore the codebase to find files that implement: "[description]" - -Focus on: -1. Find the main files for this feature (components, services, controllers) -2. Look for related files (types, utilities, hooks, styles) -3. Check multiple naming patterns: *{keyword}*, {Domain}{Component}, etc. -4. Search in likely directories: src/components/, src/services/, src/features/ - -Output a ranked list of files with confidence indicators. -Include file paths, approximate line counts, and why each file is relevant. -``` - -## Feature -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Explore the codebase to find patterns and integration points for: "[description]" - -Focus on: -1. Find similar existing features/components to use as templates -2. Identify where this new feature should live (directory structure) -3. Look for shared utilities, hooks, or base classes to extend -4. Find entry points where this feature needs to integrate (routes, menus, etc.) - -List the files that serve as good examples or integration points. -Include reasoning for why each pattern/location is appropriate. -``` diff --git a/plugins/maister-copilot/skills/codebase-analyzer/references/migration-target.md b/plugins/maister-copilot/skills/codebase-analyzer/references/migration-target.md deleted file mode 100644 index e004d41c..00000000 --- a/plugins/maister-copilot/skills/codebase-analyzer/references/migration-target.md +++ /dev/null @@ -1,23 +0,0 @@ -# Migration Target — Prompt Template - -Primarily for migrations. Replace `[description]` with the actual task description. - -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Analyze the target state for migration: "[description]" - -Focus on: -1. Find any existing usage of the target technology/pattern in the codebase -2. Look for partial migration attempts or hybrid implementations -3. Identify compatibility layers, adapters, or shims already in use -4. Check for migration-related configuration (build tools, transpilers, polyfills) -5. Document the target conventions and patterns to follow - -Output: -- Existing target technology usage (if any) -- Partial migration progress found -- Compatibility concerns identified -- Target conventions to follow -- Migration configuration requirements -``` diff --git a/plugins/maister-copilot/skills/codebase-analyzer/references/pattern-mining.md b/plugins/maister-copilot/skills/codebase-analyzer/references/pattern-mining.md deleted file mode 100644 index 20a3169e..00000000 --- a/plugins/maister-copilot/skills/codebase-analyzer/references/pattern-mining.md +++ /dev/null @@ -1,22 +0,0 @@ -# Pattern Mining — Prompt Template - -Primarily for features, usable for enhancements. Replace `[description]` with the actual task description. - -``` -IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only. - -Find similar implementations and reusable patterns for: "[description]" - -Focus on: -1. Find the most similar existing feature/component in the codebase -2. Identify reusable abstractions, base classes, or utilities that can be extended -3. Document the conventions these similar implementations follow (file structure, naming, patterns) -4. Note any generators, templates, or scaffolding tools available -5. Identify shared hooks, mixins, or helper functions that should be reused - -Output: -- Best template/example to replicate (with file paths) -- Reusable abstractions and utilities (with file paths) -- Convention checklist to follow -- Anti-patterns observed in existing similar features (what NOT to copy) -``` diff --git a/plugins/maister-copilot/skills/docs-manager/SKILL.md b/plugins/maister-copilot/skills/docs-manager/SKILL.md deleted file mode 100644 index 5be27393..00000000 --- a/plugins/maister-copilot/skills/docs-manager/SKILL.md +++ /dev/null @@ -1,360 +0,0 @@ ---- -name: docs-manager -description: Internal engine for managing project documentation and technical standards in .maister/docs/. Handles file operations, INDEX.md generation, and .github/copilot-instructions.md integration. Invoked by maister-init, standards-update, and standards-discover skills. -user-invocable: false ---- - -# Documentation Manager (Internal Engine) - -Internal skill that manages documentation file operations in `.maister/docs/`. Not directly user-invocable — called by `maister-init`, `standards-update`, and `standards-discover` skills. - -## Core Principles - -- **Project documentation is source of truth** — plugin-bundled docs are baseline/reference only -- **INDEX.md is the master map** — always kept up-to-date after changes -- **.github/copilot-instructions.md integration is mandatory** — ensures AI reads documentation - -## Documentation Structure - -``` -.maister/docs/ -├── INDEX.md # Master index - READ THIS FIRST -├── project/ # Project-level documentation (generated by maister-init, not copied from templates) -│ ├── vision.md # Project vision and goals -│ ├── roadmap.md # Development roadmap -│ ├── tech-stack.md # Technology choices and rationale -│ └── architecture.md # System architecture (optional) -└── standards/ # Technical standards and conventions - ├── global/ # Language-agnostic standards - │ ├── error-handling.md - │ ├── validation.md - │ ├── conventions.md - │ ├── coding-style.md - │ └── commenting.md - ├── frontend/ # Frontend-specific standards - │ ├── css.md - │ ├── components.md - │ ├── accessibility.md - │ └── responsive.md - ├── backend/ # Backend-specific standards - │ ├── api.md - │ ├── models.md - │ ├── queries.md - │ └── migrations.md - └── testing/ # Testing standards - └── test-writing.md -``` - -## Standard File Conventions - -Standard files follow the structure `standards/[category]/[topic].md`: -- **Category** = domain folder (global, frontend, backend, testing, or custom) -- **Topic file** = contains multiple related standards - -**Format**: Each file uses `## Topic` as the file heading, with `### Standard Name` for each individual standard. Each standard has a 1-10 line description (excluding code snippets) and an optional brief code example (under 10 lines). - -**Conciseness**: Standards are quick-reference conventions, not tutorials. If a file grows unwieldy, split into focused sub-topic files. - -**Why ### per standard**: Each standard as a discrete section makes it easier for agents to find, update, and reference individually — no need to parse bullet lists. - ---- - -## Bundled Resources - -This skill bundles the following resources within the plugin: - -- **Standards Directory**: Contains baseline technical standards organized by category: - - `global/` - Global standards (error handling, validation, conventions, etc.) - - `frontend/` - Frontend-specific standards (CSS, components, accessibility, etc.) - - `backend/` - Backend-specific standards (API design, database, queries, etc.) - - `testing/` - Testing standards (test writing, coverage, etc.) -- **INDEX.md Template**: Master template for documentation index - -## Location Reference - -- **Plugin bundles** (read-only baseline): This skill's `docs/` subdirectory within the plugin -- **Project documentation** (source of truth): `.maister/docs/` in the project root -- **Project configuration**: `.github/copilot-instructions.md` in the project root - -## Capabilities - -### 1. Initialize Documentation in Project - -Use this when a project doesn't have `.maister/docs/` or needs documentation for the first time. This is a **one-time baseline setup** that gives the project a starting point. - -**IMPORTANT**: This operation accepts an optional `standards_selection` parameter (array of standard categories) to control which standards to initialize. If not provided, all standards are copied (backward compatible). It also accepts an optional `standards_source_path` parameter to copy standards from an external project instead of the bundled defaults. - -**What to do:** -1. Check if `.maister/docs/` exists in the project root -2. If it exists, warn the user that initialization will overwrite existing documentation and ask for confirmation -3. Create the directory structure based on standards_selection: - ``` - .maister/docs/ - ├── project/ - └── standards/ - ├── global/ (if 'global' in standards_selection or no selection provided) - ├── frontend/ (if 'frontend' in standards_selection or no selection provided) - ├── backend/ (if 'backend' in standards_selection or no selection provided) - └── testing/ (if 'testing' in standards_selection or no selection provided) - ``` -4. Copy standards to the project's `.maister/docs/standards/` directory. **Source selection**: If `standards_source_path` is provided, copy from that external path. Otherwise, copy from this skill's bundled `docs/standards/` directory: - - **Project documentation**: Do NOT copy project templates — only create the `project/` directory. Project documentation files (vision, roadmap, tech-stack, architecture) are generated by the calling skill (e.g., maister-init) using analyzer data, not copied as placeholder templates. - - **Standards**: Only copy selected standard categories based on standards_selection parameter: - - If `standards_selection` is empty or not provided: Copy ALL standards (backward compatible) - - If `standards_selection` is provided: Only copy specified categories - - Examples: - - `['global', 'frontend', 'testing']` → Copy only these three categories - - `['global', 'backend', 'testing']` → Skip frontend standards - - `['global', 'testing']` → Only global and testing standards -5. Generate INDEX.md with entries for all copied documentation (see "Manage INDEX.md" operation): - - For skipped standard categories, add placeholder sections with "Not initialized - run standards discovery if needed" - - Example: If frontend standards are skipped, INDEX.md shows: - ```markdown - ### Frontend Standards - - *Not initialized for this project. If you need frontend standards, you can:* - - *Add them manually using the docs-manager skill* - - *Run `/maister-standards-discover --scope=frontend` to auto-discover* - ``` -6. **MANDATORY - Update .github/copilot-instructions.md:** - - Check if `.github/copilot-instructions.md` exists in the project root; if not, ask the user if they want to create it - - Add the documentation reference section (see "Manage .github/copilot-instructions.md Integration" operation) - - Ensure it emphasizes reading INDEX.md at the beginning of any task -7. Inform the caller about the documentation structure created - -**Parameters:** -- `standards_selection` (optional, array of strings): Standard categories to initialize - - Array of category names (e.g., `['global', 'frontend', 'backend', 'testing']`). Baseline categories: global, frontend, backend, testing. Custom categories are also supported. - - If omitted or empty: Initialize all baseline standards (backward compatible) - - If provided: Only initialize specified categories (creates directories for custom ones) -- `standards_source_path` (optional, string): Absolute path to an external standards directory (e.g., `/path/to/other-project/.maister/docs/standards/`) - - If provided: Copy standards from this path instead of the bundled defaults - - If omitted: Copy from this skill's bundled `docs/standards/` directory (default behavior) - -**Result:** The project now has baseline documentation in `.maister/docs/`, a comprehensive INDEX.md, and .github/copilot-instructions.md integration that ensures AI assistance is documentation-aware. Only selected standard categories are initialized. - -**Important:** After this initial setup, the project's documentation becomes the source of truth. Teams should customize it for their specific needs. - -**Note on Skipped Standards**: If standard categories are skipped during initialization, teams can add them later using: -- "Add Documentation File" operation to add specific standards -- `/maister-standards-discover` command to auto-discover standards from codebase - ---- - -### 2. Manage INDEX.md - -Use this to create or update the INDEX.md file that serves as the master documentation map. - -**What to do:** -1. Scan the `.maister/docs/` directory structure -2. For each documentation file found: - - Read the file content to extract description - - Determine the file's purpose and category - - **For technical standards**: The description MUST enumerate the specific practices/conventions documented in the file, not just a generic category description. -3. Read `references/index-md-template.md` for the INDEX.md structure template -4. Generate INDEX.md by populating the template with discovered files and descriptions -5. Write the generated INDEX.md to `.maister/docs/INDEX.md` -6. Verify that .github/copilot-instructions.md references this index (see "Manage .github/copilot-instructions.md Integration" operation) - -**Result:** A comprehensive, up-to-date INDEX.md that provides a clear map of all project documentation. - ---- - -### 3. Add Documentation File - -Use this to add new documentation to the project, either from plugin baseline or custom. - -**What to do:** -1. Determine the type of documentation to add: - - Project documentation (vision, roadmap, tech-stack, architecture, custom) - - Technical standard (any category under standards/) -2. If adding from plugin baseline: - - Check if the requested documentation exists in this skill's bundled `docs/` directory - - Copy it to the appropriate location in `.maister/docs/` -3. If creating custom documentation: - - Ask for the category (project/ or standards/category/) - - Ask for the filename and purpose - - Create a template file with appropriate frontmatter and structure -4. Update INDEX.md to include the new documentation (see "Manage INDEX.md" operation) -5. If this is a technical standard and corresponds to a Claude Code Skill, ensure consistency - -**Result:** New documentation is added to the project and indexed in INDEX.md. - ---- - -### 4. Update Documentation - -Use this to help the user update or modify existing project documentation. - -**What to do:** -1. Accept the documentation identifier from the user (e.g., "project/vision", "standards/global/error-handling") -2. Check if the documentation exists in `.maister/docs/` -3. If the documentation exists: - - Read the current documentation - - Ask the user what they want to change or update - - Help them edit the documentation file directly - - Optionally, show them the plugin's baseline version for reference if they ask -4. If the documentation doesn't exist: - - Offer to add it from the plugin baseline (see "Add Documentation File" operation) - - Or offer to help them create custom documentation from scratch -5. After updating: - - Check if INDEX.md needs updating (if the purpose/description changed significantly) - - If updating tech-stack.md or architecture.md, suggest reviewing .github/copilot-instructions.md for consistency -6. For technical standards: - - If a corresponding Claude Code Skill exists, suggest reviewing it for consistency - - Standards should align with actual code patterns in the project - -**Result:** Documentation is updated to reflect current project state and team decisions. - ---- - -### 5. Use Plugin Documentation as Reference - -Use this when a team wants to see the plugin's baseline documentation for reference, or reset specific docs to plugin defaults. - -**What to do:** -1. Compare the documentation in this skill's bundled `docs/` directory with the project's `.maister/docs/` directory to identify differences -2. Show the user which documents differ and how they differ -3. Explain that plugin documentation is baseline/reference only, and project documentation is superior -4. **WARNING**: Copying plugin documentation to the project will overwrite any project-specific customizations -5. Ask the user if they want to: - - View the differences for reference only (no changes) - - Reset specific documentation to plugin baseline (selective overwrite) - - Reset all documentation to plugin baseline (full overwrite - rarely recommended) -6. If the user chooses to copy any documentation: - - Copy the selected files from this skill's bundled `docs/` directory to the project's `.maister/docs/` directory - - Update INDEX.md to reflect any changes - - Review .github/copilot-instructions.md for any necessary updates - -**Important:** This operation should be used rarely, mainly when a team wants to reset to baseline. Project documentation is the source of truth and should be maintained by the team. - -**Result:** User can reference plugin baseline documentation and optionally reset specific docs to plugin versions. - ---- - -### 6. List Available Documentation - -Use this to show what documentation is bundled with this plugin and their installation status in the project. - -**What to do:** -1. List all documentation in this skill's bundled `docs/` directory, organized by category -2. For each bundled document: - - Show the category and name - - Check if it exists in the project at `.maister/docs/[category]/[name].md` - - Show installation status (bundled only, installed, or customized) - - If installed, show whether it differs from the baseline (customized) -3. Show whether INDEX.md exists and is up-to-date -4. Show whether .github/copilot-instructions.md has documentation integration -5. Remind the user that plugin documentation is baseline/reference only, and project documentation (if installed) is the source of truth - -**Result:** The user sees a complete inventory of available baseline documentation and their installation status in the current project. - ---- - -### 7. Manage .github/copilot-instructions.md Integration - -Use this to ensure the project's .github/copilot-instructions.md properly integrates with the documentation system, encouraging AI to read and use the documentation. - -**What to do:** -1. Check if `.github/copilot-instructions.md` exists in the project root -2. If it doesn't exist, ask the user if they want to create it -3. Look for a documentation reference section in .github/copilot-instructions.md -4. If the section doesn't exist or is incomplete: - - Read `references/claude-md-template.md` for the template - - Add the template section to .github/copilot-instructions.md -5. Ensure the documentation section is placed prominently in .github/copilot-instructions.md (near the top) -6. Verify that the INDEX.md path is correct and the file exists -7. If `.maister/docs/` doesn't exist, suggest running the initialization operation first - -**Result:** .github/copilot-instructions.md properly integrates with the documentation system, ensuring AI assistance is documentation-aware and follows team conventions. - ---- - -### 8. Validate Documentation Consistency - -Use this to check that documentation is consistent, up-to-date, and properly integrated. - -**What to do:** -1. **Check structure:** - - Verify `.maister/docs/` directory exists - - Verify all expected subdirectories exist (project/, standards/global/, etc.) -2. **Check INDEX.md:** - - Verify it exists and is readable - - Check that all files in `.maister/docs/` are listed in INDEX.md - - Check that all files listed in INDEX.md actually exist - - Report any orphaned files or broken references -3. **Check .github/copilot-instructions.md integration:** - - Verify .github/copilot-instructions.md exists - - Verify it contains documentation reference section - - Verify it uses valid file reference format: @.maister/docs/INDEX.md (with @ prefix, without backticks) - - Warn if using incorrect formats like `.maister/docs/INDEX.md` or `@.maister/docs/INDEX.md` (backticks) -4. **Check project documentation:** - - Verify critical files exist (vision.md, tech-stack.md) - - Check if they contain placeholder text vs. actual project information - - Warn if critical documentation is missing or empty -5. **Check standards consistency:** - - If Claude Code Skills exist, check if corresponding standards documentation exists - - If standards exist without skills, suggest creating skills (if appropriate) - - Report any inconsistencies -6. **Generate validation report:** - - Summary of documentation status - - List of issues found - - Recommendations for fixes -7. **Offer to fix issues:** - - Ask if the user wants to automatically fix found issues - - Fix missing INDEX.md entries - - Fix missing .github/copilot-instructions.md integration - - Create missing directory structure - -**Result:** A comprehensive validation report with optional automatic fixes for common issues. - ---- - -## Usage Examples - -**Initialize documentation in a new project:** -``` -User: "Set up documentation for this project" -Claude: [Executes Initialize Documentation - creates structure, copies baseline docs, generates INDEX.md, updates .github/copilot-instructions.md, gathers project info] -``` - -**Update project vision:** -``` -User: "I want to update our project vision to include AI-first approach" -Claude: [Executes Update Documentation - reads current vision.md, helps user edit it, updates INDEX.md if needed] -``` - -**Add custom documentation:** -``` -User: "Add documentation for our deployment process" -Claude: [Executes Add Documentation File - creates custom project/deployment.md, updates INDEX.md] -``` - -**Reference plugin baseline:** -``` -User: "Show me the plugin's baseline error handling standard" -Claude: [Executes Use Plugin Documentation as Reference - shows plugin baseline, compares with project version, no changes unless user requests] -``` - -**Validate documentation:** -``` -User: "Check if our documentation is complete and consistent" -Claude: [Executes Validate Documentation Consistency - checks structure, INDEX.md, .github/copilot-instructions.md integration, generates report] -``` - -**Manage INDEX.md:** -``` -User: "Rebuild the documentation index" -Claude: [Executes Manage INDEX.md - scans .maister/docs/, regenerates comprehensive INDEX.md] -``` - ---- - -## Important Notes - -- **Project documentation is source of truth** — plugin-bundled docs are baseline/reference only -- **INDEX.md must stay current** — regenerate after any documentation change -- **.github/copilot-instructions.md integration is mandatory** — ensures AI reads documentation at task start -- **This skill is an internal engine** — called by maister-init, standards-update, and standards-discover. Not directly user-invocable. -- **CRITICAL: Return control after completion** — This is an internal sub-skill. After completing the requested operation, return control to the calling workflow. Do NOT treat completion of this skill as the end of the conversation turn — the parent skill has more steps to execute. - diff --git a/plugins/maister-copilot/skills/docs-manager/docs/INDEX.md b/plugins/maister-copilot/skills/docs-manager/docs/INDEX.md deleted file mode 100644 index 0e5ef355..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/INDEX.md +++ /dev/null @@ -1,177 +0,0 @@ -# Documentation Index - -**IMPORTANT**: Read this file at the beginning of any development task to understand available documentation and standards. - -## Quick Reference - -### Project Documentation -Project-level documentation covering vision, goals, architecture, and technology choices. - -### Technical Standards -Coding standards, conventions, and best practices organized by domain. - ---- - -## Project Documentation - -Located in `.maister/docs/project/` - -### Vision (`project/vision.md`) -Defines the project's mission, goals, target users, and long-term vision. Read this to understand the "why" behind the project and align development decisions with project objectives. - -### Roadmap (`project/roadmap.md`) -Outlines development milestones, planned features, and timeline. Read this to understand project priorities and upcoming work. - -### Tech Stack (`project/tech-stack.md`) -Documents all technologies, frameworks, libraries, and tools used in the project, with rationale for each choice. Read this before adding new dependencies or making technology decisions. - -### Architecture (`project/architecture.md`) -Describes the system architecture, component structure, data flow, and design patterns. Read this to understand how the system is organized and how components interact. - ---- - -## Technical Standards - -### Global Standards - -Located in `.maister/docs/standards/global/` - -These standards apply across the entire codebase, regardless of frontend/backend context. - -#### Error Handling (`standards/global/error-handling.md`) -Structured error types, error propagation patterns, user-facing vs internal error messages, try-catch placement guidelines, error logging conventions. - -#### Validation (`standards/global/validation.md`) -Input validation at system boundaries, sanitization patterns, validation error message formatting, schema validation approach. - -#### Conventions (`standards/global/conventions.md`) -Naming conventions (files, variables, functions, classes), file organization patterns, import ordering, code structure guidelines. - -#### Coding Style (`standards/global/coding-style.md`) -Indentation and formatting rules, spacing conventions, line length limits, bracket style, consistent code readability patterns. - -#### Commenting (`standards/global/commenting.md`) -When to comment (non-obvious logic only), documentation comment format, inline explanation guidelines, TODO/FIXME conventions. - -#### Minimal Implementation (`standards/global/minimal-implementation.md`) -No speculative code, no unused methods, no "just in case" abstractions, YAGNI principle enforcement, lean code guidelines. - ---- - -### Frontend Standards - -Located in `.maister/docs/standards/frontend/` - -These standards apply to frontend code (UI components, client-side logic, styling). - -#### CSS (`standards/frontend/css.md`) -CSS naming conventions, stylesheet organization, utility-first vs component styles, CSS variable usage, responsive styling patterns. - -#### Components (`standards/frontend/components.md`) -Component structure and composition patterns, props design, lifecycle management, smart vs presentational separation. - -#### Accessibility (`standards/frontend/accessibility.md`) -Keyboard navigation requirements, screen reader support, ARIA attribute usage, WCAG compliance level, focus management patterns. - -#### Responsive Design (`standards/frontend/responsive.md`) -Breakpoint definitions, mobile-first approach, responsive layout patterns, touch target sizing, viewport considerations. - ---- - -### Backend Standards - -Located in `.maister/docs/standards/backend/` - -These standards apply to backend code (APIs, services, data layer). - -#### API Design (`standards/backend/api.md`) -REST endpoint naming, request/response format conventions, versioning strategy, error response structure, pagination patterns. - -#### Models (`standards/backend/models.md`) -Data model structure, schema conventions, business logic placement, relationship patterns, model validation rules. - -#### Queries (`standards/backend/queries.md`) -Query optimization patterns, N+1 prevention, index usage guidelines, query builder conventions, raw query policies. - -#### Migrations (`standards/backend/migrations.md`) -Migration naming conventions, schema change patterns, data migration approach, rollback requirements, migration testing. - ---- - -### Testing Standards - -Located in `.maister/docs/standards/testing/` - -These standards apply to all testing code (unit, integration, E2E). - -#### Test Writing (`standards/testing/test-writing.md`) -Test naming conventions, test file organization, arrange-act-assert structure, mocking guidelines, coverage expectations, test data management. - ---- - -## How to Use This Documentation - -1. **Start Here**: Always read this INDEX.md first to understand what documentation exists -2. **Project Context**: Read relevant project documentation before starting work - - Vision and roadmap for understanding project goals - - Tech stack for understanding technology constraints - - Architecture for understanding system design -3. **Standards**: Reference appropriate standards when writing code - - Global standards apply to all code - - Domain-specific standards (frontend/backend/testing) apply to relevant code -4. **Keep Updated**: Update documentation when making significant changes - - Update project docs when goals, tech stack, or architecture changes - - Update standards when team conventions evolve - - Update INDEX.md when adding or removing documentation -5. **Customize**: Adapt all documentation to your project's specific needs - - Project documentation should reflect your actual project - - Standards should reflect your team's conventions - - Both should be version-controlled and reviewed regularly - -## Updating Documentation - -### When to Update - -- **Project docs**: When project goals, tech stack, or architecture changes -- **Standards**: When team conventions evolve or new patterns are adopted -- **INDEX.md**: When adding, removing, or significantly changing documentation - -### How to Update - -1. Edit the relevant documentation file directly -2. Update INDEX.md if the file's purpose or description changes -3. Ensure .github/copilot-instructions.md still references this INDEX.md -4. Commit changes to version control -5. Notify the team of significant documentation changes - -### Getting Help - -Use the Documentation Manager skill to: -- Initialize documentation in a new project -- Add new documentation files -- Update existing documentation -- Validate documentation consistency -- Manage INDEX.md automatically -- Ensure .github/copilot-instructions.md integration - ---- - -## Documentation Priority - -When making development decisions, follow this priority order: - -1. **Project documentation** in `.maister/docs/` (highest priority) - - Represents team decisions and project-specific requirements -2. **Code patterns** visible in the codebase - - Shows how the team actually implements things -3. **User's direct instructions** - - Specific guidance for the current task -4. **General best practices** (lowest priority) - - Default to industry standards when no specific guidance exists - -**The documentation in `.maister/docs/` represents team decisions and should be followed unless the user explicitly overrides them.** - ---- - -**Last Generated**: [Automatically updated by Documentation Manager] -**Maintained by**: Documentation Manager skill diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/api.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/api.md deleted file mode 100644 index 702b18f2..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/api.md +++ /dev/null @@ -1,25 +0,0 @@ -## API Design - -### RESTful Principles -Use resource-based URLs with appropriate HTTP methods (GET, POST, PUT, PATCH, DELETE). - -### Consistent Naming -Use lowercase, hyphenated or underscored names consistently across endpoints. - -### Versioning -Implement versioning (URL path or headers) to manage breaking changes. - -### Plural Nouns -Use plural nouns for resources (`/users`, `/products`). - -### Limited Nesting -Keep URL nesting to 2-3 levels maximum for readability. - -### Query Parameters -Use query parameters for filtering, sorting, and pagination. - -### Proper Status Codes -Return appropriate HTTP status codes (200, 201, 400, 404, 500). - -### Rate Limit Headers -Include rate limit information in response headers. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/migrations.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/migrations.md deleted file mode 100644 index 1dde15c3..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/migrations.md +++ /dev/null @@ -1,22 +0,0 @@ -## Database Migrations - -### Reversible -Always implement rollback methods for safe migration reversals. - -### Small and Focused -Keep each migration to a single logical change. - -### Zero-Downtime Awareness -Consider deployment order and backward compatibility for high-availability systems. - -### Separate Schema and Data -Keep schema changes separate from data migrations for safer rollbacks. - -### Careful Indexing -Create indexes on large tables carefully, using concurrent options when available. - -### Descriptive Names -Use names that indicate what the migration does. - -### Version Control -Commit migrations; never modify existing ones after deployment. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/models.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/models.md deleted file mode 100644 index beeb2a1e..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/models.md +++ /dev/null @@ -1,25 +0,0 @@ -## Models - -### Clear Naming -Use singular names for models and plural for tables (or follow framework conventions). - -### Timestamps -Include created and updated timestamps for auditing and debugging. - -### Database Constraints -Enforce data rules at the database level (NOT NULL, UNIQUE, foreign keys). - -### Appropriate Types -Choose data types that match purpose and size requirements. - -### Index Foreign Keys -Index foreign key columns and frequently queried fields. - -### Multi-Layer Validation -Validate at both model and database levels for defense in depth. - -### Clear Relationships -Define relationships with appropriate cascade behaviors and naming. - -### Practical Normalization -Balance normalization with query performance needs. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/queries.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/queries.md deleted file mode 100644 index 11877a48..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/backend/queries.md +++ /dev/null @@ -1,22 +0,0 @@ -## Database Queries - -### Parameterized Queries -Always use parameterized queries or ORM methods; never interpolate user input into SQL. - -### Avoid N+1 -Use eager loading or joins to fetch related data in one query. - -### Select Only Needed Columns -Request only the columns you need rather than SELECT *. - -### Index Strategic Columns -Index columns used in WHERE, JOIN, and ORDER BY clauses. - -### Transactions -Wrap related operations in transactions to maintain consistency. - -### Query Timeouts -Set timeouts to prevent runaway queries from impacting performance. - -### Cache Expensive Queries -Cache results of complex or frequent queries when appropriate. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/accessibility.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/accessibility.md deleted file mode 100644 index 054da1f4..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/accessibility.md +++ /dev/null @@ -1,25 +0,0 @@ -## Accessibility - -### Semantic HTML -Use appropriate elements (nav, main, button) that convey meaning to assistive technologies. - -### Keyboard Navigation -Make all interactive elements accessible via keyboard with visible focus indicators. - -### Color Contrast -Maintain 4.5:1 contrast for normal text; don't rely solely on color to convey information. - -### Alt Text and Labels -Provide descriptive alt text for images and labels for form inputs. - -### Screen Reader Testing -Verify all views work with screen readers. - -### ARIA When Needed -Use ARIA attributes to enhance complex components when semantic HTML isn't enough. - -### Heading Structure -Use heading levels (h1-h6) in proper order for clear document outline. - -### Focus Management -Manage focus appropriately in dynamic content, modals, and SPAs. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/components.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/components.md deleted file mode 100644 index 25c4b2ef..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/components.md +++ /dev/null @@ -1,28 +0,0 @@ -## Components - -### Single Responsibility -Each component should do one thing well. - -### Reusability -Design components to work across different contexts with configurable props. - -### Composability -Build complex UIs by combining smaller components rather than creating monoliths. - -### Clear Interface -Define explicit, documented props with sensible defaults. - -### Encapsulation -Keep implementation details private; expose only what's necessary. - -### Consistent Naming -Use descriptive names that indicate purpose and follow team conventions. - -### Local State -Keep state as close to where it's used as possible; lift only when needed. - -### Minimal Props -If a component needs many props, consider composition or splitting it. - -### Documentation -Document usage, props, and examples to help team adoption. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/css.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/css.md deleted file mode 100644 index 1eb0a170..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/css.md +++ /dev/null @@ -1,16 +0,0 @@ -## CSS - -### Consistent Methodology -Stick to the project's chosen approach (Tailwind, BEM, CSS modules, etc.) across the entire codebase. - -### Work With the Framework -Use framework patterns as intended rather than fighting them with excessive overrides. - -### Design Tokens -Establish and document consistent values for colors, spacing, and typography. - -### Minimize Custom CSS -Prefer framework utilities to reduce custom styling maintenance. - -### Production Optimization -Use CSS purging or tree-shaking to remove unused styles. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/responsive.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/responsive.md deleted file mode 100644 index b798801d..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/frontend/responsive.md +++ /dev/null @@ -1,28 +0,0 @@ -## Responsive Design - -### Mobile-First -Start with mobile layout and progressively enhance for larger screens. - -### Standard Breakpoints -Use consistent breakpoints (mobile, tablet, desktop) across the application. - -### Fluid Layouts -Use percentage-based widths and flexible containers that adapt to screen size. - -### Relative Units -Prefer rem/em over fixed pixels for better scalability. - -### Cross-Device Testing -Test across multiple screen sizes to ensure a balanced experience. - -### Touch-Friendly -Size tap targets appropriately (minimum 44x44px) for mobile users. - -### Mobile Performance -Optimize images and assets for mobile network conditions. - -### Readable Typography -Maintain readable font sizes across all breakpoints. - -### Content Priority -Show the most important content first on smaller screens. diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/global/validation.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/global/validation.md deleted file mode 100644 index 56b66eb3..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/global/validation.md +++ /dev/null @@ -1,28 +0,0 @@ -## Validation - -### Server-Side Always -Validate on the server; client-side validation alone is insufficient for security and data integrity. - -### Client-Side for Feedback -Use client-side validation for immediate user feedback, but duplicate checks server-side. - -### Validate Early -Check inputs as early as possible and reject invalid data before processing. - -### Specific Errors -Provide clear, field-specific messages that help users correct their input. - -### Allowlists Over Blocklists -Define what's allowed rather than trying to block everything else. - -### Type and Format Checks -Validate data types, formats, ranges, and required fields systematically. - -### Input Sanitization -Sanitize user input to prevent injection attacks (SQL, XSS, command injection). - -### Business Rules -Validate business logic (sufficient balance, valid dates) at the appropriate layer. - -### Consistent Enforcement -Apply validation uniformly across all entry points (forms, APIs, background jobs). diff --git a/plugins/maister-copilot/skills/docs-manager/docs/standards/testing/test-writing.md b/plugins/maister-copilot/skills/docs-manager/docs/standards/testing/test-writing.md deleted file mode 100644 index 337b793b..00000000 --- a/plugins/maister-copilot/skills/docs-manager/docs/standards/testing/test-writing.md +++ /dev/null @@ -1,25 +0,0 @@ -## Test Writing - -### Test Behavior -Focus on what code does, not how it does it, to allow safe refactoring. - -### Clear Names -Use descriptive names explaining what's tested and expected (`shouldReturnErrorWhenUserNotFound`). - -### Mock External Dependencies -Isolate tests by mocking databases, APIs, and external services. - -### Fast Execution -Keep unit tests fast (milliseconds) so developers run them frequently. - -### Risk-Based Testing -Prioritize testing based on business criticality and likelihood of bugs. - -### Balance Coverage and Velocity -Adjust test coverage based on project needs and team workflow. - -### Critical Path Focus -Ensure core user workflows and critical business logic are well-tested. - -### Appropriate Depth -Match edge case testing to the risk profile of the code. diff --git a/plugins/maister-copilot/skills/docs-manager/references/claude-md-template.md b/plugins/maister-copilot/skills/docs-manager/references/claude-md-template.md deleted file mode 100644 index a983d70c..00000000 --- a/plugins/maister-copilot/skills/docs-manager/references/claude-md-template.md +++ /dev/null @@ -1,27 +0,0 @@ -# .github/copilot-instructions.md Documentation Section Template - -Add this section to the project's `.github/copilot-instructions.md` file. Place it prominently near the top. Verify the INDEX.md path is correct and the file exists before adding. - -```markdown -## Project Documentation & Standards - -Before writing or changing any code — even for quick, direct requests that don't go through a `/maister-*` workflow — ground yourself in the project's documentation: - -1. Read @.maister/docs/INDEX.md to see what's documented. It is the map to everything the team maintains — coding standards by domain, project vision/tech-stack/architecture, and any other project knowledge (business domain, glossaries, decisions, etc.). -2. Then open and read the specific files it points to that are relevant to your task — standards AND any project/domain docs. The index alone is not enough. -3. Follow the standards as you work (they represent team decisions; if one conflicts with the task, ask the user) and use the project docs as context. - -### Standards Evolution - -When you notice recurring patterns, fixes, or conventions during implementation that aren't yet captured in standards — suggest adding them. Examples: -- A bug fix reveals a pattern that should be standardized (e.g., "always validate X before Y") -- PR review feedback identifies a convention the team wants enforced -- The same type of fix is needed across multiple files -- A new library/pattern is adopted that should be documented - -When this happens, briefly suggest the standard to the user. If approved, invoke `/maister-standards-update` with the identified pattern. - -## Maister Workflows - -This project uses the maister plugin for structured development workflows. When any `/maister-*` command is invoked, execute it via the Skill tool immediately — do not skip workflows for "straightforward" tasks. The user chose the workflow intentionally; complexity assessment is the workflow's job. -``` diff --git a/plugins/maister-copilot/skills/docs-manager/references/index-md-template.md b/plugins/maister-copilot/skills/docs-manager/references/index-md-template.md deleted file mode 100644 index 818db313..00000000 --- a/plugins/maister-copilot/skills/docs-manager/references/index-md-template.md +++ /dev/null @@ -1,66 +0,0 @@ -# INDEX.md Template - -Use this structure when generating or updating `.maister/docs/INDEX.md`. Scan the actual `.maister/docs/` directory to populate sections dynamically — do not hardcode file lists. - -For technical standards, the description MUST enumerate specific practices/conventions documented in the file, not just a generic category description. - -```markdown -# Documentation Index - -**IMPORTANT**: Read this file at the beginning of any development task to understand available documentation and standards. - -## Quick Reference - -### Project Documentation -Project-level documentation covering vision, goals, architecture, and technology choices. - -### Technical Standards -Coding standards, conventions, and best practices organized by domain. - ---- - -## Project Documentation - -Located in `.maister/docs/project/` - -### Vision (`project/vision.md`) -[Brief description of what this file contains] - -### Roadmap (`project/roadmap.md`) -[Brief description of what this file contains] - -### Tech Stack (`project/tech-stack.md`) -[Brief description of what this file contains] - -### Architecture (`project/architecture.md`) -[Brief description of what this file contains - if exists] - ---- - -## Technical Standards - -### [Category Name] Standards - -Located in `.maister/docs/standards/[category]/` - -#### [Standard Name] (`standards/[category]/[name].md`) -[Practice-specific description — enumerate actual conventions, not generic text] - -[... repeat for all categories and standards discovered in the directory ...] - ---- - -## How to Use This Documentation - -1. **Start Here**: Always read this INDEX.md first to understand what documentation exists -2. **Project Context**: Read relevant project documentation before starting work -3. **Standards**: This index only points to the standards — open and follow the specific standard files relevant to your task; don't rely on the index alone -4. **Keep Updated**: Update documentation when making significant changes -5. **Customize**: Adapt all documentation to your project's specific needs - -## Updating Documentation - -- Project documentation should be updated when goals, tech stack, or architecture changes -- Technical standards should be updated when team conventions evolve -- Always update INDEX.md when adding, removing, or significantly changing documentation -``` diff --git a/plugins/maister-copilot/skills/implementation-plan-executor/SKILL.md b/plugins/maister-copilot/skills/implementation-plan-executor/SKILL.md deleted file mode 100644 index a645f927..00000000 --- a/plugins/maister-copilot/skills/implementation-plan-executor/SKILL.md +++ /dev/null @@ -1,412 +0,0 @@ ---- -name: implementation-plan-executor -description: Execute implementation plans by delegating each task group to task-group-implementer subagent. Main agent coordinates prepares context, invokes subagent, processes output, marks checkboxes, updates work-log. Uses lazy standards loading from INDEX.md with keyword-triggered discovery. -user-invocable: false ---- - -You are an implementation plan executor that delegates task groups to subagents with continuous standards discovery. - -## Core Principles - -1. **Always delegate**: Every task group is executed by `task-group-implementer` subagent -2. **Lazy standards loading**: Load standards per task group, not all upfront -3. **Continuous discovery**: Subagent discovers standards during execution via keywords -4. **Test-driven**: Test step (N.1) before implementation steps (N.2+) -5. **Immediate progress**: Mark checkboxes right after each step completes -6. **Main agent owns visibility**: Work-log and checkboxes always updated by main agent - -## Execution Model - -**Always delegate.** Every task group is executed by the `task-group-implementer` subagent. The main agent NEVER writes implementation code directly. - -**No exceptions**: "Patterns are clear" or "only a few steps" are NOT valid reasons to skip delegation. - -❌ Wrong: "Let me read standards..." → Implement directly -✅ Right: Task tool → Process output → Mark checkboxes - -## Phase 1: Initialize - -1. **Locate task**: Get path from context or user -2. **Validate files exist**: - - `implementation/implementation-plan.md` (required) - - `implementation/spec.md` (recommended) - - `.maister/docs/INDEX.md` (required for standards) -3. **Check for task group items**: Call `TaskList` to find existing task group items from the planner. If found, use them. If not, create them with `TaskCreate` for each task group (fallback for plans created before task system migration). -4. **Initialize work-log.md**: - ```markdown - # Work Log - - ## [timestamp] - Implementation Started - - **Total Steps**: [N] - **Task Groups**: [list] - - ## Standards Reading Log - - ### Loaded Per Group - (Entries added as groups execute) - ``` - -**Do NOT read all standards upfront.** Standards are loaded lazily per task group. - -## Phase 2: Execute (wave-based, parallel by default) - -**Dispatch unit is the wave**, not the individual group. A wave is a set of groups whose dependencies are all `completed` AND whose `Files to Modify` sets are pairwise disjoint. All groups in a wave fire in parallel from a single message; the next wave is computed once every member returns. - -### Phase 2 Validation (before computing waves) - -Read each group from `implementation-plan.md` and verify both `**Dependencies:**` and `**Files to Modify:**` are present. If any group is missing `Files to Modify`: - -- Treat the entire run as `--sequential` (see opt-out below). -- Append a warning to `work-log.md`: `Plan missing 'Files to Modify' on Group N — falling back to sequential execution.` - -Never assume missing `Files to Modify` means "None" — silent disjoint assumptions are how parallel implementers collide on the same file. - -### Wave Computation - -1. Parse `Dependencies:` (list of group numbers) and `Files to Modify:` (list of paths or `"None"`) for every group. -2. Build the directed dependency graph from `Dependencies:`. -3. The **ready set** = groups whose dependencies are all `completed` AND that have not yet been dispatched. -4. Greedily build the next wave from the ready set in plan order: a group joins the wave iff its `Files to Modify` does not overlap any group already in the wave. Conflicting groups stay in the ready set for the next wave. -5. Treat `"None"` as the empty set — review-only groups never conflict on files. -6. Glob entries (e.g. `src/migrations/*.sql`) match by glob expansion against other groups' declared paths. - -### Wave Dispatch - -For each wave: - -0. For every group in the wave, `TaskUpdate` to `status: "in_progress"` with `owner: "maister-task-group-implementer"`. - -1. **Prepare group context** (per group): - - Extract group content from `implementation-plan.md` (including `Visual References` section, if present) - - Check "Standards Compliance" section — identify standards relevant to this group - - Check INDEX.md for additional standards matching group topic - - Get relevant spec sections - - **Design context** (when `analysis/design-context/` exists): include `design-context/brief.md` excerpt (Layer 0 + the relevant screen sections from Layer 3) when relevant to this group. Do NOT inline HTML/binary mockups — pass paths only and rely on the implementer to Read them. ASCII mockup excerpts (small, text) MAY be inlined when directly relevant. The planner-supplied `locator` field already tells the implementer which region to focus on within large mockups. - -2. **Fan out — CRITICAL: parallel dispatch in a single message**: - - All groups in the wave MUST be dispatched in **one assistant turn** containing **one `Task` tool call per group**. This is not a loop. This is one message with N tool calls. - - ❌ Wrong: Send `Task(G2)`, await result, send `Task(G3)`, await result, send `Task(G4)`. → That is serial execution wearing wave-shaped clothing. Wave duration becomes `sum(G2, G3, G4)` instead of `max(G2, G3, G4)` and defeats the entire wave optimization. The "comfortable" pattern of one-Task-per-turn is the exact anti-pattern this skill exists to prevent. - - ✅ Right: One assistant message with N `Task` tool-use blocks emitted before any of them returns. The runtime returns all N results before the next assistant turn. - - Per-call parameters: - - subagent_type: `maister-task-group-implementer` - - prompt: per-group content + initial standards + INDEX.md path + spec excerpt + sibling-wave note (see "Subagent Invocation") - - **SELF-CHECK before sending the message**: Are you about to emit a message with one `Task` call when the current wave has more than one group? If yes, STOP. Compose every wave member's prompt first, then emit them all in the same message. Awaiting one before composing the next violates this skill's contract. If the wave has exactly one group, a single `Task` call is correct. - -3. **Wait for all wave members to return**, then for each result: - - Parse completed steps, standards applied, test results. - - Mark all group checkboxes in `implementation-plan.md`. - - **Sync the HTML companion** (`implementation/implementation-plan.html`, if it exists): run ONE Bash command per completed group, substituting its number for `N` (idempotent — safe to re-run): - ```bash - sed -i '' -e 's/\(data-step="N\.[0-9][0-9]*" class="step \)todo/\1done/g' \ - -e 's/\(data-group="N" class="group \)todo/\1done/g' \ - implementation/implementation-plan.html - ``` - (Linux: `sed -i` without `''`. The leading quote in `data-step="N\.` anchors the exact group — group 1 cannot match 11.) Then VERIFY: `grep -c 'data-group="N" class="group done"'` must return 1; if 0, append a warning to `work-log.md` (`HTML plan sync missed markers for Group N`) — a visible miss, never a silent one. File absent → skip silently; sync never blocks the wave. - - Add a group entry to `work-log.md` with standards trail. - - Verify test results are acceptable. - - `TaskUpdate` to `status: "completed"` with `metadata: {completed_at, tests_passed, files_modified, standards_applied, wave: N}`. - -4. **Partial-wave failure handling**: - - Do NOT cancel sibling subagents in the same wave — they may produce valid work even when one peer fails. - - After every wave member has returned, run the existing failure recovery flow (see "Error Handling" → "Subagent Failure") for each failed group individually. - - Mark successful groups in the wave as `completed` normally. Keep failed groups `in_progress` with `metadata: {failed_at, failure_reason, wave: N}` until the ask_user recovery path resolves them. - - The next wave is NOT computed until every failed group's recovery decision is made. - -5. After the wave fully resolves (all members `completed` or recovered), recompute the ready set and proceed to the next wave. - - **SELF-CHECK before dispatching the next wave**: for every group marked `completed` this wave, did you run the HTML marker-flip command (step 3)? If unsure, run it now — it is idempotent. - -### `--sequential` Opt-Out - -Read `orchestrator.options.sequential` from `orchestrator-state.yml` at Phase 2 entry. When true (or when the validation fallback above triggered): - -- Treat every wave as size 1: dispatch groups one at a time in plan order, ignoring file-overlap analysis. -- Functionally equivalent to the legacy serial loop. -- Use cases: debugging a flaky group, constrained dev environments (single port, single DB schema), users who explicitly want serial execution. - -## Continuous Standards Discovery - -**Philosophy**: Standards are discovered when relevant, not memorized upfront. - -### Three Sources of Standards - -1. **Implementation Plan Standards**: The "Standards Compliance" section in implementation-plan.md lists standards identified during planning. Filter these per task group based on relevance. - -2. **INDEX.md Discovery**: The file `.maister/docs/INDEX.md` maps topics to standard files. Use it to find standards not listed in the plan. - -3. **Keyword-Triggered Discovery**: During execution, step descriptions may reveal need for additional standards. - -### Keyword Triggers (Suggestive, Not Exhaustive) - -These are **examples** to guide discovery. Do not limit discovery to only these triggers - use judgment to identify when other standards may apply. - -| Example Keywords | May Suggest Standards For | -|------------------|---------------------------| -| file, upload, download | file handling, storage | -| auth, login, session | security, authentication | -| email, notification | external services | -| form, input, validation | forms, validation | -| API, endpoint | api design, error handling | -| migration, schema | database conventions | - -**Key principle**: If a step involves a concept that likely has project standards, check INDEX.md even if no keyword explicitly matches. - -### Discovery Flow - -``` -Per task group: - 1. Check "Standards Compliance" section in implementation-plan.md - - Identify which listed standards are relevant to THIS group - - Read those standards - - 2. Check INDEX.md for additional standards matching group topic - - 3. During step execution: - - If step description suggests a standard may apply - - Check INDEX.md, read if found and not yet loaded - - Log discovery with trigger reason - - 4. Apply discovered standards to implementation -``` - -### Standards Reading Log Format - -```markdown -## Standards Reading Log - -### Group 1: [Name] -**From Implementation Plan**: -- [x] .maister/docs/standards/backend/api.md - Listed in Standards Compliance - -**From INDEX.md**: -- [x] .maister/docs/standards/global/naming.md - Group topic match - -**Discovered During Execution**: -- [x] .maister/docs/standards/global/security.md - Step 1.3 (auth-related logic) - -### Group 2: [Name] -**From Implementation Plan**: -- [x] .maister/docs/standards/frontend/forms.md - Listed in Standards Compliance -``` - -## Subagent Invocation - -When delegating a task group, use this prompt structure: - -```markdown -## Task: Execute Task Group [N] - -### Task Group Content -[Paste the task group section from implementation-plan.md, including the `Visual References` block if present] - -### Specification Excerpt -[Relevant sections from spec.md for this group] - -### Standards from Implementation Plan -The implementation plan's "Standards Compliance" section lists these standards. -Identify which are relevant to this group and read them: -- [path/to/standard1.md] - [likely relevant because...] -- [path/to/standard2.md] - [likely relevant because...] - -### Standards Discovery -You have access to `.maister/docs/INDEX.md` for continuous standards discovery. -- Check INDEX.md for additional standards matching this group's topic -- During implementation, discover more standards as step context reveals needs -- Do not limit discovery to explicit keyword matches - use judgment - -### Design Context -[OMIT this section entirely when no `Visual References` are present in the task group AND no `analysis/design-context/` exists.] -[OTHERWISE include:] -- Design context root: `analysis/design-context/` -- Brief excerpt (when present): [Layer 0 from `design-context/brief.md` + relevant screen sections] -- Mockup files referenced by this group: [list paths from `Visual References`] -- Inline ASCII excerpt (when ASCII mockup is small and directly relevant): [paste here] -- Binding rule: each mockup in `Visual References` MUST be read before implementing; layout, copy, field order, and explicit states are binding; self-check each `acceptance` criterion before declaring done. - -### Sibling Wave -[None] OR [Group K (Files to Modify: ...) is running in parallel in the same wave. File sets are disjoint per the executor's wave-computation invariant; do not edit paths outside your declared `Files to Modify`.] - -### Requirements -1. Execute in test-driven order: tests (N.1) → implementation (N.2+) → verify (N.n) -2. Log all standards applied (from plan, from INDEX.md, discovered during execution) -3. When `Visual References` present: read each mockup before implementing, log per-reference compliance in your report -4. Report any failures with root cause analysis -5. Do NOT mark checkboxes - main agent handles that - -### Expected Output Format -[See Subagent Output Format section] -``` - -## Subagent Output Format - -The task-group-implementer returns structured output: - -```markdown -## Group [N] Execution Report - -### Status: [SUCCESS/PARTIAL/FAILED] - -### Steps Completed -- [x] N.1 - [description] -- [x] N.2 - [description] -- [ ] N.3 - [description] (if incomplete) - -### Standards Applied -**From Implementation Plan**: -- .maister/docs/standards/backend/api.md - -**From INDEX.md** (group topic): -- .maister/docs/standards/global/naming.md - -**Discovered During Execution**: -- .maister/docs/standards/global/error-handling.md (step N.2, error handling logic) - -### Visual Compliance -[OMIT this section entirely when the group had no `Visual References`.] -[OTHERWISE: one line per reference] -- ✓ analysis/design-context/mockups/login.html — screen:login — field order, error states, "Forgot password?" link match -- ⚠ analysis/design-context/mockups/dashboard.html — screen:dashboard — 3-column layout matched, but icon set differs (used Heroicons; mockup shows custom icons — flagged for review) - -### Test Results -**Command**: [test command run] -**Result**: [N passed, M failed] -**Details**: [if failures, brief explanation] - -### Files Modified -- path/to/file1.ts (created) -- path/to/file2.ts (modified) - -### Notes -[Any decisions made, blockers encountered, recommendations] -``` - -## Test-Driven Enforcement - -### Pattern Per Task Group - -``` -N.1 - Write tests (2-8 focused tests) -N.2 - Implementation step -... -N.n-1 - Implementation step -N.n - Run tests (only this group's tests) -``` - -### Enforcement - -Before executing step N.2 or higher: - -1. Verify N.1 (test step) is complete -2. If not complete, use ask_user: - ``` - Question: "Test step N.1 not completed. How to proceed?" - Header: "Tests" - Options: - - "Complete tests first" - Execute N.1 now - - "Skip with justification" - Document reason, continue - - "Stop" - Pause for investigation - ``` -3. If skipped, mark as `- [~] N.1 SKIPPED: [reason]` - -## Progress Tracking - -### Checkbox Marking - -**Format**: `- [ ]` → `- [x]` (or `- [~]` for skipped) - -**Timing**: Immediately after step completion. Never batch. Never mark ahead. - -**Responsibility**: Always main agent — subagent does NOT mark checkboxes. - -### Work-Log Updates - -After each task group: - -```markdown -## [timestamp] - Group [N] Complete - -**Steps**: N.1 through N.M completed -**Standards Applied**: -- From plan: [list] -- From INDEX.md: [list] -- Discovered: [list with trigger reason] -**Tests**: [N] passed -**Files Modified**: [list] -**Notes**: [any decisions or discoveries] -``` - -## Phase 3: Finalize - -1. **Validate completion**: - - No `- [ ]` checkboxes remain - - All groups have work-log entries - - Standards Reading Log is complete - - All group tasks are `completed` via `TaskList` (cross-validate against markdown checkboxes) - -2. **Run full project test suite** (all tests, not just feature tests — catches regressions in unrelated areas) - -3. **Final work-log entry**: - ```markdown - ## [timestamp] - Implementation Complete - - **Total Steps**: [N] completed - **Total Standards**: [M] applied - **Test Suite**: [status] - **Duration**: [if tracked] - ``` - -4. **Return summary** to calling orchestrator - -## Error Handling - -### Subagent Failure - -If task-group-implementer reports failure: - -1. **Do NOT auto-rollback** - User-confirmed rollback only -2. **Analyze root cause** from subagent output -3. **Check for easy fixes**: config issues, missing dependencies, test setup -4. **Use ask_user**: - ``` - Question: "Group [N] implementation failed: [brief reason]. How to proceed?" - Header: "Failure" - Options: - - "Try suggested fix" - [if easy fix identified] - - "Retry group" - Re-invoke subagent - - "Complete manually" - Main agent completes remaining steps for this group - - "Rollback changes" - Revert this group's changes - - "Stop" - Pause for investigation - ``` - -### Test Failure - -If tests fail after implementation: - -1. Analyze failure output -2. If obvious fix: apply and re-run -3. If unclear: use ask_user with options - -## Validation Checklist - -Before returning success: - -### Completion -- [ ] All steps marked `[x]` or `[~]` (skipped with reason) -- [ ] All task groups have work-log entries -- [ ] Full test suite passes - -### Standards -- [ ] Standards Reading Log complete for all groups -- [ ] All three sources logged: from plan, from INDEX.md, discovered -- [ ] Standards applied appropriately per step - -### Artifacts -- [ ] implementation-plan.md checkboxes updated -- [ ] work-log.md complete with timeline -- [ ] No uncommitted partial changes diff --git a/plugins/maister-copilot/skills/implementation-verifier/SKILL.md b/plugins/maister-copilot/skills/implementation-verifier/SKILL.md deleted file mode 100644 index ca4ec519..00000000 --- a/plugins/maister-copilot/skills/implementation-verifier/SKILL.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -name: implementation-verifier -description: Verify completed implementations for quality assurance. Delegates all verification work to specialized subagents - completeness checking, test execution, code review, pragmatic review, production readiness, and reality assessment. Compiles results into comprehensive verification report. Read-only verification - reports issues but does not fix them. Use after implementation is complete and before code review/commit. -user-invocable: false ---- - -You are an implementation verifier that orchestrates comprehensive quality assurance on completed implementations by delegating to specialized subagents. - -## Core Principle - -**Read-only verification via delegation**: Delegate all analysis to subagents. Compile results. Never fix, modify, or re-implement. - -## Responsibilities - -1. Validate prerequisites exist -2. Delegate ALL verifications to subagents in parallel (core + optional) -3. Compile all results into verification report -4. Update roadmap if exists (optional) -5. Output summary with overall verdict - -## Output Artifacts - -| Artifact | Condition | -|----------|-----------| -| `verification/implementation-verification.md` | Always | -| `verification/implementation-verification.html` | Always (operator-facing companion — never blocks; see Phase 3) | -| `verification/code-review-report.md` | If code_review_enabled | -| `verification/pragmatic-review.md` | If pragmatic_review_enabled | -| `verification/production-readiness-report.md` | If production_check_enabled | -| `verification/reality-check.md` | If reality_check_enabled | -| `verification/visual-fidelity.md` | Surfaced (not produced here) when e2e-test-verifier wrote one | - ---- - -## Invocation Context - -**Check for orchestrator state file** at task path: - -- **Orchestrator mode**: If `orchestrator-state.yml` exists, read verification options from it. Execute enabled reviews without re-prompting. -- **Standalone mode**: If no state file, prompt user for each optional review using ask_user. - -**Orchestrator options** (when present, are mandatory): -- `skip_test_suite` (when true, test-suite-runner is skipped — full test suite already passed during implementation phase) -- `code_review_enabled` / `code_review_scope` -- `pragmatic_review_enabled` -- `production_check_enabled` -- `reality_check_enabled` - ---- - -## Phase 1: Initialize & Validate - -1. **Get task path** from user or orchestrator parameter -2. **Validate prerequisites exist**: - - `implementation/implementation-plan.md` (required) - - `implementation/spec.md` (required) - - `implementation/work-log.md` (required) -3. **Read docs/INDEX.md** to understand available standards -4. **Determine invocation context** (orchestrator or standalone) -5. **Create task items for verification tracking** using `TaskCreate` tool: - - Subject: "Completeness check", activeForm: "Checking implementation completeness" - - Subject: "Test suite", activeForm: "Running test suite" — only if NOT skip_test_suite. When skip_test_suite is true, create task pre-completed with `metadata: {skipped: true, reason: "Full test suite passed during implementation phase"}` - - Subject: "Code review", activeForm: "Running code review" — only if code_review_enabled - - Subject: "Pragmatic review", activeForm: "Running pragmatic review" — only if pragmatic_review_enabled - - Subject: "Production readiness", activeForm: "Checking production readiness" — only if production_check_enabled - - Subject: "Reality assessment", activeForm: "Running reality assessment" — only if reality_check_enabled - - Subject: "Compile report", activeForm: "Compiling verification report" -6. **Set dependencies** using `TaskUpdate` with `addBlockedBy`: "Compile report" blocked by ALL verification tasks above - -If prerequisites missing, report and stop. - ---- - -## Phase 2: Delegate All Verifications - -**ANTI-PATTERN — DO NOT DO ANY OF THIS:** -- ❌ "Let me run the tests..." — STOP. Delegate to test-suite-runner. -- ❌ "I'll check implementation-plan.md..." — STOP. Delegate to implementation-completeness-checker. -- ❌ "Let me read the standards..." — STOP. Delegate to implementation-completeness-checker. -- ❌ "I'll verify the work-log..." — STOP. Delegate to implementation-completeness-checker. -- ❌ Running any Bash command to execute tests — STOP. Delegate to test-suite-runner. -- ❌ "Let me review the code quality..." — STOP. Delegate to code-reviewer. -- ❌ "I'll check for over-engineering..." — STOP. Delegate to code-quality-pragmatist. -- ❌ "Let me verify production readiness..." — STOP. Delegate to production-readiness-checker. -- ❌ "I'll assess whether this solves the problem..." — STOP. Delegate to reality-assessor. -- ❌ Reading source code to find security/performance issues — STOP. Delegate to code-reviewer. - -**Verifications run in two sequential steps to avoid parallel test conflicts.** - -### Step 1: Determine enabled optional reviews - -1. **Check invocation context** for each optional review: - - If orchestrator mode AND option is `true`: Include in verification (mandatory) - - If orchestrator mode AND option is `false`: Skip (mark task as completed with `metadata: {skipped: true}`) - - If orchestrator mode AND option is `null`: Warn and prompt user - - If standalone mode: Prompt user with ask_user - -### Step 2: Set all tasks to in_progress - -2. Use `TaskUpdate` to set ALL enabled verification tasks to `status: "in_progress"`. For skipped optional reviews, use `TaskUpdate` with `status: "completed"` and `metadata: {"skipped": true}`. - -### Step 3a: Run test suite (sequential, if NOT skip_test_suite) - -**Why sequential**: Test-suite-runner and reality-assessor both run tests. Running them in parallel causes conflicts. Test-suite-runner runs first and writes results to a file that reality-assessor reads. - -Task tool call (if NOT skip_test_suite): -- subagent_type: `maister-test-suite-runner` -- description: `Run full test suite` -- prompt: Include task_path, task_description, test_command (if known). The subagent runs ALL tests, analyzes results, and writes results to `verification/test-suite-results.md`. - -**Wait for test-suite-runner to complete** before proceeding to Step 3b. Mark the test suite task as `completed` with results. - -**When `skip_test_suite: true`**: Skip Step 3a entirely. Go straight to Step 3b. The full project test suite already passed during the implementation phase. The verification report will note tests were verified during implementation. - -### Step 3b: Run all other verifications (parallel) - -**INVOKE NOW** — send ALL remaining enabled subagents in a SINGLE message (up to 5 parallel Task tool calls): - -Task tool call (always): -- subagent_type: `maister-implementation-completeness-checker` -- description: `Check implementation completeness` -- prompt: Include task_path. The subagent checks plan completion, standards compliance, and documentation completeness. - -Task tool call (if code_review_enabled): -- subagent_type: `maister-code-reviewer` -- description: `Code quality review` -- prompt: Include task_path, scope (from code_review_scope or "all"), report_path (`[task_path]/verification/code-review-report.md`) - -Task tool call (if pragmatic_review_enabled): -- subagent_type: `maister-code-quality-pragmatist` -- description: `Pragmatic code review` -- prompt: Include task_path, report_path (`[task_path]/verification/pragmatic-review.md`) - -Task tool call (if production_check_enabled): -- subagent_type: `maister-production-readiness-checker` -- description: `Production readiness check` -- prompt: Include task_path, target (production), report_path (`[task_path]/verification/production-readiness-report.md`) - -Task tool call (if reality_check_enabled): -- subagent_type: `maister-reality-assessor` -- description: `Reality assessment` -- prompt: Include task_path, report_path (`[task_path]/verification/reality-check.md`). - - **If test-suite-runner ran (Step 3a)**: Include `skip_test_execution: true` and path to `verification/test-suite-results.md`. Reality-assessor should read test results from that file instead of running tests. - - **If test-suite-runner was skipped**: Include `skip_test_execution: false`. Reality-assessor should run tests itself since no other agent did. - -**SELF-CHECK**: Did you invoke test-suite-runner separately in Step 3a (or skip it), then invoke all remaining subagents in a single parallel message in Step 3b? Or did you launch everything at once? If the latter, STOP — test-suite-runner must complete before the parallel batch. - -### Step 4: Process all results - -After ALL subagents return: -1. Use `TaskUpdate` to set each verification task to `status: "completed"` -2. Extract status, issues, and findings from each -3. Aggregate issue counts -4. Track any critical issues that would affect overall verdict - -### Impact on Overall Status - -- Code review critical issues → overall status Failed -- Pragmatic review critical over-engineering → overall status Failed -- Production readiness deployment blockers → overall status Failed -- Reality assessment critical gaps → overall status Failed - ---- - -## Phase 3: Compile Verification Report - -Use `TaskUpdate` to set "Compile report" task to `status: "in_progress"`. - -1. **Compile all findings** from Phase 2 -2. **Determine overall status**: - - | Status | Criteria | - |--------|----------| - | ✅ Passed | 100% implementation, 95%+ tests passing (or skipped — verified in implementation), standards compliant, docs complete, no critical issues from optional reviews | - | ⚠️ Passed with Issues | 90-99% implementation OR 90-94% tests OR standards gaps OR optional review warnings | - | ❌ Failed | <90% implementation OR <90% tests OR critical failures OR deployment blockers | - - **When tests skipped** (`skip_test_suite: true`): Test pass rate is inherited from implementation phase (assumed passing since implementation completed successfully). Note this in the report. - -3. **Write verification report** to `verification/implementation-verification.md` - - **Re-verification rule**: `implementation-verification.md` and its `.html` companion are the CANONICAL verdict — they must always reflect the **latest** verification state. When this skill runs after fixes (`verification_context.fixes_applied` non-empty or `reverify_count` > 0): - - REWRITE both files with the post-fix verdict — never leave the pre-fix report standing - - Update the TL;DR block to the final verdict and remaining (not original) issue counts - - Add a **"Fix & Re-Verification History"** section: each issue → fix applied → re-check outcome (resolved / residual, with one-line evidence) - - Subagent re-check outputs may save as side files (e.g. `code-review-reverify.md`) — fine as evidence, but they never substitute for refreshing the canonical report -4. **Write HTML companion** to `verification/implementation-verification.html` — *skip this step entirely when `orchestrator.options.html_output` is false in `orchestrator-state.yml` (markdown-only mode; leave `html_path: null`)*: - - Follow the shared style guide at `../orchestrator-framework/references/html-report-style.md` (relative to this SKILL.md): self-contained single file, standard CSS block, no external resources - - Lead with the verdict banner (✅ Passed / ⚠️ Passed with Issues / ❌ Failed) and issue counts; then findings table sorted critical→info with severity badges, per-check section status, fixes-applied list. Link to the md twin in the header - - Same content as the md — restructure and visualize, never add findings - - Never block on it: if generation fails, keep the md, note the miss, continue -5. Use `TaskUpdate` to set "Compile report" task to `status: "completed"` - - Structure (md report — MUST open with the Artifact Summary Contract block): - - **TL;DR** (3-5 lines max: verdict + issue counts + headline finding) - - **Open Questions / Risks** (unresolved critical/warning items the operator should know — omit section when none) - - Executive summary (2-3 sentences) - - Implementation plan verification (from completeness checker) - - Test suite results (from test runner) - - Standards compliance (from completeness checker) - - Documentation completeness (from completeness checker) - - Optional review results (if performed) - - **Visual fidelity** (when `verification/visual-fidelity.md` exists — written by e2e-test-verifier in development workflow Phase 12): surface its summary table prominently. Include count of ✓/⚠/✗ comparisons and list every ✗ (substantive drift) with screen ID and one-line description. Cross-reference `implementation/visual-coverage.md` if present. This section is REPORT-ONLY — never gates overall verdict (per design decision: report-only, surfaced prominently). - - Overall assessment with breakdown table - - Issues requiring attention - - Recommendations - - Verification checklist - ---- - -## Phase 4: Update Roadmap (Optional) - -1. **Check for roadmap** at `.maister/docs/project/roadmap.md` -2. **If exists**, find matching items and mark complete -3. **Document** what was updated or why no matches found - ---- - -## Phase 5: Finalize & Output - -Output summary to user: - -``` -Verification Complete! - -Task: [name] -Location: [path] - -Overall Status: Passed | Passed with Issues | Failed - -Implementation Plan: [M]/[N] steps ([%]) -Test Suite: [P]/[N] tests ([%]) -Standards Compliance: [status] -Documentation: [status] - -[If optional reviews performed] -Code Review: [status] -Pragmatic Review: [status] -Production Readiness: [status] -Reality Check: [status] - -[If verification/visual-fidelity.md exists] -Visual Fidelity: [N] match / [M] minor / [K] drift — see verification/visual-fidelity.md (report-only) - -Verification Report: verification/implementation-verification.md - -[Status-specific guidance on next steps] -``` - ---- - -## Structured Output for Orchestrator - -When invoked by an orchestrator, return structured result alongside the report: - -```yaml -status: "passed" | "passed_with_issues" | "failed" -report_path: "verification/implementation-verification.md" -html_path: "verification/implementation-verification.html" # null if companion generation failed - -issues: - - source: "completeness" | "test_suite" | "code_review" | "pragmatic" | "production" | "reality" - severity: "critical" | "warning" | "info" - description: "[Brief description of the issue]" - location: "[File path or area affected]" - fixable: true | false - suggestion: "[How to fix, if obvious]" - -issue_counts: - critical: 0 - warning: 0 - info: 0 -``` - -**Guidelines for `fixable` assessment**: -- `true`: Lint errors, formatting issues, missing imports, obvious typos, simple config fixes -- `false`: Architecture decisions, design trade-offs, test logic errors, unclear requirements - -**The orchestrator decides** what to actually fix based on this data. Your job is to aggregate subagent results accurately. - ---- - -## Guidelines - -### Delegation-First Verification - -✅ Delegate to subagents, compile results, write report, output summary -❌ Run tests directly, review code directly, check standards directly, fix anything - -### Anti-Patterns to AVOID - -- ❌ Running Bash commands to execute tests → Use Task tool with `maister-test-suite-runner` -- ❌ Reading implementation-plan.md to check completion → Use Task tool with `maister-implementation-completeness-checker` -- ❌ Reading INDEX.md to check standards compliance → Use Task tool with `maister-implementation-completeness-checker` -- ❌ Reading source code for quality/security analysis → Use Task tool with `maister-code-reviewer` -- ❌ Checking config/monitoring/resilience directly → Use Task tool with `maister-production-readiness-checker` -- ❌ Performing ANY verification work inline → ALL verification is delegated to subagents - -### Clear Communication - -- Use consistent status icons in reports -- Provide specific evidence from subagent results -- List specific issues, not vague concerns -- Make actionable recommendations - ---- - -## Validation Checklist - -Before finalizing verification: - -- All required subagents invoked (completeness checker + test runner unless skip_test_suite) -- Optional reviews invoked per context settings -- All subagent results processed -- Verification report created -- Overall status determined from aggregated results -- No direct analysis performed (all delegated) diff --git a/plugins/maister-copilot/skills/orchestrator-framework/SKILL.md b/plugins/maister-copilot/skills/orchestrator-framework/SKILL.md deleted file mode 100644 index 3d4891f0..00000000 --- a/plugins/maister-copilot/skills/orchestrator-framework/SKILL.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -name: orchestrator-framework -description: Shared orchestration patterns for all workflow orchestrators. NOT an executable skill - provides reference documentation for phase execution, state management, interactive mode, and initialization. All orchestrators reference these patterns. -user-invocable: false ---- - -# Orchestrator Framework - -This skill provides **shared reference documentation** for all orchestrator skills in the maister plugin. It is NOT an executable skill - orchestrators reference these patterns and implement them for their specific domain. - -## Purpose - -Reduce duplication across orchestrators by documenting common patterns once: - -- **Phase Blocks**: Simple phase structure with inline transitions (`→ Pause`, `→ AUTO-CONTINUE`) — these are the only two transition types; see `orchestrator-patterns.md` § 2 for semantics -- **State Management**: `orchestrator-state.yml` schema and operations -- **Phase Gates**: Pause behavior and user prompts -- **Initialization**: Task directory setup, metadata, task creation patterns - -## How Orchestrators Use This - -Each orchestrator reads the framework reference file at initialization (Step 1): - -```markdown -### Step 1: Load Framework Patterns - -**Read the framework reference file NOW using the Read tool:** - -1. `../orchestrator-framework/references/orchestrator-patterns.md` -``` - -## Reference Files - -| File | Purpose | -|------|---------| -| `references/orchestrator-patterns.md` | Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution | -| `references/orchestrator-creation-checklist.md` | Authoring checklist for creating new orchestrators (not loaded at runtime) | - -## Key Principles - -All orchestrators follow these principles: - -1. **State-Driven Execution**: `orchestrator-state.yml` is source of truth -2. **Resume Capability**: Any orchestrator can be paused and resumed -3. **Interactive**: Pause after each phase for user review -4. **User-Confirmed Rollback**: Never auto-rollback without user approval -5. **Task Progress**: Always track progress with TaskCreate/TaskUpdate tools -6. **Standards Discovery**: Reference `.maister/docs/INDEX.md` throughout - -## Orchestrators Using This Framework - -- `development` (bug fixes, enhancements, features) -- `performance` -- `migration` -- `research` - -## NOT an Executable Skill - -This skill does NOT get invoked directly. It exists to: -1. Provide discoverable documentation for orchestrator patterns -2. Serve as single source of truth for common logic -3. Enable consistent behavior across all orchestrators - -When building new orchestrators, reference these patterns rather than duplicating them. diff --git a/plugins/maister-copilot/skills/orchestrator-framework/references/html-report-style.md b/plugins/maister-copilot/skills/orchestrator-framework/references/html-report-style.md deleted file mode 100644 index 9d08f5ec..00000000 --- a/plugins/maister-copilot/skills/orchestrator-framework/references/html-report-style.md +++ /dev/null @@ -1,168 +0,0 @@ -# HTML Companion Report Style Guide - -Shared conventions for agents that emit an HTML companion next to a markdown artifact (orchestrator-patterns.md § 9). Goal: every companion looks like part of one family, regardless of which agent or session produced it. - -## Hard Rules - -1. **Self-contained single file** — inline ` - - -