# Golden Rules: Architecture Manifests and Portable Audit Tools

## Purpose

These rules govern the Websites system architecture, its JSON manifest, and the read-only audit tools that compare `websites/system/` and `websites/apps/<appname>/` against that standard.

## Architecture ownership

1. `websites/system/` is shared platform infrastructure.
2. `websites/apps/` contains independently deployable application roots.
3. Each application has exactly one root: `websites/apps/<appname>/`.
4. The system manifest is owned by `websites/system/policies/`, not by individual applications.
5. Applications may request changes to the standard, but changes require review of representative apps before they become mandatory.

## Manifest rules

1. The JSON manifest is the architecture standard; the shell audit is only the evaluator.
2. Change directory requirements, naming policy, exclusions, and component limits in the manifest—not by editing shell logic for one app.
3. Validate a changed manifest before use:

```sh
python3 -m json.tool architecture.manifest.json >/dev/null
```

4. Use three levels for directories:

```text
required     Missing item is FAIL.
recommended  Missing item is WARN.
optional     Absence is not reported as a failure.
```

5. Mark a directory `forbidden` only after a clear ownership decision. Do not forbid a directory merely because it was absent from an early draft.
6. Keep legacy exceptions explicit, visible, owned, dated, and reviewable.
7. Never silently weaken the global standard for one application. Use a policy overlay/registry exception with reason, owner, review date, and migration target.

## Naming rules

1. Application names use lowercase letters, digits, and underscore only.
2. Directory names use lowercase letters, digits, and underscore only.
3. File base names use lowercase letters and digits only; the final extension dot is allowed.
4. New names must meet the standard immediately.
5. Existing legacy names are warnings during transition; do not bulk-rename without reference review and a tested migration plan.

## Public/private rules

1. Web servers expose intentional public routes and public assets only.
2. Source, configuration, tests, include fragments, runtime storage, backups, and vendor code are private by default.
3. Nginx production policy belongs in Nginx/hosting configuration. Do not rely on `.htaccess` in Nginx deployments.
4. A route returning 200 for an internal include fragment is a FAIL.
5. A timeout, WAF response, or 5xx response is an ERROR, never proof of protection.

## Component ownership rules

1. Exactly one active application template owns `.app-wrapper`.
2. Page/include fragments must not create `.app-wrapper` or `.app-main`.
3. Global header, sidebar, footer, modal, and toast each have one markup owner.
4. Legacy demos, backups, and examples belong outside active served roots or must be explicitly classified.

## Portable shell rules

1. System audit scripts must be POSIX `sh` compatible unless Bash is explicitly required and documented.
2. Start portable scripts with `#!/bin/sh`.
3. Use `set -eu` carefully.
4. Do not use Bash-only `[[ ... ]]`, arrays, `mapfile`, `BASH_SOURCE`, or process substitution.
5. Do not use optional false tests with `&&` in a `set -e` script:

```sh
# Unsafe under set -e
[ -n "$value" ] && do_work
```

Use:

```sh
if [ -n "$value" ]; then
    do_work
fi
```

6. Use `printf`, not `echo -e`.
7. Quote expansions unless deliberate word splitting is required.
8. Use `trap` to remove temporary files.
9. Audit tools are read-only by default.
10. Never build shell commands from browser input, arbitrary paths, globs, or URLs.

## Audit result rules

```text
PASS   Verified requirement is satisfied.
WARN   Review, recommendation, or documented transition issue.
FAIL   Verified required rule is violated.
ERROR  The audit could not reliably establish a result.
```

A PASS is not a security-compliance certification. It only means the specific declared rule was verified by the tool.