docs(architecture): adopt tracking-number identifiers, and add agent skills

[erseco]

Update — this description predates two changes

The validator is now one shared TypeScript file, byte-identical across
core and all four plugins: tools/architecture-records.mts. It runs under Bun in
exelearning/exelearning, where bun test covers it, and under the Node that
ships on the CI image here — no setup step, no dependency. Anything below that
names a per-repository PHP or Python validator is superseded. Repository-specific
values live in architecture-records.json: paths and the record prefix only.

Do not edit the copy in this repository. Fix it in core and re-copy, or the
copies drift apart — the exact failure this convention exists to prevent.

---

What this is

This repository has no architecture decision records, so there is nothing to migrate. It starts on the convention rather than adopting it after a collision — which is the cheapest moment to do it.

The model matches the rest of the ecosystem: exelearning/exelearning#2232.

Identification

Records are named after the GitHub tracking number of the change they belong to — its issue when there is one, otherwise its pull request. GitHub allocates issue and PR numbers from a single repository-wide sequence, so the two can never collide.

Issues are disabled on this repository:

$ gh api repos/exelearning/nextcloud-exelearning -q .has_issues
false

So every number here is a PR number, and no issue can — or should — be opened merely to obtain one.

docs/architecture/adr/ADR-<number>-<NN>-<decision-slug>.md
docs/architecture/changes/<number>-<change-slug>/

<NN> is a two-digit sequence scoped to that number alone, starting at 01, present even for a single ADR so that adding a second one later never renames the first. There is no global counter — that rule is unsafe on parallel branches, because the collision lands in the filename and Git merges both files cleanly without reporting anything.

The index is not a file

make architecture-records prints it from frontmatter. Committing it would guarantee a merge conflict on every concurrent branch, so check treats its presence as an error.

Tooling

tools/architecture_records.py, matching the existing tools/*.py convention. Standard library only — no YAML dependency for a documentation linter, and its own tests use unittest, so they add no dependency either.

make architecture-check    # validate
make architecture-records  # print the index
make architecture-test     # 35 tests for the tooling

make lint now depends on architecture-check, and CI gets its own architecture-records job that also prints the index into the run summary.

It validates: filename grammar (rejecting the retired global form) · id ↔ filename · tracking_issue ↔ filename/directory · H1 ↔ frontmatter · duplicate ids and sequences · status vocabularies · calendar dates · resolvable ADR/change references · numeric issue/PR values · supersedes/superseded_by symmetry and the Superseded status · retired identifiers anywhere in the tree · a committed index.

Agent guidance

Following the layout the sibling repos use: CLAUDE.md pointing at AGENTS.md, .agents/skills/ holding the skills, and .claude/skills/ symlinking to them per skill.

Skill	Covers
architecture-records	The convention, the chicken-and-egg case, what the validator enforces
nextcloud-app-development	lib/ structure, constructor injection, routes, the preview provider, what must stay off the server
elpx-package-safety	Entry-path normalization as the security boundary, SW scope, iframe sandbox
testing	The Vitest/PHPUnit split, the fixtures, and what these suites structurally cannot prove
verify, release	The local pipelines
security-audit	Ported unchanged from the sibling repos

AGENTS.md gains an architecture-records section and a skills index.

Nothing here ships

tools, docs, .agents, .claude, AGENTS.md and CLAUDE.md are excluded in both .distignore and .gitattributes.

Verified rather than assumed — staged the package with the same rsync invocation make package uses:

$ rsync -a --exclude-from=.distignore ./ /tmp/nc-stage/
$ ls /tmp/nc-stage
appinfo  blueprint.json  img  lib  LICENSE  README.md  src  templates

No tools, no docs, no .agents, no .claude, no AGENTS.md, no CLAUDE.md, and no file matching *architecture*.

Commands run

Command	Result
make architecture-check	OK — 0 ADRs, 0 changes
make architecture-test	OK — 35 tests
npm run typecheck	exit 0
npm test	exit 0 — 6 files, 59 tests
make lint	exit 0
package staging (rsync)	only runtime paths present

vendor/bin/phpunit was not run: no PHP dependencies are installed in this environment. This change touches no PHP.

A finding, reported not fixed

While writing elpx-package-safety I compared the three entry-path normalizers. They do not agree, and the TS docblock claims they do.

Input	PHP ZipEntryService	TS paths.ts / SW
../escape	null	null
a/b/../c	null	a/c
a/./b	null	a/b
a//b	a//b	a/b

Not a traversal hole — both reject ../escape, neither escapes the package root. It is a consistency defect: a package containing a/b/../c renders in the browser but 404s from the PHP asset controller and the preview provider. The comment on normalizeEntryPath saying it "matches the rule used by the PHP-side ZipEntryService" is simply false, which is the part most likely to mislead.

Converging them changes behaviour at a security boundary, so it belongs in its own PR with its own ADR. Documented in the skill; not fixed here.

Follow-up

• Converge the three normalizers, with a shared test-vector table.
• The first real ADR for this repo should record the sandboxing/Service-Worker boundary, which is currently only described in prose.

[github-actions]

Preview this PR in the Nextcloud Playground

A fresh Nextcloud boots in your browser with this branch's exelearning app installed and enabled (log in as admin / admin). Two sample .elpx are seeded under exelearning-samples/ in Files — click one to open the viewer.

eXeLearning editor: v4.0.2 (overlaid at boot from the upstream release).