Contributing#
This page tells you how to make a change to ADVISOR, what rules the change must keep, and what work is still open.
Where changes go#
Development happens on git.wayne.edu, the canonical repository: enterprise-apps/advisor (clone git@git.wayne.edu:enterprise-apps/advisor.git over SSH, or https://git.wayne.edu/enterprise-apps/advisor.git over HTTPS). Changes, issues and merge requests go there, CI runs there on its instance runner, and tags are made there by the maintainer, with an approver. GitHub (waynestate/advisor) is a read-only push mirror of git.wayne.edu for Packagist: nobody pushes to it.
Build and test#
| Task | Command |
|---|---|
| Install | composer install |
| All checks (what CI runs) | composer ci |
Regenerate data/ from the stack repos |
php bin/advisor content:generate --sources=<folder holding the stack repos> |
Check data/ against the repos |
add --check to the line above (exit 1 on drift) |
Check data/ against its manifest |
composer content:verify |
| Regenerate the parts table in the README | php bin/advisor stack-parts --write=README.md |
| Diagnose a client setup | php vendor/bin/advisor doctor (in an app) |
composer ci runs composer validate --strict, content:verify, stack-parts --check=README.md, PHPUnit, Pint, the agent-ready check, PHPStan, composer audit and the docs site check (composer docs:check). CI cannot see the sibling repos, so it verifies the manifest; regenerating is a local step.
With only Docker:
docker run --rm -v "${PWD}:/app" -v stack-composer-cache:/tmp/cache -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh -c "composer install --no-interaction && composer ci"
Snapshot tests are updated with ADVISOR_UPDATE_SNAPSHOTS=1 ($env:ADVISOR_UPDATE_SNAPSHOTS = "1" in PowerShell) before vendor/bin/phpunit. The same run rewrites the front page's field book readouts (site/assets/readouts.json) from the real tools; the readouts test fails only when a call on the map is missing, refused, or changes shape, so a content resync does not need it.
Rules a change must keep#
Every change to ADVISOR must keep the following practices:
- Read-only first. Every tool states all four hints (read-only, destructive, idempotent, open-world). A tool that writes is left out unless
ADVISOR_READ_ONLYis turned off, and that switch beats tool groups. Enforced (contract test). - Narrow tools, closed schemas. No tool takes a command, a URL or a free path. Schemas set
additionalProperties: false, and arguments are validated again on our side. Enforced (contract test). - Run other programs the safe way. Fixed program, argument array, allowlisted environment, a timeout, and no shell. Paths are resolved and must stay inside the project root. Enforced.
- Keep stdout clean. Only protocol lines go to stdout; logs, warnings and stray output go to stderr. Enforced (subprocess test).
- Strip invisible characters. The TAG block, zero-width and bidirectional controls are removed from everything served and rejected in tool metadata. Enforced (contract test).
- Load modules from a manifest only, from the
Waynestate\namespace, implementingModule. Never scan. Enforced. - Serve from verified data. Bundled content is checked against a SHA-256 manifest at start-up and in CI; a mismatch stops the server. Enforced.
- Review any change to the tool list.
tools/listis snapshotted; a changed description is a reviewed diff. Enforced (snapshot test). - Cite sources and date. Policy answers carry the day they were worked out for and the file they came from. Enforced.
Keeping the content fresh#
Run content:generate after any change that lands in CREED's policy or handbook, a project's README or best practices, an extra doc, or the projects seed. Commit the regenerated data/ with the source commits in the message. To add a project to the parts list, add its name and tagline to generator/projects.seed.json, then regenerate and stack-parts --write.
Beyond a project's README and best practices, a seed may bundle further files under extra_docs (a map of slug to path in the project); each lands in data/docs/<id>/<slug>.md and in the project's docs list, and a missing file is skipped, not an error. WayneUI's entry bundles its MIGRATING.md as the migrating doc.
Hand-written guides live in generator/guides/, one Markdown file per slug, served as advisor://guide/<slug>. Edit them there, then run content:generate.
Catch stale bundled docs#
composer content:drift compares data/ with a checkout of the stack repos and exits 1 when they no longer agree. It takes the folder from ADVISOR_STACK_DIR; without it, it prints how to run it and exits 1:
ADVISOR_STACK_DIR=<folder holding the stack repos> composer content:drift
It writes nothing. On drift it lists the files that moved; regenerate with composer content:generate and review the diff before committing.
Run the drift check before every tag: a release must carry docs that still match the repos it advises on.
Releasing#
ADVISOR is public, so its bundle must not carry internal names. The public-posture test always checks generic shapes; private strings are loaded from a denylist file named by ADVISOR_PRIVATE_DENYLIST, kept outside the repository (in CI, a masked file-type variable).
- Move the lines under
## [Unreleased]inCHANGELOG.md(Keep a Changelog) to a new## [X.Y.Z] - YYYY-MM-DDheading. - With the denylist file present, regenerate:
php bin/advisor content:generate --sources=<stack folder>, thencomposer ci(the public-posture test must pass). - Both pipelines green for that commit. Run a secrets scan of the history.
- Tag
X.Y.Z(nov) on git.wayne.edu. Its push mirror carries the tag to GitHub, and Packagist picks it up from there. - A release needs a maintainer's approval. Never move or delete a published tag.
Open work#
The following items are open questions or not yet built:
- A recorded green run on a native Windows PHP. The GitHub
native-osworkflow runsadvisor doctorand the stdio tests on Windows and macOS on every push to main; this line goes when its first green run is recorded. The MCP Inspector in CI is not added (open question 7). - Signing of any state handed back to a client (no tool needs it yet).
- A full-capture audit mode (the threat model mapped to OWASP and NIST is done: see
BEST_PRACTICES.mdand the threat pages). - "Ask ADVISOR" web chat: needs a model, an open stack question and an accessibility pass of its own.
- HTTP transport and OAuth: stdio first; remote needs a threat model of its own (the one in
BEST_PRACTICES.mdcovers stdio only). - Tools that write (scaffold with Sourdough, apply a Booster step): the approved list is read-only; the read-only switch and tool groups are built so they can arrive safely.
- Per-project modules in their own repositories: the loader and
Moduleinterface exist and are tested; the other projects have not published modules. - WarriorGPT-backed features: no model calls until an open stack question is settled.
- Plan handles,
requestStatesigning and elicitation: no tool needs state or a question to the user yet. - Full-capture audit mode: hashes only by default; an opt-in needs a retention decision.
- MCP Inspector in CI, and the full suite on Windows and macOS (the
native-osworkflow runs doctor and the stdio tests there).