@aitne/daemon 0.1.0

package/dist/core/repository-management-docs.js

@@ -0,0 +1,855 @@
+import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync, } from "node:fs";
+import { basename, join } from "node:path";
+import { formatSqliteDatetime, localDateStr } from "@aitne/shared";
+import { writeFileAtomically } from "./atomic-write.js";
+import { gitRepoJournalPath, gitRepoOverviewPath } from "./context-paths.js";
+import { withOverviewWriteLock } from "./overview-write-lock.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("repository-management-docs");
+const LOG_LIMIT = 200;
+const MAX_TEXT_BYTES = 16_000;
+const MAX_STAT_BYTES = 20_000;
+const ARCHITECTURE_BEGIN_MARKER = "<!-- architecture:start -->";
+const ARCHITECTURE_END_MARKER = "<!-- architecture:end -->";
+const ARCHITECTURE_PLACEHOLDER = "_Architecture analysis pending. Click \"Refresh architecture\" on the Daily git management panel — an agent will read the repository and replace this block with a detailed module / data-flow / integration breakdown._";
+const ARCHITECTURE_SECTION_MAX_BYTES = 64 * 1024;
+/**
+ * How long a `git.project.refresh_architecture` row may sit in
+ * `pending` or `running` before the in-flight check treats it as stuck
+ * and rescues it (`status = 'skipped'`). A pending row older than this
+ * means the scheduler never picked it up — backend quota out, an
+ * unrecoverable pre-condition failure, or the dispatcher pruning it
+ * mid-flight. A running row older than this means the daemon crashed
+ * mid-execution without flipping status, and the next startup
+ * `recoverOrphanedRunningSchedules` would resolve it — but that leaves
+ * dashboard buttons disabled until the daemon restarts.
+ *
+ * Without this rescue the dashboard's Generate-overview / Refresh-
+ * architecture buttons stay disabled forever for the affected repo.
+ * Sixty minutes is comfortably longer than any real architecture
+ * analysis (typical runs settle in single-digit minutes) but short
+ * enough that a user who hits a stuck row early in the day can
+ * recover the same session by clicking again. Manual cancel and
+ * timeout warnings are tracked separately.
+ */
+export const STUCK_ARCHITECTURE_REFRESH_THRESHOLD_MS = 60 * 60 * 1000;
+/**
+ * Initialize (or reuse) the per-repository overview document and ensure the
+ * agent will fill in the `## Architecture` section.
+ *
+ * The init flow is intentionally split into two phases that the daemon
+ * owns end-to-end so that one click — manual init from the dashboard, the
+ * GitWatcher baseline, or the cron-driven daily scan that finds the file
+ * missing — always lands a complete overview.md once the queued agent run
+ * settles:
+ *
+ *  1. **Skeleton** (synchronous, deterministic): write the YAML
+ *     frontmatter, the git-evidence Summary, the placeholder Architecture
+ *     block bracketed by markers, the Notable Changes list rendered from
+ *     `git log`, and the empty Open Threads / Daily Activity Log sections.
+ *     Mirror the repository's README into `git/<slug>/README.md` so the
+ *     agent can read it through the daemon-owned context dir without
+ *     leaving the workspace.
+ *  2. **Architecture refresh** (asynchronous, agent-driven): enqueue a
+ *     `git.project.refresh_architecture` row in `agent_schedule`. The
+ *     scheduler dispatches it through the standard scheduled.task path,
+ *     the agent reads the repo, and writes the body back through the
+ *     `PUT /api/repositories/:id/architecture-section` chokepoint which
+ *     surgically replaces the marker-bracketed Architecture block.
+ *
+ * The enqueue is idempotent in two dimensions:
+ *
+ *  - When the overview already exists with `architecture_status: complete`
+ *    (a previous refresh landed), no new schedule row is inserted.
+ *  - When a `pending`/`running` `git.project.refresh_architecture` row
+ *    already exists for this repository, the existing row is returned
+ *    instead of inserting a duplicate. Two concurrent agent sessions
+ *    would race on the chokepoint write and burn quota.
+ *
+ * Re-init on an existing overview whose `architecture_status` is still
+ * `pending` re-enqueues a refresh — that recovers cases where a prior
+ * agent run failed or never landed (e.g. before the `{context}`-injection
+ * fix that gave the task-flow access to `<task_context>`).
+ */
+export function runRepositoryManagementInit(deps) {
+    const localPath = requireLocalPath(deps.repo);
+    const now = deps.now ?? new Date();
+    const date = dateStamp(now, deps.timezone);
+    const overviewPath = gitRepoOverviewPath(deps.repo.slug);
+    const absolutePath = join(deps.contextDir, overviewPath);
+    if (existsSync(absolutePath)) {
+        const readmeCopiedTo = copyRepositoryReadme(deps, localPath);
+        const architectureScheduleId = ensureArchitectureRefreshForExisting(deps, absolutePath, now);
+        return {
+            status: "exists",
+            overviewPath,
+            absolutePath,
+            readmeCopiedTo,
+            architectureScheduleId,
+        };
+    }
+    const evidence = collectGitEvidence(localPath);
+    const content = renderOverview({
+        repo: deps.repo,
+        evidence,
+        date,
+    });
+    writeManagedContextFile(deps, overviewPath, content, "repository_management_init");
+    const readmeCopiedTo = copyRepositoryReadme(deps, localPath);
+    const architectureScheduleId = ensureArchitectureRefreshEnqueued(deps.db, deps.repo, now);
+    return {
+        status: "written",
+        overviewPath,
+        absolutePath,
+        readmeCopiedTo,
+        architectureScheduleId,
+    };
+}
+/**
+ * For the "overview already exists" branch of init: only enqueue a
+ * refresh when the existing file's frontmatter explicitly reports
+ * `architecture_status: pending`. Any other state — `complete`, an
+ * unrecognized value, missing frontmatter, or malformed YAML — produces
+ * `null` and falls through to the explicit "Refresh architecture" button.
+ *
+ * The strict reading is deliberate: `runRepositoryArchitectureSectionReplace`
+ * only writes the status field back when the file already starts with
+ * `---\n`, so a file that was hand-edited to drop its frontmatter will
+ * never have the field re-added by an agent run. Treating "missing
+ * frontmatter" as `pending` would queue a refresh, the agent would land
+ * the architecture body, the field would still be absent, and the next
+ * init click would queue the same work again — an unbounded loop bounded
+ * only by the in-flight guard. Returning `null` here makes the behavior
+ * stable for hand-managed files: the user must explicitly click
+ * "Refresh architecture" to opt into a re-run.
+ */
+function ensureArchitectureRefreshForExisting(deps, absolutePath, now) {
+    const status = readArchitectureStatus(absolutePath);
+    if (status !== "pending")
+        return null;
+    return ensureArchitectureRefreshEnqueued(deps.db, deps.repo, now);
+}
+/**
+ * Inspect the YAML frontmatter of a managed overview file and classify
+ * its `architecture_status` field. Three explicit states keep the init
+ * decision logic narrow:
+ *
+ *   - `"pending"`: the agent has not yet landed an analysis. The init
+ *     flow will (re-)enqueue a refresh.
+ *   - `"complete"`: an analysis already landed. Init skips so re-running
+ *     it is reserved for the explicit "Refresh architecture" button.
+ *   - `"unknown"`: anything else — frontmatter missing, no closing
+ *     `---`, no `architecture_status` field, or an unrecognized value.
+ *     Init treats this as "do not auto-enqueue" because
+ *     `runRepositoryArchitectureSectionReplace` only writes the field
+ *     back on files that already start with `---\n`, so a queued
+ *     refresh cannot move a hand-managed file out of "unknown".
+ *
+ * Caller is responsible for `existsSync(absolutePath)` — this helper
+ * follows the read-after-exists pattern used elsewhere in this file
+ * (`appendOverviewDailyLog`, `runRepositoryArchitectureSectionReplace`)
+ * and lets the I/O error surface up to the route's 500 path.
+ */
+function readArchitectureStatus(absolutePath) {
+    const body = readFileSync(absolutePath, "utf-8");
+    if (!body.startsWith("---\n"))
+        return "unknown";
+    const closeIdx = body.indexOf("\n---\n", 4);
+    if (closeIdx < 0)
+        return "unknown";
+    const frontmatter = body.slice(4, closeIdx);
+    const match = /^architecture_status:\s*(\S+)\s*$/m.exec(frontmatter);
+    if (!match)
+        return "unknown";
+    if (match[1] === "complete")
+        return "complete";
+    if (match[1] === "pending")
+        return "pending";
+    return "unknown";
+}
+/**
+ * Enqueue a `git.project.refresh_architecture` agent run for `repo`,
+ * skipping when one is already in flight. Used by both the init flow
+ * (auto-enqueue when a fresh skeleton lands or recovery on a pending
+ * existing file) and the dashboard's "Refresh architecture" button.
+ *
+ * The scheduled row carries the full `task_context` the task-flow reads
+ * (`repositoryId`, `slug`, `localPath`, `githubRepo`, `classification`,
+ * `category`, `correlationId`). The dispatcher's `executeScheduledTask`
+ * picks up the `processKey` field to route the prompt through the
+ * `git.project.refresh_architecture.md` task-flow; the `<task_context>`
+ * block is materialized into the prompt by the context-builder via the
+ * `{context}` placeholder at the top of that task-flow file.
+ */
+export function ensureArchitectureRefreshEnqueued(db, repo, now = new Date()) {
+    if (!repo.localPath) {
+        throw new Error("Architecture refresh requires a local clone");
+    }
+    const existing = findInFlightArchitectureRefresh(db, repo.id);
+    if (existing)
+        return existing.scheduleId;
+    const inserted = enqueueArchitectureRefresh(db, repo, now);
+    return inserted.scheduleId;
+}
+/**
+ * Insert a fresh `git.project.refresh_architecture` row unconditionally.
+ * Callers that need idempotency should go through
+ * `ensureArchitectureRefreshEnqueued` instead — this primitive exists so
+ * the dashboard's "Refresh architecture" route can compose its own
+ * 409-on-in-flight response rather than collapsing the two cases.
+ */
+export function enqueueArchitectureRefresh(db, repo, now = new Date()) {
+    if (!repo.localPath) {
+        throw new Error("Architecture refresh requires a local clone");
+    }
+    const correlationId = randomUUID();
+    const taskContext = {
+        processKey: "git.project.refresh_architecture",
+        repositoryId: repo.id,
+        slug: repo.slug,
+        localPath: repo.localPath,
+        githubRepo: repo.githubOwner && repo.githubRepo
+            ? `${repo.githubOwner}/${repo.githubRepo}`
+            : null,
+        classification: repo.classification,
+        category: repo.category,
+        correlationId,
+    };
+    const result = db
+        .prepare(`INSERT INTO agent_schedule
+         (scheduled_for, task_type, task_description, task_context, correlation_id, model, status)
+       VALUES (?, 'git.project.refresh_architecture', ?, ?, ?, NULL, 'pending')`)
+        .run(formatSqliteDatetime(now), `Refresh architecture analysis for ${repo.slug}.`, JSON.stringify(taskContext), correlationId);
+    return { scheduleId: Number(result.lastInsertRowid), correlationId };
+}
+/**
+ * Locate an in-flight `git.project.refresh_architecture` row for this
+ * repository so the init / refresh-architecture flows can short-circuit
+ * duplicate enqueues. Two concurrent agent sessions for the same repo
+ * would race on the chokepoint write and burn quota for no benefit.
+ *
+ * Before reading, this also rescues any pending/running row older than
+ * `STUCK_ARCHITECTURE_REFRESH_THRESHOLD_MS` by flipping its status to
+ * `skipped`. Without that sweep, a row stuck in `pending` (scheduler
+ * never picked it up — quota out, backend down) or `running` (daemon
+ * crashed mid-execution) would keep the dashboard's Generate-overview
+ * and Refresh-architecture buttons disabled forever, and the next
+ * click — even at full health — would 409 because this function would
+ * still report the row in flight. The rescue lets the user click
+ * again immediately and inserts a fresh row, while leaving an audit
+ * trail (status: skipped) of the stuck attempt. Manual cancel and
+ * timeout warnings are tracked separately.
+ *
+ * Reads `task_context.repositoryId` via JSON path; the table is small and
+ * this call is rare so a per-row scan is fine.
+ */
+export function findInFlightArchitectureRefresh(db, repositoryId, now = new Date()) {
+    const stuckBefore = formatSqliteDatetime(new Date(now.getTime() - STUCK_ARCHITECTURE_REFRESH_THRESHOLD_MS));
+    // `scheduled_for` is the canonical "when should this run" timestamp
+    // for an agent_schedule row — it's set explicitly at enqueue and is
+    // the value the scheduler watches. `created_at` defaults to
+    // `CURRENT_TIMESTAMP` and is *not* test-controlled, so using it here
+    // would prevent any deterministic test of the rescue threshold and
+    // leak wall-clock time into the production check. For an
+    // architecture refresh, `scheduled_for` is set to "now" at enqueue
+    // (immediate dispatch), so freshness based on `scheduled_for`
+    // matches the freshness based on enqueue time in production.
+    db.prepare(`UPDATE agent_schedule
+        SET status = 'skipped'
+      WHERE task_type = 'git.project.refresh_architecture'
+        AND status IN ('pending', 'running')
+        AND json_extract(task_context, '$.repositoryId') = ?
+        AND scheduled_for < ?`).run(repositoryId, stuckBefore);
+    const row = db
+        .prepare(`SELECT id, correlation_id, status
+         FROM agent_schedule
+        WHERE task_type = 'git.project.refresh_architecture'
+          AND status IN ('pending', 'running')
+          AND json_extract(task_context, '$.repositoryId') = ?
+        ORDER BY id DESC
+        LIMIT 1`)
+        .get(repositoryId);
+    if (!row)
+        return null;
+    return {
+        scheduleId: row.id,
+        correlationId: row.correlation_id ?? "",
+        status: row.status,
+    };
+}
+export async function runRepositoryManagementScan(deps) {
+    const localPath = requireLocalPath(deps.repo);
+    const now = deps.now ?? new Date();
+    const lookbackHours = deps.lookbackHours ?? 24;
+    const date = dateStamp(now, deps.timezone);
+    const since = new Date(now.getTime() - lookbackHours * 60 * 60 * 1000);
+    const overviewPath = gitRepoOverviewPath(deps.repo.slug);
+    const journalPath = gitRepoJournalPath(deps.repo.slug, date);
+    const absoluteJournalPath = join(deps.contextDir, journalPath);
+    const commits = gitLog(localPath, [
+        `--since=${since.toISOString()}`,
+        `--max-count=${LOG_LIMIT}`,
+    ]);
+    const observations = recentRepositoryObservations(deps.db, deps.repo, since);
+    const prEvents = observations.filter((row) => row.source.startsWith("github:notification:")).length;
+    const workflowEvents = observations.filter((row) => row.source.startsWith("github:workflow:")).length;
+    if (commits.length === 0 && observations.length === 0) {
+        return {
+            status: "skipped_no_activity",
+            overviewPath,
+            journalPath,
+            absoluteJournalPath,
+            commitCount: 0,
+            prEvents: 0,
+            workflowEvents: 0,
+        };
+    }
+    if (!existsSync(join(deps.contextDir, overviewPath))) {
+        runRepositoryManagementInit(deps);
+    }
+    const statSummary = gitStatSummary(localPath, [
+        "log",
+        "--stat",
+        `--since=${since.toISOString()}`,
+        `--max-count=${LOG_LIMIT}`,
+    ]);
+    const journal = renderJournal({
+        repo: deps.repo,
+        date,
+        commits,
+        observations,
+        prEvents,
+        workflowEvents,
+        statSummary,
+    });
+    writeManagedContextFile(deps, journalPath, journal, "repository_management_scan");
+    await appendOverviewDailyLog(deps, {
+        date,
+        overviewPath,
+        commitCount: commits.length,
+        prEvents,
+        workflowEvents,
+    });
+    return {
+        status: "written",
+        overviewPath,
+        journalPath,
+        absoluteJournalPath,
+        commitCount: commits.length,
+        prEvents,
+        workflowEvents,
+    };
+}
+function requireLocalPath(repo) {
+    if (!repo.localPath) {
+        throw new Error("repository management requires a local clone");
+    }
+    assertGitWorkTree(repo.localPath);
+    return repo.localPath;
+}
+function assertGitWorkTree(localPath) {
+    const value = git(localPath, ["rev-parse", "--is-inside-work-tree"]).trim();
+    if (value !== "true") {
+        throw new Error(`repository management requires a git worktree: ${localPath}`);
+    }
+}
+function collectGitEvidence(localPath) {
+    return {
+        currentBranch: git(localPath, ["branch", "--show-current"]).trim() || "unknown",
+        remoteUrl: nullableGit(localPath, ["remote", "get-url", "origin"]),
+        firstCommitDate: nullableGit(localPath, ["log", "--reverse", "--format=%cs", "-1"]),
+        lastCommitDate: nullableGit(localPath, ["log", "-1", "--format=%cs"]),
+        recentCommits: gitLog(localPath, [`--max-count=${LOG_LIMIT}`]),
+        readmeFileName: findReadmeFileName(localPath),
+    };
+}
+/**
+ * Locate the repo's README file in the worktree root. Prefers the
+ * dominant convention (`.md` extension) over alternative formats so a
+ * directory containing both `README.md` and `README.txt` always selects
+ * the markdown one regardless of `readdirSync` ordering. Returns the
+ * file *name* (relative to `localPath`), not the absolute path.
+ */
+function findReadmeFileName(localPath) {
+    let entries;
+    try {
+        entries = readdirSync(localPath);
+    }
+    catch {
+        return null;
+    }
+    const candidates = entries.filter((name) => /^readme(\.|$)/i.test(name));
+    if (candidates.length === 0)
+        return null;
+    const score = (name) => {
+        const lower = name.toLowerCase();
+        if (lower === "readme.md")
+            return 0;
+        if (lower.endsWith(".md"))
+            return 1;
+        if (lower.endsWith(".markdown"))
+            return 2;
+        if (lower === "readme")
+            return 3;
+        if (lower.endsWith(".rst"))
+            return 4;
+        if (lower.endsWith(".txt"))
+            return 5;
+        return 6;
+    };
+    candidates.sort((a, b) => score(a) - score(b) || a.localeCompare(b));
+    for (const candidate of candidates) {
+        const fullPath = join(localPath, candidate);
+        try {
+            if (statSync(fullPath).isFile())
+                return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Mirror the repository's `README.*` verbatim to
+ * `<contextDir>/git/<slug>/README.md`. Mechanical copy — no truncation,
+ * no processing — but routed through `writeManagedContextFile` so the
+ * write picks up the same chokepoint guarantees as every other managed
+ * write in this module:
+ *
+ *   - Atomic write (no partial-state visible to readers).
+ *   - Snapshot of the previous body into `md_file_snapshots` so an
+ *     accidental upstream README rewrite is recoverable from history.
+ *   - `AgentWriteTracker.markWriting` fires *before* the rename
+ *     completes, so observer-fired indexers tag the resulting fs event
+ *     `actor='agent'` instead of mis-attributing it to the user.
+ *
+ * Returns the relative context-file path it wrote, or `null` if no
+ * README was found in the repo root or the source could not be read.
+ * Errors during the read are logged at warn — the init endpoint should
+ * not blow up just because a README is unreadable.
+ */
+function copyRepositoryReadme(deps, localPath) {
+    const fileName = findReadmeFileName(localPath);
+    if (!fileName)
+        return null;
+    const src = join(localPath, fileName);
+    const relPath = `git/${deps.repo.slug}/README.md`;
+    let body;
+    try {
+        body = readFileSync(src, "utf-8");
+    }
+    catch (err) {
+        logger.warn({ err, repositoryId: deps.repo.id, src }, "Failed to read repository README — skipping mirror copy");
+        return null;
+    }
+    writeManagedContextFile(deps, relPath, body, "repository_management_readme_copy");
+    return relPath;
+}
+function gitLog(localPath, extraArgs) {
+    const recordSep = "\x1e";
+    const fieldSep = "\x1f";
+    let stdout;
+    try {
+        stdout = git(localPath, [
+            "log",
+            `--format=%H${fieldSep}%h${fieldSep}%cs${fieldSep}%an${fieldSep}%s${recordSep}`,
+            ...extraArgs,
+        ], MAX_TEXT_BYTES);
+    }
+    catch (err) {
+        if (isEmptyGitHistoryError(err))
+            return [];
+        throw err;
+    }
+    return stdout
+        .split(recordSep)
+        .map((record) => record.trim())
+        .filter(Boolean)
+        .map((record) => {
+        const [hash = "", short = "", date = "", author = "", ...subjectParts] = record.split(fieldSep);
+        return {
+            hash,
+            short,
+            date,
+            author,
+            subject: subjectParts.join(fieldSep).trim(),
+        };
+    });
+}
+function isEmptyGitHistoryError(err) {
+    const stderr = String(err?.stderr ?? "");
+    const message = err instanceof Error ? err.message : String(err);
+    const text = `${stderr}\n${message}`;
+    return text.includes("does not have any commits yet") ||
+        text.includes("bad default revision 'HEAD'");
+}
+function gitStatSummary(localPath, args) {
+    try {
+        return git(localPath, args, MAX_STAT_BYTES);
+    }
+    catch (err) {
+        if (isEmptyGitHistoryError(err))
+            return "";
+        throw err;
+    }
+}
+function git(localPath, args, maxBuffer = MAX_TEXT_BYTES) {
+    return execFileSync("git", args, {
+        cwd: localPath,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 10_000,
+        maxBuffer,
+    });
+}
+function nullableGit(localPath, args) {
+    try {
+        const value = git(localPath, args).trim();
+        return value.length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function recentRepositoryObservations(db, repo, since) {
+    const sources = [`git:${repo.localPath}`];
+    if (repo.githubOwner && repo.githubRepo) {
+        const slug = `${repo.githubOwner}/${repo.githubRepo}`;
+        sources.push(`github:notification:${slug}`, `github:workflow:${slug}`);
+    }
+    const placeholders = sources.map(() => "?").join(", ");
+    const rows = db
+        .prepare(`SELECT source, ref, change_type, observed_at, payload, summary_text
+         FROM observations
+        WHERE observed_at >= ?
+          AND source IN (${placeholders})
+        ORDER BY observed_at ASC`)
+        .all(formatSqliteDatetime(since), ...sources);
+    return rows.map((row) => ({
+        source: row.source,
+        ref: row.ref,
+        changeType: row.change_type,
+        observedAt: row.observed_at,
+        summary: row.summary_text ?? payloadSummary(row.payload),
+    }));
+}
+function payloadSummary(payload) {
+    if (!payload)
+        return null;
+    try {
+        const parsed = JSON.parse(payload);
+        const title = parsed.title ?? parsed.subject ?? parsed.name ?? parsed.workflow;
+        return typeof title === "string" && title.trim().length > 0
+            ? title.trim()
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function renderOverview(params) {
+    const { repo, evidence, date } = params;
+    const displayName = repo.displayName ?? repo.githubRepo ?? basename(repo.localPath ?? repo.slug);
+    const commits = evidence.recentCommits.slice(0, 30);
+    const lifecycleSection = repo.classification === "project"
+        ? "\n## Lifecycle Phases\n\n- Initial documentation created from Git history.\n"
+        : "";
+    const readmeNote = evidence.readmeFileName
+        ? `- Source README: see [README.md](./README.md) (mirrored on init).`
+        : "- README not found in the repository root.";
+    return [
+        "---",
+        "type: git-project",
+        "owner: agent",
+        `repository_id: ${yamlValue(repo.id)}`,
+        `slug: ${yamlValue(repo.slug)}`,
+        `github_repo: ${yamlValue(repo.githubOwner && repo.githubRepo ? `${repo.githubOwner}/${repo.githubRepo}` : null)}`,
+        `local_path: ${yamlValue(repo.localPath)}`,
+        `classification: ${yamlValue(repo.classification)}`,
+        `category: ${yamlValue(repo.category)}`,
+        `created: ${date}`,
+        `updated: ${date}`,
+        "architecture_status: pending",
+        "architecture_refreshed_at: null",
+        "---",
+        `# ${displayName}`,
+        "",
+        "## Summary",
+        "",
+        `- Repository: ${repo.githubOwner && repo.githubRepo ? `${repo.githubOwner}/${repo.githubRepo}` : repo.localPath}`,
+        `- Default/current branch: ${evidence.currentBranch}`,
+        `- Remote: ${evidence.remoteUrl ?? "none recorded"}`,
+        `- First commit: ${evidence.firstCommitDate ?? "unknown"}`,
+        `- Last commit: ${evidence.lastCommitDate ?? "unknown"}`,
+        readmeNote,
+        "",
+        "## Architecture",
+        "",
+        ARCHITECTURE_BEGIN_MARKER,
+        "",
+        ARCHITECTURE_PLACEHOLDER,
+        "",
+        ARCHITECTURE_END_MARKER,
+        "",
+        "## Notable Changes",
+        "",
+        commits.length > 0
+            ? commits.map((commit) => `- ${commit.date} ${commit.short}: ${commit.subject}`).join("\n")
+            : "- No commits found in the sampled history.",
+        lifecycleSection.trimEnd(),
+        "## Open Threads",
+        "",
+        "- Add follow-ups that should remain visible across sessions.",
+        "",
+        "## Daily Activity Log",
+        "",
+        "- Initial documentation created from Git history.",
+        "",
+    ].filter((part) => part !== "").join("\n") + "\n";
+}
+function renderJournal(params) {
+    const { repo, date, commits, observations, prEvents, workflowEvents, statSummary } = params;
+    return [
+        "---",
+        "type: git-journal",
+        "owner: agent",
+        `repository_id: ${yamlValue(repo.id)}`,
+        `date: ${date}`,
+        `updated: ${date}`,
+        `commit_count: ${commits.length}`,
+        `pr_events: ${prEvents}`,
+        `workflow_events: ${workflowEvents}`,
+        "---",
+        `# ${date} - ${repo.slug}`,
+        "",
+        "## Commits",
+        "",
+        commits.length > 0
+            ? commits.map((commit) => `- ${commit.date} ${commit.short}: ${commit.subject} (${commit.author})`).join("\n")
+            : "- No commits in the lookback window.",
+        "",
+        "## PR / Workflow Events",
+        "",
+        observations.length > 0
+            ? observations.map((row) => `- ${row.observedAt} ${row.source} ${row.changeType} ${row.ref}${row.summary ? ` - ${row.summary}` : ""}`).join("\n")
+            : "- No PR or workflow observations in the lookback window.",
+        "",
+        "## Files Changed",
+        "",
+        statSummary.trim().length > 0 ? fenced(statSummary.trim().slice(0, MAX_STAT_BYTES)) : "- No file-change stat available.",
+        "",
+    ].join("\n") + "\n";
+}
+async function appendOverviewDailyLog(deps, params) {
+    const absolutePath = join(deps.contextDir, params.overviewPath);
+    // Serialize against `runRepositoryArchitectureSectionReplace` on the
+    // same overview file. Both follow read-modify-write, both use atomic
+    // rename on commit; without a shared lock the second writer can clobber
+    // the first by replaying a stale read. See `overview-write-lock.ts`.
+    await withOverviewWriteLock(absolutePath, () => {
+        if (!existsSync(absolutePath))
+            return;
+        const current = readFileSync(absolutePath, "utf-8");
+        const summary = `- ${params.date}: ${params.commitCount} commits; ${params.prEvents} PR/notification events; ${params.workflowEvents} workflow events.`;
+        const withoutOldSameDay = current
+            .split("\n")
+            .filter((line) => keepDailyLogLine(line, params.date))
+            .join("\n");
+        const withUpdated = replaceUpdatedDate(withoutOldSameDay, params.date);
+        const marker = "## Daily Activity Log";
+        const next = withUpdated.includes(marker)
+            ? withUpdated.replace(marker, `${marker}\n\n${summary}`)
+            : `${withUpdated.trimEnd()}\n\n${marker}\n\n${summary}\n`;
+        writeManagedContextFile(deps, params.overviewPath, next, "repository_management_scan_overview");
+    });
+}
+function keepDailyLogLine(line, today) {
+    const match = /^- (\d{4}-\d{2}-\d{2}): /.exec(line);
+    if (!match)
+        return true;
+    if (match[1] === today)
+        return false;
+    const lineMs = Date.parse(`${match[1]}T00:00:00Z`);
+    const todayMs = Date.parse(`${today}T00:00:00Z`);
+    if (!Number.isFinite(lineMs) || !Number.isFinite(todayMs))
+        return true;
+    return lineMs >= todayMs - 30 * 24 * 60 * 60 * 1000;
+}
+function writeManagedContextFile(deps, relativePath, content, trigger) {
+    const absolutePath = join(deps.contextDir, relativePath);
+    const previous = existsSync(absolutePath) ? readFileSync(absolutePath, "utf-8") : null;
+    if (previous !== null) {
+        deps.db
+            .prepare("INSERT INTO md_file_snapshots (file_path, content, trigger, session_id) VALUES (?, ?, ?, ?)")
+            .run(relativePath, previous, trigger, null);
+    }
+    writeFileAtomically(absolutePath, content);
+    deps.writeTracker?.markWriting(absolutePath, content);
+    deps.onIndexableContextChange?.(relativePath);
+}
+function replaceUpdatedDate(content, date) {
+    if (/^updated:\s*.*$/m.test(content)) {
+        return content.replace(/^updated:\s*.*$/m, `updated: ${date}`);
+    }
+    if (content.startsWith("---\n")) {
+        return content.replace(/^---\n/, `---\nupdated: ${date}\n`);
+    }
+    return content;
+}
+function yamlValue(value) {
+    return value === null ? "null" : JSON.stringify(value);
+}
+function fenced(value) {
+    return "```text\n" + value + "\n```";
+}
+function dateStamp(date, timezone) {
+    return localDateStr(date, timezone);
+}
+/**
+ * Replace the marker-bracketed `## Architecture` block in
+ * `git/<slug>/overview.md` with `markdown`. Other sections (Summary,
+ * Notable Changes, Daily Activity Log) and the YAML frontmatter are
+ * preserved; the agent only ever submits the body of the Architecture
+ * block via `PUT /api/repositories/:id/architecture-section`, the
+ * daemon owns the surgical merge.
+ *
+ * Updates `architecture_status: complete`, `architecture_refreshed_at`,
+ * and `updated:` frontmatter fields. If the overview file is missing
+ * (e.g. management init has not run yet), returns `no_overview`
+ * without writing.
+ */
+export async function runRepositoryArchitectureSectionReplace(deps, markdown) {
+    const overviewPath = gitRepoOverviewPath(deps.repo.slug);
+    const absolutePath = join(deps.contextDir, overviewPath);
+    const now = deps.now ?? new Date();
+    const refreshedAt = now.toISOString();
+    // Serialize against `appendOverviewDailyLog` (the scan flow's daily
+    // log append) on the same overview file. See `overview-write-lock.ts`
+    // for the race this prevents.
+    return withOverviewWriteLock(absolutePath, () => {
+        if (!existsSync(absolutePath)) {
+            return { status: "no_overview", overviewPath, absolutePath, refreshedAt };
+        }
+        const current = readFileSync(absolutePath, "utf-8");
+        const merged = mergeArchitectureSection(current, markdown);
+        const withFrontmatter = updateArchitectureFrontmatter(merged, {
+            refreshedAt,
+            date: dateStamp(now, deps.timezone),
+        });
+        writeManagedContextFile(deps, overviewPath, withFrontmatter, "repository_management_refresh_architecture");
+        return { status: "written", overviewPath, absolutePath, refreshedAt };
+    });
+}
+function mergeArchitectureSection(current, markdown) {
+    const beginIdx = current.indexOf(ARCHITECTURE_BEGIN_MARKER);
+    const endIdx = current.indexOf(ARCHITECTURE_END_MARKER);
+    const body = markdown.trim();
+    const block = `${ARCHITECTURE_BEGIN_MARKER}\n\n${body}\n\n${ARCHITECTURE_END_MARKER}`;
+    if (beginIdx >= 0 && endIdx > beginIdx) {
+        return (current.slice(0, beginIdx)
+            + block
+            + current.slice(endIdx + ARCHITECTURE_END_MARKER.length));
+    }
+    // Fallback: inject the block right after `## Architecture` if the
+    // markers were stripped, or append a new Architecture section before
+    // the next canonical section. Either path keeps the file usable
+    // without manual repair.
+    const headingIdx = current.indexOf("\n## Architecture\n");
+    if (headingIdx >= 0) {
+        const afterHeading = headingIdx + "\n## Architecture\n".length;
+        const nextSectionRel = findNextSectionOffset(current.slice(afterHeading));
+        const sliceEnd = nextSectionRel >= 0 ? afterHeading + nextSectionRel : current.length;
+        return (current.slice(0, afterHeading)
+            + `\n${block}\n\n`
+            + current.slice(sliceEnd));
+    }
+    // No Architecture section at all — append before Notable Changes / EOF.
+    const insertAt = current.indexOf("\n## Notable Changes\n");
+    const newSection = `\n## Architecture\n\n${block}\n`;
+    if (insertAt >= 0) {
+        return current.slice(0, insertAt) + newSection + current.slice(insertAt);
+    }
+    return current.trimEnd() + "\n" + newSection;
+}
+function findNextSectionOffset(s) {
+    // Match the start of the next `## ` heading, anchored on a newline.
+    const match = /\n## /.exec(s);
+    return match ? match.index : -1;
+}
+function updateArchitectureFrontmatter(content, params) {
+    const setField = (text, key, value) => {
+        const re = new RegExp(`^${key}:\\s*.*$`, "m");
+        if (re.test(text)) {
+            return text.replace(re, `${key}: ${value}`);
+        }
+        if (text.startsWith("---\n")) {
+            const closeIdx = text.indexOf("\n---\n", 4);
+            if (closeIdx > 0) {
+                return (text.slice(0, closeIdx)
+                    + `\n${key}: ${value}`
+                    + text.slice(closeIdx));
+            }
+        }
+        return text;
+    };
+    let next = setField(content, "architecture_status", "complete");
+    next = setField(next, "architecture_refreshed_at", JSON.stringify(params.refreshedAt));
+    next = setField(next, "updated", params.date);
+    return next;
+}
+/**
+ * Re-copy the repository's README.* into `git/<slug>/README.md`,
+ * snapshotting the previous mirror to `md_file_snapshots`. Used by both
+ * the management-init flow (initial mirror) and the architecture-refresh
+ * flow (keep mirror in sync with the source the agent just analyzed).
+ *
+ * Returns the relative context-file path on success or `null` if no
+ * README was found.
+ */
+export function copyRepositoryReadmeForRefresh(deps) {
+    const localPath = requireLocalPath(deps.repo);
+    return copyRepositoryReadme(deps, localPath);
+}
+/** Validate that a body submitted to PUT /architecture-section is well-formed. */
+export function validateArchitectureMarkdown(markdown) {
+    if (typeof markdown !== "string") {
+        return {
+            ok: false,
+            error: "validation_error",
+            message: "markdown (string) required",
+        };
+    }
+    const trimmed = markdown.trim();
+    if (trimmed.length === 0) {
+        return {
+            ok: false,
+            error: "validation_error",
+            message: "markdown must be non-empty",
+        };
+    }
+    if (Buffer.byteLength(trimmed, "utf-8") > ARCHITECTURE_SECTION_MAX_BYTES) {
+        return {
+            ok: false,
+            error: "payload_too_large",
+            message: `markdown exceeds ${ARCHITECTURE_SECTION_MAX_BYTES} bytes`,
+        };
+    }
+    if (trimmed.includes(ARCHITECTURE_BEGIN_MARKER)
+        || trimmed.includes(ARCHITECTURE_END_MARKER)) {
+        return {
+            ok: false,
+            error: "validation_error",
+            message: "markdown must not include architecture begin/end markers — submit body content only",
+        };
+    }
+    return { ok: true, body: trimmed };
+}
+export const ARCHITECTURE_MARKERS = {
+    begin: ARCHITECTURE_BEGIN_MARKER,
+    end: ARCHITECTURE_END_MARKER,
+    placeholder: ARCHITECTURE_PLACEHOLDER,
+};
+//# sourceMappingURL=repository-management-docs.js.map