Fleet root-file extras audit

Snapshot of root-directory files that exist in fleet apps but not in this template — what they're for, how common they are, and what to do with each.

Last audited: 2026-05-23. To refresh: run the audit script in scripts/audit-fleet-root-files.sh (or the inline Python in the docs/canonical-files.md history) against apps-extra/.

Methodology

For each file present in ≥ 1 fleet app but not in this template, the audit records:

• Count — how many of the 22 audited fleet apps carry the file.
• Decision — one of:
  • Promote to template (worthy of being canonical or in the scaffold).
  • Move/keep app-private (legitimately per-app; just not a template file).
  • Move out of repo root (belongs in docs/, scripts/, etc.).
  • Delete (build artefact, scratch, or obsolete).
  • Out of scope (ExApp sidecar, special-case, intentional).

Apps in scope for this audit: app-versions, decidesk, deskdesk, docudesk, larpingapp, launchpad, nldesign, openbuild, opencatalogi, openconnector, openklant, openregister, opentalk, openzaak, pipelinq, planix, procest, scholiq, shillinq, softwarecatalog, valtimo, zaakafhandelapp.

High-frequency extras (≥ 6 apps)

File	Count	Purpose	Decision
CHANGELOG.md	13/22	Release-notes log per app	Promote to template scaffold — every released app wants one
.license-overrides.json	10/22	Per-app allow-list for compound-SPDX vendor packages	Promote to template scaffold (already Tier B in policy) — ship an empty one, apps add entries as needed
tsconfig.json	8/22	TypeScript path/lib config	Promote to template scaffold if the app uses any TS in src/
openapi.json	8/22	OpenAPI spec for the app's REST surface	Promote to template scaffold as an empty starter
.nvmrc	8/22	Node version pin	Already promoted to Tier A canonical (this PR)
.nextcloud	7/22	Nextcloud helper-tool marker file	Keep as-is — generated by occ workflow
jest.config.js	7/22	Jest config	Promote to template scaffold (Tier B)
.php-cs-fixer.dist.php	7/22	PHP-CS-Fixer config	Delete fleet-wide — superseded by PHPCBF + the canonical phpcs.xml. openconnector#842 already removed it there.
docker-compose.yml	6/22	App-local dev environment	Keep app-private — significant per-app variation
composer-setup.php	6/22	Composer installer helper	Delete fleet-wide — vendor binary, install via PATH
.babelrc	6/22	Babel config	Out of scope — superseded by eslint.config.js + webpack babel-loader inline config

Medium-frequency extras (3–5 apps)

File	Count	Purpose	Decision
.phpunit.result.cache	5/22	PHPUnit run cache	Delete + gitignore fleet-wide — already in Tier D
REVIEW.md	5/22	Per-PR review notes scratchpad	Move to docs/ or delete — should not live in root
sbom.cdx.json	5/22	CycloneDX software-bill-of-materials	Keep as-is — generated by composer plugin, may be committed for compliance
.phpqa.yml	5/22	PHPQA aggregate tool config	Delete fleet-wide — PHPQA superseded by direct phpcs/psalm/phpstan/phpmd invocation per ADR-033
grumphp.yml	5/22	GrumPHP pre-commit hooks	Delete fleet-wide — superseded by GitHub Actions quality gates
REUSE.toml	5/22	REUSE software-licensing spec	Keep app-private — needed for EUPL compliance reporting
DEVELOPMENT.md	4/22	Per-app dev setup notes	Move to docs/ — should not live in root
test-guide.md	4/22	Per-app test plan / E2E guide	Move to docs/ — should not live in root
entrypoint.sh	4/22	ExApp container entrypoint	Out of scope — ExApp sidecars only (valtimo/openzaak/opentalk/openklant)
Dockerfile	4/22	ExApp container image	Out of scope — ExApp sidecars
requirements.txt	4/22	Python deps for ExApp	Out of scope — ExApp sidecars
phpmd.baseline.xml	3/22	PHPMD pre-existing-debt baseline	Keep app-private — Tier C
.specter-prompt.txt	3/22	OpenSpec generation prompt	Keep app-private — used by Specter spec generator
phpstan-baseline.neon	3/22	PHPStan pre-existing-debt baseline	Keep app-private — Tier C
psalm-baseline.xml	3/22	Psalm pre-existing-debt baseline	Keep app-private — Tier C
.cursorrules	3/22	Cursor IDE rules	Promote to template scaffold if anyone on the team uses Cursor

Per-app outliers (1–2 apps)

The long tail is dominated by softwarecatalog with ~30 scratch files in repo root. The general placement rule:

