Architecture

The repository is organized as a workbench pipeline:

1. confluence/ mirrors Confluence storage XHTML, metadata, hierarchy, templates,

attachments, comments, and sync reports.

2. evidence/ stores curated references and provenance for non-Confluence input.
3. analysis/ captures version-bound page, subtree, topic, finding, and research

task objects.

4. architecture/ contains English-first synthesis, positions, decisions,

principles, and models.

5. workbench/ contains draft sections, translations, and structured content

objects that can feed proposals.

6. proposals/ groups changes into reviewable packages and page-scoped publish

units.

7. publication/ records readiness, approvals, targets, and dry-runs.
8. apps/portal/ renders the static review surface.

Early CI gates validate repository shape, documentation, workflow safety, mirror foundation contracts, and the portal build. Later milestones can add typed data validation for analysis objects and live Confluence sync checks as the object models become real.

Preview publication evidence

Milestone 11 adds a repeatable evidence bundle for the static fixture portal without enabling live Forgejo status writes or Confluence staging:

1. npm run evidence:preview reads the generated review indexes, verifies the

built Astro output under apps/portal/dist/, exercises every configured route and viewport with Playwright, and retains two representative screenshots: desktop Confluence navigation and mobile architecture rendering.

2. The script rejects page-level horizontal overflow for every tested route and

viewport, then writes .reports/preview-evidence/manifest.json with the commit identifier, route inventory, viewport inventory, review-index counts, Forgejo artifact metadata, and screenshot paths.

3. The same evidence directory carries copied generated indexes and

.reports/readiness-summary.md, so a Forgejo artifact can tie the portal build, readiness state, generated data, and visual QA to one commit.

The bundle is generated from Git-backed workbench data. Authenticated PR preview of committed content allowed; public publication/live authority remains blocked.

TASK-008 resolves the current live-write boundary in architecture/decisions/0002-live-preview-write-boundaries.md: the preview comment token stays unset by default, later activation requires verified repository-only minimum comment permissions and fork or untrusted-PR secret behavior, and Forgejo status contexts stay deferred until an automated consumer needs machine-readable status. This decision closes the review question only; it does not activate live comments, authenticated previews, real RWS content, or Confluence staging.

TASK-030 resolves the current status-context question in architecture/decisions/0007-defer-forgejo-status-contexts-until-a-consumer-exists.md: custom Forgejo status contexts are not needed for the fixture review path while CI jobs, the uploaded preview evidence artifact, and the gated preview comment cover the current reviewers. A later status writer must first name the consumer and document permission scope, token behavior, rollback, and data-exposure boundaries.

TASK-009 resolves the current authenticated access and staging gate review in architecture/decisions/0004-keep-authenticated-preview-and-staging-gates-blocked.md: the current deployment examples do not prove DNS/TLS ownership, approved ingress authentication, secret delivery, credential lifecycle, ArgoCD ownership, cleanup evidence, content classification, or Confluence rollback. Authenticated previews and staged page writes remain blocked until activation proof satisfies the TASK-028 and TASK-029 contracts without committing secrets or environment-specific runtime values.

ADR 0010 supersedes the preview-rendering restriction in that historical decision: the authenticated preview may render committed vault and Confluence mirror routes, while it does not authorize Confluence writes or public exposure.

TASK-028 defines the preview deployment ownership and cleanup contract in architecture/decisions/0005-preview-deployment-ownership-and-cleanup-contract.md. It requires secret-free proof for DNS/TLS ownership, authenticated access, secret delivery, ArgoCD ownership, quota boundaries, cleanup evidence, orphan reconciliation, and rollback or removal before live preview resources are implemented. It does not activate authenticated previews or real-content exposure; TASK-029 still gates Confluence staging and data handling.

TASK-029 resolves the Confluence staging rollback and data-handling review in architecture/decisions/0006-confluence-staging-rollback-and-data-handling.md. Real RWS content exposure and staged page writes remain blocked until content classification, approved hosting and retention, generated metadata exposure, scoped credentials, dry-run defaults, version-conflict refusal, partial-write recovery, attachment and comment policy, audit trail, and rollback proof are approved.

TASK-039 resolves the scoped sync activation plan in architecture/decisions/0008-plan-scoped-confluence-sync-activation.md: the first real-content candidate is limited to a small reviewed page set, external credential delivery, dry-run and no-live-write defaults, version-conflict refusal, metadata minimization, attachment/comment limits, sync reports, and rollback or removal boundaries. It does not implement sync tooling or approve real RWS content exposure.

