Adds the documentation a new session needs: AGENTS.md (read-first contract), docs/OBJECTIVES.md, ROADMAP.md, STATUS.md, ARCHITECTURE.md, DEVELOPMENT.md, CONTRIBUTING.md, GIT-WORKFLOW.md and CHANGELOG.md. STATUS.md records an honest implemented/unit-tested/VM-verified matrix and known limitations.
3.2 KiB
Git workflow and public-repository migration
What is tracked
Tracked: source (installer/, installer-rs/crates/, scripts/, .githooks/),
Cargo.toml/Cargo.lock, documentation (docs/, AGENTS.md, README.md,
installer/doc/, installer-rs/README.md), installer configs and tests.
Ignored (see .gitignore): the reference ISO and other images, installer-rs/target/,
__pycache__, .agent-shell/ transcripts, and any secret material
(*.pw, *.key, *.pem, credentials).
One-time migration (already performed)
cd /path/to/phoebus_os
git init -b main
git add -A
git commit -m "chore: import Phoebus OS installer and Rust migration"
# ... further commits for docs and tooling ...
git config core.hooksPath .githooks # enable the committed hooks
Then connect the public remote and push:
git remote add origin <PUBLIC_REPO_URL>
git push -u origin main
scripts/publish.sh performs the push after re-running the checks. It takes the
remote and branch as arguments:
scripts/publish.sh origin main
The remote URL is intentionally not hard-coded. Add it once with
git remote add origin <URL>and every laterscripts/publish.shuses it.
Ongoing loop for a work session
read AGENTS.md
-> inspect docs/ROADMAP.md and git log
-> implement the smallest correct change
-> run the quality gates
-> update docs/CHANGELOG.md and docs/STATUS.md
-> commit (conventional message)
-> push
An AI session must commit the work it does. The one-line helper:
scripts/agent-commit.sh "feat(rust): add typed SystemAction broker
Adds a closed action schema and a privileged broker. Verified with
cargo test --workspace."
agent-commit.sh refuses to commit if the secret scan finds a credential or if
a staged file is too large, then runs the fast tests.
Hooks
.githooks/pre-commit (enabled with git config core.hooksPath .githooks):
- scans staged files for secrets (
scripts/check-secrets.sh); - blocks staged
*.iso,*.qcow2and files larger than 5 MiB; - runs the fast Bash test suite.
Bypass for a genuine emergency with git commit --no-verify, or set
SKIP_PHOEBUS_HOOKS=1. Set PHOEBUS_PRECOMMIT_RUST=1 to also run
cargo test --workspace in the hook.
Branching and releases
- Trunk-based:
mainis always green. Short-lived branches are fine for risky work; merge with a conventional merge/squash. - Releases are annotated tags
vX.Y.Zwith the manifest produced byphoebus-release. Never replacelatest.isountilphoebus-release verifypasses. - Never rewrite published history (
push --forcetomainis forbidden). Fix mistakes with a newfix:commit.
Secret policy
- Never commit passwords, LUKS passphrases, API keys or tokens.
- Secrets are supplied at runtime through 0600 files or stdin and registered with the redactor.
- The pre-commit scan is a safety net, not a licence to be careless.
What a future session should do
git log --oneline -20andhead docs/CHANGELOG.mdfor context.- Work as described in
AGENTS.md. - Before committing:
scripts/check-secrets.shand the test gates. - Commit with
scripts/agent-commit.sh(orgit commit), thenscripts/publish.sh. - Confirm
git statusis clean and the push succeeded.