• Shell + PHP test scripts (test_*.sh, debug_*.php, etc.) → tests/. These ARE the app's test suite; they belong with the rest of the tests (alongside unit/Newman/Playwright), not in scripts/ or in the root.
• Unique app setup / dev tooling that isn't a test → scripts/dev/.
• Work-in-progress / issue notes / planning markdown → docs/notes/ (or docs/specs-todo/ if it's intended to be turned into an OpenSpec spec later). Don't delete this kind of content — even when it's rough, the conversation history captured in those notes is the raw material the next round of specs gets written from.
• Build artefacts → delete + add to .gitignore (see Tier D).

softwarecatalog cleanup candidates

softwarecatalog is a special case: many of the root-level notes are the long-form record of issues, testing experiments, and the "is-this-feature-done-yet" conversations the team has had about the app. We want to preserve all of it as future spec source material, not delete. The move is into docs/specs-todo/ so the content survives and can be picked up later when each topic gets turned into an OpenSpec change.

• 25+ test_*.sh / test-*.sh shell scripts → move to tests/ (these are the app's actual test suite — Newman/integration/shell-driven scenarios).
• debug_*.php, check_*.php, compare_archimate.{php,py}, enhance_archimate_service.php, find_objects_*.php, cleanup_id_properties.php, cleanup_schema.php → move to scripts/dev/ (these are diagnostic / one-shot dev utilities, not the test suite).
• AMEF_TESTING.md, ARCHIMATE_*.md, BUG_FIX_*.md, CIRCLE_TEST_DOCUMENTATION.md, FIX_VERIFICATION_SUMMARY.md, FRONTEND_DEVELOPMENT_GUIDE.md, INTEGRATION_TEST_RESULTS.md, KOPPELINGEN_GEBRUIK_REFACTOR.md, Openregister.md, README_DEBUG.md, aanvullende-informatie.md, issues.md, qwen-phpcs-test.md, setup-menus-and-pages.md, WORKFLOW-UNSTABLE-RELEASE.md → move to docs/specs-todo/ (preserves the issue-and-testing conversation history as future spec source material).
• reactphp_architecture.{html,mmd} → move to docs/architecture/.
• test_small_archimate.xml → move to tests/fixtures/.

opencatalogi cleanup candidates

• CONFIG_SYNC.md, DEEPLINKING_AND_SPOT.md, NAMED_PARAMETERS_GUIDE.md, QUALITY_REFACTORING_PLAN.md, README_AGGREGATED_PUBLICATIONS.md, SITEMAP.md, WORKFLOW_CHANGES.md, setup-menus-and-pages.md → move to docs/notes/
• phpcs-output.json, phpcs-output-after.json, coverage.txt, fix-phpcs.php → delete + gitignore
• docker-compose-build.yml → keep if functional or merge into main docker-compose.yml

openregister cleanup candidates

• composer.phar, phpstan.phar → delete (Tier D)
• bom-npm-test.cdx.json → delete (Tier D)
• .last-update, .opsx-ignore → delete (Tier D)
• qwen-phpcs-test.md, QUALITY_OVERVIEW.md, PLAN-property-level-rbac.md → move to docs/notes/
• docker-compose.demo.yml, docker-compose.dev.yml, docker-compose.integration-verification.yml, docker-compose.mariadb-test.yml, docker-compose.sso.yml, docker-compose.federation.yml → keep (foundation repo legitimately has multiple environments)
• .git-blame-ignore-revs, .grype.yaml, .spectral.yml → keep
• test-mcp.sh → move to scripts/dev/

app-versions cleanup candidates

• .eslintrc.cjs → delete (superseded by canonical eslint.config.js flat config)
• vite.config.ts, stylelint.config.cjs → reconcile with the canonical webpack.config.js + stylelint.config.js (if app-versions uses Vite intentionally, document the deviation; otherwise drop)
• rector.php → keep if Rector is actively used; otherwise delete
• CODE_OF_CONDUCT.md → consider promoting to all apps (or moving to org-level)

launchpad cleanup candidates

• HANDOVER.md → move to docs/notes/ or delete

nldesign cleanup candidates

• QUICKSTART.md → move to docs/getting-started.md
• design-systems.json, token-sets.json → keep (theme-specific source-of-truth)

zaakafhandelapp cleanup candidates

• DESIGN.md → move to docs/architecture.md
• .eslintrc.js → delete (superseded by canonical eslint.config.js flat config)

larpingapp + openconnector cleanup candidates

• psalm copy.xml (both) → delete — editor accident (Tier D)
• larpingapp/.cursorrules, openconnector/.cursorrules, softwarecatalog/.cursorrules → see "promote to template" decision above
• openconnector/.cursors/ → typo of .cursor/, reconcile

Repo-root directories that should NOT be committed

Separate from the per-file extras, several directories appear in fleet repo roots that are build / test artefacts and should be removed from git + added to .gitignore:

Directory	What it is	Action
test-results/	Playwright / Jest run output	Delete + .gitignore (template's .gitignore already covers it; sync the .gitignore via a per-app sweep)
playwright-report/	Playwright HTML reports	Same
.phpunit.cache/	PHPUnit run cache	Same
coverage/, coverage-frontend/	Coverage reports	Same
phpqa/, phpmetrics/, phpmetrics-deps/	Quality-tool output	Same
quality-reports/, quality-results/	CI artefact uploads	Same
dist/, build/ (when not the JS bundle)	Webpack / docusaurus output (varies)	App-by-app — keep js/ since NC needs the built bundle in repo, but other dist/ / build/ are artefacts
node_modules/, vendor/, vendor-bin/	Dependency installs	Already in canonical .gitignore — confirm fleet apps inherit it

The template's canonical .gitignore already lists all of these. The follow-up work is verifying each fleet app's .gitignore carries the same entries AND that no committed instances of these directories remain on development branches. Audit script (refresh whenever you want a fresh count):

# Apps with test-results/ committed:
for app in apps-extra/*/; do
  [ -d "$app/test-results" ] && \
    [ -z "$(cd "$app" && git check-ignore test-results 2>/dev/null)" ] && \
    echo "$app"
done

Cleanup PR strategy

1. Tier D mass-cleanup: one fleet sweep PR per app, deletes the build-artefact / vendor-binary / cache files + adds .gitignore entries. ~10 lines per PR, low-risk admin-merge.

2. softwarecatalog deep clean: dedicated PR moving ~30 files out of root. Larger diff but mostly file moves; no content changes.

3. Template scaffold additions: separate PR adding CHANGELOG.md template, .license-overrides.json stub, openapi.json stub, tsconfig.json template, jest.config.js template to this repo. Documents shape in docs/canonical-files.md Tier B.

4. Per-app one-offs: file an issue per cleanup candidate listed above, pick them up opportunistically when the app gets touched for other reasons.

When in doubt about whether something should be deleted, prefer move to docs/notes/ over delete — preserves history, future grep finds it, and the repo root stays clean either way.