Docs/simplify fellow weekly reports

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,26 +2,21 @@
 
 ## Branch
 
-- [ ] This branch was created from the latest `master`.
+- [ ] My branch follows `fellows/<github-username>/month-XX-week-YY-<topic>`.
+- [ ] My branch was created from and targets the matching `weeks/month-XX-week-YY` branch.
 - [ ] This work is scoped to one feature, research task, design task, documentation task, experiment, or fix.
 
 ## Human Learning
 
 - [ ] I can explain what changed without relying only on AI output.
-- [ ] I added or updated a weekly report.
-- [ ] I added a human learning log if this work involved learning.
-- [ ] I added a paper note if a paper or technical source shaped the work.
-
-## Design And Research
-
-- [ ] I added a design outcome if the work changed architecture, flow, data model, interface, or evaluation approach.
-- [ ] I linked the relevant paper, article, official documentation, or technical source.
-- [ ] I explained the design decision and alternatives considered.
+- [ ] I filled in my named block in the existing weekly report.
+- [ ] I included at least 20 words describing what I did.
+- [ ] I included my topic and public-output link.
 
 ## Verification
 
 - [ ] I ran the relevant tests, script, benchmark, or manual check.
-- [ ] I recorded evidence in the weekly report, benchmark results, screenshots, or notes.
+- [ ] I recorded verification in benchmark results, screenshots, tests, command output, or notes.
 - [ ] I ran `scripts/verify-contribution.ps1`.
 
 ## AI Use

.github/workflows/repository-safety-check.yml

@@ -1,31 +1,91 @@
-name: Repository safety checks
+name: Fellow contribution checks
 
 on:
-  pull_request:
-    branches:
-      - master
+  # Check work while it is still on a fellow's branch.
   push:
     branches:
-      - master
+      - "fellows/**"
+
+  # A fellow branch must merge into its matching weekly branch.
+  pull_request:
+    branches:
+      - "weeks/**"
+    types: [opened, synchronize, reopened, ready_for_review, edited]
 
 permissions:
   contents: read
 
+concurrency:
+  group: fellow-check-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  repo-safety-check:
-    name: repo-safety-check
+  fellow-contribution-check:
+    # Ignore PRs into weeks/** when the source is not a fellow branch.
+    if: github.event_name == 'push' || startsWith(github.head_ref, 'fellows/')
+    name: fellow-contribution-check
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
+          fetch-depth: 0
           persist-credentials: false
 
