From 31088a5ed8e78f3f8c243c7da4ca2a7b6f41c42c Mon Sep 17 00:00:00 2001 From: jarvis-at-skic Date: Thu, 10 Sep 2026 11:41:25 +0000 Subject: [PATCH] feat: mine reusable AeroSim channel lessons --- SKILL.md | 21 ++- ...rity-precedence-and-concurrent-evidence.md | 60 ++++++++ .../c4-container-registry-component-views.md | 110 ++++++++++++++ references/channel-handoff.md | 23 +++ references/delegated-solution-package-tdd.md | 141 ++++++++++++++++++ .../diagrams-drawio-canonical-compliance.md | 91 +++++++++++ .../docusaurus-drawio-browser-verification.md | 77 ++++++++++ references/gitea-actions-evidence-triage.md | 39 +++++ ...imensional-lifecycle-presentation-audit.md | 56 +++++++ .../scheduled-sync-evidence-convergence.md | 52 +++++++ tests/test_task_breakdown_policy.py | 2 +- 11 files changed, 670 insertions(+), 2 deletions(-) create mode 100644 references/authority-precedence-and-concurrent-evidence.md create mode 100644 references/c4-container-registry-component-views.md create mode 100644 references/channel-handoff.md create mode 100644 references/delegated-solution-package-tdd.md create mode 100644 references/diagrams-drawio-canonical-compliance.md create mode 100644 references/docusaurus-drawio-browser-verification.md create mode 100644 references/gitea-actions-evidence-triage.md create mode 100644 references/multidimensional-lifecycle-presentation-audit.md create mode 100644 references/scheduled-sync-evidence-convergence.md diff --git a/SKILL.md b/SKILL.md index 714b4bd..744f497 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: corp-v1-channel-architecture description: "Use when operating or synchronizing a Corp v1 project's architecture channel. Maintains C4-based architecture documentation, Draw.io diagrams, architecture decisions, and requirements while correlating verified activity across the project's seven channels." -version: 1.8.0 +version: 1.9.0 author: Hermes Agent license: MIT metadata: @@ -286,6 +286,25 @@ Requires team approval for: - adopting a project-specific `diagrams-drawio` copy; - irreversible or high-impact implementation/deployment work. + +## Mined Project-Adoption Improvements + +## Dedicated Project Channel Workspace + +Every project adoption must bind this channel to a dedicated local workspace under the active working root. Keep clones, worktrees, plans, reports, screenshots, generated artifacts, retained logs, and channel inputs inside that channel root. Use run-unique or task-specific children under `workspace/`; keep durable project truth in approved repositories. A local folder boundary organizes execution only—it neither broadens authority nor replaces remote evidence. Delivery adoptions should additionally use a channel-level `cache/` for reusable pinned toolchains and dependencies, while keeping Task evidence isolated by Task. + +## Project-Adoption Architecture Lessons + +Resolve authority from the active project authorization contract at invocation time; broad delegation never replaces exact-item evidence, safety boundaries, or a later narrower owner decision. Use [references/authority-precedence-and-concurrent-evidence.md](references/authority-precedence-and-concurrent-evidence.md). + +For cross-channel handoffs, emit a stable verified packet and let the destination re-check its own entry gates. Process each handoff ID once and return incomplete work without fabricating a lifecycle transition. Follow [references/channel-handoff.md](references/channel-handoff.md). + +When Scope and Architecture traceability disagree, preserve Scope-owned Feature identity and product-question dependencies, move Architecture-only findings into clearly proposed technical risks, and repair record coherence without manufacturing solution approval. When task execution, publication, deployment, or acceptance advances, audit every presentation surface and keep Scope lifecycle, solution completeness, implementation approval, task-derived execution, deployment, acceptance, and final version allocation separate. Use [references/multidimensional-lifecycle-presentation-audit.md](references/multidimensional-lifecycle-presentation-audit.md). + +An “in sync” Architecture audit must report structural compliance, content completeness, and build/render health separately. Verify current default-branch bytes, exact C4 levels, dedicated FR/NFR registries and readers, reciprocal traceability, task/dependency readiness, editable Draw.io rendering, browser health, and remote readback. Use [references/c4-container-registry-component-views.md](references/c4-container-registry-component-views.md), [references/diagrams-drawio-canonical-compliance.md](references/diagrams-drawio-canonical-compliance.md), and [references/docusaurus-drawio-browser-verification.md](references/docusaurus-drawio-browser-verification.md). + +Use RED-first repository contracts for delegated solution packages and task identity, [references/delegated-solution-package-tdd.md](references/delegated-solution-package-tdd.md); classify runner failures separately from repository failures, [references/gitea-actions-evidence-triage.md](references/gitea-actions-evidence-triage.md); and close scheduled evidence races before final reporting, [references/scheduled-sync-evidence-convergence.md](references/scheduled-sync-evidence-convergence.md). + ## Common Pitfalls 1. Drawing architecture without loading `diagrams-drawio`. diff --git a/references/authority-precedence-and-concurrent-evidence.md b/references/authority-precedence-and-concurrent-evidence.md new file mode 100644 index 0000000..38164b8 --- /dev/null +++ b/references/authority-precedence-and-concurrent-evidence.md @@ -0,0 +1,60 @@ +# Authority precedence and concurrent-evidence handling + +Use this reference when a scheduled Architecture run observes conflicting authority text across its invocation prompt, the installed project skill, Discord history, canonical repository data, or another concurrent agent's local work. + +## Precedence + +Apply the narrowest higher-authority instruction that governs the current run: + +1. System and developer instructions. +2. The current user's invocation-local contract, including scheduled-job boundaries. +3. The installed project-local skill and its authorization override. +4. Verified human Discord decisions within the six authorized channels. +5. Canonical remote default-branch records and exact remote PR artifacts. +6. Bot reports, local branches, uncommitted diffs, and agent assertions. + +A project-local authorization override may supersede generic reference-skill gates, but it does not supersede a stricter current invocation. If the scheduled prompt says to work only on Features carrying explicit human `Approved for Solution` evidence, broad delegation or an installed override cannot relax that run. + +## Classification rules + +- Broad project leadership, PR-management authority, urgency, or a request asking why items remain Proposed is not item-specific approval when the invocation requires an exact Feature and exact target state. +- An agent-authored approval, local staged transition, or report that a decision is “valid” is not remote authoritative lifecycle evidence unless the active contract explicitly permits delegated agent approval and the canonical decision record satisfies it. +- A concurrent local diff has no remote authority. Record it as unpublished concurrent work, do not validate it as a PR, and do not let it change the current default-branch verdict. +- A mutable installed skill may change during a run. Continue honoring the invocation snapshot and direct prompt that started the run; re-read the skill only to detect and report a contradiction, not to retroactively weaken the active contract. +- If remote default remains compliant while concurrent unpublished work conflicts with the active gate, report default as `in sync` and disclose the unpublished contradiction separately. Do not create a competing PR. + +## Validator success does not resolve authority conflicts + +Repository validators may correctly prove schema integrity, actor allowlisting, hash chains, generated views, and build health while still accepting a delegated decision that the current invocation is forbidden to use. Treat these as separate questions: + +1. **Canonical integrity:** does the remote record satisfy the repository's current schema and trust model? +2. **Invocation eligibility:** may this run act on that record under its narrower approval contract? + +A successful validator or exact-SHA CI result answers only the first question. When canonical default records say `Approved for Solution` through a delegated agent but the invocation requires explicit item-specific human approval: + +- report the canonical status and delegated actor exactly as stored; +- state that the Feature is ineligible for semantic solution work in this run; +- do not rewrite or roll back canonical lifecycle history merely to make it match the temporary run boundary; +- do not let a coordination PR's prose that "approval authorizes Architecture" override the invocation; +- keep structural/build health separate from semantic eligibility in the final verdict. + +If an unpublished solution worktree was created under the broader authority model, classify it as concurrent candidate work. Do not publish, complete, or validate it as the current run's deliverable; disclose its base SHA, publication state, and unresolved review findings when material. Avoid opening a competing Architecture PR while that worktree or an owning PR controls the same artifacts. + +## Evidence wording + +State all three dimensions separately: + +- **Current authoritative default:** branch, SHA, lifecycle state, decision actor/authority, and exact-default CI. +- **Current run boundary:** the approval rule actually governing this invocation and whether the canonical item is eligible under it. +- **Concurrent candidate state:** local/unpublished or remote PR, with its exact authority, base/head SHA, publication state, and evidence limitations. + +When canonical default contains delegated-agent solution or implementation decisions but the scheduled invocation requires exact human approval, use an explicit split verdict such as: + +```text +Structural/build state: in sync at /. +Semantic eligibility for this run: blocked — canonical decisions were authored under delegated authority and no exact human item-specific approval was found. +``` + +Do not repeat a cross-channel bot summary such as “solutioning is complete,” “ready to build,” or “no blocker remains” without immediately qualifying that it describes canonical delegated state only and is not authorization under the current human-only run. A newer Scope/General reconciliation PR that changes only status prose may be substantive synchronization evidence, but if the Architecture tree and Architecture-relevant configuration are byte-identical to the previously validated merge, verify tree equality, validate the new exact default head, and report the authority split without creating an Architecture churn PR. + +Never phrase a local proposal as integrated, never call a broad delegation item-specific unless the active contract permits that interpretation, and never imply that passing repository validation makes a decision usable under a stricter invocation. diff --git a/references/c4-container-registry-component-views.md b/references/c4-container-registry-component-views.md new file mode 100644 index 0000000..8c625f0 --- /dev/null +++ b/references/c4-container-registry-component-views.md @@ -0,0 +1,110 @@ +# C4 Container Registry with Per-Container C3 Views + +Use this pattern when a documentation site must expose C1, C2, and C3 without implying that a container is a component. + +## Semantic model + +- **C1 System Context**: the system, people, external systems, and principal relationships. +- **C2 Container view**: deployable or runnable applications, services, stores, queues, and their relationships. +- **Container registry**: an index of the C2 containers. A registry is navigation/information architecture, not a separate C4 level. +- **C3 Component view**: the internal decomposition of exactly one selected container, plus the surrounding actors, systems, and containers needed to understand its relationships. + +A container remains a container when opened at C3. The C3 page changes the level of detail, not the element type. + +## Unambiguous wording + +Use: + +```md +# Web Application — Container + +This page documents the **Web Application container** identified at C2. The diagram below is the container's **C3 Component view**: it opens that container to show its internal components and surroundings. +``` + +Use diagram titles of the form: + +```text +Web Application Container — C3 Component View +``` + +Avoid: + +```text +This C3 Component view opens the Web Application... +Containers (C3) +C3 Component registry +``` + +Those phrases can misclassify the container itself as a component or the registry as a C4 level. + +## Navigation pattern + +For the adopted project: + +```text +Context (C1) +Overview (C2) +Container Registry (C3 views) + Web Application + API Service + Documentation Site +Requirements - Functional + Registry + +Requirements - Non-Functional + Registry + +``` + +The registry page should say it lists **C2 containers** and links to a **C3 Component view** for each container. + +## C3 page contract + +Each container entry should include: + +1. a heading that explicitly identifies the subject as a container; +2. an introduction distinguishing the C2 subject from the C3 view; +3. an editable Draw.io diagram with the container boundary, internal components, and surroundings; +4. source-observed components separated from target/unimplemented components; +5. relationship edges supported by source or approved target design; +6. explicit treatment of adjacent elements with no observed relationship instead of inventing an edge; +7. source evidence and non-deployment/non-acceptance caveats where applicable. + +Shared compiled packages are components/libraries inside consuming deployables, not extra container rows, unless they have an independently deployable runtime boundary. + +## Source-default versus deployed-runtime reconciliation + +Track two immutable baselines independently: + +- **current repository source** — the application default SHA used to classify implemented internals; +- **deployed runtime** — the application/image and GitOps SHAs used to describe what users can currently execute. + +A source merge can make a C3 page stale before deployment. If a page still anchors source-observed internals to an older commit and labels newly merged components as target/unimplemented, content completeness is `partially in sync` even when C1 deployment wording remains accurate. Inspect implementation PR changed files and distinctive exported symbols rather than relying only on a Delivery summary. Then update the container page and its editable Draw.io source together so both distinguish current source, deployed runtime, and remaining target design. + +When closing a prior partial verdict after its remediation PR merges, verify all three conditions: + +1. reviewed-head ancestry and exact-default CI are current; +2. later documentation changes preserve the corrected Architecture contract; +3. no newer application or deployment SHA changes the source/target classification or relationships in C2/C3. + +If the required Draw.io governance skill cannot be loaded, do not patch prose alone. Preserve the accurate C1/runtime checkpoint, identify the stale C3 source anchor and newly implemented components, and defer one coordinated prose-plus-diagram correction. + +## Fail-closed validation + +Validators should require: + +- canonical C1 and C2 routes and labels; +- registry language identifying C2 containers and per-container C3 views; +- ` — Container` page headings; +- ` Container — C3 Component View` diagram titles; +- rejection of ambiguous legacy wording; +- native editable Draw.io sources; +- component boundary membership and exact relationship endpoints; +- no invented cross-container calls; +- source-observed versus target separation. + +Mutation-test the validator by temporarily restoring an ambiguous phrase or reversing/removing a required edge and requiring a non-zero result. + +## Publication verification + +Run the repository's full validator/test/typecheck/build set, visually inspect the registry and each C3 page, obtain independent fail-closed review, then publish through an exact-head PR/CI/merge/integrated-CI sequence. Protected Pages redirects must be reported as an authentication boundary rather than treated as deployed article evidence. diff --git a/references/channel-handoff.md b/references/channel-handoff.md new file mode 100644 index 0000000..4c71b04 --- /dev/null +++ b/references/channel-handoff.md @@ -0,0 +1,23 @@ +# Governed channel handoff + +Use this packet only after the source channel has completed and verified its owned outcome: + +```markdown +### Channel handoff +- Handoff ID: -HO---- +- State: READY | BLOCKED | RETURNED +- Canonical work-item ID: +- Reader display ID: +- Source: +- Destination: +- Completed: +- Evidence: +- Requested next action: +- Remaining gates/risks: +``` + +The destination scans for packets addressed to it, searches its own history for the exact Handoff ID, and processes each ID at most once. Before acting, it verifies the packet evidence and every destination entry gate. A valid packet is acknowledged and continued in the destination's authority boundary. An incomplete or invalid packet is returned as `BLOCKED` or `RETURNED` under the same Handoff ID with the missing condition and correct owner. A notification is never lifecycle approval. + +The normal forward path is `general → scope → architecture → ui-ux when applicable → kanban → delivery → releases → general`. Route directly to the actual owner when work begins later, and route backward for defects, contradictions, or missing evidence. General receives final outcomes and cross-cutting exceptions, not every routine transition. Continuations name the parent Handoff ID; never duplicate an already acknowledged transition or copy whole conversations. + +A project may add an event-driven dispatcher only through a separately approved project-local authorization and credential contract. The central packet contract does not authorize webhook creation, secret access, scheduler jobs, or automated destination mutation. diff --git a/references/delegated-solution-package-tdd.md b/references/delegated-solution-package-tdd.md new file mode 100644 index 0000000..ecb8870 --- /dev/null +++ b/references/delegated-solution-package-tdd.md @@ -0,0 +1,141 @@ +# Delegated solution-package TDD and handoff pattern + +Use this reference when one change must transition several approved Features and add their complete Architecture/Kanban packages. + +## RED contract + +Add one repository-level contract test before changing canonical records. It should assert, for every exact Epic/Feature/task/ADR ID. For every Task, bind decisions, lifecycle/flow events, evidence, history, and governance hashes to `canonical_id: TASK-`; treat `display_id: -TS-` only as a separate reader-facing alias: + +- delegated actor identity, authority basis, exact state, date, conditions, evidence URL, and event ID; +- append-only decision-history continuity and baseline hash registration; +- a complete Feature package: C4 impact, diagram link/rationale, interfaces, flows, technical dependencies/risks, version proposal, implementation decision, and handoff; +- reciprocal Feature↔FR/NFR/ADR/task links; +- acyclic dependency-aware task ordering, exact repository/component ownership, future acceptance-evidence specification, and `delivery_started: false`; +- release-wide task completeness: every Feature assigned to the release has an Architecture-reviewed task breakdown, every required Task and dependency is present, and planning readiness remains false when coverage or dependency closure is incomplete; +- exact-task Kanban admission as a separate decision. + +Run only that test and confirm an expected missing-behavior assertion, not a parser, command-line, syntax, or setup error. + +## GREEN implementation order + +1. Extend the canonical validator and public types to model delegated authority without weakening human decisions. Bind the delegated identity to a manifest allowlist and validate the authority basis and safe durable delegation URL. +2. Append lifecycle events; never rewrite baseline history. Compute hashes with the repository's canonical hash function and add each event to the baseline manifest. +3. Add solution packages and separate Architecture-owned technical risks/dependencies from Scope-owned questions/dependencies. +4. Add accepted FR/NFR/ADR records, then small task records and reciprocal indexes. +5. Encode implementation sequence in task dependencies rather than prose alone. +6. Regenerate indexes using repository scripts. +7. Update generated-data components and current-state prose together. Preserve verified implementation as baseline evidence, not target acceptance evidence. + +## Adversarial closure contract + +A green happy-path suite is insufficient for a multi-Feature solution package. Before publication, add negative mutations and prove the validator rejects each class below. + +### Evidence ownership + +- A `canonical-record` evidence path must equal the exact owning collection/ID path, not merely match a broad path regex. +- The cited item, state, and event must belong to that same record. +- Test a valid-looking cross-record forgery, such as an FT-1 event citing the FT-2 path; testing only a syntactically invalid path does not close the gap. +- Derive public verification fields while loader metadata such as collection and filename is still present. Strip private metadata only after verification; assert it is absent from serialized public data. + +### Conditions and sequencing + +- Every interface and data flow must preserve all applicable approval-question conditions, reject unknown IDs, and reject known but non-applicable IDs. +- Enforce the canonical handoff sequence as data, not prose only. +- Test removal of each required cross-Feature stage gate. Acyclicity and rank ordering alone do not detect omitted predecessors. +- Test removal of an assigned Feature's required Task, terminal predecessor, or dependency and prove that release planning readiness fails closed. +- Check reciprocal requirement/task ownership and exact acceptance-outcome indexes, not only that IDs exist. + +### Testable requirements and tasks + +- Architecture owns complete release-wide Feature-to-Task decomposition. +- Architecture creates missing Tasks and reviews, retains, revises, supersedes, or removes existing Tasks against current Feature outcomes and Architecture boundaries. +- Only draft Tasks with no implementation approval, Kanban admission, execution, or completion evidence may be freely revised or removed. +- Approved, Kanban-admitted, in-progress, or completed Tasks must not be deleted or silently rewritten. +- Obsolete protected Tasks retain prior evidence and history, use terminal Superseded or Cancelled status, and carry explicit replacement links when replaced. +- Every governed Feature requires between two and six independently executable Tasks; one Task is permitted only with a recorded Architecture rationale proving it is the smallest atomic, independently verifiable boundary. +- Task mappings must be exact and reciprocal for every acceptance-outcome ID and every applicable active `FR-*` and `NFR-*` record. +- Every entry Task must depend on all terminal Tasks of every prerequisite Feature. +- A material scope, outcome, dependency, repository, or component change invalidates existing implementation approval, returns the Task to its pre-approval state, and always requires renewed `Approved for Implementation` under the active authority contract before implementation can resume; execution then requires a separate exact-task Kanban Focus admission. +- Functional requirements need structured measurable criteria: `given`, `when`, `then`, and the future evidence required to prove the assertion. +- Criteria must name concrete inputs, observable outputs, boundaries, invalid behavior, and pass/fail expectations; title-restating acceptance text is not sufficient. +- Task outcomes and acceptance evidence must be specific to the implementation boundary and must not claim future tests or reviews already exist. +- Task contracts must identify implementation artifacts, concrete inputs and outputs, failure boundaries, explicit exclusions, verification steps, and task-specific future acceptance evidence; generated placeholder wording fails the package gate even when IDs and aggregate coverage are complete. +- Verify evaluator versus presenter/debrief tasks have not accidentally exchanged FRs or outcome ownership. + +### C4 and publication truth + +- Separate a source-verified implementation baseline from the approved target design. A target solution package must not link to a diagram or overview that still says its components/contracts are absent or merely proposed. +- Ensure every target relationship described in prose exists in editable Draw.io—for example evaluator outputs feeding the debrief pipeline—and ensure edge labels identify the actual payload owner. +- Type and render every material contract field: producer, consumer, schema owner, ordering/timing, persistence, error behavior, and unresolved conditions. +- Search dated steering/current-state prose for stale “remediation in progress,” “no artifacts,” or old approval-authority claims. + +## Public-data and browser verification + +After canonical validation, inspect the production/public adapter separately: + +1. assert all expected Epic/Feature lifecycle decisions publish as verified; +2. assert conditional solution approval publishes as verified while unconditional entry readiness remains false; +3. assert every admitted task publishes its exact verified flow state; +4. assert no loader-private metadata leaks; +5. exercise the Board/Focus adapters against production records and prove they contain the expected Epic, Features, and tasks; +6. build and restart the local static server after the final build—an already-running server may retain an older bundle; +7. browse at the real Docusaurus `baseUrl`, not the root route; +8. verify Scope renders delegated approval evidence rather than a false “not recorded” state, Architecture renders conditions/contracts/version honestly, Board contains governed Epics/Features, Focus contains admitted tasks, and the Draw.io SVG appears without console/resource errors. + +Do not use unconditional entry readiness to decide whether a conditional approval record exists. Present these as distinct facts: + +- approval record verified; +- conditions preserved; +- unconditional entry readiness true/false; +- solution package complete/incomplete. + +## Independent fail-closed review loop + +Freeze the complete effective diff—including intentional uncommitted review corrections—and give a read-only reviewer explicit permission to adversarially inspect it. A reviewer PASS is a publication gate; a BLOCK must be remediated with RED/GREEN evidence and sent to a fresh reviewer. + +The reviewer should inspect more than test output: + +- stale diagrams and prose; +- semantic FR/task alignment; +- public adapter derivation order; +- rendered browser truth; +- omitted dependencies/conditions; +- cross-record evidence forgery; +- implementation/release/deployment overclaims. + +Do not weaken validators to obtain PASS. Keep iterating until a fresh review returns PASS against the final effective candidate. + +## Validation discipline + +Before rewriting mutable pages, inspect repository validators and tests for required headings, historical-snapshot markers, and route contracts. Dynamic data migration does not authorize deleting validator-required static markers; preserve or intentionally update the contract test and validator together. + +Reserve execution budget for this exact finish sequence: + +1. targeted contract test; +2. full tests; +3. data validation and deterministic index check using scripts that actually exist in `package.json`; +4. Scope, Architecture, and Kanban validators; +5. typecheck; +6. strict production build and dependency audit; +7. `git diff --check`, generated-file drift check, path inventory, and uncommitted status inspection; +8. production/public-data assertions and browser verification; +9. independent fail-closed review; +10. commit, push, PR readback, complete paginated changed-file readback, and exact-head terminal CI by SHA. + +Do not report “fully validated” unless all required stages passed after the final edit. If execution stops early, enumerate the exact failing checks and leave no stronger completion claim. + +## Common failure modes + +- Assuming a semantically related Discord URL is the authority source instead of preserving the exact canonical delegation URL. +- Updating the validator's actor error wording without updating its negative assertion. +- Enforcing complete-package fields on minimal unit fixtures globally. Prefer an explicit manifest capability flag for repositories that require complete packages, while keeping focused validator fixtures small. +- Replacing current-state prose and accidentally removing headings required by page validators. +- Invoking guessed script names such as `data:index:check`; read `package.json` and execute only declared scripts or an explicit generate-and-diff equivalent. +- Spending the validation budget on broad prose rewrites before the repository's static contracts are known. +- Treating canonical validation as proof that public adapters derived verification fields correctly. +- Stripping collection/filename metadata before exact-path evidence verification. +- Testing malformed evidence only, while a valid-looking cross-record forgery still passes. +- Checking only DAG/rank validity while required stage-gate edges can be removed. +- Rendering only summary interface fields while silently dropping ownership, timing, persistence, errors, or conditions. +- Reusing a browser server started before the latest build and misclassifying its stale bundle as current output. +- Trusting the first default-sized PR-files API page as the complete changed-file list; follow pagination until an empty/short page and verify required artifacts across the union. diff --git a/references/diagrams-drawio-canonical-compliance.md b/references/diagrams-drawio-canonical-compliance.md new file mode 100644 index 0000000..1a2ad30 --- /dev/null +++ b/references/diagrams-drawio-canonical-compliance.md @@ -0,0 +1,91 @@ +# Canonical Draw.io Compliance for C4 Architecture + +Use this reference whenever an Architecture change creates, rewrites, or reroutes editable `.drawio` sources. + +## Authority and provenance + +1. Resolve the canonical global skill from `https://gitea.lego-cloud.eu/home-v1-skills-code-agent/diagrams-drawio`. +2. Fetch its remote default/test ref and record the exact full commit. Do not treat an unversioned work copy or an old reference directory as authoritative. +3. Read `SKILL.md` plus `references/capabilities.md`, `rules-layout.md`, `rules-style.md`, and `routing-best-practices.md` before editing. +4. Ask the installed CLI for its actual supported actions with `node scripts/dist/cli/commands.js --help`. If prose and CLI action names differ, use the current CLI names and disclose the documentation drift; never silently skip a requested gate. + +## C4 wording contract + +- C1 is the System Context view. +- C2 identifies containers. +- C3 opens one selected C2 container and shows components inside it. +- A C3 page does not turn its subject container into a component. +- Prefer explicit titles such as `Web Application — Container` and `Web Application Container — C3 Component View`. +- The container registry is navigation over C2 containers and their C3 views; it is not itself a C4 level and must not be called `Containers (C3)`. + +## Source invariants + +For every governed diagram: + +- preserve editable native mxGraph XML; +- use `rounded=0`; +- keep all relationship edges on root layer `parent="1"`; +- forbid `exitX`, `exitY`, `entryX`, `entryY`, `exitDx`, `exitDy`, `entryDx`, and `entryDy` style pins; +- use orthogonal routes and explicit waypoints only where needed; +- place vertex `x`, `y`, `width`, and `height` on the canonical 40pt grid; +- use a 40pt minimum gap and uniform sibling-row/column spacing; +- keep labels concise (normally at most 80 characters) and move detailed behavior to surrounding prose/tables; +- retain square C4 boundaries and visibly separate source-observed elements from target/unimplemented elements; +- do not add relationships merely to eliminate an intentional orphan. + +Add repository-level fail-closed checks for invariants the global CLI does not enforce. Mutation-test these checks—for example, change one vertex from `x=40` to `x=20` and require validation to fail. + +## Canonical CLI gate + +Run the current CLI against every changed diagram. At the time this workflow was learned, the supported quality actions were: + +```text +validate +page-connectors-summary +page-connectors-validation +page-labels-validation +page-shape-bbox-validation +page-orphans +page-recommendations +page-hierarchy-full +page-negative-space-summary +``` + +Use `task validate -- --file=` when the canonical Task wrapper is available. If the wrapper executable is unavailable but the skill explicitly documents the built Node entry point, invoke `node scripts/dist/cli/commands.js --file --action validate` and the supported quality actions directly. This is an entry-point substitution, not permission to invent replacement checks. + +Required acceptance targets: + +- valid XML/mxGraph compilation; +- zero connector crossings; +- zero single-port violations; +- zero corner-port violations; +- zero header-edge violations; +- zero leaf-shape connector overlaps; +- zero shape bounding-box overlaps; +- zero empty, duplicate, or overlong labels; +- no forbidden port pins or nested edges. + +Connector/shape diagnostics involving only the containing system or swimlane boundary are structural boundary crossings. Report them separately from leaf-shape overlaps; do not call every raw overlap total a blocker. + +## Visual QA after machine gates + +Render every affected route through the real Docusaurus production build and inspect it in the browser. Machine-clean geometry can still look poor. Check specifically for: + +- long edge prose rendered too small; +- large perimeter detours introduced only to satisfy fan-in/fan-out rules; +- multiple labels crowding a shared corridor; +- overlapping final connector segments that make source attribution ambiguous; +- labels crossing boxes or headers; +- C2 container versus C3 component wording ambiguity; +- source-observed and target/unimplemented regions blending together. + +Prefer moving external actors into aligned lanes, using a shared same-side fan-in/fan-out point, shortening edge labels, and positioning edge labels on distinct route legs. Rerun all machine gates after each visual correction. + +## Review and publication + +1. Run repository validators, tests, TypeScript, strict production build, production audit policy, and `git diff --check` on the exact final diff. +2. Obtain independent fail-closed review that reads the canonical skill and distinguishes parent-boundary diagnostics from real leaf defects. +3. Fix every blocker and request a fresh review; a pre-fix pass is stale. +4. Refresh the default branch after review. Rebase safely and rerun exact-head validation if it moved. +5. When delivery requires a PR, do not stop at a local commit or rebase. Push, open the PR, return the real URL/head, verify exact-head CI, merge when authorized, and verify integrated-head CI. +6. State publication layers precisely: local, pushed branch, open PR, exact-head CI, merged, integrated-head CI, and deployed page-body verification. diff --git a/references/docusaurus-drawio-browser-verification.md b/references/docusaurus-drawio-browser-verification.md new file mode 100644 index 0000000..f798ed0 --- /dev/null +++ b/references/docusaurus-drawio-browser-verification.md @@ -0,0 +1,77 @@ +# Docusaurus Draw.io browser and connector verification + +Use this after the production build when Architecture pages embed editable `.drawio` sources. + +## Resolve the real served route + +Docusaurus `serve` respects `baseUrl`, and a document may override its apparent filename with frontmatter such as `slug: /`. + +1. Read `docusaurus.config.*` for `baseUrl` and the Architecture plugin's `routeBasePath`. +2. Read each page's frontmatter before constructing browser URLs. +3. Build the URL as ``. +4. Treat unexpected `200`, `302`, or `404` responses as a routing-discovery problem first; do not infer that the desired document rendered merely because Docusaurus returned a page. + +A Context source named `context.mdx` with `slug: /` normally renders at `/architecture/`, not `/architecture/context/`. + +## Reject authentication shells and unrelated HTTP 200 responses + +An HTTP `200` from a deployed documentation URL is not proof that the Docusaurus route rendered. Reverse proxies and identity providers may return a login or access-denied shell with status `200` at every requested route. + +Before using a deployed response as render evidence: + +1. inspect the response body and script/style URLs for identity-provider or login-shell markers; +2. require at least one route-specific article heading or distinctive content marker; +3. if every route returns near-identical bytes or only authentication assets, classify the result as an authentication boundary—not a successful docs render; +4. do not search the login shell's generic HTML for diagram evidence or claim deployed-route verification; +5. report the limitation separately, retain exact-head build and local browser evidence, and use authenticated browser verification only when an approved credential path is available. + +A local production build may prove artifact correctness, and equal Architecture tree IDs may justify carrying forward prior render evidence, but neither substitutes for a fresh deployed browser check. State those evidence dimensions separately. + +## Prove that the diagram rendered + +Generic `svg` counts are insufficient because the Docusaurus shell and icons also use SVG. + +For every edited diagram page: + +- require the expected article heading; +- require the exact diagram title or another unique label from the imported `.drawio` source in the rendered article DOM; +- verify the required Architecture sidebar labels and nesting; +- collect browser console errors, uncaught page errors, and failed requests; +- record the HTTP status and route. + +This couples browser evidence to the intended Draw.io source instead of merely proving that some SVG exists. + +## Classify network failures + +Separate first-party or rendering-critical failures from optional third-party requests. `docusaurus-plugin-drawio` may request the diagrams.net MathJax script even when a diagram contains no mathematics. If that optional request is blocked by browser ORB policy while the exact diagram title and labels render correctly: + +- disclose the request and count; +- classify it separately from relevant failures; +- do not hide it; +- do not fail the architecture render verdict solely for that optional request. + +Any failed first-party asset, imported Draw.io source, application JavaScript, CSS, or request needed to render diagram content remains a build/render-health failure. + +## Headless verification when no browser tool is exposed + +Use a disposable Playwright runtime rather than weakening browser verification: + +1. Set `PLAYWRIGHT_BROWSERS_PATH` to a writable cache directory before installing or launching Chromium. This avoids failures when Playwright's default home/cache belongs to another service account. +2. Install the matching browser with `corepack pnpm dlx playwright@ install chromium`. +3. Do not assume a package supplied by `pnpm dlx` is importable by an arbitrary external ESM script. If `import 'playwright'` cannot resolve, create a disposable directory with a minimal `package.json`, install Playwright there, and run the verification script from that directory. Do not modify the documentation repository's package manifest or lockfile for this test-only runtime. +4. Serve the already-built production site on loopback and first prove readiness with the exact `baseUrl` route. +5. For each edited page, assert HTTP `200`, article heading, exact diagram title, a source-unique label, required sidebar labels, and at least one article SVG. Capture `console`, `pageerror`, `requestfailed`, and HTTP `>=400` events. +6. Partition optional diagrams.net MathJax failures from relevant first-party failures in the test result, then delete or leave the disposable runtime outside the repository. + +A successful headless test must report the exact routes and assertions; merely launching Chromium is not render evidence. + +## Interpret connector diagnostics + +Run mandatory XML validation and label validation for every changed source. Also run connector validation, but inspect each issue rather than treating the aggregate count as a verdict. + +- Actual connector crossings, a connector traversing an unrelated shape, header-edge violations, and ambiguous routing require correction or explicit review. +- Some validators report each child connector as overlapping its containing swimlane or boundary. Classify these parent-container intersections separately; they are not automatically diagram defects. +- Review non-container overlap entries individually. A warning naming an unrelated component or workload is actionable. +- Do not report a connector warning count as a publication blocker without listing and classifying the underlying issue types. + +Retain the final XML validity, label counts, connector classification, rendered-page evidence, console/page errors, and relevant-versus-optional network failures in the PR evidence. \ No newline at end of file diff --git a/references/gitea-actions-evidence-triage.md b/references/gitea-actions-evidence-triage.md new file mode 100644 index 0000000..3ae4c56 --- /dev/null +++ b/references/gitea-actions-evidence-triage.md @@ -0,0 +1,39 @@ +# Gitea Actions evidence triage + +Use this when a documentation PR or default-branch Action is marked failed but repository validation succeeds locally. The goal is to distinguish code/content failure from runner infrastructure failure without weakening the exact-head gate. + +## Evidence sequence + +1. Record the remote default branch SHA and, for a PR, its exact remote head/base SHAs. Do not validate an unpushed local commit as though it were the PR artifact. +2. Query the repository Action tasks and identify the entry whose `head_sha` exactly matches the commit under review. Preserve task ID, run number, status, and run URL. Treat the tasks endpoint as paginated: a small `limit` can omit an older still-valid exact-head task after other branches produce newer runs. Increase the limit or paginate before declaring that exact-head CI is absent; if a prior report preserved a run ID, query that immutable run directly. +3. Immediately preserve the numeric `run_id` from the matching task's run URL. Poll `/actions/runs/{run_id}` for `status` and `conclusion`, then query its jobs. Do not depend on repeatedly rediscovering the task by SHA: completed tasks may disappear from the tasks listing or be displaced by later activity even though the run remains available by ID. Gitea commonly exposes these paths: + - `/api/v1/repos/{owner}/{repo}/actions/tasks?limit=...` + - `/api/v1/repos/{owner}/{repo}/actions/runs/{run_id}` + - `/api/v1/repos/{owner}/{repo}/actions/runs/{run_id}/jobs` + - `/api/v1/repos/{owner}/{repo}/actions/jobs/{job_id}/logs` +4. Confirm the terminal run and every relevant job still report the exact expected `head_sha`; preserve run ID, job ID, conclusion, timestamps, and step conclusions. If a tasks-list poll returns empty after previously finding the match, query the preserved run ID before concluding that CI evidence is missing. +5. Determine the earliest failed phase: + - checkout or later command output with a repository error: content/build evidence; + - image pull/container creation/runner startup with no checkout or repository command: infrastructure evidence; + - timeout/cancellation: report the last completed phase and do not infer repository failure. +6. Independently validate the exact remote commit in a clean detached checkout/worktree using the repository's frozen-lockfile install, full validator/test/typecheck/build command, and `git diff --check`. +7. Report remote CI and local validation separately. A local pass does not turn remote exact-head CI green; an infrastructure failure does not prove the repository content failed. +8. Keep the verdict `partially in sync` when required remote build/render evidence is unavailable or failed, unless project policy explicitly allows a different disposition. State the smallest remediation: rerun exact-head CI or repair runner infrastructure, then re-read the remote terminal result. + +## Concurrent-branch safety + +If another channel worker is actively correcting the same PR branch: + +- do not create a competing Architecture PR; +- compare the remote PR head with local work before making claims; +- describe unpushed commits or working-tree fixes as ongoing local work, never as delivered remediation; +- wait for the corrected remote head and its own exact-head CI before completion. + +## Reporting checklist + +- default branch and SHA; +- PR URL, head/base SHA, mergeability, and remote changed-file scope; +- exact task/run/job IDs and failure phase; +- clean exact-commit local command results; +- browser/render checks performed or explicitly not rerun; +- approval gate under the active authority contract unchanged by CI, review, merge, or local validation; treat it as human-only only when the invocation explicitly narrows authority. diff --git a/references/multidimensional-lifecycle-presentation-audit.md b/references/multidimensional-lifecycle-presentation-audit.md new file mode 100644 index 0000000..c7e97e1 --- /dev/null +++ b/references/multidimensional-lifecycle-presentation-audit.md @@ -0,0 +1,56 @@ +# Multidimensional lifecycle presentation audit + +Use this audit when canonical task execution or deployment evidence has advanced but Scope, Architecture, Kanban, or release pages may still show an earlier snapshot. + +## Model the dimensions separately + +For every affected Epic and Feature, record these as distinct fields rather than forcing them into one status: + +1. **Scope lifecycle** — proposal and `Approved for Solution` state owned by Scope. +2. **Solution package** — package completeness, requirements, ADRs, and C4 impact owned by Architecture. +3. **Implementation approval** — exact Feature decision and conditions. +4. **Execution** — task-derived `InBacklog`, `InProgress`, or `ToBeReleased` state. Mark parent Epic/Feature values as **derived** unless they have their own canonical flow event. +5. **Publication/deployment** — application source, published artifact, selected GitOps revision, and verified runtime source. +6. **Acceptance/release** — Feature acceptance and final release allocation; never infer these from execution or deployment. + +## Evidence-first consistency matrix + +Build an expected-versus-actual matrix from current remote default: + +| Surface | Required comparison | +|---|---| +| Canonical Feature records | Scope state, package status, implementation decision, proposed/final version | +| Canonical task records | `status`, `flow_state`, `delivery_started`, flow history, implementation evidence | +| Scope Roadmap | All lifecycle dimensions visible; current prose agrees with canonical tasks | +| Kanban Board/Focus | Exact tasks shown directly; parent execution clearly labelled as derived | +| Architecture lifecycle/registers | Historical admission snapshots are dated or updated; no current claim that Delivery has not started when tasks are active | +| Release readiness | Published source, selected GitOps revision, and runtime source kept distinct | +| Task evidence prose | Deployment claims agree with Releases/runtime evidence without implying acceptance | +| Public adapters and types | Verification fields are derived before private metadata is stripped | +| Tests | Production-data assertions plus mutations for stale prose, missing derived fields, and forged cross-record evidence | + +Do not accept a green build as semantic consistency. Search static prose for obsolete assertions such as `Delivery has not started`, `all tasks are InBacklog`, `not deployed`, or `no implementation evidence`, then compare each claim with canonical YAML and current immutable evidence. + +## Parent-state derivation rules + +- Derive Feature execution only from verifier-admitted child tasks. +- Derive Epic execution only from verified child Feature/task execution. +- Label every derived parent state `(derived)` in visual nodes, tables, and accessibility text. +- Preserve Scope status as Scope status; do not rewrite `Approved for Solution` to `InProgress`. +- Define deterministic aggregation precedence and test mixed child states. +- A parent-derived `InProgress` value is presentation evidence, not a new lifecycle decision. + +## Coordinated remediation + +1. Freeze six-channel high-watermarks and current remote default SHA. +2. Confirm the contradiction using canonical records and exact immutable implementation/deployment evidence. +3. Inventory every sibling surface and adapter that presents the affected records. +4. Update data derivation, types, visual nodes, semantic tables, accessibility text, static prose, and tests together. +5. Include negative assertions rejecting superseded current-state wording. +6. Run production-data derivation tests, all domain validators, TypeScript, strict build, browser QA, generated-output drift checks, and `git diff --check`. +7. Publish one owning PR, verify the complete changed-file list, wait for exact-head CI, merge only under the active authority contract, and verify exact-default CI. +8. Perform a final six-channel plus remote-artifact convergence pass. + +## Concurrent candidate rule + +If another Architecture session has already disclosed or created an unpublished lifecycle correction, verify only its branch, base/head, cleanliness, publication state, remote PR inventory, and claimed CI. Do not modify, rebase, publish, validate as your deliverable, or create a competing PR. Report uncovered contradictions as required scope for the owning review, distinguishing current default truth from unpublished candidate work. diff --git a/references/scheduled-sync-evidence-convergence.md b/references/scheduled-sync-evidence-convergence.md new file mode 100644 index 0000000..f40441f --- /dev/null +++ b/references/scheduled-sync-evidence-convergence.md @@ -0,0 +1,52 @@ +# Scheduled synchronization evidence convergence + +Use this procedure when an Architecture synchronization must correlate six authorized Discord channels with mutable Gitea pull requests and exact-head CI without churning an owning PR. + +## Freeze the initial evidence window + +1. Read only the six authorized project channels. +2. Record one high-watermark per channel: newest message ID, timestamp, author ID, and author type. +3. Fetch potentially substantive messages in full. A truncated digest is discovery evidence only. +4. Preserve the frozen high-watermarks unchanged while repository and CI validation runs. + +## Stabilize mutable remote facts + +For each relevant pull request, fetch fresh server-side details and the changed-file list immediately before validation. Record: + +- default branch and freshly resolved default SHA; +- PR state, merge state, mergeability, base SHA, head SHA, and head ref; +- exact changed-file list; +- latest terminal Actions task whose full `head_sha` equals the PR head. + +Use a harmless cache-busting query parameter on Gitea task and PR reads when response freshness is uncertain. Never transfer CI success from an earlier head. + +When a PR advanced since the previous Architecture review: + +1. fetch the current named branch or immutable head explicitly; +2. assert the candidate worktree's full `HEAD` equals the server-side PR head; +3. compare default-to-current for full PR scope; +4. compare previously reviewed head directly to current head for incremental drift (`git diff ..`, not a three-dot merge-base diff); +5. validate in the candidate worktree's actual working directory and print both `pwd` and full `HEAD` before and after validation. + +## Classify before changing an Architecture artifact + +An owning PR advance warrants exact-head review, but not automatically an Architecture edit. Classify the delta: + +- **Material Architecture effect:** human lifecycle decision, canonical shared-data change consumed by Architecture, Architecture-path/configuration change, runtime/deployment truth that contradicts current Architecture text, or PR state/head drift that changes the gate. +- **Corroborating only:** bot-authored evidence that preserves lifecycle state and does not contradict the durable gate. + +For corroborating-only evidence, keep the Architecture PR head unchanged after exact-head review and report the validated owning-head transition. Do not refresh dated provenance merely to chase bot-only high-watermarks. + +## Final convergence guard + +Query each channel with `after=`. If any delta appears, fetch every intervening potentially substantive message in full and reclassify it. Then re-read: + +- default SHA; +- each relevant PR head/state/changed-file list; +- latest exact-head terminal CI task. + +Finish only after one complete pass finds no channel delta and unchanged remote facts. This final guard proves only that nothing arrived after the frozen window; it does not replace the initial authorization-sensitive history scan. + +## Credential and output safety + +Load configured credentials only inside the short-lived process. Parse profile environment keys in memory, never print token values or authorization headers, and emit only non-secret IDs, SHAs, statuses, file paths, and message metadata. Store probes outside repository worktrees and use run-unique filenames when concurrent scheduled jobs may share the host. diff --git a/tests/test_task_breakdown_policy.py b/tests/test_task_breakdown_policy.py index b4d00aa..c066de2 100644 --- a/tests/test_task_breakdown_policy.py +++ b/tests/test_task_breakdown_policy.py @@ -59,7 +59,7 @@ class TaskBreakdownPolicyTest(unittest.TestCase): ) def test_operational_policy_is_complete_and_structured(self): - self.assertIn("version: 1.8.0", self.skill) + self.assertIn("version: 1.9.0", self.skill) self.assertEqual(policy_failures(self.task_section, self.approval_rule), []) def test_comments_and_weakened_rules_cannot_satisfy_policy(self):