fix: sync updates PR bases, status parses isEmpty, STORIES.md cleanup

- Add updatePRBase() to GitHub class for updating PR base branches
- updateStackComments() now updates PR base when stack changes after merge
- STATUS_TEMPLATE now includes 'empty' field, parsed correctly
- navigateTop test updated to match new behavior (creates empty @ above stack)
- STORIES.md: removed .array/config.json (fully stateless), merged duplicate sections,
  clarified arr create requires file changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: jonathanlab

.array/config.json

@@ -122,6 +122,7 @@ Array is a thin layer over jj. It stores almost nothing.
 - Track stack state (jj DAG has it)
 - Store enabled changesets (jj merge parents)
 - Store PR mappings (derived from branch names)
+- Store repo-level config (no `.array/` directory)
 
 **Benefits:**
 - Can't get out of sync with jj
@@ -132,22 +133,29 @@ Array is a thin layer over jj. It stores almost nothing.
 **Only state Array stores:**
 - `~/.config/array/auth.json` — GitHub token
 
+**Derived state:**
+
+| Data | Source |
+|------|--------|
+| Changes, stack, DAG | jj |
+| Trunk branch | jj's `trunk()` revset |
+| PR ↔ change mapping | Derived from branch name |
+| Enabled changesets | jj DAG (merge parents) |
+
 ---
 
 ## Onboarding
 
 ### Repository Detection
-- When I run array in a directory with `.git`, it detects it as a git repo
-- When I run array in a directory without `.git`, it prompts to initialize
-- When I run array in a directory with `.jj`, it's ready to use
-- Array requires jj, that's it
+- When I run array in a directory with `.git` only, it prompts me to run `jj git init --colocate`
+- When I run array in a directory without `.git`, it prompts to run `git init && jj git init --colocate`
+- When I run array in a jj-colocated repo, it's ready to use (no `arr init` needed)
 
 ### Initialization
 - When I initialize git, a `.git` directory is created with an initial commit
 - When I initialize jj in a git repo, a `.jj` directory is created alongside `.git`
 - When I initialize jj, my existing git commits are imported
-- When I initialize jj, trunk is auto-detected (`main` or `master`) and set as `trunk()` revset
-- Array has no separate initialization — if jj is set up, Array works
+- When jj is initialized, trunk is auto-detected via jj's built-in `trunk()` revset
 
 ### Prerequisites
 - When jj is installed, I can check its version
@@ -180,19 +188,20 @@ Array is a thin layer over jj. It stores almost nothing.
 - Branch name format is `MM-DD-description_slug` (e.g., `12-22-add_user_auth`)
 
 ### Prerequisites
-- When @ has no changes and I create, I get an error ("No changes to save")
 - When I provide an empty message, I get an error
+- When @ has no file changes, I get an error "No changes to save"
 
 ### Multiple Stacks
 - When I create from trunk (empty @ above main), it starts a new stack
 - I can have multiple independent stacks off trunk
 - Each stack is a linear chain of changes
 
 ### Viewing Multiple Stacks
-- When I run `arr log`, I see ALL mutable stacks (not just current)
+- When I run `arr log`, I see only mutable stacks (not just current)
 - Each stack is visually separated with branch prefixes
 - I can see which stack I'm currently in (marked with ◉)
