Workflow and Troubleshooting

ProjectAtlas is designed to run locally and produce a deterministic map.

  1. projectatlas init --seed-purpose (first-time setup).
  2. Add Purpose headers to new source files.
  3. Add or update .purpose summaries for new folders.
  4. Run projectatlas map.
  5. Run projectatlas lint --strict-folders --report-untracked.
  6. Open a PR that references the GitHub issue (CI requires #NNN in title or body).
  7. Commit map updates and any Purpose changes.
  8. Install git hooks with python scripts/install_hooks.py to enforce issue references in commit messages.
  9. The pre-push hook runs python scripts/check_all.py to validate map/lint/tests/build.

One-command local verification

Run the full local check suite with:

python scripts/check_all.py

Issue hygiene

  • Every issue should carry a type:* label plus a priority:* and status:* label.
  • Use status:backlog for unscheduled work.
  • Any issue referenced by a PR must be assigned to the target release milestone (CI enforces this).
  • Keep public issues/PRs/release notes free of private or internal-only details (release notes are generated from PR text).

Review expectations

  • At least one approval is required before merging.
  • Automated reviews (Codex/Copilot) should be checked via gh pr view <PR> --comments or gh pr view <PR> --json reviews.

Documentation site

  • 04-Docs publishes to the gh-pages branch using mkdocs gh-deploy.
  • GitHub Pages should be configured to serve from gh-pages.

Branching

  • dev for active development.
  • main for stable releases only.
  • Merge dev -> main via pull request after CI is green.
  • Ensure dev includes the latest main changes before releasing.
  • Use python scripts/prepare_release.py --issue <NNN> --bump patch to create a release branch and PR.
  • If dev is behind main, the script will stop unless you pass --allow-base-divergence.
  • Add --post-release to open a dev PR that bumps to the next .dev version.
  • Pushes to main create a GitHub release when the version is not a .dev build.
  • The auto-release workflow generates GitHub release notes from merged PRs.

CI behavior

  • projectatlas map skips in CI unless you pass --force.
  • projectatlas lint validates that the map is current.
  • PRs must reference a GitHub issue (scripts/check_pr_issue_reference.py).
  • CI can be run manually via workflow_dispatch when checks do not auto-trigger.

Environment toggles:

  • PROJECTATLAS_SKIP_UPDATE=1 skips map generation locally.
  • PROJECTATLAS_ALLOW_UNTRACKED=1 allows local builds while still reporting untracked files.

Troubleshooting

Map is stale

If lint reports stale hashes or an overview mismatch, re-run:

projectatlas map

The overview: line in the atlas now reports tracked_source_files, tracked_nonsource_files, and tracked_files_total so you can see the split at a glance.

Missing Purpose headers

Add a Purpose: header using the comment style configured for that file extension (Javadoc block, block comment, or line comment). For Python, use a module docstring. If the file uses a different style, update purpose.styles_by_extension in the config.

Missing .purpose files

Create a .purpose file in the folder and add a one-line summary. You can seed them with:

projectatlas seed-purpose

Untracked files

Use --report-untracked to list non-source files. Either:

  • add to the non-source file list (.projectatlas/projectatlas-nonsource-files.toon) (agent-maintained input for non-source summaries)
  • add to allowlists/exclusions
  • move into an approved asset root

Schema reference

The TOON schema is documented in docs/format.md.