From 6e50a1624f98d89f89dd79c14d44aff3c3e24f94 Mon Sep 17 00:00:00 2001 From: "almanac-bot[bot]" <290534106+almanac-bot[bot]@users.noreply.github.com> Date: Sat, 4 Jul 2026 01:46:30 +0000 Subject: [PATCH] docs almanac: Ingest completed. --- .almanac/pages/lifecycle-architecture.md | 38 ++++++++++-------- .almanac/pages/lifecycle-cli.md | 40 ++++++++++++------- .almanac/pages/pypi-package-surface.md | 50 ++++++++++++++++++++++++ 3 files changed, 96 insertions(+), 32 deletions(-) create mode 100644 .almanac/pages/pypi-package-surface.md diff --git a/.almanac/pages/lifecycle-architecture.md b/.almanac/pages/lifecycle-architecture.md index 9ee1dcaa..ae17d91c 100644 --- a/.almanac/pages/lifecycle-architecture.md +++ b/.almanac/pages/lifecycle-architecture.md @@ -1,6 +1,6 @@ --- title: Lifecycle Architecture -summary: Lifecycle architecture is the reading map for CodeAlmanac's AI write operations, provider execution layer, repo-local job records, CLI commands, and scheduled maintenance tasks. +summary: Lifecycle architecture is the reading map for CodeAlmanac's AI write operations, provider execution layer, repo-local job records, CLI commands, and local/cloud run boundaries. topics: - agents - flows @@ -10,7 +10,7 @@ sources: - id: operations type: file path: src/codealmanac/workflows/ - note: Defines init, ingest, garden, sync, and shared lifecycle workflows in the active Python codebase. + note: Defines init, ingest, garden, and shared lifecycle workflows in the active Python codebase. - id: app-composition type: file path: src/codealmanac/app.py @@ -18,7 +18,15 @@ sources: - id: lifecycle-parser type: file path: src/codealmanac/cli/parser/lifecycle.py - note: Registers public lifecycle command parsing for init and hidden sync plus dev ingest/garden wiring. + note: Registers public init and hidden worker command parsing. + - id: dev-parser + type: file + path: src/codealmanac/cli/parser/dev.py + note: Registers hidden developer ingest and garden command parsing. + - id: local-parser + type: file + path: src/codealmanac/cli/parser/local.py + note: Registers local setup, trigger-policy, delivery-policy, and local runs command parsing. - id: jobs-parser type: file path: src/codealmanac/cli/parser/jobs.py @@ -31,10 +39,10 @@ sources: type: file path: src/codealmanac/engine/harnesses/ note: Defines provider-neutral harness requests and provider adapters that execute lifecycle prompts. - - id: automation + - id: release-verification type: file - path: src/codealmanac/services/automation/ - note: Implements scheduled sync, Garden, and update task configuration for recurring lifecycle work. + path: docs/codealmanac-launch/verification-matrix.md + note: Records the Slice 89 and Slice 90 evidence that the old sync/automation implementation path was removed from the launch CLI and shipped in 0.1.10. - id: purpose-prompt type: file path: src/codealmanac/prompts/base/purpose.md @@ -56,13 +64,13 @@ sources: path: src/codealmanac/prompts/operations/garden.md note: Defines the garden operation's graph-maintenance algorithm. status: active -verified: 2026-07-03 +verified: 2026-07-04 --- # Lifecycle Architecture -Lifecycle architecture is the cluster that explains how CodeAlmanac performs write-capable wiki work. It spans product workflows, command routing, provider-neutral harness execution, repo-local job records, transcript sync, and scheduled maintenance. [@operations] [@app-composition] [@jobs-layer] [@harness] [@automation] +Lifecycle architecture is the cluster that explains how CodeAlmanac performs write-capable wiki work. It spans product workflows, command routing, provider-neutral harness execution, repo-local job records, cloud capture, and the boundary between lifecycle jobs and local/cloud runs. [@operations] [@app-composition] [@jobs-layer] [@harness] [@release-verification] Start with [[wiki-lifecycle-operations]] when the question is "what semantic operation is this?" Start with [[lifecycle-cli]] when the question is "what command did the user run?" Start with [[process-manager-runs]] when the question is "what happened during a lifecycle job?" Start with [[harness-providers]] when the question is "how does this reach Claude, Codex, Cursor, or another runtime?" @@ -72,9 +80,9 @@ Start with [[wiki-lifecycle-operations]] when the question is "what semantic ope [[operation-prompts]] explains the base doctrine and operation-specific algorithms that give init, ingest, and garden their judgment rules. Prompt edits are the first place to improve wiki-writing behavior when the missing behavior is editorial judgment rather than deterministic plumbing. [@purpose-prompt] [@notability-prompt] [@init-prompt] [@ingest-prompt] [@garden-prompt] -[[lifecycle-cli]] maps public commands to operations and job behavior. It is the command-surface reference for `init`, `sync`, `jobs`, `serve`, `setup`, automation, and the developer ingest/garden surfaces. [@lifecycle-parser] [@jobs-parser] +[[lifecycle-cli]] maps public commands to operations and job behavior. It is the command-surface reference for `init`, hidden lifecycle jobs, `serve`, `setup`, cloud capture, local branch-control commands, and the hidden developer ingest/garden surfaces. [@lifecycle-parser] [@dev-parser] [@local-parser] [@jobs-parser] -[[process-manager-runs]] owns repo-local lifecycle job records, background spawn, event logs, cancellation, queue specs, worker locks, attach streaming, reindex-on-success, and jobs inspection. It is the storage and observability layer for init, ingest, garden, and sync-started ingest execution. It deliberately does not own cloud runs or branch-triggered local runs. +[[process-manager-runs]] owns repo-local lifecycle job records, background spawn, event logs, cancellation, queue specs, worker locks, attach streaming, reindex-on-success, and jobs inspection. It is the storage and observability layer for init, ingest, and garden execution. It deliberately does not own cloud runs or branch-triggered local runs. [[harness-providers]] owns the runtime adapter boundary. Workflows create provider-neutral harness requests; adapters translate those requests into Claude, Codex, or future runtimes. @@ -86,24 +94,20 @@ Start with [[wiki-lifecycle-operations]] when the question is "what semantic ope [[ingest-operation]] is the explicit bounded-source ingest path. It matters when work touches user-supplied files, folders, git ranges, source refs, or other concrete source material that should be distilled into durable wiki memory. -[[capture-automation]] and [[capture-ledger]] explain scheduled quiet-session capture. Read them together when changing sweep eligibility, quiet windows, dedupe, pending reconciliation, or cursor semantics. - -[[automation]] explains recurring scheduled tasks such as sync and garden. [[self-update]] is the global package mutation path scheduled automation can invoke, but package mutation remains owned by the update command. +[[pypi-package-surface]] explains the published package and release-smoke contract. It matters when command names, private console scripts, packaged resources, or launch-facing help change. ## Boundaries To Preserve Lifecycle workflows own wiki semantics and construct harness requests. They do not know provider SDKs, prompt transport protocols, launchd details, or job-record file formats. -The jobs layer owns repo-local lifecycle execution state and durable observability. It does not decide whether a transcript is worth syncing, whether a page deserves to exist, how provider-specific auth works, or how cloud/local trigger runs are delivered. +The jobs layer owns repo-local lifecycle execution state and durable observability. It does not decide whether a transcript is worth ingesting, whether a page deserves to exist, how provider-specific auth works, or how cloud/local trigger runs are delivered. Harness providers own runtime execution truth. They must reject unsupported spec fields or report unsupported capabilities rather than silently pretending a provider honored a request. -Automation owns scheduled invocation of known tasks. It does not own transcript eligibility, capture dedupe, Garden judgment, package-update semantics, or run finalization. - Agent readiness, auth checks, global instruction installation, and persisted provider config are support lifecycles, not the same thing as harness execution. [[provider-lifecycle-boundary]] is the current boundary page for that split. ## Historical Context -[[sessionend-hook]] is archived history for hook-based automatic capture. Current automatic sync is scheduler-only and must pass through sync sweep, ledger, and job records. +[[sessionend-hook]] is archived history for hook-based automatic capture. The launch CLI no longer exposes the old scheduled sync/root automation model; Slice 90 release smoke for `codealmanac` `0.1.10` specifically checked that stale `sync`, root scheduled `automation`, `local update`, and `local jobs` help text stayed absent. [@release-verification] Deleted bootstrap/build surfaces and the old writer/reviewer capture pipeline are historical names. Current runtime guidance should point to `codealmanac init`, [[wiki-lifecycle-operations]], [[operation-prompts]], and [[process-manager-runs]]. diff --git a/.almanac/pages/lifecycle-cli.md b/.almanac/pages/lifecycle-cli.md index 9d9b1d09..b5d7779a 100644 --- a/.almanac/pages/lifecycle-cli.md +++ b/.almanac/pages/lifecycle-cli.md @@ -6,6 +6,10 @@ topics: - flows - agents sources: + - id: pyproject + type: file + path: pyproject.toml + note: Defines the public `codealmanac` console script and private local trigger/worker console scripts. - id: root-parser type: file path: src/codealmanac/cli/parser/root.py @@ -13,11 +17,15 @@ sources: - id: lifecycle-parser type: file path: src/codealmanac/cli/parser/lifecycle.py - note: Defines public init, hidden sync, hidden worker, and hidden local-trigger command parsing. + note: Defines public init and hidden worker command parsing. - id: dev-parser type: file path: src/codealmanac/cli/parser/dev.py note: Defines hidden developer ingest and garden lifecycle command parsing. + - id: local-parser + type: file + path: src/codealmanac/cli/parser/local.py + note: Defines local setup, trigger-policy, delivery-policy, and local runs command parsing. - id: jobs-parser type: file path: src/codealmanac/cli/parser/jobs.py @@ -38,29 +46,35 @@ sources: type: file path: src/codealmanac/cli/parser/wiki.py note: Defines deterministic local wiki read, topic, health, reindex, serve, and tagging commands. - - id: automation-parser + - id: capture-parser type: file - path: src/codealmanac/cli/parser/automation.py - note: Defines local scheduled automation install, status, and uninstall commands. + path: src/codealmanac/cli/parser/capture.py + note: Defines cloud conversation capture commands and the hidden capture-hook entrypoint. + - id: release-verification + type: file + path: docs/codealmanac-launch/verification-matrix.md + note: Records the Slice 89 and Slice 90 evidence that stale launch-facing sync, automation, local update, and local jobs commands are absent from the published 0.1.10 CLI. status: active -verified: 2026-07-03 +verified: 2026-07-04 --- # Lifecycle CLI -The public program name is `codealmanac`. The CLI is an adapter over services and workflows: parsing builds request objects, dispatch calls the app composition root, renderers print results, and product behavior stays in workflows and services. [@root-parser] +The public program name is `codealmanac`. The CLI is an adapter over services and workflows: parsing builds request objects, dispatch calls the app composition root, renderers print results, and product behavior stays in workflows and services. The PyPI package also ships private `codealmanac-local-trigger` and `codealmanac-local-worker` console scripts for local branch-control plumbing; those names are executable integration points, not user-facing root subcommands. [@root-parser] [@pyproject] -[[lifecycle-architecture]] is the reading map for the surrounding workflow, harness, job-ledger, and automation pages. [[process-manager-runs]] owns the repo-local lifecycle job ledger that background CLI commands create and that jobs inspection commands read. +[[lifecycle-architecture]] is the reading map for the surrounding workflow, harness, and job-ledger pages. [[process-manager-runs]] owns the repo-local lifecycle job ledger that background CLI commands create and that hidden jobs inspection commands read. [[pypi-package-surface]] records the published package and release-smoke contract for this command surface. ## Write-Capable Commands `codealmanac init` initializes a local Almanac wiki. It accepts an optional path, configured root/name/description options, `--using`, foreground/background mode flags, `--force`, `--yes`, `--verbose`, `--guidance`, and background `--json`. Foreground init renders the finished job, wiki change count, and refreshed index summary; background init renders `job_id`, queued status, and worker PID. [@lifecycle-parser] [@lifecycle-rendering] -`codealmanac sync` is hidden but remains the scheduler-facing transcript sync entry point. Its status subcommand is read-only; its syncing path can queue lifecycle ingest jobs and renders started work by `job_id`. [@lifecycle-parser] [@lifecycle-rendering] - `codealmanac dev ingest` and `codealmanac dev garden` are hidden developer surfaces for local ingest and garden workflows. They share lifecycle options such as `--wiki`, `--using`, foreground/background mode, `--title`, `--guidance`, and background `--json`. These commands are not evidence for adding public `absorb`, `build`, or `garden` aliases outside the current runtime. [@dev-parser] -The hidden worker command `codealmanac __run-worker` drains the repo-local lifecycle job queue. The hidden local-worker and local-trigger commands belong to branch-triggered local runs, not to the lifecycle job ledger. [@lifecycle-parser] +The hidden worker command `codealmanac __run-worker` drains the repo-local lifecycle job queue. Branch-triggered local runs use the private package scripts `codealmanac-local-trigger` and `codealmanac-local-worker` instead of hidden root CLI subcommands. [@lifecycle-parser] [@pyproject] [@release-verification] + +`codealmanac capture status|enable|repair|disable` manages cloud conversation capture. It is not the old repo-local scheduled `sync` command surface; launch release verification requires root help to omit stale `sync` and root scheduled `automation` language. [@capture-parser] [@release-verification] + +`codealmanac local setup`, `local triggers`, `local delivery`, and `local runs` manage branch-triggered local execution for this checkout. Current local execution/history lives under `local runs`; `local update` and `local jobs` are stale launch-era spellings and must not reappear in launch-facing help. [@local-parser] [@release-verification] ## Jobs Commands @@ -74,10 +88,6 @@ The hidden worker command `codealmanac __run-worker` drains the repo-local lifec `codealmanac serve` starts the local read-only viewer. It reads wiki pages, index state, topics, backlinks, and lifecycle job data; it is not a lifecycle execution command. -## Automation Commands - -`codealmanac automation install|status|uninstall` manages scheduled local sync and garden tasks. Automation owns scheduled invocation; it does not own transcript eligibility, lifecycle job storage, provider execution, or wiki-writing judgment. [@automation-parser] - ## Boundary Rule -When adding CLI behavior, keep the CLI as an adapter. Public command names should express product intent, while internal naming follows the owning subsystem: repo-local lifecycle records are jobs, cloud/local trigger executions are runs, and query commands remain deterministic over committed wiki files plus derived local index state. +When adding CLI behavior, keep the CLI as an adapter. Public command names should express product intent, while internal naming follows the owning subsystem: repo-local lifecycle records are jobs, cloud/local trigger executions are runs, and query commands remain deterministic over committed wiki files plus derived local index state. Release verification should exercise the installed package whenever command names, console scripts, or launch-facing help change. [@release-verification] diff --git a/.almanac/pages/pypi-package-surface.md b/.almanac/pages/pypi-package-surface.md new file mode 100644 index 00000000..94681502 --- /dev/null +++ b/.almanac/pages/pypi-package-surface.md @@ -0,0 +1,50 @@ +--- +title: PyPI Package Surface +summary: The published `codealmanac` Python package exposes the public CLI plus private local-control entrypoints, and release smoke must prove stale launch-era commands stay absent. +topics: + - cli + - systems +sources: + - id: pyproject + type: file + path: pyproject.toml + note: Defines the `codealmanac` PyPI package version, Python requirement, package data, and console script entrypoints. + - id: local-trigger + type: file + path: src/codealmanac/local_trigger.py + note: Implements the private local Git-hook trigger entrypoint shipped as `codealmanac-local-trigger`. + - id: local-worker + type: file + path: src/codealmanac/local_worker.py + note: Implements the private local worker entrypoint shipped as `codealmanac-local-worker`. + - id: local-parser + type: file + path: src/codealmanac/cli/parser/local.py + note: Defines current local setup, triggers, delivery, and runs subcommands. + - id: release-verification + type: file + path: docs/codealmanac-launch/verification-matrix.md + note: Records Slice 89 and Slice 90 evidence for the CLI run-surface cleanup, wheel smoke, GitHub Actions publish, and public PyPI install smoke. +status: active +verified: 2026-07-04 +--- + +# PyPI Package Surface + +The current public package is the Python `codealmanac` distribution on PyPI. It installs the public `codealmanac` CLI and two private local-control console scripts: `codealmanac-local-trigger` and `codealmanac-local-worker`. Those private scripts are package surface because Git hooks and detached local workers need stable executable names, but they are not root CLI subcommands a user should discover as product commands. [@pyproject] [@local-trigger] [@local-worker] + +## Current Package Contract + +`pyproject.toml` defines package version `0.1.10`, requires Python 3.12 or newer, and exposes exactly these console scripts: `codealmanac`, `codealmanac-local-trigger`, and `codealmanac-local-worker`. The same package ships manual and prompt Markdown as package data, so release checks must cover both executable entrypoints and bundled resources when those surfaces change. [@pyproject] + +The launch-facing CLI must not expose the old scheduled `sync` and root `automation` model, and local branch execution must not use the stale `local update` or `local jobs` spellings. Current local execution is under `codealmanac local runs start`, with `local runs list`, `show`, and `logs` for local control-database history. [@local-parser] [@release-verification] + +## Release Evidence + +Slice 90 published `codealmanac` `0.1.10` from `main` through GitHub Actions run `28690993407`. The release matrix records passing tests, lint, diff hygiene, build checks, artifact checks, artifact upload, PyPI upload, and a fresh public temp-home install with `uv tool install --python 3.12 --refresh --no-cache --force codealmanac==0.1.10`. [@release-verification] + +That public smoke is the release bar for the Slice 89 CLI cleanup: the installed package returned version `0.1.10`, exposed `codealmanac`, `codealmanac-local-trigger`, and `codealmanac-local-worker`, and kept stale `sync`, root scheduled `automation`, `local update`, and `local jobs` help text out of the launch-facing CLI. [@release-verification] + +## Verification Rule + +Future release work that touches CLI naming, local branch runs, setup, uninstall, packaged resources, or console scripts should verify the installed artifact, not only the source checkout. A wheel or PyPI smoke should check `codealmanac --version`, root help, `codealmanac local --help`, and the private local trigger/worker help paths. [@release-verification]