Specifications

Actions

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The model is simple: the build system is intelligent, and CI orchestrates it. A composite action exists because an orchestration pattern is reusable — check out, set up credentials, call a command, pass an output along — even when the work underneath remains entirely repository-owned.

FlowPromotion path

01 Inline steps A few steps in one workflow file Workflows
02 Composite action Repeated or growing steps get a name, inputs, and outputs under .gitea/actions/
03 Shared tooling Actions that stabilise and prove broadly useful move out of the repository

Not every promotion goes through an action. When the repeated thing is logic rather than orchestration, it moves down into a script or make target instead, where it can be run outside CI.

Authoring specifications

Mon, 01 Jan 0001 00:00:00 +0000

Adding a specification#

A specification is a page bundle under www/specifications/content/specs/. The directory name is its slug and its address: specs/catalog-descriptors/ is published at /catalog-descriptors/, which is where owner documentation links to it.

hugo new --source www/specifications specs/my-specification/index.md

The archetype lists every front matter key with a comment. Drop an icon.svg beside index.md to give the specification its own mark — usually the icon of the repository area it describes. Without one, the library generates a sigil from the slug, so every specification still has a stable identity.

Automation & CI/CD

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Gitea Actions runs YAML workflows on runners in response to repository events. This folder holds those recipes, but it deliberately holds very little else. The repository’s behaviour is implemented once, behind its Command Surface , and automation calls it the same way a developer would.

FlowWhere automation work lives

01 Event A push, pull request, tag, schedule, or dispatch triggers a workflow Workflows
02 Orchestrate The workflow orders jobs and calls shared steps Actions
03 Execute Steps invoke make validate, make build, make release Command Surface
04 Implement Make modules and scripts do the actual work Scripts

Because every layer below the workflow is available outside CI, a failure on a runner can be reproduced locally with the same command, and a change to how something builds is made once rather than in each workflow.

Catalog Descriptors

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

A repository may publish a static website, expose an API, and provision a database. All three could in principle be discovered by reading source files, infrastructure definitions, and deployment configuration, but only by a consumer that understands every one of those systems and can infer how they relate.

A catalog descriptor removes the inference. It states that the resources exist and says where their definitions are. Consumers follow the reference to the source of truth rather than relying on a copy.

Code Map

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The code map is the first page to open and the shortest route to the right second page. It is organised in three layers, each more specific than the last, and every layer hands off to owner documentation instead of growing its own detail.

FlowReading the code map

01 Structure An annotated tree of the shape the conventions expect
02 Quick Lookup One line per concern: Static Websites → www, Command Surface → Makefile
03 Area sections A short paragraph on what the area is for, then “Read:” links
04 Owner documentation The area’s own README.md carries the rules and detail Owner Documentation

Because it is generated from the repository structure, the code map changes when the tree changes. That is what keeps it from drifting: a hand-written map is the first document to fall out of date when areas are added or removed.

Command Surface

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The command surface is what a developer or workflow actually types: make doctor, make build, make validate, make lint, make deploy. Behind it, the root Makefile does only three things — it finds the repository root, reads repository.mk, and includes each module in a fixed order.

FlowHow make assembles the surface

01 Root REPO_ROOT from the Makefile’s own location
02 Configure Include scripts/build/repository.mk
03 Resolve For each name in MAKE_MODULE_ORDER, the first <name>.mk across the library and repository directories
04 Include Load the resolved modules in order Make Module Registries

How the modules then contribute targets without editing each other is the Make Module Registries pattern.

Decision Records

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Most decisions in a repository are already written down — in the shape of the tree, in a make module, in a workflow, in a test. A decision record that restates one of those becomes a second source of truth that can drift. So the default is to express a convention where it lives, and to reach for a record only when that is not enough.

Derived Developer Identity

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Every developer needs their own copy, but nobody wants a directory per developer. The convention resolves this by deriving identity from context that already exists. Locally that is your username; in CI it is the branch name; when you want more than one copy, it is whatever you set DEPLOY_WORKSPACE to.

The deployer turns that name into a Terraform workspace, and the root reads it back as terraform.workspace. From there, one value flows into the state path, the hostname, and the resource tags, so two instances can never collide.

Devcontainer Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The image and its features provide reusable tooling. The lifecycle layer provides everything specific to this repository: linking command wrappers, configuring the shell, restoring dependencies, and running lightweight startup checks. A freshly rebuilt container, lifecycle included, should be ready for development without any manual bootstrapping.