-- Immutable/orphaned branches are NOT shown (they're historical artifacts)
+- Immutable commits (pushed to remote) are NOT shown - use `jj log` to see them
+- Remote-tracking branches that have been merged/deleted are filtered out via `mutable()` revset
 
 ### Switching Between Stacks
 - When I run `arr checkout` with a change from another stack, I switch to that stack
@@ -212,7 +221,8 @@ Array is a thin layer over jj. It stores almost nothing.
 - When my change has multiple children and I go up, I get an error (ambiguous)
 
 ### Jumping to Ends
-- When I go to top, I get an empty @ above the topmost change (ready for new work)
+- When I go to top and @ is already empty/undescribed with no children, I stay where I am
+- When I go to top otherwise, I get an empty @ above the topmost change (via `jj new`)
 - When I go to bottom, @ becomes the first change above trunk
 - When my stack branches and I go to top, I get an error (ambiguous path)
 
@@ -248,8 +258,8 @@ Array is a thin layer over jj. It stores almost nothing.
 - When I continue with no pending operation, I get an error
 
 ### Quick Amend (arr modify)
-- When I run `arr modify`, my edits squash into @- (parent)
-- When @ has no changes, I get an error
+- When I run `arr modify`, my edits squash into @- (parent) via `jj squash`
+- When @ is empty AND has no description, I get an error "No changes to squash"
 - After modify, I'm still on empty @ (ready for more work)
 - Descendants of the modified change auto-rebase
 
@@ -381,8 +391,8 @@ Array is a thin layer over jj. It stores almost nothing.
 ### After Merge
 - When I sync after a PR merged, the merged branch is deleted locally
 - When I sync after a PR merged, my stack is rebased onto trunk
-- When I sync after a PR merged, remaining PRs have bases updated
-- When I sync after a PR merged, stack comments are updated on remaining PRs
+- When I sync after a PR merged, remaining PRs have their base branches updated to trunk via GitHub API
+- When I sync after a PR merged, stack comments are updated on remaining PRs (showing full history including merged)
 
 ### Branch Naming on GitHub
 - Branches are named `MM-DD-description_slug`
@@ -402,8 +412,8 @@ Array is a thin layer over jj. It stores almost nothing.
 - When I sync after a PR merged, trunk includes my merged changes
 - When I sync, rebasing onto new trunk makes merged changes EMPTY (no diff)
 - When I sync, empty changes are detected and abandoned (`jj abandon`)
-- When I sync, the next PR's base is updated to trunk
-- When I sync, stack comments are updated on remaining PRs
+- When I sync, the next PR's base branch is updated to trunk via GitHub API (`gh pr edit --base`)
+- When I sync, stack comments are updated on remaining PRs (showing full history including merged)
 
 ### How Merged Detection Works
 
@@ -642,48 +652,3 @@ This is stateless. jj handles the merge. Your working directory shows the combin
 - Array commands are wrappers around jj, not a replacement
 - If array gets confused, `jj log` shows the true state
 
----
-
-## Configuration
-
-### Philosophy: Stateless
-
-Array stores almost nothing. jj is the source of truth.
-
-| Data | Source | Not stored by Array |
-|------|--------|---------------------|
-| Changes, stack, DAG | jj | ✓ |
-| Trunk branch | jj's `trunk()` revset | ✓ |
-| PR ↔ change mapping | Derived from branch name | ✓ |
-| Enabled changesets | jj DAG (merge parents) | ✓ |
-
-**Why:** Less state = less bugs. jj's data model is battle-tested. Our JSON files are not.
-
-### User Config (`~/.config/array/`)
-- `auth.json` — GitHub token (only required state)
-
-### Repo Config
-- None. Array is stateless at repo level.
-- Trunk comes from jj's `trunk()` (auto-detected or user-configured in jj)
-- Branch naming is hardcoded: `MM-DD-slug`
-- Merge strategy defaults to squash (flag override if needed)
-
-### Deriving State
-
-**PR mapping:**
-```typescript
-// Branch name is deterministic from description
-const branch = generateBranchName(change.description, change.date);
-// Query GitHub for PR with that branch
-const pr = await github.findPRByBranch(branch);
-```
-
-**Enabled changesets:**
-```
-@ (your working copy)
-├── your-stack-tip
-├── agent-change     ← enabled = it's a merge parent of @
-```
-- Enable = add as merge parent
-- Disable = remove as merge parent
-- Query = check @'s parents

packages/core/STORIES.md

@@ -325,6 +325,31 @@ export class GitHub {
     }
   }
 
