Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,9 @@
*.pdf binary
*.docx binary
*.md text eol=lf

# The hook runs in a POSIX shell and the workflow on a Linux runner. CRLF
# would leave the hook with a bad interpreter line and unrunnable there.
.githooks/* text eol=lf
*.yml text eol=lf
*.py text eol=lf
38 changes: 38 additions & 0 deletions .githooks/pre-push
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
#!/bin/sh
#
# Run the bylaws conformance suite before anything reaches the remote.
#
# Install once, in your clone:
#
# git config core.hooksPath .githooks
#
# This is a convenience, not a gate. Hooks live outside the repository's
# history unless you run that command, and `git push --no-verify` skips them.
# The gate is the Conformance check on the pull request.

set -u

for py in python3 python py; do
if command -v "$py" >/dev/null 2>&1; then
PY="$py"
break
fi
done

if [ -z "${PY:-}" ]; then
echo "pre-push: no python interpreter found; skipping conformance suite" >&2
exit 0
fi

if ! "$PY" bylaws-conformance-suite.py; then
echo "" >&2
echo "Push blocked: the bylaws conformance suite failed." >&2
echo "" >&2
echo "A cross reference, a provision number, or the structure has drifted." >&2
echo "Fix it, or run" >&2
echo " git push --no-verify" >&2
echo "to push anyway - the pull request will fail the same check." >&2
exit 1
fi

exit 0
27 changes: 27 additions & 0 deletions .github/workflows/conformance.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
name: Conformance

# No paths filter, deliberately. This check is a required status check on main,
# and a required check that never runs leaves a pull request blocked forever.
# The suite finishes in well under a second, so running it on every pull
# request costs nothing and always reports.
on:
pull_request:
push:
branches: [main]

permissions:
contents: read

jobs:
conformance:
name: conformance
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: '3.x'

- name: Run the bylaws conformance suite
run: python bylaws-conformance-suite.py
98 changes: 98 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# Contributing

This repository carries P1-001, the bylaws of Network Theory Applied Research
Institute, Inc., and its translations. Two rules govern every change: **sign
your commits off**, and **keep the suite green**.

## Amendments go into the instrument

Propose a change by editing `P1-001_Bylaws_v1.0.md` and opening a pull request.
The diff is the proposal, and the board approves or rejects it in review. Do
not add proposal files or version-documentation alongside the instrument — git
history is the version record, and a parallel proposal document starts drifting
from the text it describes the moment it is merged.

Amendment itself is governed by Article XV. Nothing here overrides it; this
file describes how a change reaches the repository, not who may adopt one.

Prior instruments are archived in `Historical Docs/` rather than amended. The
version line restarts at 1.0 for the first instrument written to the Janus
Facing Architecture — see the header and §16.1.

## Sign-off (DCO)

Every commit needs a `Signed-off-by` trailer. The DCO check requires the name
and email in that trailer to match the commit author exactly, so let git add it
rather than typing it by hand:

```
git commit -s
```

If the check fails on an existing branch, add the trailer to every commit and
force-push:

```
git rebase HEAD~<n> --signoff
git push --force-with-lease
```

## The conformance suite

```
python bylaws-conformance-suite.py # check the instrument
python bylaws-conformance-suite.py --doc PATH # check another copy
```

Exit code 0 when every check passes, 1 otherwise. It runs on every pull request
as the **Conformance** check.

To catch failures before you push, install the hook once in your clone:

```
git config core.hooksPath .githooks
```

That is a convenience, not a gate — hooks are not distributed with a
repository, and `git push --no-verify` skips them. The pull request check is
what actually holds.

### What the suite constrains

The instrument carries 104 numbered provisions and 199 internal cross
references. Nothing about that is self-checking: renumber a provision and every
reference to it keeps pointing at a number that now means something else, or
nothing at all, and the breakage stays invisible until a reader follows one.

Edits fail the suite if they:

- drop, rename or reorder the preamble, the sixteen articles, or the appendix.
- leave a gap in the provisions inside an article. They run 1..n, and the
groups must match the article count — renumbering `9.10` to `9.99` fails.
- leave a section cross reference pointing at a provision that does not exist.
- leave a lettered sub-item reference — `§3.2(e)` — pointing at a sub-item that
does not exist.
- disagree with the filename about the version number.
- introduce an email address other than the organizational footer's.
- remove a translation, or the archived prior instruments.

### What it does not constrain

It checks that the instrument is internally whole. It does not check that a
provision is wise, lawful, or consistent with the architecture — those bind a
reader, not a parser.

In particular there is **no invariant registry yet**. The JFA suite binds prose
to registered invariants with stable IDs, so the document and the registry
cannot drift apart without a check failing. The equivalent here would bind
provisions to the architecture's lines — §9.10(a) to the privacy floor, §1.4(a)
to stewardship of the document, and so on. That requires deciding which
provisions are load bearing, which is a governance judgment rather than a
mechanical one, and is deliberately left for a later change.

## Translations

The English instrument is authoritative; translations are for reach, not
interpretation. The suite checks that all seven are present, not that they say
the same thing. If you amend the English, say in the pull request whether the
translations should be updated before the change is adopted or after.
Loading
Loading