Add Factory historian PR reviewer

.agentworkforce/agents/factory-feature-guardian/manifest-contract.test.ts

@@ -216,6 +216,7 @@ describe('Factory feature manifest contract', () => {
       'src/mount/relayfile-integration-preflight.ts',
       'src/state/github-lifecycle-identity.ts',
       '.agentworkforce/agents/factory-feature-guardian/',
+      '.agentworkforce/agents/factory-maintainability/',
       '.claude/skills/verify-features.md',
       'workflows/verify-features.ts',
       'scripts/verify-packed-e2e.mjs',

.agentworkforce/agents/factory-maintainability/agent.ts

@@ -0,0 +1,23 @@
+import { defineReviewAgent, gitHistory, prDiff } from '@agentworkforce/review-kit';
+
+/**
+ * Factory's maintainability historian, cloud surface.
+ *
+ * Review-kit owns the shared PR plumbing: event parsing, repository scoping,
+ * draft and skip-label gates, checkout execution, output normalization, and
+ * once-per-revision delivery. This file declares only the repository-specific
+ * review doctrine and evidence.
+ *
+ * The doctrine lives in the checked-out repository rather than this handler.
+ * That keeps the cloud reviewer aligned with Factory's versioned critical-path
+ * catalog and lets a charter change take effect without duplicating it here.
+ */
+export default defineReviewAgent({
+  repo: 'AgentWorkforce/factory',
+  charter: '.agentworkforce/workforce/personas/maintainability.md',
+  lens: 'maintainability',
+
+  // A historian needs both the proposed change and the decisions that produced
+  // the current design. The persona therefore requests the complete history.
+  evidence: [prDiff(), gitHistory()],
+});

.agentworkforce/agents/factory-maintainability/persona.json

@@ -0,0 +1,46 @@
+{
+  "id": "factory-maintainability",
+  "intent": "review",
+  "tags": [
+    "review"
+  ],
+  "description": "Reviews AgentWorkforce/factory pull requests through the maintainability lens. Comments only; never edits.",
+  "cloud": true,
+  "sandbox": true,
+  "useSubscription": true,
+  "capabilities": {
+    "pullRequest": {
+      "enabled": true,
+      "writeback": false,
+      "fetchDepth": "full"
+    }
+  },
+  "integrations": {
+    "github": {
+      "scope": {
+        "repo": "AgentWorkforce/factory"
+      },
+      "relayfileMount": {
+        "requiredReadPaths": [
+          "/github/repos/AgentWorkforce/factory/issues/**"
+        ],
+        "writeOnlyPaths": []
+      }
+    }
+  },
+  "inputs": {
+    "SKIP_LABELS": {
+      "description": "Comma-separated PR labels that disable the maintainability reviewer.",
+      "env": "SKIP_LABELS",
+      "optional": true
+    }
+  },
+  "harness": "claude",
+  "model": "claude-opus-4-8",
+  "systemPrompt": "You are the maintainability historian for this repository. You review on one axis: whether a future agent can understand and safely change this code. Your operating doctrine is the charter checked into the repo — read it and follow it exactly, including its output contract. Cite git history as evidence. You are read-only: recommend fix direction, never edit.",
+  "harnessSettings": {
+    "reasoning": "high",
+    "timeoutSeconds": 2400
+  },
+  "onEvent": "./agent.ts"
+}

.agentworkforce/agents/factory-maintainability/persona.test.ts

@@ -0,0 +1,123 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+import agent from './agent.js';
+import persona from './persona.js';
+
+type RelayfileMount = {
+  requiredReadPaths: string[];
+  writeOnlyPaths: string[];
+};
+
+type CompiledPersona = {
+  id: string;
+  capabilities?: {
+    pullRequest?: {
+      enabled?: boolean;
+      writeback?: boolean;
+      fetchDepth?: number | 'full';
+    };
+  };
+  integrations: {
+    github: {
+      scope?: { repo?: string };
+      relayfileMount?: RelayfileMount;
+    };
+  };
+  onEvent?: string;
+};
+
+const agentworkforceRoot = new URL('../../', import.meta.url);
+const expectedAuthority = '/github/repos/AgentWorkforce/factory/issues/**';
+
+function githubMount(value: typeof persona): RelayfileMount {
+  const integrations = value.integrations as Record<
+    string,
+    { relayfileMount?: RelayfileMount }
+  >;
+  const mount = integrations.github?.relayfileMount;
+  expect(mount).toBeDefined();
+  return mount as RelayfileMount;
+}
+
+function terminalTreeContains(authority: string, path: string): boolean {
+  expect(authority).toMatch(/^\/[^*?\[\]{}]+\/\*\*$/u);
+  const root = authority.slice(0, -3);
+  return path === root || path.startsWith(`${root}/`);
+}
+
+describe('factory maintainability reviewer contract', () => {
+  it('is repository-qualified, read-only, and backed by full git history', () => {
+    expect(persona.id).toBe('factory-maintainability');
+    expect(persona.integrations.github.scope).toEqual({
+      repo: 'AgentWorkforce/factory',
+    });
+    expect(persona.capabilities.pullRequest).toEqual({
+      enabled: true,
+      writeback: false,
+      fetchDepth: 'full',
+    });
+    expect(persona).not.toHaveProperty('memory');
+  });
+
+  it('wakes only for Factory PR revisions and carries the issue-comment companion', () => {
+    const triggers = agent.triggers as Record<
+      string,
+      Array<{ on: string; paths?: string[] }>
+    >;
+    const expectedPaths = [
+      '/github/repos/AgentWorkforce/factory/pulls/**',
+      expectedAuthority,
+    ];
+
+    expect(triggers.github).toEqual([
+      { on: 'pull_request.opened', paths: expectedPaths, maxConcurrency: 1 },
+      { on: 'pull_request.synchronize', paths: expectedPaths, maxConcurrency: 1 },
+    ]);
+  });
+
+  it('uses one terminal issue-tree authority for idempotency and review delivery', () => {
+    const mount = githubMount(persona);
+    expect(mount).toEqual({
+      requiredReadPaths: [expectedAuthority],
+      writeOnlyPaths: [],
+    });
+
+    const reviewPath =
+      '/github/repos/AgentWorkforce/factory/issues/180/comments/review-maintainability-deadbeef.json';
+    expect(terminalTreeContains(expectedAuthority, reviewPath)).toBe(true);
+    expect(new Set([...mount.requiredReadPaths, ...mount.writeOnlyPaths]).size).toBe(1);
+  });
+
+  it('ships a Factory-specific charter and compiled deployment manifest', () => {
+    const charter = readFileSync(
+      new URL('workforce/personas/maintainability.md', agentworkforceRoot),
+      'utf8',
+    );
+    const compiled = JSON.parse(
+      readFileSync(
+        new URL('agents/factory-maintainability/persona.json', agentworkforceRoot),
+        'utf8',
+      ),
+    ) as CompiledPersona;
+
+    expect(charter).toContain('# The Factory Maintainability Charter');
+    expect(charter).toContain('.agentworkforce/features/critical-paths.md');
+    expect(charter).not.toContain('HoopSheet');
+    expect(compiled.id).toBe('factory-maintainability');
+    expect(compiled.integrations.github.scope).toEqual({
+      repo: 'AgentWorkforce/factory',
+    });
+    expect(compiled.integrations.github.relayfileMount).toEqual({
+      requiredReadPaths: [expectedAuthority],
+      writeOnlyPaths: [],
+    });
+    expect(compiled.capabilities?.pullRequest).toEqual({
+      enabled: true,
+      writeback: false,
+      fetchDepth: 'full',
+    });
+    expect(compiled.onEvent).toBe('./agent.ts');
+  });
+});

.agentworkforce/agents/factory-maintainability/persona.ts

@@ -0,0 +1,42 @@
+import { defineReviewPersona } from '@agentworkforce/review-kit';
+
+/**
+ * Factory's maintainability historian, deployment surface.
+ *
+ * Review-kit supplies the read-only pull-request capability and exact GitHub
+ * trigger paths. GitHub represents PR comments under the issue tree, so the
+ * issues mount below is required both for revision idempotency and for posting
+ * the review. Pull hydration remains tied to the exact delivered event.
+ */
+const persona = defineReviewPersona({
+  repo: 'AgentWorkforce/factory',
+  lens: 'maintainability',
+
+  // Preserve a repository-qualified deployment identity in a workspace that
+  // hosts reviewers for multiple projects.
+  id: 'factory-maintainability',
+
+  systemPrompt:
+    'You are the maintainability historian for this repository. You review on one axis: whether a future agent can understand and safely change this code. Your operating doctrine is the charter checked into the repo — read it and follow it exactly, including its output contract. Cite git history as evidence. You are read-only: recommend fix direction, never edit.',
+
+  // Foundational safety decisions are older than the default shallow window;
+  // silently truncating them would make historical claims unreliable.
+  fetchDepth: 'full',
+
+  model: 'claude-opus-4-8',
+  harnessSettings: { reasoning: 'high', timeoutSeconds: 2400 },
+});
+
+export default {
+  ...persona,
+  integrations: {
+    ...persona.integrations,
+    github: {
+      ...persona.integrations.github,
+      relayfileMount: {
+        requiredReadPaths: ['/github/repos/AgentWorkforce/factory/issues/**'],
+        writeOnlyPaths: [],
+      },
+    },
+  },
+};

.agentworkforce/features/manifest.yaml

@@ -1,14 +1,14 @@
 version: '1.1'
 updated: '2026-07-21'
 catalog:
-  category_count: 24
-  feature_count: 300
+  category_count: 25
+  feature_count: 301
   tier_counts:
     1: 43
     2: 123
     3: 11
     4: 51
-    5: 57
+    5: 58
     6: 15
 
 # Every user-facing feature in @agent-relay/factory, categorized and scored.
@@ -50,6 +50,7 @@ verification:
     release-verification: release-verification
     verification-environments: verification-environments
     proactive-health: proactive-health
+    maintainability-review: maintainability-review
     config-intake: triage-and-configuration
     config-repositories: triage-and-configuration
     config-loop: loop-and-recovery
@@ -1702,6 +1703,18 @@ categories:
         location: .agentworkforce/agents/factory-feature-guardian/agent.ts
         verify_tier: 5
 
+  maintainability-review:
+    name: Maintainability Historian Review
+    description: Read-only, repository-scoped pull-request review against Factory's critical paths and complete git history
+    criticality: hot
+    features:
+      - id: historian-pr-reviewer
+        name: Factory Historian PR Reviewer
+        api: factory-maintainability pull_request.opened / pull_request.synchronize
+        description: Review each non-draft Factory PR once per head revision for invariant drift and lost rationale, using the checked-in charter, exact diff, and full git history without editing or merging
+        location: .agentworkforce/agents/factory-maintainability/agent.ts, .agentworkforce/agents/factory-maintainability/persona.ts, .agentworkforce/agents/factory-maintainability/persona.json, .agentworkforce/workforce/personas/maintainability.md
+        verify_tier: 5
+
   config-intake:
     name: Workspace Intake Configuration
     description: Factory source, capacity, subscription, and retry controls in factory.config.json

.agentworkforce/features/verify/procedures.md

@@ -814,6 +814,28 @@ In deployment, assert the manifest is read only from
 write only to `${SLACK_CHANNEL}`, and one scheduled tick posts one question with
 a real provider `ts` before the exact state checkpoint advances.
 
+## maintainability-review
+
+**Categories:** `maintainability-review`.
+
+**Prerequisites:** source checkout for the deterministic contract test. A live
+check additionally requires the compiled persona deployed with the scoped
+GitHub integration.
+
+```bash
+npx vitest run \
+  .agentworkforce/agents/factory-maintainability/persona.test.ts
+```
+
+Assert the source and compiled persona both identify `AgentWorkforce/factory`,
+request full PR history, disable checkout writeback, and mount only the Factory
+issue-comment tree. The handler must subscribe only to opened and synchronized
+Factory PRs, with both the exact pull and issue companion paths retained. The
+charter must point reviewers to the canonical critical-path catalog, remain
+Factory-specific, and preserve the bounded verdict-first output contract. For a
+deployed preview, deliver the same non-draft head revision twice and confirm one
+review comment; deliver a new head and confirm exactly one additional review.
+
 ## loop-and-recovery
 
 **Categories:** `config-loop`.