LifecycleFrom rebuild to development session

host · may repeat initializeCommand Prepare host-side files a mount or build expects
once on create onCreateCommand Container-local state later phases consume
on content sync updateContentCommand Restore dependencies from lockfiles and manifests
once after create postCreateCommand Last-mile workspace bootstrap
every start postStartCommand Fast checks and lightweight services
every attach postAttachCommand Human-facing guidance and auth prompts

Restart containerpostStartCommand
Detach and reattachpostAttachCommand
Rebuild containerinitializeCommand

Between the hooks, the Dev Containers tooling builds the image, installs features, creates the container, and starts it. The hooks never replace those steps; they only add to them.

Development Container

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The development container is responsible for the environment; the repository’s commands only use it. Developers are not expected to run a separate bootstrap step to install tools after the container is built — if a tool is needed, the container provides it.

The definition is layered. A small base image sets the operating system and primary runtime. Devcontainer features add reusable capabilities on top. The Devcontainer Lifecycle adds the last, repository-specific layer.

Environment Doctor

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The Development Container is responsible for provisioning the tools. The doctor is how anyone checks that it did. It walks three registries, reports each entry, and only then exits — with status 1 if anything was missing.

Environments

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

env/ answers the question “what can be deployed?”. Each directory beneath it is a root that a deployment system can point at and run, and each one stands for a real target — production, a non-production tier, a variant. Reading the tree tells you the full set of canonical deployments without opening any file.

A root is wiring, not implementation. It names a module, supplies a domain, a backend, and credentials, and exposes the outputs a deployer needs. The infrastructure pattern itself lives in a module, local or published, so the same pattern can back every tier. See Pinned Module Composition .

Explicit Skips

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Repository commands are written to run wherever the repository is checked out. Some of what they cover is optional: a linter that is only installed in the dev container, a link checker the repository may not have, Terraform roots that may not exist yet, a plugin download that needs the network. Rather than fail on the first absent piece, or silently do nothing, each step announces that it did not run.

Fingerprinted Cache Tiers

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

A fingerprinted file’s URL is derived from its content, so a given URL always means the same bytes and can be cached forever. An HTML page’s URL stays the same while its content changes, so it must be checked on every request. The upload encodes that difference in two passes over the same public/ tree.

FlowTwo upload passes

