Model one Almanac project across multiple local checkouts #47

Activity

1. markds75 commented on Jul 21, 2026

   

   markds75

   on Jul 21, 2026

   Author

   More actions

   Additional design note: merging transcript-derived decisions

   After more discussion, the hard part is not only the local registry collision or even Markdown merge mechanics. The hardest part is how multiple Claude/Codex workstreams should feed decisions from their transcripts into one shared project wiki.

   A useful framing: transcript ingestion should extract knowledge candidates, not directly mutate project truth.

   Proposed pipeline

   Claude/Codex transcripts from workspaces
           |
           v
   structured decision/fact candidates
           |
           v
   dedupe + conflict detection + branch/merge awareness
           |
           v
   wiki update proposal
           |
           v
   reviewed committed Markdown in almanac/
   

   A transcript may say “the agent chose X while working on branch A,” but the Almanac should only say “the project follows X” once that decision survives review, merge, or explicit acceptance.

   Candidate shape

   Candidates probably need fields such as:

   • project id
   • workspace id
   • branch / commit range, when available
   • transcript session id and evidence range
   • kind: decision, invariant, flow, gotcha, incident, todo, etc.
   • summary
   • affected files
   • proposed page or topic
   • confidence
   • status: proposed, accepted, rejected, superseded, stale
   • relations: duplicates, conflicts, supersedes

   Merge cases

   • Same decision, same meaning: one wiki update with multiple evidence refs.
   • Related decisions, different scope: one consolidated page/section with scoped nuance.
   • Conflicting decisions: one accepted project decision; rejected alternatives can be summarized in a Considered/Rejected section, but should not both become truth.
   • Branch-local decisions: if the code never merges, the candidate should expire, stay branch-local, or remain proposed rather than entering project truth.

   Important rule

   Only merged/reviewed code should create project truth automatically. Transcript-derived decisions from unmerged workstreams should remain proposed candidates. If CodeAlmanac cannot tell whether the branch merged, it should be conservative and require Garden/review to accept the candidate.

   Design implication

   This reinforces the need for a project/workspace model. Workspaces produce transcript evidence and candidates, but the shared project owns the durable wiki truth. Background sync should not blindly turn every local agent transcript into committed project knowledge.

   Direct transcript-to-wiki mutation is likely too eager for parallel workstreams. A safer design is:

   1. discover transcripts per workspace,
   2. extract structured candidates,
   3. group candidates by shared project identity,
   4. dedupe/conflict-check them,
   5. propose wiki updates,
   6. commit accepted knowledge into almanac/ through normal Git review/merge.

   That means the basename collision is one symptom of a larger missing model: CodeAlmanac needs to distinguish shared project memory from local workspace activity and treat transcript-derived knowledge as evidence/proposals until it becomes settled project knowledge.
2. markds75 commented on Jul 21, 2026

   

   markds75

   on Jul 21, 2026

   Author

   More actions

   Additional design note: --wiki <name> currently selects a path-bound registration

   One more implication: today's --wiki <name> behavior shows that this is not just an auto-registration collision.

   Currently, --wiki lmfellow means roughly:

   name -> one registered repository row -> one stored root_path
   

   It does not mean "the shared lmfellow project, resolved through the workspace I am currently in." If lmfellow is registered to /a/lmfellow, then running a command from /b/lmfellow with --wiki lmfellow still targets the stored /a/lmfellow root.

   That means the current selector conflates two things that probably need to be separate:

   • Project selector: which shared Almanac project/codebase?
   • Workspace selector: which local checkout/worktree should this command read or write?

   Design implication

   If CodeAlmanac supports one project across multiple checkouts, name likely belongs at the project level, not the workspace/root-path level.

   A future shape might be:

   projects
     project_id
     name
     canonical_git_identity
     default_workspace_id
   
   workspaces
     workspace_id
     project_id
     root_path
     git_common_dir
     branch
     last_seen_at
   

   Then --wiki lmfellow would select the project. Command execution would still need an active workspace:

   • If cwd is a known workspace for that project, use cwd.
   • If cwd is outside known workspaces, use a configured default workspace or fail with a clear message.
   • A later explicit --workspace selector may be needed for non-cwd workflows.

   Command behavior implications

   For read/write commands:

   codealmanac show architecture/foo --wiki lmfellow

   If run from /b/lmfellow, the intuitive behavior is:

   select project lmfellow
   use active workspace /b/lmfellow
   read /b/lmfellow/almanac
   

   For sync:

   codealmanac sync --wiki lmfellow

   The project selector should scope to the shared project, but transcript evidence may come from any known workspace for that project. That reinforces the earlier candidate/proposal model: sync can discover transcript-derived knowledge across workspaces, but should not blindly mutate project truth from every local transcript.

   Scope update

   The issue should cover both:

   1. the immediate crash from same-basename auto-registration, and
   2. the deeper selector model problem where --wiki <name> currently identifies a single path-bound registration instead of a shared project plus an active workspace.

   A suffix-based name workaround would not solve this, because it would keep treating /a/lmfellow and /b/lmfellow as unrelated wiki projects rather than workspaces for the same project.