@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/project-init-shared.mjs

@@ -0,0 +1,272 @@
+/**
+ * lib/project-init-shared.mjs — shared builders for project bootstrap scaffolds.
+ *
+ * Keeps the regular `construct init` bootstrap separate from `construct init-docs`
+ * while letting both commands reuse the same stamped file writers and core
+ * repo-state templates.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stampFrontmatter } from "./doc-stamp.mjs";
+
+export function writeStampedIfMissing({ targetRoot, created, skipped, filePath, content, generator }) {
+  if (fs.existsSync(filePath)) {
+    skipped.push(path.relative(targetRoot, filePath));
+    return false;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const stamped = filePath.endsWith(".md")
+    ? stampFrontmatter(content, { generator })
+    : content;
+  fs.writeFileSync(filePath, stamped, "utf8");
+  created.push(path.relative(targetRoot, filePath));
+  return true;
+}
+
+export function buildAgentsGuide(projectName) {
+  return `<!--
+AGENTS.md — canonical operating contract for AI agents working in this repository.
+
+Generated by \`construct init\`. Keep this file concise, current, and pruned:
+- update it when workflow rules, tracker hierarchy, or required tools change
+- remove stale sections instead of preserving historical guidance here
+- avoid duplicating deeper docs when a canonical source already exists elsewhere
+-->
+
+# ${projectName} Agent Guide
+
+## Operating hierarchy
+
+- Use Beads (\`bd\`) as the canonical durable tracker. All non-trivial work must have a Beads issue before implementation begins.
+- Use \`plan.md\` as the human-readable implementation plan tied to the active Beads issue set.
+- Use cass-memory through the MCP \`memory\` server for cross-session and cross-tool recall, not for task tracking.
+
+## Start-of-session rules
+
+- Read \`AGENTS.md\`, \`plan.md\`, \`.cx/context.md\`, and any canonical docs that exist before planning or coding.
+- Treat \`construct up\` as runtime hydration only. If services are unavailable, resume from durable state: \`plan.md\`, \`.cx/context.md\`, the latest \`.cx/handoffs/\` file, Beads, docs, and git.
+- Run \`bd ready\` to see unblocked work available to claim.
+- Run \`bd show <id>\` for the active issue to see its full context, dependencies, and notes.
+- Check \`.cx/handoffs/\` for the most recent handoff — if another session was active, read the latest handoff to understand what was in progress.
+- Carry tracker ids into plans, workflow entries, handoffs, and verification notes.
+- Use the single-writer rule: if two agent or harness sessions would touch the same file, one session owns the edit and the other reviews, researches, or waits for handoff.
+
+## Maintenance rules
+
+- Update \`plan.md\`, \`.cx/context.md\`, and \`.cx/context.json\` when work changes project reality.
+- Do not rely on dashboard chat history, running services, or an agent session as the source of truth. Persist recovery context in repo files, Beads, docs, and git before ending work.
+- Prune stale sections from managed docs as soon as they stop matching the repo.
+- Prefer updating an existing canonical file over creating a new top-level markdown file.
+
+## End-of-session rules
+
+- Before calling work done, update \`plan.md\` to reflect completed tasks: mark items \`done\`, add new phases or rows for work that was not previously tracked, and remove or correct rows that no longer match reality.
+- Session-level todo lists (OpenCode, Claude Code, etc.) are ephemeral. Any task that represents a durable change to the project must be reflected in \`plan.md\` before the session closes — not just in the todo tracker.
+- Write a handoff to \`.cx/handoffs/{date}-{slug}.md\` covering: current state, recent decisions, next actions, risks, do-not-touch files, and which Beads issue id(s) were in scope. Use \`bd note <id>\` to attach a summary to the tracker issue.
+- Do not close a session with a working-tree change that has no corresponding \`plan.md\` entry or Beads issue.
+- Check CI status after every push. Do not call work complete if CI is failing — either fix the failure or explicitly flag it as a known infrastructure issue (e.g. billing, secrets) that is outside the scope of the change.
+- Wait for CI to reach a terminal state (success or failure) before declaring done. "Queued" or "in progress" is not done. Run \`gh run list --limit 3\` and confirm the relevant workflow shows \`completed success\`.
+
+## Parallel agent coordination
+
+- **Embedded dolt lock contention**: Parallel \`bd\` commands fail because beads uses an embedded dolt database with a single writer lock. Always serialize beads operations.
+- **Use \`construct beads\`**: Instead of direct \`bd\` commands, use \`construct beads <command>\` for lock‑aware serialized execution.
+- **Merge‑slot coordination**: For batch operations like \`bd dolt push\` that need exclusive database access, check \`construct‑6uo\` (Merge slot coordination bead) using \`bd merge-slot check/acquire/release\`.
+- **Lock visibility**: Run \`construct beads status\` to see who holds the lock, pending queue, and stale lock cleanup.
+- **Queueing**: If lock is held, requests are queued in \`.beads/queue.jsonl\` and processed FIFO.
+- **Stale lock cleanup**: Run \`construct beads cleanup\` to remove locks from dead processes.
+
+### New workflow for beads operations
+
+1. **Check status**: \`construct beads status\` (or \`construct beads status --json\`)
+2. **Run commands**: \`construct beads ready\`, \`construct beads show construct-xxx\`, \`construct beads update construct-xxx --claim\`
+3. **Clean up**: \`construct beads cleanup\` if operations are stuck
+4. **View queue**: \`construct beads queue\` to see pending requests
+5. **Batch operations**: Before \`bd dolt push\`, check merge‑slot availability
+
+## Documentation System
+
+### README.md Maintenance
+- Update README.md when architecture changes
+- README.md must reflect current project capabilities  
+- Documentation updates belong in same PR as code changes
+- README.md should link to AGENTS.md, plan.md, and docs/
+
+### Documentation Quality Gates  
+- Run \`construct docs:verify\` before calling work complete
+- CI will fail if critical docs are missing or stale
+- Documentation drift must be addressed within one sprint
+
+### Documentation Lifecycle
+- Use \`construct init --docs-preset=product\` to establish documentation lanes
+- ADRs for architectural decisions, RFCs for proposals, PRDs for products
+- Documentation should be linked to beads issues in plan.md
+
+### Update Mechanism  
+- Run \`construct init:update\` quarterly to adopt new standards
+- Check \`.cx/context.json\` version matches current template
+- Review and apply migration scripts when prompted
+
+## CI Enforcement
+
+### Documentation Validation
+- \`construct docs:verify\` runs on every PR
+- Missing README.md, AGENTS.md, or plan.md fails CI
+- Stale plan.md (>7 days) or .cx/context.md (>7 days) fails CI
+- README.md missing basic sections warns but doesn't fail
+
+### Quality Gates
+- All local tests must pass before pushing
+- CI must be green after pushing
+- Documentation validation must pass
+- Comment policy must be enforced
+
+## Verification rules
+
+- Record verification evidence in the Beads issue (\`bd note <id>\`) or \`plan.md\`, or the relevant durable doc before calling work done.
+- If architecture, contracts, or operating rules change, update the relevant canonical docs in the same change.
+- All local tests must pass (\`npm test\`) before pushing. CI must be green after pushing before the task is considered done.
+- Push Beads changes alongside code: \`bd dolt push\` must succeed before the session closes.
+
+<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:placeholder -->
+## Beads Issue Tracker
+
+This project uses **bd (beads)** for issue tracking. Run \`bd prime\` to see full workflow context and commands.
+
+### Quick Reference
+
+\`\`\`bash
+bd ready              # Find available work
+bd show <id>          # View issue details  
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+
+# New: lock‑aware execution
+construct beads ready        # Run bd ready with lock management
+construct beads status       # Show lock and queue status
+construct beads cleanup      # Remove stale locks
+construct beads queue        # Show pending requests
+\`\`\`
+
+### Rules
+
+- Use \`bd\` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
+- **IMPORTANT**: For parallel agent safety, prefer \`construct beads <command>\` over direct \`bd\` calls
+- Run \`bd prime\` for detailed command reference and session close protocol
+- Use \`bd remember\` for persistent knowledge — do NOT use MEMORY.md files
+- Acquire the merge slot (\`bd merge-slot acquire\`) before batch operations like \`bd dolt push\`
+- **Beads hygiene is a project contract.** Read \`rules/common/beads-hygiene.md\` once per session — it defines when to claim, close, supersede, and prune beads. Stale tracker state is treated as broken work.
+
+## Session Completion
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until \`git push\` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   \`\`\`bash
+   git pull --rebase
+   # Check merge‑slot before dolt push
+   construct beads dolt push
+   git push
+   git status  # MUST show "up to date with origin"
+   \`\`\`
+5. **Run end‑of‑session automation**:
+   \`\`\`bash
+   # Sync plan.md with bead statuses
+   node -e "import('./lib/beads-automation.mjs').then(m => m.syncPlanWithBeads({ cwd: process.cwd() }))"
+   
+   # Create handoff
+   node -e "import('./lib/beads-automation.mjs').then(m => m.endOfSessionHook({ actor: process.env.USER, cwd: process.cwd() }))"
+   \`\`\`
+6. **Clean up** - Clear stashes, prune remote branches
+7. **Verify** - All changes committed AND pushed
+8. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until \`git push\` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+- ALWAYS use \`construct beads\` for beads operations in multi‑agent sessions
+- Clean up stale locks with \`construct beads cleanup\` if operations hang
+<!-- END BEADS INTEGRATION -->`;
+}
+
+export function buildPlanTemplate() {
+  return `<!--
+plan.md — current implementation plan for this repository.
+
+Generated by \`construct init\`. This file is a living plan, not an archive:
+- keep it linked to the active tracker issue ids
+- update it when scope, sequencing, or acceptance changes
+- prune or replace sections once the plan is superseded
+-->
+
+# Implementation Plan
+
+## Tracker Links
+
+- Primary issue: TBD
+- Related issues: TBD
+
+## Goal
+
+Describe the current objective in one clear sentence.
+
+## Active Plan
+
+1. Define the current execution slices and link each one to a tracker issue.
+2. Note the owner, constraints, and acceptance criteria for each slice.
+3. Assign one writer per file when work runs in parallel.
+
+## Decisions
+
+- List important decisions that shape the current plan.
+
+## Verification
+
+- Record the commands, tests, or checks that prove this plan slice is complete.
+`;
+}
+
+export function buildContextMarkdown() {
+  return `<!--
+.cx/context.md — concise resumable project context for human and agent handoff.
+
+Keep this file under 100 lines. Update it when reality changes, and prune stale bullets
+instead of letting it turn into a historical log. Durable task status belongs in Beads;
+\`plan.md\` holds the current plan; use the single-writer rule when parallel sessions are active.
+-->
+
+# Project Context
+
+> Required project state. Keep this file current enough that a new session can resume work quickly.
+
+## Active Work
+
+## Recent Decisions
+
+## Architecture Notes
+
+## Open Questions
+`;
+}
+
+export function buildContextJson(projectName) {
+  return `${JSON.stringify({
+    format: "json",
+    savedAt: new Date().toISOString(),
+    source: "construct-init",
+    projectName,
+    activeWork: [],
+    recentDecisions: [],
+    architectureNotes: [],
+    openQuestions: [],
+  }, null, 2)}\n`;
+}