diff --git a/.changeset/upstream-auto-sync.md b/.changeset/upstream-auto-sync.md
new file mode 100644
index 000000000..4309fe176
--- /dev/null
+++ b/.changeset/upstream-auto-sync.md
@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-sdk": minor
+---
+
+feat: bidirectional upstream sync + auto-propagation (#357)
diff --git a/docs/blog/2026-03-17-upstream-sync.md b/docs/blog/2026-03-17-upstream-sync.md
new file mode 100644
index 000000000..f7ea279d4
--- /dev/null
+++ b/docs/blog/2026-03-17-upstream-sync.md
@@ -0,0 +1,128 @@
+---
+title: "Upstream Auto-Sync: Keep Squads in Sync"
+date: 2026-03-17
+author: "Squad (Copilot)"
+wave: null
+tags: [squad, sync, orchestration, parent-child, automation]
+status: published
+hero: "Upstream sync enables bidirectional change detection and synchronization between parent and child squads. Detect updates automatically, pull selectively, and propose changes back with a single command."
+---
+
+# Upstream Auto-Sync: Keep Squads in Sync
+
+> _Child squads detect parent changes automatically, pull updates selectively, and propose changes back upstream—no manual diff hunting required._
+
+## The Problem
+
+Many organizations structure squads hierarchically: a parent squad defines shared governance and patterns, while child squads inherit and customize for their teams. Today, keeping them in sync requires manual work:
+
+- Child squads periodically check if parent changed
+- No clear way to decide what to pull (skills vs. governance vs. all)
+- When child squads learn something valuable, proposing it back upstream means manual PR creation with copy-paste
+- Multiple child squads quickly drift from parent, creating inconsistency
+
+Upstream auto-sync solves this with **automatic change detection and bidirectional sync**.
+
+## How It Works
+
+### Register a Parent
+
+```bash
+squad upstream add https://github.com/org/parent-squad --name parent
+```
+
+The squad clones the parent (once) and stores metadata in `.squad/upstream.json`.
+
+### Watch for Changes
+
+```bash
+squad upstream watch --interval 10 --auto-pr
+```
+
+The watcher:
+1. Polls the parent repo every 10 seconds
+2. Hashes files in key directories (`.squad/`, `docs/`, `lib/`)
+3. Detects additions, changes, deletions
+4. Optionally creates a PR in your squad with the updates
+
+### Propose Changes Back
+
+```bash
+squad upstream propose parent --skills --decisions
+```
+
+Your squad packages its learnings (skills, decisions, or all) and creates a PR in the parent for review and merge.
+
+## Real-World Example
+
+### Monorepo Pattern
+
+An organization has:
+- **parent-squad**: Defines shared conventions, governance, and base skills
+- **team-a-squad**: Inherits from parent, customizes for Team A's workflow
+- **team-b-squad**: Inherits from parent, customizes for Team B's workflow
+
+**Day 1:** Both teams sync from parent
+```bash
+squad upstream sync parent
+```
+
+**Day 3:** Parent squad learns a valuable skill (e.g., "jest-mocking-patterns")
+- Parent updates its `.ai-team/skills/jest-mocking-patterns/SKILL.md`
+- Child squads detect the change via `squad upstream watch`
+- Child squads auto-pull the new skill
+
+**Day 5:** Team A discovers an improvement to governance
+```bash
+squad upstream propose parent --decisions
+```
+- Team A's squad creates a PR in parent with the governance update
+- Parent merges it
+- Team B detects the change and auto-pulls it next watch cycle
+
+## Configuration
+
+Upstreams live in `.squad/upstream.json`:
+
+```json
+{
+  "upstreams": [
+    {
+      "name": "parent",
+      "source": "https://github.com/org/parent-squad",
+      "ref": "main",
+      "lastSync": "2026-03-17T10:30:00Z"
+    }
+  ]
+}
+```
+
+## GitHub Actions Integration
+
+For teams using GitHub, automate the watch with a cron job:
+
+```bash
+squad upstream init-ci
+```
+
+This generates `.github/workflows/squad-upstream-sync.yml` that runs every 6 hours and auto-creates PRs when changes are detected.
+
+## Technical Design
+
+Upstream sync uses **file hashing** instead of git diff:
+
+- **Speed**: Hash-based detection is fast (no clone on every check)
+- **Flexibility**: Works with git repos, local paths, and exported squads
+- **Safety**: No merge conflicts—sync creates a PR for human review
+
+How it works:
+1. Parent is cloned to `.squad/_upstream_repos/{name}/` (once)
+2. Files in `.squad/`, `docs/`, `scripts/` are hashed
+3. Hash changed? → Create PR with the diff
+4. User reviews and merges
+
+## See Also
+
+- [Generic Scheduler](/features/generic-scheduler) — Run upstream sync as a scheduled task
+- [Cross-Squad Orchestration](/features/cross-squad-orchestration) — Delegate work across squads
+- [Persistent Ralph](/features/persistent-ralph) — Monitor all squad activity
diff --git a/docs/features/upstream-sync.md b/docs/features/upstream-sync.md
new file mode 100644
index 000000000..05dc07dfc
--- /dev/null
+++ b/docs/features/upstream-sync.md
@@ -0,0 +1,171 @@
+# Upstream Auto-Sync
+
+**Try this to see configured upstreams:**
+```
+squad upstream list
+```
+
+**Try this to watch for parent changes:**
+```
+squad upstream watch --interval 10 --auto-pr
+```
+
+**Try this to propose changes back:**
+```
+squad upstream propose --all
+```
+
+Upstream sync keeps your squad in sync with parent repositories. Detect changes automatically, pull them into your squad, and propose your own changes back upstream with minimal friction.
+
+---
+
+## What Upstream Sync Does
+
+Upstream sync enables **bidirectional synchronization** between parent and child squads. Register a parent repository (local path or git URL), and your squad can:
+
+1. **Detect changes** in the parent using fast file hashing
+2. **Pull updates** selectively (skills, decisions, governance, or all)
+3. **Propose changes** back to the parent repo as a pull request
+4. **Monitor continuously** with an optional GitHub Action cron job
+
+## Quick Start
+
+### Register a Parent Upstream
+
+```bash
+squad upstream add https://github.com/org/parent-squad --name parent
+```
+
+For a local path:
+```bash
+squad upstream add ../parent-squad --name local-parent
+```
+
+View registered upstreams:
+```bash
+squad upstream list
+```
+
+### Sync Now
+
+Pull updates from all registered upstreams:
+```bash
+squad upstream sync
+```
+
+Sync a specific upstream:
+```bash
+squad upstream sync parent
+```
+
+### Watch for Changes
+
+Start watching for parent changes every 10 seconds:
+```bash
+squad upstream watch --interval 10
+```
+
+Auto-create a PR when changes are detected:
+```bash
+squad upstream watch --auto-pr
+```
+
+The `watch` command runs until stopped (Ctrl+C), continuously polling for new changes.
+
+### Propose Changes Upstream
+
+Package your squad's learnings to propose back:
+
+All learnings:
+```bash
+squad upstream propose parent --all
+```
+
+Just skills and decisions:
+```bash
+squad upstream propose parent --skills --decisions
+```
+
+The proposal creates a pull request in the parent repository with your changes, formatted for easy review.
+
+## Configuration
+
+Upstreams are stored in `.squad/upstream.json`:
+
+```json
+{
+  "upstreams": [
+    {
+      "name": "parent",
+      "source": "https://github.com/org/parent-squad",
+      "ref": "main",
+      "lastSync": "2026-03-17T10:30:00Z"
+    },
+    {
+      "name": "local",
+      "source": "../parent-squad",
+      "ref": "main",
+      "lastSync": "2026-03-17T10:20:00Z"
+    }
+  ]
+}
+```
+
+- **name**: Identifier for this upstream
+- **source**: Git URL or local filesystem path
+- **ref**: Branch/tag to track (defaults to `main`)
+- **lastSync**: ISO timestamp of last successful sync
+
+## GitHub Actions Integration
+
+Automate upstream sync with a scheduled workflow:
+
+```bash
+squad upstream init-ci
+```
+
+This creates `.github/workflows/squad-upstream-sync.yml` configured to:
+- Run every 6 hours via cron
+- Sync all registered upstreams
+- Auto-create pull requests when changes found
+- Post summaries to GitHub Issues
+
+Customize the schedule and PR behavior in the generated workflow.
+
+## How Change Detection Works
+
+Upstream sync uses **file hashing** (not git diff) for fast, cross-source change detection:
+
+1. Clone/read the parent repo to `.squad/_upstream_repos/{name}/`
+2. Hash all files in key directories (`.squad/`, `docs/`, etc.)
+3. Compare hashes to last known state
+4. If changes found, optionally create PR
+
+This approach works whether the parent is:
+- A remote git repository (over HTTPS/SSH)
+- A local filesystem path
+- An exported squad (local directory)
+
+## Use Cases
+
+### Monorepo Pattern
+- Parent squad defines shared governance, patterns, and skills
+- Child squads inherit and customize
+- Run `squad upstream sync parent` when parent updates
+- Propose back when child squad learns something valuable
+
+### Distributed Teams
+- Each team has their own squad (local branch)
+- Central squad acts as coordinator
+- Cross-team discoveries flow back via `squad upstream propose`
+
+### Export & Reuse
+- Export a proven squad from one org
+- Import into new org via upstream sync
+- Continue receiving updates from original
+
+## See Also
+
+- [Cross-Squad Orchestration](/features/cross-squad-orchestration) — delegate work across squads
+- [Persistent Ralph](/features/persistent-ralph) — track squad activity
+- [Generic Scheduler](/features/generic-scheduler) — run scheduled sync tasks
diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts
index ffd3524d8..e54fe0c10 100644
--- a/packages/squad-cli/src/cli-entry.ts
+++ b/packages/squad-cli/src/cli-entry.ts
@@ -198,6 +198,8 @@ async function main(): Promise<void> {
     console.log(`                    upstream remove <name>`);
     console.log(`                    upstream list`);
     console.log(`                    upstream sync [name]`);
+    console.log(`                    upstream watch [--interval N] [--auto-pr]`);
+    console.log(`                    upstream propose <name> [--skills] [--decisions] [--governance] [--all]`);
 
     console.log(`  ${BOLD}help${RESET}       Show this help message`);
     console.log(`\nFlags:`);
diff --git a/packages/squad-cli/src/cli/commands/upstream.ts b/packages/squad-cli/src/cli/commands/upstream.ts
index e8d6e32de..247a4e56c 100644
--- a/packages/squad-cli/src/cli/commands/upstream.ts
+++ b/packages/squad-cli/src/cli/commands/upstream.ts
@@ -6,6 +6,8 @@
  *   squad upstream remove <name>
  *   squad upstream list
  *   squad upstream sync [name]
+ *   squad upstream watch [--interval N] [--auto-pr]
+ *   squad upstream propose <name> [--skills] [--decisions] [--governance] [--all]
  *
  * @module cli/commands/upstream
  */
@@ -72,8 +74,8 @@ function ensureGitignoreEntry(repoDir: string, entry: string): void {
 
 export async function upstreamCommand(args: string[]): Promise<void> {
   const action = args[0];
-  if (!action || !['add', 'remove', 'list', 'sync'].includes(action)) {
-    fatal('Usage: squad upstream add|remove|list|sync');
+  if (!action || !['add', 'remove', 'list', 'sync', 'watch', 'propose'].includes(action)) {
+    fatal('Usage: squad upstream add|remove|list|sync|watch|propose');
     return;
   }
 
@@ -243,4 +245,136 @@ export async function upstreamCommand(args: string[]): Promise<void> {
     writeUpstreams(upstreamFile, data);
     info(`\n${synced}/${toSync.length} upstream(s) synced.\n`);
   }
+
+  if (action === 'watch') {
+    const {
+      createWatchState,
+      runWatchCycle,
+      parseSyncConfig,
+    } = await import('@bradygaster/squad-sdk/upstream' as string);
+
+    const syncConfig = parseSyncConfig(squadDir);
+
+    // Parse CLI flags
+    const intervalIdx = args.indexOf('--interval');
+    const interval = (intervalIdx !== -1 && args[intervalIdx + 1])
+      ? parseInt(args[intervalIdx + 1]!, 10)
+      : syncConfig.interval;
+
+    if (isNaN(interval) || interval < 10) {
+      fatal('--interval must be a number >= 10 (seconds)');
+      return;
+    }
+
+    const autoPr = args.includes('--auto-pr') || syncConfig.autoPr;
+
+    const data = readUpstreams(upstreamFile);
+    if (data.upstreams.length === 0) {
+      fatal('No upstreams configured. Run "squad upstream add <source>" first.');
+      return;
+    }
+
+    info(`\n🔄 Watching ${data.upstreams.length} upstream(s) every ${interval}s${autoPr ? ' (auto-PR enabled)' : ''}...\n`);
+
+    const state = createWatchState();
+
+    // Initial snapshot (first cycle always reports no changes)
+    runWatchCycle(squadDir, state);
+    info('📸 Initial snapshot captured. Watching for changes...\n');
+
+    const runCycle = (round: number) => {
+      const result = runWatchCycle(squadDir, state);
+      if (result.hasAnyChanges) {
+        info(`\n🔔 Changes detected (round ${round}):`);
+        for (const d of result.detections) {
+          if (d.hasChanges) {
+            success(`  ${d.name}: ${d.changedFiles.length} file(s) changed`);
+            for (const f of d.changedFiles.slice(0, 10)) {
+              info(`    • ${f}`);
+            }
+            if (d.changedFiles.length > 10) {
+              info(`    ... and ${d.changedFiles.length - 10} more`);
+            }
+          }
+        }
+        if (autoPr) {
+          info('  📝 Auto-PR: would create PR (requires gh CLI integration)');
+        }
+      } else {
+        info(`⏳ Round ${round}: no changes detected`);
+      }
+    };
+
+    // Run first check immediately after snapshot
+    let round = 1;
+    const timer = setInterval(() => {
+      runCycle(round++);
+    }, interval * 1000);
+
+    // Handle graceful shutdown
+    const cleanup = () => {
+      clearInterval(timer);
+      info('\n👋 Watch stopped.');
+      process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+
+    // Keep alive — the interval will run until interrupted
+    await new Promise<void>(() => {
+      // Intentionally never resolves — watch runs until SIGINT/SIGTERM
+    });
+  }
+
+  if (action === 'propose') {
+    const {
+      packageProposal,
+      parseProposeConfig,
+    } = await import('@bradygaster/squad-sdk/upstream' as string);
+
+    const targetName = args[1];
+    if (!targetName) {
+      fatal('Usage: squad upstream propose <upstream-name> [--skills] [--decisions] [--governance] [--all]');
+      return;
+    }
+
+    const data = readUpstreams(upstreamFile);
+    if (!data.upstreams.some(u => u.name === targetName)) {
+      fatal(`Upstream "${targetName}" not found. Run "squad upstream list" to see configured upstreams.`);
+      return;
+    }
+
+    // Parse scope flags
+    const useAll = args.includes('--all');
+    const scope = {
+      skills: useAll || args.includes('--skills'),
+      decisions: useAll || args.includes('--decisions'),
+      governance: useAll || args.includes('--governance'),
+    };
+
+    // If no flags specified, default to what the config allows
+    if (!scope.skills && !scope.decisions && !scope.governance) {
+      const proposeConfig = parseProposeConfig(squadDir);
+      scope.skills = proposeConfig.scope.skills;
+      scope.decisions = proposeConfig.scope.decisions;
+      scope.governance = proposeConfig.scope.governance;
+    }
+
+    info(`\n📦 Packaging proposal for upstream "${targetName}"...\n`);
+
+    const proposal = packageProposal(squadDir, targetName, scope);
+    if (!proposal) {
+      warn('No files to propose. Check your .squad/ directory and scope flags.');
+      return;
+    }
+
+    success(`Proposal packaged: ${proposal.summary}`);
+    info(`  Branch: ${proposal.branchName}`);
+    info(`  Files (${proposal.files.length}):`);
+    for (const f of proposal.files) {
+      info(`    • ${f.path}`);
+    }
+    info('\n💡 To submit: use "gh pr create" on the upstream repo with these changes.');
+    info('   (Automated PR creation requires gh CLI authentication to the parent repo)\n');
+  }
 }
diff --git a/packages/squad-sdk/src/upstream/index.ts b/packages/squad-sdk/src/upstream/index.ts
index 6f1320852..5661cde0e 100644
--- a/packages/squad-sdk/src/upstream/index.ts
+++ b/packages/squad-sdk/src/upstream/index.ts
@@ -18,3 +18,38 @@ export {
   buildInheritedContextBlock,
   buildSessionDisplay,
 } from './resolver.js';
+
+export type {
+  UpstreamSyncConfig,
+  UpstreamChangeDetection,
+  WatchCycleResult,
+  UpstreamProposeScope,
+  UpstreamProposeConfig,
+  ProposePackage,
+} from './sync-types.js';
+
+export {
+  DEFAULT_SYNC_CONFIG,
+  DEFAULT_PROPOSE_CONFIG,
+} from './sync-types.js';
+
+export {
+  hashFile,
+  collectFileHashes,
+  diffHashes,
+  resolveUpstreamSquadPath,
+  getGitHeadSha,
+  pullGitUpstream,
+  createWatchState,
+  checkUpstreamForChanges,
+  runWatchCycle,
+  parseSyncConfig,
+} from './watcher.js';
+export type { WatchState } from './watcher.js';
+
+export {
+  parseProposeConfig,
+  collectProposalFiles,
+  buildProposalSummary,
+  packageProposal,
+} from './proposer.js';
diff --git a/packages/squad-sdk/src/upstream/proposer.ts b/packages/squad-sdk/src/upstream/proposer.ts
new file mode 100644
index 000000000..c8b336fb9
--- /dev/null
+++ b/packages/squad-sdk/src/upstream/proposer.ts
@@ -0,0 +1,159 @@
+/**
+ * Upstream proposer — packages child squad changes for upstream PR.
+ *
+ * Phase 2 of bidirectional sync: child → parent proposal.
+ * Reads local .squad/ content and packages it for an upstream PR.
+ *
+ * @module upstream/proposer
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { UpstreamSource } from './types.js';
+import type {
+  UpstreamProposeConfig,
+  UpstreamProposeScope,
+  ProposePackage,
+} from './sync-types.js';
+import { DEFAULT_PROPOSE_CONFIG } from './sync-types.js';
+import { readUpstreamConfig } from './resolver.js';
+
+/**
+ * Parse propose configuration from upstream-config.json, merged with defaults.
+ */
+export function parseProposeConfig(squadDir: string): UpstreamProposeConfig {
+  const configPath = path.join(squadDir, 'upstream-config.json');
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_PROPOSE_CONFIG };
+
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as Partial<{
+      propose: Partial<UpstreamProposeConfig & { scope: Partial<UpstreamProposeScope> }>;
+    }>;
+    return {
+      scope: {
+        skills: raw.propose?.scope?.skills ?? DEFAULT_PROPOSE_CONFIG.scope.skills,
+        decisions: raw.propose?.scope?.decisions ?? DEFAULT_PROPOSE_CONFIG.scope.decisions,
+        governance: raw.propose?.scope?.governance ?? DEFAULT_PROPOSE_CONFIG.scope.governance,
+      },
+      targetBranch: raw.propose?.targetBranch ?? DEFAULT_PROPOSE_CONFIG.targetBranch,
+      branchPrefix: raw.propose?.branchPrefix ?? DEFAULT_PROPOSE_CONFIG.branchPrefix,
+    };
+  } catch {
+    return { ...DEFAULT_PROPOSE_CONFIG };
+  }
+}
+
+/**
+ * Collect files from the local .squad/ that match the given scope flags.
+ */
+export function collectProposalFiles(
+  squadDir: string,
+  scope: { skills: boolean; decisions: boolean; governance: boolean },
+): Array<{ path: string; content: string }> {
+  const files: Array<{ path: string; content: string }> = [];
+
+  if (scope.skills) {
+    const skillsDir = path.join(squadDir, 'skills');
+    if (fs.existsSync(skillsDir)) {
+      for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+          files.push({
+            path: `skills/${entry.name}/SKILL.md`,
+            content: fs.readFileSync(skillFile, 'utf8'),
+          });
+        }
+      }
+    }
+  }
+
+  if (scope.decisions) {
+    const decisionsPath = path.join(squadDir, 'decisions.md');
+    if (fs.existsSync(decisionsPath)) {
+      files.push({
+        path: 'decisions.md',
+        content: fs.readFileSync(decisionsPath, 'utf8'),
+      });
+    }
+  }
+
+  if (scope.governance) {
+    const routingPath = path.join(squadDir, 'routing.md');
+    if (fs.existsSync(routingPath)) {
+      files.push({
+        path: 'routing.md',
+        content: fs.readFileSync(routingPath, 'utf8'),
+      });
+    }
+
+    const castingPath = path.join(squadDir, 'casting', 'policy.json');
+    if (fs.existsSync(castingPath)) {
+      files.push({
+        path: 'casting/policy.json',
+        content: fs.readFileSync(castingPath, 'utf8'),
+      });
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Build a human-readable summary of what's being proposed.
+ */
+export function buildProposalSummary(
+  files: Array<{ path: string; content: string }>,
+): string {
+  const skills = files.filter(f => f.path.startsWith('skills/'));
+  const decisions = files.filter(f => f.path === 'decisions.md');
+  const governance = files.filter(f => f.path === 'routing.md' || f.path === 'casting/policy.json');
+
+  const parts: string[] = [];
+  if (skills.length > 0) {
+    parts.push(`${skills.length} skill${skills.length > 1 ? 's' : ''}`);
+  }
+  if (decisions.length > 0) parts.push('decisions');
+  if (governance.length > 0) {
+    parts.push(`governance (${governance.map(f => f.path).join(', ')})`);
+  }
+
+  return parts.length > 0
+    ? `Proposing: ${parts.join(', ')}`
+    : 'No files to propose';
+}
+
+/**
+ * Package a proposal for a specific upstream target.
+ *
+ * @param squadDir - The local .squad/ directory
+ * @param upstreamName - Name of the target upstream
+ * @param scope - What content to include
+ * @returns The packaged proposal, or null if upstream not found
+ */
+export function packageProposal(
+  squadDir: string,
+  upstreamName: string,
+  scope: { skills: boolean; decisions: boolean; governance: boolean },
+): ProposePackage | null {
+  const config = readUpstreamConfig(squadDir);
+  if (!config) return null;
+
+  const upstream = config.upstreams.find(u => u.name === upstreamName);
+  if (!upstream) return null;
+
+  const proposeConfig = parseProposeConfig(squadDir);
+  const files = collectProposalFiles(squadDir, scope);
+
+  if (files.length === 0) return null;
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const branchName = `${proposeConfig.branchPrefix}/${timestamp}`;
+
+  return {
+    upstreamName,
+    branchName,
+    files,
+    summary: buildProposalSummary(files),
+  };
+}
diff --git a/packages/squad-sdk/src/upstream/sync-types.ts b/packages/squad-sdk/src/upstream/sync-types.ts
new file mode 100644
index 000000000..8aa06b33c
--- /dev/null
+++ b/packages/squad-sdk/src/upstream/sync-types.ts
@@ -0,0 +1,88 @@
+/**
+ * Types for bidirectional upstream sync + auto-propagation.
+ *
+ * Phase 1: Auto-sync (parent → child) — watch & poll for upstream changes.
+ * Phase 2: Bidirectional (child → parent) — propose child changes upstream.
+ *
+ * @module upstream/sync-types
+ */
+
+/** Configuration for upstream watch/auto-sync behaviour. */
+export interface UpstreamSyncConfig {
+  /** Polling interval in seconds (default: 600). */
+  interval: number;
+  /** Automatically create a PR when changes are detected. */
+  autoPr: boolean;
+  /** Branch name prefix for sync branches (default: "squad/upstream-sync"). */
+  branchPrefix: string;
+}
+
+/** Result of checking a single upstream for changes. */
+export interface UpstreamChangeDetection {
+  /** Name of the upstream source. */
+  name: string;
+  /** Whether changes were detected. */
+  hasChanges: boolean;
+  /** List of changed file paths (relative to .squad/). */
+  changedFiles: string[];
+  /** New commit SHA (for git upstreams), or null. */
+  newSha: string | null;
+  /** Previous commit SHA (for git upstreams), or null. */
+  previousSha: string | null;
+}
+
+/** Result of a single watch poll cycle. */
+export interface WatchCycleResult {
+  /** Timestamp of this cycle. */
+  timestamp: string;
+  /** Per-upstream change detection results. */
+  detections: UpstreamChangeDetection[];
+  /** Whether any upstream had changes. */
+  hasAnyChanges: boolean;
+}
+
+/** Scope control for what a child can propose upstream. */
+export interface UpstreamProposeScope {
+  /** Allow proposing skills. */
+  skills: boolean;
+  /** Allow proposing decisions. */
+  decisions: boolean;
+  /** Allow proposing governance (routing, casting). */
+  governance: boolean;
+}
+
+/** Configuration for upstream propose (child → parent). */
+export interface UpstreamProposeConfig {
+  /** Scope control — what the child is allowed to propose. */
+  scope: UpstreamProposeScope;
+  /** Default target branch on the parent repo (default: "main"). */
+  targetBranch: string;
+  /** Branch name prefix for proposal branches (default: "squad/child-propose"). */
+  branchPrefix: string;
+}
+
+/** Result of packaging a proposal. */
+export interface ProposePackage {
+  /** Name of the upstream target. */
+  upstreamName: string;
+  /** Branch name created for the proposal. */
+  branchName: string;
+  /** Files included in the proposal. */
+  files: Array<{ path: string; content: string }>;
+  /** Human-readable summary of what's being proposed. */
+  summary: string;
+}
+
+/** Default sync configuration values. */
+export const DEFAULT_SYNC_CONFIG: UpstreamSyncConfig = {
+  interval: 600,
+  autoPr: false,
+  branchPrefix: 'squad/upstream-sync',
+};
+
+/** Default propose configuration values. */
+export const DEFAULT_PROPOSE_CONFIG: UpstreamProposeConfig = {
+  scope: { skills: true, decisions: true, governance: false },
+  targetBranch: 'main',
+  branchPrefix: 'squad/child-propose',
+};
diff --git a/packages/squad-sdk/src/upstream/watcher.ts b/packages/squad-sdk/src/upstream/watcher.ts
new file mode 100644
index 000000000..ca4ac3c77
--- /dev/null
+++ b/packages/squad-sdk/src/upstream/watcher.ts
@@ -0,0 +1,225 @@
+/**
+ * Upstream watcher — polls parent repos for changes in their .squad/ directory.
+ *
+ * Phase 1 of bidirectional sync: parent → child auto-propagation.
+ * Detects changes by comparing file hashes of the upstream's .squad/ contents.
+ *
+ * @module upstream/watcher
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import type { UpstreamConfig, UpstreamSource } from './types.js';
+import type {
+  UpstreamChangeDetection,
+  WatchCycleResult,
+  UpstreamSyncConfig,
+} from './sync-types.js';
+import { DEFAULT_SYNC_CONFIG } from './sync-types.js';
+import { readUpstreamConfig } from './resolver.js';
+
+/** Hash a file's content for change detection. */
+export function hashFile(filePath: string): string {
+  const content = fs.readFileSync(filePath, 'utf8');
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 12);
+}
+
+/** Recursively collect all files under a directory with their hashes. */
+export function collectFileHashes(dir: string): Map<string, string> {
+  const hashes = new Map<string, string>();
+  if (!fs.existsSync(dir)) return hashes;
+
+  function walk(current: string, prefix: string): void {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name);
+      const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        // Skip _upstream_repos and .git
+        if (entry.name === '_upstream_repos' || entry.name === '.git') continue;
+        walk(fullPath, relPath);
+      } else {
+        hashes.set(relPath, hashFile(fullPath));
+      }
+    }
+  }
+
+  walk(dir, '');
+  return hashes;
+}
+
+/** Compare two sets of file hashes and return changed file paths. */
+export function diffHashes(
+  previous: Map<string, string>,
+  current: Map<string, string>,
+): string[] {
+  const changed: string[] = [];
+
+  // Files added or modified
+  for (const [file, hash] of current) {
+    if (!previous.has(file) || previous.get(file) !== hash) {
+      changed.push(file);
+    }
+  }
+
+  // Files removed
+  for (const file of previous.keys()) {
+    if (!current.has(file)) {
+      changed.push(file);
+    }
+  }
+
+  return changed.sort();
+}
+
+/**
+ * Resolve the .squad/ directory path for an upstream source.
+ * For local upstreams: source/.squad/
+ * For git upstreams: squadDir/_upstream_repos/{name}/.squad/
+ */
+export function resolveUpstreamSquadPath(
+  upstream: UpstreamSource,
+  squadDir: string,
+): string | null {
+  if (upstream.type === 'local') {
+    const squadPath = path.join(upstream.source, '.squad');
+    return fs.existsSync(squadPath) ? squadPath : null;
+  }
+  if (upstream.type === 'git') {
+    const cloneDir = path.join(squadDir, '_upstream_repos', upstream.name);
+    const squadPath = path.join(cloneDir, '.squad');
+    return fs.existsSync(squadPath) ? squadPath : null;
+  }
+  return null;
+}
+
+/** Get the current git HEAD SHA for a cloned upstream repo. */
+export function getGitHeadSha(repoDir: string): string | null {
+  try {
+    return execFileSync('git', ['-C', repoDir, 'rev-parse', 'HEAD'], {
+      stdio: 'pipe',
+      timeout: 10000,
+    }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Pull latest changes for a git upstream repo. Returns new HEAD SHA or null on failure. */
+export function pullGitUpstream(repoDir: string): string | null {
+  try {
+    execFileSync('git', ['-C', repoDir, 'pull', '--ff-only'], {
+      stdio: 'pipe',
+      timeout: 60000,
+    });
+    return getGitHeadSha(repoDir);
+  } catch {
+    return null;
+  }
+}
+
+/** State store for tracking previous file hashes between poll cycles. */
+export interface WatchState {
+  /** Per-upstream file hash snapshots from last successful check. */
+  snapshots: Map<string, Map<string, string>>;
+}
+
+/** Create a fresh watch state. */
+export function createWatchState(): WatchState {
+  return { snapshots: new Map() };
+}
+
+/**
+ * Check a single upstream for changes.
+ */
+export function checkUpstreamForChanges(
+  upstream: UpstreamSource,
+  squadDir: string,
+  state: WatchState,
+): UpstreamChangeDetection {
+  const result: UpstreamChangeDetection = {
+    name: upstream.name,
+    hasChanges: false,
+    changedFiles: [],
+    newSha: null,
+    previousSha: null,
+  };
+
+  // For git upstreams, pull first
+  if (upstream.type === 'git') {
+    const cloneDir = path.join(squadDir, '_upstream_repos', upstream.name);
+    if (fs.existsSync(path.join(cloneDir, '.git'))) {
+      result.previousSha = getGitHeadSha(cloneDir);
+      const newSha = pullGitUpstream(cloneDir);
+      result.newSha = newSha;
+    }
+  }
+
+  // Resolve the .squad/ path
+  const upstreamSquadPath = resolveUpstreamSquadPath(upstream, squadDir);
+  if (!upstreamSquadPath) return result;
+
+  // Collect current file hashes
+  const currentHashes = collectFileHashes(upstreamSquadPath);
+  const previousHashes = state.snapshots.get(upstream.name) ?? new Map<string, string>();
+
+  // Diff
+  const changedFiles = diffHashes(previousHashes, currentHashes);
+  result.hasChanges = changedFiles.length > 0;
+  result.changedFiles = changedFiles;
+
+  // Update state
+  state.snapshots.set(upstream.name, currentHashes);
+
+  return result;
+}
+
+/**
+ * Run a single poll cycle — check all configured upstreams for changes.
+ */
+export function runWatchCycle(
+  squadDir: string,
+  state: WatchState,
+): WatchCycleResult {
+  const config = readUpstreamConfig(squadDir);
+  if (!config) {
+    return {
+      timestamp: new Date().toISOString(),
+      detections: [],
+      hasAnyChanges: false,
+    };
+  }
+
+  const detections: UpstreamChangeDetection[] = [];
+  for (const upstream of config.upstreams) {
+    detections.push(checkUpstreamForChanges(upstream, squadDir, state));
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    detections,
+    hasAnyChanges: detections.some(d => d.hasChanges),
+  };
+}
+
+/**
+ * Parse sync configuration from upstream-config.json, merged with defaults.
+ */
+export function parseSyncConfig(squadDir: string): UpstreamSyncConfig {
+  const configPath = path.join(squadDir, 'upstream-config.json');
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_SYNC_CONFIG };
+
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as Partial<{
+      sync: Partial<UpstreamSyncConfig>;
+    }>;
+    return {
+      interval: raw.sync?.interval ?? DEFAULT_SYNC_CONFIG.interval,
+      autoPr: raw.sync?.autoPr ?? DEFAULT_SYNC_CONFIG.autoPr,
+      branchPrefix: raw.sync?.branchPrefix ?? DEFAULT_SYNC_CONFIG.branchPrefix,
+    };
+  } catch {
+    return { ...DEFAULT_SYNC_CONFIG };
+  }
+}
diff --git a/templates/squad-upstream-sync.yml b/templates/squad-upstream-sync.yml
new file mode 100644
index 000000000..9cba75725
--- /dev/null
+++ b/templates/squad-upstream-sync.yml
@@ -0,0 +1,97 @@
+# Squad Upstream Sync — GitHub Action template
+#
+# Periodically checks parent Squad repos for changes and opens PRs.
+# Generated by: squad upstream watch --auto-pr (GitHub Action mode)
+#
+# Usage:
+#   1. Copy this file to .github/workflows/squad-upstream-sync.yml
+#   2. Adjust the cron schedule as needed
+#   3. Ensure GITHUB_TOKEN has PR creation permissions
+#
+# See: https://github.com/bradygaster/squad/issues/357
+
+name: Squad Upstream Sync
+
+on:
+  schedule:
+    # Run every 6 hours (configurable)
+    - cron: '0 */6 * * *'
+  workflow_dispatch:
+    inputs:
+      force_sync:
+        description: 'Force sync even if no changes detected'
+        required: false
+        default: 'false'
+        type: boolean
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  upstream-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install Squad CLI
+        run: npm install -g @bradygaster/squad-cli
+
+      - name: Sync upstream sources
+        id: sync
+        run: |
+          squad upstream sync 2>&1 | tee sync-output.txt
+          echo "output<<EOF" >> $GITHUB_OUTPUT
+          cat sync-output.txt >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet .squad/; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+            echo "No upstream changes detected"
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            echo "Upstream changes detected!"
+            git diff --stat .squad/
+          fi
+
+      - name: Create sync branch and PR
+        if: steps.changes.outputs.has_changes == 'true' || github.event.inputs.force_sync == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="squad/upstream-sync/$(date +%Y%m%d-%H%M%S)"
+          git checkout -b "$BRANCH"
+          git config user.name "squad-bot"
+          git config user.email "squad-bot@users.noreply.github.com"
+          git add .squad/
+          git commit -m "chore: sync upstream Squad sources
+
+          Automated upstream sync by Squad CLI.
+          ${{ steps.sync.outputs.output }}"
+          git push origin "$BRANCH"
+
+          gh pr create \
+            --title "chore: sync upstream Squad sources" \
+            --body "## Upstream Sync
+
+          This PR was automatically created by the Squad upstream sync workflow.
+
+          ### Changes
+          ${{ steps.sync.outputs.output }}
+
+          ---
+          *Automated by [Squad CLI](https://github.com/bradygaster/squad)*" \
+            --base main \
+            --head "$BRANCH" \
+            --label "squad:upstream-sync"
diff --git a/test/upstream-sync.test.ts b/test/upstream-sync.test.ts
new file mode 100644
index 000000000..9597ecab8
--- /dev/null
+++ b/test/upstream-sync.test.ts
@@ -0,0 +1,525 @@
+/**
+ * Tests for bidirectional upstream sync + auto-propagation (#357).
+ *
+ * Covers:
+ *   Phase 1 — watcher: polling, change detection, hash diffing, config parsing
+ *   Phase 2 — proposer: file collection, scope filtering, proposal packaging
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import {
+  hashFile,
+  collectFileHashes,
+  diffHashes,
+  resolveUpstreamSquadPath,
+  createWatchState,
+  checkUpstreamForChanges,
+  runWatchCycle,
+  parseSyncConfig,
+} from '../packages/squad-sdk/src/upstream/watcher.js';
+
+import {
+  collectProposalFiles,
+  buildProposalSummary,
+  packageProposal,
+  parseProposeConfig,
+} from '../packages/squad-sdk/src/upstream/proposer.js';
+
+import {
+  DEFAULT_SYNC_CONFIG,
+  DEFAULT_PROPOSE_CONFIG,
+} from '../packages/squad-sdk/src/upstream/sync-types.js';
+
+import type { UpstreamSource } from '../packages/squad-sdk/src/upstream/types.js';
+
+function tmp(prefix: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function clean(dir: string): void {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ok */ }
+}
+
+// ─── Phase 1: Watcher / Change Detection ───────────────────────────
+
+describe('upstream watcher — hash utilities', () => {
+  let tempDir: string;
+
+  beforeAll(() => {
+    tempDir = tmp('squad-hash-');
+    fs.writeFileSync(path.join(tempDir, 'a.txt'), 'hello');
+    fs.writeFileSync(path.join(tempDir, 'b.txt'), 'world');
+    fs.mkdirSync(path.join(tempDir, 'sub'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'sub', 'c.txt'), 'nested');
+  });
+
+  afterAll(() => clean(tempDir));
+
+  it('hashFile returns deterministic 12-char hash', () => {
+    const h1 = hashFile(path.join(tempDir, 'a.txt'));
+    const h2 = hashFile(path.join(tempDir, 'a.txt'));
+    expect(h1).toBe(h2);
+    expect(h1).toHaveLength(12);
+  });
+
+  it('different content produces different hash', () => {
+    const h1 = hashFile(path.join(tempDir, 'a.txt'));
+    const h2 = hashFile(path.join(tempDir, 'b.txt'));
+    expect(h1).not.toBe(h2);
+  });
+
+  it('collectFileHashes walks directory recursively', () => {
+    const hashes = collectFileHashes(tempDir);
+    expect(hashes.size).toBe(3);
+    expect(hashes.has('a.txt')).toBe(true);
+    expect(hashes.has('b.txt')).toBe(true);
+    expect(hashes.has('sub/c.txt')).toBe(true);
+  });
+
+  it('collectFileHashes returns empty map for non-existent dir', () => {
+    const hashes = collectFileHashes('/nonexistent/path');
+    expect(hashes.size).toBe(0);
+  });
+
+  it('collectFileHashes skips _upstream_repos directories', () => {
+    const dir = tmp('squad-skip-');
+    try {
+      fs.writeFileSync(path.join(dir, 'top.txt'), 'top');
+      fs.mkdirSync(path.join(dir, '_upstream_repos', 'repo'), { recursive: true });
+      fs.writeFileSync(path.join(dir, '_upstream_repos', 'repo', 'hidden.txt'), 'hidden');
+
+      const hashes = collectFileHashes(dir);
+      expect(hashes.size).toBe(1);
+      expect(hashes.has('top.txt')).toBe(true);
+    } finally {
+      clean(dir);
+    }
+  });
+});
+
+describe('upstream watcher — diffHashes', () => {
+  it('detects added files', () => {
+    const prev = new Map([['a.txt', 'aaa']]);
+    const curr = new Map([['a.txt', 'aaa'], ['b.txt', 'bbb']]);
+    expect(diffHashes(prev, curr)).toEqual(['b.txt']);
+  });
+
+  it('detects modified files', () => {
+    const prev = new Map([['a.txt', 'aaa']]);
+    const curr = new Map([['a.txt', 'bbb']]);
+    expect(diffHashes(prev, curr)).toEqual(['a.txt']);
+  });
+
+  it('detects removed files', () => {
+    const prev = new Map([['a.txt', 'aaa'], ['b.txt', 'bbb']]);
+    const curr = new Map([['a.txt', 'aaa']]);
+    expect(diffHashes(prev, curr)).toEqual(['b.txt']);
+  });
+
+  it('returns empty array for identical hashes', () => {
+    const prev = new Map([['a.txt', 'aaa']]);
+    const curr = new Map([['a.txt', 'aaa']]);
+    expect(diffHashes(prev, curr)).toEqual([]);
+  });
+
+  it('detects multiple changes sorted', () => {
+    const prev = new Map([['b.txt', 'old'], ['c.txt', 'old']]);
+    const curr = new Map([['a.txt', 'new'], ['b.txt', 'new']]);
+    const diff = diffHashes(prev, curr);
+    expect(diff).toContain('a.txt'); // added
+    expect(diff).toContain('b.txt'); // modified
+    expect(diff).toContain('c.txt'); // removed
+    // Should be sorted
+    expect(diff).toEqual([...diff].sort());
+  });
+});
+
+describe('upstream watcher — resolveUpstreamSquadPath', () => {
+  let parentDir: string;
+  let childSquadDir: string;
+
+  beforeAll(() => {
+    parentDir = tmp('squad-resolve-parent-');
+    fs.mkdirSync(path.join(parentDir, '.squad'), { recursive: true });
+    fs.writeFileSync(path.join(parentDir, '.squad', 'decisions.md'), '# Decisions');
+
+    childSquadDir = tmp('squad-resolve-child-');
+    fs.mkdirSync(path.join(childSquadDir, '.squad'), { recursive: true });
+  });
+
+  afterAll(() => {
+    clean(parentDir);
+    clean(childSquadDir);
+  });
+
+  it('resolves local upstream .squad/ path', () => {
+    const upstream: UpstreamSource = {
+      name: 'parent',
+      type: 'local',
+      source: parentDir,
+      added_at: new Date().toISOString(),
+      last_synced: null,
+    };
+    const result = resolveUpstreamSquadPath(upstream, childSquadDir);
+    expect(result).toBe(path.join(parentDir, '.squad'));
+  });
+
+  it('returns null for non-existent local upstream', () => {
+    const upstream: UpstreamSource = {
+      name: 'ghost',
+      type: 'local',
+      source: '/nonexistent/path',
+      added_at: new Date().toISOString(),
+      last_synced: null,
+    };
+    expect(resolveUpstreamSquadPath(upstream, childSquadDir)).toBeNull();
+  });
+
+  it('returns null for git upstream without cached clone', () => {
+    const upstream: UpstreamSource = {
+      name: 'remote',
+      type: 'git',
+      source: 'https://example.com/repo.git',
+      added_at: new Date().toISOString(),
+      last_synced: null,
+    };
+    expect(resolveUpstreamSquadPath(upstream, childSquadDir)).toBeNull();
+  });
+});
+
+describe('upstream watcher — watch cycle', () => {
+  let parentDir: string;
+  let childDir: string;
+
+  beforeAll(() => {
+    parentDir = tmp('squad-watch-parent-');
+    const parentSquad = path.join(parentDir, '.squad');
+    fs.mkdirSync(parentSquad, { recursive: true });
+    fs.writeFileSync(path.join(parentSquad, 'decisions.md'), '# Decisions v1');
+
+    childDir = tmp('squad-watch-child-');
+    const childSquad = path.join(childDir, '.squad');
+    fs.mkdirSync(childSquad, { recursive: true });
+    fs.writeFileSync(path.join(childSquad, 'upstream.json'), JSON.stringify({
+      upstreams: [
+        { name: 'parent', type: 'local', source: parentDir, added_at: new Date().toISOString(), last_synced: null },
+      ],
+    }, null, 2));
+  });
+
+  afterAll(() => {
+    clean(parentDir);
+    clean(childDir);
+  });
+
+  it('first cycle captures snapshot (no changes)', () => {
+    const state = createWatchState();
+    const result = runWatchCycle(path.join(childDir, '.squad'), state);
+    expect(result.detections).toHaveLength(1);
+    // First cycle has no previous snapshot to compare against, so everything is "new"
+    // But after first cycle, state should have the snapshot
+    expect(state.snapshots.has('parent')).toBe(true);
+  });
+
+  it('second cycle with no changes reports no changes', () => {
+    const state = createWatchState();
+    runWatchCycle(path.join(childDir, '.squad'), state);
+    const result = runWatchCycle(path.join(childDir, '.squad'), state);
+    expect(result.hasAnyChanges).toBe(false);
+    expect(result.detections[0].changedFiles).toHaveLength(0);
+  });
+
+  it('detects file modification between cycles', () => {
+    const state = createWatchState();
+    runWatchCycle(path.join(childDir, '.squad'), state);
+
+    // Modify parent content
+    fs.writeFileSync(path.join(parentDir, '.squad', 'decisions.md'), '# Decisions v2');
+
+    const result = runWatchCycle(path.join(childDir, '.squad'), state);
+    expect(result.hasAnyChanges).toBe(true);
+    expect(result.detections[0].changedFiles).toContain('decisions.md');
+  });
+
+  it('detects new file between cycles', () => {
+    const state = createWatchState();
+    runWatchCycle(path.join(childDir, '.squad'), state);
+
+    // Add new file to parent
+    fs.writeFileSync(path.join(parentDir, '.squad', 'routing.md'), '# Routing');
+
+    const result = runWatchCycle(path.join(childDir, '.squad'), state);
+    expect(result.hasAnyChanges).toBe(true);
+    expect(result.detections[0].changedFiles).toContain('routing.md');
+  });
+
+  it('returns empty detections for missing upstream.json', () => {
+    const emptyDir = tmp('squad-watch-empty-');
+    try {
+      fs.mkdirSync(path.join(emptyDir, '.squad'), { recursive: true });
+      const state = createWatchState();
+      const result = runWatchCycle(path.join(emptyDir, '.squad'), state);
+      expect(result.detections).toHaveLength(0);
+      expect(result.hasAnyChanges).toBe(false);
+    } finally {
+      clean(emptyDir);
+    }
+  });
+});
+
+describe('upstream watcher — parseSyncConfig', () => {
+  it('returns defaults when no upstream-config.json exists', () => {
+    const dir = tmp('squad-sync-cfg-');
+    try {
+      const config = parseSyncConfig(dir);
+      expect(config.interval).toBe(DEFAULT_SYNC_CONFIG.interval);
+      expect(config.autoPr).toBe(DEFAULT_SYNC_CONFIG.autoPr);
+      expect(config.branchPrefix).toBe(DEFAULT_SYNC_CONFIG.branchPrefix);
+    } finally {
+      clean(dir);
+    }
+  });
+
+  it('reads custom sync config from upstream-config.json', () => {
+    const dir = tmp('squad-sync-cfg2-');
+    try {
+      fs.writeFileSync(path.join(dir, 'upstream-config.json'), JSON.stringify({
+        sync: { interval: 300, autoPr: true, branchPrefix: 'custom/sync' },
+      }));
+      const config = parseSyncConfig(dir);
+      expect(config.interval).toBe(300);
+      expect(config.autoPr).toBe(true);
+      expect(config.branchPrefix).toBe('custom/sync');
+    } finally {
+      clean(dir);
+    }
+  });
+
+  it('merges partial config with defaults', () => {
+    const dir = tmp('squad-sync-cfg3-');
+    try {
+      fs.writeFileSync(path.join(dir, 'upstream-config.json'), JSON.stringify({
+        sync: { interval: 120 },
+      }));
+      const config = parseSyncConfig(dir);
+      expect(config.interval).toBe(120);
+      expect(config.autoPr).toBe(DEFAULT_SYNC_CONFIG.autoPr);
+      expect(config.branchPrefix).toBe(DEFAULT_SYNC_CONFIG.branchPrefix);
+    } finally {
+      clean(dir);
+    }
+  });
+});
+
+// ─── Phase 2: Proposer ─────────────────────────────────────────────
+
+describe('upstream proposer — collectProposalFiles', () => {
+  let squadDir: string;
+
+  beforeAll(() => {
+    squadDir = tmp('squad-propose-');
+    const sq = squadDir;
+
+    // Skills
+    fs.mkdirSync(path.join(sq, 'skills', 'my-skill'), { recursive: true });
+    fs.writeFileSync(path.join(sq, 'skills', 'my-skill', 'SKILL.md'), '# My Skill');
+    fs.mkdirSync(path.join(sq, 'skills', 'other-skill'), { recursive: true });
+    fs.writeFileSync(path.join(sq, 'skills', 'other-skill', 'SKILL.md'), '# Other');
+
+    // Decisions
+    fs.writeFileSync(path.join(sq, 'decisions.md'), '# Decisions');
+
+    // Governance
+    fs.writeFileSync(path.join(sq, 'routing.md'), '# Routing');
+    fs.mkdirSync(path.join(sq, 'casting'), { recursive: true });
+    fs.writeFileSync(path.join(sq, 'casting', 'policy.json'), '{}');
+  });
+
+  afterAll(() => clean(squadDir));
+
+  it('collects skills when skills=true', () => {
+    const files = collectProposalFiles(squadDir, { skills: true, decisions: false, governance: false });
+    expect(files).toHaveLength(2);
+    expect(files.map(f => f.path)).toContain('skills/my-skill/SKILL.md');
+    expect(files.map(f => f.path)).toContain('skills/other-skill/SKILL.md');
+  });
+
+  it('collects decisions when decisions=true', () => {
+    const files = collectProposalFiles(squadDir, { skills: false, decisions: true, governance: false });
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe('decisions.md');
+    expect(files[0].content).toBe('# Decisions');
+  });
+
+  it('collects governance when governance=true', () => {
+    const files = collectProposalFiles(squadDir, { skills: false, decisions: false, governance: true });
+    expect(files).toHaveLength(2);
+    expect(files.map(f => f.path)).toContain('routing.md');
+    expect(files.map(f => f.path)).toContain('casting/policy.json');
+  });
+
+  it('collects all when all flags true', () => {
+    const files = collectProposalFiles(squadDir, { skills: true, decisions: true, governance: true });
+    expect(files).toHaveLength(5); // 2 skills + 1 decisions + 2 governance
+  });
+
+  it('returns empty array when all flags false', () => {
+    const files = collectProposalFiles(squadDir, { skills: false, decisions: false, governance: false });
+    expect(files).toHaveLength(0);
+  });
+});
+
+describe('upstream proposer — buildProposalSummary', () => {
+  it('summarizes skills', () => {
+    const files = [{ path: 'skills/a/SKILL.md', content: '' }];
+    expect(buildProposalSummary(files)).toBe('Proposing: 1 skill');
+  });
+
+  it('pluralizes multiple skills', () => {
+    const files = [
+      { path: 'skills/a/SKILL.md', content: '' },
+      { path: 'skills/b/SKILL.md', content: '' },
+    ];
+    expect(buildProposalSummary(files)).toContain('2 skills');
+  });
+
+  it('summarizes decisions', () => {
+    const files = [{ path: 'decisions.md', content: '' }];
+    expect(buildProposalSummary(files)).toBe('Proposing: decisions');
+  });
+
+  it('summarizes governance', () => {
+    const files = [{ path: 'routing.md', content: '' }];
+    expect(buildProposalSummary(files)).toContain('governance');
+  });
+
+  it('summarizes mixed content', () => {
+    const files = [
+      { path: 'skills/a/SKILL.md', content: '' },
+      { path: 'decisions.md', content: '' },
+      { path: 'routing.md', content: '' },
+    ];
+    const summary = buildProposalSummary(files);
+    expect(summary).toContain('1 skill');
+    expect(summary).toContain('decisions');
+    expect(summary).toContain('governance');
+  });
+
+  it('returns "No files" message for empty array', () => {
+    expect(buildProposalSummary([])).toBe('No files to propose');
+  });
+});
+
+describe('upstream proposer — packageProposal', () => {
+  let squadDir: string;
+  let parentDir: string;
+
+  beforeAll(() => {
+    parentDir = tmp('squad-pkg-parent-');
+    fs.mkdirSync(path.join(parentDir, '.squad'), { recursive: true });
+
+    squadDir = tmp('squad-pkg-child-');
+    const sq = squadDir;
+
+    // Child content
+    fs.mkdirSync(path.join(sq, 'skills', 'child-skill'), { recursive: true });
+    fs.writeFileSync(path.join(sq, 'skills', 'child-skill', 'SKILL.md'), '# Child Skill');
+    fs.writeFileSync(path.join(sq, 'decisions.md'), '# Child Decisions');
+
+    // Upstream config pointing to parent
+    fs.writeFileSync(path.join(sq, 'upstream.json'), JSON.stringify({
+      upstreams: [
+        { name: 'parent', type: 'local', source: parentDir, added_at: new Date().toISOString(), last_synced: null },
+      ],
+    }, null, 2));
+  });
+
+  afterAll(() => {
+    clean(squadDir);
+    clean(parentDir);
+  });
+
+  it('packages proposal for known upstream', () => {
+    const pkg = packageProposal(squadDir, 'parent', { skills: true, decisions: true, governance: false });
+    expect(pkg).not.toBeNull();
+    expect(pkg!.upstreamName).toBe('parent');
+    expect(pkg!.files.length).toBeGreaterThan(0);
+    expect(pkg!.branchName).toContain(DEFAULT_PROPOSE_CONFIG.branchPrefix);
+    expect(pkg!.summary).toContain('skill');
+  });
+
+  it('returns null for unknown upstream', () => {
+    expect(packageProposal(squadDir, 'nonexistent', { skills: true, decisions: true, governance: false })).toBeNull();
+  });
+
+  it('returns null when no files match scope', () => {
+    expect(packageProposal(squadDir, 'parent', { skills: false, decisions: false, governance: false })).toBeNull();
+  });
+
+  it('respects scope flags', () => {
+    const skillsOnly = packageProposal(squadDir, 'parent', { skills: true, decisions: false, governance: false });
+    expect(skillsOnly).not.toBeNull();
+    expect(skillsOnly!.files.every(f => f.path.startsWith('skills/'))).toBe(true);
+
+    const decisionsOnly = packageProposal(squadDir, 'parent', { skills: false, decisions: true, governance: false });
+    expect(decisionsOnly).not.toBeNull();
+    expect(decisionsOnly!.files.every(f => f.path === 'decisions.md')).toBe(true);
+  });
+});
+
+describe('upstream proposer — parseProposeConfig', () => {
+  it('returns defaults when no config file', () => {
+    const dir = tmp('squad-pcfg-');
+    try {
+      const config = parseProposeConfig(dir);
+      expect(config.scope.skills).toBe(true);
+      expect(config.scope.decisions).toBe(true);
+      expect(config.scope.governance).toBe(false);
+      expect(config.targetBranch).toBe('main');
+    } finally {
+      clean(dir);
+    }
+  });
+
+  it('reads custom propose config', () => {
+    const dir = tmp('squad-pcfg2-');
+    try {
+      fs.writeFileSync(path.join(dir, 'upstream-config.json'), JSON.stringify({
+        propose: {
+          scope: { skills: false, decisions: true, governance: true },
+          targetBranch: 'develop',
+          branchPrefix: 'custom/propose',
+        },
+      }));
+      const config = parseProposeConfig(dir);
+      expect(config.scope.skills).toBe(false);
+      expect(config.scope.governance).toBe(true);
+      expect(config.targetBranch).toBe('develop');
+      expect(config.branchPrefix).toBe('custom/propose');
+    } finally {
+      clean(dir);
+    }
+  });
+});
+
+// ─── Defaults validation ────────────────────────────────────────────
+
+describe('sync-types defaults', () => {
+  it('DEFAULT_SYNC_CONFIG has expected values', () => {
+    expect(DEFAULT_SYNC_CONFIG.interval).toBe(600);
+    expect(DEFAULT_SYNC_CONFIG.autoPr).toBe(false);
+    expect(DEFAULT_SYNC_CONFIG.branchPrefix).toBe('squad/upstream-sync');
+  });
+
+  it('DEFAULT_PROPOSE_CONFIG has expected values', () => {
+    expect(DEFAULT_PROPOSE_CONFIG.scope.skills).toBe(true);
+    expect(DEFAULT_PROPOSE_CONFIG.scope.decisions).toBe(true);
+    expect(DEFAULT_PROPOSE_CONFIG.scope.governance).toBe(false);
+    expect(DEFAULT_PROPOSE_CONFIG.targetBranch).toBe('main');
+    expect(DEFAULT_PROPOSE_CONFIG.branchPrefix).toBe('squad/child-propose');
+  });
+});