-      - name: Check README exists
-        run: test -f README.md
+      - name: Validate fellow branch name
+        shell: bash
+        env:
+          BRANCH_NAME: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+        run: |
+          pattern='^fellows/[a-z0-9]+(-[a-z0-9]+)*/month-(0[1-9]|1[0-2])-week-0[1-4]-[a-z0-9]+(-[a-z0-9]+)*$'
+          if [[ ! "$BRANCH_NAME" =~ $pattern ]]; then
+            echo "Invalid fellow branch: $BRANCH_NAME"
+            echo "Use: fellows/<github-username>/month-XX-week-YY-<topic>"
+            exit 1
+          fi
+
+      - name: Validate weekly pull request target
+        if: github.event_name == 'pull_request'
+        shell: bash
+        env:
+          HEAD_BRANCH: ${{ github.head_ref }}
+          BASE_BRANCH: ${{ github.base_ref }}
+        run: |
+          fellow_week=$(echo "$HEAD_BRANCH" | sed -E 's#^fellows/[^/]+/(month-[0-9]{2}-week-[0-9]{2})-.*$#\1#')
+          expected_base="weeks/$fellow_week"
+
+          if [[ "$BASE_BRANCH" != "$expected_base" ]]; then
+            echo "This fellow branch must target: $expected_base"
+            echo "Current pull request target: $BASE_BRANCH"
+            exit 1
+          fi
+
+      - name: Require the matching weekly report
+        if: github.event_name == 'pull_request'
+        shell: bash
+        env:
+          HEAD_BRANCH: ${{ github.head_ref }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          month=$(echo "$HEAD_BRANCH" | sed -E 's#^fellows/[^/]+/month-([0-9]{2})-week-[0-9]{2}-.*$#\1#')
+          week=$(echo "$HEAD_BRANCH" | sed -E 's#^fellows/[^/]+/month-[0-9]{2}-week-([0-9]{2})-.*$#\1#')
+          report_pattern="^reports/month-${month}/week-${week}.*\.md$"
+
+          merge_base=$(git merge-base "$BASE_SHA" "$HEAD_SHA")
+          if ! git diff --name-only "$merge_base" "$HEAD_SHA" | grep -Eq "$report_pattern"; then
+            echo "Update the shared report for Month $month, Week $week."
+            echo "Expected a changed file matching: reports/month-${month}/week-${week}*.md"
+            exit 1
+          fi
+
+      - name: Verify report structure and 20-word minimum
+        shell: pwsh
+        run: ./scripts/verify-contribution.ps1
 
       - name: Check for unresolved merge conflict markers
+        shell: bash
         run: |
           if grep -R -n -E '^(<<<<<<<|=======|>>>>>>>)' . --exclude-dir=.git; then
             echo "Unresolved merge conflict marker found."

CONTRIBUTING.md

@@ -6,9 +6,15 @@ This project is a fellowship-style learning project. The goal is not for AI to d
 
 `master` is the evolving stable project branch. Do not work directly on `master`.
 
-Every meaningful contribution should happen on a branch created from `master`.
+Each week has an integration branch created from `master`. Fellows create their individual branches from that weekly branch:
 
-New fellows who are starting at Week 1 should branch from `baseline/week-01-starter` instead of the current `master`.
+```text
+fellows/<github-username>/month-XX-week-YY-<topic>
+        -> weeks/month-XX-week-YY
+        -> master
+```
+
+For a new fellowship starting at Week 1, create `weeks/month-01-week-01` from `baseline/week-01-starter`.
 
 The tag `v0.1-week-01-baseline` marks the immutable Week 1 starter snapshot.
 
@@ -22,25 +28,36 @@ The tag `v0.1-week-01-baseline` marks the immutable Week 1 starter snapshot.
 | Experiment | `experiment/month-XX-topic` | `experiment/month-08-network-exchange` |
 | Documentation | `docs/topic` | `docs/fellowship-guide` |
 | Fix | `fix/topic` | `fix/readme-links` |
-| Fellow Work | `fellows/<name>/week-XX` | `fellows/ada/week-01` |
+| Fellow Work | `fellows/<github-username>/month-XX-week-YY-<topic>` | `fellows/ada/month-03-week-02-sync-test` |
+| Weekly Integration | `weeks/month-XX-week-YY` | `weeks/month-03-week-02` |
 
-## New Fellow Start
+## Create A Fellow Branch
 
 ```bash
-git checkout baseline/week-01-starter
-git checkout -b fellows/<name>/week-01
+git fetch origin
+git switch weeks/month-03-week-02
+git pull origin weeks/month-03-week-02
+git switch -c fellows/<github-username>/month-03-week-02-<topic>
 ```
 
-## Required Learning Evidence
+Example:
+
+```bash
+git switch -c fellows/ada/month-03-week-02-sync-test
+```
 
-Every weekly branch should include:
+Push the fellow branch and open its pull request against `weeks/month-03-week-02`, not `master`. The GitHub Action checks the fellow branch name, matching weekly target, weekly report update, repository structure, and unresolved conflict markers.
 
-- A weekly report in `reports/month-XX/`.
-- A human learning log in `research/learning-logs/` when the work involved learning.
-- A paper note in `research/paper-notes/` when a paper or technical source influenced the work.
-- A design outcome in `design/outcomes/` when a design, architecture, flow, or data model changed.
-- A feature brief in `features/active/` or `features/completed/` when a feature was planned or finished.
-- Evidence of verification in the weekly report, benchmark output, screenshots, tests, or command output.
+## Required Weekly Documentation
+
+The shared weekly report is the only documentation file every fellow must modify. Each fellow adds:
+
+- A short named block in the existing `reports/month-XX/week-YY.md` report.
+- The topic they worked on.
+- At least 20 words explaining what they did.
+- A link to the fellow's public post in the weekly report.
+
+Each fellow edits only their numbered block, such as `Fellow 1: Ada`. Separate learning logs, paper notes, design outcomes, and feature briefs are not required unless the assigned task specifically asks for them. Code, tests, or other project files may still change when needed to complete the work. See `reports/README.md` for the report format.
 
 ## Human Work And AI Assistance
 
@@ -73,10 +90,12 @@ Then fill the pull request checklist in `.github/PULL_REQUEST_TEMPLATE.md`.
 
 ## Merge Standard
 
-A branch should only merge back to `master` when another person can understand:
+A fellow branch should only merge into its matching `weeks/month-XX-week-YY` branch when another person can understand:
 
 - What was learned.
 - What was designed.
 - What was built.
 - What was verified.
 - What still needs work.
+
+After all accepted fellow contributions are combined and reviewed, open one pull request from the weekly branch into `master`.

README.md

@@ -55,8 +55,8 @@ The verification script checks the baseline structure, but human review is still
 | `PROJECT_BRIEF.md` | Why the project exists and what is in scope |
 | `docs/roadmap.md` | The progressive 12-month roadmap |
 | `docs/` | Architecture notes, benchmarking notes, compute targets, and decisions |
-| `reports/` | Weekly learning and build journal |
-| `reports/month-01` to `reports/month-12` | Monthly report folders with four weekly reports each |
+| `reports/` | One shared report per week with a short named block for each fellow |
+| `reports/month-01` to `reports/month-12` | Monthly folders containing four weekly reports |
 | `research/` | Paper notes, reading lists, and learning evidence |
 | `research/learning-logs/` | Human learning reflections and AI-use notes |
 | `design/` | Design outcomes, sketches, flows, and decision artifacts |

docs/architecture.md

@@ -7,7 +7,9 @@ This repository is organized around a research-to-design-to-build loop.
 ```text
 master branch
   |
-new branch
+weeks/month-XX-week-YY
+  |
+fellows/<username>/month-XX-week-YY-topic
   |
 Research input
   |
@@ -19,10 +21,12 @@ Code / benchmark / docs change
   |
 Weekly report
   |
-merge back to master
+merge into weekly branch
+  |
+weekly branch merges into master
 ```
 
-`master` should stay clean. It is the stable baseline used to start each feature, research, design, documentation, experiment, or fix branch.
+`master` should stay clean. Weekly integration branches start from it, individual fellow branches start from the matching weekly branch, and only the reviewed weekly branch returns to `master`.
 
 ## Repository Architecture
 

docs/baseline-start-guide.md

@@ -7,6 +7,7 @@ This project keeps `master` as the evolving stable project, while `baseline/week
 | Name | Type | Purpose |
 |---|---|---|
 | `master` | Branch | Evolving stable project branch |
+| `weeks/month-XX-week-YY` | Branch | Combines reviewed fellow contributions for one week |
 | `baseline/week-01-starter` | Branch | Permanent Week 1 starter baseline |
 | `v0.1-week-01-baseline` | Tag / release | Immutable snapshot of the Week 1 starter baseline |
 
@@ -31,37 +32,38 @@ git clone https://github.com/Flow-Research/local-first-AI.git
 cd local-first-AI
 ```
 
-Start from the Week 1 baseline:
+The coordinator creates the Week 1 integration branch from the baseline:
 
 ```bash
 git checkout baseline/week-01-starter
-git checkout -b fellows/<name>/week-01
+git checkout -b weeks/month-01-week-01
+git push -u origin weeks/month-01-week-01
 ```
 
-Example:
+Each fellow then branches from the weekly integration branch:
 
 ```bash
-git checkout baseline/week-01-starter
-git checkout -b fellows/ada/week-01
+git checkout weeks/month-01-week-01
+git checkout -b fellows/<github-username>/month-01-week-01-setup
 ```
 
 ## Alternative: Start From The Tag
 
-Use the tag when you want the exact immutable snapshot:
+Use the tag when the coordinator needs to create the weekly branch from the exact immutable snapshot:
 
 ```bash
 git checkout v0.1-week-01-baseline
-git checkout -b fellows/<name>/week-01
+git checkout -b weeks/month-01-week-01
 ```
 
 ## Ongoing Fellow Workflow
 
-After Week 1, a fellow can continue their own sequence:
+For each later week, create a new fellow branch from the matching weekly branch:
 
 ```text
-fellows/<name>/week-01
-fellows/<name>/week-02
-fellows/<name>/week-03
+fellows/<github-username>/month-01-week-01-setup
+fellows/<github-username>/month-01-week-02-local-storage
+fellows/<github-username>/month-01-week-03-local-ai-flow
 ```
 
 Shared project work still uses the normal branch types:
@@ -79,6 +81,7 @@ fix/topic
 Do not commit new work directly to:
 
 - `master`
+- `weeks/month-XX-week-YY`
 - `baseline/week-01-starter`
 
 `baseline/week-01-starter` should only change if the fellowship deliberately decides to publish a new starter baseline.
@@ -88,7 +91,9 @@ Do not commit new work directly to:
 In GitHub branch protection settings:
 
 - Protect `master`.
+- Protect `weeks/**`.
 - Protect `baseline/week-01-starter`.
 - Require pull requests before merging into `master`.
+- Require pull requests and the `fellow-contribution-check` before merging fellow work into a weekly branch.
 - Prevent force pushes.
 - Prevent deletion of protected branches.

docs/branching-and-features.md

@@ -4,7 +4,13 @@
 
 `master` is the evolving stable project branch. Do not do active work directly on `master`.
 
-Every project task should branch from `master`, stay small, and return to `master` only when the work is documented, reviewed, and safe to build on.
+Create one integration branch for the active week from `master`. Each fellow branches from that weekly branch, stays small, and merges back into the same weekly branch after review.
+
+```text
+fellows/<github-username>/month-XX-week-YY-<topic>
+        -> weeks/month-XX-week-YY
+        -> master
+```
 
 The clean Week 1 starter baseline lives at `baseline/week-01-starter` and is also marked by the `v0.1-week-01-baseline` tag.
 
@@ -19,7 +25,8 @@ New fellows who start from Week 1 should branch from `baseline/week-01-starter`,
 | `design/` | Architecture, flows, diagrams, and prototypes | `design/month-03-demo-storyboard` |
 | `experiment/` | Temporary technical trials | `experiment/month-08-network-exchange` |
 | `fix/` | Small corrections | `fix/readme-links` |
-| `fellows/` | Individual fellow learning branches | `fellows/ada/week-01` |
+| `fellows/` | Individual fellow learning branches | `fellows/ada/month-03-week-02-sync-test` |
+| `weeks/` | Reviewed weekly integration branches | `weeks/month-03-week-02` |
 | `docs/` | Documentation-only work | `docs/month-01-report-cleanup` |
 
 ## Feature Folder Flow
@@ -34,24 +41,23 @@ Use `features/` to keep feature thinking separate from final code.
 
 ## Recommended Feature Lifecycle
 
-1. Branch from `master`.
-2. Create a feature brief in `features/active/`.
-3. Add research notes in `research/paper-notes/` if the work depends on a paper or technical source.
-4. Add design outcomes in `design/outcomes/`.
-5. Implement the smallest useful code change in `src/`.
-6. Add tests, benchmark evidence, screenshots, or command output.
-7. Update the weekly report.
-8. Merge back to `master` only when the branch is coherent and documented.
+1. Branch from the matching `weeks/month-XX-week-YY` branch.
+2. Implement the assigned work in the relevant project files.
+3. Add or run the relevant verification.
+4. Fill in your named block in the existing weekly report using at least 20 words for what you did.
+5. Open a pull request into the matching weekly branch.
+6. Merge the weekly branch into `master` after all fellow contributions are reviewed together.
+
+The weekly report is the only required documentation file. Research notes, design outcomes, learning logs, and feature briefs are optional unless the assigned task specifically requires one.
 
 ## Merge Checklist
 
 | Check | Required? |
 |---|---|
-| Branch started from latest `master` | Yes |
+| Fellow branch started from the matching weekly branch | Yes |
+| Pull request targets the matching weekly branch | Yes |
 | Weekly report updated | Yes |
-| Human learning log added when learning happened | Yes |
-| Design outcome added when UI, flow, architecture, or data model changed | Yes |
-| Research note added when a paper influenced the work | Yes |
+| Fellow block contains name, topic, at least 20 words, and public-output link | Yes |
 | Tests or manual verification recorded | Yes |
 | README changed only when the public project overview changed | Yes |