+  async updatePRBase(prNumber: number, newBase: string): Promise<Result<void>> {
+    try {
+      const result = await this.executor.execute(
+        "gh",
+        ["pr", "edit", String(prNumber), "--base", newBase],
+        { cwd: this.cwd },
+      );
+
+      if (result.exitCode !== 0) {
+        return err(
+          createError(
+            "COMMAND_FAILED",
+            `Failed to update PR base: ${result.stderr}`,
+          ),
+        );
+      }
+
+      return ok(undefined);
+    } catch (e) {
+      return err(
+        createError("COMMAND_FAILED", `Failed to update PR base: ${e}`),
+      );
+    }
+  }
+
   async getPRForBranch(branchName: string): Promise<Result<PRStatus | null>> {
     try {
       const result = await this.executor.execute(

packages/core/src/github.ts

@@ -152,7 +152,7 @@ export class JJ {
       isWorkingCopy: true,
       isImmutable: false,
       hasConflicts: parsed.value.hasConflicts,
-      isEmpty: false,
+      isEmpty: parsed.value.isEmpty,
       bookmarks: parsed.value.bookmarks,
     };
 
@@ -978,11 +978,13 @@ export class JJ {
 
   async getPRForBranch(
     branch: string,
-  ): Promise<Result<{ number: number; url: string } | null>> {
+  ): Promise<
+    Result<{ number: number; url: string; baseRefName: string } | null>
+  > {
     try {
       const result = await this.executor.execute(
         "gh",
-        ["pr", "list", "--head", branch, "--json", "number,url"],
+        ["pr", "list", "--head", branch, "--json", "number,url,baseRefName"],
         { cwd: this.cwd },
       );
 
@@ -995,7 +997,11 @@ export class JJ {
         return ok(null);
       }
 
-      return ok({ number: prs[0].number, url: prs[0].url });
+      return ok({
+        number: prs[0].number,
+        url: prs[0].url,
+        baseRefName: prs[0].baseRefName,
+      });
     } catch {
       return ok(null);
     }
@@ -1288,6 +1294,8 @@ export class JJ {
       changeId: string;
       prNumber: number;
       change: Changeset;
+      bookmark: string;
+      currentBase: string;
     }> = [];
 
     for (const change of stack) {
@@ -1301,6 +1309,8 @@ export class JJ {
           changeId: change.changeId,
           prNumber: prResult.value.number,
           change,
+          bookmark,
+          currentBase: prResult.value.baseRefName,
         });
       }
     }
@@ -1316,6 +1326,12 @@ export class JJ {
     for (let i = 0; i < prInfos.length; i++) {
       const prInfo = prInfos[i];
 
+      // Update PR base if needed (first PR should base on trunk, others on previous PR's branch)
+      const expectedBase = i === 0 ? this.trunk : prInfos[i - 1].bookmark;
+      if (prInfo.currentBase !== expectedBase) {
+        await github.updatePRBase(prInfo.prNumber, expectedBase);
+      }
+
       const stackEntries: StackEntry[] = prInfos.map((p, idx) => {
         const prStatus = statuses.get(p.prNumber);
         let status: StackEntry["status"] = "waiting";

packages/core/src/jj.ts

@@ -78,6 +78,7 @@ export function parseStatus(stdout: string): Result<{
   commitId: string;
   description: string;
   hasConflicts: boolean;
+  isEmpty: boolean;
   bookmarks: string[];
 }> {
   try {
@@ -88,14 +89,15 @@ export function parseStatus(stdout: string): Result<{
 
     const parts = line.split("\t");
     // Handle case where trailing empty fields are trimmed (e.g., empty bookmarks)
-    while (parts.length < 5) {
+    while (parts.length < 6) {
       parts.push("");
     }
-    if (parts.length < 5) {
+    if (parts.length < 6) {
       return err(createError("PARSE_ERROR", `Invalid status line: ${line}`));
     }
 
-    const [changeId, commitId, description, conflict, bookmarksStr] = parts;
+    const [changeId, commitId, description, conflict, empty, bookmarksStr] =
+      parts;
     // Strip * suffix from bookmarks (indicates diverged from origin)
     const bookmarks = bookmarksStr
       ? bookmarksStr
@@ -109,6 +111,7 @@ export function parseStatus(stdout: string): Result<{
       commitId,
       description,
       hasConflicts: conflict === "true",
+      isEmpty: empty === "true",
       bookmarks,
     });
   } catch (e) {

packages/core/src/parser.ts

@@ -18,6 +18,7 @@ export const STATUS_TEMPLATE = `${[
   "commit_id.short()",
   "description.first_line()",
   "conflict",
+  "empty",
   'local_bookmarks.join(",")',
 ].join(' ++ "\\t" ++ ')} ++ "\\n"`;
 

packages/core/src/templates.ts

@@ -273,10 +273,16 @@ describe("Checkout/Edit", () => {
       await jj.navigateDown();
       expect(unwrap(await jj.getWorkingCopyId())).toBe(firstId);
 
-      // Navigate to top - should go to Third
+      // Navigate to top - should create empty @ above Third (ready for new work)
       const topResult = await jj.navigateTop();
       expect(topResult.ok).toBe(true);
-      expect(unwrap(await jj.getWorkingCopyId())).toBe(thirdId);
+      const topId = unwrap(await jj.getWorkingCopyId());
+      expect(topId).not.toBe(thirdId); // Should be a new change, not Third
+
+      // Verify we're above Third (Third is our parent)
+      const status = unwrap(await jj.status());
+      expect(status.workingCopy.isEmpty).toBe(true);
+      expect(status.workingCopy.parents).toContain(thirdId);
     });
 
     it("navigates to bottom of stack", async () => {