TASK-0101 through TASK-0103 now add the first implementation-facing sync review artifacts for that plan: publication/approvals/TASK-0101-approval-package.md, fixture-only command npm run sync:confluence-fixture-dry-run, and publication/dry-runs/TASK-0103-dry-run.md. These artifacts keep live reads, real-content repository import, generated-index exposure, preview screenshots, PR comments, and Confluence writes blocked until human approvals are recorded. TASK-0101 has since selected the Datacenter architecture candidate family and the Server Virtualization and Container Platform pages as initial candidates. The latest observed page IDs, titles, versions, URLs, and zero-byte attachment totals are recorded in the TASK-0101 package. That selection is still not a live-read approval: OpenBao-backed CI credential delivery, trusted-branch gating, version re-check, and reviewed no-live-write proof remain required before TASK-0103; the scoped index-metadata closure for tree, comment indexes, and attachment indexes is recorded in TASK-0109, while future attachment payload handling remains separate. The CI credential plan now targets scheduled/manual sync on same-repository branches and PRs through the existing confluence OpenBao profile if it is least-privilege/read-only enough. The private Wouter-controlled Forgejo trust model removes separate artifact-audience, fork/untrusted misuse, and named runner-trust proof blockers; all configured Forgejo runners are trusted for this workbench. The latest setup decision uses a separate weekly/manual Confluence sync workflow, private CI artifact output first, and runtime refresh of current Confluence versions for read-only sync instead of treating TASK-0101 version drift as a failure. The first proof uses ubuntu-latest, fetches only the three scoped page metadata records, emits report/metadata artifacts by default, and keeps reviewed no-live-write execution as the remaining implementation gate after TASK-0108 and TASK-0109.

Issue workflow model

The current planning model uses Forgejo issues as the operational work queue. Issues carry scope, acceptance criteria, implementation discussion, PR links, CI evidence, and review handoff. Scoped labels in workbench/issue-workflow/labels.json encode type, status, priority, automation intent, gates, and area ownership. The portal reads the issue workflow contract from apps/portal/src/data/issueWorkflow.ts and no longer renders a parallel roadmap ledger.

The agent/implement label starts the issue-agent workflow. The workflow clones MoekenIT/agent-skills, installs the shared OpenCode skills, agents, commands, and helpers into an isolated CI runtime config, and records the exact agent-skills commit used for the run. It is deliberately dry-run until an OpenCode-capable runner is configured with OPENCODE_ISSUE_RUN_ENABLED=1. Issue automation may prepare implementation work and evidence, but Confluence writes, real RWS content exposure, and credentialed preview deployment remain separately approval-gated.

Confluence mirror foundation

Milestone 3 adds the first executable source mirror foundation under confluence/:

1. schemas/ defines the mirror contracts for a space manifest, page metadata,

page tree, attachment index, templates manifest, and sync report.

2. spaces/INFRAARCH/manifest.json is the space-level entry point. It links the

page tree, templates manifest, latest sync report, and page artifacts.

3. Page folders contain page.storage.xhtml, page.metadata.json,

children.json, attachments.json, and comments.json so later analysis can bind findings to a specific Confluence page version.

4. Template folders mirror Confluence template metadata and storage fragments so

ABB/SBB/HLD contract work can compare content against source templates.

5. Sync reports record the run mode, scope, artifact counts, and errors. The

current repository fixture uses mode: fixture; live snapshots must use mode: snapshot after a separate access and data-handling review.

6. TASK-023 expands the fixture with a platform-services hub, a nested API

connectivity SBB, a risk-register appendix, macro-heavy storage fragments, comments, and attachment metadata. These slices are still synthetic and do not approve real RWS content exposure.

The portal reads mirror status, generated source indexes, sanitized fixture or reviewed snapshot storage fragments, escaped fallback storage, attachment metadata, and comment metadata. Snapshot rendering is opt-in behind the reviewed real-rendering guard in apps/portal/src/lib/safeStorage.mjs: mirror.mode must be snapshot, payloadPolicy must be metadata-with-storage, and the page ID must be part of the committed reviewed page set for the scoped INFRAARCH snapshot. The renderer parses storage XHTML with parse5, serializes only the supported subset (headings, paragraphs, lists, tables, links, code/pre blocks, panel/info macros), rewrites in-mirror Confluence page links to local /confluence/<pageId>/ routes, and turns attachment references, external references, unknown macros, and active/unsupported content into inert placeholders. It never fetches Confluence, attachment binaries, comment bodies, credentials, or remote active content. Rollback is to remove a page from the reviewed snapshot set or set the generated mirror mode/payload policy outside the guard; the escaped storage fallback remains visible beside the readable render for review and debugging.

Analysis object foundation

Milestone 4 adds the first typed analysis layer without changing mirrored source artifacts:

1. analysis/schemas/ defines contracts for findings, evidence entries,

version-bound page analysis, and domain-level quality reports.

2. evidence/registry/ stores curated evidence entries with source references,

provenance, usage constraints, and claims.

3. analysis/pages/ binds a Confluence page version to quality checks, evidence,

and finding identifiers.

4. analysis/findings/ records gaps, contradictions, risks, template issues,

missing sources, ownership questions, duplicates, and terminology issues with severity, confidence, status, source references, impacted area, and recommended action.

5. analysis/domains/ rolls page analysis into Datacenter ABB/SBB/HLD quality and

gap reports for portal and review workflows.

The initial data is a synthetic fixture slice. Real RWS analysis remains blocked until live mirror access, content classification, evidence retention, and preview exposure are reviewed.

TASK-0401 records a draft comparison model in analysis/findings/TASK-0401-findings-comparison-model.md. It aligns with the current finding schema as conventions first and remains blocked from final acceptance until full sync data and architect validation are available.