Linotype v0.5

v0.5 adds a portable learning layer (inbox, signals, snapshots) and optional, disabled-by-default GitHub automation templates. It is designed to be adopted incrementally with minimal disruption to existing galley/slug workflows.

This doc covers:

• What changed from v0.4
• Migration steps (safe defaults)
• Optional tidy-ups for older galleys
• A conservative migration helper (dry-run first)

What changed from v0.4

1) Learning layer (portable across apps)

New structure:

• docs/learning/inbox/ raw reflections dropped by humans/systems
• docs/learning/signals/ normalised signals (daily and weekly)
• docs/learning/proposals/ clustered suggestions (advisory)
• docs/learning/snapshots/ compiled context for ChatGPT/agents
• docs/learning/_templates/ templates for the above

File naming convention: YYYY-MM-DD__app__area__type__slug.md

2) New CLI helpers

Added:

• cli/linotype signal add "..." to append to today’s signals file
• cli/linotype signal normalise to pull bullet-like lines out of inbox into signals
• cli/linotype bundle snapshot to generate a daily planning snapshot

These are intentionally lightweight and do not change the galley lifecycle.

3) GitHub automation templates (opt-in)

Workflow templates can live in .github-disabled/workflows/ so nothing runs unless a user renames .github-disabled to .github.

Migration from v0.4 to v0.5

This migration is designed to be safe: it should not rewrite or relocate your work by default.

Step 0: Upgrade Linotype files

Upgrade Linotype by applying the v0.5 patch (scripts, docs, templates). Ensure:

• docs/learning/ exists
• cli/linotype.sh includes signal and bundle snapshot
• .github-disabled/ exists if adopting disabled-by-default workflows

Step 1: Create learning folders (if missing)

Confirm these folders exist (empty is fine):

• docs/learning/inbox/
• docs/learning/signals/
• docs/learning/proposals/
• docs/learning/snapshots/

Step 2: Don’t move existing galleys unless you need to

v0.4 galleys live across stages: docs/work/planning|queue|doing|review|done/<galley>/

In v0.5, keep this structure intact unless you have a strong reason to tidy. The learning layer works with the existing layout.

Step 3: Bootstrap your first signals

Create your first daily signals file by adding 5–15 signals:

cli/linotype signal add "..." --app linotype --area core --type workflow

You can also drop raw notes into: docs/learning/inbox/YYYY-MM-DD__<app>__<area>__reflection__<slug>.md

Then run: cli/linotype signal normalise --app <app> --area <area>

Step 4: Generate a planning snapshot

Generate a daily snapshot you can paste into ChatGPT/agents:

cli/linotype bundle snapshot --app <app> --area <area>

Writes: docs/learning/snapshots/YYYY-MM-DD__<app>__<area>__snapshot__daily.md

Step 5: Optional weekly reconcile

Once per week, create: docs/learning/signals/YYYY-WW__<app>__<area>__reconcile.md

Track:

• carried forward (still open)
• closed with evidence (commit/slug pointer)
• failed attempts
• deferred
• noise

Optional tidy-ups for older galleys (best-effort)

These are optional and should be done only if they reduce confusion.

A) Ensure each galley has review sections

If a galley is missing headings, add:

• Learnings
• Reflection
• Surprises
• Follow-ups

This improves aggregation and bundling.

B) Add “Closes: S-###” lines where appropriate

When a slug addresses a signal, add: Closes: S-0XX (evidence: <pointer>)

Migration helper (conservative)

For existing repos, use the helper script:

• Dry-run (default): ./cli/migrate-v04-to-v05.sh --dry-run
• Apply: ./cli/migrate-v04-to-v05.sh --apply
• Apply + disable workflows: ./cli/migrate-v04-to-v05.sh --apply --disable-workflows

The helper:

• creates docs/learning/** folders
• optionally disables workflows by moving .github/workflows/* to .github-disabled/workflows/*
• scans galleys and creates missing stubs (never overwrites)
• seeds an inbox reflection from recent done galley reviews
• writes a report to docs/learning/migration/