01 Immutable pass --exclude '*' --include '*.min.*.css' --include '*.min.*.js' with a one-year, immutable header
02 Revalidate pass Every file, with max-age=0, must-revalidate, and --delete
03 Invalidate /* clears edge copies of the unhashed files

Files	`Cache-Control`
`.min.<hash>.css`, `.min.<hash>.js`	`public, max-age=31536000, immutable`
Everything else	`public, max-age=0, must-revalidate`

Files the first pass has just uploaded are already identical at the destination, so the second pass skips them and they keep their long header. Its job is to give every remaining file the short header and to prune keys the new build no longer produces.

Initialize Phase

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

initializeCommand is the only phase that runs outside the container. It runs before the image is built and the container is created, and the Dev Containers tooling may run it again on later rebuilds. That makes it the narrowest phase: it exists so that host-side paths are in place when the container definition refers to them, and for nothing else.

If a task needs the container shell, the mounted workspace, or a tool the environment provides, it belongs in On-Create Phase or later.

Issue Plan Tree

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

A plan starts as files. gitea-planner reads the tree and mirrors it into Gitea: reserve claims milestone IDs and issue numbers, and sync pushes titles, states, labels, assignees, dates, bodies, and dependency edges. Two things make a plan file good — it is structurally valid, or it will not sync, and it is readable, because the body is what someone actually works from.

LifecycleFrom draft to synced

while planning Draft Slug-only names; no id or number; title and state: open
on `reserve` Reserved Gitea assigns milestone IDs and issue numbers
on `sync` Synced Names carry the 4-digit prefix; front matter and edges are mirrored
on `pull` Pulled Remote state, including numeric depends_on, is written back to disk

Edit and re-syncSynced

A template set uses exactly the same layout as a live tree, in draft mode, so a reusable plan can be copied in and reserved like any other.

Lint Gate

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The gate is written so that it works anywhere. A small run helper checks whether the linter’s command exists; if not, it prints a skip: line and moves on. If it does, the linter runs and any failure is recorded, not raised, so the remaining linters still report.

FlowOne run of the lint gate

01 Locate cd to the Git top level
02 Collect files Tracked and untracked-but-not-ignored *.sh, *.md, *Dockerfile*
03 Run linters ShellCheck, MarkdownLint, Hadolint, shfmt, Actionlint, EditorConfig, Codespell Explicit Skips
04 Prettier npm run format:check when node_modules/.bin/prettier exists
05 Terraform make check.terraform.fmt check.terraform.lint
06 Report Lint PASSED, or Lint FAILED and exit 1

A linter is skipped only when it is missing. When there are no files of a type — no Dockerfiles, say — that linter is not invoked at all.

Linter Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Linters conventionally scatter dotfiles across the repository root. Here they are gathered into one directory, so the root stays focused on the repository’s own structure and the lint setup is visible in one place.

Configuration is layered. The organisation’s defaults travel with the Development Container and the CI/CD tooling; files in .linter/ contain only what this repository changes. Each tool is told where to find its file — --config .linter/.markdownlint.json, -config-file .linter/actionlint.yaml — instead of discovering it at the root.

Make Module Registries

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The root Makefile is identical in every repository. It includes the repository’s configuration and then a fixed sequence of numbered modules. Each module is self-contained: it defines its own targets and registers them by appending to shared lists. No module edits another.

FlowAssembling the command surface

01 Configure repository.mk declares components; 00-config.mk initialises empty registries
02 Register Each module appends: BUILD_TARGETS += check.hugo, DOCTOR_TOOLS += terraform
03 Aggregate 90-aggregates.mk is read last, so build: $(BUILD_TARGETS) sees every registration
04 Run make build, make validate, and make clean cover whatever modules are present

Managed Standard Files

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Some files express a convention that should read the same everywhere. Copying them by hand guarantees drift, so an external tool owns them: it writes them into each repository and overwrites them when the standard changes. The header tells a reader, before they start editing, that this is not the place to make the change.

FlowChanging a managed file

01 Notice the header DO NOT EDIT on the first line marks the file as managed
02 Find the source Change the standard file in the tool that manages it
03 Propagate The next update rewrites the file in every repository
04 Keep local values local Anything repository-specific goes in the file the standard delegates to

Modules

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

A module is the part of the infrastructure that does not care where it is deployed. It knows how to build a thing — a bucket and its distribution, a secrets store, a network — and it asks the caller for everything that differs between targets: the domain, the tags, which providers to use.

Roots supply those answers. Because a module makes no assumptions about tier or account, the same module can sit behind production and behind every developer’s own copy, and a fix made once reaches all of them.

Offline Validation

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Validation is most useful when it is reproducible: the same inputs give the same result, and nothing changes underneath it mid-run. A target that re-runs terraform init or tflint --init as a side effect quietly depends on the network and on whatever the registry serves that minute.

The repository separates the two concerns. Getting dependencies onto the machine is setup — the dev container’s lifecycle hooks locally, a prepare phase in CI. Validation then runs against the hydrated workspace, and OFFLINE=1 tells every module that the network is off-limits.

On-Create Phase

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

On-create is the first phase inside the container. Its job is to lay down container-local state — things that live under $HOME or in tool configuration — so that the repository-driven phases that follow find them in place.

The distinction from Update-Content Phase is the input. On-create work depends on the container; update-content work depends on the repository’s files. A Terraform plugin cache directory is on-create; terraform init against the checked-in roots is not.

Owner Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

A reader who opens a directory is already looking at the thing they want to understand. Owner documentation meets them there. The README beside the files says what the area is for, what belongs in it and what does not, and the handful of rules that keep it coherent. Moving or deleting the area takes its documentation with it.

The same principle applies below the directory level. A make module explains itself in its header comment, a script in its usage line, a workflow in its file header. The decision-record guidance lists these owners explicitly and asks for a separate record only when none of them can carry the explanation.

Parameterless Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

If a deployment needs someone to remember a flag, it is only as reliable as that memory. Canonical roots avoid the question entirely: every value they need is written down in the repository or looked up from a well-defined source, so the only thing a deployer has to know is which directory to run.

That is what lets one generic deployer drive every root. It does not carry per-environment knowledge; it runs terraform init, apply, and reads outputs using the same commands everywhere, with -input=false so a missing value fails loudly instead of prompting.

Pinned Module Composition

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The repository deploys one static website to several places. Rather than describe that website’s infrastructure several times, it describes it once — the S3 bucket, CloudFront distribution, ACM certificate, and DNS records — as a published module, and gives each environment a root that does nothing but call it.

Because every root runs the same module at the same version, the pattern lives in exactly one place and every environment is the same deployment. A change tested in a developer’s copy is the change production will get, because there is no second implementation for it to diverge from.

Post-Attach Phase

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Post-attach is the last phase and the only one aimed at a person. It runs on every attach, including reattaching to a container that has been running for days, so it says what is useful now and gets out of the way.

The repository stays usable without it. A container that is started and never attached — by automation, for example — has everything it needs from the earlier phases; post-attach only adds guidance on top. Anything that has to happen for the session itself belongs in Post-Start Phase .

Post-Create Phase

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Post-create is the final creation-time phase. By the time it runs, the container exists, the content is synchronised, and dependencies are restored. What remains is wiring the workspace together so it is ready for development.

The line with Update-Content Phase is about purpose rather than timing. Update-content reacts to repository content and may rerun when it changes; post-create configures the workspace once, using whatever is now in place.

Post-Start Phase

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Post-start is the first phase that repeats in normal use: restarting the container returns here without passing through creation again. Everything in it pays that cost on every start, so it holds only work that is cheap and that has to be true for the session to work.

It differs from Post-Attach Phase in audience. Post-start runs for the container whether or not an editor ever connects; post-attach runs for a person who has just arrived. Services and runtime repairs belong here; prompts and guidance belong there.

Product Development Life Cycle

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Most of a repository explains what and how. The PDLC directory explains why, and is written to stay true for a long time. A reader opening it should learn what the repository is for, what went wrong when it lost its way, and which constraints any change should respect — without wading through the history of how each decision was reached.

The README calls these files the cornerstone of the repository: they are the reference point other documentation, structure, and code are measured against.

Reference Over Duplication

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Every copy of a fact is a promise to keep two places in step. Promises like that are broken quietly: one file is updated, the other is not, and a reader can no longer tell which is current. The repository avoids making the promise. A fact lives with the thing that owns it, and everything else links.

FlowResolving a fact

01 Index The code map, a descriptor, or a summary names the thing Code Map
02 Reference A link or path points at its owner
03 Source of truth The owner — a README, a make module, a Terraform root, an API definition — holds the detail Owner Documentation

What drift looks like#

The problem statement for this repository lists the symptoms of losing this discipline. Human-facing docs, the generated code map, and the actual layout drifted apart. It became hard to tell which files were externally managed, which were repository-specific, and which were meant to be reused. The conclusion: a repository cannot be a trustworthy reference “if readers must reverse-engineer which source of truth is current.”

Release Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The same three stages run at every point a change passes through. What changes from stage to stage is only where the output is published: nowhere locally, to an edge or staging location on a pull request, and to production on merge.

FlowOne pipeline, every stage

01 Build Produce the artifact or site from source
02 Test Exercise it with the same logic CI runs
03 Publish Push the output to the location this stage targets

Running that pipeline three times is the point. A pull request that already built, tested, and published to an edge location has rehearsed most of the release, so merge is a promotion rather than a first attempt.

Run-Parts Hook Directories

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

The name comes from the classic Unix run-parts utility, which runs every script in a directory. Here the directory is chosen by event: post-start resolves to post-start.d/, on-create to on-create.d/, and so on. Adding a hook is adding a file; the devcontainer.json command never changes.

FlowOne invocation of run-parts.sh

01 Check arguments Exactly one non-empty event name, or usage text and exit 1
02 Resolve directory <event>.d/ beside the runner; missing directory exits 1
03 Announce Running lifecycle event: <event>
04 Run hooks Each *.sh in lexical order, as bash <script>, after ==> Running <name>
05 Finish Report No lifecycle scripts found when the glob matched nothing

The canonical event names are initialize, on-create, update-content, post-create, post-start, and post-attach, one per phase of the Devcontainer Lifecycle . The runner enforces them through the directory check: an event with no matching directory is refused.

Scripts

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

A script exists because something does not fit comfortably in a make recipe. It gives that behaviour a name and an entry point, but it does not take over decisions that belong to its caller. The make module decides that Terraform roots are $(TERRAFORM_DIRS); the script works on whatever it is handed.

That narrowness keeps scripts predictable. Run twice with the same arguments and environment, a script does the same thing, because it does not reach for ambient repository state or set up its own prerequisites along the way.

Self-Documenting Help

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

There is no hand-maintained list of commands. The help target runs awk over every makefile that make has loaded and picks out two kinds of line: section headings that start with ##@, and rule lines that end in ## description.

FlowFrom comments to help

01 Annotate A module writes doctor: ## Verify required tools ...
02 Load Make records every included file in MAKEFILE_LIST
03 Scan awk prints ##@ lines as headings and target: ## text as entries
04 Print HELP_START banner, then each section in load order

Because the source of the listing is the makefiles themselves, adding a module adds its section, and deleting one removes it. The help composes the same way the Make Module Registries do, without a registry of its own.

Staged Content Mounts

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Documentation under docs/ is written as ordinary Markdown for people reading the repository. A Hugo site wants front matter and a content tree. Rather than make the documents serve both masters, a small script stages a Hugo-ready copy and the site mounts it.

FlowFrom docs/ to a published page

01 Author Edit Markdown in docs/, where it is owned Owner Documentation
02 Stage prepare-site-content.mjs writes .cache/docs-site/content/<path> with front matter
03 Mount [module] mounts place the staged tree at content/repository
04 Build check.hugo renders it alongside the site’s own content Static Websites

The mount, not the script, decides where the pages appear. The script only knows about docs/ and .cache/; the site decides that repository documentation is published beneath /repository/ so it cannot collide with library pages.

Static Site Delivery

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Deployment is five steps, and make deploy is all five. They live in one script that is short enough to read before running it, and the make targets are one-line wrappers that pass ENV through.

Flowmake deploy

01 Build make check.hugo renders every site into public/ Static Websites
02 Init terraform init -input=false in the selected root
03 Apply Provisions the S3 bucket, CloudFront distribution, ACM certificate, and DNS records Pinned Module Composition
04 Upload Two aws s3 sync passes with different Cache-Control headers Fingerprinted Cache Tiers
05 Invalidate create-invalidation --paths '/*' on the distribution

plan and destroy stop after init (and workspace selection): plan prints the change set, and destroy removes everything, bucket contents included, because the stack bucket sets force_destroy.

Static Websites

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

www/ is a logical grouping, not a site. Every child directory is a complete site root: point a static site generator at it and it builds, with nothing borrowed from a sibling. That keeps each site understandable on its own and lets a site be moved, renamed, or deleted without breaking another.

The make module for Hugo turns the declared sites into one output tree. The first site in HUGO_DIRS owns the root of public/; every later site is nested beneath it under its own directory name.

Tools

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

A tool owns a workflow. Where a script runs a few existing commands in a particular order, a tool defines what it accepts, what it produces, and how it gets from one to the other — and that definition is what callers depend on.

Because callers depend on it, the entry point is treated as stable. The implementation behind it can change language, structure, or dependencies; the command and its contract stay put.

Update-Content Phase

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

Update-content is where the repository’s own files start to matter. It runs once the workspace content is available, and may run again when that content is refreshed during creation or prebuilding. Because the work is a function of the checked-in files, rerunning it after a content change brings the workspace back in line.

It sits between two easily confused neighbours. On-Create Phase prepares the container before content matters; Post-Create Phase finishes the workspace once everything is in place. Update-content is the step that responds to the content itself.

Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

A workflow answers three questions: when does automation run, how are its jobs ordered, and which commands or actions does each step invoke. Anything beyond that — how the site builds, how a scanner is configured, how a bucket is uploaded — belongs to the repository, where it can be run and tested without a runner.

FlowPhases of a primary CI workflow

01 Validate make validate, make lint, make test on every pull request
02 Package make build / make package produce the artifact
03 Publish Artifacts go to a CI, edge, or staging location Release Pipeline
04 Deploy Only where the repository has something to deploy Static Site Delivery

The pull request path and the main-branch path should look alike. If a check only runs after merge, a pull request can be green while main breaks; keeping event differences narrow is what makes the pull request result trustworthy.

Workspaces

Mon, 01 Jan 0001 00:00:00 +0000

Behaviour#

env/ holds the deployments that matter to everyone. workspaces/ holds the ones that matter to a single person or branch for a while. Both compose the same reusable modules, so a developer’s copy is built the same way production is; the difference is how the instance is named and who owns it.

A workspace root is still committed, reviewed configuration. What it adds is permission to depend on context: the Terraform workspace, the current user, a branch name, an environment variable. That context decides the instance’s identity — its hostname, its state, its resources — and nothing else.