docs+chore: repo hygiene -- v2.0 manifests, ADRs, changelog, doctor, guides #20

Merged

admin merged 1 commits from docs/repo-hygiene-v2-standard into main 2026-08-11 12:32:19 +00:00

Conversation 0 Commits 1 Files Changed 32

+1569 -81

admin commented 2026-08-11 12:18:51 +00:00

Owner

Copy Link

Copy Source

Summary

Repo-hygiene pass covering BACKLOG P1-1, P1-2, P1-3, P1-19, P1-20, P1-21, P2-5, P3-5, and all 19 P6 guide-level items.

• P1-1: siax.repo.json/siax.config.json rewritten to be schema-valid against sax3l/siax-standard's actual v2.0 schemas — validated with Python jsonschema, not eyeballed. config.json restructured to the real deploy-descriptor shape (framework/build/start/port/healthcheck/environments), dropping fields the schema doesn't allow there (they already live correctly in repo.json). Confirmed no code in this repo reads either file (grep), so this is a safe, non-breaking manifest change.
• P1-2: 3 ADRs for decisions already made and evidenced elsewhere (Coolify-not-Vercel, Zitadel-not-NextAuth, Iceberg pointer to n0d ADR-0030) — retroactive documentation, not new decisions. Payments-provider and services/scrapers/* explicitly not written as ADRs (account-owner-gated / actively under review — see docs/architecture/decisions/README.md).
• P1-3: CHANGELOG.md from real git log history.
• P1-19: pnpm siax:doctor (scripts/siax-doctor.mjs, zero-dependency, control AGENT-04), .devcontainer/devcontainer.json, compose.dev.yaml (⚠️ unverified — no Docker available in the environment this was authored in, flagged in the file itself), all 4 prompts/*.md + index rewritten to the required goal/context/prerequisites/scope/contract/acceptance-criteria/control-ID/forbidden-actions shape.
• P1-20: docs/architecture/ARCHITECTURE.md migrated to the v2.0 9-heading template — new §5 "Ytor och paritet" capability-coverage table, §6–9 renumbered from the old §5–8 with every internal cross-reference fixed (verified via scripted diff, one CLAUDE.md §5 external reference caught and corrected after an over-eager regex pass). docs/api/ added, pointing at contracts/openapi.yaml as the one SSOT rather than duplicating it.
• P1-21: packages/schemas now has a real package.json (was loose JSON files, no package — the workspace glob matched nothing). Verified pnpm install --frozen-lockfile + full typecheck/test/build still pass with 2 real workspace projects. apps/ restructuring explicitly not attempted — the backlog's own effort estimate is "L" (large), moving the whole app tree is bigger and riskier than belongs in an autonomous pass. Import-boundary check added via dependency-cruiser — installed for real, tested against this codebase (179 modules, 310 deps, 0 violations), wired as pnpm run deps:check (advisory, not a CI gate yet).
• P2-5: docs/02-architecture.md's "Hosting" section marked SUPERSEDED (superseded by the Coolify deploy.target flip, ADR-0001). Checked README.md/.env.example — already accurately framed, not touched.
• P3-5: 2 stale github.com/.../pull/3 links removed (merged long ago, .env.example is real today). The "two diverged remotes, unresolved which is canonical" language elsewhere is deliberately not touched — that's a live, correctly-flagged, account-owner-owned open question per the Gitea-exclusivity mandate, not a stale link.
• P6 (19 items): concrete files for the ones that are actually a file (.editorconfig, .dependency-cruiser.cjs, deprecation policy, K8s reference manifest, .actrc, Makefile, ONBOARDING.md); docs/guides/P6-GUIDES.md for the rest, each grounded in this repo's actual code/gaps.

Explicitly not attempted (noted, not silently skipped)

• P2-1 (cl0ud/.../app-registry.ts mismatch) — lives in a different repo (sax3l/cl0ud), not cloned or authorized for this task's single-repo PR flow.
• The CI "doctor step" half of P1-15 — left out of this PR's ci.yml on purpose to avoid a 3-way merge conflict with ci/security-headers-and-scanning, which already restructured that file. Add it as a follow-up once that PR merges.

Cross-PR note for the reviewer

This branch shares docs/architecture/ARCHITECTURE.md and docs/slo.md with fix/honest-health-check, and shares docs/slo.md/attribution comments with the concurrent docs/curl-cffi-decision-attribution merge that landed on main mid-session. All three of my branches were rebased cleanly against the latest main and against each other as of this PR — but if this is rebased again after one of the sibling PRs merges, expect a normal, small conflict in ARCHITECTURE.md (different sections, should auto-resolve in most merge tools).

Test plan

• pnpm run typecheck / pnpm run test (134 passed, 1 pre-existing skip) / pnpm run build — all pass.
• pnpm run lint — identical pre-existing baseline, no new errors from anything in this PR.
• node scripts/siax-doctor.mjs — 38/40 checks pass on this branch alone; the 2 expected failures (CODEOWNERS, app/api/ready/route.ts) come from the sibling PRs by design (documented in the script's own header).
• siax.repo.json / siax.config.json validated against the real sax3l/siax-standard JSON Schemas with Python jsonschema — both VALID.
• pnpm run deps:check (dependency-cruiser) — 0 violations.
• YAML/JSON syntax-checked every new/changed non-Markdown file.

Not merged

Per instructions.

🤖 Generated with Claude Code

## Summary Repo-hygiene pass covering BACKLOG **P1-1, P1-2, P1-3, P1-19, P1-20, P1-21, P2-5, P3-5**, and all 19 **P6** guide-level items. - **P1-1**: `siax.repo.json`/`siax.config.json` rewritten to be schema-valid against `sax3l/siax-standard`'s actual v2.0 schemas — validated with Python `jsonschema`, not eyeballed. `config.json` restructured to the real deploy-descriptor shape (`framework`/`build`/`start`/`port`/`healthcheck`/`environments`), dropping fields the schema doesn't allow there (they already live correctly in `repo.json`). Confirmed no code in this repo reads either file (grep), so this is a safe, non-breaking manifest change. - **P1-2**: 3 ADRs for decisions already made and evidenced elsewhere (Coolify-not-Vercel, Zitadel-not-NextAuth, Iceberg pointer to `n0d` ADR-0030) — retroactive documentation, not new decisions. Payments-provider and `services/scrapers/*` explicitly **not** written as ADRs (account-owner-gated / actively under review — see `docs/architecture/decisions/README.md`). - **P1-3**: `CHANGELOG.md` from real `git log` history. - **P1-19**: `pnpm siax:doctor` (`scripts/siax-doctor.mjs`, zero-dependency, control AGENT-04), `.devcontainer/devcontainer.json`, `compose.dev.yaml` (⚠️ **unverified** — no Docker available in the environment this was authored in, flagged in the file itself), all 4 `prompts/*.md` + index rewritten to the required goal/context/prerequisites/scope/contract/acceptance-criteria/control-ID/forbidden-actions shape. - **P1-20**: `docs/architecture/ARCHITECTURE.md` migrated to the v2.0 9-heading template — new **§5 "Ytor och paritet"** capability-coverage table, §6–9 renumbered from the old §5–8 with every internal cross-reference fixed (verified via scripted diff, one `CLAUDE.md §5` external reference caught and corrected after an over-eager regex pass). `docs/api/` added, pointing at `contracts/openapi.yaml` as the one SSOT rather than duplicating it. - **P1-21**: `packages/schemas` now has a real `package.json` (was loose JSON files, no package — the workspace glob matched nothing). Verified `pnpm install --frozen-lockfile` + full typecheck/test/build still pass with 2 real workspace projects. `apps/` restructuring **explicitly not attempted** — the backlog's own effort estimate is "L" (large), moving the whole app tree is bigger and riskier than belongs in an autonomous pass. Import-boundary check added via `dependency-cruiser` — installed for real, tested against this codebase (179 modules, 310 deps, 0 violations), wired as `pnpm run deps:check` (advisory, not a CI gate yet). - **P2-5**: `docs/02-architecture.md`'s "Hosting" section marked SUPERSEDED (superseded by the Coolify `deploy.target` flip, ADR-0001). Checked `README.md`/`.env.example` — already accurately framed, not touched. - **P3-5**: 2 stale `github.com/.../pull/3` links removed (merged long ago, `.env.example` is real today). The "two diverged remotes, unresolved which is canonical" language elsewhere is **deliberately not touched** — that's a live, correctly-flagged, account-owner-owned open question per the Gitea-exclusivity mandate, not a stale link. - **P6** (19 items): concrete files for the ones that are actually a file (`.editorconfig`, `.dependency-cruiser.cjs`, deprecation policy, K8s reference manifest, `.actrc`, `Makefile`, `ONBOARDING.md`); `docs/guides/P6-GUIDES.md` for the rest, each grounded in this repo's actual code/gaps. ## Explicitly not attempted (noted, not silently skipped) - **P2-1** (`cl0ud/.../app-registry.ts` mismatch) — lives in a **different repo** (`sax3l/cl0ud`), not cloned or authorized for this task's single-repo PR flow. - The **CI "doctor step"** half of P1-15 — left out of this PR's `ci.yml` on purpose to avoid a 3-way merge conflict with `ci/security-headers-and-scanning`, which already restructured that file. Add it as a follow-up once that PR merges. ## Cross-PR note for the reviewer This branch shares `docs/architecture/ARCHITECTURE.md` and `docs/slo.md` with `fix/honest-health-check`, and shares `docs/slo.md`/attribution comments with the concurrent `docs/curl-cffi-decision-attribution` merge that landed on `main` mid-session. All three of my branches were rebased cleanly against the latest `main` and against each other as of this PR — but if this is rebased again *after* one of the sibling PRs merges, expect a normal, small conflict in `ARCHITECTURE.md` (different sections, should auto-resolve in most merge tools). ## Test plan - [x] `pnpm run typecheck` / `pnpm run test` (134 passed, 1 pre-existing skip) / `pnpm run build` — all pass. - [x] `pnpm run lint` — identical pre-existing baseline, no new errors from anything in this PR. - [x] `node scripts/siax-doctor.mjs` — 38/40 checks pass on this branch alone; the 2 expected failures (`CODEOWNERS`, `app/api/ready/route.ts`) come from the sibling PRs by design (documented in the script's own header). - [x] `siax.repo.json` / `siax.config.json` validated against the real `sax3l/siax-standard` JSON Schemas with Python `jsonschema` — both VALID. - [x] `pnpm run deps:check` (dependency-cruiser) — 0 violations. - [x] YAML/JSON syntax-checked every new/changed non-Markdown file. ## Not merged Per instructions. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

admin added 1 commit 2026-08-11 12:18:51 +00:00

docs+chore: repo hygiene -- v2.0 manifests, ADRs, changelog, doctor, guides ... 328f8a46cb

BACKLOG P1-1: siax.repo.json/siax.config.json rewritten to be schema-valid
against sax3l/siax-standard's actual v2.0 schemas (lifecycle,
operationalState, gitHost, domains-as-objects, consumedBy, children,
contracts -- validated with jsonschema, not just eyeballed). config.json
restructured to the real deploy-descriptor shape (framework/build/start/
port/healthcheck/environments) instead of duplicating repo.json's identity
fields, which the schema doesn't allow.

BACKLOG P1-2: 3 ADRs for decisions already made and evidenced elsewhere in
this repo (Coolify-not-Vercel, Zitadel-not-NextAuth, Iceberg-format pointer
to n0d ADR-0030) -- retroactive documentation, not new decisions. The
Stripe/Revolut and services/scrapers/* questions are explicitly NOT written
as ADRs here; both are account-owner-gated or actively under review
elsewhere (see docs/architecture/decisions/README.md).

BACKLOG P1-3: CHANGELOG.md from real git log history (no tags/releases
exist yet -- this doesn't invent version numbers that were never cut).

BACKLOG P1-19: `pnpm siax:doctor` (scripts/siax-doctor.mjs, AGENT-04) --
zero-dependency, checks required files + manifest shape, prints
control-IDs. .devcontainer/devcontainer.json (DX-03). compose.dev.yaml
(DX-02 -- UNVERIFIED, no Docker available in this environment to smoke-test,
flagged in the file itself). All 4 prompts + the index rewritten to AGENT-03
shape (goal/context/prerequisites/scope/contract/acceptance-criteria/
control-ID/forbidden-actions).

BACKLOG P1-20: docs/architecture/ARCHITECTURE.md migrated to the v2.0
9-heading template -- new §5 "Ytor och paritet" (capability x
API/CLI/MCP/console coverage table, grounded in the same registry facts
docs/02-architecture.md already established), §6-9 renumbered from the old
§5-8 (all internal cross-references fixed, CLAUDE.md's own §-numbers left
untouched). docs/api/ added (points at contracts/openapi.yaml as the one
SSOT instead of duplicating it as drift-prone prose).

BACKLOG P1-21: packages/schemas now has a real package.json (was loose JSON
files with no package -- pnpm-workspace.yaml's packages/* glob matched an
empty package). Verified `pnpm install --frozen-lockfile` and the full
typecheck/test/build suite still pass with 2 real workspace projects.
apps/ restructuring explicitly NOT attempted (BACKLOG's own effort estimate
is "L" / large -- moving the whole app tree is a bigger, riskier change than
belongs in this pass). Import-boundary check added via dependency-cruiser
(ARK-14) -- installed for real, config tested against this codebase (179
modules, 310 deps, 0 violations), wired as `pnpm run deps:check` (advisory,
not yet a CI gate).

BACKLOG P2-5: docs/02-architecture.md's "Hosting" section marked SUPERSEDED
(the Vercel plan was superseded by the Coolify deploy.target flip,
2026-08-09 -- ADR-0001). README.md/.env.example were checked and are
already accurately framed (live-on-Vercel vs. config-target-is-Coolify) --
not touched.

BACKLOG P3-5: 2 stale github.com/sax3l/0pt/pull/3 links removed (the PR
merged long ago, .env.example is real and current) -- docs/09-build-plan.md,
docs/08-infrastructure.md. The "two diverged remotes, unresolved which is
canonical" language elsewhere (CLAUDE.md, AGENTS.md, SECURITY.md, etc.) is
deliberately NOT touched -- that's a live, correctly-flagged, account-owner-
owned open question per the Gitea-exclusivity mandate, not a stale link.

BACKLOG P6 (19 items): concrete artifacts for the ones that are actually a
file (.editorconfig, dependency-cruiser, deprecation policy, K8s reference
manifest, .actrc, Makefile, ONBOARDING.md); docs/guides/P6-GUIDES.md for the
rest (CLI-13, DOC-18, UI-30, IAM-19, PAY-11, AI-18, OBS-21, TEST-20, NET-19,
SCALE-13, OSS-10, AGENT-13) -- each grounded in this repo's actual code/gaps,
not generic advice.

NOT attempted (out of this task's scope, noted for the record):
- P2-1 (cl0ud app-registry.ts mismatch) -- lives in a different repo
  (sax3l/cl0ud), not cloned/authorized for this task's single-repo PR flow.
- The CI "doctor step" half of P1-15 -- deliberately left out of this PR's
  .gitea/workflows/ci.yml to avoid a 3-way merge conflict with
  ci/security-headers-and-scanning, which already restructured that file;
  add it as a follow-up once that PR merges.

This branch was authored independently of, but shares docs/architecture/
ARCHITECTURE.md and docs/slo.md with, fix/honest-health-check and
ci/security-headers-and-scanning -- expect a small, normal merge conflict
if this is rebased after either of those merge first (both already rebased
cleanly against each other and against main as of this commit).

admin merged commit into main 2026-08-11 12:32:19 +00:00

admin referenced this pull request 2026-08-11 12:39:11 +00:00

feat(compliance): scaffold Golden Standard artifacts (CI-14, DX-02, DX-03) #21

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

siax-bot siax-ci siax-healer (siax-healer (CI self-healing agent)) admin (Simon Axelsson)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: admin/0pt#20