From b61f90f361490180fce130784e94f2b4bfb144e2 Mon Sep 17 00:00:00 2001 From: "almanac-bot[bot]" <290534106+almanac-bot[bot]@users.noreply.github.com> Date: Sat, 4 Jul 2026 02:32:08 +0000 Subject: [PATCH] docs almanac: Ingest complete. I updated: --- .almanac/pages/lifecycle-architecture.md | 32 +++++--------- .almanac/pages/lifecycle-cli.md | 54 +++++++++++++----------- .almanac/pages/process-manager-runs.md | 28 ++++++------ 3 files changed, 55 insertions(+), 59 deletions(-) diff --git a/.almanac/pages/lifecycle-architecture.md b/.almanac/pages/lifecycle-architecture.md index 9ee1dcaa..7b0330c9 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, and CLI commands. 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, and garden lifecycle workflows in the active Python codebase. - id: app-composition type: file path: src/codealmanac/app.py @@ -18,11 +18,7 @@ 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. - - id: jobs-parser - type: file - path: src/codealmanac/cli/parser/jobs.py - note: Registers the hidden jobs inspection surface with `job_id` arguments. + note: Registers `codealmanac init` lifecycle command parsing. - id: jobs-layer type: file path: src/codealmanac/jobs/ @@ -31,10 +27,6 @@ sources: type: file path: src/codealmanac/engine/harnesses/ note: Defines provider-neutral harness requests and provider adapters that execute lifecycle prompts. - - id: automation - type: file - path: src/codealmanac/services/automation/ - note: Implements scheduled sync, Garden, and update task configuration for recurring lifecycle work. - id: purpose-prompt type: file path: src/codealmanac/prompts/base/purpose.md @@ -56,13 +48,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, and repo-local job records. [@operations] [@app-composition] [@jobs-layer] [@harness] 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 +64,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 command-surface behavior to operations, private process entrypoints, and job behavior. It is the command-surface reference for `init`, `serve`, setup/capture/local commands, and the hidden developer ingest/garden surfaces. [@lifecycle-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, and reindex-on-success. It is the storage and observability layer for init, ingest, and garden execution. It deliberately does not own cloud runs, branch-triggered local runs, or the root CLI command contract. [[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 +78,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. +[[capture-automation]], [[capture-ledger]], and [[automation]] are historical pages for removed scheduled capture and automation surfaces. Read them as migration context when a launch-facing cleanup mentions old sync or automation behavior, not as current command-surface references. ## 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 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. Current runtime guidance should not infer an active automatic sync surface from that page. 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..89efde73 100644 --- a/.almanac/pages/lifecycle-cli.md +++ b/.almanac/pages/lifecycle-cli.md @@ -13,60 +13,66 @@ 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 `codealmanac init` lifecycle 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: jobs-parser + - id: capture-parser type: file - path: src/codealmanac/cli/parser/jobs.py - note: Defines hidden jobs inspection commands with `job_id` arguments. - - id: jobs-dispatch + path: src/codealmanac/cli/parser/capture.py + note: Defines cloud capture commands, including `capture inspect` for recent local hook events. + - id: local-parser type: file - path: src/codealmanac/cli/dispatch/jobs.py - note: Dispatches jobs inspection commands to `app.jobs`. + path: src/codealmanac/cli/parser/local.py + note: Defines local branch trigger and local runs command parsing. - id: lifecycle-rendering type: file path: src/codealmanac/cli/render/lifecycle.py note: Renders foreground and background lifecycle results with job terminology. - - id: jobs-rendering + - id: project-scripts type: file - path: src/codealmanac/cli/render/jobs.py - note: Renders job records, logs, attach streams, and cancellation results. + path: pyproject.toml + note: Defines the installed console scripts for the public CLI and private hook/worker entrypoints. + - id: capture-hook-script + type: file + path: src/codealmanac/capture_hook.py + note: Implements the private `codealmanac-capture-hook` console script. + - id: job-worker-script + type: file + path: src/codealmanac/job_worker.py + note: Implements the private `codealmanac-job-worker` console script that drains lifecycle jobs. - id: wiki-parser 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: cli-contract-tests type: file - path: src/codealmanac/cli/parser/automation.py - note: Defines local scheduled automation install, status, and uninstall commands. + path: tests/test_cli.py + note: Verifies public help hides removed compatibility commands and rejects old root worker/admin names. 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] -[[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, job-ledger, and local-run pages. [[process-manager-runs]] owns the repo-local lifecycle job ledger that background CLI commands create and that the local viewer reads. ## 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] +Detached lifecycle jobs are drained by the private console script `codealmanac-job-worker`, not by a root `codealmanac __run-worker` subcommand. Branch-triggered local runs use the separate private `codealmanac-local-trigger` and `codealmanac-local-worker` scripts. [@project-scripts] [@job-worker-script] [@local-parser] -## Jobs Commands +## Removed Compatibility Commands -`codealmanac jobs`, `jobs show `, `jobs logs `, `jobs attach `, and `jobs cancel ` are hidden admin inspection commands over lifecycle job records. They dispatch to `app.jobs`, render `job_id`, and do not run AI or write wiki page prose. [@jobs-parser] [@jobs-dispatch] [@jobs-rendering] +`codealmanac jobs`, `codealmanac __capture-hook`, and `codealmanac __run-worker` are no longer accepted root parser commands. The root help also hides the old `sync`, root scheduled `automation`, and developer lifecycle surfaces. Tests pin this as a public contract because a hidden-but-accepted root command still becomes user-facing once an installed package can execute it. [@root-parser] [@cli-contract-tests] -`jobs attach` streams job log events until a job reaches a terminal status. `jobs cancel` marks queued or running lifecycle jobs cancelled through the job ledger; it is not the cancellation surface for hosted/cloud runs. [@jobs-dispatch] [@jobs-rendering] +The capture hook moved to the private `codealmanac-capture-hook` console script. Capture setup writes provider hooks that invoke that script, and `codealmanac capture inspect` is the public local inspection surface for recent hook events. [@project-scripts] [@capture-hook-script] [@capture-parser] ## Read And Organization Commands @@ -74,10 +80,8 @@ 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. + +Private process entrypoints belong in package scripts when installed hooks or detached workers need to call them directly. Do not reintroduce private worker or hook verbs as hidden root `codealmanac` subcommands unless they are meant to become part of the executable root parser contract. [@project-scripts] [@cli-contract-tests] diff --git a/.almanac/pages/process-manager-runs.md b/.almanac/pages/process-manager-runs.md index 19dc6ca4..ddeb713a 100644 --- a/.almanac/pages/process-manager-runs.md +++ b/.almanac/pages/process-manager-runs.md @@ -34,23 +34,27 @@ sources: - id: job-queue type: file path: src/codealmanac/jobs/queue/service.py - note: Queues init, ingest, and garden specs, spawns the hidden worker, and drains jobs through lifecycle workflows. + note: Queues init, ingest, and garden specs, spawns the private job worker, and drains jobs through lifecycle workflows. - id: page-run type: file path: src/codealmanac/engine/page_run/service.py note: Shows lifecycle workflows marking jobs running, recording harness events, refreshing the index, and finishing jobs. - - id: cli-jobs-parser + - id: project-scripts type: file - path: src/codealmanac/cli/parser/jobs.py - note: Defines the hidden `codealmanac jobs` inspection command arguments as `job_id`. - - id: cli-job-rendering + path: pyproject.toml + note: Defines `codealmanac-job-worker` as the private installed console script for lifecycle job draining. + - id: job-worker-script type: file - path: src/codealmanac/cli/render/jobs.py - note: Renders job records, logs, attach streams, and cancellation output with job terminology. + path: src/codealmanac/job_worker.py + note: Implements the private worker script that calls `app.workflows.queue.drain`. - id: cli-lifecycle-rendering type: file path: src/codealmanac/cli/render/lifecycle.py note: Renders foreground and background lifecycle results with `job` and `job_id` fields. + - id: cli-contract-tests + type: file + path: tests/test_cli.py + note: Verifies old root `jobs`, `__capture-hook`, and `__run-worker` commands are rejected. - id: cloud-runs type: file path: src/codealmanac/cloud/runs/ @@ -68,12 +72,12 @@ sources: path: tests/test_architecture.py note: Guards the job ID and job-ledger persistence boundaries introduced by the rename. status: active -verified: 2026-07-03 +verified: 2026-07-04 --- # Lifecycle Job Ledger -Repo-local lifecycle work in the Python codebase is a job ledger, not a run subsystem. `init`, `ingest`, `garden`, and sync-started ingest work produce `JobRecord` entries with `job_id` values, event logs, durable queued specs, cancellation, attach streaming, and worker locking under `src/codealmanac/jobs/`. Cloud runs and branch-triggered local control-plane runs remain separate concepts under `src/codealmanac/cloud/runs/` and `src/codealmanac/local/runs/`. [@slice-85-plan] [@job-models] [@cloud-runs] [@local-runs] +Repo-local lifecycle work in the Python codebase is a job ledger, not a run subsystem. `init`, `ingest`, and `garden` work produce `JobRecord` entries with `job_id` values, event logs, durable queued specs, cancellation, attach streaming, and worker locking under `src/codealmanac/jobs/`. Cloud runs and branch-triggered local control-plane runs remain separate concepts under `src/codealmanac/cloud/runs/` and `src/codealmanac/local/runs/`. [@slice-85-plan] [@job-models] [@cloud-runs] [@local-runs] The page slug is historical. Treat this page as the current home for lifecycle jobs, not as evidence that new repo-local lifecycle code should use run-shaped names. @@ -81,7 +85,7 @@ The page slug is historical. Treat this page as the current home for lifecycle j `src/codealmanac/jobs/ledger/` owns durable lifecycle observability. It defines `JobRecord`, `JobLogEvent`, `JobSpec`, `JobOperation`, `JobStatus`, `JobStore`, and `JobLedgerService`; callers pass `job_id` through request objects rather than `run_id`. `src/codealmanac/jobs/queue/` owns the single-writer background queue through `JobQueueWorkflow`. [@job-models] [@job-service] [@job-store] [@job-queue] -The composition root wires `JobLedgerService` as `app.jobs` and passes that service to the viewer, init, ingest, garden, page-run workflow, sync workflow, and queue workflow. There is no current `app.runs` facade for this repo-local lifecycle surface. [@app-composition] +The composition root wires `JobLedgerService` as `app.jobs` and passes that service to the viewer, init, ingest, garden, page-run workflow, and queue workflow. There is no current `app.runs` facade for this repo-local lifecycle surface. [@app-composition] The run noun is still correct for two other domains. Cloud runs are hosted or cloud-parallel executions started through `codealmanac runs ...`; local runs are trigger-created branch executions managed by the local control plane. Engine run artifacts are request/result material for one engine execution and now validate their IDs through `src/codealmanac/engine/run_ids.py`, so engine storage does not import local control-plane ID types. [@cloud-runs] [@local-runs] [@engine-run-ids] @@ -104,13 +108,13 @@ worker.lock/ A foreground lifecycle workflow starts a job record, marks it running through `PageRunWorkflow.begin()`, records mutation-policy and harness events, validates changed files, refreshes the SQLite index after a successful harness run, and finishes the job as `done` or `failed`. The workflow records harness transcript references when the adapter supplies them. [@page-run] -A background lifecycle workflow creates a queued job plus a durable `JobSpec`, spawns the hidden worker, and returns `job_id` plus the worker PID to the CLI. `JobQueueWorkflow.drain()` acquires the per-workspace worker lock, chooses the next queued spec-backed job, and calls the owning lifecycle workflow through `run_with_job(...)`. Missing specs fail the queued job instead of silently dropping it. [@job-queue] [@cli-lifecycle-rendering] +A background lifecycle workflow creates a queued job plus a durable `JobSpec`, spawns `codealmanac-job-worker`, and returns `job_id` plus the worker PID to the CLI. `JobQueueWorkflow.drain()` acquires the per-workspace worker lock, chooses the next queued spec-backed job, and calls the owning lifecycle workflow through `run_with_job(...)`. Missing specs fail the queued job instead of silently dropping it. [@job-queue] [@project-scripts] [@job-worker-script] [@cli-lifecycle-rendering] Terminal job statuses are `done`, `failed`, and `cancelled`. Cancelling a queued or running job writes a terminal cancelled transition; finishing a job that was already cancelled returns the cancelled record instead of resurrecting it. Attach streaming tails job log events until the record reaches a terminal status. [@job-models] [@job-store] ## CLI And Viewer -The public CLI name is `codealmanac`. The lifecycle jobs inspection surface is the hidden admin command group `codealmanac jobs`: list jobs, `show `, `logs `, `attach `, and `cancel `. Parser arguments, renderers, background JSON, and sync summaries now use `job_id`. [@cli-jobs-parser] [@cli-job-rendering] [@cli-lifecycle-rendering] +The public CLI name is `codealmanac`. Root `codealmanac jobs`, `codealmanac __capture-hook`, and `codealmanac __run-worker` are rejected by the root parser; private hook and worker execution use installed console scripts instead of hidden root verbs. Background lifecycle JSON and renderers still expose `job_id` for queued work. [@project-scripts] [@job-worker-script] [@cli-contract-tests] [@cli-lifecycle-rendering] `codealmanac serve` uses the same `JobLedgerService` through the viewer service; job data for the local viewer is not reimplemented in a separate storage path. The jobs page is a read surface over lifecycle job records and logs, not a second execution mechanism. [@app-composition]