project-handbook 0.0.1__tar.gz

project_handbook-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff check .
+
+      - name: Test
+        run: |
+          pytest -q
+
+      - name: Build
+        run: |
+          python -m build

project_handbook-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Docs (GitHub Pages)
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build MkDocs site
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install mkdocs
+          mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+

project_handbook-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,100 @@
+name: Release (PyPI)
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing git tag to release (e.g. v0.0.1)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Needed for workflow_dispatch + tag ref checkouts.
+          fetch-depth: 0
+          ref: ${{ inputs.tag != '' && inputs.tag || github.ref }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches version
+        env:
+          TAG: ${{ inputs.tag != '' && inputs.tag || github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+          
+          tag = os.environ["TAG"]
+          m = re.fullmatch(r"v(?P<version>[0-9]+(?:\.[0-9]+){2}(?:[a-zA-Z0-9\.\-_]+)?)", tag)
+          if not m:
+              raise SystemExit(f"Tag must look like vX.Y.Z (got {tag!r})")
+          tag_version = m.group("version")
+          
+          pyproject = tomllib.loads(Path("pyproject.toml").read_text("utf-8"))
+          project_version = pyproject["project"]["version"]
+          if project_version != tag_version:
+              raise SystemExit(f"pyproject.toml version {project_version!r} != tag {tag_version!r}")
+          
+          init_text = Path("src/ph/__init__.py").read_text("utf-8")
+          mm = re.search(r'__version__\s*=\s*"([^"]+)"', init_text)
+          if not mm:
+              raise SystemExit("src/ph/__init__.py missing __version__")
+          init_version = mm.group(1)
+          if init_version != tag_version:
+              raise SystemExit(f"src/ph/__init__.py __version__ {init_version!r} != tag {tag_version!r}")
+          
+          print(f"OK: tag={tag_version} matches pyproject + src/ph/__init__.py")
+          PY
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check --strict dist/*
+
+      - name: Smoke test wheel
+        run: |
+          python -m pip install dist/*.whl
+          ph --help >/dev/null
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/') || (github.event_name == 'workflow_dispatch' && inputs.tag != '')
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@v1.13.0
+
+      - name: Create GitHub Release (attach artifacts)
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*

project_handbook-0.0.1/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+site/
+.pytest_cache/
+.ruff_cache/
+uv.lock
+.codex-agent-*
+ph-parity-*.done
+.DS_Store

project_handbook-0.0.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: project-handbook
+Version: 0.0.1
+Summary: Installed ph CLI for Project Handbook
+Project-URL: Repository, https://github.com/Spenquatch/project-handbook-cli
+Requires-Python: >=3.10
+Requires-Dist: packaging>=23.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.0; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# project-handbook-cli
+
+Installed Python CLI distribution: `project-handbook`
+
+Console script: `ph`
+
+Handbook root marker (v1):
+- `project_handbook.config.json`
+
+Rule: `ph` MUST NOT execute repo-local Python scripts at runtime.
+
+## IMPORTANT: Be explicit about `PH_ROOT` during development
+
+When developing, prefer `ph --root /absolute/path/to/handbook` so you don’t accidentally operate on the wrong directory.
+
+v1 contract summary:
+- Content root: `PH_ROOT/**` (repo-root layout, e.g. `sprints/`, `features/`, `status/`, etc.)
+- Internals: `PH_ROOT/.project-handbook/**`
+
+## Repo layout (this repo)
+
+- `src/ph/**`: CLI implementation
+- `cli_plan/**`: authoritative v1 contract + spec + planning
+- `docs/**`: rendered docs (MkDocs)
+
+## Local install verification (exact commands)
+
+1) `uv venv`
+2) `uv pip install -e .`
+3) `ph --help`
+
+If `ph` is not found, activate the venv first: `. .venv/bin/activate`.
+
+## Dev verification (exact commands)
+
+- `uv pip install -e ".[dev]"`
+- `uv run ruff format .`
+- `uv run ruff check .`
+- `uv run pytest -q`
+
+## Docs (MkDocs)
+
+- `uv pip install -e ".[dev]"`
+- `uv run mkdocs serve`
+
+## End-session (manual verification)
+
+Non-`--skip-codex` mode requires the `codex` CLI on your `PATH` (e.g. `npm i -g @openai/codex`).
+
+Example:
+- `ph end-session --log ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl --root /path/to/project-handbook`
+
+## Release (exact steps)
+
+1) update `pyproject.toml` `project.version` and `src/ph/__init__.py` `__version__` (must match)
+2) run `uv run ruff check .` then `uv run pytest -q`
+3) create git tag `v<version>` and push
+4) GitHub Actions publishes to PyPI on tag push (see `.github/workflows/release.yml`)

project_handbook-0.0.1/README.md

@@ -0,0 +1,58 @@
+# project-handbook-cli
+
+Installed Python CLI distribution: `project-handbook`
+
+Console script: `ph`
+
+Handbook root marker (v1):
+- `project_handbook.config.json`
+
+Rule: `ph` MUST NOT execute repo-local Python scripts at runtime.
+
+## IMPORTANT: Be explicit about `PH_ROOT` during development
+
+When developing, prefer `ph --root /absolute/path/to/handbook` so you don’t accidentally operate on the wrong directory.
+
+v1 contract summary:
+- Content root: `PH_ROOT/**` (repo-root layout, e.g. `sprints/`, `features/`, `status/`, etc.)
+- Internals: `PH_ROOT/.project-handbook/**`
+
+## Repo layout (this repo)
+
+- `src/ph/**`: CLI implementation
+- `cli_plan/**`: authoritative v1 contract + spec + planning
+- `docs/**`: rendered docs (MkDocs)
+
+## Local install verification (exact commands)
+
+1) `uv venv`
+2) `uv pip install -e .`
+3) `ph --help`
+
+If `ph` is not found, activate the venv first: `. .venv/bin/activate`.
+
+## Dev verification (exact commands)
+
+- `uv pip install -e ".[dev]"`
+- `uv run ruff format .`
+- `uv run ruff check .`
+- `uv run pytest -q`
+
+## Docs (MkDocs)
+
+- `uv pip install -e ".[dev]"`
+- `uv run mkdocs serve`
+
+## End-session (manual verification)
+
+Non-`--skip-codex` mode requires the `codex` CLI on your `PATH` (e.g. `npm i -g @openai/codex`).
+
+Example:
+- `ph end-session --log ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl --root /path/to/project-handbook`
+
+## Release (exact steps)
+
+1) update `pyproject.toml` `project.version` and `src/ph/__init__.py` `__version__` (must match)
+2) run `uv run ruff check .` then `uv run pytest -q`
+3) create git tag `v<version>` and push
+4) GitHub Actions publishes to PyPI on tag push (see `.github/workflows/release.yml`)

project_handbook-0.0.1/cli_plan/AI_AGENT_START_HERE.md

@@ -0,0 +1,184 @@
+---
+title: CLI Plan – AI Agent Start Here
+type: process
+date: 2026-01-14
+tags: [cli, plan, execution, agent]
+links:
+  - ./archive/tasks_legacy.json
+  - ./tasks_v1_next.json
+  - ./archive/strict_parity_2026-02/tasks_v1_parity.json
+  - ./archive/strict_parity_2026-02/due-diligence.json
+  - ./backlog.json
+  - ./session_logs.md
+  - ./archive/strict_parity_2026-02/PARITY_CHECKLIST.md
+  - ./v1_cli/ADR-CLI-0001-ph-cli-migration.md
+  - ./v1_cli/ADR-CLI-0002-handbook-instance-scaffolding.md
+  - ./v1_cli/ADR-CLI-0003-ph-project-layout.md
+  - ./v1_cli/ADR-CLI-0004-ph-root-layout.md
+  - ./v1_cli/CLI_CONTRACT.md
+  - ./archive/strict_parity_2026-02/v0_make/MAKE_CONTRACT.md
+  - ./ph_spec/
+---
+
+# CLI Plan – AI Agent Start Here
+
+This folder is the **only** place we track v1 CLI execution planning and due diligence. Do not update general handbook onboarding docs for v1; keep v1 planning scoped to `cli_plan/`.
+
+## What you are building
+
+- A separately-installed Python CLI tool named `project-handbook` that provides the `ph` command.
+- The `ph` tool operates on a “handbook instance repo” (any repo with `project_handbook.config.json`) as **data/templates/plans**, and MUST NOT execute repo-local Python scripts at runtime.
+  - Reference implementation for parity/real-world behavior: `/Users/spensermcconnell/__Active_Code/oss-saas/project-handbook` (invoked via `pnpm make -- <target>`).
+  - When running commands during development, prefer `ph --root /absolute/path/to/target` so you don’t accidentally operate on the wrong directory.
+
+## Sources of truth (read in this order)
+
+1. `cli_plan/v1_cli/ADR-CLI-0004-ph-root-layout.md` (project layout + marker)
+2. `cli_plan/v1_cli/CLI_CONTRACT.md`
+3. `cli_plan/ph_spec/` (directory-by-directory spec + examples)
+4. `cli_plan/tasks_v1_next.json` (active incremental work queue)
+5. `cli_plan/archive/strict_parity_2026-02/due-diligence.json` (historical; complete)
+6. `cli_plan/archive/strict_parity_2026-02/v0_make/MAKE_CONTRACT.md` (historical parity reference)
+7. `cli_plan/v1_cli/ADR-CLI-0001-ph-cli-migration.md` (historical context)
+8. `cli_plan/v1_cli/ADR-CLI-0003-ph-project-layout.md` (historical context; superseded)
+9. `cli_plan/v1_cli/ADR-CLI-0002-handbook-instance-scaffolding.md` (historical context; superseded)
+
+## Root marker for v1
+
+For v1, the handbook instance repo root is detected by the presence of:
+
+- `project_handbook.config.json`
+
+The `ph` CLI MUST treat the directory that contains `project_handbook.config.json` as `PH_ROOT`.
+
+## Workstreams
+
+There are two primary workstreams under `cli_plan/`:
+
+1. **Next tasks (active)**: incremental v1 improvements in `cli_plan/tasks_v1_next.json`.
+2. **Backlog (active)**: items that require contract/spec decisions first in `cli_plan/backlog.json` (+ tech-debt notes in `cli_plan/backlog.md`).
+
+Historical (kept for audit trail):
+- Due diligence queue: `cli_plan/archive/strict_parity_2026-02/due-diligence.json` (complete).
+- Strict parity queue + checklist: `cli_plan/archive/strict_parity_2026-02/` (complete).
+- Original migration queue: `cli_plan/archive/tasks_legacy.json` (complete).
+
+Default policy:
+- Use `cli_plan/tasks_v1_next.json` for new work.
+- Only refer to archived queues for historical context.
+
+Important note:
+- `cli_plan/archive/tasks_legacy.json` and older `cli_plan/session_logs.md` entries include historical references to a deprecated `.ph/**` / `ph/**` layout. For v1, treat `cli_plan/v1_cli/CLI_CONTRACT.md` + `cli_plan/ph_spec/` as authoritative.
+
+## Strict workflow (do this every session)
+
+1. Decide the active queue:
+   - Use **Next queue workflow** (`cli_plan/tasks_v1_next.json`) for new work.
+2. Select exactly one task to execute (algorithm below).
+3. Before doing any work:
+   - set that task’s `status` to `in_progress` in the appropriate JSON file
+   - append exactly one new entry to `cli_plan/session_logs.md` using the template in that file
+4. Execute the task exactly as written (no scope creep; do not execute other task IDs).
+5. When finished, update both:
+   - the appropriate JSON file: set status to `done` OR `blocked` (and record blockers)
+   - `cli_plan/session_logs.md`: fill in verification, outcome, and the computed “Next task”
+6. Stop. The next session starts again from step 1.
+
+## Task selection algorithm (zero ambiguity)
+
+### Due diligence queue (archived) (`cli_plan/archive/strict_parity_2026-02/due-diligence.json`)
+
+Given `cli_plan/archive/strict_parity_2026-02/due-diligence.json`:
+
+1. If there is exactly one task with `status == "in_progress"`, continue that same task.
+2. Else pick the single task with `status == "todo"` with the lowest numeric ID (e.g. `DD-0001` before `DD-0100`).
+3. If none are `todo`:
+   - if there are blocked tasks, pick the blocked task with the lowest numeric ID and work only on unblocking it
+   - else stop and report: “No runnable due-diligence tasks. All due-diligence tasks are done.”
+
+### CLI queue (`cli_plan/archive/tasks_legacy.json`)
+
+Given `cli_plan/archive/tasks_legacy.json`:
+
+1. Build the set `DONE = { task.id | task.status == "done" }`.
+2. Compute the candidate list:
+   - `CANDIDATES = [ task | task.status == "todo" AND every dep in task.depends_on is in DONE ]`
+3. If `CANDIDATES` is empty:
+   - pick the single `blocked` task with the lowest `(phase.order, task.order)` and work only on unblocking it
+   - if there are no blocked tasks, stop and report: “No runnable tasks. All tasks are done.”
+4. Otherwise pick the single task in `CANDIDATES` with the lowest `(phase.order, task.order)`.
+5. The selected task is “the next task” for this session.
+
+### Next queue (`cli_plan/tasks_v1_next.json`)
+
+Given `cli_plan/tasks_v1_next.json`:
+
+1. Build the set `DONE = { task.id | task.status == "done" }`.
+2. Compute the candidate list:
+   - `CANDIDATES = [ task | task.status == "todo" AND every dep in task.depends_on is in DONE ]`
+3. If `CANDIDATES` is empty:
+   - pick the single `blocked` task with the lowest `(phase.order, task.order)` and work only on unblocking it
+   - if there are no blocked tasks, stop and report: “No runnable v1-next tasks. All v1-next tasks are done.”
+4. Otherwise pick the single task in `CANDIDATES` with the lowest `(phase.order, task.order)`.
+5. The selected task is “the next task” for this session.
+
+### Parity queue (archived) (`cli_plan/archive/strict_parity_2026-02/tasks_v1_parity.json`)
+
+Given `cli_plan/archive/strict_parity_2026-02/tasks_v1_parity.json`:
+
+1. Build the set `DONE = { task.id | task.status == "done" }`.
+2. Compute the candidate list:
+   - `CANDIDATES = [ task | task.status == "todo" AND every dep in task.depends_on is in DONE ]`
+3. If `CANDIDATES` is empty:
+   - pick the single `blocked` task with the lowest `(phase.order, task.order)` and work only on unblocking it
+   - if there are no blocked tasks, stop and report: “No runnable parity tasks. All parity tasks are done.”
+4. Otherwise pick the single task in `CANDIDATES` with the lowest `(phase.order, task.order)`.
+5. The selected task is “the next task” for this session.
+
+## How to mark progress
+
+### Due diligence tasks (archived) (`cli_plan/archive/strict_parity_2026-02/due-diligence.json`)
+
+For the active due-diligence task object:
+
+- On start:
+  - set `"status": "in_progress"`
+  - add `"started_at": "YYYY-MM-DDTHH:MM:SSZ"` (UTC)
+  - add `"last_session_log_ref": "cli_plan/session_logs.md#<paste the entry heading>"`
+- On completion:
+  - set `"status": "done"`
+  - add `"completed_at": "YYYY-MM-DDTHH:MM:SSZ"` (UTC)
+  - add `"next_task_id": "<computed next DD-#### id or NONE>"`
+- On blocked:
+  - set `"status": "blocked"`
+  - add `"blocked_at": "YYYY-MM-DDTHH:MM:SSZ"` (UTC)
+  - add `"blockers": ["<concrete blocker>", "..."]`
+  - add `"unblock_steps": ["<exact step to unblock>", "..."]`
+  - add `"next_task_id": "<computed next DD-#### id or NONE>"`
+
+### CLI tasks (`cli_plan/archive/tasks_legacy.json`)
+
+For the active CLI task object:
+
+- On start:
+  - set `"status": "in_progress"`
+  - set `"started_at": "YYYY-MM-DDTHH:MM:SSZ"` (UTC)
+  - set `"last_session_log_ref": "cli_plan/session_logs.md#<paste the entry heading>"`
+- On completion:
+  - set `"status": "done"`
+  - set `"completed_at": "YYYY-MM-DDTHH:MM:SSZ"` (UTC)
+  - set `"next_task_id": "<computed next task id>"`
+- On blocked:
+  - set `"status": "blocked"`
+  - set `"blocked_at": "YYYY-MM-DDTHH:MM:SSZ"` (UTC)
+  - set `"blockers": ["<concrete blocker>", "..."]`
+  - set `"unblock_steps": ["<exact step to unblock>", "..."]`
+  - set `"next_task_id": "<computed next task id>"` (this will typically be the same task, until unblocked)
+
+These tracking fields are permitted and expected even if they were not present originally.
+
+## Non-negotiables
+
+- Keep execution planning here (`cli_plan/`) only.
+- Follow the contract exactly; if you must change the contract, do it as a dedicated task and explain why in session logs.
+- Prefer small PR-sized tasks; do not bundle multiple task IDs into one run.

project_handbook-0.0.1/cli_plan/README.md

@@ -0,0 +1,37 @@
+---
+title: CLI Migration Plan (Versioned)
+type: guide
+date: 2026-01-13
+tags: [handbook, cli, migration, plan]
+links:
+  - ./archive/strict_parity_2026-02/v0_make/MAKE_CONTRACT.md
+  - ./v1_cli/ADR-CLI-0001-ph-cli-migration.md
+  - ./v1_cli/CLI_CONTRACT.md
+---
+
+# CLI Migration Plan (Versioned)
+
+This folder is versioned so we can always compare the **current Make-based interface** against the **new CLI interface** during parity work.
+
+## Versions
+
+### `v0_make/`
+Authoritative snapshot/contract of the current command surface:
+- Make targets (including placeholders/no-ops)
+- Hook behavior (history + auto validation)
+- Pre-exec gates + release coordination targets
+
+### `v1_cli/`
+Authoritative CLI design:
+- ADR for the `ph` CLI migration
+- CLI contract (command tree, hints, hooks, skip rules)
+
+## Parity rule
+
+`v1_cli` MUST preserve the intent and ergonomics of `v0_make` where applicable, while improving usability by ensuring the CLI can bootstrap a repo (`ph init`) and scaffold required files/directories (so commands don’t assume a pre-existing handbook filesystem).
+
+## Task queues
+
+- `cli_plan/archive/tasks_legacy.json`: historical migration task queue (complete; kept as an audit trail).
+- `cli_plan/archive/strict_parity_2026-02/tasks_v1_parity.json`: strict parity queue (complete; one checkbox per task from `cli_plan/archive/strict_parity_2026-02/PARITY_CHECKLIST.md`).
+- `cli_plan/tasks_v1_next.json`: active incremental v1 task queue (preferred for new work).

project_handbook-0.0.1/cli_plan/archive/README.md

@@ -0,0 +1,20 @@
+---
+title: CLI Plan – Archive
+type: guide
+date: 2026-02-04
+tags: [cli, plan, archive]
+links: []
+---
+
+# Archive
+
+This folder contains historical planning artifacts kept for audit trail purposes.
+
+Active planning queues:
+
+- `cli_plan/tasks_v1_next.json` (post-parity improvements)
+
+Historical (do not use for new work):
+
+- `cli_plan/archive/tasks_legacy.json` (original migration queue; contains deprecated prompts/layout references)
+- `cli_plan/archive/strict_parity_2026-02/` (strict Make→CLI parity artifacts: queue + checklist + legacy Make contract snapshot)